Predajná transakcia je základná platobná operácia, ktorá umožňuje prevod zadanej sumy z bankového účtu držiteľa karty na účet obchodníka.
Pokiaľ ide o proces platby, postup je nasledovný:
Prihlásenie & autentifikácia
Overenie tokenom JWT sa vyžaduje pre všetky neverejné koncové body. Token (so životnosťou 90 dní) získate prostredníctvom koncového bodu /cloud/oauth/token s nasledujúcimi argumentmi:
- Základná autentifikácia pre koncové body tokenov (meno/heslo) - bude zabezpečená pre každého používateľa.
- 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 adrese:
Tento spôsob autentifikácie je rovnaký pre všetky terminály.
Získanie prístupového tokenu
Príklad žiadosti:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Authorization a Contect-Type je pro všechny zákazníky vždy stejný – použijte prosím stejné údaje jako v příkladu. Do grant_type je potřeba následně vložit unikátní údaje klienta).
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Príklad odpovede:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"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 žiadosti:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ bezpečnostního schématu / Security scheme
HTTP
Schéma autorizace HTTP / HTTP authorization scheme
bearer
Vytvorenie úlohy
Zavolajte na koncový bod POST /v1/úlohy/TRANSACTION a na podanie žiadosti použite CreateCloudTaskTransactionApiRequest s vyplnenými nasledujúcimi informáciami:
Premenná
Formát
Popis: __________
Príklad
apiKey
MANDATORY
MANDATORY
string
API Kľúč nájdete priamo v aplikácii GP tom v časti Konto -Cloud API . Používa sa na rozlíšenie prihlásení najmä v Cloud API . Pre každú spoločnosť je API kľúč jedinečný.
333W212J3
tid
POVINNÝ
POVINNÝ
string
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é naraz použiť iba jeden TID.
483590
initiator
POVINNÝ
POVINNÝ
string
Opis iniciátora by mal byť jedinečný pre každú inštanciu subsystému, ktorá môže iniciovať úlohu. Príklad: "Server XY" alebo "Pokladník 1"
Pokladňa 12
title
POVINNÝ
POVINNÝ
string
Názov úlohy čitateľný ľudským okom. Mal by obsahovať určitú identifikáciu úlohy.
Príklad: Faktúra 37364FD
Príklad: Faktúra 37364FD
Faktúra 36744
printByPaymentApp
Boolean
predvolené: true
Platí, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa musíte uistiť, že je pripojená tlačiareň Bluetooth.
Platí, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa musíte uistiť, že je pripojená tlačiareň Bluetooth.
nepravdivé
amount
POVINNÝ
POVINNÝ
number
Suma transakcie musí byť nenulová a musí obsahovať desatinné miesta. Pri prevodnej hodnote 50 EUR vyplníte hodnotu "5000".
40000
tipAmount
number
Množstvo prepitného. Pre hodnotu prepitného 3 € vyplňte hodnotu "300".
0
transactionOperation
MANDATORY
MANDATORY
string
Typ transakcie úlohy. Pre transakciu "Predaj" vyplňte hodnotu "PREDAJ".
SALE
originTransactionId
string
ID transakcie na zrušenie. Nie je neplatné, ak je režim VOID a zrušenie OLDER_TRANSACTION.
NEPOUŽÍVA SA
originReferenceNum
string
Referenčné číslo, napr. číslo faktúry – pridajte ľubovoľnú hodnotu do 20 znakov, ktorá bude viditeľná v prehľadoch a identifikujte platbu na vašej strane.
FD123456
cancelMode
string
Režim obrátenia, nie nulový, 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Ý
string
Možné hodnoty: [ CASH, CARD, ACCOUNT_PAYMENT ]
KARTA
currencyCode
string
3 znaky meny (podľa ISO 4217)
KČ
preferableReceiptType
string
Vopred zvolený spôsob odoslania potvrdenia: [ E-MAIL, TELEFÓN, QR, TLAČ ]
SMALT
smalt
string
Zákaznícky e-mail
support@gptom.com
Telefón
string
Telefónne číslo zákazníka
+420123456789
TipCollect
Boolean
predvolené: false
Ak je nastavené na hodnotu true, ako prvá sa vyvolá obrazovka na zadávanie prepitného na stránke GP tom.
Ak chcete túto obrazovku vyvolať, musíte mať v aplikácii povolené aj dávanie prepitného.
Ak je nastavené na hodnotu true, ako prvá sa vyvolá obrazovka na zadávanie prepitného na stránke GP tom.
Ak chcete túto obrazovku vyvolať, musíte mať v aplikácii povolené aj dávanie prepitného.
Čas na život
celé číslo
Limit vypršania platnosti pre cloudovú úlohu. Môžete zadať hodnoty od 10 do 172800 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á.
Prejdite na ďalší krok v toku transakcií.
RC401
Neviazané
Ak nedošlo k autenfikácii s terminálom.
Vykonajte proces overenia (pozri krok vyššie).
RC403
Používateľ nie je oprávnený zaregistrovať úlohu na danom termináli
Ak sú vaše prihlasovacie údaje API sa nezhodujú s odoslanou hodnotou TID (napríklad ak je vlastník TID iný).
Skontrolujte, či ste vyplnili správny TID, a skúste to znova.
RC406
úloha nie je prijateľná pre terminál
To sa zvyčajne stáva, keď TID nie je schopný spracovať žiadosť.
Skontrolujte chybové hlásenie.
RC 502
Push notifikácia nie je odoslaná
Push notifikácia nebola odoslaná z dôvodu zlyhania služby na dodávateľskom trhu.
Nižšie nájdete premenné použité v odpovedi:
Premenná
Formát
Popis: __________
Príklad
RC200
RC403
RC406
RC502
title
string
Názov úlohy čitateľný ľudským okom. Použité z hodnoty požiadavky.
Faktúra 36744
YES
NO
NO
NO
taskId
string
Interné id úlohy
dFd3sda
YES
NO
NO
NO
created
string
Dátum a čas vytvorenia úlohy.
YES
NO
NO
NO
taskClass
string
Trieda užitočného zaťaženiaMožné hodnoty: [TRANSACTION, BATCH, VOID]
TRANSAKCIA
YES
NO
NO
NO
status
string
Stav cloudovej úlohy. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREATED
YES
NO
NO
NO
initiator
string
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
Pokladňa 12
YES
NO
NO
NO
contextId
string
ID dotknutej cieľovej entity, ak existuje (transactionId / batchId)
YES
NO
NO
NO
Payload
object
Kontextové telo úlohy – v závislosti od úlohyClass
{...}
YES
NO
NO
NO
exceptionId
string
Pseudo-jedinečné ID výnimky. Môže slúžiť ako "ID podpory", ktoré môže používateľ komunikovať s podporou, aby mohol chybu vyšetriť.
FujIk6
NO
YES
YES
YES
typ
string
Druh výnimky.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
string
Správa o výnimke.
Príliš slabé heslo
NO
YES
YES
YES
context
string
Kontext výnimky. Zistiť viac.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
YES
YES
Kontrola stavu úlohy
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Premenná
Formát
Popis: __________
Príklad
taskId
string
Identifikácia úlohy, ktorú ste dostali v rámci predchádzajúceho kroku.
dFd3sda
Možné návratové kódy:
Odpoveď
Správa
Správa
Popis: __________
RC200
OK – stav úlohy je k dispozícii
Aktualizácia stavu zákazky bola úspešne spracovaná.
Ak nedostanete konečný stav (pozri nižšie), zopakujte tento krok.
RC403
Cloudová úloha sa pre aktuálny terminál nenašla.
Mali by ste skontrolovať ID úlohy a znova odoslať správnu hodnotu.
Skontrolujte, či ste vyplnili správne ID úlohy, a skúste to znova.
Premenné v odpovedi:
Premenná
Formát
Popis: __________
Príklad
RC200
RC404
title
string
Názov úlohy čitateľný ľudským okom. Používa sa z hodnoty žiadosti o vytvorenie úlohy.
Faktúra 36744
YES
NO
taskId
string
Interná identifikácia úlohy
dFd3sda
YES
NO
created
string
Dátum a čas vytvorenia úlohy.
YES
NO
taskClass
string
Možné hodnoty: [TRANSAKCIA, DÁVKA, FIGURÍNA]
YES
NO
status
string
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
YES
NO
initiator
string
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
Pokladňa 12
YES
NO
contextID
string
ID dotknutej cieľovej entity, ak existuje (transactionId / batchId)
YES
NO
Payload
YES
NO
exceptionId
string
Pseudo-jedinečné ID výnimky. Môže slúžiť ako "ID podpory", ktoré môže používateľ komunikovať s podporou, aby mohol vyšetriť akýkoľvek problém.
FujIk6
NO
YES
typ
string
Druh výnimky.
VALIDATION_EXCEPTION
NO
YES
message
string
Správa o výnimke.
Príliš slabé heslo
NO
YES
context
string
Kontext výnimky - viac informácií.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Žiadosť o stav úlohy by sa mala opakovať, kým nedostanete jeden z kódov konečnej odpovede, ktoré sú:
Stav
Popis: __________
Ako sa správať
INIT_ERROR
Platobný proces sa nepodarilo inicializovať. Skontrolujte chybu, ktorá sa vám zobrazila.
Postupujte podľa pokynov na chybu.
COMPLETED
Po získaní tohto stavu bola úloha dokončená a výsledok je k dispozícii.
Môžete prejsť na ďalší krok.
CANCELLED
Úloha bola používateľom zrušená.
Mali by ste začať novú prácu, pretože túto úlohu používateľ zrušil.
ERROR
Pri spracovaní zákazky sa vyskytla chyba.
Postupujte podľa pokynov na chybu.
K ďalšiemu kroku môžete pristúpiť len vtedy, keď je odpoveď v stave DOKONČENÉ.
Získanie výsledku platby
Nyní víme, že transakce byla autorizována. Cílem tohoto kroku je získat stav transakce a detaily transakce. Pro nový požadavek zavoláte koncový bod GET /v1/transactions/{transactionId}, kde použijete následující proměnné:
Premenná
Formát
Popis: __________
Príklad
contextId
string
ID transakcie, ktoré získate v predchádzajúcich krokoch.
Možné kódy odpovedí sú:
Odpoveď
Správa
Správa
Popis: __________
RC200
OK – poskytnuté údaje o transakcii
Úspešná odpoveď na vašu žiadosť.
Transakcia je dokončená!
RC404
Transakciu sa nepodarilo nájsť pre aktuálny TID.
Táto podmienka sa vyskytuje, keď sa pre vaše zariadenie nenašiel daný identifikátor transakcie.
Skontrolujte ID transakcie.
Odpoveď obsahuje nasledujúce premenné v závislosti od kódu odpovede:
Premenná
Formát
Popis: __________
Príklad
RC 200
RC 404
result
string
Výsledok transakcie, možné hodnoty [ ACCEPTED, DECLINED, CANCELLED ], kde:
ACCEPTED - transakcia bola úspešne autorizovaná
DECLINED - transakcia bola z nejakého dôvodu zamietnutá
CANCELLED - ak je transakcia zrušená prevádzkovateľom alebo zákazníkom
ACCEPTED - transakcia bola úspešne autorizovaná
DECLINED - transakcia bola z nejakého dôvodu zamietnutá
CANCELLED - ak je transakcia zrušená prevádzkovateľom alebo zákazníkom
AKCEPTOVANÝ
YES
NO
responseMessage
string
Podrobnejší opis výslednej hodnoty.
"Odmietnuté emitentom."
YES
NO
transanctionId
string
Interné ID úlohy
YES
NO
transactionOperation
string
Možné sadzby: ""SALE"" "VOID"" "REFUND""
Typ operácie/transakcie."
Typ operácie/transakcie."
SALE
YES
NO
transactionType
string
Možné hodnoty "CASH" "CARD"
KARTA
YES
NO
merchantID
string
Iba pre kartové transakcie - ID pobočky.
343382001
YES
NO
tid
string
ID transakcie vytvorené terminálom
483591
YES
NO
currencyCode
string
Kód meny (ISO 4217)
YES
NO
amount
number
Suma transakcie s 2 desatinnými miestami (400 Kč).
400
YES
NO
tipAmount
number
Suma prepitného zadaná na 2 desatinné miesta (30 Kč).
3000
YES
NO
maskovanýPan
string
Číslo maskovanej karty.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
string
Spôsob nabíjania karty - magnetický prúžok, čip alebo bezkontaktná karta
BEZKONTAKTNÉ
YES
NO
referenceNumber
string
Referenčné číslo transakcie prevzaté z hodnoty úlohy v žiadosti: originReferenceNum
FD123456
YES
NO
príjemPočet
string
Číslo potvrdenia o prijatí
12
YES
NO
batchNumber
string
Číslo šarže
2
YES
NO
date
string
Dátum a čas autorizácie transakcie
09.10.2021 15:34
YES
NO
cardType
string
Karta značky EMV prevzatá z údajov o karte
Mastercard CL
YES
NO
declinedReason
string
Dôvod zamietnutia transakcie
201
YES
NO
authorizationCode
string
Číslo vygenerované na strane GP
10293045
YES
NO
sequenceNumber
string
Číslo vygenerované na strane GP
102304128
YES
NO
pomoc
string
Identifikuje aplikáciu EMV použitú na spracovanie transakcie
40100000000
YES
NO
pinMessage
Boolean
Označuje, či sa vstup uskutočnil PIN
Ok
YES
NO
zrušenéPodľa
string
V prípade operácie zrušenia sa tu zobrazí identifikátor kontextu
YES
NO
cardHolderVerificationMethod
string
Len pre terminály Nexgo - označuje spôsob overenia transakcie
PIN
YES
NO
exceptionId
string
Pseudo-jedinečné ID výnimky. Môže slúžiť ako "ID podpory", ktoré môže používateľ komunikovať s podporou, aby mohol preskúmať.
FujIk6
NO
YES
typ
string
Typ výnimky
VALIDATION_EXCEPTION
NO
YES
message
string
Správa o výnimke
Príliš slabé heslo
NO
YES
context
string
Kontext výnimky - viac informácií.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Ak sa chystáte vygenerovať alebo vytlačiť účtenku na svojej strane, odporúčame vám skontrolovať, ktoré polia sú povinné a musia byť vytlačené/zobrazené na účtenke. Popis je k dispozícii tu.