Informace
Pokud skrze Cloud API voláte storno platby, je nezbytné vytvořit task pro zařízení (TID), kde byla platba původně provedena. Volání storna platby provedené na terminálu „A“ na terminálu „B“ není aktuálně podporováno.
Storno transakce je základní platební operace, která umožňuje zrušit dříve zpracovanou transakci až 93 dnů od původní transakce. Zrušení transakce lze provést bez zákaznické karty – prostředky budou automaticky vráceny na kartu použitou pro původní transakci typu prodej.
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:
Získání access tokenu
Příklad požadavku:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
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
Schéma autorizace HTTP
HTTP
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á
apiKey
MANDATORY
MANDATORY
tid
MANDATORY
MANDATORY
initiator
MANDATORY
MANDATORY
title
MANDATORY
MANDATORY
printByPaymentApp
amount
MANDATORY
MANDATORY
tipAmount
transactionOperation
originTransactionId
originReferenceNum
cancelMode
MANDATORY
MANDATORY
transactionType*
MANDATORY
MANDATORY
currencyCode
timeToLive
Formát
string
string
string
string
boolean
number
number
string
string
string
string
string
string
integer
Popis
API key naleznete přímo v aplikaci v sekci Účet-Cloud API. Používá se k rozlišení přihlášení hlavně v Cloud API.
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.
Popis iniciátoru by měl být jedinečný pro každou instanci subsystému, která může iniciovat úlohu. Příklad: „server XY“ nebo „Pokladna 1“
Lidsky čitelný název úkolu. Mělo by obsahovat nějakou identifikaci úkolu.
Příklad: „Faktura 37364FD platba“
Příklad: „Faktura 37364FD platba“
výchozí hodnota: true
True, pokud má být účtenka vytištěna na zařízení.
Poznámka: U mobilních telefonů se ujistěte, ž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 ujistěte, že je připojena Bluetooth tiskárna.
Částka transakce, která má být zrušena, musí být nenulová a zahrnuje desetinná místa.
Pro storno se nepoužívá.
Typ transakce tasku. U transakce „Storno transakce“ vyplníte hodnotu „VOID“.
ID transakce ke zrušení. Není null, pokud je režim VOID a zrušení OLDER_TRANSACTION.
Nechcete-li tuto hodnotu tisknout na účtenku, ponechte prázdné.
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ] kde:
LAST_TRANSACTION - používá se pouze pro dříve autorizovanou transakci. Mezi tímto úkolem a předchozím prodejním úkolem nemůže být žádný jiný požadavek.
OLDER_TRANSACTION – používá se pro všechny starší transakce kromě poslední transakce.
LAST_TRANSACTION - používá se pouze pro dříve autorizovanou transakci. Mezi tímto úkolem a předchozím prodejním úkolem nemůže být žádný jiný požadavek.
OLDER_TRANSACTION – používá se pro všechny starší transakce kromě poslední transakce.
Možné hodnoty: [ CASH, CARD, GO_CRYPTO ]
3 znaky pro kód měny (ISO 4217)
Limit pro vypršení platnosti cloudové úlohy. Je povoleno zadat hodnoty z intervalu sekund.
Příklad
333W212J3
483590
Cash desk 12
Storno 36744
false
40000
NOT USED
VOID
FD283737333
OPTIONAL
OLDER_TRANSACTION
CARD
CZK
10
Obsah odpovědi [CloudTaskDetailApiResponse]:
Možné kódy odpovědí jsou:
Odpověd
RC200
RC403
RC406
RC 502
Zpráva
OK - Task byl zaregistrován
Uživateli není povoleno registrovat úlohu na daném terminálu
Úloha není pro daný terminál přijatelná
Push notifikace nebyla odeslána
Popis
Úkol byl úspěšně vytvořen a bude zpracován.
Pokud se vaše přihlašovací údaje API neshodují s odeslanou hodnotou TID (například když je vlastník TID jiný).
K tomu obvykle dochází, když TID není schopen požadavek zpracovat.
Push notifikace nebyla odeslána z důvodu selhání upstream služby.
Jak se zachovat
Pokračujte dalším krokem ve flow transakce.
Zkontrolujte, zda jste vyplnili správné TID a zkuste to znovu.
Zkontrolujte chybovou zprávu.
Níže naleznete proměnné použité v odpovědi:
Proměnná
title
taskId
created
taskClass
status
initiator
contextId
payload
exceptionId
type
message
context
Formát
string
string
string
string
string
string
string
object
string
string
string
string
Popis
Lidsky čitelný název tasku. Použito z hodnoty požadavku.
Interní id tasku
Datum a čas vytvoření tasku.
Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, DUMMY]
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
Tělo kontextové úlohy - v závislosti na taskClass
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.
Typ výjimky.
Zpráva o výjimce.
Kontext výjimky. Další informace.
Příklad
Invoice 36744
dFd3sda
TRANSACTION
CREATED
Cash desk 12
{...}
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC406
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC502
NO
NO
NO
NO
NO
NO
NO
NO
YES
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á
taskId
Formát
string
Popis
ID tasku, který jste obdrželi jako součást předchozího kroku.
Příklad
dFd3sda
Možné návratové kódy:
Odpověd
RC200
RC403
Zpráva
OK - Stav tasku k dispozici
Cloudová úloha nebyla pro aktuální terminál nalezena.
Zpráva
Aktualizace stavu úlohy byla úspěšně zpracována.
Měli byste zkontrolovat své taskID a znovu odeslat správnou hodnotu.
Popis
Pokud neobdržíte konečný stav (viz níže), opakujte tento krok.
Zkontrolujte, zda jste vyplnili správné taskID a zkuste to znovu.
Proměnné v odpovědi:
Proměnná
title
taskId
created
taskClass
status
initiator
contextID
payload
exceptionId
type
message
context
Formát
string
string
string
string
string
string
string
string
string
string
string
Popis
Lidsky čitelný název úkolu. Použito z hodnoty požadavku na vytvoření úkolu.
Interní ID tasku
Datum a čas vytvoření tasku.
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
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.
Typ výjimky.
Zpráva výjimky.
Kontext výjimky - další informace.
Příklad
Invoice 36744
dFd3sda
IN_PROGRESS
Cash desk 12
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
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
INIT_ERROR
COMPLETED
CANCELLED
ERROR
Popis
Inicializace platebního procesu se nezdařila. Zkontrolujte přijatou chybu.
Jakmile získáte tento stav, váš úkol byl dokončen a výsledek je k dispozici.
Task byl zrušen uživatelem.
Během zpracování úlohy došlo k nějaké chybě.
Jak se zachovat
Postupujte podle pokynů k chybě.
Můžete pokračovat dalším krokem.
Měli byste zahájit novou úlohu, protože tato úloha byla zrušena uživatelem.
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á
transactionId
Formát
string
Popis
ID transakce, které získáte v předchozích krocích.
Příklad
4414c640-2db7-11ec-910a-91880dadec20
Možné kódy odpovědí jsou:
Odpověd
RC200
RC404
Zpráva
OK – podrobnosti transakce poskytnuty
Pro aktuální TID nebyla transakce nalezena.
Zpráva
Úspěšná odpověď na vaši žádost.
K tomuto stavu dojde, když nebylo pro vaše zařízení nalezeno dané transakční ID.
Popis
Transakce je dokončena!
Zkontrolujte ID transakce.
Odpověď obsahuje následující proměnné v závislosti na kódu odpovědi:
Proměnná
result
responseMessage
transanctionId
transactionOperation
transactionType
merchantID
tid
currencyCode
amount
tipAmount
cardNumber
cardDataEntry
referenceNumber
invoiceNumber
date
emvAppLabel
sequenceNumber
exceptionId
type
message
context
Formát
string
string
string
string
string
string
string
string
number
number
string
string
string
string
string
string
string
string
string
string
string
Popis
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
Podrobnější popis výsledné hodnoty.
Interní ID úkolu
Možné hodnody: ""SALE"" ""VOID"" ""REFUND""
Operace / typ transakce."
Operace / typ transakce."
Možné hodnoty: "CASH" "CARD" "GO_CRYPTO"
Pouze pro transakce kartou - ID pobočky.
ID transakce vytvořené terminálem
Kód měny (ISO 4217)
Částka transakce se 2 desetinnými místy (400 CZK).
Částka spropitného zadaná na 2 desetinná místa (30 CZK).
Maskované číslo karty.
Způsob načtení karty - mag.proužek, čip nebo contactless.
Referenční číslo transakce převzaté z hodnoty task požadavku: originReferenceNum
Datum a čas autorizace transakce
EMV brand karty převzatý z dat karty
Číslo generované na straně GP
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.
Typ výjimky
Zpráva výjimky
Kontext výjimky - další informace.
Příklad
ACCEPTED
null
4414c640-2db7-11ec-910a-91880dadec20
VOID
CARD
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC 200
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC 404
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
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.