Callbacks & Webhooks
Mercuryo sends a POST request to your callback URL every time a transaction status changes.
Setup
- Sign in to the Dashboard.
- Go to Widgets → select your widget.
- Fill in the Callback URL field with your server endpoint.
- Copy the Sign Key — you'll need it to verify incoming callbacks.
Go to Widget Callbacks to browse callback history, resend a callback, or send a test callback.
Callback Payload
The callback uses the standard Mercuryo callback format — see Callback Reference for the full payload schema and examples. For a native Apple Pay transaction, the data object contains:
"type": "buy""payment_method": "mobile_pay""method_code": "apple"
data.merchant_transaction_id contains your identifier, if you sent it in the payment request.
The status field reflects the current state of the transaction. See Transaction Statuses for all statuses and which of them are final.
After a successful payment, Mercuryo sends the purchased crypto to the user's wallet in a separate withdraw transaction, which has its own callbacks — see Transaction Statuses.
Callback Delivery & Retry Logic
Mercuryo considers a callback successfully delivered when your server responds with HTTP 200. For any other response code, the system retries automatically:
| Attempt | Delay |
|---|---|
| 1st retry | 60 seconds |
| 2nd retry | 120 seconds |
| 3rd retry | 240 seconds |
| Nth retry | 2^(N−1) × 60 seconds (N = attempt number, starting at 1) |
| Maximum interval | 4 hours |
| After reaching max interval | Every 4 hours for 3 days |
| Total retry period | 3 days |
You can also manually resend callbacks from the Dashboard.
Callbacks for the same transaction can arrive more than once: process them idempotently.
Callback Signature Verification
Each callback includes an X-Signature header. Verify it before processing the callback — see Signature.