Skip to main content
POST
/
b2c
/
payouts
Initiate B2C payout
curl --request POST \
  --url https://api.palpluss.com/v1/b2c/payouts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 500,
  "phone": "0712345678",
  "reference": "WD-2024-001",
  "description": "Commission payout",
  "callbackUrl": "https://yourserver.com/webhooks/b2c"
}
'
{
  "success": true,
  "data": {
    "transactionId": "2f9c1e77-0000-0000-0000-000000000001",
    "tenantId": "b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d",
    "channelId": null,
    "type": "B2C",
    "status": "PENDING",
    "amount": 500,
    "currency": "KES",
    "phone": "254712345678",
    "reference": "WD-2024-001",
    "description": "Commission payout",
    "resultDescription": "B2C payout queued",
    "createdAt": "2026-03-01T09:00:00.000Z",
    "updatedAt": "2026-03-01T09:00:00.000Z"
  },
  "requestId": "d2c3b4a5-0000-0000-0000-000000000000"
}
B2C payouts require KYC approval on your account. Requests before approval return 403 KYC_NOT_VERIFIED. See Going Live for the KYC process.

​
Key notes

  • Minimum amount: KES 10.
  • The B2C wallet must have sufficient balance. If not, the request returns 409 INSUFFICIENT_FUNDS.
  • The wallet balance is debited when the provider accepts the payout (status changes to PROCESSING).
  • On failure, the debited balance is automatically reversed — no manual action needed.
  • The service fee (from your service wallet) is deducted on initiation and is not refunded on failure.
  • Payouts are processed asynchronously. Expect 30 seconds to 5 minutes for completion.

​
Wallet requirements

Before initiating a payout:
  1. Ensure your B2C wallet has enough balance for the payout amount.
  2. Ensure your service wallet has enough balance for the transaction fee.
Both balances are visible in the PalPluss dashboard under Finance → Wallets.

​
Failure and reversal

If the M-Pesa provider declines or times out, PalPluss automatically credits your B2C wallet back. Your webhook receives the FAILED state and the transaction’s result_code and result_desc contain the M-Pesa error details. Reversed transactions have status: "REVERSED". You can safely retry a failed payout — the original transaction will not be retried automatically.

Authorizations

​
Authorization
string
header
required

Use your API key as the username. Leave the password field empty.

Authorization: Basic <base64(apikey:)>

You can also pass the raw API key:

Authorization: Basic <apikey>

Body

application/json
​
amount
number
required

Payout amount in KES. Minimum KES 10.

Required range: x >= 10
Example:

500

​
phone
string
required

Recipient M-Pesa phone number.

Example:

"0712345678"

​
reference
string
required

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

Example:

"WD-2024-001"

​
callbackUrl
string<uri>
required

HTTPS URL to receive the payout result.

Example:

"https://yourserver.com/webhooks/b2c"

​
currency
string
default:KES

Currency code. Currently only KES is supported.

​
description
string

Short description of the payout purpose.

Example:

"Commission payout"

​
channelId
string<uuid> | null

Optional channel to use for this payout.

Response

Payout queued successfully. Transaction is in PENDING state.

​
success
boolean
required
Example:

true

​
data
object
required

Response payload. Shape varies by endpoint.

​
requestId
string<uuid>
required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"