Informácie
Ak prostredníctvom Cloud API voláte zrušenie platby, je potrebné vytvoriť úlohu pre zariadenie (TID), na ktorom bola platba pôvodne vykonaná. Volanie zrušenia platby vykonanej na termináli „A“ na termináli „B“ momentálne nie je podporované.
Storno transakcie je základná platobná operácia, ktorá umožňuje zrušiť predtým spracovanú transakciu až do 93 dní od pôvodnej transakcie. Zrušenie transakcie je možné vykonať bez zákazníckej karty – prostriedky budú automaticky vrátené na kartu použitú pri pôvodnej transakcii typu predaj.
Prihlásenie a overenie
Pre všetky neverejné koncové body je potrebné overenie pomocou tokenu JWT. Token (s platnosťou 90 dní) získate prostredníctvom koncového bodu /cloud/oauth/token s nasledujúcimi zadanými argumentmi:
- Základné overenie pre koncové body tokenu (meno/heslo) – bude poskytnuté každému používateľovi.
- Používateľské meno obchodníka – rovnaké ako pre GP tom
- Heslo obchodníka – rovnaké ako pre GP tom
- ID terminálu (TID) – ID cieľového terminálu
- Autorizačný koncový bod sa nachádza na:
Získanie prístupového tokenu
Príklad požiadavky:
POST {{apiCloudHost}}/cloud/oauth/token
Autorizácia: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Príklad odpovede:
{
"access_token": "eyJh…", // prístupový token používaný v overených požiadavkách na API
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Obnovenie tokenu
Po uplynutí platnosti access_tokenu je k dispozícii refresh_token.
Príklad požiadavky:
POST {{apiHost}}/api/oauth/token
Autorizácia: 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 HTTP autorizácie
HTTP
na doručiteľa
Vytvorenie úlohy
Oslovte koncový bod POST /v1/tasks/TRANSACTION a na vytvorenie požiadavky použite CreateCloudTaskTransactionApiRequest s nasledujúcimi údajmi:
Premenná
apiKey
POVINNÉ
POVINNÉ
čas
POVINNÉ
POVINNÉ
iniciátor
POVINNÉ
POVINNÉ
názov
POVINNÉ
POVINNÉ
tlač cez platobnú aplikáciu
suma
POVINNÉ
POVINNÉ
tipAmount
transakčná operácia
originTransactionId
originReferenceNum
režim zrušenia
POVINNÉ
POVINNÉ
transactionType*
POVINNÉ
POVINNÉ
kód meny
timeToLive
Formát
reťazec
reťazec
reťazec
reťazec
boolean
číslo
číslo
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
celé číslo
Popis
API kľúč nájdete priamo v aplikácii v sekcii Účet – Cloud API. Slúži na identifikáciu prihlásenia, najmä v Cloud API.
Cieľové TID pre danú úlohu. TID = ID terminálu, ktoré je jedinečné pre každé zariadenie. Na všetkých nainštalovaných zariadeniach je možné súčasne používať len jedno TID.
Popis iniciátora by mal byť jedinečný pre každú inštanciu subsystému, ktorá môže iniciovať úlohu. Príklad: „server XY“ alebo „Pokladňa 1“
Ľahko zrozumiteľný názov úlohy. Mal by obsahovať nejakú identifikáciu úlohy.
Príklad: „Faktúra 37364FD – platba“
Príklad: „Faktúra 37364FD – platba“
predvolená hodnota: true
To je pravda, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa uistite, že je pripojená Bluetooth tlačiareň.
To je pravda, ak sa má účtenka vytlačiť na zariadení.
Poznámka: V prípade mobilných telefónov sa uistite, že je pripojená Bluetooth tlačiareň.
Suma transakcie, ktorá sa má zrušiť, nesmie byť nulová a musí obsahovať desatinné miesta.
Na zrušenie sa nepoužíva.
Typ transakcie: tasku. Pri transakcii „Storno transakcie“ vyplňte hodnotu „VOID“.
ID transakcie, ktorá sa má zrušiť. Nie je null, ak je režim VOID a zrušenie OLDER_TRANSACTION.
Ak túto hodnotu nechcete vytlačiť na účtenku, ponechajte pole prázdne.
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ], kde:
LAST_TRANSACTION – používa sa iba pre predtým autorizovanú transakciu. Medzi touto úlohou a predchádzajúcou predajnou úlohou nesmie byť žiadna iná požiadavka.
OLDER_TRANSACTION – používa sa pre všetky staršie transakcie okrem poslednej transakcie.
LAST_TRANSACTION – používa sa iba pre predtým autorizovanú transakciu. Medzi touto úlohou a predchádzajúcou predajnou úlohou nesmie byť žiadna iná požiadavka.
OLDER_TRANSACTION – používa sa pre všetky staršie transakcie okrem poslednej transakcie.
Možné hodnoty: [ CASH, CARD ]
3 znaky pre kód meny (ISO 4217)
Časový limit pre vypršanie platnosti úlohy v cloude. Je možné zadať hodnoty v rozmedzí od sekúnd.
Príklad
333W212J3
483590
Pokladňa 12
Storno 36744
false
40000
NEPOUŽÍVA SA
NEPLATNÉ
FD283737333
VOLITEĽNÉ
STARŠIA TRANSAKCIA
KARTA
CZK
10
Obsah odpovede [CloudTaskDetailApiResponse]:
Možné kódy odpovedí sú:
Odpoveď
RC200
RC403
RC406
RC 502
Správa
OK – Úloha bola zaregistrovaná
Používateľ nemá oprávnenie zaregistrovať úlohu na danom termináli
Úloha nie je pre daný terminál prijateľná
Push notifikácia nebola odoslaná
Popis
Úloha bola úspešne vytvorená a bude spracovaná.
Ak sa vaše prihlasovacie údaje API nezhodujú s odoslanou hodnotou TID (napríklad ak je vlastník TID iný).
K tomu zvyčajne dochádza, keď TID nie je schopný spracovať požiadavku.
Push notifikácia nebola odoslaná z dôvodu zlyhania služby upstream.
Ako sa správať
Pokračujte ďalším krokom v priebehu transakcie.
Skontrolujte, či ste zadali správne TID, a skúste to znova.
Skontrolujte chybovú správu.
Nižšie nájdete premenné použité v odpovedi:
Premenná
názov
ID úlohy
vytvorené
taskClass
stav
iniciátor
contextId
užitočné zaťaženie
ID výnimky
typ
správa
kontext
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
objekt
reťazec
reťazec
reťazec
reťazec
Popis
Čitateľný názov priečinka. Použitý z hodnoty požiadavky.
Interné ID tašky
Dátum a čas vytvorenia úlohy.
Trieda užitočného zaťaženiaMožné hodnoty: [TRANSACTION, BATCH, DUMMY]
Stav úlohy v cloude. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
Telo kontextovej úlohy – v závislosti od taskClass
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID pre podporu“, ktoré môže používateľ poskytnúť podpore, aby mohla chybu prešetriť.
Typ výnimky.
Správa o výnimke.
Kontext výnimky. Ďalšie informácie.
Príklad
Faktúra č. 36744
dFd3sda
TRANSAKCIA
VYTVORENÉ
Pokladňa 12
{...}
FujIk6
VALIDATION_EXCEPTION
Heslo je príliš slabé
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
RC406
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
RC502
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
Kontrola stavu tašky
V ďalšom kroku skontrolujete stav úlohy na koncovom bode GET /v1/tasks/{taskID} pomocou požiadavky, ktorá obsahuje:
Premenná
ID úlohy
Formát
reťazec
Popis
ID tašky, ktoré ste dostali v predchádzajúcom kroku.
Príklad
dFd3sda
Možné kódy vrátenia:
Odpoveď
RC200
RC403
Správa
OK – Stav tašky k dispozícii
Pre aktuálny terminál nebola nájdená žiadna úloha v cloude.
Správa
Aktualizácia stavu úlohy bola úspešne spracovaná.
Mali by ste skontrolovať svoje taskID a znovu odoslať správnu hodnotu.
Popis
Ak nedostanete konečný stav (pozri nižšie), tento krok zopakujte.
Skontrolujte, či ste zadali správne taskID, a skúste to znova.
Premenné v odpovedi:
Premenná
názov
ID úlohy
vytvorené
taskClass
stav
iniciátor
contextID
užitočné zaťaženie
ID výnimky
typ
správa
kontext
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
Popis
Ľahko zrozumiteľný názov úlohy. Použitý z hodnoty požiadavky na vytvorenie úlohy.
Interné ID tašky
Dátum a čas vytvorenia úlohy.
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID podpory“, ktoré môže používateľ poskytnúť podpore, aby mohla prešetriť prípadný problém.
Typ výnimky.
Správa o výnimke.
Kontext výnimky – ďalšie informácie.
Príklad
Faktúra č. 36744
dFd3sda
V PRÍPRAVE
Pokladňa 12
FujIk6
VALIDATION_EXCEPTION
Heslo je príliš slabé
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
Požiadavka na stav úlohy by sa mala opakovať, kým nezískate jeden z konečných kódov odpovede, ktorými sú:
Stav
INIT_ERROR
DOKONČENÉ
ZRUŠENÉ
CHYBA
Popis
Inicializácia platobného procesu sa nepodarila. Skontrolujte hlásenú chybu.
Akonáhle dosiahnete tento stav, vaša úloha je dokončená a výsledok je k dispozícii.
Úloha bola zrušená používateľom.
Pri spracovaní úlohy došlo k chybe.
Ako sa správať
Postupujte podľa pokynov k chybe.
Môžete pokračovať ďalším krokom.
Mali by ste začať novú úlohu, pretože táto úloha bola zrušená používateľom.
Postupujte podľa pokynov k chybe.
Ďalším krokom môžete pokračovať len vtedy, ak je odpoveď v stave COMPLETED.
Získanie informácií o platbe
Teraz vieme, že transakcia bola autorizovaná. Cieľom tohto kroku je získať stav transakcie a jej podrobnosti. Pre novú požiadavku voláte koncový bod GET /v1/transactions/{transactionId}, kde použijete nasledujúce premenné:
Premenná
transactionId
Formát
reťazec
Popis
ID transakcie, ktoré získate v predchádzajúcich krokoch.
Príklad
4414c640-2db7-11ec-910a-91880dadec20
Možné kódy odpovedí sú:
Odpoveď
RC200
RC404
Správa
OK – podrobnosti transakcie boli poskytnuté
Pre zadané TID nebola nájdená žiadna transakcia.
Správa
Vaša žiadosť bola úspešne spracovaná.
K tejto situácii dôjde, ak sa pre vaše zariadenie nepodarilo nájsť príslušné transakčné ID.
Popis
Transakcia bola dokončená!
Skontrolujte identifikačné číslo transakcie.
Odpoveď obsahuje nasledujúce premenné v závislosti od kódu odpovede:
Premenná
výsledok
odpoveďová správa
transanctionId
transakčná operácia
typ transakcie
merchantID
čas
kód meny
suma
tipAmount
číslo karty
vstup údajov z karty
referenčné číslo
číslo faktúry
dátum
emvAppLabel
číslo sekvencie
ID výnimky
typ
správa
kontext
dccData": {"status"}
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
číslo
číslo
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
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
Podrobnejší popis výslednej hodnoty.
Interné ID úlohy
Možné hodnoty: "SALE", "VOID", "REFUND"
Operácia / typ transakcie."
Operácia / typ transakcie."
Možné hodnoty: "CASH", "CARD"
Iba pre transakcie kartou – ID pobočky.
ID transakcie vytvorené terminálom
Kód meny (ISO 4217)
Suma transakcie s dvoma desatinnými miestami (400 CZK).
Suma spropitného zadaná na 2 desatinné miesta (30 CZK).
Skryté číslo karty.
Spôsob čítania karty – magnetický prúžok, čip alebo bezkontaktný.
Referenčné číslo transakcie prevzaté z hodnoty požiadavky úlohy: originReferenceNum
Dátum a čas autorizácie transakcie
Údaje o značke karty prevzaté z údajov na karte
Číslo vygenerované na strane GP
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID podpory“, ktoré môže používateľ poskytnúť podpore, aby mohla situáciu prešetriť.
Typ výnimky
Správa o výnimke
Kontext výnimky – ďalšie informácie.
SK: Uvádza informáciu, či sa transakcia DCC zruší
EN: Poskytuje informáciu o tom, či bola zrušená transakcia spracovaná ako DCC
EN: Poskytuje informáciu o tom, či bola zrušená transakcia spracovaná ako DCC
Príklad
PRIJATÉ
null
4414c640-2db7-11ec-910a-91880dadec20
NEPLATNÉ
KARTA
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDATION_EXCEPTION
Heslo je príliš slabé
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
SK: Ak je stav ACCEPTED, je potrebné na účtenku uviesť text:
EN: Ak bude žiadosť schválená, do potvrdenia je potrebné uviesť nasledujúci text:
Suma transakcie, mena a výmenný kurz sú rovnaké ako pri pôvodnej transakcii.
Prepočet meny zabezpečuje spoločnosť Global Payments.
EN: Ak bude žiadosť schválená, do potvrdenia je potrebné uviesť nasledujúci text:
Suma transakcie, mena a výmenný kurz sú rovnaké ako pri pôvodnej transakcii.
Prepočet meny zabezpečuje spoločnosť Global Payments.
RC 200
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
NO
NO
NO
NO
ÁNO
RC 404
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
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.