--- title: Transakce prodej description: "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í…" url: "https://www.gptom.com/hr/docs/api/cloudapi/transakce-prodej/" updated: "2026-10-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 Genius mobile pay - Heslo obchodníka – stejné jako pro Genius mobile pay - 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** **Obsah požadavku:** **Request** POST {{apiCloudHost}}/cloud/oauth/token **Headers** (pro všechny zákazníky vždy stejné, použijte přesně tyto hodnoty): Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ== Content-Type: application/x-www-form-urlencoded **Body** (posílá se v těle požadavku; hodnoty `username`, `password` a `tid` nahraďte unikátními údaji klienta): grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888 **Příklad požadavku:** ``` curl --location '{{apiCloudHost}}/cloud/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'password=ABCDEFGHIJKL' \ --data-urlencode 'username=jan.novak@example.com' \ --data-urlencode 'tid=999888' ``` **Příklad odpovědi:** ```none { "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 Genius mobile pay 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 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 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 string Lidsky čitelný název úkolu. Mělo by obsahovat nějakou identifikaci úkolu. 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. false amount 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 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 \] NOT USED transactionType\* MANDATORY string Možné hodnoty: \[ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY \] 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 Genius mobile pay. 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, 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, COMPLETED, CANCELLED, ERROR\] COMPLETED 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 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." 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 PIN_ENTERED nebo NO_PIN 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 dccData 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 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 currencyCode (DCC) string CZ: Měna zákaznické karty. EN: Currency of the customer's card. EUR YES NO 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 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 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/).