Gostovana plačilna stran (HPP)
Sprejemajte plačila z uporabo gostovane plačilne strani Cost+
Gostovana plačilna stran (HPP) je plačilni obrazec Cost+, skladen s PCI DSS. Omogoča vam sprejemanje plačil brez obdelave občutljivih kartičnih podatkov na vaših strežnikih. Ustvarite naročilo prek API-ja, preusmerite stranko na gostovano stran, stranka pa se po plačilu vrne na vaše spletno mesto.
Kako deluje
- Vaš strežnik ustvari naročilo s klicem POST /v1/orders/.
- API vrne URL, ki kaže na gostovano plačilno stran.
- Stranko preusmerite na plačilno stran.
- Stranka dokonča plačilo na gostovani strani Cost+.
- Stranka je preusmerjena nazaj na vaš
return_url(alifailure_urlza neuspešna plačila). - Cost+ pošlje webhook obvestilo na vaš
webhook_urls statusom naročila.
Gostovana plačilna stran je v celoti skladna s PCI DSS. Nikoli vam ni treba obdelovati surovih številk kartic ali občutljivih plačilnih podatkov na vaših strežnikih.
Ustvarjanje naročila
Obstajata dva pristopa za uporabo HPP:
Pristop 1: Prikažite vse plačilne metode (najpreprostejše)
Ustvarite naročilo brez navedbe transactions. Odgovor vključuje order_url — stranka je preusmerjena tja in vidi vse plačilne metode, omogočene za vaš račun:
{
"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"
}Preusmerite stranko na order_url. Na gostovani strani so prikazane vse omogočene plačilne metode.
Pristop 2: Predizberite plačilne metode
Ustvarite naročilo z nizom transactions za nadzor nad tem, katere plačilne metode se prikažejo in v kakšnem vrstnem redu. Vsaka transakcija vključuje payment_method, odgovor pa vrne payment_url znotraj objekta transakcije:
{
"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.../"
}
]
}Preusmerite stranko na payment_url iz transakcije.
Če navedete samo en vnos v nizu transactions, je stranka preusmerjena neposredno na to plačilno metodo brez prikaza izbirnega zaslona. Niz flags vsebuje "is-test" pri uporabi API ključa peskovnika.
Polja zahteve
| Polje | Obvezno | Opis |
|---|---|---|
currency | Da | Valutna koda ISO 4217 (npr. EUR, GBP, SEK) |
amount | ja | Znesek v manjši enoti ISO 4217 valute. Na primer, 12,95 EUR je predstavljen kot 1295 |
merchant_order_id | Ne | Vaša lastna referenčna oznaka za naročilo |
return_url | Ne | URL za preusmeritev stranke po plačilu (privzeto za vse statuse) |
failure_url | Ne | URL za preusmeritev stranke ob statusu cancelled, expired ali error (glejte Povratni URL-ji spodaj) |
locale | Ne | Jezik plačilne strani. Podprti: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK |
description | Ne | Opis naročila, prikazan stranki |
payment_methods | št | Filtrirajte na eno samo plačilno sredstvo (npr. ["credit-card"]). Izpustite, če želite prikazati vse omogočene metode. Za več specifičnih metod namesto tega uporabite matriko transactions |
webhook_url | Ne | URL za prejemanje obvestil o spremembi statusa |
expiration_period | Ne | Trajanje ISO 8601 za potek naročila. Privzeto je PT30M (30 minut) |
Polje amount je vedno celo število v pomožni enoti ISO 4217 valute. Za EUR 1295 pomeni 12,95 EUR; ničelne in tridecimalne valute uporabljajo lasten eksponent ISO 4217. Posredovanje decimalne vrednosti, kot je 1295.00 ali 12.95, bo povzročilo napako ali nepravilno bremenitev.
Več plačilnih metod
Obstajata dva načina za nadzor, katera plačilna sredstva so prikazana na gostujoči strani:
Možnost A — payment_methods (enoten filter). Posredujte matriko z enim elementom, da omejite naročilo na eno plačilno sredstvo. V celoti izpustite polje, da prikažete vse metode, omogočene za vaš račun.
Možnost B — niz transactions (priporočeno za več načinov). Dodajte en vnos na način plačila. Vsaka transakcija dobi svoj lasten payment_url, metode pa so prikazane v matričnem vrstnem redu na gostujoči strani:
"transactions": [
{ "payment_method": "credit-card" },
{ "payment_method": "apple-pay" }
]Polje payment_methods na naročilih sprejme največ eno vrednost. Če želite ponuditi več specifičnih metod, vedno uporabite matriko transactions. Če potrebujete povezavo za večkratno uporabo z več načini plačila, razmislite o povezavah do plačil, ki podpirajo pravo matriko payment_methods.
Povratni URL-ji
Po plačilu je stranka preusmerjena glede na status naročila in navedene URL-je:
-
Ko sta nastavljena tako
return_urlkotfailure_url:cancelled,expiredalierror→ stranka je preusmerjena nafailure_url- Vsi ostali statusi → stranka je preusmerjena na
return_url
-
Ko je nastavljen samo
return_url:- Vsi statusi → stranka je preusmerjena na
return_url
- Vsi statusi → stranka je preusmerjena na
Uporabite failure_url za prikaz strani za ponovni poskus ali podporo pri neuspešnih plačilih, medtem ko return_url prikaže potrditev naročila. Če potrebujete samo eno destinacijo, zadošča samo return_url.
Obnašanje gumba za preklic
Gostovana plačilna stran vključuje gumb za preklic. Ko stranka klikne nanj, je preusmerjena na failure_url (če je naveden) ali return_url. Status naročila se spremeni v cancelled. Vedno preverite status naročila prek API-ja ali webhook-ov, namesto da se zanašate samo na preusmeritev.
Povezane končne točke
- Ustvari naročilo — ustvarite plačilno naročilo in prejmite
payment_url - Pridobi naročilo — preverite status naročila po plačilu