O tranzacție de vânzare este o operațiune de plată de bază care prevede transferul unei sume specificate din contul bancar al titularului cardului în contul comerciantului.
În ceea ce privește procesul de plată, procedura este după cum urmează:
Autentificare & Autentificare
Autentificarea simbolului JWT este necesară pentru toate punctele finale non-publice. Obțineți simbolul (cu o durată de viață de 90 de zile) prin punctul final /cloud/oauth/token cu următoarele argumente furnizate:
- Autentificarea de bază pentru punctele finale ale tokenului (nume/parolă) - va fi furnizată pentru fiecare utilizator.
- Numele de utilizator al comerciantului – la fel ca pentru GP tom
- Parola comerciantului – la fel ca pentru GP tom
- ID terminal (TID) – ID terminal de destinație
- Punctul final al autorizării se află la adresa:
Această metodă de autentificare este aceeași pentru toate terminalele.
Obțineți un simbol de acces
Exemplu de solicitare:
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
Exemplu de răspuns:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Reînnoirea tokenului
Când expiră access_tokenu, refresh_token este disponibilă.
Exemplu de solicitare:
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
Crearea unei activități
Apelați punctul final POST /v1/tasks/TRANSACTION și utilizați CreateCloudTaskTransactionApiRequest cu următoarele informații completate pentru a face solicitarea:
Variabil
Format
Descriere
Exemplu
apiKey
OBLIGATORIU
OBLIGATORIU
string
API Cheia poate fi găsită direct în aplicație GP tom în secțiunea Cont-Cloud API . Aceasta este utilizată pentru a distinge autentificările în principal în Cloud API . Pentru fiecare companie, cheia API este unică.
333W212J3
tid
OBLIGATORIU
OBLIGATORIU
string
TID-ul țintă pentru activitate. TID = ID terminal, care este unic pentru fiecare dispozitiv. Un singur DDIL poate fi utilizat la un moment dat pe toate dispozitivele instalate.
483590
initiator
OBLIGATORIU
OBLIGATORIU
string
Descrierea inițiatorului ar trebui să fie unică pentru fiecare instanță a subsistemului care poate iniția o sarcină. Exemplu: "Server XY" sau "Casierie 1"
Casierie 12
title
OBLIGATORIU
OBLIGATORIU
string
Nume de activitate care poate fi citit de om. Acesta ar trebui să conțină o anumită identificare a sarcinii.
Exemplu: "Factură 37364FD"
Exemplu: "Factură 37364FD"
Factură 36744
printByPaymentApp
Boolean
implicit: adevărat
Adevărat dacă chitanța urmează să fie imprimată pe dispozitiv.
Notă: Pentru telefoanele mobile, trebuie să vă asigurați că imprimanta Bluetooth este conectată.
Adevărat dacă chitanța urmează să fie imprimată pe dispozitiv.
Notă: Pentru telefoanele mobile, trebuie să vă asigurați că imprimanta Bluetooth este conectată.
fals
amount
OBLIGATORIU
OBLIGATORIU
număr
Valoarea tranzacției trebuie să fie non-zero și să includă zecimale. Pentru o valoare a tranzacției de 50 EUR, completați valoarea "5000".
40000
tipAmount
număr
Cantitatea de basculare. Pentru o valoare maximă de 3 €, completați valoarea "300".
0
transactionOperation
OBLIGATORIU
OBLIGATORIU
string
Tipul de tranzacție al activității. Pentru tranzacția "Vânzare", completați valoarea "SALE".
SALE
originTransactionId
string
ID-ul tranzacției de anulat. Nu este nul dacă modul VOID și anula sunt OLDER_TRANSACTION.
NEFOLOSIT
originReferenceNum
string
Numărul de referință, de exemplu numărul facturii – adăugați orice valoare de până la 20 de caractere care va fi vizibilă în rapoarte și identificați plata de partea dvs.
FD123456
cancelMode
string
Modul inversare, nu nu este nul dacă tipul de tranzacție este VOID
Valori posibile: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Valori posibile: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NEFOLOSIT
transactionType*
OBLIGATORIU
OBLIGATORIU
string
Valori posibile: [ CASH, CARD, ACCOUNT_PAYMENT ]
CARD
currencyCode
string
3 caractere monetare (conform ISO 4217)
CZK
preferabilReceiptType
string
Metoda de trimitere a chitanțelor preselectate: [ EMAIL, TELEFON, QR, PRINT ]
SMALȚ
smalț
string
E-mailul clientului
support@gptom.com
Telefon
string
Numărul de telefon al clientului
+420123456789
TipCollect
Boolean
implicit: false
Dacă este setat la true, ecranul de introducere a bacșișului din GP tom va fi apelat primul.
Pentru a apela acest ecran, trebuie ca în aplicație să fie activat bacșișul.
Dacă este setat la true, ecranul de introducere a bacșișului din GP tom va fi apelat primul.
Pentru a apela acest ecran, trebuie ca în aplicație să fie activat bacșișul.
timp de viață
Număr întreg
Limita de expirare pentru funcția cloud. Vă este permis să specificați valori cuprinse între 10 și 172800 de secunde.
10
Conținutul răspunsului [CloudTaskDetailApiResponse]:
Codurile de răspuns posibile sunt:
Răspunde
Mesaj
Descriere
Cum să se comporte
RC200
OK - Activitatea a fost înregistrată
Sarcina a fost creată cu succes și va fi procesată.
Treceți la pasul următor din fluxul de tranzacții.
RC401
Nu este tentificat
Dacă nu a existat nici o autenfiticare cu terminalul.
Efectuați procesul de autentificare (consultați pasul de mai sus).
RC403
Utilizatorul nu are voie să înregistreze sarcina pe terminalul dat
Dacă detaliile de conectare API nu se potrivesc cu valoarea TID trimis (de exemplu, dacă proprietarul TID este diferit).
Verificați dacă ați completat TID-ul corect și încercați din nou.
RC406
sarcina nu este acceptabilă pentru terminal
Acest lucru se întâmplă de obicei atunci când TID nu poate procesa solicitarea.
Verificați mesajul de eroare.
RC 502
Notificare push netransmisă
Notificarea push nu a fost trimisă din cauza unei defecțiuni a serviciului în amonte.
Mai jos veți găsi variabilele utilizate în răspuns:
Variabil
Format
Descriere
Exemplu
RC200
RC403
RC406
RC502
title
string
Nume de activitate care poate fi citit de om. Utilizat din valoarea cererii.
Factură 36744
DA
BINE
BINE
BINE
taskId
string
Id activitate internă
dFd3sda
DA
BINE
BINE
BINE
created
string
Data și ora la care a fost creată activitatea.
DA
BINE
BINE
BINE
taskClass
string
Payload classValori posibile: [TRANSACTION, BATCH, VOID]
TRANZACȚIE
DA
BINE
BINE
BINE
status
string
Starea activității în cloud. Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREATED
DA
BINE
BINE
BINE
initiator
string
O descriere a inițiatorului de partea clientului. Utilizat din valoarea cererii.
Casierie 12
DA
BINE
BINE
BINE
contextId
string
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
DA
BINE
BINE
BINE
payload
object
Corpul de activități contextuale - în funcție de taskClass
{...}
DA
BINE
BINE
BINE
exceptionId
string
ID de excepție pseudo-unic. Acesta poate servi ca un "ID de suport" pe care utilizatorul îl poate comunica pentru a sprijini, astfel încât să poată investiga eroarea.
FujIk6
BINE
DA
DA
DA
tip
string
Tipul excepției.
VALIDATION_EXCEPTION
BINE
DA
DA
DA
message
string
Mesaj de excepție.
Parolă prea slabă
BINE
DA
DA
DA
context
string
Contextul excepției. Află mai multe.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
BINE
DA
DA
DA
Verificarea stării unei activități
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Variabil
Format
Descriere
Exemplu
taskId
string
ID-ul activității pe care ați primit-o ca parte a pasului anterior.
dFd3sda
Coduri de returnare posibile:
Răspunde
Mesaj
Mesaj
Descriere
RC200
OK - Stare activitate disponibilă
Actualizarea stării activității a fost procesată cu succes.
Dacă nu primiți starea finală (vedeți mai jos), repetați acest pas.
RC403
Cloud de locuri de muncă nu a fost găsit pentru terminalul curent.
Ar trebui să verificați taskID-ul și să retrimiteți valoarea corectă.
Verificați dacă ați completat id-ul de activitate corect și încercați din nou.
Variabile în răspuns:
Variabil
Format
Descriere
Exemplu
RC200
RC404
title
string
Nume de activitate care poate fi citit de om. Utilizat din valoarea solicitării de creare a activității.
Factură 36744
DA
BINE
taskId
string
ID-ul activității interne
dFd3sda
DA
BINE
created
string
Data și ora la care a fost creată activitatea.
DA
BINE
taskClass
string
Valori posibile: [TRANZACȚIE, LOT, MANECHIN]
DA
BINE
status
string
Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
DA
BINE
initiator
string
O descriere a inițiatorului de partea clientului. Utilizat din valoarea cererii.
Casierie 12
DA
BINE
contextID
string
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
DA
BINE
payload
DA
BINE
exceptionId
string
ID de excepție pseudo-unic. Acesta poate servi ca un "ID de suport" pe care utilizatorul îl poate comunica pentru a sprijini, astfel încât să poată investiga orice problemă.
FujIk6
BINE
DA
tip
string
Tipul excepției.
VALIDATION_EXCEPTION
BINE
DA
message
string
Mesaj de excepție.
Parolă prea slabă
BINE
DA
context
string
Contextul excepției - mai multe informații.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
BINE
DA
Solicitarea de stare a activității trebuie repetată până când obțineți unul dintre codurile de răspuns finale, care sunt:
Stare
Descriere
Cum să se comporte
INIT_ERROR
Procesul de plată nu a reușit să inițializeze. Verificați dacă eroarea pe care ați primit-o.
Urmați instrucțiunile de eroare.
COMPLETED
După ce obțineți această stare, activitatea a fost finalizată și rezultatul este disponibil.
Puteți trece la pasul următor.
CANCELLED
Activitatea a fost anulată de utilizator.
Ar trebui să începeți o nouă activitate, deoarece această activitate a fost anulată de utilizator.
ERROR
A apărut o eroare în timpul procesării lucrării.
Urmați instrucțiunile de eroare.
Puteți trece la pasul următor numai atunci când răspunsul este în starea finalizată.
Obținerea unui rezultat de plată
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é:
Variabil
Format
Descriere
Exemplu
contextId
string
ID-ul tranzacției pe care îl obțineți în pașii anteriori.
Codurile de răspuns posibile sunt:
Răspunde
Mesaj
Mesaj
Descriere
RC200
OK – detaliile tranzacției furnizate
Răspuns cu succes la solicitarea dvs.
Tranzacția este finalizată!
RC404
O tranzacție nu a putut fi găsită pentru TID curent.
Această condiție apare atunci când un anumit ID de tranzacție nu a fost găsit pentru dispozitivul dvs.
Verificați ID-ul tranzacției.
Răspunsul conține următoarele variabile, în funcție de codul de răspuns:
Variabil
Format
Descriere
Exemplu
RC 200
RC 404
result
string
Rezultatul tranzacției, valori posibile [ ACCEPTED, DECLINED, CANCELLED ] în cazul în care:
ACCEPTED - tranzacția a fost autorizată cu succes
DECLINED - tranzacția a fost respinsă din anumite motive
CANCELLED - în cazul în care tranzacția este anulată de către operator sau client
ACCEPTED - tranzacția a fost autorizată cu succes
DECLINED - tranzacția a fost respinsă din anumite motive
CANCELLED - în cazul în care tranzacția este anulată de către operator sau client
ACCEPTATE
DA
BINE
responseMessage
string
O descriere mai detaliată a valorii rezultate.
"Refuzat de emitent."
DA
BINE
transanctionId
string
ID-ul de activitate intern
DA
BINE
transactionOperation
string
Tarife posibile: ""SALE"" "VOID"" "REFUND""
Tipul operațiunii/tranzacției."
Tipul operațiunii/tranzacției."
SALE
DA
BINE
transactionType
string
Valori posibile "CASH" "CARD"
CARD
DA
BINE
merchantID
string
Numai pentru tranzacțiile cu cardul - ID-ul sucursalei.
343382001
DA
BINE
tid
string
ID-ul tranzacției creat de terminal
483591
DA
BINE
currencyCode
string
Codul monedei (ISO 4217)
DA
BINE
amount
număr
Valoarea tranzacției cu 2 zecimale (400 CZK).
400
DA
BINE
tipAmount
număr
Valoarea bacșișului introdus la 2 zecimale (30 CZK).
3000
DA
BINE
maskedPan
string
Numărul cardului mascat.
XXXX XXXX XXXX 1233
DA
BINE
cardDataEntry
string
Metoda de încărcare a cardului - cu bandă magnetică, cu cip sau fără contact
CONTACTLESS
DA
BINE
referenceNumber
string
Numărul de referință al tranzacției preluat din valoarea de activitate a solicitării: originReferenceNum
FD123456
DA
BINE
receiptNumber
string
Numărul chitanței
12
DA
BINE
batchNumber
string
Numărul lotului
2
DA
BINE
date
string
Data și ora autorizării tranzacției
09.10.2021 15:34
DA
BINE
cardType
string
Card de marcă EMV preluat din datele cardului
Mastercard CL
DA
BINE
declinedReason
string
Motivul respingerii tranzacției
201
DA
BINE
authorizationCode
string
Numărul generat pe partea gp
10293045
DA
BINE
sequenceNumber
string
Numărul generat pe partea gp
102304128
DA
BINE
ajutor
string
Identifică aplicația EMV utilizată pentru procesarea tranzacției
40100000000
DA
BINE
pinMessage
Boolean
Indică dacă a avut loc intrarea PIN
Ok
DA
BINE
anulatPe
string
În cazul unei operațiuni de anulare, aici se va afișa ID-ul contextului.
DA
BINE
cardHolderVerificationMethod
string
Numai pentru terminalele Nexgo - indică metoda de verificare a tranzacției
PIN
DA
BINE
exceptionId
string
ID de excepție pseudo-unic. Acesta poate servi ca un "ID de suport" pe care utilizatorul îl poate comunica pentru a sprijini, astfel încât să poată investiga.
FujIk6
BINE
DA
tip
string
Tip de excepție
VALIDATION_EXCEPTION
BINE
DA
message
string
Mesaj de excepție
Parolă prea slabă
BINE
DA
context
string
Contextul excepției - mai multe informații.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
BINE
DA
Dacă aveți de gând să generați sau să imprimați chitanța de partea dvs., vă recomandăm să verificați ce câmpuri sunt necesare și trebuie să fie imprimate / afișate pe chitanță. Descrierea este disponibilă aici.