Collections

Use collections when you want to request a mobile money payment from a customer. Collections currently support KES and UGX. Successful collections settle into your USD wallet.

Endpoint

POST /v3/collect

Required fields

Field	Description
`currency`	Customer payment currency. Use `KES` or `UGX`.
`source`	Use `mobile`.
`amount`	Amount to collect.
`phone_number`	Customer phone 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 collection.

Quote first

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

Create the collection

Send the same request with quote: false. In production, Sarafa stores the transaction as pending, queues a collection.pending callback, and dispatches the provider request through the worker. The worker confirms the transaction from a provider webhook or status check. In sandbox, Sarafa skips phone-provider validation and worker dispatch, credits the sandbox USD wallet immediately, returns a completed transaction, and queues one collection.updated callback with status: "completed". Use a new external_id for every collection. Duplicate IDs return 409. The terminal callback uses collection.updated with a completed or failed status. A completed collection credits your USD wallet. A failed collection does not change your wallet balance.

Get started

How to use the API

Endpoint playground

Endpoint

Required fields

Quote first

Create the collection

​Endpoint

​Required fields

​Quote first

​Create the collection

Endpoint

Required fields

Quote first

Create the collection