Callbacks

Introduction

A callback is a system message sent from the ecommpay payment platform to the merchant's web service. It contains information about a specific event in the payment platform that usually takes place in the context of processing a payment or storing customer payment data.

Callbacks allow merchants to receive information about various events. Along with that, the callback payload as well as the conditions of sending callbacks can be flexibly configured: you can define what data the callback should contain as well as specify in what cases, in what format, and where it should be sent. This article covers general information about callbacks, the procedure and special aspects of working with them.

A callback is a system message with information about a specific event sent from the ecommpay payment platform to the merchant's web service. This article covers general information about callbacks, the procedure and special aspects of working with them.

Callback types

Callbacks can be roughly divided into two groups: prescriptive (that require certain actions from the web service side) and informational (that are sent for informational purposes).

Callbacks can be roughly divided into two groups: prescriptive and informational.

Prescriptive callbacks are triggered by the necessity of a certain action: for example, specific data has to be sent to the payment platform, the customer must be provided with specific information or redirected to third-party services, and so on. Such callbacks always contain intermediate information, and you cannot opt out of receiving them since timely response to this category of callbacks is indispensable for payments to be processed correctly.

Prescriptive callbacks are triggered by the necessity of a certain action: for example, specific data has to be sent to the payment platform, the customer must be provided with specific information or redirected to third-party services, and so on. Such callbacks always contain intermediate information, and you cannot opt out of receiving them.

Informational callbacks are triggered by such events as the change of the payment status or the generation of the payment card token. These callbacks can contain intermediate or final payment information, and you can opt out of receiving them (selectively or fully).

Common use cases

Callbacks are typically triggered by the following events.

• Payment status has changed.

  In this case, callbacks can contain intermediate or final information about payment processing.

  Figure: Example of callback data indicating that the payment has been assigned an intermediate status

  {
      "project_id": 42,
      "customer": {
          "id": "6361696170"
      },
      "payment": {
          "id": "456789",
          "type": "purchase",
          "status": "awaiting capture",      // intermediate payment status
          "date": "2022-01-11T13:00:40+0000",
          "method": "card",
          "sum": {
              "amount": 20000,
              "currency": "USD"
          },
          "description": ""
      },
      "account": {
          "number": "431422******0056 ",
          "type": "visa",
          "card_holder": "ARTHUR EDDINGTON",
          "expiry_month": "03",
          "expiry_year": "2022"
      },
      "operation": {
          "id": 2777000002350,
          "type": "auth",
          "status": "success",
          "date": "2022-01-11T13:00:40+0000",
          "created_date": "2022-01-11T13:00:37+0000",
          "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
          "sum_initial": {
              "amount": 20000,
              "currency": "USD"
          },
          "sum_converted": {
              "amount": 20000,
              "currency": "USD"
          },
          "provider": {
              "id": 120,
              "payment_id": "224750650",
              "date": "2022-01-11T13:00:39+0000",
              "result_code": "000",
              "result_message": "Approved",
              "auth_code": "505050",
              "endpoint_id": 120
          },
          "code": "0",
          "message": "Success",
          "description": "SUCCESS",
          "eci": "00"
      },
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
  }

  Figure: Example of callback data indicating that the payment has been assigned a final status

  {
      "project_id": 42,
      "payment": {
          "id": "456789",
          "type": "purchase",
          "status": "success",      // final payment status
          "date": "2022-01-11T15:54:40+0000",
          "method": "card",
          "sum": {
              "amount": 20000,
              "currency": "USD"
          },
          "description": ""
      },
      "account": {
          "number": "431422******0056 ",
          "type": "visa",
          "card_holder": "ARTHUR EDDINGTON",
          "expiry_month": "03",
          "expiry_year": "2022"
      },
      "customer": {
          "id": "6361696170"
      },
      "operation": {
          "id": 7178000006597,
          "type": "capture",
          "status": "success",
          "date": "2022-01-11T15:54:40+0000",
          "created_date": "2022-01-11T15:54:39+0000",
          "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
          "sum_initial": {
              "amount": 20000,
              "currency": "USD"
          },
          "sum_converted": {
              "amount": 20000,
              "currency": "USD"
          },
          "provider": {
              "id": 120,
              "payment_id": "227307324",
              "date": "2022-01-11T15:54:40+0000",
              "auth_code": "919372",
              "endpoint_id": 120
          },
          "code": "0",
          "message": "Success"
      },
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
  }

