Callback vs Webhook
A payment's outcome can reach you through up to three channels. Only one of them is authoritative. Getting this distinction right is what keeps you from fulfilling an order you were never paid for.
| Channel | Direction | Carries | Trust for fulfilment? |
|---|---|---|---|
| Callback | Browser redirect to your callbackUrl | paymentId, status (+ your callbackParams) | No — forgeable, unsigned |
| Webhook | Server-to-server POST to your webhookUrl | paymentId, status (signed) | No — a trigger only |
| Verify | Your server → POST /payments/{id}/verify | Full authoritative status and amounts | Yes |
What each one is for
- Callback — a UX hint. It tells the customer's browser (and you) which payment just resolved so you can show a result page. Every parameter on it can be edited by hand, so never fulfil from it. Hosted checkout only; API mode has no callback.
- Webhook — the reliable notification that a payment reached a terminal status, even if the customer closed the tab. It is HMAC-signed so you can trust it fired, but it deliberately carries no amounts. Treat it as "go call verify now." In API mode it is the only push channel, so it is required there.
- Verify — the single source of truth. It returns the real status plus the expected and received amounts. Fulfil only on a verified
SUCCESSorACCEPTABLE.
The rule
Callback and webhook tell you which payment to look at. Verify tells you what actually happened. Fulfil on verify, never on the trigger.
Next
- Verify Payments — the authoritative check.
- Webhooks — signature verification, retries, idempotency.
- Hosted Checkout — where the callback comes from.