Webhooks

Callbacks help your system track payment and transfer progress.

Authentication header

Every callback includes the webhook secret created with the API key:

x-sarafa-signature: whsec_test_...

Compare this header with the webhook secret stored on your server. Use a constant-time comparison. Despite the header name, its value is the raw bearer secret, not an encrypted value or an HMAC digest. Never log it or return it to a browser. Rotate the API key immediately if the value is exposed.

import { timingSafeEqual } from "node:crypto";

const received = Buffer.from(request.headers["x-sarafa-signature"] ?? "");
const expected = Buffer.from(process.env.SARAFA_WEBHOOK_SECRET ?? "");
const valid = received.length === expected.length && timingSafeEqual(received, expected);

Callback URL

For collection, transfer, and swap requests, send a callback_url in the request body. The field is required. Production provider flows send pending and terminal updates. Sandbox flows and swaps settle immediately and send only the terminal update. Your endpoint should:

Accept POST requests.
Respond quickly with a success status.
Store the event and transaction reference.
Handle duplicate events safely.

Collection pending event

Sent after a collection is created.

{
  "event": "collection.pending",
  "reference": "SRF-ABC123",
  "external_id": "order-1001",
  "status": "pending",
  "product": "collect_mobile",
  "amount": 7.5,
  "currency": "USD",
  "usd_amount": 7.5,
  "phone_number": "+254700000000"
}

Transfer pending event

Sent after a transfer is created.

{
  "event": "transfer.pending",
  "reference": "DSM-ABC123",
  "external_id": "payout-1001",
  "status": "pending",
  "product": "disburse_mobile",
  "amount": 10,
  "currency": "USD",
  "usd_amount": 10,
  "phone_number": "+254700000000"
}

Terminal event

Provider-backed collections and transfers send a terminal update after a webhook or worker status check settles the transaction.

{
  "event": "transfer.updated",
  "reference": "DSM-ABC123",
  "external_id": "payout-1001",
  "product": "disburse_mobile",
  "status": "completed",
  "amount": 10,
  "total_amount": 10,
  "fee": 0,
  "completed_at": "2026-07-17T10:00:00.000Z"
}

Collection terminal events use collection.updated. Transfer terminal events use transfer.updated. The status is completed, failed, or cancelled. Completed swaps use swap.updated and include the quote plus debit and credit transaction legs. All terminal transfer callbacks use transfer.updated. An SSP production cashout sends it when the agent completes the request. Sarafa may retry callbacks. Use reference, external_id, and status as your idempotency key. Do not assume callbacks arrive only once. Use the transaction endpoints to fetch the latest status when your system needs to reconcile activity. Callback delivery is asynchronous and requires Sarafa’s QStash delivery configuration. Settlement is never rolled back when your callback endpoint is unavailable.

Get started

How to use the API

Endpoint playground

Authentication header

Callback URL

Collection pending event

Transfer pending event

Terminal event

​Authentication header

​Callback URL

​Collection pending event

​Transfer pending event

​Terminal event

Authentication header

Callback URL

Collection pending event

Transfer pending event

Terminal event