• Actions on the web service side are required.

  In this case, callbacks usually contain information for redirecting customers, displaying specific information to them, or specifying additional data necessary for payment processing.

  Figure: Example of callback data indicating that the customer redirection is required

  "redirect_data": {
      "body": {},
      "method": "GET",
      "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
    }

  Figure: Example of callback data indicating that displaying a QR code to the customer is required

   "display_data": [
              {
                  "type": "qr_data",
                  "title": "QR code",
                  "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
              },
              {
                  "type": "add_info",
                  "title": "QR Code Timeout",
                  "data": "600"
              }
          ]

• Payment card token has been generated or deleted.

  In this case, callbacks contain information about events related to payment card tokens (such as token generation or deletion).

  Figure: Example of callback data indicating that a payment card token has been generated

  {
      "general":{
      "project_id":42,
      "customer_id":6361696170,
      "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ",
          "request": {
  			"id": "3c7f53fdbb5b8c96f9707457d75f",
  			"action": "tokenize",
  			"status": "success"
          },
      "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654",
      "token_created_at":"2021-01-28 13:30:57",
      "token_status":"active"
  }

Configuring for projects

Callbacks for the merchant's production projects are usually set up during the integration of the web service with the ecommpay payment platform. Along with that, to change callback settings, you can always use the capabilities of Dashboard (details), specify certain parameters in payment requests, and when necessary, contact the ecommpay technical support specialists.

The following properties can be configured on the part of the merchant:

Callbacks for the merchant's production projects are usually set up during the integration of the web service with the ecommpay payment platform. Along with that, you can use the capabilities of Dashboard and the Gate API and contact our technical support to configure the following properties:

• Requirement for sending callbacks.

  Callbacks can be triggered by all events or only by the events that correspond to the specified set of conditions. Such conditions include certain event types, payment methods as well as types and statuses of payments and operations. For example, callbacks can be disabled for the completed payouts and enabled for the declined ones. This allows you to promptly receive only the necessary information.

  Callbacks can be triggered by all events or only by the events that correspond to the specified set of conditions. Such conditions include certain event types, payment methods as well as types and statuses of payments and operations.

• URLs for delivering callbacks.

  Callbacks triggered by different events can be sent to different web service URLs with regard to the event type, the payment method, the payment type and status. For example, callbacks with final information about declined payments can be sent to one URL, while callbacks with final information about completed payments can be sent to another URL.

  Callbacks triggered by different events can be sent to different web service URLs with regard to the event type, the payment method, the payment type and status.

• Delay time for sending callbacks.

  If necessary, callbacks can be sent with a delay of up to 600 seconds (inclusive), for example, to streamline the handling of these callbacks on the web service side.

  If necessary, callbacks can be sent with a delay of up to 600 seconds (inclusive).

• Set of parameters.

  For more convenient handling of callbacks on the web service side, you can vary their payload by adding and removing parameters, changing their names, and setting the requirement to include parameters with empty values. At the same time, you cannot change the callback structure and remove required parameters.

  Bear in mind that certain parameters can be required for all or only specific types of callbacks. The required parameters are always included in callbacks, while the optional ones are only sent in cases when the corresponding information has been received, or when sending such parameters with empty values has been set up.

  Thus, callbacks triggered by the same events can include different information depending on the settings.

  You can vary the callback payload by adding and removing parameters, changing their names, and setting the requirement to include parameters with empty values. At the same time, you cannot change the callback structure and remove required parameters.

  Figure: Example of standard callback data indicating that the one-time purchase has been completed

  {
      "account": {
          "number": "431422******0056 ",
          "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
          "type": "visa",
          "card_holder": "ARTHUR EDDINGTON",
          "expiry_month": "11",
          "expiry_year": "2027"
      },
      "customer": {
          "id": "6361696170",
          "phone": "441223262463"
      },
      "payment": {
          "date": "2022-11-11T13:02:42+0000",
          "id": "456789",
          "method": "card",
          "status": "success",
          "sum": {
              "amount": 40000,
              "currency": "USD"
          },
          "type": "purchase",
          "description": ""
      },
      "project_id": 42,
      "operation": {
          "id": 969000002636,
          "type": "sale",
          "status": "success",
          "date": "2022-11-11T13:02:42+0000",
          "created_date": "2022-11-11T13:01:45+0000",
          "request_id": "c6eed1eb14c6290088cbc0be4667c",
          "sum_initial": {
              "amount": 40000,
              "currency": "USD"
          },
          "sum_converted": {
              "amount": 40000,
              "currency": "USD"
          },
          "provider": {
              "id": 408,
              "payment_id": "330157196",
              "date": "2022-11-11T13:02:32+0000",
              "auth_code": "",
              "endpoint_id": "612266625"
          },
          "code": "0",
          "message": "Success",
          "eci": "07"
      },
      "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  }

  Figure: Example of customised callback data indicating that the one-time purchase has been completed

  {
      "account": {
          "number": "431422******0056 ",
          "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
          "type": "visa",
          "card_holder": "ARTHUR EDDINGTON",
          "id": 45678,
          "expiry_month": "11",
          "expiry_year": "2027"
      },
      "customer": {            // object with extended customer information
          "id": "6361696170",
          "email": "siraseddington@gmail.com"
          "phone": "441223262463",
          "first_name": "Arthyr",
          "last_name": "Eddington"
      },
      "payment": {
          "date": "2022-11-11T13:02:42+0000",
          "id": "456789",
          "method": "card",
          "status": "success",
          "sum": {
              "amount": 40000,
              "currency": "USD"
          },
          "type": "purchase",
          "description": ""
      },
      "project_id": 42,
      "operation": {
          "id": 969000002636,
          "type": "sale",
          "status": "success",
          "date": "2022-11-11T13:02:42+0000",
          "created_date": "2022-11-11T13:01:45+0000",
          "request_id": "c6eed1e088cbc0be4667c",
          "sum_initial": {
              "amount": 40000,
              "currency": "USD"
          },
          "sum_converted": {
              "amount": 40000,
              "currency": "USD"
          },
          "provider": {
              "id": 408,
              "payment_id": "330157196",
              "date": "2022-11-11T13:02:32+0000",
              "auth_code": "",
              "endpoint_id": "612266625"
          },
          "code": "0",
          "message": "Success",
          "eci": "07"
      },
      "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...=="
  }

Managing callbacks for individual payments

When processing payments via Gate, you can set up the URLs where callbacks will be delivered to, the requirement, and the delay time for sending callbacks. To do this, use the following parameters when sending payment requests:

• merchant_callback_url (passed in the general object)—the callback URL for this specific request;
• force_disable (passed in the callback object)—an indicator for disabling callbacks (possible values: true, for disabling callbacks with information about the given payment, and false, for enabling these callbacks).
• delay (passed in the callback object)—the delay time for sending callbacks, in seconds (possible values are 0 to 600; for example 42);

To learn if these parameters can be used in requests to certain endpoints, see the Gate API specification.

{
    "general":{
        "project_id":42,
        "payment_id":"456789",
        "merchant_callback_url":"https://example.com",
        "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "customer":{
        "ip_address":"192.0.2.32",
        "id":"6361696170"
    },
    "payment":{
        "amount":40000,
        "currency":"USD",
        "callback":{
            "delay":42                // delay time set to 42 seconds
        }
    },
    "card":{
        "pan":"4314220000000056",
        "year":2027,
        "month":11,
        "card_holder":"ARTHUR EDDINGTON",
        "cvv":"123"
    }
}

Handling callbacks

A callback is an HTTP POST message sent to the URL provided by the merchant. The procedure of responding to each callback on the web service side consists of the following steps:

The procedure of responding to each callback on the web service side consists of the following steps:

1. Accept and verify the callback.

   Callbacks should be accepted only if they have been sent from the payment platform's IP addresses provided by the ecommpay technical support specialists. Along with that, it is recommended not to limit the waiting time for callbacks since different events can occur at different times while callbacks can be sent with a specified delay.

   The callback sender and data integrity should be validated by way of verifying the signature included in every callback. For more information, see Signature generation and verification.

   Callbacks should be accepted only if they have been sent from the payment platform IP addresses provided by the ecommpay technical support specialists, and the waiting time for callbacks should not be limited. Along with that, data integrity should be validated by way of verifying the signature included in every callback.

2. Confirm the callback receipt.

   For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes. If no errors have been detected upon the receipt, the response code should be 200 OK. In other cases, the response code should correspond to the error type: for example, use HTTP 400 Bad Request if a parameter string could not be converted into an array or HTTP 500 Internal Server Error if the callback has been received at an incorrect URL of the web service.

   For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes. If no errors have been detected upon the receipt, the response code should be 200 OK. In other cases, the response code should correspond to the error type: for example, HTTP 400 Bad Request.

   If the 200 OK response has not been received from the web service, the callback will be sent again regardless of the error type.

3. Perform the required actions.

   Upon the receipt of prescriptive callbacks, the actions that are stated in these callbacks as required should be performed; and upon the receipt of informational callbacks, the actions that correspond to the aspects of the web service operation should be performed (for example, customer notification).

Resending callbacks

If the information about a callback receipt error has been communicated to the payment platform or the callback receipt has not been confirmed, this callback is sent again. Keep in mind that the data in such callbacks can change due to the changes of the corresponding information in the payment platform: for example, if a payment status changes, all subsequent callbacks contain the newly assigned status.

Generally, resending callbacks is carried out as follows:

If the information about a callback receipt error has been communicated to the payment platform or the callback receipt has not been confirmed, this callback is sent again. Resending callbacks is carried out as follows:

1. 6 attempts at an increasing interval of 10 to 60 seconds. The interval increases by 10 seconds at each attempt.
2. 58 attempts at an increasing interval of 84 seconds to 2.5 hours.

   The interval, measured in seconds, is increased according to the formula 70 + 10 × 1.12n − 4 where n is the sequence number of the attempt.

3. 56 attempts every 4 hours until a total of 120 attempts is reached. After that, callbacks triggered by the given event are no longer sent.

This order can slightly change depending on the load on servers and communication channels, but in general the time span for automatic callback delivery attempts does not exceed 11 days. You can change this order via the ecommpay technical support specialists.

You can change this order via the ecommpay technical support specialists.

In addition to automatic resending of callbacks, you can also initiate one-time resending via Dashboard and Telegram bot if necessary.

Troubleshooting

There can be cases when callbacks are not received at the specified URLs for various reasons. These situations and the ways to resolve them can be divided into the following groups:

• There are no callbacks triggered by any of the events.

  This can happen because certain requests and events have not been initiated in the platform, or issues with communication channels have been detected, or the web service URLs are invalid, or callbacks have been disabled in the project.

  In such cases, it is recommended to proceed as follows:

  1. Ensure that the correct requests (i.e. they do not disable callbacks) were sent from the web service and accepted in the platform. It may be necessary to send a test request, for example, to generate a payment card token.
  2. If requests are accepted in the platform, but callbacks are still not received, check if the URLs for delivering callbacks are correct. If problems are found, fix the URLs or replace them with the correct ones—on your own via Dashboard, or with the help of the ecommpay technical support specialists.
  3. If the previous steps did not help, contact the ecommpay technical support specialists.
• There are no callbacks triggered by specific event types.

  This can happen for the following reasons: there are no events of such types, web service URLs are invalid, or callbacks have been disabled for such event types.

  In such cases, it is recommended to proceed as follows:

  1. Ensure that the events of the types for which callbacks are not received have been initiated. You can do this by using payment information tabs in the Dashboard interface.
  2. Check the correctness of the URLs for receiving callbacks triggered by the corresponding event types. If problems are found, fix the URLs or replace them by the correct ones—on your own via Dashboard, or with the help of the ecommpay technical support specialists.
  3. If the previous steps did not help, contact the ecommpay technical support specialists.
• There are no callbacks for a specific operation.

  This can happen because the callback object in the request for processing the operation contains the force_disable parameter with the true value.

  In this case, you can check the operation status via Gate using requests for checking current payment information (details), Dashboard, and Telegram bot.

There can be cases when callbacks are not received at the specified URLs for various reasons: for example, certain requests and events have not been initiated in the platform, or issues with communication channels have been detected, or the web service URLs are invalid. The merchant can handle such situations as follows:

1. Ensure that callbacks are not disabled for the whole project in use or for certain event types in the project.
2. Ensure that the correct requests (i.e. they do not disable callbacks) were sent from the web service and accepted in the platform. It may be necessary to send a test request.
3. Check if the URLs for delivering callbacks are correct. If problems are found, fix the URLs or replace them by the correct ones—on your own via Dashboard, or with the help of the ecommpay technical support specialists.
4. If the previous steps did not help, contact the ecommpay technical support specialists.

Callback parameters for payments and operations

The set of parameters sent in callbacks with payments and operations information can be standard or customised for separate projects. The following table contains the standard set of parameters.

Callback parameters for tokens

The set of parameters sent in callbacks triggered by actions with tokens (for example, creating or deleting a token) can be standard or customised for separate projects. The following table contains the standard set of parameters.