Sign up

Einführung

Webhooks sind Nachrichten, die von unserer Plattform an Ihren Server gesendet werden. Diese Nachrichten informieren Sie über das Ergebnis Ihrer Transaktionen oder über spätere Statusänderungen (d. h. Erfassungen, Erstattungen).

Mit unserer API können Sie jederzeit den Status einer Transaktion abfragen. Um jedoch regelmäßig API-Aufrufe zu senden, müssen Sie eine Anwendung erstellen, die alle Ihre Transaktionen und deren aktuellen Status verfolgt.

Unsere Webhook-Lösung befreit Sie von diesem Aufwand. Unser System verfolgt alle Ihre Transaktionen und benachrichtigt Sie, sobald eine Statusänderung eintritt.

Stellen Sie Folgendes sicher:

Grundlegendes zu Webhooks

Ein Webhook ist eine POST-Anfrage von unserer Plattform an einen HTTPS- oder HTTP-Endpunkt auf Ihrem Server. Sie enthält Informationen über den aktuellen Status einer Transaktion. Unsere Plattform sendet Webhooks für Statusaktualisierungen in folgenden Fällen:

  • Online-Ereignisse, die nicht in Ihren Zuständigkeitsbereich fallen (Autorisierungsergebnisse eines Drittanbieters): Das Ergebnis ist für Sie nicht sichtbar, da sich Ihr Kunde zu diesem Zeitpunkt nicht auf Ihrer Website befindet
  • Offline-Ereignisse (z. B. Erfassung einer Autorisierung, Rückerstattung eines Auftrags): Eine Änderung, die zu einem späteren Zeitpunkt nach der ursprünglichen Transaktion erfolgt

Sehen Sie sich alle Ereignisse an, die eine Webhook-Nachricht auslösen:

Ereignis Beschreibung
payment.created Die Transaktion wurde erstellt. Dies ist der Ausgangszustand, wenn eine neue Zahlung erstellt wird
payment.redirected Der Verbraucher wurde an eine dritte Partei weitergeleitet, um die Authentifzierung/Zahlung abzuschließen
payment.authorization_requested Wir haben eine Autorisierung für ein asynchrones System beantragt und warten auf dessen Antwort
payment.pending_approval Es gibt Transaktionen, die auf Ihre Genehmigung warten
payment.pending_completion Es gibt Transaktionen, die darauf warten, dass Sie sie abschließen
payment.pending_capture Es gibt Transaktionen, die darauf warten, dass Sie sie erfassen.
payment.capture_requested Die Transaktion befindet sich im Wartezustand für deren Erfassung. (Bei Karten bedeutet dies, dass die Transaktion authorisiert wurde)
payment.captured Die Transaktion wurde erfasst und wir haben eine Online-Bestätigung erhalten.
payment.rejected Die Transaktion wurde abgelehnt
payment.rejected_capture Wir oder einer unserer nachgelagerten Banken/Provider haben die Erfassungsanfrage abgelehnt. Für jede 4xx- und 5xx-Antwort werden eine errorId und ein Array von Fehlern mit detaillierten Fehlerinformationen zurückgegeben
payment.cancelled Sie haben die Transaktion storniert. Gilt nur für Transaktionen, welche statusOutput.statusCode=6 erreichen
payment.refunded Die Transaktion wurde zurückerstattet
refund.refund_requested Die Transaktion befindet sich im Wartezustand für deren Erstattung

Ein Webhook-Ereignis enthält ein vollständiges JSON-Objekt mit allen relevanten Informationen, die Sie zur Aktualisierung Ihrer Datenbank benötigen.

Dieses Beispiel enthält drei verschiedene Ereignisse (definiert in der Eigenschaft status), die jeweils einer Aktualisierung des Transaktionsstatus entsprechen: CREATED, AUTHORIZATION_REQUESTED und CAPTURED.
Sie erhalten diese drei Webhooks-Nachrichten separat, sobald die jeweilige Statusaktualisierung auf unserer Plattform erfolgt:


