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 cancelled on merchant payment-status when the SDK/cancel API ran. On iOS, userCancelledBeforeAuthorization means no charge — a new payment is safe. networkRequestCancelled means the request may have reached VenPays — reconcile by track_id first |
| Customer does not pay | After 30 minutes in pending_merchant, pending_user, or redirecting, payment-status becomes cancelled. A PAYMENT_FAILED webhook is also sent. Do not fulfill. Start a new payment to try again |
| Unsure whether to charge again | Call payment-status with include_lifecycle: true and follow lifecycle.reattempt.decision |
| 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.