Prodajna transakcija je osnovna platna operacija koja osigurava prijenos određenog iznosa s bankovnog računa korisnika kartice na račun trgovca.
Što se tiče postupka plaćanja, postupak je sljedeći:
Prijava i autentifikacija
Sve nejavne krajnje točke zahtijevaju autentifikaciju pomoću JWT tokena. Token (s vijekom trajanja od 90 dana) možete dobiti putem krajnje točke /cloud/oauth/token sa sljedećim argumentima:
- Osnovna autentifikacija za krajnje točke tokena (ime/lozinka) – bit će osigurana za svakog korisnika.
- Korisničko ime trgovca – isto kao i za GP tom
- Lozinka trgovca – ista kao i za GP tom
- ID terminala (TID) – ID ciljnog terminala
- Krajnja točka autorizacije nalazi se na:
Ova metoda autentifikacije je ista za sve terminale.
Dobivanje pristupnog tokena
Primjer zahtjeva:
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
Primjer odgovora:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Oporavak tokena
Nakon isteka access_tokena, dostupan je refresh_token.
Primjer zahtjeva:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Vrsta sigurnosne sheme / Security scheme
HTTP
HTTP autorizacijska shema / HTTP authorization scheme
bearer
Izrada zadatka
Pozovite POST krajnju točku /v1/tasks/TRANSACTION i upotrijebite CreateCloudTaskTransactionApiRequest sa sljedećim popunjenim podacima za stvaranje zahtjeva:
Varijabla
Format
Opis
Primjer
apiKey
OBAVEZNO
OBAVEZNO
niz
API ključ možete pronaći izravno u GP tom aplikaciji u odjeljku Account-Cloud API. Koristi se za razlikovanje prijava uglavnom u Cloud API-ju. API ključ je jedinstven za svaku tvrtku.
333W212J3
tid
OBAVEZNO
OBAVEZNO
niz
Ciljani TID za zadatak. TID = ID terminala, koji je jedinstven za svaki uređaj. Samo jedan TID može se koristiti istovremeno na svim instaliranim uređajima.
483590
initiator
OBAVEZNO
OBAVEZNO
niz
Opis inicijatora trebao bi biti jedinstven za svaku instancu podsustava koja može pokrenuti zadatak. Primjer: "poslužitelj XY" ili "Blagajnik 1"
Cash desk 12
title
OBAVEZNO
OBAVEZNO
niz
Naziv zadatka koji ljudi mogu pročitati. Trebao bi sadržavati neku identifikaciju zadatka.
Primjer: "Dostavnica 37364FD"
Primjer: "Dostavnica 37364FD"
Invoice 36744
isprintaj po uplati
boolean
default: true
True, ako račun treba ispisati na uređaju.
Napomena: Za mobilne telefone morate provjeriti je li Bluetooth pisač spojen.
True, ako račun treba ispisati na uređaju.
Napomena: Za mobilne telefone morate provjeriti je li Bluetooth pisač spojen.
false
amount
OBAVEZNO
OBAVEZNO
number
Iznos transakcije mora biti različit od nule i mora sadržavati decimalna mjesta. Za vrijednost transakcije od 50 EUR, unesite vrijednost "5000".
40000
iznos
number
Iznos napojnice. Za vrijednost napojnice od 3 EUR unesite vrijednost "300".
0
transactionOperation
OBAVEZNO
OBAVEZNO
niz
Vrsta transakcije zadatka. Za transakciju "Prodaja" unesite vrijednost "PRODAJA".
SALE
originTransactionId
niz
ID transakcije koju treba otkazati. Nije null ako je način otkazivanja VOID i OLDER_TRANSACTION.
NOT USED
broj izvora
niz
Referentni broj, npr. broj računa – dodajte bilo koju vrijednost do 20 znakova koja će biti vidljiva u izvješćima i identificirati plaćanje s vaše strane.
FD123456
otkažiMod
niz
Način otkazivanja, nije null ako je vrsta transakcije VOID
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NOT USED
transactionType*
OBAVEZNO
OBAVEZNO
niz
Moguće vrijednosti: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
KARTA
kôd valute
niz
3 znaka valute (prema ISO 4217)
CZK
poželjeni tip potvrde o uplati
niz
Unaprijed odabrana metoda slanja računa: [ EMAIL, PHONE, QR, PRINT ]
EMAIL
email
niz
E-pošta kupca
support@gptom.com
phone
niz
Tel. broj kupca
+420123456789
savjetPrikupi
boolean
default: false
Ako je postavljeno na true, prvo će se pozvati zaslon za unos savjeta u GP tom.
Da biste pozvali ovaj zaslon, morate omogućiti i savjete u aplikaciji.
Ako je postavljeno na true, prvo će se pozvati zaslon za unos savjeta u GP tom.
Da biste pozvali ovaj zaslon, morate omogućiti i savjete u aplikaciji.
timeToLive
integer
Vremensko ograničenje isteka zadatka u oblaku. Dopuštene su vrijednosti od 10 do 172800 sekundi.
10
Sadržaj odgovora [CloudTaskDetailApiResponse]:
Mogući kodovi odgovora su:
Odgovor
Poruka
Opis
Što učiniti
RC200
OK - Zadatak je registriran
Zadatak je uspješno kreiran i bit će obrađen.
Nastavite sa sljedećim korakom u tijeku transakcije.
RC401
Neutentifikováno
Ako autentifikacija s terminalom nije dovršena.
Dovršite postupak autentifikacije (vidi gornji korak).
RC403
Korisniku nije dopušteno registrirati posao na danom terminalu.
Ako se vaši API podaci ne podudaraju s poslanom TID vrijednošću (na primjer, kada je vlasnik TID-a drugačiji).
Molimo provjerite jeste li unijeli ispravan TID i pokušajte ponovno.
RC406
Zadatak nije prihvatljiv za zadani terminal.
To se obično događa kada TID ne može obraditi zahtjev.
Provjerite poruku o pogrešci.
RC 502
Push notification nije poslana
Push notification nije poslano zbog kvara uzvodne usluge.
U nastavku možete pronaći varijable korištene u odgovoru:
Varijabla
Format
Opis
Primjer
RC200
RC403
RC406
RC502
title
niz
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva.
Invoice 36744
YES
NO
NO
NO
taskId
niz
Interní id tasku
dFd3sda
YES
NO
NO
NO
created
niz
Datum i vrijeme kada je zadatak kreiran.
YES
NO
NO
NO
taskClass
niz
Klasa korisnog tereta
Moguće vrijednosti: [TRANSACTION, BATCH, VOID]
Moguće vrijednosti: [TRANSACTION, BATCH, VOID]
TRANSACTION
YES
NO
NO
NO
status
niz
Status zadatka u oblaku. Moguće vrijednosti: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
STVORENO
YES
NO
NO
NO
initiator
niz
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
Cash desk 12
YES
NO
NO
NO
contextId
niz
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
YES
NO
NO
NO
payload
object
Tijelo kontekstualnog zadatka - ovisno o taskClass
{...}
YES
NO
NO
NO
exceptionId
niz
Pseudo-jedinstveni ID iznimke. Može poslužiti kao "ID podrške" koji korisnik može dati podršci kako bi istražila pogrešku.
FujIk6
NO
YES
YES
YES
type
niz
Vrsta iznimke.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
niz
Izvješće o iznimci.
Password too weak
NO
YES
YES
YES
context
niz
Kontekst iznimke. Više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
YES
YES
Provjera statusa zadatka
U sljedećem koraku provjerit ćete status zadatka na krajnjoj točki GET /v1/tasks/{taskID} koristeći zahtjev koji uključuje:
Varijabla
Format
Opis
Primjer
taskId
niz
ID zadatka koji ste primili kao dio prethodnog koraka.
dFd3sda
Mogući povratni kodovi:
Odgovor
Poruka
Poruka
Opis
RC200
OK - Dostupan status zadatka
Ažuriranje statusa posla uspješno je obrađeno.
Ako ne dobijete konačni status (vidi dolje), ponovite ovaj korak.
RC403
Zadatak u oblaku nije pronađen za trenutni terminal.
Trebali biste provjeriti svoj ID zadatka i ponovno poslati ispravnu vrijednost.
Molimo provjerite jeste li unijeli ispravan ID zadatka i pokušajte ponovno.
Varijable u odgovoru:
Varijabla
Format
Opis
Primjer
RC200
RC404
title
niz
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva za stvaranje zadatka.
Invoice 36744
YES
NO
taskId
niz
Interní ID tasku
dFd3sda
YES
NO
created
niz
Datum i vrijeme kada je zadatak kreiran.
YES
NO
taskClass
niz
Moguće vrijednosti: [TRANSACTION, BATCH, DUMMY]
YES
NO
status
niz
Moguće vrijednosti: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
YES
NO
initiator
niz
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
Cash desk 12
YES
NO
contextID
niz
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
YES
NO
payload
YES
NO
exceptionId
niz
Pseudo-jedinstveni ID iznimke. Može poslužiti kao "ID podrške" koji korisnik može dati podršci kako bi istražio potencijalni problem.
FujIk6
NO
YES
type
niz
Vrsta iznimke.
VALIDATION_EXCEPTION
NO
YES
message
niz
Poruka o iznimci.
Password too weak
NO
YES
context
niz
Kontekst iznimke - više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Zahtjev za status zadatka treba ponavljati dok se ne dobije jedan od konačnih kodova odgovora, a to su:
Status
Opis
Što učiniti
INIT_ERROR
Proces plaćanja nije mogao biti pokrenut. Molimo provjerite poruku o pogrešci.
Slijedite upute za pogrešku.
Završeno
Kad dosegnete ovu fazu, vaš je zadatak dovršen i rezultat je dostupan.
Můžete pokračovat dalším krokem.
OTKAZANO
Zadatak je otkazao korisnik.
Trebali biste započeti novi zadatak jer je korisnik otkazao ovaj zadatak.
ERROR
Došlo je do pogreške tijekom obrade zadatka.
Slijedite upute za pogrešku.
Možete prijeći na sljedeći korak samo ako je odgovor u statusu COMPLETED.
Dobijte rezultat plaćanja
Sada znamo da je transakcija autorizirana. Cilj ovog koraka je dobiti status transakcije i detalje transakcije. Za novi zahtjev, pozvat ćete GET krajnju točku /v1/transactions/{transactionId}, gdje ćete koristiti sljedeće varijable:
Varijabla
Format
Opis
Primjer
contextId
niz
ID transakcije koji ste dobili u prethodnim koracima.
Mogući kodovi odgovora su:
Odgovor
Poruka
Poruka
Opis
RC200
OK - navedeni detalji transakcije
Uspješan odgovor na vaš zahtjev.
Transakcija je dovršena!
RC404
Za trenutni TID nije pronađena nijedna transakcija.
Ovaj status se javlja kada zadani ID transakcije nije pronađen za vaš uređaj.
Provjerite ID transakcije.
Odgovor sadrži sljedeće varijable ovisno o kodu odgovora:
Varijabla
Format
Opis
Primjer
RC 200
RC 404
rezultat
niz
Rezultat transakcije, moguće vrijednosti [ ACCEPTED, DECLINED, CANCELLED ] gdje je:
ACCEPTED - transakcija je uspješno autorizirana
DECLINED - transakcija je iz nekog razloga odbijena
CANCELLED - ako je transakciju otkazao operater ili korisnik
ACCEPTED - transakcija je uspješno autorizirana
DECLINED - transakcija je iz nekog razloga odbijena
CANCELLED - ako je transakciju otkazao operater ili korisnik
ACCEPTED
YES
NO
responseMessage
niz
Detaljniji opis rezultirajuće vrijednosti.
“Refused by issuer.”
YES
NO
transanctionId
niz
Interní ID úkolu
YES
NO
transactionOperation
niz
Moguće vrijednosti: ""SALE"" ""VOID"" ""REFUND""
Vrsta operacije/transakcije.
Vrsta operacije/transakcije.
SALE
YES
NO
vrsta transakcije
niz
Moguće vrijednosti: "CASH" "CARD"
KARTA
YES
NO
ID trgovca
niz
Samo za transakcije karticama - ID poslovnice.
343382001
YES
NO
tid
niz
ID transakcije koji je kreirao terminal
483591
YES
NO
kôd valute
niz
Kod valute (ISO 4217)
YES
NO
amount
number
Iznos transakcije s 2 decimalna mjesta (400 CZK).
400
YES
NO
iznos
number
Iznos napojnice unesen je na 2 decimale (30 CZK).
3000
YES
NO
maskedPan
niz
Broj maskirane kartice.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
niz
Način očitavanja kartice - magnetska traka, čip ili beskontaktno
CONTACTLESS
YES
NO
broj referencije
niz
Referentni broj transakcije preuzet iz vrijednosti zahtjeva za zadatak: originReferenceNum
FD123456
YES
NO
receiptNumber
niz
Broj računa
12
YES
NO
batchNumber
niz
Broj serije
2
YES
NO
date
niz
Datum i vrijeme autorizacije transakcije
09.10.2021 15:34
YES
NO
cardType
niz
Marka EMV kartice preuzeta iz podataka kartice
Mastercard CL
YES
NO
declinedReason
niz
Razlog odbijanja transakcije
201
YES
NO
kod za autorizaciju
niz
Broj generiran na strani GP-a
10293045
YES
NO
broj sekvence
niz
Broj generiran na strani GP-a
102304128
YES
NO
aid
niz
Identificira EMV aplikaciju koja se koristi za obradu transakcije
40100000000
YES
NO
pinMessage
boolean
Označava je li unesen PIN
PIN_ENTERED nebo NO_PIN
YES
NO
cancelledBy
niz
U slučaju otkazivanja operacije, ovdje će se prikazati contextID
YES
NO
cardHolderVerificationMethod
niz
Samo za Nexgo terminale - označava način provjere transakcije
PIN
YES
NO
exceptionId
niz
Pseudo-jedinstveni ID iznimke. Može poslužiti kao "ID podrške" koji korisnik može dati podršci za istragu.
FujIk6
NO
YES
type
niz
Vrsta iznimke.
VALIDATION_EXCEPTION
NO
YES
message
niz
Poruka o iznimci.
Password too weak
NO
YES
context
niz
Kontekst iznimke - više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
dccData
status (DCC)
niz
HR: Označava DCC status. Ako je "ACCEPTED", transakcija je izvršena putem DCC-a i morate ispuniti potvrdu s DCC podacima. Ako je "NOT_ACCEPTED", tada možete zanemariti DCC podatke.
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)
niz
HR: Iznos transakcije u DCC valuti - u valuti kupčeve kartice. Mora biti prikazan točno onako kako dolazi u API odgovoru, uključujući broj decimalnih mjesta.
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)
niz
HR: Valuta kartice kupca.
EN: Currency of the customer's card.
EN: Currency of the customer's card.
EUR
YES
NO
exchangeRate (DCC)
niz
HR: Označava tečaj. Ova vrijednost je u lokalnoj valuti terminala. Mora se prikazati točno onako kako dolazi u API odgovoru, uključujući broj decimalnih mjesta.
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)
niz
HR: Doplata za tečaj konverzije. Mora biti prikazan točno onako kako dolazi u API odgovoru, uključujući broj decimalnih mjesta.
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)
niz
HR: Označava je li kartica kupca izdana unutar EU ili izvan nje. Ako je vrijednost "0" ili "1", na računu se mora prikazati tekst "Markup". Ako je vrijednost "2", na računu se mora prikazati tekst "Markup preko ECB tečaja".
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
Ako ćete sami generirati ili ispisati račun, preporučujemo da provjerite koja su polja obavezna i moraju se ispisati/prikazati na računu. Opis je dostupan ovdje.