curl --request POST \
--url https://api.sarafa.site/v3/transfer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "25",
"currency": "USD",
"channel": "sarafa",
"account_number": "602600000002",
"reference": "payout-100",
"callback_url": "https://merchant.example/payments",
"quote": false
}
'{
"status": "success",
"quote": {
"source_currency": "<string>",
"destination_currency": "<string>",
"amount": "<string>",
"exchange_rate": "<string>",
"amount_received": "<string>",
"total_fees": "<string>",
"total_debit": "<string>",
"pricing": "temporary_fixed",
"quote_token": "<string>"
}
}{
"status": "success",
"transaction": {
"tx_reference": "TX7A2B9C4D1E0",
"transaction_type": "credit",
"product": "<string>",
"description": "<string>",
"amount": "<string>",
"total_amount": "<string>",
"total_fees": "<string>",
"channel": "<string>",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"reference": "<string>",
"exchange_details": {
"from_currency": "<string>",
"to_currency": "<string>",
"rate": "<string>",
"total": "<string>"
},
"expires_at": "2023-11-07T05:31:56Z",
"reason": "<string>"
},
"quote": {
"source_currency": "<string>",
"destination_currency": "<string>",
"amount": "<string>",
"exchange_rate": "<string>",
"amount_received": "<string>",
"total_fees": "<string>",
"total_debit": "<string>",
"pricing": "temporary_fixed",
"quote_token": "<string>"
}
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}Payments
Send a payment
Send USD or SSP to a Sarafa customer, or pay out USD to mobile money.
POST
/
transfer
curl --request POST \
--url https://api.sarafa.site/v3/transfer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "25",
"currency": "USD",
"channel": "sarafa",
"account_number": "602600000002",
"reference": "payout-100",
"callback_url": "https://merchant.example/payments",
"quote": false
}
'{
"status": "success",
"quote": {
"source_currency": "<string>",
"destination_currency": "<string>",
"amount": "<string>",
"exchange_rate": "<string>",
"amount_received": "<string>",
"total_fees": "<string>",
"total_debit": "<string>",
"pricing": "temporary_fixed",
"quote_token": "<string>"
}
}{
"status": "success",
"transaction": {
"tx_reference": "TX7A2B9C4D1E0",
"transaction_type": "credit",
"product": "<string>",
"description": "<string>",
"amount": "<string>",
"total_amount": "<string>",
"total_fees": "<string>",
"channel": "<string>",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"reference": "<string>",
"exchange_details": {
"from_currency": "<string>",
"to_currency": "<string>",
"rate": "<string>",
"total": "<string>"
},
"expires_at": "2023-11-07T05:31:56Z",
"reason": "<string>"
},
"quote": {
"source_currency": "<string>",
"destination_currency": "<string>",
"amount": "<string>",
"exchange_rate": "<string>",
"amount_received": "<string>",
"total_fees": "<string>",
"total_debit": "<string>",
"pricing": "temporary_fixed",
"quote_token": "<string>"
}
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}{
"status": "failed",
"error": "<string>",
"request_id": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>"
}
]
}Sarafa transfers
Send USD or SSP to an active Sarafa customer account in the same currency, with no additional Sarafa fee:{
"amount": "25",
"currency": "USD",
"channel": "sarafa",
"account_number": "602600000002",
"reference": "payout-100",
"callback_url": "https://merchant.example/payments",
"quote": false
}
200 with transaction.status: "completed" and the transaction/quote response structure shown in payment details.
Mobile payouts
Specify a USD principal and a KES or UGX destination. KES usesMPESA; UGX uses MTN or AIRTEL and requires the recipient’s name.
{
"amount": "10",
"currency": "USD",
"destination_currency": "UGX",
"channel": "mobile",
"account_number": "256772123456",
"network": "MTN",
"name": "Recipient Name",
"reference": "payout-101",
"callback_url": "https://merchant.example/payments",
"quote": true
}
amount_received, total_fees, and total_debit in the quote before executing with "quote": false. Your USD wallet debit is the principal plus quoted fees. The amount is not an all-inclusive budget.
You may include the returned quote_token when executing to detect a changed estimate. Preserve it on later retries. Mobile payments generally return HTTP 202 while pending. Confirm completion through signed callbacks or payment details.Authorizations
Use the full key from the merchant dashboard API section. Keep it on your server.
Body
application/json
- Option 1
- Option 2
- Option 3
Positive decimal string, not a JSON number. Zero is invalid. Currency-specific precision and payment limits also apply.
Pattern:
^[0-9]+([.][0-9]{1,18})?$Example:
"100.00"
Your idempotency reference, unique across charge, transfer, swap, and checkout creation within your organization. Reuse it with unchanged details for execution retries.
Required string length:
1 - 128HTTPS URL without embedded credentials. Required even for quotes. Receives signed payment callbacks.
Pattern:
^https://Example:
"https://merchant.example/payments"
Available options:
sarafa Available options:
USD, SSP Active receiving customer account.
Pattern:
^\d{12,13}$Example:
"602600000002"
True returns a quote without moving funds or creating a transaction. Set false to execute.