O tranzacție de vânzare este o operațiune de plată de bază care transferă o anumită sumă din contul bancar al titularului cardului în contul comerciantului.
În ceea ce privește procesul de plată, procedura este următoarea:
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:
Această metodă de autentificare este aceeași pentru toate terminalele.
Obținerea unui jeton de acces
Exemplu de cerere:
POST {{apiCloudHost}}/cloud/oauth/token
Autorizare: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Autorizația și tipul de cont sunt întotdeauna aceleași pentru toți clienții - vă rugăm să utilizați aceleași date ca în exemplu. Trebuie să introduceți ulterior datele unice ale clientului în grant_type).
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 / Schema de securitate
HTTP
Scheme autorizace HTTP / Schema de autorizare 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ă
Format
Descriere
Exemplu
apiKey
OBLIGATORIU
OBLIGATORIU
șir
Cheia API poate fi găsită direct în aplicația GP tom în secțiunea Cont-Cloud API. Aceasta este utilizată pentru a distinge autentificările în principal în Cloud API. Cheia API este unică pentru fiecare companie.
333W212J3
tid
OBLIGATORIU
OBLIGATORIU
șir
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.
483590
inițiator
OBLIGATORIU
OBLIGATORIU
șir
Descrierea inițiatorului trebuie să fie unică pentru fiecare instanță de subsistem care poate iniția o sarcină. Exemplu: „Server XY“ sau „Checkout 1“
Casierie 12
titlu
OBLIGATORIU
OBLIGATORIU
șir
Un titlu al sarcinii care poate fi citit de către om. Acesta trebuie să includă o anumită identificare a sarcinii.
Exemplu: „Factura 37364FD“
Exemplu: „Factura 37364FD“
Factura 36744
printarePaymentApp
boolean
implicit: true
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
sumă
OBLIGATORIU
OBLIGATORIU
număr
Valoarea tranzacției trebuie să fie diferită de zero și să includă zecimale. Pentru o valoare a tranzacției de 50 EUR, introduceți „5000“.
40000
TipAmount
număr
Valoarea bacșișului. Pentru un bacșiș în valoare de 3 EUR, introduceți „300“.
0
tranzacțieOperațiune
OBLIGATORIU
OBLIGATORIU
șir
Tipul tranzacției Task. Pentru tranzacția „Vânzare“, introduceți valoarea „VÂNZARE“.
VÂNZARE
originTransactionId
șir
ID-ul tranzacției care urmează să fie anulată. Nu este nul dacă modul este VOID și anularea este OLDER_TRANSACTION.
NEUTILIZAT
origineNumReferință
șir
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 care identifică plata din partea dvs.
FD123456
anulareMode
șir
Modul de anulare, nu nul, dacă tipul tranzacției este VOID
Valori posibile: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Valori posibile: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NEUTILIZAT
tip de tranzacție*
OBLIGATORIU
OBLIGATORIU
șir
Valori posibile: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
CARD
cod valută
șir
3 caractere monetare (în conformitate cu ISO 4217)
CZK
preferabilReceiptType
șir
Metoda preselectată de trimitere a chitanței: [ EMAIL, PHONE, QR, PRINT ]
EMAIL
e-mail
șir
E-mail client
support@gptom.com
telefon
șir
Numărul de telefon al clientului
+420123456789
TipCollect
boolean
implicit: false
Dacă este setat la true, ecranul de introducere a bacșișului în GP tom va fi apelat primul.
De asemenea, trebuie să aveți activat bacșișul în aplicație pentru a afișa acest ecran
Dacă este setat la true, ecranul de introducere a bacșișului în GP tom va fi apelat primul.
De asemenea, trebuie să aveți activat bacșișul în aplicație pentru a afișa acest ecran
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 [CloudTaskDetailApiResponse]:
Codurile de răspuns posibile sunt:
Răspuns
Raport
Descriere
Cum să te comporți
RC200
OK - Sarcina a fost înregistrată
Sarcina a fost creată cu succes și va fi procesată.
Continuați cu următorul pas din fluxul de tranzacții.
RC401
neautentificat
Dacă autentificarea cu terminalul nu a avut loc.
Efectuați procesul de autentificare (a se vedea pasul de mai sus).
RC403
Utilizatorul nu are permisiunea de a înregistra o sarcină pe terminal
Dacă acreditările API nu corespund 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 este în măsură să proceseze cererea.
Verificați mesajul de eroare.
RC 502
Notificarea push nu a fost trimisă
Notificarea push nu a fost trimisă din cauza unui eșec al serviciului upstream.
Mai jos sunt prezentate variabilele utilizate în răspuns:
Variabilă
Format
Descriere
Exemplu
RC200
RC403
RC406
RC502
titlu
șir
Numele lizibil de către om al sacului. Utilizat din valoarea cererii.
Factura 36744
DA
NU
NU
NU
TaskId
șir
Identitatea internă a genții
dFd3sda
DA
NU
NU
NU
creat
șir
Data și ora la care a fost creat sacul.
DA
NU
NU
NU
TaskClass
șir
Payload classValori posibile: [TRANSACTION, BATCH, VOID]
TRANZACȚIE
DA
NU
NU
NU
statut
șir
Starea sacului cloud. Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREAT
DA
NU
NU
NU
inițiator
șir
Descrierea inițiatorului din partea clientului. Utilizată din valoarea cererii.
Casierie 12
DA
NU
NU
NU
contextId
șir
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
DA
NU
NU
NU
sarcina utilă
obiect
Corpul sarcinii contextuale - în funcție de taskClass
{...}
DA
NU
NU
NU
excepțieId
șir
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.
FujIk6
NU
DA
DA
DA
tip
șir
Tipul de excepție.
VALIDARE_EXCEPȚIE
NU
DA
DA
DA
mesaj
șir
Raport de scutire.
Parolă prea slabă
NU
DA
DA
DA
context
șir
Contextul excepției. Informații suplimentare.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NU
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ă
Format
Descriere
Exemplu
TaskId
șir
ID-ul genții pe care ați primit-o în cadrul etapei anterioare.
dFd3sda
Coduri de retur posibile:
Răspuns
Raport
Raport
Descriere
RC200
OK - Starea sacului disponibilă
Actualizarea statutului sarcinii a fost procesată cu succes.
Dacă nu primiți statutul final (a se vedea mai jos), repetați acest pas.
RC403
Nu a fost găsit un loc de muncă în cloud pentru terminalul curent.
Ar trebui să verificați TaskID și să retrimiteți valoarea corectă.
Verificați dacă ați completat TaskID corect și încercați din nou.
Variabile de răspuns:
Variabilă
Format
Descriere
Exemplu
RC200
RC404
titlu
șir
Un titlu al sarcinii care poate fi citit de către om. Utilizat din valoarea cererii de creare a sarcinii.
Factura 36744
DA
NU
TaskId
șir
ID sac intern
dFd3sda
DA
NU
creat
șir
Data și ora la care a fost creat sacul.
DA
NU
TaskClass
șir
Valori posibile: [TRANSACTION, BATCH, DUMMY]
DA
NU
statut
șir
Valori posibile: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
ÎN_PROGRES
DA
NU
inițiator
șir
Descrierea inițiatorului din partea clientului. Utilizată din valoarea cererii.
Casierie 12
DA
NU
ID context
șir
ID-ul entității țintă afectate, dacă există (transactionId / batchId)
DA
NU
sarcina utilă
DA
NU
excepțieId
șir
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ă.
FujIk6
NU
DA
tip
șir
Tipul de excepție.
VALIDARE_EXCEPȚIE
NU
DA
mesaj
șir
Raport de excepție.
Parolă prea slabă
NU
DA
context
șir
Contextul scutirii - informații suplimentare.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NU
DA
Solicitarea privind starea sacului trebuie repetată până când obțineți unul dintre codurile finale de răspuns, care sunt:
Statut
Descriere
Cum să te comporți
INIT_ERROR
Inițierea procesului de plată a eșuat. Verificați eroarea primită.
Urmați instrucțiunile pentru eroare.
COMPLETAT
Odată ce obțineți acest statut, sarcina dvs. a fost finalizată și rezultatul este disponibil.
Puteți continua cu pasul următor.
ANULAT
Sarcina a fost anulată de către utilizator.
Ar trebui să începeți o sarcină nouă deoarece această sarcină a fost anulată de utilizator.
ERROR
A apărut o eroare în timpul procesării sarcinii.
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ă
Format
Descriere
Exemplu
contextId
șir
ID-ul tranzacției obținut în pașii anteriori.
Codurile de răspuns posibile sunt:
Răspuns
Raport
Raport
Descriere
RC200
OK - detaliile tranzacției furnizate
Răspuns cu succes la solicitarea dumneavoastră.
Tranzacția este completă!
RC404
Nu a fost găsită nicio tranzacție pentru TID-ul curent.
Această condiție apare atunci când ID-ul tranzacției 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
rezultat
șir
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
ACCEPTAT
DA
NU
Mesaj de răspuns
șir
O descriere mai detaliată a valorii rezultate.
“Refuzat de emitent.”
DA
NU
transanctionId
șir
ID intern al sarcinii
DA
NU
tranzacțieOperațiune
șir
Valori posibile: ""SALE"" ""VOID"" ""REFUND""
Operațiune / tip de tranzacție."
Operațiune / tip de tranzacție."
VÂNZARE
DA
NU
Tipul tranzacției
șir
Valori posibile "CASH" "CARD"
CARD
DA
NU
MerchantID
șir
Numai pentru tranzacțiile cu cardul - ID sucursală.
343382001
DA
NU
tid
șir
ID-ul tranzacției create de terminal
483591
DA
NU
cod valută
șir
Codul monedei (ISO 4217)
DA
NU
sumă
număr
Valoarea tranzacției cu 2 zecimale (400 CZK).
400
DA
NU
TipAmount
număr
Valoarea bacșișului introdusă cu 2 zecimale (30 CZK).
3000
DA
NU
MaskedPan
șir
Număr de card mascat.
XXXX XXXX XXXX 1233
DA
NU
cardDataEntry
șir
Metoda de încărcare a cardului - magstripe, cip sau fără contact
FĂRĂ CONTACT
DA
NU
Număr de referință
șir
Numărul de referință al tranzacției preluat din sarcina de solicitare Valoarea: originReferenceNum
FD123456
DA
NU
Numărul chitanței
șir
Numărul chitanței
12
DA
NU
Numărul lotului
șir
Numărul lotului
2
DA
NU
data
șir
Data și ora autorizării tranzacției
09.10.2021 15:34
DA
NU
tip card
șir
Marca EMV a cardului preluată din datele cardului
Mastercard CL
DA
NU
refuzatRezon
șir
Motivul respingerii tranzacției
201
DA
NU
cod de autorizare
șir
Număr generat pe partea GP
10293045
DA
NU
Numărul secvenței
șir
Număr generat pe partea GP
102304128
DA
NU
ajutor
șir
Identifică aplicația EMV utilizată pentru procesarea tranzacției
40100000000
DA
NU
pinMesaj
boolean
Indică dacă a fost introdus un cod PIN
PIN_ENTERED sau NO_PIN
DA
NU
anulatDe
șir
În cazul unei operațiuni de anulare, ID-ul contextului va fi afișat aici
DA
NU
cardHolderVerificationMethod
șir
Numai pentru terminalele Nexgo - indică metoda de verificare a tranzacției
PIN
DA
NU
excepțieId
șir
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.
FujIk6
NU
DA
tip
șir
Tip excepție
VALIDARE_EXCEPȚIE
NU
DA
mesaj
șir
Raport de excepție
Parolă prea slabă
NU
DA
context
șir
Contextul scutirii - informații suplimentare.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NU
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.