Transakce prodej je základní platební operace, která zajišťuje převod stanovené částky z bankovního účtu držitele karty na účet obchodníka.
Pokud jde o průběh platby, postup je následující:
Přihlášení & autentifikace
Pro všechny neveřejné koncové body je potřeba ověření pomocí tokenu JWT. Token (s životností 90 dnů) získáte prostřednictvím koncového bodu /cloud/oauth/token s následujícími poskytnutými argumenty:
- Základní autentizace pro koncové body tokenu (jméno/heslo) – bude poskytnuto pro každého uživatele.
- Uživatelské jméno obchodníka – stejné jako pro GP tom
- Heslo obchodníka – stejné jako pro GP tom
- ID terminálu (TID) – ID cílového terminálu
- Autorizační koncový bod se nachází na:
Tento způsob autentifikace je pro všechny terminály stejný.
Získání access tokenu
Příklad požadavku:
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
Příklad odpovědi:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Obnovení tokenu
Po vypršení platnosti access_tokenu je k dispozici refresh_token.
Příklad požadavku:
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
Vytvoření tasku
Zavolejte koncový bod POST /v1/tasks/TRANSACTION a použijte CreateCloudTaskTransactionApiRequest s následujícími údaji vyplněnými k vytvoření požadavku:
Proměnná
Formát
Popis
Příklad
apiKey
MANDATORY
MANDATORY
string
API key najdete přímo v aplikaci GP tom v sekci Účet-Cloud API. Používá se k rozlišení přihlášení hlavně v Cloud API. Pro každou společnost je API key unikátní.
333W212J3
tid
MANDATORY
MANDATORY
string
Cílové TID pro daný úkol. TID = ID terminálu, které je jedinečné pro každé zařízení. Na všech nainstalovaných zařízeních lze současně používat pouze jedno TID.
483590
initiator
MANDATORY
MANDATORY
string
Popis iniciátoru by měl být jedinečný pro každou instanci subsystému, která může iniciovat task. Příklad: „server XY“ nebo „Pokladna 1“
Cash desk 12
title
MANDATORY
MANDATORY
string
Lidsky čitelný název úkolu. Mělo by obsahovat nějakou identifikaci úkolu.
Příklad: „Faktura 37364FD“
Příklad: „Faktura 37364FD“
Invoice 36744
printByPaymentApp
boolean
default: true
True, pokud má být účtenka vytištěna na zařízení.
Poznámka: U mobilních telefonů se musíte ujistit, že je připojena Bluetooth tiskárna.
True, pokud má být účtenka vytištěna na zařízení.
Poznámka: U mobilních telefonů se musíte ujistit, že je připojena Bluetooth tiskárna.
false
amount
MANDATORY
MANDATORY
number
Částka transakce musí být nenulová a zahrnuje desetinná místa. Pro hodnotu transakce 50 EUR vyplníte hodnotu „5000“.
40000
tipAmount
number
Výše spropitného. Pro hodnotu spropitného 3 EUR vyplníte hodnotu „300“.
0
transactionOperation
MANDATORY
MANDATORY
string
Typ transakce úkolu. U transakce „Sale“ vyplníte hodnotu „SALE“.
SALE
originTransactionId
string
ID transakce ke zrušení. Není null, pokud je režim VOID a zrušení OLDER_TRANSACTION.
NOT USED
originReferenceNum
string
Referenční číslo, např. číslo faktury – přidejte libovolnou hodnotu do 20 znaků, která bude viditelná v přehledech a identifikuje platbu na vaší straně.
FD123456
cancelMode
string
Režim storna, ne null, pokud je typ transakce VOID
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NOT USED
transactionType*
MANDATORY
MANDATORY
string
Možné hodnoty: [ CASH, CARD, ACCOUNT_PAYMENT ]
CARD
currencyCode
string
3 znaky měny (dle ISO 4217)
CZK
preferableReceiptType
string
Předvybraný způsob odeslání účtenky: [ EMAIL, PHONE, QR, PRINT ]
EMAIL
email
string
Email zákazníka
support@gptom.com
phone
string
Tel. čí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
integer
Limit pro vypršení platnosti cloudové úlohy. Je povoleno zadat hodnoty z intervalu 10 až 172800 sekund.
10
Obsah odpovědi [CloudTaskDetailApiResponse]:
Možné kódy odpovědí jsou:
Odpověd
Zpráva
Popis
Jak se zachovat
RC200
OK - Task byl zaregistrován
Úkol byl úspěšně vytvořen a bude zpracován.
Pokračujte dalším krokem ve flow transakce.
RC401
Neutentifikováno
Pokud neproběhla autenfitikace s terminálem.
Proveďte proces autentifikace (viz krok výše).
RC403
Uživateli není povoleno registrovat úlohu na daném terminálu
Pokud se vaše přihlašovací údaje API neshodují s odeslanou hodnotou TID (například když je vlastník TID jiný).
Zkontrolujte, zda jste vyplnili správné TID a zkuste to znovu.
RC406
Úloha není pro daný terminál přijatelná
K tomu obvykle dochází, když TID není schopen požadavek zpracovat.
Zkontrolujte chybovou zprávu.
RC 502
Push notifikace nebyla odeslána
Push notifikace nebyla odeslána z důvodu selhání upstream služby.
Níže naleznete proměnné použité v odpovědi:
Proměnná
Formát
Popis
Příklad
RC200
RC403
RC406
RC502
title
string
Lidsky čitelný název tasku. Použito z hodnoty požadavku.
Invoice 36744
YES
NO
NO
NO
taskId
string
Interní id tasku
dFd3sda
YES
NO
NO
NO
created
string
Datum a čas vytvoření tasku.
YES
NO
NO
NO
taskClass
string
Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, VOID]
TRANSACTION
YES
NO
NO
NO
status
string
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREATED
YES
NO
NO
NO
initiator
string
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
Cash desk 12
YES
NO
NO
NO
contextId
string
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
YES
NO
NO
NO
payload
object
Tělo kontextové úlohy - v závislosti na taskClass
{...}
YES
NO
NO
NO
exceptionId
string
Pseudojedinečné ID výjimky. Může sloužit jako „ID pro podporu“, které může uživatel sdělit podpoře, aby mohla prošetřit chybu.
FujIk6
NO
YES
YES
YES
type
string
Typ výjimky.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
string
Zpráva o výjimce.
Password too weak
NO
YES
YES
YES
context
string
Kontext výjimky. Další informace.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
YES
YES
Kontrola stavu tasku
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Proměnná
Formát
Popis
Příklad
taskId
string
ID tasku, který jste obdrželi jako součást předchozího kroku.
dFd3sda
Možné návratové kódy:
Odpověd
Zpráva
Zpráva
Popis
RC200
OK - Stav tasku k dispozici
Aktualizace stavu úlohy byla úspěšně zpracována.
Pokud neobdržíte konečný stav (viz níže), opakujte tento krok.
RC403
Cloudová úloha nebyla pro aktuální terminál nalezena.
Měli byste zkontrolovat své taskID a znovu odeslat správnou hodnotu.
Zkontrolujte, zda jste vyplnili správné taskID a zkuste to znovu.
Proměnné v odpovědi:
Proměnná
Formát
Popis
Příklad
RC200
RC404
title
string
Lidsky čitelný název úkolu. Použito z hodnoty požadavku na vytvoření úkolu.
Invoice 36744
YES
NO
taskId
string
Interní ID tasku
dFd3sda
YES
NO
created
string
Datum a čas vytvoření tasku.
YES
NO
taskClass
string
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
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átoru na straně klienta. Použito z hodnoty požadavku.
Cash desk 12
YES
NO
contextID
string
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
YES
NO
payload
YES
NO
exceptionId
string
Pseudojedinečné ID výjimky. Může sloužit jako „ID podpory“, které může uživatel sdělit podpoře, aby mohla prošetřit případný problém.
FujIk6
NO
YES
type
string
Typ výjimky.
VALIDATION_EXCEPTION
NO
YES
message
string
Zpráva výjimky.
Password too weak
NO
YES
context
string
Kontext výjimky - další informace.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Požadavek na stav tasku by se měl opakovat, dokud nezískáte jeden z konečných kódů odpovědi, kterými jsou:
Stav
Popis
Jak se zachovat
INIT_ERROR
Inicializace platebního procesu se nezdařila. Zkontrolujte přijatou chybu.
Postupujte podle pokynů k chybě.
COMPLETED
Jakmile získáte tento stav, váš úkol byl dokončen a výsledek je k dispozici.
Můžete pokračovat dalším krokem.
CANCELLED
Task byl zrušen uživatelem.
Měli byste zahájit novou úlohu, protože tato úloha byla zrušena uživatelem.
ERROR
Během zpracování úlohy došlo k nějaké chybě.
Postupujte podle pokynů k chybě.
Dalším krokem můžete pokračovat pouze tehdy, když je odpověď ve stavu COMPLETED.
Získání 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é:
Proměnná
Formát
Popis
Příklad
contextId
string
ID transakce, které získáte v předchozích krocích.
Možné kódy odpovědí jsou:
Odpověd
Zpráva
Zpráva
Popis
RC200
OK – podrobnosti transakce poskytnuty
Úspěšná odpověď na vaši žádost.
Transakce je dokončena!
RC404
Pro aktuální TID nebyla transakce nalezena.
K tomuto stavu dojde, když nebylo pro vaše zařízení nalezeno dané transakční ID.
Zkontrolujte ID transakce.
Odpověď obsahuje následující proměnné v závislosti na kódu odpovědi:
Proměnná
Formát
Popis
Příklad
RC 200
RC 404
result
string
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
ACCEPTED
YES
NO
responseMessage
string
Podrobnější popis výsledné hodnoty.
“Refused by issuer.”
YES
NO
transanctionId
string
Interní ID úkolu
YES
NO
transactionOperation
string
Možné hodnody: ""SALE"" ""VOID"" ""REFUND""
Operace / typ transakce."
Operace / typ transakce."
SALE
YES
NO
transactionType
string
Možné hodnoty: "CASH" "CARD"
CARD
YES
NO
merchantID
string
Pouze pro transakce kartou - ID pobočky.
343382001
YES
NO
tid
string
ID transakce vytvořené terminálem
483591
YES
NO
currencyCode
string
Kód měny (ISO 4217)
YES
NO
amount
number
Částka transakce se 2 desetinnými místy (400 CZK).
400
YES
NO
tipAmount
number
Částka spropitného zadaná na 2 desetinná místa (30 CZK).
3000
YES
NO
maskedPan
string
Maskované číslo karty.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
string
Způsob načtení karty - mag.proužek, čip nebo contactless
CONTACTLESS
YES
NO
referenceNumber
string
Referenční číslo transakce převzaté z hodnoty task požadavku: originReferenceNum
FD123456
YES
NO
receiptNumber
string
Číslo účtenky
12
YES
NO
batchNumber
string
Číslo dávky
2
YES
NO
date
string
Datum a čas autorizace transakce
09.10.2021 15:34
YES
NO
cardType
string
EMV brand karty převzatý z dat karty
Mastercard CL
YES
NO
declinedReason
string
Důvod zamítnutí transakce
201
YES
NO
authorizationCode
string
Číslo generované na straně GP
10293045
YES
NO
sequenceNumber
string
Číslo generované na straně GP
102304128
YES
NO
aid
string
Identifikuje aplikaci EMV používanou pro zpracování transakce
40100000000
YES
NO
pinMessage
boolean
Značí, zda došlo k zadání PIN
Ok
YES
NO
cancelledBy
string
V případě storno operace se zde zobrazí contextID
YES
NO
cardHolderVerificationMethod
string
Pouze pro Nexgo terminály - značí způsob ověření transakce
PIN
YES
NO
exceptionId
string
Pseudojedinečné ID výjimky. Může sloužit jako „ID podpory“, které může uživatel sdělit podpoře, aby mohla prošetřit.
FujIk6
NO
YES
type
string
Typ výjimky
VALIDATION_EXCEPTION
NO
YES
message
string
Zpráva výjimky
Password too weak
NO
YES
context
string
Kontext výjimky - další informace.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
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.