B2C Payments

Send money to M-Pesa users (Business to Customer). Funds are deducted from your payment wallet.

/v3/pay-request/

POST /v3/pay-request/ Auth Required Service: b2c_payments

Send B2C Payment

Transfer money from your payment wallet to an M-Pesa phone number.

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`amount`	number	Yes	Amount in KES (min 10, max 70000 per transaction)
`phone_number`	string	Yes	Recipient phone (254XXXXXXXXX or 07XXXXXXXX)
`external_reference`	string	No	Your unique reference
`command_id`	string	No	BusinessPayment (default), SalaryPayment, or PromotionPayment
`remarks`	string	No	Transaction remarks (max 100 chars)
`occassion`	string	No	Occasion/reason for payment (API uses double "s")
`occasion`	string	No	Alias for occassion (single "s")
`callback_url`	string	No	URL to receive payment result callback

Example Response

JSON

{
    "success": true,
    "status": "INITIATED",
    "message": "B2C payment initiated successfully",
    "reference": "B2C-abc123",
    "transaction_id": 790,
    "identifiers": {
        "originatorConversationID": "12345-67890-1",
        "conversationID": "AG_20241231_...",
        "responseCode": "0",
        "responseDescription": "Accept the service request successfully."
    },
    "payment_details": {
        "amount_sent": 1000,
        "withdrawal_fee": 15,
        "phone_number": "2547****5678",
        "command_id": "BusinessPayment",
        "remarks": "Salary payment",
        "occassion": "December salary"
    },
    "wallet_balances": {
        "payment_wallet": 4000,
        "service_wallet": 835
    }
}

cURL Example

bash

curl -X POST 'https://swiftwallet.co.ke/v3/pay-request/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "phone_number": "254712345678",
    "external_reference": "SALARY-DEC-001",
    "command_id": "SalaryPayment",
    "remarks": "December 2024 Salary",
    "callback_url": "https://yoursite.com/b2c-callback"
  }'

Callback Payload

After M-Pesa processes the B2C transaction, SwiftWallet sends a POST request to your callback_url with the result. Internal M-Pesa account balance snapshots (utility/working/charges) are intentionally excluded; use the Wallet API to check your own balances.

POST to your callback_url

{
    "success": true,
    "transaction_id": 790,
    "external_reference": "SALARY-DEC-001",
    "originatorConversationID": "12345-67890-1",
    "conversationID": "AG_20241231_...",
    "transactionID": "NLJ41HAY6Q",
    "status": "completed",
    "timestamp": "2024-12-31T12:35:00+03:00",
    "service_fee": 15,
    "withdrawal_fee": 15,
    "result": {
        "ResultCode": 0,
        "ResultDesc": "The service request is processed successfully.",
        "TransactionAmount": 1000,
        "TransactionReceipt": "NLJ41HAY6Q",
        "RecipientIsRegistered": "Y",
        "TransactionCompletedDateTime": "31.12.2024 12:35:00",
        "ReceiverPublicName": "254712345678 - John Doe"
    },
    "transaction_info": {
        "phone_number": "254712345678",
        "amount": 1000,
        "currency": "KES",
        "transaction_type": "B2C"
    },
    "payer_name": "Jane Merchant"
}

Verify callbacks by checking the transaction_id and originatorConversationID against your records via the Transactions API.

Notes

Funds are immediately deducted from your payment wallet upon initiation
If the B2C request fails at M-Pesa, funds are automatically reversed to your wallet
Withdrawal fees are charged from your service wallet
Maximum single transaction is KES 70,000 (daily limit may also apply)
Requires the b2c_payments service to be enabled on your API key