Information
Cloud API Wenn Sie eine Stornierung über aufrufen, müssen Sie eine Aufgabe für das Gerät (TID) erstellen, an dem die Zahlung ursprünglich vorgenommen wurde. Das Aufrufen einer Stornierung, die an Terminal "A" vorgenommen wurde, an Terminal "B" wird derzeit nicht unterstützt.
Die Transaktionsumkehr ist ein grundlegender Zahlungsvorgang, mit dem Sie eine zuvor verarbeitete Transaktion bis zu 93 Tage nach der ursprünglichen Transaktion stornieren können. Die Stornierung der Transaktion kann ohne Kundenkarte erfolgen - das Geld wird automatisch auf die Karte zurückerstattet, die für die ursprüngliche Transaktion der Verkaufsart verwendet wurde.
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
Abrufen eines Zugriffstokens
Beispielanfrage:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
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
Art des Sicherheitssystems
HTTP-Autorisierungsschema
HTTP-VERBINDUNG
Überbringer
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
apiKey
MANDATORY
MANDATORY
Tid
OBLIGATORISCH
OBLIGATORISCH
initiator
OBLIGATORISCH
OBLIGATORISCH
title
OBLIGATORISCH
OBLIGATORISCH
printByPaymentApp
amount
OBLIGATORISCH
OBLIGATORISCH
tipAmount
transactionOperation
originTransactionId
originReferenceNum
cancelMode
OBLIGATORISCH
OBLIGATORISCH
transactionType*
OBLIGATORISCH
OBLIGATORISCH
currencyCode
timeToLive
Format
string
string
string
string
boolean
number
number
string
string
string
string
string
string
ganze Zahl
Beschreibung
API Schlüssel finden Sie direkt in der Anwendung im Bereich Konto -Cloud API . Er wird hauptsächlich zur Unterscheidung von Anmeldungen in Cloud API verwendet.
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.
Die Initiatorbeschreibung sollte für jede Instanz des Subsystems, die den Task initiieren kann, eindeutig sein. Beispiel: "Server XY" oder "Kasse 1"
Vom Menschen lesbarer Aufgabenname. Es sollte eine gewisse Identifizierung der Aufgabe enthalten.
Beispiel: "Rechnung 37364FD Zahlung"
Beispiel: "Rechnung 37364FD Zahlung"
Standardwert: true
True, wenn die Quittung auf das Gerät gedruckt werden soll.
Hinweis: Stellen Sie bei Mobiltelefonen sicher, dass der Bluetooth-Drucker angeschlossen ist.
True, wenn die Quittung auf das Gerät gedruckt werden soll.
Hinweis: Stellen Sie bei Mobiltelefonen sicher, dass der Bluetooth-Drucker angeschlossen ist.
Der zu stornierende Transaktionsbetrag muss ungleich Null sein und Dezimalstellen enthalten.
Es wird nicht für die Stornierung verwendet.
Der Typ der Aufgabentransaktion. Geben Sie für die Transaktion "Transaktionsstornierung" den Wert "VOID" ein.
Die ID der abzubrechenden Transaktion. Nicht null, wenn der VOID-Modus und der Abbruch OLDER_TRANSACTION sind.
Wenn Sie diesen Wert nicht auf der Quittung drucken möchten, lassen Sie ihn leer.
Mögliche Werte: [ LAST_TRANSACTION, OLDER_TRANSACTION ] wobei:
LAST_TRANSACTION - Wird nur für eine zuvor autorisierte Transaktion verwendet. Zwischen dieser Aufgabe und der vorherigen Vertriebsaufgabe kann keine weitere Anforderung bestehen.
OLDER_TRANSACTION – Wird für alle älteren Transaktionen mit Ausnahme der letzten Transaktion verwendet.
LAST_TRANSACTION - Wird nur für eine zuvor autorisierte Transaktion verwendet. Zwischen dieser Aufgabe und der vorherigen Vertriebsaufgabe kann keine weitere Anforderung bestehen.
OLDER_TRANSACTION – Wird für alle älteren Transaktionen mit Ausnahme der letzten Transaktion verwendet.
Mögliche Werte: [ BARGELD, KARTE, GO_CRYPTO ]
3 Zeichen für Währungscode (ISO 4217)
Limit pro vypršení platnosti cloudové úlohy. Je povoleno zadat hodnoty z intervalu <10 až 172800> sekund.
Beispiel
333W212J3
483590
Kasse 12
Stornierung 36744
FALSE
40000
NICHT VERWENDET
VOID
FD283737333
WAHLFREI
OLDER_TRANSACTION
CARD
CZK
10
Inhalt der Antwort [CloudTaskDetailApiResponse]:
Mögliche Antwortcodes sind:
Antwort
RC200
RC 403
RC 406
RC 502
Nachricht
OK - Aufgabe wurde registriert
Der Benutzer darf die Aufgabe nicht auf dem angegebenen Terminal registrieren
Die Aufgabe ist für das Terminal nicht akzeptabel
Push-Benachrichtigung nicht gesendet
Beschreibung
Die Aufgabe wurde erfolgreich erstellt und wird verarbeitet.
Wenn Ihre Login-Daten API stimmen nicht mit dem gesendeten TID-Wert überein (z. B. wenn der TID-Besitzer unterschiedlich ist).
Dies geschieht normalerweise, wenn die TID die Anforderung nicht verarbeiten kann.
Die Pushbenachrichtigung wurde aufgrund eines Upstreamdienstfehlers nicht gesendet.
Wie man sich verhält
Fahren Sie mit dem nächsten Schritt im Transaktionsfluss fort.
Überprüfen Sie, ob Sie die richtige TID eingegeben haben, und versuchen Sie es erneut.
Überprüfen Sie die Fehlermeldung.
Im Folgenden finden Sie die in der Antwort verwendeten Variablen:
Variable
title
taskId
created
taskClass
Status
initiator
contextId
payload
exceptionId
type
message
context
Format
string
string
string
string
string
string
string
Objekt
string
string
string
string
Beschreibung
Vom Menschen lesbarer Aufgabenname. Wird aus dem Anforderungswert verwendet.
Interne Aufgaben-ID
Das Datum und die Uhrzeit der Erstellung der Aufgabe.
NutzlastklasseMopworthy-Werte: [TRANSACTION, BATCH, DUMMY]
Cloud-Aufgabenstatus. Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Eine Beschreibung des clientseitigen Initiators. Wird aus dem Anforderungswert verwendet.
Die ID der betroffenen Zielentität, falls vorhanden (transactionId / batchId)
Kontextaufgabentext - abhängig von taskClass
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er den Fehler untersuchen kann.
Art der Ausnahme.
Ausnahmemeldung.
Ausnahmekontext. Weitere Informationen.
Beispiel
Rechnung 36744
dFd3sda
TRANSAKTION
CREATED
Kasse 12
{...}
FujIk6
VALIDATION_EXCEPTION
Passwort zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC 403
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC 406
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC-502
NO
NO
NO
NO
NO
NO
NO
NO
YES
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
taskId
Format
string
Beschreibung
Die ID der Aufgabe, die Sie im Rahmen des vorherigen Schritts erhalten haben.
Beispiel
dFd3sda
Mögliche Rückgabecodes:
Antwort
RC200
RC 403
Nachricht
OK - Aufgabenstatus verfügbar
Cloud-Job für aktuelles Terminal nicht gefunden.
Nachricht
Die Aktualisierung des Auftragsstatus wurde erfolgreich verarbeitet.
Sie sollten Ihre taskID überprüfen und den richtigen Wert erneut übermitteln.
Beschreibung
Wenn Sie den endgültigen Status nicht erhalten (siehe unten), wiederholen Sie diesen Schritt.
Überprüfen Sie, ob Sie die richtige taskID eingegeben haben, und versuchen Sie es erneut.
Variablen in der Antwort:
Variable
title
taskId
created
taskClass
Status
initiator
contextID
payload
exceptionId
type
message
context
Format
string
string
string
string
string
string
string
string
string
string
string
Beschreibung
Vom Menschen lesbarer Aufgabenname. Wird aus dem Wert der Aufgabenerstellungsanforderung verwendet.
Interne Aufgaben-ID
Das Datum und die Uhrzeit der Erstellung der Aufgabe.
Mögliche Werte: [TRANSACTION, BATCH, DUMMY]
Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Eine Beschreibung des clientseitigen Initiators. Wird aus dem Anforderungswert verwendet.
Die ID der betroffenen Zielentität, falls vorhanden (transactionId / batchId)
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er jedes Problem untersuchen kann.
Art der Ausnahme.
Ausnahmemeldung.
Ausnahmekontext - weitere Informationen.
Beispiel
Rechnung 36744
dFd3sda
IN_PROGRESS
Kasse 12
FujIk6
VALIDATION_EXCEPTION
Passwort zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC-404
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
Die Aufgabenstatusanforderung sollte wiederholt werden, bis Sie einen der endgültigen Antwortcodes erhalten, nämlich:
Status
INIT_ERROR
COMPLETED
CANCELLED
ERROR
Beschreibung
Der Zahlungsvorgang konnte nicht initialisiert werden. Überprüfen Sie, ob der Fehler angezeigt wurde, den Sie erhalten haben.
Sobald Sie diesen Status erhalten haben, ist Ihre Aufgabe abgeschlossen und das Ergebnis ist verfügbar.
Die Aufgabe wurde vom Benutzer abgebrochen.
Bei der Verarbeitung des Auftrags ist ein Fehler aufgetreten.
Wie man sich verhält
Befolgen Sie die Fehleranweisungen.
Sie können mit dem nächsten Schritt fortfahren.
Sie sollten einen neuen Auftrag starten, da diese Aufgabe vom Benutzer abgebrochen wurde.
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
transactionId
Format
string
Beschreibung
Die Transaktions-ID, die Sie in den vorherigen Schritten erhalten.
Beispiel
4414C640-2DB7-11EC-910A-91880DADEC20
Mögliche Antwortcodes sind:
Antwort
RC200
RC-404
Nachricht
OK – Transaktionsdetails zur Verfügung gestellt
Für die aktuelle TID konnte keine Transaktion gefunden werden.
Nachricht
Erfolgreiche Antwort auf Ihre Anfrage.
Diese Bedingung tritt auf, wenn eine bestimmte Transaktions-ID für Ihr Gerät nicht gefunden wurde.
Beschreibung
Die Transaktion ist abgeschlossen!
Überprüfen Sie die Transaktions-ID.
Die Antwort enthält je nach Antwortcode die folgenden Variablen:
Variable
result
responseMessage
transanctionId
transactionOperation
transactionType
merchantID
Tid
currencyCode
amount
tipAmount
cardNumber
cardDataEntry
referenceNumber
invoiceNumber
Datum
emvAppLabel
sequenceNumber
exceptionId
type
message
context
Format
string
string
string
string
string
string
string
string
number
number
string
string
string
string
string
string
string
string
string
string
string
Beschreibung
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
Eine detailliertere Beschreibung des resultierenden Werts.
Interne Aufgaben-ID
Mögliche Preise: ""SALE"" "VOID"" "REFUND""
Vorgang/Vorgangsart."
Vorgang/Vorgangsart."
Mögliche Werte: "CASH" "CARD" "GO_CRYPTO"
Nur für Kartentransaktionen - Filial-ID.
Vom Terminal erstellte Transaktions-ID
Währungscode (ISO 4217)
Transaktionsbetrag mit 2 Dezimalstellen (400 CZK).
Der Betrag der eingegebenen Spitze beträgt 2 Dezimalstellen (30 CZK).
Maskierte Kartennummer.
Kartenlademethode - mag.strip, Chip oder kontaktlos.
Transaktionsreferenznummer aus dem Aufgabenwert der Anforderung: originReferenceNum
Datum und Uhrzeit der Transaktionsautorisierung
EMV-Markenkarte aus Kartendaten entnommen
Seitengenerierte Nummer GP
Pseudoeindeutige Ausnahme-ID. Es kann als "Support-ID" dienen, die der Benutzer an den Support kommunizieren kann, damit er dies untersuchen kann.
Ausnahmetyp
Ausnahmemeldung
Ausnahmekontext - weitere Informationen.
Beispiel
ACCEPTED
Null
4414C640-2DB7-11EC-910A-91880DADEC20
VOID
CARD
343382001
483591
40000
-
1233
Null
FD-123456
2020-09-16T09:31:16.000S
Null
102304128
FujIk6
VALIDATION_EXCEPTION
Passwort zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC 200
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC 404
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
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.