Tárolt fizetési oldal (HPP)

A Tárolt fizetési oldal (HPP) a Cost+ PCI DSS megfelelőségű fizetési űrlapja. Lehetővé teszi fizetések elfogadását anélkül, hogy érzékeny kártyaadatokat kellene kezelnie a saját szerverein. Létrehoz egy rendelést az API-n keresztül, átirányítja az ügyfelet a tárolt oldalra, és a fizetés után visszatér az Ön oldalára.

Hogyan működik

Az Ön szervere rendelést hoz létre a POST /v1/orders/ végpont meghívásával.
Az API egy URL-t ad vissza, amely a tárolt fizetési oldalra mutat.
Átirányítja az ügyfelet a fizetési oldalra.
Az ügyfél befejezi a fizetést a Cost+ tárolt oldalán.
Az ügyfelet visszairányítjuk az Ön return_url címére (vagy failure_url címére sikertelen fizetés esetén).
A Cost+ webhook értesítést küld az Ön webhook_url címére a rendelés állapotával.

A tárolt fizetési oldal teljes mértékben PCI DSS megfelelőségű. Soha nem kell nyers kártyaszámokat vagy érzékeny fizetési adatokat kezelnie a szerverein.

Rendelés létrehozása

A HPP használatának két megközelítése van:

1. megközelítés: Összes fizetési mód megjelenítése (legegyszerűbb)

Hozzon létre rendelést transactions megadása nélkül. A válasz tartalmaz egy order_url-t — az ügyfelet ide irányítjuk, és látja az Ön fiókjára engedélyezett összes fizetési módot:

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"
}

Irányítsa át az ügyfelet az order_url-re. A tárolt oldalon az összes engedélyezett fizetési mód megjelenik.

2. megközelítés: Fizetési módok előválasztása

Hozzon létre rendelést a transactions tömb megadásával, hogy szabályozza, mely fizetési módok jelenjenek meg és milyen sorrendben. Minden tranzakció tartalmaz egy payment_method értéket, és a válasz a tranzakció objektumban egy payment_url-t ad vissza:

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

Irányítsa át az ügyfelet a tranzakcióból kapott payment_url-re.

Ha csak egyetlen bejegyzést ad meg a transactions tömbben, az ügyfél közvetlenül az adott fizetési módra kerül, választási képernyő nélkül. A flags tömb tartalmazza az "is-test" értéket sandbox API-kulcs használatakor.

Kérés mezők

Mező	Kötelező	Leírás
`currency`	Igen	ISO 4217 pénznemkód (pl. `EUR`, `GBP`, `SEK`)
`amount`	Igen	Az összeg a pénznem ISO 4217 kisebb egységében. Például a 12.95 EUR `1295`
`merchant_order_id`	Nem	Az Ön saját referenciaazonosítója a rendeléshez
`return_url`	Nem	URL, ahová az ügyfelet fizetés után irányítjuk (alapértelmezett minden állapothoz)
`failure_url`	Nem	URL, ahová az ügyfelet `cancelled`, `expired` vagy `error` állapot esetén irányítjuk (lásd a Visszairányítási URL-ek részt alább)
`locale`	Nem	A fizetési oldal nyelve. Támogatott: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Nem	A rendelés leírása, amely megjelenik az ügyfélnek
`payment_methods`	Nem	Szűrés egyetlen fizetési módra (pl. `["credit-card"]`). Hagyja el az összes engedélyezett metódus megjelenítését. Több konkrét módszerhez használja helyette a `transactions` tömböt
`webhook_url`	Nem	URL az állapotváltozási értesítések fogadásához
`expiration_period`	Nem	ISO 8601 időtartam a rendelés lejáratához. Az alapértelmezett `PT30M` (30 perc)

A amount mező mindig egy egész szám a pénznem ISO 4217 kisebb egységében. A EUR esetében a 1295 jelentése 12,95 EUR; A nulla és három tizedes jegyű pénznemek saját ISO 4217 kitevőjüket használják. Egy tizedes érték (például 1295.00 vagy 12.95) átadása hibát vagy helytelen terhelést eredményez.

Több fizetési mód

Kétféleképpen szabályozhatja, hogy mely fizetési módok jelenjenek meg a tárolt oldalon:

A lehetőség – payment_methods (egyetlen szűrő). Adjon át egy egyelemű tömböt, hogy a rendelést egy fizetési módra korlátozza. Hagyja ki teljesen a mezőt, hogy megjelenjen a fiókjában engedélyezett összes módszer.

B lehetőség – transactions tömb (több módszerhez ajánlott). Fizetési módonként adjon hozzá egy bejegyzést. Minden tranzakció saját payment_url kódot kap, és a metódusok tömb sorrendben jelennek meg a tárolt oldalon:

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

A rendeléseknél a payment_methods mező legfeljebb egy értéket fogad el. Több specifikus módszer felajánlásához mindig a transactions tömböt használja. Ha több fizetési módot tartalmazó újrafelhasználható linkre van szüksége, fontolja meg inkább a Payment Links lehetőséget, amelyek támogatják a valódi payment_methods tömböt.

Visszairányítási URL-ek

A fizetés után az ügyfelet a rendelés állapota és a megadott URL-ek alapján irányítjuk át:

Ha mind a return_url, mind a failure_url be van állítva:
- cancelled, expired vagy error → az ügyfelet a failure_url címre irányítjuk
- Minden más állapot → az ügyfelet a return_url címre irányítjuk
Ha csak a return_url van beállítva:
- Minden állapot → az ügyfelet a return_url címre irányítjuk

Használja a failure_url-t egy újrapróbálkozási vagy ügyfélszolgálati oldal megjelenítéséhez sikertelen fizetések esetén, míg a return_url a rendelés visszaigazolását jeleníti meg. Ha csak egy célcímre van szüksége, a return_url önmagában is elegendő.

Mégse gomb viselkedése

A tárolt fizetési oldal tartalmaz egy mégse gombot. Amikor az ügyfél rákattint, a failure_url címre (ha meg van adva) vagy a return_url címre irányítjuk. A rendelés állapota cancelled lesz. Mindig ellenőrizze a rendelés állapotát az API-n vagy webhookon keresztül, ahelyett hogy kizárólag az átirányításra hagyatkozna.

Kapcsolódó végpontok

Rendelés létrehozása — fizetési rendelés létrehozása és a payment_url fogadása
Rendelés lekérdezése — a rendelés állapotának ellenőrzése fizetés után

Tárolt fizetési oldal (HPP)

On this page