Predajná transakcia je základná platobná operácia, ktorá zabezpečuje prevod stanovenej sumy z bankového účtu držiteľa karty na účet obchodníka.
Pokiaľ ide o priebeh platby, postup je nasledovný:
Prihlásenie a overenie
Pre všetky neverejné koncové body je potrebné overenie pomocou tokenu JWT. Token (s platnosťou 90 dní) získate prostredníctvom koncového bodu /cloud/oauth/token s nasledujúcimi zadanými argumentmi:
- Základné overenie pre koncové body tokenu (meno/heslo) – bude poskytnuté každému používateľovi.
- Používateľské meno obchodníka – rovnaké ako pre GP tom
- Heslo obchodníka – rovnaké ako pre GP tom
- ID terminálu (TID) – ID cieľového terminálu
- Autorizačný koncový bod sa nachádza na:
Tento spôsob overovania je pre všetky terminály rovnaký.
Získanie prístupového tokenu
Príklad požiadavky:
POST {{apiCloudHost}}/cloud/oauth/token
Autorizácia: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Autorizácia a typ obsahu sú pre všetkých zákazníkov vždy rovnaké – použite prosím rovnaké údaje ako v príklade. Do poľa grant_type je potrebné následne vložiť jedinečné údaje klienta).
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Príklad odpovede:
{
"access_token": "eyJh…", // prístupový token používaný v overených požiadavkách na API
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Obnovenie tokenu
Po uplynutí platnosti access_tokenu je k dispozícii refresh_token.
Príklad požiadavky:
POST {{apiHost}}/api/oauth/token
Autorizácia: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ bezpečnostného schématu / Bezpečnostné schéma
HTTP
Schéma autorizácie HTTP / Schéma autorizácie HTTP
na doručiteľa
Vytvorenie úlohy
Oslovte koncový bod POST /v1/tasks/TRANSACTION a na vytvorenie požiadavky použite CreateCloudTaskTransactionApiRequest s nasledujúcimi údajmi:
Premenná
Formát
Popis
Príklad
apiKey
POVINNÉ
POVINNÉ
reťazec
API kľúč nájdete priamo v aplikácii GP tom v sekcii Účet – Cloud API. Slúži na identifikáciu prihlásenia, najmä v Cloud API. Pre každú spoločnosť je API kľúč jedinečný.
333W212J3
čas
POVINNÉ
POVINNÉ
reťazec
Cieľové TID pre danú úlohu. TID = ID terminálu, ktoré je jedinečné pre každé zariadenie. Na všetkých nainštalovaných zariadeniach je možné súčasne používať len jedno TID.
483590
iniciátor
POVINNÉ
POVINNÉ
reťazec
Popis iniciátora by mal byť jedinečný pre každú inštanciu subsystému, ktorá môže iniciovať úlohu. Príklad: „server XY“ alebo „Pokladňa 1“
Pokladňa 12
názov
POVINNÉ
POVINNÉ
reťazec
Ľahko zrozumiteľný názov úlohy. Mal by obsahovať nejakú identifikáciu úlohy.
Príklad: „Faktúra 37364FD“
Príklad: „Faktúra 37364FD“
Faktúra č. 36744
tlač cez platobnú aplikáciu
boolean
predvolené nastavenie: true
To je pravda, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa musíte uistiť, že je pripojená Bluetooth tlačiareň.
To je pravda, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa musíte uistiť, že je pripojená Bluetooth tlačiareň.
false
suma
POVINNÉ
POVINNÉ
číslo
Suma transakcie nesmie byť nulová a musí obsahovať desatinné miesta. Pri hodnote transakcie 50 EUR zadajte hodnotu „5000“.
40000
tipAmount
číslo
Výška spropitného. Ak chcete uviesť spropitné vo výške 3 EUR, zadajte hodnotu „300“.
0
transakčná operácia
POVINNÉ
POVINNÉ
reťazec
Typ transakcie úlohy. Pri transakcii „Sale“ zadajte hodnotu „SALE“.
VÝPREDAJ
originTransactionId
reťazec
ID transakcie, ktorá sa má zrušiť. Nie je null, ak je režim VOID a zrušenie OLDER_TRANSACTION.
NEPOUŽÍVA SA
originReferenceNum
reťazec
Referenčné číslo, napr. číslo faktúry – zadajte ľubovoľnú hodnotu do 20 znakov, ktorá bude viditeľná v prehľadoch a bude slúžiť na identifikáciu platby na vašej strane.
FD123456
režim zrušenia
reťazec
Režim zrušenia, nie null, ak je typ transakcie VOID
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NEPOUŽÍVA SA
transactionType*
POVINNÉ
POVINNÉ
reťazec
Možné hodnoty: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
KARTA
kód meny
reťazec
3 kódy mien (podľa ISO 4217)
CZK
preferovaný typ potvrdenia
reťazec
Predvolený spôsob zaslania účtenky: [ E-MAIL, TELEFÓN, QR, TLAČ ]
E-MAIL
e-mail
reťazec
E-mail zákazníka
support@gptom.com
telefón
reťazec
Telefónne číslo zákazníka
+420123456789
tipCollect
boolean
default: false
Pokud se nastaví true, tak se nejdříve vyvolá obrazovka zadání spropitného v GP tom.
Pro vyvolání této obrazovky je potřeba mít také aktivované spropitné v aplikaci
Pokud se nastaví true, tak se nejdříve vyvolá obrazovka zadání spropitného v GP tom.
Pro vyvolání této obrazovky je potřeba mít také aktivované spropitné v aplikaci
timeToLive
celé číslo
Limit pre vypršanie platnosti úlohy v cloude. Je možné zadať hodnoty v rozmedzí od 10 do 172 800 sekúnd.
10
Obsah odpovede [CloudTaskDetailApiResponse]:
Možné kódy odpovedí sú:
Odpoveď
Správa
Popis
Ako sa správať
RC200
OK – Úloha bola zaregistrovaná
Úloha bola úspešne vytvorená a bude spracovaná.
Pokračujte ďalším krokom v priebehu transakcie.
RC401
Neidentifikované
Ak sa neuskutočnila autentifikácia s terminálom.
Vykonajte proces overenia (pozri krok vyššie).
RC403
Používateľ nemá oprávnenie zaregistrovať úlohu na danom termináli
Ak sa vaše prihlasovacie údaje API nezhodujú s odoslanou hodnotou TID (napríklad ak je vlastník TID iný).
Skontrolujte, či ste zadali správne TID, a skúste to znova.
RC406
Úloha nie je pre daný terminál prijateľná
K tomu zvyčajne dochádza, keď TID nie je schopný spracovať požiadavku.
Skontrolujte chybovú správu.
RC 502
Push notifikácia nebola odoslaná
Push notifikácia nebola odoslaná z dôvodu zlyhania služby upstream.
Nižšie nájdete premenné použité v odpovedi:
Premenná
Formát
Popis
Príklad
RC200
RC403
RC406
RC502
názov
reťazec
Čitateľný názov priečinka. Použitý z hodnoty požiadavky.
Faktúra č. 36744
ÁNO
NO
NO
NO
ID úlohy
reťazec
Interné ID tašky
dFd3sda
ÁNO
NO
NO
NO
vytvorené
reťazec
Dátum a čas vytvorenia úlohy.
ÁNO
NO
NO
NO
taskClass
reťazec
Trieda užitočného zaťaženiaMožné hodnoty: [TRANSACTION, BATCH, VOID]
TRANSAKCIA
ÁNO
NO
NO
NO
stav
reťazec
Stav úlohy v cloude. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
VYTVORENÉ
ÁNO
NO
NO
NO
iniciátor
reťazec
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
Pokladňa 12
ÁNO
NO
NO
NO
contextId
reťazec
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
ÁNO
NO
NO
NO
užitočné zaťaženie
objekt
Telo kontextovej úlohy – v závislosti od taskClass
{...}
ÁNO
NO
NO
NO
ID výnimky
reťazec
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID pre podporu“, ktoré môže používateľ poskytnúť podpore, aby mohla chybu prešetriť.
FujIk6
NO
ÁNO
ÁNO
ÁNO
typ
reťazec
Typ výnimky.
VALIDATION_EXCEPTION
NO
ÁNO
ÁNO
ÁNO
správa
reťazec
Správa o výnimke.
Heslo je príliš slabé
NO
ÁNO
ÁNO
ÁNO
kontext
reťazec
Kontext výnimky. Ďalšie informácie.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
ÁNO
ÁNO
ÁNO
Kontrola stavu tašky
V ďalšom kroku skontrolujete stav úlohy na koncovom bode GET /v1/tasks/{taskID} pomocou požiadavky, ktorá obsahuje:
Premenná
Formát
Popis
Príklad
ID úlohy
reťazec
ID tašky, ktoré ste dostali v predchádzajúcom kroku.
dFd3sda
Možné kódy vrátenia:
Odpoveď
Správa
Správa
Popis
RC200
OK – Stav tašky k dispozícii
Aktualizácia stavu úlohy bola úspešne spracovaná.
Ak nedostanete konečný stav (pozri nižšie), tento krok zopakujte.
RC403
Pre aktuálny terminál nebola nájdená žiadna úloha v cloude.
Mali by ste skontrolovať svoje taskID a znovu odoslať správnu hodnotu.
Skontrolujte, či ste zadali správne taskID, a skúste to znova.
Premenné v odpovedi:
Premenná
Formát
Popis
Príklad
RC200
RC404
názov
reťazec
Ľahko zrozumiteľný názov úlohy. Použitý z hodnoty požiadavky na vytvorenie úlohy.
Faktúra č. 36744
ÁNO
NO
ID úlohy
reťazec
Interné ID tašky
dFd3sda
ÁNO
NO
vytvorené
reťazec
Dátum a čas vytvorenia úlohy.
ÁNO
NO
taskClass
reťazec
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
ÁNO
NO
stav
reťazec
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
V PRÍPRAVE
ÁNO
NO
iniciátor
reťazec
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
Pokladňa 12
ÁNO
NO
contextID
reťazec
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
ÁNO
NO
užitočné zaťaženie
ÁNO
NO
ID výnimky
reťazec
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID podpory“, ktoré môže používateľ poskytnúť podpore, aby mohla prešetriť prípadný problém.
FujIk6
NO
ÁNO
typ
reťazec
Typ výnimky.
VALIDATION_EXCEPTION
NO
ÁNO
správa
reťazec
Správa o výnimke.
Heslo je príliš slabé
NO
ÁNO
kontext
reťazec
Kontext výnimky – ďalšie informácie.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
ÁNO
Požiadavka na stav úlohy by sa mala opakovať, kým nezískate jeden z konečných kódov odpovede, ktorými sú:
Stav
Popis
Ako sa správať
INIT_ERROR
Inicializácia platobného procesu sa nepodarila. Skontrolujte hlásenú chybu.
Postupujte podľa pokynov k chybe.
DOKONČENÉ
Akonáhle dosiahnete tento stav, vaša úloha je dokončená a výsledok je k dispozícii.
Môžete pokračovať ďalším krokom.
ZRUŠENÉ
Úloha bola zrušená používateľom.
Mali by ste začať novú úlohu, pretože táto úloha bola zrušená používateľom.
CHYBA
Pri spracovaní úlohy došlo k chybe.
Postupujte podľa pokynov k chybe.
Ďalším krokom môžete pokračovať len vtedy, ak je odpoveď v stave COMPLETED.
Získanie informácií o platbe
Teraz vieme, že transakcia bola autorizovaná. Cieľom tohto kroku je získať stav transakcie a jej podrobnosti. Pre novú požiadavku voláte koncový bod GET /v1/transactions/{transactionId}, kde použijete nasledujúce premenné:
Premenná
Formát
Popis
Príklad
contextId
reťazec
ID transakcie, ktoré získate v predchádzajúcich krokoch.
Možné kódy odpovedí sú:
Odpoveď
Správa
Správa
Popis
RC200
OK – podrobnosti transakcie boli poskytnuté
Vaša žiadosť bola úspešne spracovaná.
Transakcia bola dokončená!
RC404
Pre zadané TID nebola nájdená žiadna transakcia.
K tejto situácii dôjde, ak sa pre vaše zariadenie nepodarilo nájsť príslušné transakčné ID.
Skontrolujte identifikačné číslo transakcie.
Odpoveď obsahuje nasledujúce premenné v závislosti od kódu odpovede:
Premenná
Formát
Popis
Príklad
RC 200
RC 404
výsledok
reťazec
Výsledek transakce, možné hodnoty [ ACCEPTED, DECLINED, CANCELLED ] kde:
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
PRIJATÉ
ÁNO
NO
odpoveďová správa
reťazec
Podrobnejší popis výslednej hodnoty.
“Vydavateľ odmietol.”
ÁNO
NO
transanctionId
reťazec
Interné ID úlohy
ÁNO
NO
transakčná operácia
reťazec
Možné hodnoty: "SALE", "VOID", "REFUND"
Operácia / typ transakcie."
Operácia / typ transakcie."
VÝPREDAJ
ÁNO
NO
typ transakcie
reťazec
Možné hodnoty: "CASH", "CARD"
KARTA
ÁNO
NO
merchantID
reťazec
Iba pre transakcie kartou – ID pobočky.
343382001
ÁNO
NO
čas
reťazec
ID transakcie vytvorené terminálom
483591
ÁNO
NO
kód meny
reťazec
Kód meny (ISO 4217)
ÁNO
NO
suma
číslo
Suma transakcie s dvoma desatinnými miestami (400 CZK).
400
ÁNO
NO
tipAmount
číslo
Suma spropitného zadaná na 2 desatinné miesta (30 CZK).
3000
ÁNO
NO
maskedPan
reťazec
Skryté číslo karty.
XXXX XXXX XXXX 1233
ÁNO
NO
vstup údajov z karty
reťazec
Spôsob čítania karty – magnetický prúžok, čip alebo bezkontaktný
BEZKONTAKTNÉ
ÁNO
NO
referenčné číslo
reťazec
Referenčné číslo transakcie prevzaté z hodnoty požiadavky úlohy: originReferenceNum
FD123456
ÁNO
NO
číslo potvrdenia
reťazec
Číslo účtenky
12
ÁNO
NO
číslo šarže
reťazec
Číslo dávky
2
ÁNO
NO
dátum
reťazec
Dátum a čas autorizácie transakcie
09.10.2021 15:34
ÁNO
NO
typ karty
reťazec
Údaje o značke karty prevzaté z údajov na karte
Mastercard CL
ÁNO
NO
dôvod zamietnutia
reťazec
Dôvod zamietnutia transakcie
201
ÁNO
NO
autorizačný kód
reťazec
Číslo vygenerované na strane GP
10293045
ÁNO
NO
číslo sekvencie
reťazec
Číslo vygenerované na strane GP
102304128
ÁNO
NO
pomoc
reťazec
Identifikuje aplikáciu EMV použitú na spracovanie transakcie
40100000000
ÁNO
NO
pinMessage
boolean
Označuje, či bol zadaný PIN
PIN_ENTERED alebo NO_PIN
ÁNO
NO
zrušené
reťazec
V prípade zrušenia transakcie sa tu zobrazí contextID
ÁNO
NO
metóda overovania držiteľa karty
reťazec
Iba pre terminály Nexgo – označuje spôsob overenia transakcie
PIN
ÁNO
NO
ID výnimky
reťazec
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID podpory“, ktoré môže používateľ poskytnúť podpore, aby mohla situáciu prešetriť.
FujIk6
NO
ÁNO
typ
reťazec
Typ výnimky
VALIDATION_EXCEPTION
NO
ÁNO
správa
reťazec
Správa o výnimke
Heslo je príliš slabé
NO
ÁNO
kontext
reťazec
Kontext výnimky – ďalšie informácie.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
ÁNO
dccData
stav (DCC)
reťazec
SK: Uvádza stav DCC. Ak je stav "ACCEPTED", transakcia prebehla cez DCC a musíte vyplniť údaje DCC na účtenke. Ak je stav "NOT_ACCEPTED", v takom prípade môžete údaje DCC ignorovať.
EN: Uvádza stav DCC. Ak je stav "ACCEPTED", transakcia bola vykonaná prostredníctvom DCC a do potvrdenia je potrebné vyplniť údaje DCC. Ak je stav "NOT_ACCEPTED", údaje DCC môžete ignorovať.
EN: Uvádza stav DCC. Ak je stav "ACCEPTED", transakcia bola vykonaná prostredníctvom DCC a do potvrdenia je potrebné vyplniť údaje DCC. Ak je stav "NOT_ACCEPTED", údaje DCC môžete ignorovať.
PRIJATÉ
NEPREJÍMANÉ
NEPREJÍMANÉ
ÁNO
NO
suma (DCC)
reťazec
SK: Suma transakcie v mene DCC – v mene karty zákazníka. Je potrebné ju zobraziť presne tak, ako je uvedená v odpovedi API, vrátane počtu desatinných miest.
EN: Suma transakcie v mene DCC – v mene karty zákazníka. Na potvrdení ju musíte uviesť presne tak, ako ste ju dostali v odpovedi API, vrátane správnych desatinných miest.
EN: Suma transakcie v mene DCC – v mene karty zákazníka. Na potvrdení ju musíte uviesť presne tak, ako ste ju dostali v odpovedi API, vrátane správnych desatinných miest.
2.31
ÁNO
NO
kód meny (DCC)
reťazec
SK: Mena zákazníckej karty.
EN: Mena karty zákazníka.
EN: Mena karty zákazníka.
EUR
ÁNO
NO
výmenný kurz (DCC)
reťazec
SK: Uvádza výmenný kurz. Táto hodnota je v miestnej mene terminálu. Je potrebné ju zobraziť presne tak, ako je uvedená v odpovedi API, vrátane počtu desatinných miest.
EN: Uvádza výmenný kurz. Táto hodnota je vyjadrená v miestnej mene terminálu. Na potvrdení ju musíte uviesť presne tak, ako ste ju dostali v odpovedi API, vrátane správneho počtu desatinných miest.
EN: Uvádza výmenný kurz. Táto hodnota je vyjadrená v miestnej mene terminálu. Na potvrdení ju musíte uviesť presne tak, ako ste ju dostali v odpovedi API, vrátane správneho počtu desatinných miest.
56.35
ÁNO
NO
značkovací jazyk (DCC)
reťazec
SK: Prirážka k konverznému kurzu. Je potrebné ju zobraziť presne tak, ako je uvedená v odpovedi API, vrátane počtu desatinných miest.
EN: Údaj o konverznej sadzbe. Na účtenke ho musíte uviesť presne tak, ako ste ho dostali v odpovedi API, vrátane správnych desatinných miest.
EN: Údaj o konverznej sadzbe. Na účtenke ho musíte uviesť presne tak, ako ste ho dostali v odpovedi API, vrátane správnych desatinných miest.
3.20
ÁNO
NO
regionSchemaIndicator (DCC)
reťazec
SK: Uvádza, či bola zákaznícka karta vydaná v rámci EÚ alebo mimo nej. Ak je hodnota "0" alebo "1", na účtenke sa musí zobraziť text "Markup". Ak je hodnota "2", na účtenke sa musí zobraziť "Markup over ECB rate".
EN: Uvádza, či bola karta zákazníka vydaná v rámci EÚ alebo mimo nej. Ak je hodnota "0" alebo "1", na účtenke sa musí zobraziť text "Prirážka". Ak je hodnota "2", na účtenke sa musí zobraziť text "Prirážka nad kurzom ECB“.
EN: Uvádza, či bola karta zákazníka vydaná v rámci EÚ alebo mimo nej. Ak je hodnota "0" alebo "1", na účtenke sa musí zobraziť text "Prirážka". Ak je hodnota "2", na účtenke sa musí zobraziť text "Prirážka nad kurzom ECB“.
0
1
2
1
2
ÁNO
NO
Pokud budete účtenku generovat nebo tisknout na své straně, doporučujeme zkontrolovat, která pole jsou povinná a musí být vytištěna/zobrazena na účtence. Popis je k dispozici zde.