[
   {
      "apiVersion":"v1",
      "created":"2020-12-09T11:20:40.3744722+01:00",
      "id":"34b8a607-1fce-4003-b3ae-a4d29e92b232",
      "merchantId":"TESTCIMCREDITCARDS",
      "payment":{
         "paymentOutput":{
            "amountOfMoney":{
               "amount":1000,
               "currencyCode":"EUR"
            },
            "references":{
               "merchantReference":"BDD_20201209112039463_UNNERD0105E2_SS_00"
            },
            "cardPaymentMethodSpecificOutput":{
               "paymentProductId":1,
               "card":{
                  "cardNumber":"************4675",
                  "expiryDate":"1221"
               },
               "fraudResults":{
                  "fraudServiceResult":"no-advice"
               },
               "threeDSecureResults":{
                  "eci":"9"
               }
            },
            "paymentMethod":"card"
         },
         "status":"CREATED",
         "statusOutput":{
            "isCancellable":false,
            "statusCategory":"CREATED",
            "statusCode":0,
            "isAuthorized":false,
            "isRefundable":false
         },
         "id":"***3092546156***"
      },
      "type":"payment.created"
   },
   {
      "apiVersion":"v1",
      "created":"2020-12-09T11:20:40.346554+01:00",
      "id":"03643daf-ba3e-4511-9c8c-e45988037c40",
      "merchantId":"TESTCIMCREDITCARDS",
      "payment":{
         "paymentOutput":{
            "amountOfMoney":{
               "amount":1000,
               "currencyCode":"EUR"
            },
            "references":{
               "merchantReference":"BDD_20201209112039463_UNNERD0105E2_SS_00"
            },
            "cardPaymentMethodSpecificOutput":{
               "paymentProductId":1,
               "card":{
                  "cardNumber":"************4675",
                  "expiryDate":"1221"
               },
               "fraudResults":{
                  "fraudServiceResult":"challenged"
               },
               "threeDSecureResults":{
                  "version":"2.2.0",
                  "flow":"challenge",
                  "cavv":"AAABBEg0VhI0VniQEjRWAAAAAAA=",
                  "eci":"9",
				  "schemeEci":"5",
                  "authenticationStatus":"Y",
                  "acsTransactionId":"3E1D57DF-8DB1-4614-91D5-B11962519703",
                  "dsTransactionId":"3E1D57DF-8DB1-4614-91D5-B11962519703",
                  "xid":"MzE5NTA3Njg2Ng==",
                  "challengeIndicator":"no-preference",
                  "liability":"issuer"
               }
            },
            "paymentMethod":"card"
         },
         "status":"AUTHORIZATION_REQUESTED",
         "statusOutput":{
            "isCancellable":false,
            "statusCategory":"PENDING_CONNECT_OR_3RD_PARTY",
            "statusCode":51,
            "isAuthorized":false,
            "isRefundable":false
         },
         "id":"***3092546156***"
      },
      "type":"payment.authorization_requested"
   },
   {
      "apiVersion":"v1",
      "created":"2020-12-09T11:20:42.1464012+01:00",
      "id":"7aeb0c3d-066e-4d31-bfe9-f9b5e48414df",
      "merchantId":"TESTCIMCREDITCARDS",
      "payment":{
         "paymentOutput":{
            "amountOfMoney":{
               "amount":1000,
               "currencyCode":"EUR"
            },
            "references":{
               "merchantReference":"BDD_20201209112039463_UNNERD0105E2_SS_00"
            },
            "cardPaymentMethodSpecificOutput":{
               "paymentProductId":1,
               "authorisationCode":"test123",
               "card":{
                  "cardNumber":"************4675",
                  "expiryDate":"1221"
               },
               "fraudResults":{
                  "fraudServiceResult":"challenged",
                  "avsResult":"U",
                  "cvvResult":"M"
               },
               "threeDSecureResults":{
                  "version":"2.2.0",
                  "flow":"challenge",
                  "cavv":"AAABBEg0VhI0VniQEjRWAAAAAAA=",
                  "eci":"9",
                  "schemeEci":"5",
                  "authenticationStatus":"Y",
                  "acsTransactionId":"3E1D57DF-8DB1-4614-91D5-B11962519703",
                  "dsTransactionId":"3E1D57DF-8DB1-4614-91D5-B11962519703",
                  "xid":"MzE5NTA3Njg2Ng==",
                  "challengeIndicator":"no-preference",
                  "liability":"issuer"
               }
            },
            "paymentMethod":"card"
         },
         "status":"CAPTURED",
         "statusOutput":{
            "isCancellable":false,
            "statusCategory":"COMPLETED",
            "statusCode":9,
            "isAuthorized":false,
            "isRefundable":true
         },
         "id":"***3092546156***"
      },
      "type":"payment.captured"
   }
]

Understand maintenance operations and status changes

Our platform links every webhook to a specific transaction with property payment.id. Depending on a transaction’s status, you can perform maintenance operations on it, such as a capture or a refund. Once you perform such a maintenance operation, the payment.id of this transaction changes, as you change the transaction status (i.e. from statusOutput.statusCode=5 to statusOutput.statusCode=91). Our platform will send webhooks for these maintenance operations, also known as online events.

However, there are specific transaction status changes triggered by our platform and not by maintenance operations (i.e. from statusOutput.statusCode=91 to statusOutput.statusCode=9). Our platform will send webhooks for these status changes as well, but not change the payment.id, also known as offline events.

Have a look at the following example to understand how:

  • The payment.id changes over the course of a transaction life cycle due to maintenance operations.
  • Our platform performs transaction status changes without changing the payment.id.
  • Our platform sends webhooks for these maintenance operation (online events) and transaction status changes (offline events).

The payment.id can change after each maintenance operation following an incremental logic. However, as this is not the case in some specific scenarios, we strongly recommend not building your business operations around it.

payment.id Maintenance operation/transaction status change/webhook statusOutput.statusCode
payment.id1 You send an authorisiation request via CreatePayment/CreateHostedCheckout

