Skip to main content
Every endpoint page has a playground. Paste a bearer token into the Authorization field to send requests; a token from sandbox keys keeps them in sandbox.

​
Base URL

Sandbox and production share the base URL; your keys pick the environment. See Environments.

​
Authentication

Every endpoint except Generate bearer token needs:
Generate bearer token takes your secret in an api-key header and your public key in the body. Tokens last one hour.

​
Requests and responses

  • Send JSON with Content-Type: application/json.
  • Responses are JSON with a success boolean. Most put their payload in data.
  • Currency is KES and country is KE.
  • Amounts are in shillings: 1500 is KES 1,500.
  • Phone numbers use 254XXXXXXXXX, without the +. The one exception is Get phone number operator, which takes +254XXXXXXXXX.

​
Idempotency

Checkout sessions, charges, payouts and refunds require an externalReference that you generate, unique to each transaction. Sending the same value again returns 409 DUPLICATE_EXTERNAL_REFERENCE instead of creating a second transaction, so it’s safe to resend a request that timed out. You can also use externalReference in place of transactionId with Get transaction.

​
Asynchronous results

A 200 from a charge or payout means the request was accepted. The result arrives later by webhook. Only successful means money moved.

​
Errors

Failed requests return a 4xx or 5xx status with success: false, a human-readable message and, for most errors, an errorCode to branch on. See API errors.

​
Endpoints