Skip to main content

2.3 Withdrawal callback

The required callback_url from Create withdrawal receives a POST when the withdrawal reaches a terminal v2 result: SUCCESS or FAILED, including a later permitted correction to a different terminal result. Intermediate PENDING states do not generate v2 callbacks. The callback body identifies the order; query transaction status to obtain its result.

{"order_id":"WD-BOB-1001"}
HeaderValue
Content-Typeapplication/json
X-Api-KeyThe API key associated with this operation.
X-SignatureLowercase hexadecimal HMAC-SHA256 of the exact raw callback body, using that API key's signing secret.

The callback has no X-Timestamp requirement. Verify the signature against the raw bytes before parsing JSON, compare it in constant time, then locate the order by order_id. The body contains only order_id; do not expect an event, status, or transaction amount. 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.

Handling retries and result corrections​

  1. Verify the signature against the original raw body before trusting the notification.
  2. Durably record or queue the notification in your application and return HTTP 200.
  3. Look up your saved transaction_id and retrieve its current status. Retry your own status lookup if it fails after you have acknowledged the callback.
  4. 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.

Key rotation and callback destination​

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.