Eine Verkaufstransaktion ist ein grundlegender Zahlungsvorgang, bei dem ein festgelegter Betrag vom Bankkonto des Karteninhabers auf das Konto des Händlers überwiesen wird.

Was den Zahlungsablauf betrifft, ist wie folgt vorzugehen:

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:
- dev: https://cloud-api-dev.gptom.com/cloud/oauth/token
- Produktion: https://cloud-api.gptom.com/cloud/oauth/token

Diese Art der Authentifizierung ist für alle Terminals gleich.

Beantragung eines Zugriffstokens

Beispielanfrage:

POST {{apiCloudHost}}/cloud/oauth/token
Autorisierung: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Inhalt-Typ: anwendung/x-www-form-urlencoded

(Die Angaben zu „Authorization“ und „Content-Type“ sind für alle Kunden immer identisch – bitte verwenden Sie dieselben Angaben wie im Beispiel. In das Feld „grant_type“ müssen anschließend die eindeutigen Kundendaten eingegeben werden.).

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 / Security scheme

HTTP

HTTP-Autorisierungsschema

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

Format

Beschreibung

Beispiel

apiKey
VERPFLICHTUNG

String

Den API-Schlüssel finden Sie direkt in der GP-App im Bereich „Konto – Cloud-API“. Er dient hauptsächlich zur Authentifizierung bei der Cloud-API. Der API-Schlüssel ist für jedes Unternehmen einzigartig.

333W212J3

tid
VERPFLICHTUNG

String

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.

483590

Initiator
VERPFLICHTUNG

String

Die Beschreibung des Initiators sollte für jede Instanz des Subsystems, die eine Aufgabe initiieren kann, eindeutig sein. Beispiel: „Server XY“ oder „Kasse 1“

Kasse 12

Titel
VERPFLICHTUNG

String

Ein für Menschen lesbarer Name der Aufgabe. Er sollte eine Identifikation der Aufgabe enthalten.
Beispiel: „Rechnung 37364FD“

Rechnung 36744

printByPaymentApp

bool

Standard: true
Das stimmt, wenn der Beleg auf dem Gerät ausgedruckt werden soll.
Hinweis: Bei Mobiltelefonen müssen Sie sicherstellen, dass der Bluetooth-Drucker verbunden ist.

false

Betrag
VERPFLICHTUNG

Zahl

Der Transaktionsbetrag muss ungleich Null sein und Dezimalstellen enthalten. Bei einem Transaktionswert von 50 EUR geben Sie den Wert „5000“ ein.

40000

TipAmount

Zahl

Höhe des Trinkgeldes. Für ein Trinkgeld in Höhe von 3 EUR geben Sie den Wert „300“ ein.

transactionOperation
VERPFLICHTUNG

String

Art der Transaktion für die Aufgabe. Bei der Transaktion „Sale“ geben Sie den Wert „SALE“ ein.

SALE

originTransactionId

String

ID der zu stornierenden Transaktion. Ist nicht null, wenn der Modus „VOID“ und die Stornierung „OLDER_TRANSACTION“ ist.

WIRD NICHT VERWENDET

originReferenceNum

String

Referenznummer, z. B. Rechnungsnummer – Geben Sie einen beliebigen Wert mit bis zu 20 Zeichen ein, der in den Übersichten angezeigt wird und die Zahlung auf Ihrer Seite identifiziert.

FD123456

cancelMode

String

Stornomodus, nicht null, wenn der Transaktionstyp VOID ist
Mögliche Werte: [ LAST_TRANSACTION, OLDER_TRANSACTION ]

WIRD NICHT VERWENDET

transactionType*
VERPFLICHTUNG

String

Mögliche Werte: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]

KARTE

currencyCode

String

3 Währungscodes (gemäß ISO 4217)

CZK

preferableReceiptType

String

Voreingestellte Versandart für die Quittung: [ E-MAIL, TELEFON, QR-CODE, DRUCKEN ]

E-Mail

String

E-Mail-Adresse des Kunden

support@gptom.com

Telefon

String

Telefonnummer des Kunden

+420123456789

TipCollect

bool

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

timeToLive

Ganzzahl

