Eine Verkaufstransaktion ist ein grundlegender Zahlungsvorgang, der die Überweisung eines bestimmten Betrags vom Bankkonto des Karteninhabers auf das Konto des Händlers vorsieht.
Was den Zahlungsvorgang betrifft, so ist das Verfahren wie folgt:
Login & Authentifizierung
Die JWT-Tokenauthentifizierung ist für alle nicht öffentlichen Endpunkte erforderlich. Sie erhalten das Token (mit einer Lebensdauer von 90 Tagen) über den Endpunkt /cloud/oauth/token mit den folgenden Argumenten:
- Standardauthentifizierung für Token-Endpunkte (Name/Passwort) - wird für jeden Benutzer bereitgestellt.
- Händler-Benutzername – wie für GP tom
- Händlerpasswort – wie für GP tom
- Terminal ID (TID) – Zielterminal-ID
- Der Autorisierungsendpunkt befindet sich unter:
- Entwicklung: https://cloud-api-dev.gptom.com/cloud/oauth/token
- Produktion: https://cloud-api.gptom.com/cloud/oauth/token
Diese Authentifizierungsmethode ist für alle Terminals gleich.
Abrufen eines Zugriffstokens
Beispielanfrage:
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
Beispielantwort:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Token-Verlängerung
Wenn die access_tokenu abläuft, ist refresh_token verfügbar.
Beispielanfrage:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ bezpečnostního schématu / Security scheme
HTTP
Schéma autorizace HTTP / HTTP authorization scheme
bearer
Erstellen einer Aufgabe
Rufen Sie den POST-Endpunkt /v1/tasks/TRANSACTION auf, und verwenden Sie CreateCloudTaskTransactionApiRequest mit den folgenden Informationen, um die Anforderung zu stellen:
Variable
Format
Beschreibung
Beispiel
apiKey
MANDATORY
MANDATORY
string
API Schlüssel kann direkt in der App gefunden werden GP tom im Bereich Konto -Cloud API . Er wird zur Unterscheidung von Anmeldungen hauptsächlich in Cloud API verwendet. Der Schlüssel API ist für jedes Unternehmen eindeutig.
333W212J3
Tid
OBLIGATORISCH
OBLIGATORISCH
string
Die Ziel-TID für die Aufgabe. TID = Terminal ID, die für jedes Gerät eindeutig ist. Auf allen installierten Geräten kann jeweils nur eine TID verwendet werden.
483590
initiator
OBLIGATORISCH
OBLIGATORISCH
string
Die Initiatorbeschreibung sollte für jede Instanz des Subsystems, die eine Aufgabe initiieren kann, eindeutig sein. Beispiel: "Server XY" oder "Kasse 1"
Kasse 12
title
OBLIGATORISCH
OBLIGATORISCH
string
Vom Menschen lesbarer Aufgabenname. Es sollte eine gewisse Identifizierung der Aufgabe enthalten.
Beispiel: "Rechnung 37364FD"
Beispiel: "Rechnung 37364FD"
Rechnung 36744
printByPaymentApp
boolean
Standardwert: true
True, wenn die Quittung auf das Gerät gedruckt werden soll.
Hinweis: Bei Mobiltelefonen müssen Sie sicherstellen, dass der Bluetooth-Drucker angeschlossen ist.
True, wenn die Quittung auf das Gerät gedruckt werden soll.
Hinweis: Bei Mobiltelefonen müssen Sie sicherstellen, dass der Bluetooth-Drucker angeschlossen ist.
FALSE
amount
OBLIGATORISCH
OBLIGATORISCH
number
Der Transaktionsbetrag muss ungleich Null sein und Dezimalstellen enthalten. Bei einem Transaktionswert von 50 EUR geben Sie den Wert "5000" ein.
40000
tipAmount
number
Höhe des Trinkgeldes. Für einen Trinkgeldwert von 3 € geben Sie den Wert "300" ein.
0
transactionOperation
MANDATORY
MANDATORY
string
Die Vorgangsart der Aufgabe. Geben Sie für die Transaktion "Sale" den Wert "SALE" ein.
AUSVERKAUF
originTransactionId
string
Die ID der abzubrechenden Transaktion. Nicht null, wenn der VOID-Modus und der Abbruch OLDER_TRANSACTION sind.
NICHT VERWENDET
originReferenceNum
string
Referenznummer, z. B. Rechnungsnummer – fügen Sie einen beliebigen Wert bis zu 20 Zeichen hinzu, der in den Berichten sichtbar ist, und identifizieren Sie die Zahlung auf Ihrer Seite.
FD-123456
cancelMode
string
Umkehrmodus, nicht null, wenn der Transaktionstyp VOID ist
Mögliche Werte: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Mögliche Werte: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NICHT VERWENDET
transactionType*
OBLIGATORISCH
OBLIGATORISCH
string
Mögliche Werte: [ BARGELD, KARTE, GO_CRYPTO ]
CARD
currencyCode
string
3 Währungszeichen (nach ISO 4217)
CZK
preferableReceiptType
string
Vorausgewählte Quittungsversandmethode: [ E-Mail, TELEFON, QR, DRUCKEN ]
E-MAIL
E-Mail
string
E-Mail Kunde
support@gptom.com
Telefon
string
Telefonnummer des Kunden
+420123456789
TipCollect
boolean
default: false
Wenn diese Option auf true gesetzt ist, wird der Trinkgeld-Eingabebildschirm zuerst in GP tom.
Um diesen Bildschirm aufzurufen, müssen Sie in der App auch die Trinkgelderfassung aktiviert haben
Wenn diese Option auf true gesetzt ist, wird der Trinkgeld-Eingabebildschirm zuerst in GP tom.
Um diesen Bildschirm aufzurufen, müssen Sie in der App auch die Trinkgelderfassung aktiviert haben
timeToLive
ganze Zahl
Das Ablauflimit für den Cloud-Auftrag. Sie können Werte zwischen 10 und 172800 Sekunden angeben.
10
Inhalt der Antwort [CloudTaskDetailApiResponse]:
Mögliche Antwortcodes sind:
Antwort
Nachricht
Beschreibung
Wie man sich verhält
RC200
OK - Aufgabe wurde registriert
Die Aufgabe wurde erfolgreich erstellt und wird verarbeitet.
Fahren Sie mit dem nächsten Schritt im Transaktionsfluss fort.
RC401
Nicht tentifiziert
Wenn es keine Authentifizierung mit dem Terminal gab.
Führen Sie den Authentifizierungsprozess durch (siehe Schritt oben).
RC 403
Der Benutzer darf die Aufgabe nicht auf dem angegebenen Terminal registrieren
Wenn Ihre Login-Daten API stimmen nicht mit dem gesendeten TID-Wert überein (z. B. wenn der TID-Besitzer unterschiedlich ist).
Überprüfen Sie, ob Sie die richtige TID eingegeben haben, und versuchen Sie es erneut.
RC 406
Die Aufgabe ist für das Terminal nicht akzeptabel
Dies geschieht normalerweise, wenn die TID die Anforderung nicht verarbeiten kann.
Überprüfen Sie die Fehlermeldung.
RC 502
Push-Benachrichtigung nicht gesendet
Die Pushbenachrichtigung wurde aufgrund eines Upstreamdienstfehlers nicht gesendet.
Im Folgenden finden Sie die in der Antwort verwendeten Variablen:
Variable
Format
Beschreibung
Beispiel
RC200
RC 403
RC 406
RC-502
title
string
Vom Menschen lesbarer Aufgabenname. Wird aus dem Anforderungswert verwendet.
Rechnung 36744
YES
NO
NO
NO
taskId
string
Interne Aufgaben-ID
dFd3sda
YES
NO
NO
NO
created
string
Das Datum und die Uhrzeit der Erstellung der Aufgabe.
YES
NO
NO
NO
taskClass
string
NutzlastklasseMopworthy-Werte: [TRANSACTION, BATCH, DUMMY]
TRANSAKTION
YES
NO
NO
NO
Status
string
Cloud-Aufgabenstatus. Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREATED
YES
NO
NO
NO
initiator
string
Eine Beschreibung des clientseitigen Initiators. Wird aus dem Anforderungswert verwendet.
Kasse 12
YES
NO
NO
NO
contextId
string
Die ID der betroffenen Zielentität, falls vorhanden (transactionId / batchId)
YES
NO
NO
NO
payload
Objekt
Kontextaufgabentext - abhängig von taskClass
{...}
YES
NO
NO
NO
exceptionId
string
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er den Fehler untersuchen kann.
FujIk6
NO
YES
YES
YES
type
string
Art der Ausnahme.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
string
Ausnahmemeldung.
Passwort zu schwach
NO
YES
YES
YES
context
string
Ausnahmekontext. Weitere Informationen.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
YES
YES
Überprüfen des Status einer Aufgabe
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Variable
Format
Beschreibung
Beispiel
taskId
string
Die ID der Aufgabe, die Sie im Rahmen des vorherigen Schritts erhalten haben.
dFd3sda
Mögliche Rückgabecodes:
Antwort
Nachricht
Nachricht
Beschreibung
RC200
OK - Aufgabenstatus verfügbar
Die Aktualisierung des Auftragsstatus wurde erfolgreich verarbeitet.
Wenn Sie den endgültigen Status nicht erhalten (siehe unten), wiederholen Sie diesen Schritt.
RC 403
Cloud-Job für aktuelles Terminal nicht gefunden.
Sie sollten Ihre taskID überprüfen und den richtigen Wert erneut übermitteln.
Überprüfen Sie, ob Sie die richtige taskID eingegeben haben, und versuchen Sie es erneut.
Variablen in der Antwort:
Variable
Format
Beschreibung
Beispiel
RC200
RC-404
title
string
Vom Menschen lesbarer Aufgabenname. Wird aus dem Wert der Aufgabenerstellungsanforderung verwendet.
Rechnung 36744
YES
NO
taskId
string
Interne Aufgaben-ID
dFd3sda
YES
NO
created
string
Das Datum und die Uhrzeit der Erstellung der Aufgabe.
YES
NO
taskClass
string
Mögliche Werte: [TRANSACTION, BATCH, DUMMY]
YES
NO
Status
string
Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
YES
NO
initiator
string
Eine Beschreibung des clientseitigen Initiators. Wird aus dem Anforderungswert verwendet.
Kasse 12
YES
NO
contextID
string
Die ID der betroffenen Zielentität, falls vorhanden (transactionId / batchId)
YES
NO
payload
YES
NO
exceptionId
string
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er jedes Problem untersuchen kann.
FujIk6
NO
YES
type
string
Art der Ausnahme.
VALIDATION_EXCEPTION
NO
YES
message
string
Ausnahmemeldung.
Passwort zu schwach
NO
YES
context
string
Ausnahmekontext - weitere Informationen.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Die Aufgabenstatusanforderung sollte wiederholt werden, bis Sie einen der endgültigen Antwortcodes erhalten, nämlich:
Status
Beschreibung
Wie man sich verhält
INIT_ERROR
Der Zahlungsvorgang konnte nicht initialisiert werden. Überprüfen Sie, ob der Fehler angezeigt wurde, den Sie erhalten haben.
Befolgen Sie die Fehleranweisungen.
COMPLETED
Sobald Sie diesen Status erhalten haben, ist Ihre Aufgabe abgeschlossen und das Ergebnis ist verfügbar.
Sie können mit dem nächsten Schritt fortfahren.
CANCELLED
Die Aufgabe wurde vom Benutzer abgebrochen.
Sie sollten einen neuen Auftrag starten, da diese Aufgabe vom Benutzer abgebrochen wurde.
ERROR
Bei der Verarbeitung des Auftrags ist ein Fehler aufgetreten.
Befolgen Sie die Fehleranweisungen.
Sie können mit dem nächsten Schritt nur fortfahren, wenn sich die Antwort im Status ABGESCHLOSSEN befindet.
Abrufen eines Zahlungsergebnisses
Nyní víme, že transakce byla autorizována. Cílem tohoto kroku je získat stav transakce a detaily transakce. Pro nový požadavek zavoláte koncový bod GET /v1/transactions/{transactionId}, kde použijete následující proměnné:
Variable
Format
Beschreibung
Beispiel
contextId
string
Die Transaktions-ID, die Sie in den vorherigen Schritten erhalten.
Mögliche Antwortcodes sind:
Antwort
Nachricht
Nachricht
Beschreibung
RC200
OK – Transaktionsdetails zur Verfügung gestellt
Erfolgreiche Antwort auf Ihre Anfrage.
Die Transaktion ist abgeschlossen!
RC-404
Für die aktuelle TID konnte keine Transaktion gefunden werden.
Diese Bedingung tritt auf, wenn eine bestimmte Transaktions-ID für Ihr Gerät nicht gefunden wurde.
Überprüfen Sie die Transaktions-ID.
Die Antwort enthält je nach Antwortcode die folgenden Variablen:
Variable
Format
Beschreibung
Beispiel
RC 200
RC 404
result
string
Transaktionsergebnis, mögliche Werte [ AKZEPTIERT, ABGELEHNT, STORNIERT ] wobei:
AKZEPTIERT - die Transaktion wurde erfolgreich autorisiert
ABGELEHNT - die Transaktion wurde aus irgendeinem Grund abgelehnt
STORNIERT - wenn die Transaktion vom Betreiber oder Kunden storniert wird
AKZEPTIERT - die Transaktion wurde erfolgreich autorisiert
ABGELEHNT - die Transaktion wurde aus irgendeinem Grund abgelehnt
STORNIERT - wenn die Transaktion vom Betreiber oder Kunden storniert wird
ACCEPTED
YES
NO
responseMessage
string
Eine detailliertere Beschreibung des resultierenden Werts.
"Vom Emittenten abgelehnt."
YES
NO
transanctionId
string
Interne Aufgaben-ID
YES
NO
transactionOperation
string
Mögliche Preise: ""SALE"" "VOID"" "REFUND""
Vorgang/Vorgangsart."
Vorgang/Vorgangsart."
AUSVERKAUF
YES
NO
transactionType
string
Mögliche Werte: "CASH" "CARD" "GO_CRYPTO"
CARD
YES
NO
merchantID
string
Nur für Kartentransaktionen - Filial-ID.
343382001
YES
NO
Tid
string
Vom Terminal erstellte Transaktions-ID
483591
YES
NO
currencyCode
string
Währungscode (ISO 4217)
YES
NO
amount
number
Transaktionsbetrag mit 2 Dezimalstellen (400 CZK).
400
YES
NO
tipAmount
number
Der Betrag der eingegebenen Spitze beträgt 2 Dezimalstellen (30 CZK).
3000
YES
NO
maskiertPan
string
Maskierte Kartennummer.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
string
Art der Kartenaufladung - Magnetstreifen, Chip oder kontaktlos
CONTACTLESS
YES
NO
referenceNumber
string
Transaktionsreferenznummer aus dem Aufgabenwert der Anforderung: originReferenceNum
FD-123456
YES
NO
receiptNumber
string
Nummer der Quittung
12
YES
NO
batchNumber
string
Chargennummer
2
YES
NO
Datum
string
Datum und Uhrzeit der Transaktionsautorisierung
09.10.2021 15:34
YES
NO
cardType
string
EMV-Markenkarte aus Kartendaten entnommen
Mastercard CL
YES
NO
abgelehntGrund
string
Grund für die Ablehnung der Transaktion
201
YES
NO
AutorisierungCode
string
Seitengenerierte Nummer GP
10293045
YES
NO
sequenceNumber
string
Seitengenerierte Nummer GP
102304128
YES
NO
helfen
string
Identifiziert die EMV-Anwendung, die für die Verarbeitung der Transaktion verwendet wird
40100000000
YES
NO
pinMessage
boolean
Zeigt an, ob die Eingabe erfolgt ist PIN
Ok
YES
NO
annulliertVon
string
Im Falle einer Stornierung wird hier die contextID angezeigt
YES
NO
cardHolderVerificationMethod
string
Nur für Nexgo-Terminals - gibt die Methode der Transaktionsüberprüfung an
PIN
YES
NO
exceptionId
string
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er dies untersuchen kann.
FujIk6
NO
YES
type
string
Ausnahmetyp
VALIDATION_EXCEPTION
NO
YES
message
string
Ausnahmemeldung
Passwort zu schwach
NO
YES
context
string
Ausnahmekontext - weitere Informationen.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
Wenn Sie die Quittung auf Ihrer Seite generieren oder drucken möchten, empfehlen wir Ihnen, zu prüfen, welche Felder erforderlich sind und auf der Quittung gedruckt / angezeigt werden müssen. Die Beschreibung finden Sie hier.