B2C payout

Send money from your payments wallet to an M-Pesa phone.

POST /v3/pay-request Send B2C payment Try it

Pays an M-Pesa customer. The result arrives by callback.

Scope: b2c_payments

Parameters

Field	In	Type	Required	Description
`amount`	body	integer	yes	Whole KES. Between 10 and 70000. Range 10 – 70000
`phone_number`	body	string	yes	Recipient phone. Format 2547XXXXXXXX, 2541XXXXXXXX, 07XXXXXXXX or 01XXXXXXXX.
`external_reference`	body	string	no	Your own id, max 100 characters (A-Z, 0-9 and . _ : - /). Reusing one returns 409 DUPLICATE_REFERENCE.
`command_id`	body	string	no	M-Pesa command. One of: `BusinessPayment`, `SalaryPayment`, `PromotionPayment`
`remarks`	body	string	no	Shown on the M-Pesa statement, 1-100 characters.
`occasion`	body	string	no	Max 100. Alias: occassion.
`callback_url`	body	url	no	Public HTTPS URL for the signed result callback, max 500. Overrides the key's webhook URL for this transaction.

Request

curl -X POST "https://swiftwallet.co.ke/v3/pay-request" \
  -H "Authorization: Bearer $SWIFTWALLET_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount":500,"phone_number":"254712345678","command_id":"BusinessPayment","remarks":"Refund","occasion":"Order 1001"}'

Response fields

success status (INITIATED) message transaction_id reference external_reference livemode identifiers.originatorConversationID identifiers.conversationID identifiers.responseCode identifiers.responseDescription payment_details.amount_sent payment_details.withdrawal_fee payment_details.command_id payment_details.remarks payment_details.phone_number (masked) wallet_balances.service_wallet_balance wallet_balances.payments_wallet_balance wallet_balances.currency

Requires approved personal KYC (403 PERSONAL_KYC_VERIFICATION_REQUIRED) and an activated wallet channel (403 WALLET_ACTIVATION_REQUIRED).

The send amount is debited from the payments wallet immediately; if M-Pesa rejects the payout it is refunded. The fee comes from the service wallet and is not refunded.

"occasion" is the field name. The legacy spelling "occassion" is accepted as an alias; if both are sent, "occasion" wins.