Skip to content

Callbacks

Callbacks allow you to receive notifications whenever the state on an object changes (or something significant happens to that object).

To set up Callbacks for the object, set a callback_url in the Integration settings or send it in the payment request. Whenever something significant happens to the object 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.

Note

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.

Configure Callbacks

To configure your callbacks, go to Commerce Settings > Integration > Callbacks and add a callback URL.

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 public API);
  • contains the object type and id in the body of the request (that not added as a URL-parameters).

Here is an example of payment-request operation callback data:

Example

{  
"data":{  
    "type":"payment-invoices",
    "id":"cpi_TV465FXkbGch3GNe",
    "attributes":{  
        "status":"processed",
        "resolution":"ok",
        "moderation_required":false,
        "amount":3.33,
        "payment_amount":3.33,
        "currency":"USD",
        "service_currency":"USD",
        "reference_id":"Order ID 1",
        "test_mode":true,
        "fee":0,
        "deposit":3.33,
        "processed":1564153164,
        "processed_amount":3.33,
        "processed_fee":0,
        "processed_deposit":3.33,
        "metadata":[  

        ],
        "flow_data":{  
            "action":"api.paymega.io/hpp/{guid}",
            "method":"GET",
            "params":[  

            ]
        },
        "flow":"hpp",
        "created":1564153017,
        "updated":1564153164,
        "payload":{  
            "payment_card":{  
            "last":"1111",
            "mask":"511111******1111",
            "brand":"mastercard",
            "first":"511111",
            "issuer_name":"PUBLIC JOINT-STOCK COMPANY COMMERCIAL BANK PRIVATBANK",
            "issuer_country":"UA"
            }
        },
        "description":null,
        "callback_url":null
    },
    "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_TV465FXkbGch3GNe"
    }
}
}

Signature

Paymega sign data using secret keys. You can obtain them in Account Integration settings. All callbacks are signed live or test secret key according to the chosen mode.

Paymega sends signature in X-Signature callback request header. The signature is created by the next algorithm:

$signature = base64_encode(sha1($secret . $callbackData . $secret, true));
where the $secret is one of your secret keys: test or live,
$callbackData is raw JSON data.

Note

To be sure you got data from Paymega, you should compute the signature using an appropriate secret key and compare with ones from Paymega callback data.

Timeouts

There are 3 timeouts for Callbacks in Paymega:

  1. The Connection Timeout is the timeout for making an initial connection to the callback URL's HTTP server.
  2. Read Timeout: After the initial connection setting, still can be a possibility of an indefinite waiting period for reading data from the HTTP server.
  3. Total Callback Timeout: In addition to the above timeouts, PayCore.io also checks the total execution time through the callback execution timeout.

The values for each timeout are as follows:

Timeout For Test site For Live site
Connection Timeout 10,000 ms 20,000 ms
Read Timeout 10,000 ms 20,000 ms
Execution Timeout 20,000 ms 60,000 ms

Automatic Retries

When you successfully process callback request, you must return 200 HTTP status code. Our application ignores any other data return by callback.

If the callback returns status code other then 200, it is assumed the delivery of request 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 HTTP status code.

We can set up the delay between retries and number of attempts

Contact our support team that we may find the most appropriate settings for your account.

Note

Also, you could resend a callback manually if you wish to sync your data immediately. Go to Transaction overview > Callbacks, select the callback and use the button on the right side to resend it.

Resend Callback

Duplicate Handling

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

Definition

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 is not a severe issue if your app's actions are always idempotent: in that case, you don't need to worry much about concurrency.

Batching

We batch Callbacks for the same object that are very close together. So if a payment goes from a state created to invoked to processed immediately, you only receive one Callback, and when you look up the status of the payment, it will be processed.

It prevents us from overwhelming your server(s) with HTTP requests, and it prevents your app from having to build complicated logic around subsequent state changes. Your app should only care about the latest state of the object.

Out-of-Order Delivery

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

IPs whitelist

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

Learn More →