Zeitlimit für das Ablaufen eines Cloud-Auftrags. Es können Werte im Bereich von 10 bis 172.800 Sekunden eingegeben werden.

Inhalt der Antwort [CloudTaskDetailApiResponse]:

Mögliche Antwortcodes sind:

Antwort

Bericht

Beschreibung

Wie man sich verhält

RC200

OK – Die Aufgabe wurde registriert

Die Aufgabe wurde erfolgreich erstellt und wird bearbeitet.

Fahren Sie mit dem nächsten Schritt im Transaktionsablauf fort.

RC401

Nicht identifiziert

Falls die Authentifizierung mit dem Terminal nicht stattgefunden hat.

Führen Sie den Authentifizierungsprozess durch (siehe obigen Schritt).

RC403

Der Benutzer ist nicht berechtigt, einen Auftrag auf diesem Terminal zu registrieren

Wenn Ihre API-Anmeldedaten nicht mit dem übermittelten TID-Wert übereinstimmen (beispielsweise wenn der TID-Inhaber ein anderer ist).

Bitte überprüfen Sie, ob Sie die richtige TID eingegeben haben, und versuchen Sie es erneut.

RC406

Der Auftrag kann für dieses Terminal nicht angenommen werden

Dies geschieht in der Regel, wenn TID die Anfrage nicht bearbeiten kann.

Überprüfen Sie die Fehlermeldung.

RC 502

Die Push-Benachrichtigung wurde nicht gesendet

Die Push-Benachrichtigung wurde aufgrund eines Ausfalls des Upstream-Dienstes nicht gesendet.

Nachfolgend finden Sie die in der Antwort verwendeten Variablen:

Variabel

Format

Beschreibung

Beispiel

RC200

RC403

RC406

RC502

Titel

String

Ein für Menschen lesbarer Name für den Ordner. Wird aus dem Wert der Anforderung übernommen.

Rechnung 36744

taskId

String

Interne ID des Tasks

dFd3sda

erstellt

String

Datum und Uhrzeit der Erstellung der Aufgabe.

Aufgabenklasse

String

Nutzlastklasse Mögliche Werte: [TRANSACTION, BATCH, VOID]

TRANSAKTION

Status

String

Status der Cloud-Aufgabe. Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]

GESCHAFFEN

Initiator

String

Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.

Kasse 12

contextId

String

ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)

Nutzlast

Objekt

Der Hauptteil der kontextbezogenen Aufgabe – abhängig von der taskClass

{...}

exceptionId

String

Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser den Fehler untersuchen kann.

FujIk6

Typ

String

Ausnahmetyp.

VALIDATION_EXCEPTION

Nachricht

String

Meldung einer Ausnahme.

Das Passwort ist zu schwach

Kontext

String

Kontext der Ausnahme. Weitere Informationen.

[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}

Ü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

Format

Beschreibung

Beispiel

taskId

String

Die ID des Tasks, den Sie im vorherigen Schritt erhalten haben.

dFd3sda

Mögliche Rückgabecodes:

Antwort

Bericht

Beschreibung

RC200

OK – Status der Tasche verfügbar

Die Aktualisierung des Auftragsstatus wurde erfolgreich durchgeführt.

Falls Sie keinen endgültigen Status erhalten (siehe unten), wiederholen Sie diesen Schritt.

RC403

Für das aktuelle Terminal wurde keine Cloud-Aufgabe gefunden.

Sie sollten Ihre Task-ID überprüfen und den richtigen Wert erneut übermitteln.

Bitte überprüfen Sie, ob Sie die richtige Task-ID eingegeben haben, und versuchen Sie es erneut.

Variablen in der Antwort:

Variabel

Format

Beschreibung

Beispiel

RC200

RC404

Titel

String

Ein für Menschen lesbarer Name für die Aufgabe. Wird aus dem Wert der Anforderung zur Erstellung der Aufgabe übernommen.

Rechnung 36744

taskId

String

Interne ID der Aufgabe

dFd3sda

erstellt

String

Datum und Uhrzeit der Erstellung der Aufgabe.

Aufgabenklasse

String

Mögliche Werte: [TRANSACTION, BATCH, DUMMY]

Status

String

Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]

IN_PROGRESS

