Informacije
Ako pozivate storniranje plaćanja putem Cloud API-ja, potrebno je kreirati zadatak za uređaj (TID) na kojem je plaćanje izvorno izvršeno. Pozivanje storniranja plaćanja izvršenog na terminalu "A" na terminalu "B" trenutno nije podržano.
Otkazivanje transakcije osnovna je platna operacija koja vam omogućuje otkazivanje prethodno obrađene transakcije do 93 dana nakon izvorne transakcije. Otkazivanje transakcije može se izvršiti bez korisničke kartice - sredstva će se automatski vratiti na karticu korištenu za izvornu prodajnu transakciju.
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:
Dobivanje pristupnog tokena
Primjer zahtjeva:
POST {{apiCloudHost}}/cloud/oauth/token
Ovlaštenje: Osnovni YXRvbTphc2hmdWY0ZTVmYQ==
Tip sadržaja: application/x-www-form-urlencoded
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
HTTP autorizacijska shema
HTTP
nositelj
Izrada zadatka
Pozovite POST krajnju točku /v1/tasks/TRANSACTION i upotrijebite CreateCloudTaskTransactionApiRequest sa sljedećim popunjenim podacima za stvaranje zahtjeva:
Varijabla
api ključ
OBAVEZNO
OBAVEZNO
plima
OBAVEZNO
OBAVEZNO
pokretač
OBAVEZNO
OBAVEZNO
naslov
OBAVEZNO
OBAVEZNO
isprintaj po uplati
amount
OBAVEZNO
OBAVEZNO
iznos
transakcijska operacija
ID transakcije podrijetla
broj izvora
otkažiMod
OBAVEZNO
OBAVEZNO
tip transakcije*
OBAVEZNO
OBAVEZNO
kôd valute
vrijeme trajanja
Format
niz
niz
niz
niz
Boolean
broj
broj
niz
niz
niz
niz
niz
niz
cijeli broj
Opis
API ključ možete pronaći izravno u aplikaciji u odjeljku Račun – Cloud API. Koristi se za autentifikaciju prijava, prvenstveno u Cloud API-ju.
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.
Opis inicijatora trebao bi biti jedinstven za svaku instancu podsustava koja može pokrenuti zadatak. Primjer: "poslužitelj XY" ili "Blagajnik 1"
Naziv zadatka koji ljudi mogu pročitati. Trebao bi sadržavati neku identifikaciju zadatka.
Primjer: „Račun 37364FD – uplata“
Primjer: „Račun 37364FD – uplata“
zadana vrijednost: true
True, ako račun treba ispisati na uređaju.
Napomena: Za mobilne telefone, molimo provjerite je li priključen Bluetooth pisač.
True, ako račun treba ispisati na uređaju.
Napomena: Za mobilne telefone, molimo provjerite je li priključen Bluetooth pisač.
Iznos transakcije koji se treba poništiti mora biti pozitivan i uključivati decimalne znamenke.
Ne koristi se za otkazivanja.
Tip transakcije: zadatak. Za transakciju „Otkazivanje transakcije“ unesite „VOID“.
ID transakcije koju treba otkazati. Nije null ako je način otkazivanja VOID i OLDER_TRANSACTION.
Ako ne želite ispisati ovu vrijednost na računu, ostavite je praznom.
Moguće vrijednosti: [ LAST_TRANSACTION, OLDER_TRANSACTION ] gdje:
LAST_TRANSACTION – koristi se samo za prethodno autoriziranu transakciju. Ne smije biti nikakvog drugog zahtjeva između ovog zadatka i prethodnog prodajnog zadatka.
STARJA_TRANZAKCIJA – koristi se za sve starije transakcije osim najnovije.
LAST_TRANSACTION – koristi se samo za prethodno autoriziranu transakciju. Ne smije biti nikakvog drugog zahtjeva između ovog zadatka i prethodnog prodajnog zadatka.
STARJA_TRANZAKCIJA – koristi se za sve starije transakcije osim najnovije.
Moguće vrijednosti: [ GOTOVINA, KARTICA ]
3 znaka za kôd valute (ISO 4217)
Vremensko ograničenje isteka zadatka u oblaku. Dopuštene su vrijednosti od sekundi.
Primjer
333W212J3
483590
Blagajna 12
Otkaz 36744
lažno
40000
Nije korišteno
NIŠTAVNO
FD283737333
NEOBAVEZNO
STARIJA_TRANZAKCIJA
KARTA
CZK
10
Sadržaj odgovora [CloudTaskDetailApiResponse]:
Mogući kodovi odgovora su:
Odgovor
RC200
RC403
RC406
RC 502
Poruka
OK - Zadatak je registriran
Korisniku nije dopušteno registrirati posao na danom terminalu.
Zadatak nije prihvatljiv za zadani terminal.
Push notification nije poslana
Opis
Zadatak je uspješno kreiran i bit će obrađen.
Ako se vaši API podaci ne podudaraju s poslanom TID vrijednošću (na primjer, kada je vlasnik TID-a drugačiji).
To se obično događa kada TID ne može obraditi zahtjev.
Push notification nije poslano zbog kvara uzvodne usluge.
Što učiniti
Nastavite sa sljedećim korakom u tijeku transakcije.
Molimo provjerite jeste li unijeli ispravan TID i pokušajte ponovno.
Provjerite poruku o pogrešci.
U nastavku možete pronaći varijable korištene u odgovoru:
Varijabla
naslov
ID zadatka
stvoreno
razred zadatka
stanje
pokretač
identifikator konteksta
korisni teret
ID iznimke
vrsta
poruka
kontekst
Format
niz
niz
niz
niz
niz
niz
niz
predmet
niz
niz
niz
niz
Opis
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva.
ID interne zadatke
Datum i vrijeme kada je zadatak kreiran.
Klasa korisnog tereta. Moguće vrijednosti: [TRANSACTION, BATCH, DUMMY]
Status zadatka u oblaku. Moguće vrijednosti: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
Tijelo kontekstualnog zadatka - ovisno o taskClass
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.
Vrsta iznimke.
Izvješće o iznimci.
Kontekst iznimke. Više informacija.
Primjer
Račun 36744
dFd3sda
TRANSAKCIJA
STVORENO
Blagajna 12
{...}
FujIk6
IZUZETAK_VALIDACIJE
Lozenka je preslaba
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
DA
DA
DA
DA
DA
DA
DA
DA
Dobro
Dobro
Dobro
Dobro
RC403
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
DA
DA
DA
DA
RC406
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
DA
DA
DA
DA
RC502
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
DA
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
ID zadatka
Format
niz
Opis
ID zadatka koji ste primili kao dio prethodnog koraka.
Primjer
dFd3sda
Mogući povratni kodovi:
Odgovor
RC200
RC403
Poruka
OK - Dostupan status zadatka
Zadatak u oblaku nije pronađen za trenutni terminal.
Poruka
Ažuriranje statusa posla uspješno je obrađeno.
Trebali biste provjeriti svoj ID zadatka i ponovno poslati ispravnu vrijednost.
Opis
Ako ne dobijete konačni status (vidi dolje), ponovite ovaj korak.
Molimo provjerite jeste li unijeli ispravan ID zadatka i pokušajte ponovno.
Varijable u odgovoru:
Varijabla
naslov
ID zadatka
stvoreno
razred zadatka
stanje
pokretač
ID konteksta
korisni teret
ID iznimke
vrsta
poruka
kontekst
Format
niz
niz
niz
niz
niz
niz
niz
niz
niz
niz
niz
Opis
Naziv zadatka koji ljudi mogu pročitati. Koristi se iz vrijednosti zahtjeva za stvaranje zadatka.
ID interne zadatke
Datum i vrijeme kada je zadatak kreiran.
Moguće vrijednosti: [TRANSACTION, BATCH, DUMMY]
Moguće vrijednosti: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Opis inicijatora na strani klijenta. Koristi se iz vrijednosti zahtjeva.
ID pogođenog ciljnog entiteta, ako postoji (transactionId / batchId)
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.
Vrsta iznimke.
Poruka o iznimci.
Kontekst iznimke - više informacija.
Primjer
Račun 36744
dFd3sda
U tijeku
Blagajna 12
FujIk6
IZUZETAK_VALIDACIJE
Lozenka je preslaba
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
DA
DA
DA
DA
DA
DA
DA
DA
Dobro
Dobro
Dobro
Dobro
RC404
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
DA
DA
DA
DA
Zahtjev za status zadatka treba ponavljati dok se ne dobije jedan od konačnih kodova odgovora, a to su:
Status
INIT_ERROR
Završeno
OTKAZANO
ERROR
Opis
Proces plaćanja nije mogao biti pokrenut. Molimo provjerite poruku o pogrešci.
Kad dosegnete ovu fazu, vaš je zadatak dovršen i rezultat je dostupan.
Zadatak je otkazao korisnik.
Došlo je do pogreške tijekom obrade zadatka.
Što učiniti
Slijedite upute za pogrešku.
Možete prijeći na sljedeći korak.
Trebali biste započeti novi zadatak jer je korisnik otkazao ovaj zadatak.
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
identifikator transakcije
Format
niz
Opis
ID transakcije koji ste dobili u prethodnim koracima.
Primjer
4414c640-2db7-11ec-910a-91880dadec20
Mogući kodovi odgovora su:
Odgovor
RC200
RC404
Poruka
OK - navedeni detalji transakcije
Za trenutni TID nije pronađena nijedna transakcija.
Poruka
Uspješan odgovor na vaš zahtjev.
Ovaj status se javlja kada zadani ID transakcije nije pronađen za vaš uređaj.
Opis
Transakcija je dovršena!
Provjerite ID transakcije.
Odgovor sadrži sljedeće varijable ovisno o kodu odgovora:
Varijabla
rezultat
poruka odgovora
identifikator transakcije
transakcijska operacija
vrsta transakcije
ID trgovca
plima
kôd valute
amount
iznos
brojkartice
unosa kartice
broj referencije
brojračuna
date
emvAppLabel
broj sekvence
ID iznimke
vrsta
poruka
kontekst
"dccData": {"status"}
Format
niz
niz
niz
niz
niz
niz
niz
niz
broj
broj
niz
niz
niz
niz
niz
niz
niz
niz
niz
niz
niz
niz
Opis
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
Detaljniji opis rezultirajuće vrijednosti.
ID interne zadatke
Moguće vrijednosti: ""SALE"" ""VOID"" ""REFUND""
Vrsta operacije/transakcije.
Vrsta operacije/transakcije.
Moguće vrijednosti: "CASH" "CARD"
Samo za transakcije karticama - ID poslovnice.
ID transakcije koji je kreirao terminal
Kod valute (ISO 4217)
Iznos transakcije s 2 decimalna mjesta (400 CZK).
Iznos napojnice unesen je na 2 decimale (30 CZK).
Broj maskirane kartice.
Metoda čitanja kartice – magnetska traka, čip ili beskontaktno.
Referentni broj transakcije preuzet iz vrijednosti zahtjeva za zadatak: originReferenceNum
Datum i vrijeme autorizacije transakcije
Marka EMV kartice preuzeta iz podataka kartice
Broj generiran na strani GP-a
Pseudo-jedinstveni ID iznimke. Može poslužiti kao "ID podrške" koji korisnik može dati podršci za istragu.
Vrsta iznimke.
Poruka o iznimci.
Kontekst iznimke - više informacija.
HR: Označava otkazuje li se DCC transakcija.
EN: Pruža informacije o tome je li poništena transakcija obrađena kao DCC
EN: Pruža informacije o tome je li poništena transakcija obrađena kao DCC
Primjer
Prihvaćeno
null
4414c640-2db7-11ec-910a-91880dadec20
NIŠTAVNO
KARTA
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
IZUZETAK_VALIDACIJE
Lozenka je preslaba
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
Ako je ACCEPTED, na računu morate napisati sljedeći tekst:
Ako je PRIHVATENO, morate na svoj račun uključiti sljedeći tekst:
Iznos transakcije, valuta i tečaj isti su kao kod izvorne transakcije.
Konverziju valuta osigurava Global Payments.
Ako je PRIHVATENO, morate na svoj račun uključiti sljedeći tekst:
Iznos transakcije, valuta i tečaj isti su kao kod izvorne transakcije.
Konverziju valuta osigurava Global Payments.
RC 200
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
DA
Dobro
Dobro
Dobro
Dobro
DA
RC 404
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
Dobro
DA
DA
DA
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.