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`
Concrete API error catalog
Authentication and environment
| code | status | when this is returned | how to recover |
|---|---|---|---|
No code (401) | 401 | Bearer token missing, malformed, expired, revoked, or unknown. | Confirm the `Authorization: Bearer <apiKey>` header is present and the key is active and unrevoked. |
No code (401) | 401 | API key belongs to a different merchant than the `merchantId` (or `shopId`) in the body. | Use the API key issued for the merchant in the request, or correct the merchantId. |
No code (403) | 403 | Live key used in test mode, or test key used against a production-only configuration. | Use the API key whose `allow_test_mode` / `allow_production_mode` matches the intended runtime. |
Merchant eligibility
| code | status | when this is returned | how to recover |
|---|---|---|---|
SHOP_NOT_FOUND | 404 | No store resolves from the supplied `merchantId` (or compatibility `shopId`). | Use the canonical `merchantId` from the Foxpay store dashboard. |
SHOP_NOT_VERIFIED | 403 | Store has not finished verification and is not eligible for live traffic. | Complete onboarding in the Foxpay app, or send the call against test mode. |
SHOP_MISSING_BANK_DETAILS | 400 | Direct-provider OBT requested but the store has no IBAN or beneficiary configured. | Save IBAN, BIC, and beneficiary in the Foxpay store dashboard before retrying. |
KYC_USER_ASSOCIATION_MISSING | 403 | Store record has no associated user account; KYC cannot be evaluated. | Contact Foxpay support to attach the store to its merchant user account. |
KYC_USER_MISMATCH | 403 | Store user does not match the API key owner. | Use an API key generated for the store's owning user. |
KYC_SUBMISSION_MISSING | 403 | No KYC submission exists for the merchant when one is required (always for live, sometimes for test). | Submit KYC in the Foxpay app. Test mode accepts `submitted`/`pending`/`approved`; live requires `approved`. |
Payment initialization
| code | status | when this is returned | how to recover |
|---|---|---|---|
VALIDATION_ERROR | 400 | Request body fails Zod schema validation: missing or wrong-typed fields, IBAN regex mismatch, currency length, etc. | Inspect the `details` field returned in the response. Fix the named fields and retry. |
PAYMENT_NOT_FOUND | 404 | Status / bank-details lookup ran against a `paymentId` that does not exist for the resolved merchant. | Persist `paymentId` from the initializer response and use that exact value for follow-up reads. |
No code (403) | 403 | Requested `paymentMethod` is not enabled on the store for the active mode. | Enable the method in the Foxpay store dashboard for the target environment. |
Open Bank Transfer
| code | status | when this is returned | how to recover |
|---|---|---|---|
CALYTICS_NOT_CONFIGURED | 400 | OBT direct-provider call routed to an environment whose Calytics PSP credentials are not configured on Foxpay. | Confirm the request is routing to the intended environment; if so, contact Foxpay support to provision Calytics credentials. |
PROVIDER_MODE_DISABLED | 403 | OBT direct-provider call requested a Calytics mode (test or production) that is not toggled on for the store. | Enable Calytics for the target mode on the store's Open-Bank-Transfer payment-method configuration. |
CALYTICS_FOXPAY_TRANSACTION_REQUIRED | 500 | OBT direct-provider call could not create or attach a Foxpay transaction record. | Retry once. If it persists, escalate with the request id from the response. |
CALYTICS_INITIATION_FAILED | 502 | Foxpay reached Calytics but the upstream initiation call did not return a usable session. | Inspect the message field for the Calytics-side reason, confirm country/recipient configuration, and retry. If sending payer context, send both senderName and senderIban. |
CALYTICS_OBT_PERSIST_FAILED | 500 | Calytics returned a session but Foxpay could not persist the OBT transaction row. | Retry. If it persists, escalate with the request id. |
FEATURE_NOT_AVAILABLE | 400 | A previously-gated combination is rejected. As of 2026-04-29, `open_bank_transfer` + hosted checkout is supported and this code is no longer emitted for that pairing. | Re-read the documentation for the requested method/checkout-mode combination and adjust. |
Internal
| code | status | when this is returned | how to recover |
|---|---|---|---|
INTERNAL_ERROR | 500 | Unexpected exception inside the Foxpay route. The request id appears in server logs. | Retry once. If it persists, contact support with the timestamp and any returned request id. |
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.
- OBT direct-provider failure: confirm Calytics is enabled for the target mode and that country and optional sender data pass validation.
- Pending payment confusion: rely on webhook reconciliation for authoritative completion state.