Skip to main content

Authentication

Send your key as a bearer token. X-Api-Key: sk_… also works.
A key acts for one business, with exactly the scopes it was created with. Scopes are 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.
API keys are for servers only. Never put one in a browser, a mobile app or a git repository. If a key leaks, revoke it under API keys. It stops working immediately.

Requests

  • Bodies are JSON (Content-Type: application/json), up to 64 KB.
  • Unknown fields are rejected with 400 invalid_body. This catches typos such as ammount before 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 in data:
A failure puts it in errors:
Every response also carries an 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 the created_at of the last item you saw as before, and set limit:
An empty page is [], never null.