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"
}
Disburse funds to any M-Pesa number. Reversals are automatic on failure — no manual action needed.
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 — insufficient funds return 409 INSUFFICIENT_FUNDS.
  • The wallet balance is debited immediately when the request is accepted.
  • On failure, the debited balance is automatically reversed to your B2C wallet.
  • The service fee (from your service wallet) is deducted on initiation and is not refunded on failure.
  • transactionFee in the response shows the service wallet amount reserved for this payout. It is 0 if no pricing rule is configured or the transaction fails.
  • Payouts settle asynchronously. Expect 30 seconds to 5 minutes for completion.

​
Receiving the result (callbackUrl)

Supply a callbackUrl in the request body. PalPluss will POST the transaction result to that URL when the payout reaches a terminal state (SUCCESS or FAILED). 
{
  "amount": 500,
  "phone": "0712345678",
  "reference": "WD-2024-001",
  "callbackUrl": "https://yourserver.com/webhooks/b2c"
}
The callback payload sent to your URL: 
{
  "event": "transaction.updated",
  "event_type": "transaction.success",
  "transaction": {
    "id": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "type": "B2C",
    "status": "SUCCESS",
    "amount": 500,
    "currency": "KES",
    "phone_number": "254712345678",
    "external_reference": "WD-2024-001",
    "mpesa_receipt": "RKL1XXXXX0",
    "transaction_fee": 5.00,
    "result_code": "0",
    "result_desc": "The service request is processed successfully.",
    "created_at": "2026-03-31T08:00:00.000Z",
    "updated_at": "2026-03-31T08:00:45.000Z"
  }
}
See Webhooks for retry policy, idempotency handling, and full field reference.

​
Wallet requirements

Before initiating a payout, verify:
  • Your B2C wallet has enough balance for the payout amount
  • Your service wallet has enough balance for the transaction fee
Both balances are visible in the console under Finance → Wallets.

​
Failure and reversal

If M-Pesa declines or times out:
  • PalPluss automatically credits your B2C wallet back
  • Your webhook receives status: "FAILED" with result_code and result_desc from M-Pesa
  • The reversed transaction shows status: "REVERSED"
  • Retry safely — the original transaction is not 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"

​
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.

​
callbackUrl
string<uri>

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

Example:

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

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"