Cost+Docs

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

  1. Vaš strežnik ustvari naročilo s klicem POST /v1/orders/.
  2. API vrne URL, ki kaže na gostovano plačilno stran.
  3. Stranko preusmerite na plačilno stran.
  4. Stranka dokonča plačilo na gostovani strani Cost+.
  5. Stranka je preusmerjena nazaj na vaš return_url (ali failure_url za neuspešna plačila).
  6. Cost+ pošlje webhook obvestilo na vaš webhook_url s 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:

Zahteva
{
  "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"
}
Odgovor
{
  "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:

Zahteva
{
  "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" }
  ]
}
Odgovor
{
  "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

PoljeObveznoOpis
currencyDaValutna koda ISO 4217 (npr. EUR, GBP, SEK)
amountjaZnesek v manjši enoti ISO 4217 valute. Na primer, 12,95 EUR je predstavljen kot 1295
merchant_order_idNeVaša lastna referenčna oznaka za naročilo
return_urlNeURL za preusmeritev stranke po plačilu (privzeto za vse statuse)
failure_urlNeURL za preusmeritev stranke ob statusu cancelled, expired ali error (glejte Povratni URL-ji spodaj)
localeNeJezik plačilne strani. Podprti: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK
descriptionNeOpis naročila, prikazan stranki
payment_methodsštFiltrirajte 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_urlNeURL za prejemanje obvestil o spremembi statusa
expiration_periodNeTrajanje 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_url kot failure_url:

    • cancelled, expired ali error → stranka je preusmerjena na failure_url
    • Vsi ostali statusi → stranka je preusmerjena na return_url
  • Ko je nastavljen samo return_url:

    • Vsi statusi → stranka je preusmerjena na return_url

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

On this page