Withdrawals – B2C Payments (Send Money to Customer)

Use the B2C endpoint to disburse funds from your business account directly to a customer’s mobile money wallet (e.g., commissions, refunds, salaries, cashbacks, bonuses).

Endpoint

POST /b2c

Production
https://payments.pesavoucher.com/api/v1/b2c

Sandbox
https://sandbox.payments.pesavoucher.com/api/v1/b2c

Request Example

curl -X POST https://payments.pesavoucher.com/api/v1/b2c \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "phone_number": "254708374149",
    "amount": 2500.00,
    "command_id": "BusinessPayment",
    "remarks": "November affiliate commission",
    "occasion": "Monthly payout - Nov 2025",
  }'

Request Parameters

Parameter	Type	Required	Description
`phone_number`	string	Yes	Recipient phone in 254XXXXXXXXX format (auto-converts 07xx / +254)
`amount`	float	Yes	Exact amount with 2 decimal places (e.g., `1500.00`)
`command_id`	string	Yes	Type of payment – see table below
`remarks`	string	Yes	Short description shown to recipient (max 100 chars)
`occasion`	string	Yes	Reason/context of payment (e.g., "Birthday Bonus")

Command ID Options

Command ID	Recommended Use Case
`BusinessPayment`	Commissions, refunds, settlements, general payouts
`SalaryPayment`	Employee salaries, wages
`PromotionPayment`	Cashbacks, rewards, referral bonuses

Amount Rules

Minimum: 1.00 KES
Maximum: 150,000.00 KES per transaction
Must have exactly 2 decimal places

Success Response (Initiation)

{
  "success": true,
  "message": "B2C payment initiated successfully",
  "data": {
    "payment_id": "550e8400-e29b-41d4-a716-446655440001",
    "conversation_id": "AG_20251120_000123456789",
    "originator_conversation_id": "OC_20251120_987654321",
    "amount": 2500.00,
    "recipient_phone": "254708374149",
    "status": "Queued"
  }
}

The final result (Success, Failed, etc.) will be delivered to your webhook.

B2C Webhook Callback (Final Result)

{
  "payment_id": "550e8400-e29b-41d4-a716-446655440001",
  "conversation_id": "AG_20251120_000123456789",
  "originator_conversation_id": "OC_20251120_987654321",
  "transaction_type": "b2c",
  "status": "Success",
  "result_code": "0",
  "result_description": "The service request is processed successfully.",
  "transaction_id": "RKJ3M9P2XQ",
  "amount": 2500.00,
  "recipient_phone": "254708374149",
  "recipient_name": "Jane Doe",
  "command_id": "BusinessPayment",
  "transaction_date": "2025-11-20 14:30:45",
  "charges": {
    "charges_paid": 125.00,
    "utility_balance": 987500.00,
    "working_balance": 862375.00
  },
  "timestamp": "2025-11-20 14:30:50"
}

Important Fields in Callback

Field	Description
`status`	`Success` → credit sent, `Failed` → retry or notify
`transaction_id`	Official receipt number (e.g., M-Pesa reference)
`charges`	Breakdown of fees deducted from your account

Test Phone Numbers (Sandbox Only)

Phone Number	Behavior
`254708374149`	Always succeeds instantly
`254711223344`	Always fails (insufficient funds)
`254722334455`	Simulates timeout

Rate Limits

Default: 60 B2C requests per minute
Burst up to 100/min
Contact support for higher limits

You're now ready to send payments to yor customers!