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
alapértelmezett: false
Ha a beállítás értéke true, akkor a GP tom alkalmazásban először a borravaló megadására szolgáló képernyő jelenik meg.
Ennek a képernyőnek a megjelenítéséhez a borravaló funkciót is engedélyezni kell az alkalmazásban
Ha a beállítás értéke true, akkor a GP tom alkalmazásban először a borravaló megadására szolgáló képernyő jelenik meg.
Ennek a képernyőnek a megjelenítéséhez a borravaló funkciót is engedélyezni kell az alkalmazásban
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
A felhőalapú feladat állapota. Lehetséges értékek: [CREATED, STARTED, INIT_OK, INIT_ERROR, 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, COMPLETED, CANCELLED, ERROR]
TELJESÍTETT
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
A tranzakció eredménye, lehetséges értékek [ ACCEPTED, DECLINED, CANCELLED ] ahol:
ACCEPTED – a tranzakciót sikeresen jóváhagyták
DECLINED – a tranzakciót valamilyen okból elutasították
CANCELLED – ha a tranzakciót a személyzet vagy az ügyfél törölte
ACCEPTED – a tranzakciót sikeresen jóváhagyták
DECLINED – a tranzakciót valamilyen okból elutasították
CANCELLED – ha a tranzakciót a személyzet vagy az ügyfél törölte
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: A tranzakció összege DCC-valutában – az ügyfél kártyájának valutájában. Ezt pontosan úgy kell megjeleníteni, ahogyan az az API-válaszban szerepel, a tizedesjegyek számát is beleértve.
EN: A tranzakció összege DCC-valutában – az ügyfél kártyájának valutájában. Ezt a nyugtán pontosan úgy kell feltüntetni, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
EN: A tranzakció összege DCC-valutában – az ügyfél kártyájának valutájában. Ezt a nyugtán pontosan úgy kell feltüntetni, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
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: Az árfolyamot jelzi. Ez az érték a terminál helyi pénznemében van megadva. Pontosan úgy kell megjeleníteni, ahogyan az API-válaszban szerepel, a tizedesjegyek számát is beleértve.
EN: Az árfolyamot jelzi. Ez az érték a helyi terminál pénznemében van megadva. A nyugtán pontosan úgy kell feltüntetnie, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
EN: Az árfolyamot jelzi. Ez az érték a helyi terminál pénznemében van megadva. A nyugtán pontosan úgy kell feltüntetnie, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
56.35
IGEN
NO
jelölés (DCC)
string
CZ: Az átváltási árfolyamhoz hozzáadott felár. Ezt pontosan úgy kell megjeleníteni, ahogyan az az API-válaszban szerepel, a tizedesjegyek számát is beleértve.
EN: A konverziós arány jelölése. Ezt a nyugtán pontosan úgy kell feltüntetni, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
EN: A konverziós arány jelölése. Ezt a nyugtán pontosan úgy kell feltüntetni, ahogyan az API-válaszban megkapta, a tizedesjegyek pontos megadásával együtt.
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
Ha Ön állítja ki vagy nyomtatja ki a számlát, javasoljuk, hogy ellenőrizze, mely mezők kötelezőek, és azokat feltétlenül fel kell tüntetni a számlán. A leírás itt található.