Skip to main content

​
Access and authentication

Complete your organization’s verification, then create an API key in the merchant dashboard’s API section. Save the full key immediately: the secret is shown only once. The production base URL is:
Send these headers with your requests:
The public identifier is 16 hexadecimal characters; the secret is 64 hexadecimal characters. Keep the full key on your server. Each key grants access only to its organization’s account. Customer session tokens cannot authenticate this API.
Example response:

​
Request conventions

  • Send amounts as positive decimal strings, such as "100.00", rather than JSON numbers.
  • Mobile collections accept KES with up to two decimal places or whole UGX. Mobile payout USD principal accepts up to two decimal places. Sarafa payments and swaps support up to 18 decimal places.
  • Include your own reference and an HTTPS callback_url for charge, transfer, swap, and checkout creation, including quote requests. Callback URLs must not contain embedded credentials.
  • Charge, transfer, and swap default to "quote": true. Quotes move no funds and create no transaction or callback. Send "quote": false to execute.
  • Mobile quotes may return a quote_token. Include it when executing to detect a changed estimate, which returns HTTP 409. A quote is an estimate; use the execution result and final payment status for settlement.
  • References must be 1–128 characters and unique across charge, transfer, swap, and checkout creation within your organization.

​
Retry without duplicating a payment

Your reference is the idempotency key; no separate Idempotency-Key header is needed. After a timeout or uncertain response, retry execution with the same reference and unchanged payload. The API returns the existing payment or checkout. Changing the operation, amount, recipient, callback URL, or other request details returns HTTP 409. Preserve any quote_token supplied on the original execution. Your merchant reference and Sarafa’s tx_reference are different. Generated payment references are 13 characters, such as TX7A2B9C4D1E0. Use tx_reference to read a payment, and your merchant reference to read a checkout.

​
Interpret responses

The top-level status: "success" means the API request succeeded. Only transaction.status: "completed" confirms payment. Pending payments, including those marked needs_review, still need a final outcome. Use signed callbacks and authenticated status reads to establish payment outcomes. See the same guide for error codes and retry handling.