Transakcja sprzedaży to podstawowa operacja płatnicza, która przenosi określoną kwotę z konta bankowego posiadacza karty na konto sprzedawcy.
Jeśli chodzi o proces płatności, procedura wygląda następująco:
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
Przykładowe zapytanie:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Typ zawartości: 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
Przykładowa odpowiedź:
{
"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.
Przykładowe zapytanie:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Typ zawartości: 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á
Format
Opis
Przykład
apiKey
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
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
porządek
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
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
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
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
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
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
kwota
OBOWIĄZKOWE
OBOWIĄZKOWE
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
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Typ transakce úkolu. U transakce „Sale“ vyplníte hodnotu „SALE“.
SALE
originTransactionId
ciąg
ID transakce ke zrušení. Není null, pokud je režim VOID a zrušení OLDER_TRANSACTION.
NOT USED
originReferenceNum
ciąg
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
ciąg
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*
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Možné hodnoty: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
KARTA
currencyCode
ciąg
3 znaky měny (dle ISO 4217)
CZK
preferableReceiptType
ciąg
Předvybraný způsob odeslání účtenky: [ EMAIL, PHONE, QR, PRINT ]
EMAIL
e-mail
ciąg
Email zákazníka
support@gptom.com
phone
ciąg
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
Opis
Jak się zachować
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á
Format
Opis
Przykład
RC200
RC403
RC406
RC502
title
ciąg
Lidsky čitelný název tasku. Použito z hodnoty požadavku.
Invoice 36744
YES
NO
NO
NO
taskId
ciąg
Interní id tasku
dFd3sda
YES
NO
NO
NO
stworzony
ciąg
Datum a čas vytvoření tasku.
YES
NO
NO
NO
taskClass
ciąg
Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, VOID]
TRANSACTION
YES
NO
NO
NO
status
ciąg
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
UTWORZONY
YES
NO
NO
NO
initiator
ciąg
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
Cash desk 12
YES
NO
NO
NO
contextId
ciąg
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
ciąg
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
ciąg
Typ výjimky.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
ciąg
Zpráva o výjimce.
Password too weak
NO
YES
YES
YES
context
ciąg
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á
Format
Opis
Przykład
taskId
ciąg
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
Opis
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á
Format
Opis
Przykład
RC200
RC404
title
ciąg
Lidsky čitelný název úkolu. Použito z hodnoty požadavku na vytvoření úkolu.
Invoice 36744
YES
NO
taskId
ciąg
Interní ID tasku
dFd3sda
YES
NO
stworzony
ciąg
Datum a čas vytvoření tasku.
YES
NO
taskClass
ciąg
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
YES
NO
status
ciąg
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
YES
NO
initiator
ciąg
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
Cash desk 12
YES
NO
contextID
ciąg
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
YES
NO
payload
YES
NO
exceptionId
ciąg
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
ciąg
Typ výjimky.
VALIDATION_EXCEPTION
NO
YES
message
ciąg
Zpráva výjimky.
Password too weak
NO
YES
context
ciąg
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:
Status
Opis
Jak się zachować
INIT_ERROR
Inicjacja procesu płatności nie powiodła się. Sprawdź otrzymany błąd.
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
ZAKOŃCZONE
Otrzymanie tego statusu oznacza, że zadanie zostało ukończone, a jego wynik jest dostępny.
Můžete pokračovat dalším krokem.
ODWOŁANE
Task byl zrušen uživatelem.
Měli byste zahájit novou úlohu, protože tato úloha byla zrušena uživatelem.
BŁĄD
Podczas przetwarzania zadania wystąpił błąd.
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
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á
Format
Opis
Przykład
contextId
ciąg
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
Opis
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á
Format
Opis
Przykład
RC 200
RC 404
wynik
ciąg
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
ciąg
Podrobnější popis výsledné hodnoty.
“Refused by issuer.”
YES
NO
transanctionId
ciąg
Interní ID úkolu
YES
NO
transactionOperation
ciąg
Možné hodnody: ""SALE"" ""VOID"" ""REFUND""
Operace / typ transakce."
Operace / typ transakce."
SALE
YES
NO
transactionType
ciąg
Možné hodnoty: "CASH" "CARD"
KARTA
YES
NO
merchantID
ciąg
Pouze pro transakce kartou - ID pobočky.
343382001
YES
NO
porządek
ciąg
ID transakce vytvořené terminálem
483591
YES
NO
currencyCode
ciąg
Kód měny (ISO 4217)
YES
NO
kwota
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
ciąg
Maskované číslo karty.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
ciąg
Způsob načtení karty - mag.proužek, čip nebo contactless
BEZKONTAKTOWY
YES
NO
referenceNumber
ciąg
Referenční číslo transakce převzaté z hodnoty task požadavku: originReferenceNum
FD123456
YES
NO
receiptNumber
ciąg
Číslo účtenky
12
YES
NO
batchNumber
ciąg
Číslo dávky
2
YES
NO
data
ciąg
Datum a čas autorizace transakce
09.10.2021 15:34
YES
NO
cardType
ciąg
EMV brand karty převzatý z dat karty
Mastercard CL
YES
NO
declinedReason
ciąg
Důvod zamítnutí transakce
201
YES
NO
authorizationCode
ciąg
Číslo generované na straně GP
10293045
YES
NO
sequenceNumber
ciąg
Číslo generované na straně GP
102304128
YES
NO
aid
ciąg
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
ciąg
V případě storno operace se zde zobrazí contextID
YES
NO
cardHolderVerificationMethod
ciąg
Pouze pro Nexgo terminály - značí způsob ověření transakce
PIN
YES
NO
exceptionId
ciąg
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
ciąg
Typ výjimky
VALIDATION_EXCEPTION
NO
YES
message
ciąg
Zpráva výjimky
Password too weak
NO
YES
context
ciąg
Kontext výjimky - další informace.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
dccData
status (DCC)
ciąg
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.
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
NOT_ACCEPTED
YES
NO
amount (DCC)
ciąg
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.
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)
ciąg
CZ: Měna zákaznické karty.
EN: Currency of the customer's card.
EN: Currency of the customer's card.
EUR
YES
NO
exchangeRate (DCC)
ciąg
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.
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)
ciąg
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.
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)
ciąg
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.
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
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.