Initiator

String

Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.

Kasse 12

contextID

String

ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)

Nutzlast

exceptionId

String

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.

FujIk6

Typ

String

Ausnahmetyp.

VALIDATION_EXCEPTION

Nachricht

String

Ausnahmemeldung.

Das Passwort ist zu schwach

Kontext

String

Kontext der Ausnahme – weitere Informationen.

[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}

Die Abfrage des Tasks-Status sollte so lange wiederholt werden, bis Sie einen der folgenden endgültigen Antwortcodes erhalten:

Status

Beschreibung

Wie man sich verhält

INIT_ERROR

Die Initiierung des Zahlungsvorgangs ist fehlgeschlagen. Überprüfen Sie den empfangenen Fehler.

Befolgen Sie die Anweisungen für den Fehler.

ABGESCHLOSSEN

Sobald Sie diesen Status erhalten, ist Ihre Aufgabe abgeschlossen und das Ergebnis liegt vor.

Sie können mit dem nächsten Schritt fortfahren.

ABGESAGT

Die Aufgabe wurde vom Benutzer gelöscht.

Sie sollten eine neue Aufgabe starten, da diese Aufgabe vom Benutzer abgebrochen wurde.

ERROR

Bei der Verarbeitung des Auftrags ist ein Fehler aufgetreten.

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

Format

Beschreibung

Beispiel

contextId

String

Die Transaktions-ID, die Sie in den vorherigen Schritten erhalten haben.

Mögliche Antwortcodes sind:

Antwort

Bericht

Beschreibung

RC200

OK – Transaktionsdetails bereitgestellt

Ihre Anfrage wurde erfolgreich bearbeitet.

Die Transaktion ist abgeschlossen!

RC404

Für die aktuelle TID wurde keine Transaktion gefunden.

Dieser Zustand tritt ein, wenn für Ihr Gerät die entsprechende Transaktions-ID nicht gefunden wurde.

Überprüfen Sie die Transaktions-ID.

Die Antwort enthält je nach Antwortcode die folgenden Variablen:

Variabel

Format

Beschreibung

Beispiel

RC 200

RC 404

Ergebnis

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

AKZEPTIERT

responseMessage

String

Eine ausführlichere Beschreibung des Endwerts.

“Vom Aussteller abgelehnt.”

transactionId

String

Interne Aufgaben-ID

transactionOperation

String

Mögliche Werte: "SALE", "VOID", "REFUND"
Vorgang / Transaktionsart."

SALE

transactionType

String

Mögliche Werte: "CASH" "CARD"

KARTE

merchantID

String

Nur für Kartenzahlungen – Filial-ID.

343382001

tid

String

Vom Terminal generierte Transaktions-ID

483591

currencyCode

String

Währungscode (ISO 4217)

Betrag

Zahl

Transaktionsbetrag mit 2 Dezimalstellen (400 CZK).

400

TipAmount

Zahl

Der Trinkgeldbetrag wurde auf zwei Dezimalstellen genau angegeben (30 CZK).

3000

maskedPan

String

Die Kartennummer ist verdeckt.

XXXX XXXX XXXX 1233

cardDataEntry

String

Art des Kartenlesens – Magnetstreifen, Chip oder kontaktlos

KONTAKTLOS

referenzNummer

String

Transaktionsreferenznummer, die aus dem Wert der Aufgabenanforderung übernommen wurde: originReferenceNum

FD123456

receiptNumber

String

Belegnummer

batchNumber

String

Chargennummer

Datum

String

Datum und Uhrzeit der Transaktionsautorisierung

09.10.2021 15:34

cardType

String

EMV-Markenkarte, übernommen aus den Kartendaten

Mastercard CL

Grund für die Ablehnung

String

Grund für die Ablehnung der Transaktion

201

authorizationCode

String

Auf der GP-Seite generierte Nummer

10293045

sequenceNumber

String

Auf der GP-Seite generierte Nummer

102304128

Hilfe

String

Identifiziert die für die Transaktionsabwicklung verwendete EMV-Anwendung

40100000000

pinMessage

bool

Zeigt an, ob eine PIN eingegeben wurde

PIN_ENTERED oder NO_PIN

