Az értékesítési tranzakció egy olyan alapvető fizetési művelet, amely egy meghatározott összeget utal át a kártyabirtokos bankszámlájáról a kereskedő számlájára.
Ami a fizetési folyamatot illeti, az eljárás a következő:
Bejelentkezés és hitelesítés
Minden nem nyilvános végpont esetében JWT-token hitelesítésre van szükség. A token (90 napos élettartammal) a /cloud/oauth/token végponton keresztül érhető el a következő argumentumok megadásával:
- Alapszintű hitelesítés a token végpontokhoz (név/jelszó) - minden felhasználó számára biztosított.
- Kereskedő felhasználónév - ugyanaz, mint a GP tom esetében
- Kereskedői jelszó - ugyanaz, mint a GP tom esetében
- Terminal ID (TID) - a célterminál azonosítója.
- Az engedélyezési végpont a következő címen található:
Ez a hitelesítési módszer minden terminál esetében azonos.
Hozzáférési token megszerzése
Példa kérés:
POST {{apiCloudHost}}/cloud/oauth/token
Engedélyezés: Alapvető YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Az Authorization és a Contect-Type mindig ugyanaz az összes ügyfél esetében - kérjük, használja ugyanazokat az adatokat, mint a példában. Az egyedi ügyféladatokat utólag kell beillesztenie a grant_type-be).
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Példa válaszra:
{
"access_token": "eyJh...", // hitelesített API-kérésekben használt hozzáférési token
"token_type": "bearer",
"refresh_token": "GciO...",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Egy token megújítása
Amikor a access_token lejár, egy refresh_token áll rendelkezésre.
Példa kérés:
POST {{apiHost}}/api/oauth/token
Engedélyezés: Alapvető YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO...
GPTomAuth
Typ bezpečnostního schématu / Biztonsági rendszer
HTTP
Scheme autorizace HTTP / HTTP engedélyezési séma
hordozó
Táska létrehozása
Hívja meg a /v1/tasks/TRANSACTION POST végpontot, és használja a CreateCloudTaskTransactionApiRequest funkciót a következő információk kitöltésével a kérelem létrehozásához:
Változó
Formátum
Leírás
Példa
apiKey
KÖTELEZŐ
KÖTELEZŐ
string
Az API-kulcs közvetlenül a GP tom alkalmazásban található a Fiók-felhő API szakaszban. Ez elsősorban a Cloud API-ban történő bejelentkezések megkülönböztetésére szolgál. Az API-kulcs minden vállalat esetében egyedi.
333W212J3
tid
KÖTELEZŐ
KÖTELEZŐ
string
A feladat cél-TID-je. TID = terminál azonosító, amely minden eszközön egyedi. Egyszerre csak egy TID használható az összes telepített eszközön.
483590
kezdeményező
KÖTELEZŐ
KÖTELEZŐ
string
A kezdeményező leírásának minden olyan alrendszerpéldány esetében egyedinek kell lennie, amely feladatot kezdeményezhet. Példa: „XY szerver“ vagy „Checkout 1“.“
Pénztár 12
cím
KÖTELEZŐ
KÖTELEZŐ
string
Ember által olvasható feladatcím. Tartalmaznia kell a feladat valamilyen azonosítóját.
Példa: „Számla 37364FD“
Példa: „Számla 37364FD“
36744 számla
printByPaymentApp
boolean
alapértelmezett: true
Igaz, ha a nyugtát ki kell nyomtatni a készülékre.
Megjegyzés: Mobiltelefonok esetében meg kell győződnie arról, hogy a Bluetooth nyomtató csatlakoztatva van.
Igaz, ha a nyugtát ki kell nyomtatni a készülékre.
Megjegyzés: Mobiltelefonok esetében meg kell győződnie arról, hogy a Bluetooth nyomtató csatlakoztatva van.
hamis
összeg
KÖTELEZŐ
KÖTELEZŐ
szám
A tranzakció összege nem lehet nulla és tizedesjegyeket is tartalmazhat. Egy 50 eurós tranzakció értékéhez írja be az „5000“ értéket.
40000
TipAmount
szám
A borravaló összege. A 3 EUR borravaló értékéhez írja be a „300“ értéket.
0
transactionOperation
KÖTELEZŐ
KÖTELEZŐ
string
Feladat tranzakció típusa. Az „Eladás“ tranzakcióhoz adja meg az „ELADÁS“ értéket.
ELADÓ
originTransactionId
string
A törlendő tranzakció azonosítója. Nem null, ha az üzemmód VOID és a törlés OLDER_TRANSACTION.
NEM HASZNÁLTAK
originReferenceNum
string
Hivatkozási szám, pl. számlaszám - adjon meg bármilyen, legfeljebb 20 karakteres értéket, amely látható lesz a jelentésekben, és azonosítja a kifizetést az Ön oldalán.
FD123456
cancelMode
string
Törlési mód, nem null, ha a tranzakció típusa VOID
Lehetséges értékek: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Lehetséges értékek: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NEM HASZNÁLTAK
transactionType*
KÖTELEZŐ
KÖTELEZŐ
string
Lehetséges értékek: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
KÁRTYA
currencyCode
string
3 pénznem karakter (az ISO 4217 szerint)
CZK
preferableReceiptType
string
A nyugta elküldésének előre kiválasztott módja: [ EMAIL, TELEFON, QR, NYOMÁS ]
EMAIL
e-mail
string
Ügyfél e-mail
support@gptom.com
telefon
string
Az ügyfél telefonszáma
+420123456789
Fő fogadásCollect
boolean
default: false
Pokud se nastaví true, tak se nejdříve vyvolá obrazovka zadání spropitného v GP tom.
Pro vyvolání této obrazovky je potřeba mít také aktivované spropitné v aplikaci
Pokud se nastaví true, tak se nejdříve vyvolá obrazovka zadání spropitného v GP tom.
Pro vyvolání této obrazovky je potřeba mít také aktivované spropitné v aplikaci
timeToLive
Egész szám
A felhőfeladat lejárati határideje. Az értékek 10 és 172800 másodperc között adhatók meg.
10
A [CloudTaskDetailApiResponse] tartalma:
A lehetséges válaszkódok a következők:
Válasz
Jelentés
Leírás
Hogyan viselkedjünk
RC200
OK - A feladatot regisztrálták
A feladatot sikeresen létrehoztuk és feldolgozzuk.
Folytassa a tranzakciófolyam következő lépésével.
RC401
Nem hitelesített
Ha a terminállal való automatikus illesztés nem történt meg.
Végezze el a hitelesítési folyamatot (lásd a fenti lépést).
RC403
A felhasználó nem regisztrálhat munkát a terminálon
Ha az API hitelesítő adatai nem egyeznek az elküldött TID-értékkel (például ha a TID tulajdonosa nem azonos).
Ellenőrizze, hogy a helyes TID-et adta-e meg, és próbálja meg újra.
RC406
A feladat nem elfogadható a terminál számára
Ez általában akkor fordul elő, ha a TID nem tudja feldolgozni a kérelmet.
Ellenőrizze a hibaüzenetet.
RC 502
Nem küldött Push-értesítés
A Push-értesítés nem került elküldésre az upstream szolgáltatás hibája miatt.
Az alábbiakban a válaszban használt változókat ismertetjük:
Változó
Formátum
Leírás
Példa
RC200
RC403
RC406
RC502
cím
string
A táska ember által olvasható neve. A kérés értékéből használatos.
36744 számla
IGEN
NO
NO
NO
taskId
string
A táska belső azonosítója
dFd3sda
IGEN
NO
NO
NO
létrehozott
string
A táska létrehozásának dátuma és időpontja.
IGEN
NO
NO
NO
taskClass
string
Payload classLehetséges értékek: [TRANSACTION, BATCH, VOID]
TRANSACTION
IGEN
NO
NO
NO
státusz
string
Felhőzsák státusz. Lehetséges értékek: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
KÉSZÜLT
IGEN
NO
NO
NO
kezdeményező
string
Ügyféloldali kezdeményező leírása. A kérés értékéből használatos.
Pénztár 12
IGEN
NO
NO
NO
contextId
string
Az érintett célszervezet azonosítója, ha van ilyen (transactionId / batchId)
IGEN
NO
NO
NO
hasznos teher
objektum
Kontextusfeladat teste - a taskClass-tól függően
{...}
IGEN
NO
NO
NO
exceptionId
string
Pszeudo-egyedi kivételazonosító. Szolgálhat „támogatási azonosítóként“, amelyet a felhasználó a hiba kivizsgálásához meg tud adni a támogatásnak.
FujIk6
NO
IGEN
IGEN
IGEN
típus
string
Kivétel típusa.
VALIDATION_EXCEPTION
NO
IGEN
IGEN
IGEN
üzenet
string
Mentességi jelentés.
Túl gyenge jelszó
NO
IGEN
IGEN
IGEN
kontextus
string
A kivétel kontextusa. További információk.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
IGEN
IGEN
IGEN
Ellenőrizze a táska állapotát
A következő lépésben a GET /v1/tasks/{taskID} végponton ellenőrizni fogja a feladat állapotát egy olyan kéréssel, amely a következőket tartalmazza:
Változó
Formátum
Leírás
Példa
taskId
string
Az előző lépésben kapott táska azonosítója.
dFd3sda
Lehetséges visszatérési kódok:
Válasz
Jelentés
Jelentés
Leírás
RC200
OK - A zsák állapota elérhető
A feladat állapotfrissítése sikeresen megtörtént.
Ha nem kapja meg a végleges státuszt (lásd alább), ismételje meg ezt a lépést.
RC403
Az aktuális terminálhoz nem találtak felhőmunkát.
Ellenőrizze a taskID-t, és küldje be újra a helyes értéket.
Ellenőrizze, hogy a helyes taskID-t adta-e meg, és próbálja meg újra.
Válaszváltozók:
Változó
Formátum
Leírás
Példa
RC200
RC404
cím
string
Ember által olvasható feladatcím. A feladat létrehozására irányuló kérelem értékéből használatos.
36744 számla
IGEN
NO
taskId
string
Belső táska azonosító
dFd3sda
IGEN
NO
létrehozott
string
A táska létrehozásának dátuma és időpontja.
IGEN
NO
taskClass
string
Lehetséges értékek: [TRANSACTION, BATCH, DUMMY]
IGEN
NO
státusz
string
Lehetséges értékek: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
IGEN
NO
kezdeményező
string
Ügyféloldali kezdeményező leírása. A kérés értékéből használatos.
Pénztár 12
IGEN
NO
contextID
string
Az érintett célszervezet azonosítója, ha van ilyen (transactionId / batchId)
IGEN
NO
hasznos teher
IGEN
NO
exceptionId
string
Pszeudo-egyedi kivételazonosító. Szolgálhat „támogatási azonosítóként“, amelyet a felhasználó meg tud mondani a támogatásnak a lehetséges probléma kivizsgálásához.
FujIk6
NO
IGEN
típus
string
Kivétel típusa.
VALIDATION_EXCEPTION
NO
IGEN
üzenet
string
Kivételes jelentés.
Túl gyenge jelszó
NO
IGEN
kontextus
string
Mentességi kontextus - további információk.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
IGEN
A zsák állapotára vonatkozó kérést addig kell ismételni, amíg meg nem kapjuk a végső válaszkódok egyikét, amelyek a következők:
Állapot
Leírás
Hogyan viselkedjünk
INIT_ERROR
A fizetési folyamat kezdeményezése sikertelen volt. Ellenőrizze a kapott hibát.
Kövesse a hibára vonatkozó utasításokat.
TELJESÍTETT
Amint megkapja ezt az állapotot, a feladatot elvégezte, és az eredmény elérhető.
Folytathatja a következő lépéssel.
ELMARADÓ
A feladatot a felhasználó törölte.
Új feladatot kell indítania, mert ezt a feladatot a felhasználó törölte.
HIBA
A feladat feldolgozása során hiba történt.
Kövesse a hibára vonatkozó utasításokat.
Csak akkor léphet tovább a következő lépésre, ha a válasz KÉSZ állapotú.
A fizetési eredmény elérése
Most már tudjuk, hogy a tranzakciót engedélyezték. Ennek a lépésnek az a célja, hogy megkapjuk a tranzakció státuszát és részleteit. Az új kéréshez a /v1/transactions/{transactionId} GET végpontot hívja meg a következő változókkal:
Változó
Formátum
Leírás
Példa
contextId
string
Az előző lépések során kapott tranzakcióazonosító.
A lehetséges válaszkódok a következők:
Válasz
Jelentés
Jelentés
Leírás
RC200
OK - tranzakció adatai megadva
Sikeres válasz a kérésére.
A tranzakció befejeződött!
RC404
Az aktuális TID-hez nem találtak tranzakciót.
Ez a feltétel akkor lép fel, ha a tranzakcióazonosító nem található az Ön készülékéhez.
Ellenőrizze a tranzakció azonosítóját.
A válasz a válaszkódtól függően a következő változókat tartalmazza:
Változó
Formátum
Leírás
Példa
RC 200
RC 404
eredmény
string
Výsledek transakce, možné hodnoty [ ACCEPTED, DECLINED, CANCELLED ] kde:
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
ELFOGADVA
IGEN
NO
responseMessage
string
A kapott érték részletesebb leírása.
“A kibocsátó elutasította.”
IGEN
NO
transanctionId
string
Belső feladat azonosítója
IGEN
NO
transactionOperation
string
Lehetséges értékek: ""ELADÓ"" ""érvénytelen"" ""VISSZAFIZETÉS""
Művelet / tranzakció típusa."
Művelet / tranzakció típusa."
ELADÓ
IGEN
NO
transactionType
string
Lehetséges értékek "KÉSZPÉNZ" "KÁRTYA"
KÁRTYA
IGEN
NO
merchantID
string
Csak kártyás tranzakciók esetén - Fióktelep azonosító.
343382001
IGEN
NO
tid
string
A terminál által létrehozott tranzakció azonosítója
483591
IGEN
NO
currencyCode
string
Valutakód (ISO 4217)
IGEN
NO
összeg
szám
Tranzakció összege 2 tizedesjegy pontossággal (400 CZK).
400
IGEN
NO
TipAmount
szám
A borravaló összege 2 tizedesjegy pontossággal (30 CZK).
3000
IGEN
NO
maskedPan
string
Maszkolt kártyaszám.
XXXX XXXX XXXX XXXX 1233
IGEN
NO
cardDataEntry
string
A kártya feltöltésének módja - magisztrális csík, chip vagy érintésmentes kártya
CONTACTLESS
IGEN
NO
referenceNumber
string
A tranzakció hivatkozási száma a kérési feladat értékéből: originReferenceNum
FD123456
IGEN
NO
receiptNumber
string
A nyugta száma
12
IGEN
NO
batchNumber
string
Tételszám
2
IGEN
NO
dátum
string
A tranzakció engedélyezésének dátuma és időpontja
09.10.2021 15:34
IGEN
NO
cardType
string
A kártya EMV márkája a kártya adataiból
Mastercard CL
IGEN
NO
declinedReason
string
A tranzakció elutasításának oka
201
IGEN
NO
authorizationCode
string
A GP oldalán generált szám
10293045
IGEN
NO
sequenceNumber
string
A GP oldalán generált szám
102304128
IGEN
NO
támogatás
string
Azonosítja a tranzakció feldolgozásához használt EMV-alkalmazást.
40100000000
IGEN
NO
pinMessage
boolean
Jelzi, hogy megtörtént-e a PIN-kód megadása
PIN_ENTERED vagy NO_PIN
IGEN
NO
cancelledBy
string
Törlési művelet esetén a contextID itt jelenik meg.
IGEN
NO
cardHolderVerificationMethod
string
Csak Nexgo terminálok esetében - a tranzakció ellenőrzésének módját jelzi.
PIN-KÓD
IGEN
NO
exceptionId
string
Pszeudo-egyedi kivételazonosító. Szolgálhat „támogatási azonosítóként“, amelyet a felhasználó megmondhatja a támogatásnak, hogy vizsgálja ki.
FujIk6
NO
IGEN
típus
string
Kivétel típusa
VALIDATION_EXCEPTION
NO
IGEN
üzenet
string
Kivételes jelentés
Túl gyenge jelszó
NO
IGEN
kontextus
string
Mentességi kontextus - további információk.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
IGEN
dccData
állapot (DCC)
string
CZ: A DCC állapotát jelzi. Ha "ELFOGADVA", a tranzakció DCC-n keresztül történt, és a bizonylatot ki kell tölteni a DCC-adatokkal. Ha "NOT_ACCEPTED", akkor figyelmen kívül hagyhatja a DCC-adatokat.
HU: A DCC állapotát jelzi. Ha "ELFOGADVA", a tranzakció DCC-n keresztül történt, és a nyugtát ki kell töltenie a DCC-adatokkal. Ha "NOT_ACCEPTED", akkor figyelmen kívül hagyhatja a DCC-adatokat.
HU: A DCC állapotát jelzi. Ha "ELFOGADVA", a tranzakció DCC-n keresztül történt, és a nyugtát ki kell töltenie a DCC-adatokkal. Ha "NOT_ACCEPTED", akkor figyelmen kívül hagyhatja a DCC-adatokat.
ELFOGADVA
NOT_ACCEPTED
NOT_ACCEPTED
IGEN
NO
összeg (DCC)
string
CZ: Částka transakce v DCC měně - v měně karty zákazníka. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst.
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
IGEN
NO
currencyCode (DCC)
string
CZ: Ügyfélkártya pénzneme.
HU: Az ügyfélkártya pénzneme.
HU: Az ügyfélkártya pénzneme.
EUR
IGEN
NO
exchangeRate (DCC)
string
CZ: Udává směnný kurz. Tato hodnota je v lokální měně terminálu. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst.
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
IGEN
NO
jelölés (DCC)
string
CZ: Přirážka ke konverznímu kurzu. Je potřeba ji zobrazit přesně tak jak přijde v API odpovědi včetně počtu desetinných míst.
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
IGEN
NO
regionSchemaIndicator (DCC)
string
CZ: Jelzi, hogy az ügyfél kártyáját az EU-n belül vagy kívül bocsátották-e ki. Ha az érték "0" vagy "1", akkor a "Markup" szöveget kell megjeleníteni a nyugtán. Ha az érték "2", akkor a "Markup over ECB rate" (EKB-kamatláb felár) szöveget kell feltüntetni a nyugtán.
HU: Jelzi, hogy az ügyfél kártyáját az EU-n belül vagy kívül bocsátották-e ki. Ha az érték "0" vagy "1", akkor a "Markup" szöveget kell feltüntetni a bizonylaton. Ha az érték "2", akkor a "Markup over ECB rate" szöveget kell feltüntetni a bizonylaton.
HU: Jelzi, hogy az ügyfél kártyáját az EU-n belül vagy kívül bocsátották-e ki. Ha az érték "0" vagy "1", akkor a "Markup" szöveget kell feltüntetni a bizonylaton. Ha az érték "2", akkor a "Markup over ECB rate" szöveget kell feltüntetni a bizonylaton.
0
1
2
1
2
IGEN
NO
Pokud budete účtenku generovat nebo tisknout na své straně, doporučujeme zkontrolovat, která pole jsou povinná a musí být vytištěna/zobrazena na účtence. Popis je k dispozici zde.