Get started

Errors and idempotency

Errors come back with an HTTP status and a code you can act on.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your available balance is ₦12,000.00; this needs ₦18,510.75.",
    "request_id": "req_…"
  }
}
StatusCodes
401unauthenticated: no key, or a wrong one
402insufficient_balance
403forbidden, ip_not_allowed, not_live, …_not_enabled for a product not switched on yet, and limit_exceeded when a live checkout would pass your monthly limit (see GET /v1/business)
404not_found
409duplicate_reference, idempotency_conflict, rate_changed, not_settled, already_refunded, invalid_transition
422invalid_input (with details), name_mismatch, amount_too_small, amount_too_large
429rate_limited: slow down and retry
502, 503provider_refused, not_configured: our payment partner said no or is unavailable

Idempotency

Send an Idempotency-Key header (up to 255 characters) with any POST. If you send the same request with the same key again, you get the first answer back and nothing happens twice. The same key with a different body gets 409 idempotency_conflict. Use one per order or per payment, such as your order number.

Many objects also take your own reference: a second one with the same reference is refused or returns the first.