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.
Conectare și autentificare
Autentificarea cu jetonul JWT este necesară pentru toate punctele finale nepublice. Jetonul (cu o durată de viață de 90 de zile) este obținut prin intermediul punctului final /cloud/oauth/token, cu următoarele argumente furnizate:
- Autentificarea de bază pentru punctele finale cu token (nume/parolă) - va fi furnizată pentru fiecare utilizator.
- Numele de utilizator Trader - același ca pentru GP tom
- Parola Trader - aceeași ca pentru GP tom
- ID terminal (TID) - ID al terminalului de destinație
- Punctul final de autorizare este situat la:
Obținerea unui jeton de acces
Exemplu de cerere:
POST {{apiCloudHost}}/cloud/oauth/token
Autorizare: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Exemplu de răspuns:
{
"access_token": "eyJh...", // token de acces utilizat în cererile API autentificate
"token_type": "bearer",
"refresh_token": "GciO...",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Reînnoirea unui jeton
Atunci când access_token expiră, este disponibil un refresh_token.
Exemplu de cerere:
POST {{apiHost}}/api/oauth/token
Autorizare: 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
purtător
Crearea unui sac
Apelați la punctul final POST /v1/tasks/TRANSACTION și utilizați CreateCloudTaskTransactionApiRequest cu următoarele informații completate pentru a crea cererea:
Variabilă
apiKey
OBLIGATORIU
OBLIGATORIU
tid
OBLIGATORIU
OBLIGATORIU
inițiator
OBLIGATORIU
OBLIGATORIU
titlu
OBLIGATORIU
OBLIGATORIU
printarePaymentApp
sumă
OBLIGATORIU
OBLIGATORIU
TipAmount
tranzacțieOperațiune
originTransactionId
origineNumReferință
anulareMode
OBLIGATORIU
OBLIGATORIU
tip de tranzacție*
OBLIGATORIU
OBLIGATORIU
cod valută
timp de viață
Format
șir
șir
șir
șir
boolean
număr
număr
șir
șir
șir
șir
șir
șir
Număr întreg
Descriere
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.
TID-ul țintă pentru sarcină. TID = Terminal ID, care este unic pentru fiecare dispozitiv. Un singur TID poate fi utilizat în același timp pe toate dispozitivele instalate.
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“
Un titlu al sarcinii care poate fi citit de către om. Acesta trebuie să includă o anumită identificare a sarcinii.
Příklad: „Faktura 37364FD platba“
Příklad: „Faktura 37364FD platba“
výchozí hodnota: true
Adevărat dacă chitanța urmează să fie imprimată pe dispozitiv.
Poznámka: U mobilních telefonů se ujistěte, že je připojena Bluetooth tiskárna.
Adevărat dacă chitanța urmează să fie imprimată pe dispozitiv.
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-ul tranzacției care urmează să fie anulată. Nu este nul dacă modul este VOID și anularea este 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.
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.
Exemplu
333W212J3
483590
Casierie 12
Storno 36744
fals
40000
NEUTILIZAT
VOID
FD283737333
OPTIONAL
OLDER_TRANSACTION
CARD
CZK
10
Conținutul [CloudTaskDetailApiResponse]:
Codurile de răspuns posibile sunt:
Răspuns
RC200
RC403
RC406
RC 502
Raport
OK - Sarcina a fost înregistrată
Utilizatorul nu are permisiunea de a înregistra o sarcină pe terminal
Sarcina nu este acceptabilă pentru terminal
Notificarea push nu a fost trimisă
Descriere
Sarcina a fost creată cu succes și va fi procesată.
Dacă acreditările API nu corespund cu valoarea TID trimisă (de exemplu, dacă proprietarul TID este diferit).
Acest lucru se întâmplă de obicei atunci când TID nu este în măsură să proceseze cererea.
Notificarea push nu a fost trimisă din cauza unui eșec al serviciului upstream.
Cum să te comporți
Continuați cu următorul pas din fluxul de tranzacții.
Verificați dacă ați completat TID-ul corect și încercați din nou.
Verificați mesajul de eroare.
Mai jos sunt prezentate variabilele utilizate în răspuns:
Variabilă
titlu
TaskId
creat
TaskClass
statut
inițiator
contextId
sarcina utilă
excepțieId
tip
mesaj
context
Format
șir
șir
șir
șir
șir
șir
șir
obiect
șir
șir
șir
șir
Descriere
Numele lizibil de către om al sacului. Utilizat din valoarea cererii.
Identitatea internă a genții
Data și ora la care a fost creat sacul.
Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, DUMMY]
Starea sacului cloud. Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Descrierea inițiatorului din partea clientului. Utilizată din valoarea cererii.
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
Corpul sarcinii contextuale - în funcție de taskClass
ID de excepție pseudo-unic. Poate servi ca un „ID de asistență“ pe care utilizatorul îl poate indica asistenței pentru a investiga eroarea.
Tipul de excepție.
Raport de scutire.
Contextul excepției. Informații suplimentare.
Exemplu
Factura 36744
dFd3sda
TRANZACȚIE
CREAT
Casierie 12
{...}
FujIk6
VALIDARE_EXCEPȚIE
Parolă prea slabă
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
DA
DA
DA
DA
DA
DA
DA
DA
NU
NU
NU
NU
RC403
NU
NU
NU
NU
NU
NU
NU
NU
DA
DA
DA
DA
RC406
NU
NU
NU
NU
NU
NU
NU
NU
DA
DA
DA
DA
RC502
NU
NU
NU
NU
NU
NU
NU
NU
DA
DA
DA
DA
Verificați starea sacului
În etapa următoare, veți verifica starea sarcinii la punctul final GET /v1/tasks/{taskID} utilizând o cerere care include:
Variabilă
TaskId
Format
șir
Descriere
ID-ul genții pe care ați primit-o în cadrul etapei anterioare.
Exemplu
dFd3sda
Coduri de retur posibile:
Răspuns
RC200
RC403
Raport
OK - Starea sacului disponibilă
Nu a fost găsit un loc de muncă în cloud pentru terminalul curent.
Raport
Actualizarea statutului sarcinii a fost procesată cu succes.
Ar trebui să verificați TaskID și să retrimiteți valoarea corectă.
Descriere
Dacă nu primiți statutul final (a se vedea mai jos), repetați acest pas.
Verificați dacă ați completat TaskID corect și încercați din nou.
Variabile de răspuns:
Variabilă
titlu
TaskId
creat
TaskClass
statut
inițiator
ID context
sarcina utilă
excepțieId
tip
mesaj
context
Format
șir
șir
șir
șir
șir
șir
șir
șir
șir
șir
șir
Descriere
Un titlu al sarcinii care poate fi citit de către om. Utilizat din valoarea cererii de creare a sarcinii.
ID sac intern
Data și ora la care a fost creat sacul.
Valori posibile: [TRANSACTION, BATCH, DUMMY]
Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Descrierea inițiatorului din partea clientului. Utilizată din valoarea cererii.
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
ID de excepție pseudo-unic. Poate servi ca un „ID de asistență“ pe care utilizatorul îl poate indica asistenței pentru a investiga o problemă potențială.
Tipul de excepție.
Raport de excepție.
Contextul scutirii - informații suplimentare.
Exemplu
Factura 36744
dFd3sda
ÎN_PROGRES
Casierie 12
FujIk6
VALIDARE_EXCEPȚIE
Parolă prea slabă
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
DA
DA
DA
DA
DA
DA
DA
DA
NU
NU
NU
NU
RC404
NU
NU
NU
NU
NU
NU
NU
NU
DA
DA
DA
DA
Solicitarea privind starea sacului trebuie repetată până când obțineți unul dintre codurile finale de răspuns, care sunt:
Statut
INIT_ERROR
COMPLETAT
ANULAT
ERROR
Descriere
Inițierea procesului de plată a eșuat. Verificați eroarea primită.
Odată ce obțineți acest statut, sarcina dvs. a fost finalizată și rezultatul este disponibil.
Sarcina a fost anulată de către utilizator.
A apărut o eroare în timpul procesării sarcinii.
Cum să te comporți
Urmați instrucțiunile pentru eroare.
Puteți continua cu pasul următor.
Ar trebui să începeți o sarcină nouă deoarece această sarcină a fost anulată de utilizator.
Urmați instrucțiunile pentru eroare.
Puteți trece la pasul următor numai dacă răspunsul este în starea COMPLETAT.
Obținerea rezultatului plății
Acum știm că tranzacția a fost autorizată. Scopul acestei etape este de a obține starea și detaliile tranzacției. Pentru noua cerere, veți apela endpoint-ul GET /v1/transactions/{transactionId} utilizând următoarele variabile:
Variabilă
TransactionId
Format
șir
Descriere
ID-ul tranzacției obținut în pașii anteriori.
Exemplu
4414c640-2db7-11ec-910a-91880dadec20
Codurile de răspuns posibile sunt:
Răspuns
RC200
RC404
Raport
OK - detaliile tranzacției furnizate
Nu a fost găsită nicio tranzacție pentru TID-ul curent.
Raport
Răspuns cu succes la solicitarea dumneavoastră.
Această condiție apare atunci când ID-ul tranzacției nu a fost găsit pentru dispozitivul dvs.
Descriere
Tranzacția este completă!
Verificați ID-ul tranzacției.
Răspunsul conține următoarele variabile, în funcție de codul de răspuns:
Variabilă
rezultat
Mesaj de răspuns
transanctionId
tranzacțieOperațiune
Tipul tranzacției
MerchantID
tid
cod valută
sumă
TipAmount
Numărul cardului
cardDataEntry
Număr de referință
invoiceNumber
data
emvAppLabel
Numărul secvenței
excepțieId
tip
mesaj
context
Format
șir
șir
șir
șir
șir
șir
șir
șir
număr
număr
șir
șir
șir
șir
șir
șir
șir
șir
șir
șir
șir
Descriere
Rezultatul tranzacției, valori posibile [ ACCEPTED, DECLINED, CANCELLED ] unde:
ACCEPTAT - tranzacția a fost autorizată cu succes
DECLINED - tranzacția a fost respinsă din anumite motive
CANCELLED - dacă tranzacția este anulată de operator sau de client
ACCEPTAT - tranzacția a fost autorizată cu succes
DECLINED - tranzacția a fost respinsă din anumite motive
CANCELLED - dacă tranzacția este anulată de operator sau de client
O descriere mai detaliată a valorii rezultate.
ID intern al sarcinii
Valori posibile: ""SALE"" ""VOID"" ""REFUND""
Operațiune / tip de tranzacție."
Operațiune / tip de tranzacție."
Valori posibile "CASH" "CARD"
Numai pentru tranzacțiile cu cardul - ID sucursală.
ID-ul tranzacției create de terminal
Codul monedei (ISO 4217)
Valoarea tranzacției cu 2 zecimale (400 CZK).
Valoarea bacșișului introdusă cu 2 zecimale (30 CZK).
Număr de card mascat.
Způsob načtení karty - mag.proužek, čip nebo contactless.
Numărul de referință al tranzacției preluat din sarcina de solicitare Valoarea: originReferenceNum
Data și ora autorizării tranzacției
Marca EMV a cardului preluată din datele cardului
Număr generat pe partea GP
ID de excepție pseudo-unic. Poate servi ca un „ID de asistență“ pe care utilizatorul îl poate indica serviciului de asistență pentru a investiga.
Tip excepție
Raport de excepție
Contextul scutirii - informații suplimentare.
Exemplu
ACCEPTAT
null
4414c640-2db7-11ec-910a-91880dadec20
VOID
CARD
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDARE_EXCEPȚIE
Parolă prea slabă
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC 200
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
NU
NU
NU
NU
RC 404
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
NU
DA
DA
DA
DA
Dacă veți genera sau tipări chitanța pe partea dvs., vă recomandăm să verificați ce câmpuri sunt obligatorii și trebuie să fie tipărite/afișate pe chitanță. O descriere este disponibilă aici.