Hostovana platobna stranka (HPP)
Prijimajte platby pomocou hostovanej platobnej stranky Cost+
Hostovana platobna stranka (HPP) je platobny formular Cost+ kompatibilny s PCI DSS. Umoznuje vam prijimat platby bez manipulacie s citlivymi udajmi kariet na vasich vlastnych serveroch. Vytvorite objednavku cez API, presmerujete zakaznika na hostovanu stranku a po platbe sa vrati na vasu stranku.
Ako to funguje
- Vas server vytvori objednavku volanim POST /v1/orders/.
- API vrati URL adresu smerujucu na hostovanu platobnu stranku.
- Presmerujete zakaznika na platobnu stranku.
- Zakaznik dokonci platbu na hostovanej stranke Cost+.
- Zakaznik je presmerovany spat na vasu
return_url(alebofailure_urlpri neuspesnych platbach). - Cost+ posle webhook notifikaciu na vasu
webhook_urlso stavom objednavky.
Hostovana platobna stranka je plne kompatibilna s PCI DSS. Nikdy nemusite manipulovat so surovymi cislami kariet ani s citlivymi platobnymi udajmi na vasich serveroch.
Vytvorenie objednavky
Existuju dva pristupy k pouzitiu HPP:
Pristup 1: Zobrazenie vsetkych platobnych metod (najjednoduchsie)
Vytvorte objednavku bez zadania transactions. Odpoved obsahuje order_url -- zakaznik je presmerovany tam a vidi vsetky platobne metody aktivovane pre vas ucet:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}{
"id": "43114fde-da30-4115-8004-b7f808f9b25c",
"status": "new",
"currency": "EUR",
"amount": 1295,
"order_url": "https://api.costplus.online/pay/43114fde.../select-payment-method/",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}Presmerujte zakaznika na order_url. Na hostovanej stranke sa zobrazia vsetky aktivovane platobne metody.
Pristup 2: Predvolene platobne metody
Vytvorte objednavku s polom transactions na kontrolu toho, ktore platobne metody sa zobrazia a v akom poradi. Kazda transakcia obsahuje payment_method a odpoved vrati payment_url v objekte transakcie:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{ "payment_method": "credit-card" }
]
}{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "new",
"currency": "EUR",
"amount": 1295,
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "new",
"payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
}
]
}Presmerujte zakaznika na payment_url z transakcie.
Ak uvediete len jednu polozku v poli transactions, zakaznik je presmerovany priamo na tu platobnu metodu bez zobrazenia obrazovky vyberu. Pole flags obsahuje "is-test" pri pouziti sandbox API kluca.
Polia poziadavky
| Pole | Povinne | Popis |
|---|---|---|
currency | Ano | ISO 4217 kod meny (napr. EUR, GBP, SEK) |
amount | áno | Suma v menovej jednotke ISO 4217. Napríklad 12,95 EUR je reprezentované ako 1295 |
merchant_order_id | Nie | Vase vlastne referencne ID pre objednavku |
return_url | Nie | URL na presmerovanie zakaznika po platbe (predvolene pre vsetky stavy) |
failure_url | Nie | URL na presmerovanie zakaznika pri stavoch cancelled, expired alebo error (pozrite Navratove URL nizsie) |
locale | Nie | Jazyk platobnej stranky. Podporovane: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK |
description | Nie | Popis objednavky zobrazeny zakaznikovi |
payment_methods | Nie | Filtrujte na jeden spôsob platby (napr. ["credit-card"]). Vynechaním zobrazíte všetky povolené metódy. Pre viacero špecifických metód použite namiesto toho pole transactions |
webhook_url | Nie | URL na prijimanie notifikacii o zmene stavu |
expiration_period | Nie | ISO 8601 trvanie pre exspiraciu objednavky. Predvolene je PT30M (30 minut) |
Pole amount je vždy celé číslo v menovej jednotke ISO 4217. Pre EUR znamená 1295 12,95 EUR; meny s nulou a tromi desatinnými miestami používajú svoj vlastný exponent ISO 4217. Odovzdanie desatinnej hodnoty, napríklad 1295.00 alebo 12.95, bude mať za následok chybu alebo nesprávny poplatok.
Viacero platobnych metod
Existujú dva spôsoby, ako ovládať, ktoré spôsoby platby sa zobrazia na hosťovanej stránke:
Možnosť A – payment_methods (jeden filter). Odovzdajte jednoprvkové pole na obmedzenie objednávky na jeden spôsob platby. Ak chcete zobraziť všetky metódy povolené pre váš účet, pole úplne vynechajte.
Možnosť B – pole transactions (odporúčané pre viacero spôsobov). Pridajte jednu položku na každý spôsob platby. Každá transakcia dostane svoj vlastný payment_url a metódy sa zobrazia v poradí polí na hosťovanej stránke:
"transactions": [
{ "payment_method": "credit-card" },
{ "payment_method": "apple-pay" }
]Pole payment_methods na objednávkach akceptuje najviac jednu hodnotu. Ak chcete ponúknuť viacero špecifických metód, vždy použite pole transactions. Ak potrebujete opakovane použiteľný odkaz s viacerými spôsobmi platby, zvážte namiesto toho platobné odkazy, ktoré podporujú skutočné pole payment_methods.
Navratove URL
Po platbe je zakaznik presmerovany na zaklade stavu objednavky a toho, ktore URL ste zadali:
-
Ked su nastavene obe
return_urlafailure_url:cancelled,expiredaleboerror-> zakaznik je presmerovany nafailure_url- Vsetky ostatne stavy -> zakaznik je presmerovany na
return_url
-
Ked je nastavena len
return_url:- Vsetky stavy -> zakaznik je presmerovany na
return_url
- Vsetky stavy -> zakaznik je presmerovany na
Pouzite failure_url na zobrazenie stranky s moznostou opakovaneho pokusu alebo podporou pre neuspesne platby, zatial co return_url zobrazuje potvrdenie objednavky. Ak potrebujete len jednu cielovu adresu, samotna return_url je dostatocna.
Spravanie tlacidla Zrusit
Hostovana platobna stranka obsahuje tlacidlo Zrusit. Ked na neho zakaznik klikne, je presmerovany na failure_url (ak je zadana) alebo return_url. Stav objednavky sa zmeni na cancelled. Vzdy overujte stav objednavky cez API alebo webhooky namiesto spoliemania sa len na presmerovanie.
Suvisiace endpointy
- Vytvorenie objednavky -- vytvorenie platobnej objednavky a ziskanie
payment_url - Ziskanie objednavky -- kontrola stavu objednavky po platbe