Cost+Docs

Hosted stranica za plaćanje (HPP)

Prihvaćajte plaćanja koristeći Cost+ hosted stranicu za plaćanje

Hosted stranica za plaćanje (HPP) je Cost+ obrazac za plaćanje usklađen s PCI DSS standardom. Omogućuje vam prihvaćanje plaćanja bez rukovanja osjetljivim podacima kartica na vašim poslužiteljima. Stvorite narudžbu putem API-ja, preusmjerite kupca na hosted stranicu, a oni se vraćaju na vašu stranicu nakon plaćanja.

Kako funkcionira

  1. Vaš poslužitelj stvara narudžbu pozivom POST /v1/orders/.
  2. API vraća URL koji upućuje na hosted stranicu za plaćanje.
  3. Preusmjerite kupca na stranicu za plaćanje.
  4. Kupac dovršava plaćanje na Cost+ hosted stranici.
  5. Kupac se preusmjerava natrag na vaš return_url (ili failure_url za neuspjela plaćanja).
  6. Cost+ šalje webhook obavijest na vaš webhook_url sa statusom narudžbe.

Hosted stranica za plaćanje potpuno je usklađena s PCI DSS standardom. Nikada ne morate rukovati sirovim brojevima kartica ili osjetljivim podacima o plaćanju na vašim poslužiteljima.

Stvaranje narudžbe

Postoje dva pristupa korištenju HPP-a:

Pristup 1: Prikaži sve načine plaćanja (najjednostavnije)

Stvorite narudžbu bez navođenja transactions. Odgovor uključuje order_url — kupac se preusmjerava tamo i vidi sve načine plaćanja omogućene za vaš račun:

Request
{
  "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"
}
Response
{
  "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"
}

Preusmjerite kupca na order_url. Na hosted stranici prikazani su svi omogućeni načini plaćanja.

Pristup 2: Unaprijed odabrani načini plaćanja

Stvorite narudžbu s transactions poljem za kontrolu koji se načini plaćanja prikazuju i kojim redoslijedom. Svaka transakcija uključuje payment_method, a odgovor vraća payment_url unutar objekta transakcije:

Request
{
  "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" }
  ]
}
Response
{
  "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.../"
    }
  ]
}

Preusmjerite kupca na payment_url iz transakcije.

Ako navedete samo jedan unos u transactions polju, kupac se vodi izravno na taj način plaćanja bez prikaza ekrana za odabir. Polje flags sadrži "is-test" kada koristite sandbox API ključ.

Polja zahtjeva

PoljeObaveznoOpis
currencyDaISO 4217 kod valute (npr. EUR, GBP, SEK)
amountDaIznos u manjoj jedinici ISO 4217 valute. Na primjer, 12,95 EUR predstavljeno je kao 1295
merchant_order_idNeVaš vlastiti referentni ID za narudžbu
return_urlNeURL za preusmjeravanje kupca nakon plaćanja (zadano za sve statuse)
failure_urlNeURL za preusmjeravanje kupca pri statusu cancelled, expired ili error (pogledajte Povratni URL-ovi dolje)
localeNeJezik stranice za plaćanje. Podržani: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK
descriptionNeOpis narudžbe, prikazan kupcu
payment_methodsNeFiltrirajte prema jednom načinu plaćanja (npr. ["credit-card"]). Izostavi za prikaz svih omogućenih metoda. Za više specifičnih metoda umjesto toga upotrijebite niz transactions
webhook_urlNeURL za primanje obavijesti o promjeni statusa
expiration_periodNeISO 8601 trajanje za istek narudžbe. Zadano je PT30M (30 minuta)

Polje amount uvijek je cijeli broj u manjoj jedinici ISO 4217 valute. Za EUR, 1295 znači 12,95 EUR; valute s nula i tri decimale koriste vlastiti eksponent ISO 4217. Prosljeđivanje decimalne vrijednosti kao što je 1295.00 ili 12.95 rezultirat će pogreškom ili netočnim terećenjem.

Višestruki načini plaćanja

Postoje dva načina za kontroliranje načina plaćanja koji se pojavljuju na hostiranoj stranici:

Opcija A — payment_methods (jedan filtar). Proslijedite niz od jednog elementa da ograničite narudžbu na jedan način plaćanja. U potpunosti izostavite polje kako biste prikazali sve metode omogućene za vaš račun.

Opcija B — polje transactions (preporučeno za više metoda). Dodajte jedan unos po načinu plaćanja. Svaka transakcija dobiva vlastiti payment_url, a metode se pojavljuju u nizu na hostiranoj stranici:

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

Polje payment_methods na nalozima prihvaća najviše jednu vrijednost. Da biste ponudili više specifičnih metoda, uvijek koristite niz transactions. Ako vam je potrebna veza za višekratnu upotrebu s više načina plaćanja, umjesto toga razmislite o Vezama za plaćanje, koje podržavaju pravi payment_methods niz.

Povratni URL-ovi

Nakon plaćanja, kupac se preusmjerava ovisno o statusu narudžbe i URL-ovima koje ste naveli:

  • Kada su postavljeni i return_url i failure_url:

    • cancelled, expired ili error → kupac se preusmjerava na failure_url
    • Svi ostali statusi → kupac se preusmjerava na return_url
  • Kada je postavljen samo return_url:

    • Svi statusi → kupac se preusmjerava na return_url

Koristite failure_url za prikaz stranice za ponovni pokušaj ili podršku za neuspjela plaćanja, dok return_url prikazuje potvrdu narudžbe. Ako vam treba samo jedno odredište, dovoljan je samo return_url.

Ponašanje gumba za odustajanje

Hosted stranica za plaćanje uključuje gumb za odustajanje. Kada kupac klikne na njega, preusmjerava se na failure_url (ako je naveden) ili return_url. Status narudžbe prijeći će u cancelled. Uvijek provjerite status narudžbe putem API-ja ili webhookova umjesto oslanjanja samo na preusmjeravanje.

Povezane krajnje točke

On this page