401 on payment initialization
Likely cause: Missing Bearer token, expired API key, or key-store mismatch.
First action: Check the `Authorization` header, confirm the key belongs to the requested merchant, and verify the key is active.
Troubleshooting
These are the first-response playbooks for the most likely custom integration failures. The goal is to help merchants and support teams decide quickly whether to retry, fix configuration, or escalate.
404 invalid merchant ID
Likely cause: The provided `merchantId` or compatibility `shopId` does not resolve to a store.
First action: Verify the canonical merchant identifier copied from Foxpay, not a local merchant reference.
403 KYC or verification block
Likely cause: The store is not eligible for the requested payment mode or has not completed KYC requirements.
First action: Check KYC completion, store verification status, and whether the request should be using test mode instead of production.
Payment method unavailable
Likely cause: The requested payment method is not enabled for the store or for the current mode.
First action: Confirm the store has the relevant payment method active and available in the intended environment.
Buyer remains pending
Likely cause: Polling is running, but reconciliation has not reached a final state yet.
First action: Use polling for buyer feedback, but rely on backend reconciliation and webhook handling for authoritative completion state.
Retry guidance
- Retry transport or transient `500` failures cautiously and log the original request context.
- Do not blindly retry `401`, `403`, or `404` cases without fixing the underlying configuration issue first.
- Treat webhook deliveries as potentially duplicated and process them idempotently.
Escalation threshold
- Escalate when a valid request repeatedly fails without a clear config issue.
- Escalate when webhook verification or delivery behavior contradicts the documented contract.
- Escalate when the buyer-facing state and backend reconciliation state diverge unexpectedly.