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
Ovlaštenje: Osnovni YXRvbTphc2hmdWY0ZTVmYQ==
Tip sadržaja: application/x-www-form-urlencoded
(Autorizacija i tip sadržaja uvijek su isti za sve korisnike – molimo upotrijebite iste podatke kao u primjeru. Zatim ćete morati unijeti jedinstvene podatke klijenta u polje 'grant_type'.).
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Primjer odgovora:
{
"access_token": "eyJh…", // pristupni token koji se koristi u provjerenim API zahtjevima
"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
Ovlaštenje: Osnovni YXRvbTphc2hmdWY0ZTVmYQ==
Tip sadržaja: 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
nositelj
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
api ključ
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
plima
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
pokretač
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"
Blagajna 12
naslov
OBAVEZNO
OBAVEZNO
niz
Naziv zadatka koji ljudi mogu pročitati. Trebao bi sadržavati neku identifikaciju zadatka.
Primjer: "Dostavnica 37364FD"
Primjer: "Dostavnica 37364FD"
Račun 36744
isprintaj po uplati
Boolean
podrazumijevano: istinito
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.
lažno
amount
OBAVEZNO
OBAVEZNO
broj
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
broj
Iznos napojnice. Za vrijednost napojnice od 3 EUR unesite vrijednost "300".
0
transakcijska operacija
OBAVEZNO
OBAVEZNO
niz
Vrsta transakcije zadatka. Za transakciju "Prodaja" unesite vrijednost "PRODAJA".
RASPRODAJA
ID transakcije podrijetla
niz
ID transakcije koju treba otkazati. Nije null ako je način otkazivanja VOID i OLDER_TRANSACTION.
Nije korišteno
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
Moguće vrijednosti: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Moguće vrijednosti: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Nije korišteno
tip transakcije*
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 ]
E-pošta
e-pošta
niz
E-pošta kupca
support@gptom.com
telefon
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.
vrijeme trajanja
cijeli broj
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
Neidentificirano
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
naslov
niz
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva.
Račun 36744
DA
Dobro
Dobro
Dobro
ID zadatka
niz
ID interne zadatke
dFd3sda
DA
Dobro
Dobro
Dobro
stvoreno
niz
Datum i vrijeme kada je zadatak kreiran.
DA
Dobro
Dobro
Dobro
razred zadatka
niz
Klasa korisnog tereta
Moguće vrijednosti: [TRANSACTION, BATCH, VOID]
Moguće vrijednosti: [TRANSACTION, BATCH, VOID]
TRANSAKCIJA
DA
Dobro
Dobro
Dobro
stanje
niz
Status oblačne zadatke. Moguće vrijednosti: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR]
STVORENO
DA
Dobro
Dobro
Dobro
pokretač
niz
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
Blagajna 12
DA
Dobro
Dobro
Dobro
identifikator konteksta
niz
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
DA
Dobro
Dobro
Dobro
korisni teret
predmet
Tijelo kontekstualnog zadatka - ovisno o taskClass
{...}
DA
Dobro
Dobro
Dobro
ID iznimke
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
Dobro
DA
DA
DA
vrsta
niz
Vrsta iznimke.
IZUZETAK_VALIDACIJE
Dobro
DA
DA
DA
poruka
niz
Izvješće o iznimci.
Lozenka je preslaba
Dobro
DA
DA
DA
kontekst
niz
Kontekst iznimke. Više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
Dobro
DA
DA
DA
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
ID zadatka
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
naslov
niz
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva za stvaranje zadatka.
Račun 36744
DA
Dobro
ID zadatka
niz
ID interne zadatke
dFd3sda
DA
Dobro
stvoreno
niz
Datum i vrijeme kada je zadatak kreiran.
DA
Dobro
razred zadatka
niz
Moguće vrijednosti: [TRANSACTION, BATCH, DUMMY]
DA
Dobro
stanje
niz
Moguće vrijednosti: [STVORENO, POČETNO, INICIJALIZACIJA_U_REDU, INICIJALIZACIJA_GREŠKA, ZAVRŠENO, OTKAZANO, GREŠKA]
Završeno
DA
Dobro
pokretač
niz
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
Blagajna 12
DA
Dobro
ID konteksta
niz
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
DA
Dobro
korisni teret
DA
Dobro
ID iznimke
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
Dobro
DA
vrsta
niz
Vrsta iznimke.
IZUZETAK_VALIDACIJE
Dobro
DA
poruka
niz
Poruka o iznimci.
Lozenka je preslaba
Dobro
DA
kontekst
niz
Kontekst iznimke - više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
Dobro
DA
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.
Možete prijeći na sljedeći korak.
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
identifikator konteksta
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
Prihvaćeno
DA
Dobro
poruka odgovora
niz
Detaljniji opis rezultirajuće vrijednosti.
“Odbio izdavatelj.”
DA
Dobro
identifikator transakcije
niz
ID interne zadatke
DA
Dobro
transakcijska operacija
niz
Moguće vrijednosti: ""SALE"" ""VOID"" ""REFUND""
Vrsta operacije/transakcije.
Vrsta operacije/transakcije.
RASPRODAJA
DA
Dobro
vrsta transakcije
niz
Moguće vrijednosti: "CASH" "CARD"
KARTA
DA
Dobro
ID trgovca
niz
Samo za transakcije karticama - ID poslovnice.
343382001
DA
Dobro
plima
niz
ID transakcije koji je kreirao terminal
483591
DA
Dobro
kôd valute
niz
Kod valute (ISO 4217)
DA
Dobro
amount
broj
Iznos transakcije s 2 decimalna mjesta (400 CZK).
400
DA
Dobro
iznos
broj
Iznos napojnice unesen je na 2 decimale (30 CZK).
3000
DA
Dobro
maskiraniPan
niz
Broj maskirane kartice.
XXXX XXXX XXXX 1233
DA
Dobro
unosa kartice
niz
Način očitavanja kartice - magnetska traka, čip ili beskontaktno
CONTACTLESS
DA
Dobro
broj referencije
niz
Referentni broj transakcije preuzet iz vrijednosti zahtjeva za zadatak: originReferenceNum
FD123456
DA
Dobro
broj-potvrde
niz
Broj računa
12
DA
Dobro
batchNumber
niz
Broj serije
2
DA
Dobro
date
niz
Datum i vrijeme autorizacije transakcije
09.10.2021 15:34
DA
Dobro
vrsta kartice
niz
Marka EMV kartice preuzeta iz podataka kartice
Mastercard CL
DA
Dobro
razlog odbijanja
niz
Razlog odbijanja transakcije
201
DA
Dobro
kod za autorizaciju
niz
Broj generiran na strani GP-a
10293045
DA
Dobro
broj sekvence
niz
Broj generiran na strani GP-a
102304128
DA
Dobro
pomoć
niz
Identificira EMV aplikaciju koja se koristi za obradu transakcije
40100000000
DA
Dobro
Prikaži poruku
Boolean
Označava je li unesen PIN
PIN_ENTERED ili NO_PIN
DA
Dobro
otkazano od
niz
U slučaju otkazivanja operacije, ovdje će se prikazati contextID
DA
Dobro
Metoda provjere vlasnika kartice
niz
Samo za Nexgo terminale - označava način provjere transakcije
PIN
DA
Dobro
ID iznimke
niz
Pseudo-jedinstveni ID iznimke. Može poslužiti kao "ID podrške" koji korisnik može dati podršci za istragu.
FujIk6
Dobro
DA
vrsta
niz
Vrsta iznimke.
IZUZETAK_VALIDACIJE
Dobro
DA
poruka
niz
Poruka o iznimci.
Lozenka je preslaba
Dobro
DA
kontekst
niz
Kontekst iznimke - više informacija.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
Dobro
DA
dccPodaci
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: Označava status DCC-a. Ako je "ACCEPTED", transakcija je obrađena putem DCC-a i morate unijeti detalje DCC-a na računu. Ako je "NOT_ACCEPTED", detalje DCC-a možete zanemariti.
EN: Označava status DCC-a. Ako je "ACCEPTED", transakcija je obrađena putem DCC-a i morate unijeti detalje DCC-a na računu. Ako je "NOT_ACCEPTED", detalje DCC-a možete zanemariti.
Prihvaćeno
NIJE PRIHVATLJIVO
NIJE PRIHVATLJIVO
DA
Dobro
iznos (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: Iznos transakcije u DCC valuti – u valuti kartice kupca. To morate prikazati na računu točno onako kako ste ga primili putem API odgovora, uključujući ispravan broj decimalnih mjesta.
EN: Iznos transakcije u DCC valuti – u valuti kartice kupca. To morate prikazati na računu točno onako kako ste ga primili putem API odgovora, uključujući ispravan broj decimalnih mjesta.
2.31
DA
Dobro
kodValute (DCC)
niz
HR: Valuta kartice kupca.
EN: Valuta kartice kupca.
EN: Valuta kartice kupca.
EUR
DA
Dobro
tečaj (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: Označava tečaj. Ova vrijednost je u lokalnoj valuti terminala. Morate je prikazati na računu točno onako kako ste je dobili u API odgovoru, uključujući ispravan broj decimalnih mjesta.
EN: Označava tečaj. Ova vrijednost je u lokalnoj valuti terminala. Morate je prikazati na računu točno onako kako ste je dobili u API odgovoru, uključujući ispravan broj decimalnih mjesta.
56.35
DA
Dobro
pristavka (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: Marža za stopu konverzije. Morate je prikazati na svom računu točno onako kako ste je dobili u odgovoru API-ja, uključujući ispravan broj decimalnih mjesta.
EN: Marža za stopu konverzije. Morate je prikazati na svom računu točno onako kako ste je dobili u odgovoru API-ja, uključujući ispravan broj decimalnih mjesta.
3.20
DA
Dobro
regijskiSchemaPokazatelj (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: Pokazuje je li kartica kupca izdana unutar EU ili izvan nje. Ako je vrijednost "0" ili "1", na računu se mora prikazati tekst "Dodatna marža". Ako je vrijednost "2", na računu se mora prikazati tekst "Marža iznad stope ECB-a".
EN: Pokazuje je li kartica kupca izdana unutar EU ili izvan nje. Ako je vrijednost "0" ili "1", na računu se mora prikazati tekst "Dodatna marža". Ako je vrijednost "2", na računu se mora prikazati tekst "Marža iznad stope ECB-a".
0
1
2
1
2
DA
Dobro
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.