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
Konfigurieren von Webhooks
Zum Verwenden von Webhooks müssen Sie:
- a. die Webhooks im Merchant Portal konfigurieren
- b. Ihre Webhook-Endpunkte auf Ihrem Server einrichten
a. Webhooks in Merchant Portal konfigurieren
Zum Konfigurieren von Webhooks im Merchant Portal führen Sie diese Schritte aus:
- Melden Sie sich im Merchant Portal an. Gehen Sie zu Developer > Webhooks
- Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm "No keys generated" / "You don’t have endpoints configured at the moment."
- 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
- 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
Konfigurieren von Webhooks
Zum Verwenden von Webhooks müssen Sie:
- a. die Webhooks im Merchant Portal konfigurieren
- b. Ihre Webhook-Endpunkte auf Ihrem Server einrichten
a. Webhooks in Merchant Portal konfigurieren
Zum Konfigurieren von Webhooks im Merchant Portal führen Sie diese Schritte aus:
- Melden Sie sich im Merchant Portal an. Gehen Sie zu Developer > Webhooks
- Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm "No keys generated" / "You don’t have endpoints configured at the moment."
- 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
- 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
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
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"
}
]
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",
[...]
}
}
]
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 |