Our platform sends a webhook for online event payment.created
5
payment.id2 You capture this transaction via CapturePayment

Our platform sends a webhook for online event payment.capture_requested
91
payment.id2

Our platform receives the confirmation that the capture has been successful

Our platform updates the original capture request payment.id1 to statusOutput.status=9 and sends a webhook for offline event payment.captured

9
payment.id3

You refund this transation via RefundPayment

Our platform sends a webhook for online event refund.refund_requested

81
payment.id3

Our platform receives the confirmation that the refund has been successful

Our platform updates the original capture request payment.id2 to statusOutput.status=8 and sends a webhook for offline event payment.refunded

8

Use GetPaymentDetails to retrace the changes of the payment.id over the course of a transactions’ life cycle via property operations.id:


{
  "id": "9000003260847978002",
  "operations": [
    [...]
      "id": "payment.id1",
    [...]
      },
      "id": " payment.id2",
    [...]
      "id": " payment.id3",
    [...]
    }
  }
]

Konfigurieren von Webhooks

Zum Verwenden von Webhooks müssen Sie:

a. Webhooks in Merchant Portal konfigurieren

Zum Konfigurieren von Webhooks im Merchant Portal führen Sie diese Schritte aus:

  1. Melden Sie sich im Merchant Portal an. Gehen Sie zu Developer > Webhooks
  2. Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm "No keys generated" / "You don’t have endpoints configured at the moment."
  3. Klicken Sie auf "Generate webhooks keys". Auf dem Bildschirm werden nun sowohl der "Webhooks ID" als auch der zugehörige "Secret Webhook Key" in der Tabelle angezeigt. Der resultierende Webhook-Schlüssel wird dafür verwendet, die Nachrichten als rechtmäßige Datenübertragung zwischen unserer Plattform und Ihrem Server zu validieren. Wenn Sie eines unserer SDKs verwenden, geschieht das automatisch. Wenn Sie sich dafür entscheiden, Ihre eigene Anwendung zu erstellen, müssen Sie sicherstellen, dass Sie ihn aufnehmen
  4. Klicken Sie auf "Add webhook endpoint" und geben Sie in das Dialogfeld die Endpunkt-URL ein, die die Webhooks auf Ihrem Server empfängt. Klicken Sie auf „Confirm“. Sie können bis zu fünf URLs hinzufügen, indem Sie den Vorgang wiederholen

Wenn Sie bereits ein Paar aus Webhook-ID und geheimem Webhook-Schlüssel konfiguriert haben, wird mit einem Klick auf „Generate webhooks keys“ ein neues Paar erstellt und das bestehende sofort gelöscht

b. Webhook-Endpunkt einrichten

Um die eingehenden Webhooks in Ihrem System zu verarbeiten, müssen Sie eine Anwendung auf einem HTTPS-Endpunkt auf Ihrem Server einrichten. Die Anwendung muss Folgendes können:

  • JSON in Objekte übersetzen und Signaturen überprüfen. Unsere Server-SDKs helfen Ihnen dabei
  • Auf eine GET-Aktion antworten und im Body den Header-Wert 'X-GCS-Webhooks-Endpoint-Verification' ausgeben
  • Auf die POST-Aktion mit einem 2XX-Statuscode für alle gelieferten Events reagieren
  • Die Signatur der Nachricht validieren

Reagieren auf Webhooks

Wenn Ihr Server erfolgreich eine Webhook-Nachricht empfängt, sollte er einen HTTP-Statuscode im Bereich 2xx zurückgeben. Dadurch wird sichergestellt, dass unser System bestätigt, dass Sie den Webhook erhalten haben.

Wenn Ihr System jedoch nicht antwortet, geht unsere Plattform davon aus, dass die Übermittlung des Webhooks fehlgeschlagen ist. In unserem nächsten Kapitel erfahren Sie mehr über unsere Ausweichlösungen für dieses Szenario.

Entkoppeln Sie Ihre Geschäftslogik von der tatsächlichen Handhabung der Webhook-Nachricht. Wir empfehlen dringend, sofort mit einem 2xx-Statuscode zu antworten, bevor Sie später jegliche Folgeaktionen durchführen.

Damit wird verhindert, dass wir fälschlicherweise annehmen, dass die Webhook-Nachricht nicht zugestellt wurde

Fehlgeschlagene Versuche wiederherstellen

Wenn unser System die Nachrichten nicht an Ihre Endpunkt-URLs senden kann (oder keinen 2xx-Statuscode von Ihrem Server erhält), versucht unsere Plattform, sie zu einem späteren Zeitpunkt erneut zuzustellen. Wir werden dreimal nach dem folgenden Muster vorgehen:

Wiederholungsversuch Wiederholungszeit relativ zum ersten Zustellversuch
1 10 Minuten
2 1 Stunde
3 2 Stunden
4 8 Stunden
5 24 Stunden

Was this page helpful?

Do you have any comments?

Thank you for your response.