--- title: Transakce prodej url: "https://www.gptom.com/en/docs/api/cloudapi/transakce-prodej/" updated: "2026-07-21" category: Cloud API --- # Transakce prodej 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: - 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) 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 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 Proměnná Formát Popis Příklad tid 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 Proměnná Formát Popis Příklad initiator 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 Proměnná Formát Popis Příklad title MANDATORY string Lidsky čitelný název úkolu. Mělo by obsahovat nějakou identifikaci úkolu. Příklad: „Faktura 37364FD“ Invoice 36744 Proměnná Formát Popis Příklad 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. false Proměnná Formát Popis Příklad amount MANDATORY number Částka transakce musí být nenulová a zahrnuje desetinná místa. Pro hodnotu transakce 50 EUR vyplníte hodnotu „5000“. 40000 Proměnná Formát Popis Příklad tipAmount number Výše spropitného. Pro hodnotu spropitného 3 EUR vyplníte hodnotu „300“. 0 Proměnná Formát Popis Příklad transactionOperation MANDATORY string Typ transakce úkolu. U transakce „Sale“ vyplníte hodnotu „SALE“. SALE Proměnná Formát Popis Příklad originTransactionId string ID transakce ke zrušení. Není null, pokud je režim VOID a zrušení OLDER_TRANSACTION. NOT USED Proměnná Formát Popis Příklad 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 Proměnná Formát Popis Příklad cancelMode string Režim storna, ne null, pokud je typ transakce VOID Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ] NOT USED Proměnná Formát Popis Příklad transactionType* MANDATORY string Možné hodnoty: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ] CARD Proměnná Formát Popis Příklad currencyCode string 3 znaky měny (dle ISO 4217) CZK Proměnná Formát Popis Příklad preferableReceiptType string Předvybraný způsob odeslání účtenky: [ EMAIL, PHONE, QR, PRINT ] EMAIL Proměnná Formát Popis Příklad email string Email zákazníka support@gptom.com Proměnná Formát Popis Příklad phone string Tel. číslo zákazníka +420123456789 Proměnná Formát Popis Příklad 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 Proměnná Formát Popis Příklad 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. Odpověd Zpráva Popis Jak se zachovat RC401 Neutentifikováno Pokud neproběhla autenfitikace s terminálem. Proveďte proces autentifikace (viz krok výše). Odpověd Zpráva Popis Jak se zachovat 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. Odpověd Zpráva Popis Jak se zachovat 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. Odpověd Zpráva Popis Jak se zachovat 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 Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 taskId string Interní id tasku dFd3sda YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 created string Datum a čas vytvoření tasku. YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 taskClass string Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, VOID] TRANSACTION YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 status string Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR] CREATED YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 initiator string Popis iniciátoru na straně klienta. Použito z hodnoty požadavku. Cash desk 12 YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 contextId string ID dotčené cílové entity, pokud existuje (transactionId / batchId) YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 payload object Tělo kontextové úlohy - v závislosti na taskClass {...} YES NO NO NO Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 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 Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 type string Typ výjimky. VALIDATION_EXCEPTION NO YES YES YES Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 message string Zpráva o výjimce. Password too weak NO YES YES YES Proměnná Formát Popis Příklad RC200 RC403 RC406 RC502 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. Odpověd Zpráva Zpráva Popis 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 Proměnná Formát Popis Příklad RC200 RC404 taskId string Interní ID tasku dFd3sda YES NO Proměnná Formát Popis Příklad RC200 RC404 created string Datum a čas vytvoření tasku. YES NO Proměnná Formát Popis Příklad RC200 RC404 taskClass string Možné hodnoty: [TRANSACTION, BATCH, DUMMY] YES NO Proměnná Formát Popis Příklad RC200 RC404 status string Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR] COMPLETED YES NO Proměnná Formát Popis Příklad RC200 RC404 initiator string Popis iniciátoru na straně klienta. Použito z hodnoty požadavku. Cash desk 12 YES NO Proměnná Formát Popis Příklad RC200 RC404 contextID string ID dotčené cílové entity, pokud existuje (transactionId / batchId) YES NO Proměnná Formát Popis Příklad RC200 RC404 payload YES NO Proměnná Formát Popis Příklad RC200 RC404 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 Proměnná Formát Popis Příklad RC200 RC404 type string Typ výjimky. VALIDATION_EXCEPTION NO YES Proměnná Formát Popis Příklad RC200 RC404 message string Zpráva výjimky. Password too weak NO YES Proměnná Formát Popis Příklad RC200 RC404 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ě. Stav Popis Jak se zachovat 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. Stav Popis Jak se zachovat CANCELLED Task byl zrušen uživatelem. Měli byste zahájit novou úlohu, protože tato úloha byla zrušena uživatelem. Stav Popis Jak se zachovat 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! Odpověd Zpráva Zpráva Popis 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 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 responseMessage string Podrobnější popis výsledné hodnoty. “Refused by issuer.” YES NO Proměnná Formát Popis Příklad RC 200 RC 404 transanctionId string Interní ID úkolu YES NO Proměnná Formát Popis Příklad RC 200 RC 404 transactionOperation string Možné hodnody: ""SALE"" ""VOID"" ""REFUND"" Operace / typ transakce." SALE YES NO Proměnná Formát Popis Příklad RC 200 RC 404 transactionType string Možné hodnoty: "CASH" "CARD" CARD YES NO Proměnná Formát Popis Příklad RC 200 RC 404 merchantID string Pouze pro transakce kartou - ID pobočky. 343382001 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 tid string ID transakce vytvořené terminálem 483591 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 currencyCode string Kód měny (ISO 4217) YES NO Proměnná Formát Popis Příklad RC 200 RC 404 amount number Částka transakce se 2 desetinnými místy (400 CZK). 400 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 tipAmount number Částka spropitného zadaná na 2 desetinná místa (30 CZK). 3000 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 maskedPan string Maskované číslo karty. XXXX XXXX XXXX 1233 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 cardDataEntry string Způsob načtení karty - mag.proužek, čip nebo contactless CONTACTLESS YES NO Proměnná Formát Popis Příklad RC 200 RC 404 referenceNumber string Referenční číslo transakce převzaté z hodnoty task požadavku: originReferenceNum FD123456 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 receiptNumber string Číslo účtenky 12 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 batchNumber string Číslo dávky 2 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 date string Datum a čas autorizace transakce 09.10.2021 15:34 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 cardType string EMV brand karty převzatý z dat karty Mastercard CL YES NO Proměnná Formát Popis Příklad RC 200 RC 404 declinedReason string Důvod zamítnutí transakce 201 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 authorizationCode string Číslo generované na straně GP 10293045 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 sequenceNumber string Číslo generované na straně GP 102304128 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 aid string Identifikuje aplikaci EMV používanou pro zpracování transakce 40100000000 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 pinMessage boolean Značí, zda došlo k zadání PIN PIN_ENTERED nebo NO_PIN YES NO Proměnná Formát Popis Příklad RC 200 RC 404 cancelledBy string V případě storno operace se zde zobrazí contextID YES NO Proměnná Formát Popis Příklad RC 200 RC 404 cardHolderVerificationMethod string Pouze pro Nexgo terminály - značí způsob ověření transakce PIN YES NO Proměnná Formát Popis Příklad RC 200 RC 404 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 Proměnná Formát Popis Příklad RC 200 RC 404 type string Typ výjimky VALIDATION_EXCEPTION NO YES Proměnná Formát Popis Příklad RC 200 RC 404 message string Zpráva výjimky Password too weak NO YES Proměnná Formát Popis Příklad RC 200 RC 404 context string Kontext výjimky - další informace. [INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=} NO YES Proměnná Formát Popis Příklad RC 200 RC 404 dccData Proměnná Formát Popis Příklad RC 200 RC 404 status (DCC) string CZ: Udává status DCC. Pokud "ACCEPTED", tak transakce proběhla přes DCC a musíte naplnit účtenku DCC daty. Pokud "NOT_ACCEPTED", tak v tom případě můžete DCC data ignorovat. EN: Indicates the DCC status. If "ACCEPTED", the transaction was made via DCC and you must fill in the receipt with DCC data. If "NOT_ACCEPTED", then you can ignore the DCC data. ACCEPTED NOT_ACCEPTED YES NO Proměnná Formát Popis Příklad RC 200 RC 404 amount (DCC) string CZ: Částka transakce v DCC měně - v měně karty zákazníka. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst. EN: Transaction amount in DCC currency - in the currency of the customer's card. You must present it on your receipt exactly as received through API response including correct decimal numbers. 2.31 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 currencyCode (DCC) string CZ: Měna zákaznické karty. EN: Currency of the customer's card. EUR YES NO Proměnná Formát Popis Příklad RC 200 RC 404 exchangeRate (DCC) string CZ: Udává směnný kurz. Tato hodnota je v lokální měně terminálu. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst. EN: Indicates the exchange rate. This value is in the local terminal currency. You must present it on your receipt exactly as received through API response including correct decimal numbers. 56.35 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 markup (DCC) string CZ: Přirážka ke konverznímu kurzu. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst. EN: Markup for the conversion rate. You must present it on your receipt exactly as received through API response including correct decimal numbers. 3.20 YES NO Proměnná Formát Popis Příklad RC 200 RC 404 regionSchemaIndicator (DCC) string CZ: Udává, zda karta zákazníka byla vydaná v rámci EU nebo mimo. Pokud je hodnota "0" nebo "1", je potřeba na účtence zobrazit text "Markup". Pokud je hodnota "2", je potřeba na účtence zobrazit "Markup over ECB rate". EN: Indicates whether the customer's card was issued within the EU or outside. If the value is "0" or 1", the text "Markup" needs to be displayed on the receipt. If the value is "2", the text "Markup over ECB rate" needs to be displayed on the receipt. 0 1 2 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/).