Webhooks

Introduction

Webhooks are messages sent from our platform to your server. These messages inform you about the result of your transactions or about status changes that happen at a later point (i.e. captures, refunds).

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.

Understand Webhooks

A webhook is a POST request from our platform to an HTTPS or HTTP 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.

This example contains three different events (defined in property status): corresponding to a respective transaction status update: CREATED, AUTHORIZATION_REQUESTED and CAPTURED.
You will receive these three webhooks messages separately as soon as the respective status update occurs on our platform:

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

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 settings > 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

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

Respond to Webhooks

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.

Recover failed attempts

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: