Sign in

v1

latestOpenAPI 3.1.02026-07-2691531.2 KB
B2C Payouts

Initiate B2C payout

Sends money directly to a customer's M-Pesa mobile number.

Requirements before calling this endpoint:

  • Account KYC must be approved.
  • B2C wallet must have sufficient balance.
  • Minimum payout: KES 10.

Payouts are processed asynchronously. The initial response confirms the payout was queued. The final result is delivered to your callbackUrl and the transaction status updates to SUCCESS or FAILED.

On failure, the debited wallet balance is automatically reversed.

post/b2c/payouts

Request body

amountnumber required

Payout amount in KES. Minimum KES 10.

currencystring

Currency code. Currently only KES is supported.

phonestring required

Recipient M-Pesa phone number.

referencestring required

Your reference for this payout (e.g. withdrawal ID).

descriptionstring

Short description of the payout purpose.

channelIdstring uuid nullable

Optional channel to use for this payout.

callbackUrlstring uri

HTTPS URL to receive the payout result. PalPluss POSTs the terminal transaction payload here when the status reaches SUCCESS or FAILED.

Example request

{
  "amount": 500,
  "phone": "0712345678",
  "reference": "WD-2024-001",
  "description": "Commission payout",
  "callbackUrl": "https://yourserver.com/webhooks/b2c"
}

Response

Payout queued successfully. Transaction is in PENDING state.

successboolean required
requestIdstring uuid required

Unique identifier for this API request. Include in support tickets.

Example response

{
  "success": true,
  "data": {
    "type": "B2C",
    "status": "PENDING",
    "amount": 500,
    "currency": "KES",
    "phone": "254712345678",
    "reference": "WD-2024-001",
    "resultDescription": "B2C payout queued"
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}
All 9 operations