Worldline | Webhooks

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:

Sie verstehen die Bedeutung aller Statusmeldungen, die unsere Plattform in den Webhooks zurückgibt
Unser IP-Bereich ist auf die Whitelist gesetzt, wie in unserer Firewall-Dokumentation beschrieben. Damit wird sichergestellt, dass die Webhook-Funktion korrekt funktioniert

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",
    [...]
    }
  }
]

4. Configure Webhooks

To use webhooks, you need to

1. Configure them in the Back Office and
2. Set up your webhook endpoints

1. Configure webhooks in Back Office
Login to the Back Office. Go to Configuration > Technical information > API Einstellungen > Webhooks Configuration and perform the following steps:

Click on "GENERATE WEBHOOKS API KEY" or enter the desired webhooks api key manually. The "WebhooksKey" is used to validate the messages as legitimate data transfer between our platform and your server. If you use one of our SDKs, this process happens automatically. If you choose to build your own application, make sure to include it
In "Endpoint URLs", enter your webhook destination(s) on your server. Enter any additional URL in a separate line
Click on "SAVE" to confirm your settings

The image shows where to configure webhooks in the Back Office

2. Set up webhook endpoint
To process the incoming webhooks in your system, you need to build an application on an HTTPS endpoint on your server. It should be able to

Translate JSON into objects and signature verification. Our Server SDKs help you achieve this
Respond to a GET action and echo the 'X-GCS-Webhooks-Endpoint-Verification' header value in the body
Respond to the POST action with a 2XX status code for all events delivered
Validate the signature on the message

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

Webhooks