Amounts, errors & idempotency
The rules that apply to every endpoint.
Amounts
- Requests take amounts in major units:
1500.50is ₦1,500.50. - Responses that describe stored money (balances, statement lines, journal entries) give amounts in minor units:
150050is ₦1,500.50. Balances also include a ready-formattedformattedBalance. - Currencies are three-letter ISO codes, such as
NGN.
Idempotency
Endpoints that move money accept a reference that you choose. Sending the same reference again never moves money twice. You get the original result back with status 200, so it is always safe to retry after a timeout or a network error.
- Use a value that is unique per operation and that you can regenerate, such as your own order or invoice ID.
- Service charges check that a repeated reference describes the same charge. If it names a different customer or amount, the request is rejected with
409. Transfers and payouts simply return the original result. - Transfers and payouts generate a reference for you if you leave it out, but then you can't safely retry, so send your own.
Status codes
| Status | Meaning |
|---|---|
200 | OK. Also returned when a reference was already processed. |
201 | Created. |
202 | Accepted but not final yet, such as a payout whose outcome is still being confirmed. |
401 / 403 | Authentication failed. See Authentication. |
404 | The account, customer, service or transaction doesn't exist in this mode. |
409 | A conflict: the resource already exists, or a reference was reused for a different operation. |
422 | Validation failed, or the request can't be done (for example insufficient balance). |
500 | Something went wrong on our side. Retry with the same reference. |
Error format
Most errors carry a message:
Error
{
"message": "Insufficient balance"
}Validation failures return 422 with an errors array naming each bad field:
Validation error
{
"errors": [
{
"msg": "Invalid value",
"param": "amount",
"location": "body"
}
]
}Successful responses include status: "OK" and a human-readable message. Always branch on the HTTP status code, not on the message text, which may change.