--- title: Storno transakce url: "https://www.gptom.com/en/docs/api/cloudapi/storno-transakce/" updated: "2026-05-05" category: Cloud API --- # Storno transakce ![](https://www.gptom.com/wp-content/uploads/2022/05/info_white_small.png) 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: - dev: [https://cloud-api-dev.gptom.com/cloud/oauth/token](https://cloud-api-dev.gptom.com/cloud/oauth/token) - produkce: [https://cloud-api.gptom.com/cloud/oauth/token](https://cloud-api.gptom.com/cloud/oauth/token) ## 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 tid MANDATORY initiator MANDATORY title MANDATORY printByPaymentApp amount MANDATORY tipAmount transactionOperation originTransactionId originReferenceNum cancelMode MANDATORY transactionType* 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“ 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. Čá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. Možné hodnoty: [ CASH, CARD ] 3 znaky pro kód měny (ISO 4217) Limit pro vypršení platnosti cloudové úlohy. Je povoleno zadat hodnoty z intervalu <10 až 172800> 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 dccData": {"status"} Formát string string string string string string string string number number string 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 Podrobnější popis výsledné hodnoty. Interní ID úkolu Možné hodnody: ""SALE"" ""VOID"" ""REFUND"" Operace / typ transakce." Možné hodnoty: "CASH" "CARD" 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. CZ: Udává informaci, zda se stornuje DCC transakce EN: Gives iformation whether voided transaction was processed as DCC 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=} CZ: Pokud ACCEPTED, je potřeba na účtenku dát text: EN: If ACCEPTED, you need to put on your receit following text: The transaction amount, currency and the exchange rate are the same as for the original transaction. The currency conversion is provided by Global Payments. RC 200 YES YES YES YES YES YES YES YES YES YES YES YES YES YES YES YES YES NO NO NO NO YES RC 404 NO NO NO NO NO NO NO NO NO NO NO NO NO NO NO NO NO YES YES YES YES 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](https://www.gptom.com/manual/vizual-uctenky/).