Skip to main content

S2S CARD callbacks

Payment Platform sends a callback (webhook), an HTTP POST to your server, every time an S2S CARD 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 CARD 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, DEBIT, RECURRING_SALE, RECURRING_DEBIT, CREDIT2CARD or CARD2CARD 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. If the URL is not valid, the request returns a validation error (400).

warning

Set the URL before your first payment: it is mandatory if your account supports 3D-Secure. 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. The URL must not be longer than 255 characters.

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 Transaction results and statuses.

actionresult in the callback
SALE, RECURRING_SALESUCCESS, DECLINED, REDIRECT, UNDEFINED
DEBIT, RECURRING_DEBITSUCCESS, DECLINED, REDIRECT, UNDEFINED
CARD2CARDSUCCESS, DECLINED, REDIRECT, UNDEFINED
CAPTURE, VOIDSUCCESS, DECLINED, UNDEFINED
CREDITVOIDSUCCESS, DECLINED, WAITING, UNDEFINED
CREDIT2CARDSUCCESS, DECLINED, REDIRECT, UNDEFINED
CHARGEBACKSUCCESS. Sent only for a successful chargeback.

REDIRECT means the payer must complete a redirect or 3DS step, see Redirect / 3DS handling. The final result arrives in a later callback.

To tell whether a callback is final, check status: SETTLED, DECLINED, REFUND, VOID, CHARGEBACK and REVERSAL are final, the other statuses are intermediary.

If cascading is enabled for your account, a declined payment can be retried automatically through another route. You then receive the callback of the last attempt, and its trans_id can differ from the one in the synchronous response, so match the callback to your order by order_id. See SALE request.

There is no callback with action = RETRY. The result of a RETRY request arrives as a RECURRING_SALE callback for the retried payment.

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 CARD callbacks are signed with Formula 2, except CREDIT2CARD, which uses Formula 6. See also Hash signature.

What the callback carries​

Every callback contains these parameters:

ParameterDescription
actionThe action the callback refers to: SALE, RECURRING_SALE, CAPTURE, CREDITVOID, VOID, DEBIT, RECURRING_DEBIT, CREDIT2CARD, CARD2CARD, CHARGEBACK. See Callback events
resultResult of the operation: SUCCESS, DECLINED, REDIRECT, UNDEFINED. CREDITVOID can also return WAITING
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: