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
- Vaš poslužitelj stvara narudžbu pozivom POST /v1/orders/.
- API vraća URL koji upućuje na hosted stranicu za plaćanje.
- Preusmjerite kupca na stranicu za plaćanje.
- Kupac dovršava plaćanje na Cost+ hosted stranici.
- Kupac se preusmjerava natrag na vaš
return_url(ilifailure_urlza neuspjela plaćanja). - Cost+ šalje webhook obavijest na vaš
webhook_urlsa 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:
{
"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"
}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:
{
"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.../"
}
]
}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
| Polje | Obavezno | Opis |
|---|---|---|
currency | Da | ISO 4217 kod valute (npr. EUR, GBP, SEK) |
amount | Da | Iznos u manjoj jedinici ISO 4217 valute. Na primjer, 12,95 EUR predstavljeno je kao 1295 |
merchant_order_id | Ne | Vaš vlastiti referentni ID za narudžbu |
return_url | Ne | URL za preusmjeravanje kupca nakon plaćanja (zadano za sve statuse) |
failure_url | Ne | URL za preusmjeravanje kupca pri statusu cancelled, expired ili error (pogledajte Povratni URL-ovi dolje) |
locale | Ne | Jezik stranice za plaćanje. Podržani: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK |
description | Ne | Opis narudžbe, prikazan kupcu |
payment_methods | Ne | Filtrirajte 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_url | Ne | URL za primanje obavijesti o promjeni statusa |
expiration_period | Ne | ISO 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_urlifailure_url:cancelled,expiredilierror→ kupac se preusmjerava nafailure_url- Svi ostali statusi → kupac se preusmjerava na
return_url
-
Kada je postavljen samo
return_url:- Svi statusi → kupac se preusmjerava na
return_url
- Svi statusi → kupac se preusmjerava na
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
- Stvori narudžbu — stvorite narudžbu plaćanja i dobijte
payment_url - Dohvati narudžbu — provjerite status narudžbe nakon plaćanja