Callbacks

Callbacks allow you to receive notifications whenever the state on a transaction changes (or something significant happens to it).

To set up Callbacks for the transactions, specify a callback_url in the Integration settings or send it in the payment request. Whenever something significant happens to the transaction that we think it needs notification of (typically a state change), we make an HTTP POST request to your callback_url with the object_id in the body of the request.

Callbacks are asynchronous and not recommended for time-critical applications. It is very much possible and even likely that callbacks reach your application out-of-order and that they get duplicated. For time-critical applications, we advise using the API reconciliation to poll our system for updates.

Callback Requests

We send to your callback_url the HTTP request with the following characteristics:

a POST request;

with Request Body in JSON API format (the same as in the API);

contains the object type and id in the body of the request (not as URL-parameters).

Example

{
"data": {
    "type": "payment-invoices",
    "id": "cpi_yv1RgJ2l8ty2AxIs",
    "attributes": {
    "serial_number": "yv1RgJ2l8ty2AxIs",
    "status": "processed",
    "resolution": "ok",
    "moderation_required": false,
    "amount": 22,
    "payment_amount": 22,
    "currency": "USD",
    "service_currency": "USD",
    "reference_id": "da1b0b9d-c249-4f6e-9949-2a2f2d4b1758",
    "test_mode": true,
    "fee": 0,
    "deposit": 22,
    "processed": 1592232071,
    "processed_amount": 22,
    "refunded_amount": null,
    "processed_fee": 0,
    "processed_deposit": 22,
    "metadata": {
        "merchant_url": "https://yu.test.this"
    },
    "flow_data": {
        "action": "https://example.domain/hpp/cgi_Q0fYDFaHlqb5MCdl",
        "method": "GET",
        "params": [],
        "metadata": {
        "sid": "cgi_Q0fYDFaHlqb5MCdl",
        "token": "eyJ0eXAiOiJKV1QiLRiGCg2O...nGE7E"
        }
    },
    "flow": "hpp",
    "payment_flow": "charge",
    "created": 1592232050,
    "updated": 1592232071,
    "payload": {
        "token": null,
        "client_ip": "54.36.117.30",
        "payment_card": {
        "last": "0000",
        "mask": "512381******0000",
        "brand": "mastercard",
        "first": "512381",
        "holder": null,
        "expiry_year": "33",
        "issuer_name": "FIRST DATA CORPORATION",
        "expiry_month": "11",
        "issuer_country": "US"
        }
    },
    "description": null,
    "descriptor": null,
    "callback_url": "https://test.doc.home",
    "return_url": "https://example.com",
    "return_urls": {
        "fail": "https://example.com/sorry-page",
        "pending": "https://example.com/wait-for-it-page",
        "success": "https://example.com/thank-you-page"
    },
    "original_data": null,
    "rrn": null,
    "approval_code": null,
    "reserved_amount": null,
    "reserve_expires": null,
    "unreserved": null,
    "source": null,
    "callback_logs": []
    },
    "relationships": {
    "payment-service": {
        "data": {
        "type": "payment-services",
        "id": "payment_card_usd_hpp"
        }
    },
    "payment-method": {
        "data": {
        "type": "payment-methods",
        "id": "payment_card"
        }
    },
    "customer": {
        "data": null
      }
    },
    "links": {
    "self": "/api/payment-invoices/cpi_yv1RgJ2l8ty2AxIs"
    }
}
}

Signature

GatewayPay signs data using secret keys in the X-Signature callback request header.

The X-Signature generation algorithm

where:
$secret is one of your secret (private) keys: test or live,
$callbackData is raw JSON data,
$signature is a generation algorithm.

To be sure you got data from GatewayPay, you should generate a signature using the appropriate private key and raw JSON Сallback's data. The result is a base64 string that you should compare with Сallback's header signature. As an example:

Timeouts

GatewayPay uses 3 timeout types for Callbacks

The Connection Timeout is the timeout for making an initial connection to the callback URL's HTTP server.

Read Timeout: after the initial connection setting, still can be a possibility of an indefinite waiting period for reading data from the HTTP server.

Total Callback Timeout: in addition to the above, GatewayPay also checks the total execution time through the callback execution timeout.
The values for each timeout are as follows:

Timeout	For test connection	For test connection
Connection Timeout	10,000 ms	20,000 ms
Read Timeout	10,000 ms	20,000 ms
Execution Timeout	20,000 ms	60,000 ms

Callback delivery and auto retries

The HTTP code received in the response to Callbacks defines system further actions.

Code	Definition	Further actions
`200`	Successful delivery	No retry required, next scheduled delivery attempts cancelled
`429`	Too Many Requests, Callback is undelivered	The system forcibly stops delivery retries and cancels next scheduled delivery attempts.

If the system obtains any other status code in the response, we assume the delivery of Callback failed. As default, the failed callback request is resent with an increasing delay between each attempt:

the 1st retry 1 minute after the initial attempt,

the 2nd retry 2 minutes after the 1st retry,

the 3rd retry 3 minutes after the 2nd retry,

the 4th retry 4 minutes after the 3rd retry,

the 5th retry 5 minutes after the 4th retry,

the 6th retry 6 minutes after the 5th retry,

and so on, up to 100 attempts or up to receiving 200 or 429 HTTP status code.

Duplicate handling

Due to callback retries, your app may receive the same callback more than once. Ensure idempotency of the callback by detecting such duplicates within your app.

Idempotence is the property of certain operations in mathematics and computer science, whereby they can be applied multiple times without changing the result beyond the initial application. In short, making multiple identical requests has the same effect as making a single request.

To control processing idempotency use by examining the id parameter in callback request data since its value is unique to operation and thus identifies it.

It isn't a severe issue: if your app's actions are always idempotent, you don't need to worry much about concurrency.

Out-of-Order Delivery

Callbacks can also arrive out-of-order due to issues such as network delays or failures. However, you can determine the order of the events by examining the updated attribute of the resource sent by the callback. updated is a timestamp value that updated for every change made to the transaction.

IPs whitelist

To increase the security of the interaction between the GatewayPay platform and your server, use the white list of IP addresses.

Callback Requests#

Signature#

Timeouts#

Callback delivery and auto retries#

Duplicate handling#

Out-of-Order Delivery#

IPs whitelist#

Callback Requests

Signature

Timeouts

Callback delivery and auto retries

Duplicate handling

Out-of-Order Delivery

IPs whitelist