Transfers

Use transfers to send money from your merchant wallet.

Endpoint

POST /v3/transfer

Required fields

Field	Description
`currency`	Source wallet currency.
`amount`	Amount to send.
`destination`	Use `mobile` or `sarafa`.
`destination_currency`	Required for mobile transfers. Use `KES`, `UGX`, or `SSP`.
`account_number`	Destination phone number or Sarafa account number.
`external_id`	Required unique reference from your system.
`callback_url`	Required HTTPS URL that receives pending and terminal callbacks.
`quote`	Set `true` to quote only, or `false` to create the transfer.

Mobile money transfer quote

curl https://serviceapi.sarafa.ss/v3/transfer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "environment: sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 25,
    "destination": "mobile",
    "destination_currency": "KES",
    "account_number": "+254700000000",
    "external_id": "payout-1001",
    "callback_url": "https://example.com/sarafa/callback",
    "quote": true
  }'

Create the transfer

Send the request with quote: false after your customer or operations team accepts the quote.

Mobile money

KES and UGX transfers are dispatched to a payment provider through the worker.
Sarafa reserves the source funds while the transfer is pending.
Failed provider payouts return the reserved funds.

SSP cash payout

Use destination: "mobile" and destination_currency: "SSP". SSP does not use a mobile money provider. Sarafa creates an agent cashout request instead. The API returns 202 with a pending disburse_ssp_agent operation. An agent can accept the request and complete the cash payout. Completion debits your wallet and sends the terminal callback. In sandbox, SSP payouts bypass the agent workflow, debit the sandbox wallet immediately, return 200 with a completed disburse_ssp_agent transaction, and queue one terminal callback.

Sarafa account

Use destination: "sarafa" and the recipient Sarafa account number. The recipient account must exist and have completed verification. Valid transfers complete instantly. Production execution requests queue transfer.pending, followed by transfer.updated at completion or failure. Sandbox mobile, SSP, and Sarafa transfers settle immediately and queue only transfer.updated with status: "completed".

Get started

How to use the API

Endpoint playground

Endpoint

Required fields

Mobile money transfer quote

Create the transfer

Mobile money

SSP cash payout

Sarafa account

​Endpoint

​Required fields

​Mobile money transfer quote

​Create the transfer

​Mobile money

​SSP cash payout

​Sarafa account

Endpoint

Required fields

Mobile money transfer quote

Create the transfer

Mobile money

SSP cash payout

Sarafa account