curl --request POST \
--url https://api.sarafa.site/v3/charge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "1300",
"currency": "KES",
"channel": "mobile",
"account_number": "254712345678",
"network": "MPESA",
"reference": "collection-100",
"callback_url": "https://merchant.example/payments",
"quote": true
}
'{
"status": "success",
"quote": {
"source_currency": "KES",
"destination_currency": "USD",
"amount": "1300",
"exchange_rate": "130",
"amount_received": "10",
"total_fees": "0",
"total_debit": "1300",
"pricing": "payswitch_estimate",
"quote_token": "<token>"
}
}{
"status": "success",
"transaction": {
"tx_reference": "TX7A2B9C4D1E0",
"reference": "collection-101",
"transaction_type": "credit",
"product": "sarafa_charge",
"description": "Payment approval request",
"amount": "10",
"total_amount": "10",
"total_fees": "0",
"currency": "USD",
"channel": "Sarafa",
"status": "pending",
"created_at": "2026-10-30T10:00:00.000Z",
"updated_at": "2026-10-30T10:00:00.000Z",
"exchange_details": null,
"expires_at": "2026-10-30T10:15:00.000Z",
"reason": null
},
"quote": {
"source_currency": "USD",
"destination_currency": "USD",
"amount": "10",
"exchange_rate": "1",
"amount_received": "10",
"total_fees": "0",
"total_debit": "10",
"pricing": "temporary_fixed"
}
}{
"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
Collect a payment
Collect mobile money or request approval from a Sarafa account.
POST
/
charge
curl --request POST \
--url https://api.sarafa.site/v3/charge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "1300",
"currency": "KES",
"channel": "mobile",
"account_number": "254712345678",
"network": "MPESA",
"reference": "collection-100",
"callback_url": "https://merchant.example/payments",
"quote": true
}
'{
"status": "success",
"quote": {
"source_currency": "KES",
"destination_currency": "USD",
"amount": "1300",
"exchange_rate": "130",
"amount_received": "10",
"total_fees": "0",
"total_debit": "1300",
"pricing": "payswitch_estimate",
"quote_token": "<token>"
}
}{
"status": "success",
"transaction": {
"tx_reference": "TX7A2B9C4D1E0",
"reference": "collection-101",
"transaction_type": "credit",
"product": "sarafa_charge",
"description": "Payment approval request",
"amount": "10",
"total_amount": "10",
"total_fees": "0",
"currency": "USD",
"channel": "Sarafa",
"status": "pending",
"created_at": "2026-10-30T10:00:00.000Z",
"updated_at": "2026-10-30T10:00:00.000Z",
"exchange_details": null,
"expires_at": "2026-10-30T10:15:00.000Z",
"reason": null
},
"quote": {
"source_currency": "USD",
"destination_currency": "USD",
"amount": "10",
"exchange_rate": "1",
"amount_received": "10",
"total_fees": "0",
"total_debit": "10",
"pricing": "temporary_fixed"
}
}{
"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>"
}
]
}Mobile collections
Collect KES or UGX into your USD wallet. UseMPESA for KES, or MTN/AIRTEL for UGX. UGX requires the payer’s name. Supply the payer’s phone number with country prefix and 12 digits; an optional leading + is accepted.
{
"amount": "1300",
"currency": "KES",
"channel": "mobile",
"account_number": "254712345678",
"network": "MPESA",
"reference": "collection-100",
"callback_url": "https://merchant.example/payments",
"quote": true
}
{
"status": "success",
"quote": {
"source_currency": "KES",
"destination_currency": "USD",
"amount": "1300",
"exchange_rate": "130",
"amount_received": "10",
"total_fees": "0",
"total_debit": "1300",
"pricing": "payswitch_estimate",
"quote_token": "<token>"
}
}
"quote": false to collect. You may include the returned quote_token; a changed estimate then returns HTTP 409. Provider acceptance remains pending until settlement. HTTP 202 means the payment is pending or awaiting reconciliation.
Sarafa approval requests
Request payment in USD or SSP from an eligible Sarafa customer or merchant account:{
"amount": "10",
"currency": "USD",
"channel": "sarafa",
"account_number": "602600000002",
"reference": "collection-101",
"callback_url": "https://merchant.example/payments",
"quote": false
}
reason set to rejected or expired. Sarafa charges have no additional fee.
Read payment details or process signed callbacks to confirm the outcome. Preserve the reference and original execution payload when retrying.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 Eligible payer customer or merchant account.
Pattern:
^\d{12,13}$Example:
"602600000002"
True returns a quote without moving funds or creating a transaction. Set false to execute.