Errors & FAQ
HTTP status codes
The API uses standard HTTP status codes: 2xx for success, 4xx for
request-specific problems (permissions, missing or invalid parameters), and
5xx for server-side errors.
| Code | Meaning | Description |
|---|---|---|
200 | OK | Request processed successfully |
201 | Created | A new resource was created |
400 | Bad Request | Malformed request—check the header, query, and body against the error description |
401 | Unauthorized | Missing or expired access token |
403 | Forbidden | The resource exists but you do not have rights to access it |
404 | Not Found | No resource behind the URL (e.g. an unknown ID) |
409 | Conflict | Duplicate x-idempotency-key detected |
500 | Internal Server Error | Something unexpected happened on our side |
When a request fails, read the response's error description—it explains what to fix (for example, a duplicate beneficiary or a missing conditional field).
Idempotency
Mutating endpoints accept an optional x-idempotency-key header (≤ 36
characters). If the same key is replayed, the API returns 409 instead of
performing the action twice. Many create endpoints also accept a referenceId
in the body for business-level deduplication.
Always use idempotency keys for payment and deposit creation so a network retry never results in a double action.
FAQ
My token keeps expiring—what's the best practice?
Tokens last 60 minutes. Cache the token in memory, reuse it until it nears
expiry, and re-authenticate on a 401. There is no refresh endpoint—just call
/authenticate again.
Can I test without moving real money?
Yes. Build against Sandbox (https://api.sandbox.capay.com.au). You can also
simulate deposits there
to exercise the full flow.
Why was my beneficiary or payment rejected as a duplicate?
Beneficiaries are deduplicated by clientId plus either uniquePayId or bank
details. Payments can be deduplicated by referenceId. Reuse the existing
record, or change the identifying details.
A field is "conditionally required"—when do I need it?
Some fields depend on the payment type. For example, sourceOfFunds is required
for local payments and for POBO SWIFT payments to personal beneficiaries;
invoiceNumber/invoiceDate are required for local INR payments to business
beneficiaries. The API Reference notes each condition.
How do I report an issue? Contact your Integration Support team with the request details and any reference number from the response so we can trace it.