Bad request
Invalid payloads, missing required fields, and amount-limit failures fall into the `400` class.
Error handling
Foxpay custom REST integrations can fail for credential, merchant-eligibility, payment-method, or payload reasons. Use the guidance on this page to classify failures quickly and decide whether to retry, reconfigure, or escalate.
Unauthorized / forbidden
Bearer token failures, KYC gates, verification rules, and payment-method restrictions map to `401` or `403` outcomes.
Not found / internal
Merchant resolution failures return `404`; transaction creation failures can surface as `500` and should be logged for escalation.
Representative runtime messages
- `API key required via Authorization: Bearer <key>`
- `Invalid custom payment initialization payload`
- `Invalid merchant ID`
- `Payment method unavailable`
- `KYC validation required`
- `Shop verification required`
- `Failed to initialize payment`
Retry guidance
- Retry transient transport or isolated `500` failures with request logging and idempotent order handling.
- Do not retry `401`, `403`, or `404` responses until the underlying configuration issue is corrected.
- Treat duplicate or replayed webhook deliveries as expected and process them idempotently.
Recovery playbook
- Auth failure: verify the Bearer key, store ownership, and environment mode.
- Merchant resolution failure: confirm the public `merchantId` rather than a local merchant reference.
- KYC or verification failure: resolve merchant eligibility before retrying production traffic.
- Pending payment confusion: rely on webhook reconciliation for authoritative completion state.