OTP specifikus paraméterek

Az OTP Bank esetében a hagyományos SZÉP Kártyán kívül úgynevezett cafeteria kártya is elérhető. A cafeteria, a SZÉP Kártyához képest más típusú alszámlákat (zsebeket) tartalmaz, ugyanakkor az alszámla azonosítók átadása a SZÉP Kártyás fizetéssel azonos módon történik.

2023. január 9-től a SZÉP Kártyához tartozó alszámlák (zsebek) összevonásra kerültek a szálláshely alszámla alatt. A határozat szerint minden SZÉP Kártyás fizetés a szálláshely alszámlából kerül levonásra. Ennek értelmében a fizetési szolgáltatók jelenleg minden SZÉP Kártyás terhelést a szálláshely alszámlára irányítanak át. Ennek ellenére a SZÉP Kártyás tranzakciók indításában nem történt technikai változás, így ezek indításához továbbra is meg kell adni egy alszámla-azonosítót.

Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

• kötelező paraméterek

• opcionális paraméterek

API kérés paraméterek

Kötelező paraméterek

Paraméter	Típus	Érték	Leírás
StoreName	string	A BIG FISH Payment Gateway szerződésben kerül meghatározásra.	Rendszerünkben tárolt egyedi bolt azonosító.
ProviderName *	string	OTP RawOTPSZEP	A tranzakcióhoz kiválasztott fizetési szolgáltató. * RawOTPSZEP használatánál a szolgáltató elvárja a vásárló email címének átadását az általános vásárlói adatok objektumban (ebben az esetben az Info paraméter átadása kötelező).
OtpCardPocketId *	string	Cafeteria kártya esetén: 01 (étel utalvány) 02 (meleg étkezési utalvány) 03 (iskolakezdési utalvány) 04 (kultúra utalvány) 05 (ajándék utalvány) 06 (sport utalvány) SZÉP Kártya esetén: 07 (vendéglátás alszámla) 08 (szabadidő alszámla) 09 (szálláshely alszámla)	A fizetéshez használt alszámla (zseb) azonosítója. * A paramétert csak OTP ProviderName érték használata esetén kell átadni. RawOTPSZEP ProviderName érték használatánál nem szükséges megadni OtpCardPocketId értéket. RawOTPSZEP ProviderName érték használatával csak SZÉP Kártya terhelhető.
ResponseUrl	string (255 karakter)	szabadon választható	Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.
NotificationUrl	string (255 karakter)	szabadon választható	Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (URL értesítés).
Amount	number	szabadon választható (egész szám)	Bruttó végösszeg amit a vásárló kifizet.

Opcionális paraméterek

Paraméter	Típus	Érték	Leírás
Currency	string (3 karakter)	HUF	A fizetés devizaneme. (Átadása nem befolyásolja a tranzakció devizanemét, mely SZÉP Kártyánál minden esetben HUF.)
OrderId	string (255 karakter)	szabadon választható (kivéve e-mail címek, illetve személyes adatok)	A megrendelés azonosítója a kereskedő áruházában. (Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)
UserId	string (255 karakter)	szabadon választható (kivéve e-mail címek, illetve személyes adatok)	A vásárló azonosítója a kereskedő áruházában. (Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)
Language	string (2 karakter)	HU (alapért.) EN DE	A fizetési felület nyelve.
Info *	string	egyedi értékek	A vásárlás és a vásárló adatai (PSD2/SCA). * RawOTPSZEP használatánál a szolgáltató elvárja a vásárló email címének átadását az általános vásárlói adatok objektumban (ebben az esetben az Info paraméter átadása kötelező).
ModuleName	string (255 karakter)	egyedi értékek	A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.
ModuleVersion	string (8 karakter)	verziószám	A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.

Mintakód

Tranzakció inicializálása Init kérés használatával:

curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"OTP",
        "ResponseUrl":"https://demo.paymentgateway.hu/response.php",
        "NotificationUrl":"https://www.notification.url/bfpg",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"BF-TEST-ORDER",
        "UserId":"BF-TEST-USER",
        "OtpCardPocketId":"08"
    }'

API válasz paraméterek

Az Init kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

Paraméter	Típus	Érték	Leírás
TransactionId	string	Sikeres inicializálás: 32 karakter hosszú md5 hash Sikertelen inicializálás: null	A tranzakció azonosítója a BIG FISH Payment Gateway rendszerében.
ResultCode	string	Sikeres inicializálás: SUCCESSFUL Sikertelen inicializálás: InactiveStore InactiveProvider MissingParameter MissingRemoteAddress UnauthorizedAccess UnauthorizedRemoteAddress UnknownParameter UnknownProvider UnknownProviderForStore UnknownStore WrongApikey WrongParameter WrongProviderSettings Illetve további szolgáltató specifikus eredménykódok.	Jelzi a tranzakció inicializálás eredményét. Sikertelen inicializálás esetén jelzi a hiba okát. A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.
ResultMessage	string	leírás	Az egyes ResultCode értékek szöveges magyarázata.
ResponseId	integer	egyedi értékek	A válaszüzenet egyedi azonosítója a BIG FISH Payment Gateway rendszerében.

Mintakód

Sikeres inicializálásra adott válasz:

{
    "TransactionId": "3df9aa96b538f2ee2916d8441e5302ca",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047703"
}