Informationen
Wenn Sie über die Cloud-API eine Zahlungsstornierung veranlassen, müssen Sie eine Aufgabe für das Gerät (TID) erstellen, auf dem die Zahlung ursprünglich durchgeführt wurde. Die Stornierung einer Zahlung, die auf Terminal „A“ getätigt wurde, über Terminal „B“ wird derzeit nicht unterstützt.
Die Stornierung einer Transaktion ist ein grundlegender Zahlungsvorgang, der es ermöglicht, eine zuvor verarbeitete Transaktion bis zu 93 Tage nach der ursprünglichen Transaktion zu stornieren. Die Stornierung der Transaktion kann ohne Kundenkarte erfolgen – der Betrag wird automatisch auf die Karte zurückerstattet, die für die ursprüngliche Verkaufstransaktion verwendet wurde.
Anmeldung & Authentifizierung
Für alle nicht öffentlichen Endpunkte ist eine Authentifizierung mittels JWT-Token erforderlich. Das Token (mit einer Gültigkeitsdauer von 90 Tagen) erhalten Sie über den Endpunkt /cloud/oauth/token mit den folgenden übergebenen Argumenten:
- Basisauthentifizierung für Token-Endpunkte (Benutzername/Passwort) – wird für jeden Benutzer bereitgestellt.
- Händlername – derselbe wie für GP tom
- Händler-Passwort – dasselbe wie für GP tom
- Terminal-ID (TID) – ID des Zielterminals
- Der Autorisierungsendpunkt befindet sich unter:
Beantragung eines Zugriffstokens
Beispielanfrage:
POST {{apiCloudHost}}/cloud/oauth/token
Autorisierung: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Inhalt-Typ: anwendung/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Beispielantwort:
{
"access_token": "eyJh…", // Zugriffstoken, das bei authentifizierten API-Anfragen verwendet wird
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Token zurücksetzen
Nach Ablauf des access_tokens steht ein refresh_token zur Verfügung.
Beispielanfrage:
POST {{apiHost}}/api/oauth/token
Autorisierung: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Inhalt-Typ: anwendung/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Art des Sicherheitsschemas
Schema der HTTP-Autorisierung
HTTP
Inhaber
Erstellen eines Ordners
Rufen Sie den Endpunkt POST /v1/tasks/TRANSACTION auf und verwenden Sie CreateCloudTaskTransactionApiRequest mit den folgenden Angaben, um die Anfrage zu erstellen:
Variabel
apiKey
VERPFLICHTUNG
VERPFLICHTUNG
tid
VERPFLICHTUNG
VERPFLICHTUNG
Initiator
VERPFLICHTUNG
VERPFLICHTUNG
Titel
VERPFLICHTUNG
VERPFLICHTUNG
printByPaymentApp
Betrag
VERPFLICHTUNG
VERPFLICHTUNG
TipAmount
transactionOperation
originTransactionId
originReferenceNum
cancelMode
VERPFLICHTUNG
VERPFLICHTUNG
transactionType*
VERPFLICHTUNG
VERPFLICHTUNG
currencyCode
timeToLive
Format
String
String
String
String
bool
Zahl
Zahl
String
String
String
String
String
String
Ganzzahl
Beschreibung
Den API-Schlüssel finden Sie direkt in der App im Bereich „Konto – Cloud-API“. Er dient vor allem in der Cloud-API zur Identifizierung bei der Anmeldung.
Ziel-TID für die jeweilige 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 Beschreibung des Initiators sollte für jede Instanz des Subsystems, die eine Aufgabe initiieren kann, eindeutig sein. Beispiel: „Server XY“ oder „Kasse 1“
Ein für Menschen lesbarer Name der Aufgabe. Er sollte eine Identifikation der Aufgabe enthalten.
Beispiel: „Rechnung 37364FD – Zahlung“
Beispiel: „Rechnung 37364FD – Zahlung“
Standardwert: true
Das stimmt, wenn der Beleg auf dem Gerät ausgedruckt werden soll.
Hinweis: Stellen Sie bei Mobiltelefonen sicher, dass der Bluetooth-Drucker verbunden ist.
Das stimmt, wenn der Beleg auf dem Gerät ausgedruckt werden soll.
Hinweis: Stellen Sie bei Mobiltelefonen sicher, dass der Bluetooth-Drucker verbunden ist.
Der Betrag der Transaktion, die storniert werden soll, darf nicht null sein und muss Dezimalstellen enthalten.
Für Stornierungen gilt dies nicht.
Transaktionstyp „tasku“. Bei der Transaktion „Transaktion stornieren“ geben Sie den Wert „VOID“ ein.
ID der zu stornierenden Transaktion. Ist nicht null, wenn der Modus „VOID“ und die Stornierung „OLDER_TRANSACTION“ ist.
Wenn Sie diesen Wert nicht auf den Beleg drucken möchten, lassen Sie das Feld 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 Verkaufsaufgabe darf keine andere Anforderung liegen.
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 Verkaufsaufgabe darf keine andere Anforderung liegen.
OLDER_TRANSACTION – wird für alle älteren Transaktionen mit Ausnahme der letzten Transaktion verwendet.
Mögliche Werte: [ CASH, CARD ]
3 Zeichen für den Währungscode (ISO 4217)
Zeitlimit für das Ablaufen eines Cloud-Auftrags. Es dürfen Werte im Bereich von Sekunden eingegeben werden.
Beispiel
333W212J3
483590
Kasse 12
Stornierung 36744
false
40000
WIRD NICHT VERWENDET
NULL
FD283737333
OPTIONAL
VORHERIGE_TRANSAKTION
KARTE
CZK
10
Inhalt der Antwort [CloudTaskDetailApiResponse]:
Mögliche Antwortcodes sind:
Antwort
RC200
RC403
RC406
RC 502
Bericht
OK – Die Aufgabe wurde registriert
Der Benutzer ist nicht berechtigt, einen Auftrag auf diesem Terminal zu registrieren
Der Auftrag kann für dieses Terminal nicht angenommen werden
Die Push-Benachrichtigung wurde nicht gesendet
Beschreibung
Die Aufgabe wurde erfolgreich erstellt und wird bearbeitet.
Wenn Ihre API-Anmeldedaten nicht mit dem übermittelten TID-Wert übereinstimmen (beispielsweise wenn der TID-Inhaber ein anderer ist).
Dies geschieht in der Regel, wenn TID die Anfrage nicht bearbeiten kann.
Die Push-Benachrichtigung wurde aufgrund eines Ausfalls des Upstream-Dienstes nicht gesendet.
Wie man sich verhält
Fahren Sie mit dem nächsten Schritt im Transaktionsablauf fort.
Bitte überprüfen Sie, ob Sie die richtige TID eingegeben haben, und versuchen Sie es erneut.
Überprüfen Sie die Fehlermeldung.
Nachfolgend finden Sie die in der Antwort verwendeten Variablen:
Variabel
Titel
taskId
erstellt
Aufgabenklasse
Status
Initiator
contextId
Nutzlast
exceptionId
Typ
Nachricht
Kontext
Format
String
String
String
String
String
String
String
Objekt
String
String
String
String
Beschreibung
Ein für Menschen lesbarer Name für den Ordner. Wird aus dem Wert der Anforderung übernommen.
Interne ID des Tasks
Datum und Uhrzeit der Erstellung der Aufgabe.
Nutzlastklasse Mögliche Werte: [TRANSACTION, BATCH, DUMMY]
Status der Cloud-Aufgabe. Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.
ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)
Der Hauptteil der kontextbezogenen Aufgabe – abhängig von der taskClass
Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser den Fehler untersuchen kann.
Ausnahmetyp.
Meldung einer Ausnahme.
Kontext der Ausnahme. Weitere Informationen.
Beispiel
Rechnung 36744
dFd3sda
TRANSAKTION
GESCHAFFEN
Kasse 12
{...}
FujIk6
VALIDATION_EXCEPTION
Das Passwort ist zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
JA
JA
JA
JA
JA
JA
JA
JA
NA
NA
NA
NA
RC403
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
RC406
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
RC502
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
Überprüfung des Taschenzustands
Im nächsten Schritt überprüfen Sie den Status der Aufgabe am Endpunkt GET /v1/tasks/{taskID} mithilfe einer Anfrage, die Folgendes enthält:
Variabel
taskId
Format
String
Beschreibung
Die ID des Tasks, den Sie im vorherigen Schritt erhalten haben.
Beispiel
dFd3sda
Mögliche Rückgabecodes:
Antwort
RC200
RC403
Bericht
OK – Status der Tasche verfügbar
Für das aktuelle Terminal wurde keine Cloud-Aufgabe gefunden.
Bericht
Die Aktualisierung des Auftragsstatus wurde erfolgreich durchgeführt.
Sie sollten Ihre Task-ID überprüfen und den richtigen Wert erneut übermitteln.
Beschreibung
Falls Sie keinen endgültigen Status erhalten (siehe unten), wiederholen Sie diesen Schritt.
Bitte überprüfen Sie, ob Sie die richtige Task-ID eingegeben haben, und versuchen Sie es erneut.
Variablen in der Antwort:
Variabel
Titel
taskId
erstellt
Aufgabenklasse
Status
Initiator
contextID
Nutzlast
exceptionId
Typ
Nachricht
Kontext
Format
String
String
String
String
String
String
String
String
String
String
String
Beschreibung
Ein für Menschen lesbarer Name für die Aufgabe. Wird aus dem Wert der Anforderung zur Erstellung der Aufgabe übernommen.
Interne ID der Aufgabe
Datum und 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]
Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.
ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)
Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser ein eventuelles Problem untersuchen kann.
Ausnahmetyp.
Ausnahmemeldung.
Kontext der Ausnahme – weitere Informationen.
Beispiel
Rechnung 36744
dFd3sda
IN_PROGRESS
Kasse 12
FujIk6
VALIDATION_EXCEPTION
Das Passwort ist zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
JA
JA
JA
JA
JA
JA
JA
JA
NA
NA
NA
NA
RC404
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
Die Abfrage des Tasks-Status sollte so lange wiederholt werden, bis Sie einen der folgenden endgültigen Antwortcodes erhalten:
Status
INIT_ERROR
ABGESCHLOSSEN
ABGESAGT
ERROR
Beschreibung
Die Initiierung des Zahlungsvorgangs ist fehlgeschlagen. Überprüfen Sie den empfangenen Fehler.
Sobald Sie diesen Status erhalten, ist Ihre Aufgabe abgeschlossen und das Ergebnis liegt vor.
Die Aufgabe wurde vom Benutzer gelöscht.
Bei der Verarbeitung des Auftrags ist ein Fehler aufgetreten.
Wie man sich verhält
Befolgen Sie die Anweisungen für den Fehler.
Sie können mit dem nächsten Schritt fortfahren.
Sie sollten eine neue Aufgabe starten, da diese Aufgabe vom Benutzer abgebrochen wurde.
Befolgen Sie die Anweisungen für den Fehler.
Sie können erst dann mit dem nächsten Schritt fortfahren, wenn der Status der Antwort „COMPLETED“ lautet.
Abruf des Zahlungsergebnisses
Nun wissen wir, dass die Transaktion autorisiert wurde. Ziel dieses Schritts ist es, den Status und die Details der Transaktion abzurufen. Für die neue Anfrage rufen Sie den Endpunkt GET /v1/transactions/{transactionId} auf, wobei Sie die folgenden Variablen verwenden:
Variabel
transactionId
Format
String
Beschreibung
Die Transaktions-ID, die Sie in den vorherigen Schritten erhalten haben.
Beispiel
4414c640-2db7-11ec-910a-91880dadec20
Mögliche Antwortcodes sind:
Antwort
RC200
RC404
Bericht
OK – Transaktionsdetails bereitgestellt
Für die aktuelle TID wurde keine Transaktion gefunden.
Bericht
Ihre Anfrage wurde erfolgreich bearbeitet.
Dieser Zustand tritt ein, wenn für Ihr Gerät die entsprechende Transaktions-ID nicht gefunden wurde.
Beschreibung
Die Transaktion ist abgeschlossen!
Überprüfen Sie die Transaktions-ID.
Die Antwort enthält je nach Antwortcode die folgenden Variablen:
Variabel
Ergebnis
responseMessage
transactionId
transactionOperation
transactionType
merchantID
tid
currencyCode
Betrag
TipAmount
cardNumber
cardDataEntry
referenzNummer
Rechnungsnummer
Datum
emvAppLabel
sequenceNumber
exceptionId
Typ
Nachricht
Kontext
"dccData": {"status"}
Format
String
String
String
String
String
String
String
String
Zahl
Zahl
String
String
String
String
String
String
String
String
String
String
String
String
Beschreibung
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
Eine ausführlichere Beschreibung des Endwerts.
Interne Aufgaben-ID
Mögliche Werte: "SALE", "VOID", "REFUND"
Vorgang / Transaktionsart."
Vorgang / Transaktionsart."
Mögliche Werte: "CASH" "CARD"
Nur für Kartenzahlungen – Filial-ID.
Vom Terminal generierte Transaktions-ID
Währungscode (ISO 4217)
Transaktionsbetrag mit 2 Dezimalstellen (400 CZK).
Der Trinkgeldbetrag wurde auf zwei Dezimalstellen genau angegeben (30 CZK).
Die Kartennummer ist verdeckt.
Art des Kartenlesens – Magnetstreifen, Chip oder kontaktlos.
Transaktionsreferenznummer, die aus dem Wert der Aufgabenanforderung übernommen wurde: originReferenceNum
Datum und Uhrzeit der Transaktionsautorisierung
EMV-Markenkarte, übernommen aus den Kartendaten
Auf der GP-Seite generierte Nummer
Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser die Angelegenheit untersuchen kann.
Ausnahmetyp
Ausnahmemeldung
Kontext der Ausnahme – weitere Informationen.
DE: Gibt an, ob eine DCC-Transaktion storniert wird
EN: Gibt an, ob eine stornierte Transaktion als DCC verarbeitet wurde
EN: Gibt an, ob eine stornierte Transaktion als DCC verarbeitet wurde
Beispiel
AKZEPTIERT
null
4414c640-2db7-11ec-910a-91880dadec20
NULL
KARTE
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDATION_EXCEPTION
Das Passwort ist zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
CZ: Wenn „ACCEPTED“, muss folgender Text auf den Beleg gedruckt werden:
EN: Falls Sie zustimmen, müssen Sie auf Ihrer Quittung folgenden Text vermerken:
Der Transaktionsbetrag, die Währung und der Wechselkurs entsprechen denen der ursprünglichen Transaktion.
Die Währungsumrechnung wird von Global Payments bereitgestellt.
EN: Falls Sie zustimmen, müssen Sie auf Ihrer Quittung folgenden Text vermerken:
Der Transaktionsbetrag, die Währung und der Wechselkurs entsprechen denen der ursprünglichen Transaktion.
Die Währungsumrechnung wird von Global Payments bereitgestellt.
RC 200
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
JA
NA
NA
NA
NA
JA
RC 404
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
NA
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.