Conventions

The rules every call follows. Read them once before you build.

Amountslink

• Every amount is an integer in the currency's minor unit. For naira that is kobo: 4037500 NGN is ₦40,375.00.
• Never send decimals. To display naira, divide by 100.
• Every amount travels with its own currency.

Request idslink

• Every response carries X-Request-Id.
• Send your own X-Request-Id matching ^[A-Za-z0-9._-]{1,64}$, such as your order number, and it is echoed back. Anything else is replaced with a new req_<uuid>.
• The request id is the correlationId of any error. Quote it when you contact support.

Rate limitslink

• Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• Over the per-minute budget the answer is 429 with Retry-After, in seconds. Wait that long, then retry.

Request bodieslink

• JSON only, at most 1 MiB. A larger body is 413 PAYLOAD_TOO_LARGE, and a malformed one is 400 BAD_REQUEST.
• Text fields are trimmed before use, and a value that is only whitespace counts as empty. Length limits are measured before trimming.

Idempotent writeslink

Every write takes an Idempotency-Key: a UUIDv4 you generate for that one request. If a network error leaves you unsure whether a write landed, send it again with the same key and the same body. The write happens once.

Paginglink

Environmentslink

The key prefix picks the environment: sk_test_ for test, sk_live_ for live. A record created in one environment is a 404 in the other.