Skip to main content

S2S APM callbacks

Payment Platform sends a callback (webhook), an HTTP POST to your server, every time an S2S APM transaction reaches a result. The callback is the source of truth for the final transaction status, not the synchronous response and not the payer's return to your site.

For the full list of parameters a callback can carry, see S2S APM callback parameters.

Callback URL​

Callbacks go to your notification URL: the notification_url that the Payment Platform administrator configures for your merchant in the admin panel. The administrator can also set a separate notification URL for test payments.

info

You can also send callback_url in a SALE, DEBIT2VIRTUAL, DEBIT2VIRTUAL_CALC, CREDIT2VIRTUAL or CREDIT2CRYPTO request, for example callback_url=https://example.com/callback. It replaces notification_url for that payment: every callback of the payment goes there, including the callbacks of a later CAPTURE, VOID, CREDITVOID or chargeback. It must be a valid URL, not longer than 255 characters, otherwise the request returns a validation error.

warning

Set the URL before your first payment. If neither a notification URL nor callback_url is set, Payment Platform sends no callbacks for the payment, also not later when a URL is added.

Request format​

PropertyValue
MethodPOST
Content typeapplication/x-www-form-urlencoded
Parameters without a valueNot sent
Nested valuesSent with bracket keys, for example custom_data[key]=value
DatesYYYY-MM-DD HH:MM:SS

Responding to a callback​

Return any HTTP 2xx status to confirm that you received the callback. The response body is not checked.

Send the response first and process the data afterward. Callbacks that time out count toward URL blocking.

Give the exact URL that accepts the POST. If your server redirects the request, for example from http to https or to add a trailing slash, the callback data is lost.

Retries​

If your endpoint returns a status other than 2xx, or the request fails, Payment Platform sends the callback again several times, with increasing intervals. Delivery stops after the first 2xx response. Your administrator can also resend a callback from the admin panel. If a callback does not arrive, request the transaction status with GET_TRANS_STATUS.

The same callback can reach you more than once, so process callbacks idempotently: check trans_id, action and status before you update an order, and for CREDITVOID also creditvoid_id, because every partial refund of a payment has the same trans_id.

One payment produces several callbacks, for example a REDIRECT callback, then the final one, then the callbacks of a later CAPTURE or CREDITVOID. A retried callback can arrive after a newer one, so do not replace a final status with an intermediary one.

URL blocking​

warning

If callbacks to your notification URL time out five times within five minutes, Payment Platform stops sending callbacks to that URL for your account for 15 minutes. The callbacks due during the block are not lost: they are sent later, as retries.

The block lifts automatically after 15 minutes. Your Payment Platform administrator can turn off URL blocking for your account.

Callback events​

You receive a callback for the actions below, with these result values. The status values are listed in Possible transaction results and statuses.

actionresult in the callback
SALESUCCESS, DECLINED, REDIRECT, UNDEFINED
CAPTURE, VOIDSUCCESS, DECLINED, UNDEFINED
CREDITVOIDSUCCESS, DECLINED, WAITING, UNDEFINED
DEBIT2VIRTUAL, CREDIT2VIRTUALSUCCESS, DECLINED, REDIRECT, UNDEFINED
DEBIT2VIRTUAL_CALCSUCCESS, with status = PREPARE: the commission is calculated and the payment waits for confirmation
CREDIT2CRYPTOSUCCESS, DECLINED, REDIRECT, INIT, UNDEFINED
CHARGEBACKSUCCESS. Sent only for a successful chargeback.

REDIRECT means the payer must complete an action on the provider's side. The final result arrives in a later callback.

To tell whether a callback is final, check status: SETTLED, DECLINED, REFUND, VOID, REVERSAL and CHARGEBACK are final; PREPARE, REDIRECT, 3DS and PENDING are intermediary. When the funds of a two-stage payment are held, PENDING changes only when the payment is captured or released. See Possible transaction results and statuses. A CHARGEBACK callback carries status = CHARGEBACK.

Verifying the callback​

Every callback carries a hash. Calculate it on your side and compare it with the received value before you trust the data. S2S APM callbacks are signed from the values of the callback itself, see Callback signature. CREDIT2VIRTUAL and CREDIT2CRYPTO use the Credit2Virtual callback signature. A SALE paid in cryptocurrency is signed with md5(strtoupper(strrev(email).PASSWORD.trans_id)), where email is the payer's email and trans_id is the trans_id of the payment. If SHA256 is set for your account, sha256 replaces md5. See also Hash signature.

What the callback carries​

Every callback contains these parameters:

ParameterDescription
actionThe action the callback refers to: SALE, CAPTURE, CREDITVOID, VOID, DEBIT2VIRTUAL, DEBIT2VIRTUAL_CALC, CREDIT2VIRTUAL, CREDIT2CRYPTO, CHARGEBACK. See Callback events
resultResult of the operation: SUCCESS, DECLINED, REDIRECT, UNDEFINED. CREDITVOID can also return WAITING, CREDIT2CRYPTO can also return INIT
statusActual status of the transaction in Payment Platform: SETTLED, PENDING, PREPARE, 3DS, REDIRECT, DECLINED, REFUND, REVERSAL, VOID, CHARGEBACK
order_idTransaction ID in the Merchant's system
trans_idTransaction ID in Payment Platform
hashSignature used to validate the callback, see Verifying the callback

The other parameters depend on the action and the result, and some are sent only if they are enabled for your account in the admin panel, under Configuration → Protocol Mapping, option Add Data to: Callback (ask your account manager), for example connector_name, rrn, approval_code, gateway_id, extra_gateway_id, merchant_name, mid_name, merchant_key, issuer_country, issuer_bank, arn, extended_data, brand, plus the exchange and payer data. The full list: Optional parameters.

Where to find each parameter: