Skip to content

Authentication

All requests require your API key in the X-Api-Key header.

X-Api-Key: rk_live_<your_key>

API keys are scoped: each key only grants access to the endpoints listed in its scope. Keys are managed through the Regini partner portal.

Keep your API key secret

Rotate it immediately if you believe it has been compromised. Never expose it in client-side code or mobile apps.

Scopes

Scope Grants access to
accounts:read GET /accounts, GET /accounts/{id}, GET /accounts/{id}/balance
accounts:create POST /accounts, PATCH /accounts/{id}, POST /accounts/{id}/deactivate, PATCH /programs/{id}/spread — program spread configuration requires this scope
transactions:read GET /accounts/{id}/transactions, GET /transactions, GET /transactions/{id}
transactions:create Quote and initiate deposits and withdrawals
compliance:read GET /accounts/{id}/compliance

Idempotency

All requests that initiate a transaction (POST /deposits, POST /withdrawals) require an Idempotency-Key header. The value must be a UUID you generate per request.

Idempotency-Key: <unique-uuid-per-request>

Behavior:

  • If the key has not been seen before, the request executes normally and the response is stored.
  • If the same key is submitted again (retry), you receive the exact same response as the original, no duplicate transaction is created.
  • If the same key is submitted while the first request is still processing, you receive 409 with the message "A request with this Idempotency-Key is already in progress." Retry after the original completes.

TTL: Stored responses are cached for 24 hours. After that, the same key is treated as a new request. Keys are scoped to your API key, so two different partners using the same key string never collide.

Warning

Generate a fresh UUID per request. Reusing a key for a different operation (e.g., a different amount_kes) will silently return the cached response from the first call.

Rate limits

The API enforces a global limit of 200 requests per minute per IP address. This applies to all endpoints equally.

Transaction velocity limits (daily/weekly per account) are documented separately in Deposits and Withdrawals.

Sandbox vs. live

Key prefix Environment Behaviour
rk_live_<key> Production Real M-Pesa flows and Kotani calls
rk_test_<key> Sandbox Immediate success responses, no real money moves

See Sandbox for details.