Payments
Payment errors
Handle failures using stable status values and webhook events — not UI copy alone.
Common situations
| Situation | What to do |
|---|---|
| Initiate returns 4xx | Fix request, currency, provider, or API key / connector config |
| Customer cancels checkout | Expect failed/cancelled at the engine; merchant status may show pending or failed depending on path — confirm with status API |
| HTTP timeout on initiate | Persist nothing critical until you have track_id; if you received track_id, reconcile |
Webhook PAYMENT_FAILED | Mark order failed; allow retry with a new initiation |
Native Apple Pay processing / unknown | Reconcile with backend + status APIs; do not assume failure |
Benefit gateway response codes (for example insufficient funds 51) are mapped inside the Benefit integration; surface a generic decline to customers unless you have a dedicated UX for issuer responses.
See Troubleshooting and Error codes.