Authentication
Send your key as a bearer token.X-Api-Key: sk_… also works.
read, collect, disburse, links, transfer, settle, rails, credentials and settings. A key can never manage people or other keys, so a leaked key can’t create more keys. A call outside the key’s scopes returns 403 permission_denied.
Requests
- Bodies are JSON (
Content-Type: application/json), up to 64 KB. - Unknown fields are rejected with
400 invalid_body. This catches typos such asammountbefore any money moves. - Times are RFC 3339, for example
2026-11-16T09:30:00+03:00.
The envelope
Every response has the same shape. Success puts the result indata:
errors:
X-Request-Id header. Log it with failures: Cloudpay support can find any request by it.
status.code is always the same as the HTTP status. errors.code is stable, so write your logic against it. errors.message is written for people and may change. See the error reference for the full list of codes.
Phone numbers
You can send a number in any of these forms:0712345678, 0112345678, +254712345678 or 254712345678. Responses always return it as 254712345678.
Lists and paging
Lists are newest first. To page, pass thecreated_at of the last item you saw as before, and set limit:
An empty page is
[], never null.