Webhooks

Overview

Webhooks send notification for both successful and failed operations. Hence, Webhooks allow you to automise your transaction processing workflow by updating your order management systems.

Our API allows you to receive the status of a transaction anytime you wish. However, sending API calls on a regular basis requires you to build an application keeping track on all your transactions and their current status.
Our webhook solution frees you from this effort. Our system keeps track on all your transactions and notifies you whenever and status update occurs.

Our webhook solution frees you from this effort. Our system keeps track on all your transactions and notifies you whenever and status update occurs.

Best practices

For using webhooks most efficiently, follow these guidelines:

• Get a general understanding about transaction statuses and for which statuses our platform sends webhooks.
• Webhooks are asynchronous events. Therefore, they are not suitable for handling real-time events for the checkout process (i.e. to adapt your customers’ payment journey according to the transaction result). For updates in real-time, we recommend
  • Sending a GetHostedCheckoutStatus (for Hosted Checkout Page transactions) / GetPaymentDetails (for Server-to-server transactions) request.
  • Using the returnUrl as a generic, status-agnostic intermediate page. Once your system has received the transaction status, adapt the returnUrl accordingly or redirect your customers to another Url in your webshop.
• If for whatever reason your system does not process a webhook correctly, we recommend including a back-up mechanism in your business logic. This could be sending proactively a GetHostedCheckout/GetPaymentDetails request to our platform

Configuration

To use Webhooks, you need to

• a. Configure them in the Merchant Portal
• b. Define Webhooks endpoint
• c. Build a Webhooks mechanism

a. Configure Webhooks key / secret

To configure webhooks key / secret in the Merchant Portal, follow these steps:

1. Login to the Merchant Portal. Go to Developer > Webhooks.
2. If you have not configured anything yet, the screen shows "No keys generated" / "You don’t have endpoints configured at the moment."
3. Click on "Generate webhooks keys". The screen now shows both the "Webhooks ID" and the affiliated "Secret Webhook Key" in the table. The resulting webhooks key 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.

b. Define Webhooks endpoint

You can define the your Webhooks endpoint in two ways:

• In the Merchant Portal as a hard-coded value.
• Individually for each CreateHostedCheckout/CreatePayments request.

In the Merchant Portal as a hard-coded value

1. Login to the Merchant Portal. Go to Developer > Webhooks.
2. Click on "Add webhook endpoint" and enter your endpoint URL receiving the webhooks on your server in the dialogue box. Click on "Confirm". You can add up to five URLs by repeating the operation.

Individually for each CreateHostedCheckout/CreatePayments request.

Instead of hard-coding the webhooks Url in the Merchant Portal, you can add it to your CreateHostedCheckout/CreatePayment requests individually. This way, you can define the destination for the webhook for each transaction/payment.id. We strongly recommend doing this if you process transactions via different webshops.

To do so, add property feedbacks.webhookUrls to your CreateHostedCheckout/CreatePayment requests. Define up to five individual Urls as an array of strings in this property. Mind that sending any value in property feedbacks.webhookUrls will overwrite the values you have configured in your account.

Property feedbacks.webhookUrl is deprecated. We strongly recommend using feedbacks.webhookUrls instead.

c. Build a Webhooks mechanism

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 the POST action with a 2XX status code for all events delivered.
• Validate the signature on the message.

Messages

A webhook is a POST request from our platform to an HTTPS endpoint at your server. It contains information about the current status of a transaction. Our platform sends webhooks for status updates after:

• Online events that are out of your scope (authorisation results from a 3rd party provider): the result is not visible to you, as your customer is not on your website at that time.
• Offline events (i.e. capture of an authorisation, refund of an order): a change that occurs at a later point after the initial transaction has taken place.

Have a look at all the events that trigger a webhook message:

A webhook event contains a full JSON object with all relevant information you need to update your database.

You will receive these three webhooks messages separately (for CREATED, AUTHORIZATION_REQUESTED and CAPTURED) as soon as the respective status (as defined in property status) update occurs on our platform:

CREATED

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

AUTHORIZATION_REQUESTED

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

CAPTURED

[
   {
      "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).

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

Response

Whenever your server successfully receives a webhook message, it should return a HTTP status code in 2xx range. This will ensure our system acknowledges that you have received the webhook.

However, if your system does not respond, our platform will assume that the delivery of the webhook failed. Learn in our next chapter about our fallback solutions for this scenario.

Failure Recovery

If our system fails to send messages to your endpoint URLs (or does not receive a 2xx status code from your server), our platform will retry to deliver them at a later point. We will perform five times according to the following pattern:

Each retry includes a header attribute in the webhook message, called retry-count. The first attempt will have a retry-count of 0, and each retry will increase this number. This allows you to distinguish between a new webhook event and a retry of a previously failed attempt.

Testing

To ensure the webhooks you have configured work correctly, use our dedicated ValidateWebhookCredentials/SendTestWebhooks endpoints.

Credentials validation

Ensure your system accepts webhooks notification from our platform by validating your webhooks key and secret.
Our platform matches the webhooks key configured in your account and calculate a hashed empty request body based on the webhooks secret.
Send a request to our dedicated ValidateWebhookCredentials endpoint:

{
	"key": "bfa99cffb98dcad6c7f15824f5eb37",
	"secret": "0mw3LBod/3yPuI+UOmjpVmzL8U+YaTDC44haC6bzQpw="
}

Test message

Instruct our platform to send a test message to your webhooks endpoint. Upon receiving the webhook, your server should return a HTTP status code in 2xx range. Consequentially, our platform will return a HTTP status code 204 to your initial request.

Send a request to our dedicated SendTestWebhook endpoint:

{
	"url": "https://your-webhooks-url.com"
}

Our platform will return this JSON: 

{
  "apiVersion": "v1",
  "apiFullVersion": "v1.1",
  "created": "2025-03-11T14:26:49.6746458+01:00",
  "id": "a028fc60-b04c-4119-8c87-b836967e30de",
  "merchantId": "YourMerchantId",
  "payment": {
    "paymentOutput": {
      "amountOfMoney": {
        "amount": 1234,
        "currencyCode": "EUR"
      },
      "references": {
        "merchantReference": "YourMerchantReference"
      },
      "acquiredAmount": {
        "amount": 0,
        "currencyCode": "EUR"
      },
      "customer": {
        "device": {
          "ipAddressCountryCode": "XX"
        }
      },
      "cardPaymentMethodSpecificOutput": {
        "paymentProductId": 0,
        "card": {
          "cardNumber": "************0000",
          "expiryDate": "XXX",
          "bin": "999999",
          "countryCode": "XX"
        },
        "fraudResults": {
          "fraudServiceResult": "no-advice",
          "avsResult": "0",
          "cvvResult": "0"
        },
        "threeDSecureResults": {
          "eci": "0"
        },
        "acquirerInformation": {
          "name": "Test"
        }
      },
      "paymentMethod": "card"
    },
    "status": "AUTHORIZATION_REQUESTED",
    "statusOutput": {
      "isCancellable": false,
      "statusCategory": "PENDING_CONNECT_OR_3RD_PARTY",
      "statusCode": 0,
      "isAuthorized": false,
      "isRefundable": false
    },
    "id": "9999_9"
  },
  "type": "payment.test"
}