3.3 PayIn Webhook Delivery
Webhook request
- Format
- Headers
- Payload
- Signature
| Property | Value |
|---|---|
| Method | POST |
| URL | The required callback_url from Create PayIn. |
| Body | JSON object. |
Sent for terminal v2 results SUCCESS or FAILED, including a later permitted correction to a different terminal result. Intermediate PENDING states do not generate callbacks.
| Header | Value |
|---|---|
Content-Type | application/json |
X-Api-Key | The API key associated with this operation. |
X-Signature | Lowercase hexadecimal HMAC-SHA256 of the exact raw callback body, using that API key's signing secret. |
The callback has no X-Timestamp requirement.
| Field | Type | Description |
|---|---|---|
| order_id | string | Your order identifier from the create request. |
The body contains only order_id; it does not contain an event, status, transaction amount, or unique event ID. Query transaction status for the current result.
Verify the signature against the exact raw callback bytes before parsing or trusting JSON:
X-Signature = hex(HMAC-SHA256(api_secret, raw_request_body))
Compare signatures in constant time and locate the order by order_id. Use the original operation's verification material selected by X-Api-Key.
Example payload
{"order_id":"DEP-BDT-1001"}
Delivery
- Webhook URL
- Requirements
- Retries
The callback URL, API key, and signing secret are retained from creation for that operation. Rotating the key or changing configuration does not change how an existing operation's callbacks are signed. Securely retain the original verification material for outstanding operations and deliveries, and select it using X-Api-Key. Use a currently enabled key for the same merchant to make status API requests. Replays and delivery retries continue to use the original callback destination.
Respond with HTTP 200 to acknowledge delivery. HTTP 202, 204, redirects, all other non-200 responses, and network timeouts are not acknowledgements. The callback request does not follow redirects. Accept the notification promptly: the request timeout is 10 seconds.
- Verify the signature against the original raw body before trusting the notification.
- Durably record or queue the notification in your application and return HTTP 200.
- Look up your saved
transaction_idand retrieve its current status. Retry your own status lookup if it fails after you have acknowledged the callback. - Apply business effects idempotently for that order and its current result.
Delivery attempts may repeat and do not have a guaranteed order. Retries use a bounded backoff policy; they are not unlimited. If an expected notification is missing, query status and contact your integration contact rather than creating another payment.
A later permitted result correction, such as FAILED to SUCCESS, generates another notification with the same order_id body. It can arrive while an earlier delivery is still being retried. Do not permanently discard every callback after the first one for an order: use each valid notification to refresh the current status. The callback body is a prompt to read current state, not a snapshot of an earlier result or a unique event ID.
Example acknowledgment
HTTP/1.1 200 OK
Content-Type: application/json
{
"received": true
}