abgebrochen durch

String

Im Falle einer Stornierung wird hier die contextID angezeigt

cardHolderVerificationMethod

String

Nur für Nexgo-Terminals – gibt die Art der Transaktionsüberprüfung an

Pin Protection

exceptionId

String

Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser die Angelegenheit untersuchen kann.

FujIk6

Typ

String

Ausnahmetyp

VALIDATION_EXCEPTION

Nachricht

String

Ausnahmemeldung

Das Passwort ist zu schwach

Kontext

String

Kontext der Ausnahme – weitere Informationen.

[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}

dccData

Status (DCC)

String

CZ: Gibt den DCC-Status an. Bei "ACCEPTED" wurde die Transaktion über DCC abgewickelt, und Sie müssen den DCC-Beleg mit den entsprechenden Daten ausfüllen. Bei "NOT_ACCEPTED" können Sie die DCC-Daten ignorieren.
DE: Zeigt den DCC-Status an. Bei "ACCEPTED" wurde die Transaktion über DCC abgewickelt, und Sie müssen die Quittung mit den DCC-Daten ausfüllen. Bei "NOT_ACCEPTED" können Sie die DCC-Daten ignorieren.

AKZEPTIERT
NOT_ACCEPTED

Betrag (DCC)

String

DE: Transaktionsbetrag in der DCC-Währung – in der Währung der Kundenkarte. Er muss genau so angezeigt werden, wie er in der API-Antwort erscheint, einschließlich der Anzahl der Dezimalstellen.
EN: Transaktionsbetrag in DCC-Währung – in der Währung der Kundenkarte. Sie müssen diesen Betrag auf Ihrem Beleg genau so ausweisen, wie er in der API-Antwort angegeben wurde, einschließlich der korrekten Dezimalstellen.

2.31

Währungscode (DCC)

String

DE: Währung der Kundenkarte.
EN: Währung der Kundenkarte.

EUR

Wechselkurs (DCC)

String

DE: Gibt den Wechselkurs an. Dieser Wert ist in der Landeswährung des Terminals angegeben. Er muss genau so angezeigt werden, wie er in der API-Antwort erscheint, einschließlich der Anzahl der Dezimalstellen.
EN: Gibt den Wechselkurs an. Dieser Wert ist in der lokalen Terminalwährung angegeben. Sie müssen ihn auf Ihrem Beleg genau so angeben, wie er in der API-Antwort erhalten wurde, einschließlich der korrekten Dezimalstellen.

56.35

Markup (DCC)

String

DE: Aufschlag auf den Umrechnungskurs. Er muss genau so angezeigt werden, wie er in der API-Antwort erscheint, einschließlich der Anzahl der Dezimalstellen.
EN: Angabe der Umrechnungsrate. Sie müssen diese auf Ihrem Beleg genau so angeben, wie sie in der API-Antwort angegeben wurde, einschließlich der korrekten Dezimalstellen.

3.20

regionSchemaIndicator (DCC)

String

CZ: Gibt an, ob die Kundenkarte innerhalb oder außerhalb der EU ausgestellt wurde. Wenn der Wert "0" oder "1" ist, muss auf dem Kassenbon der Text "Markup" angezeigt werden. Wenn der Wert "2" ist, muss auf dem Kassenbon "Markup over ECB rate" angezeigt werden.
DE: Gibt an, ob die Karte des Kunden innerhalb oder außerhalb der EU ausgestellt wurde. Wenn der Wert "0" oder "1" lautet, muss auf dem Beleg der Text "Aufschlag" angezeigt werden. Wenn der Wert "2" lautet, muss auf dem Beleg der Text "Aufschlag gegenüber dem EZB-Kurs“ angezeigt werden.

0
1
2

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.

Startseite

app2app API

Cloud-API

iOS-API

Verkaufstransaktion

Anmeldung & Authentifizierung

Beantragung eines Zugriffstokens

Token zurücksetzen

GPTomAuth

Erstellen eines Ordners

Inhalt der Antwort [CloudTaskDetailApiResponse]:

Überprüfung des Taschenzustands

Abruf des Zahlungsergebnisses

Wie gefällt Ihnen dieses Lernprogramm?

Handbuch