Amounts, idempotency and errors

AmountsCopy Anchor Link

Amounts are integer minor units sent as strings: kobo for NGN. "250000" is ₦2,500.00. Strings avoid floating-point rounding; never send 2500.00.

IdempotencyCopy Anchor Link

Every write (POST, PUT, PATCH, DELETE) needs an x-idempotency-key header: up to 128 letters, digits, ., _, : or -. Use one key per operation, for example payout-881 or the order id.

• Retrying with the same key and the same body within 24 hours returns the original response; nothing is charged or paid twice.
• The same key with a different body returns 409.
• After a timeout or a network error, retry with the same key. Never invent a new key for an operation that may already have happened.

Separately, your own reference values must be unique per environment. Reusing one returns 409.

Uncertain outcomesCopy Anchor Link

Collection and payout responses include requiresReconciliation. When it is true, the provider has not confirmed the result yet. Do not retry: look the transaction up with GET /transactions/{id} or wait for the webhook.

ErrorsCopy Anchor Link

Errors use standard HTTP status codes and a JSON body:

{
  "statusCode": 409,
  "path": "/api/v1/payouts",
  "timestamp": "2026-11-02T10:15:00.000Z",
  "error": {
    "statusCode": 409,
    "error": "Conflict",
    "message": "Reference already exists. Query the original operation before retrying"
  }
}

Show or log error.message. For validation errors (400) it can be a list of messages, one per invalid field.