Initiate B2C Payout

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"
}
'

import requests

url = "https://api.palpluss.com/v1/b2c/payouts"

payload = {
    "amount": 500,
    "phone": "0712345678",
    "reference": "WD-2024-001",
    "description": "Commission payout",
    "callbackUrl": "https://yourserver.com/webhooks/b2c"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 500,
    phone: '0712345678',
    reference: 'WD-2024-001',
    description: 'Commission payout',
    callbackUrl: 'https://yourserver.com/webhooks/b2c'
  })
};

fetch('https://api.palpluss.com/v1/b2c/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.palpluss.com/v1/b2c/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 500,
    'phone' => '0712345678',
    'reference' => 'WD-2024-001',
    'description' => 'Commission payout',
    'callbackUrl' => 'https://yourserver.com/webhooks/b2c'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.palpluss.com/v1/b2c/payouts"

	payload := strings.NewReader("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.palpluss.com/v1/b2c/payouts")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.palpluss.com/v1/b2c/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "success": false,
  "error": {
    "message": "Invalid phone number format.",
    "code": "INVALID_PHONE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid or revoked API key.",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Insufficient service wallet balance to cover the transaction fee.",
    "code": "INSUFFICIENT_SERVICE_BALANCE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "KYC verification is required to initiate payouts.",
    "code": "KYC_NOT_VERIFIED",
    "details": {}
  },
  "requestId": "d2c3b4a5-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "limit": 60,
      "remaining": 0,
      "resetInSeconds": 12
    }
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

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"
}
'

import requests

url = "https://api.palpluss.com/v1/b2c/payouts"

payload = {
    "amount": 500,
    "phone": "0712345678",
    "reference": "WD-2024-001",
    "description": "Commission payout",
    "callbackUrl": "https://yourserver.com/webhooks/b2c"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 500,
    phone: '0712345678',
    reference: 'WD-2024-001',
    description: 'Commission payout',
    callbackUrl: 'https://yourserver.com/webhooks/b2c'
  })
};

fetch('https://api.palpluss.com/v1/b2c/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.palpluss.com/v1/b2c/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 500,
    'phone' => '0712345678',
    'reference' => 'WD-2024-001',
    'description' => 'Commission payout',
    'callbackUrl' => 'https://yourserver.com/webhooks/b2c'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.palpluss.com/v1/b2c/payouts"

	payload := strings.NewReader("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.palpluss.com/v1/b2c/payouts")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.palpluss.com/v1/b2c/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 500,\n  \"phone\": \"0712345678\",\n  \"reference\": \"WD-2024-001\",\n  \"description\": \"Commission payout\",\n  \"callbackUrl\": \"https://yourserver.com/webhooks/b2c\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "success": false,
  "error": {
    "message": "Invalid phone number format.",
    "code": "INVALID_PHONE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid or revoked API key.",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Insufficient service wallet balance to cover the transaction fee.",
    "code": "INSUFFICIENT_SERVICE_BALANCE",
    "details": {}
  },
  "requestId": "a1b2c3d4-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "KYC verification is required to initiate payouts.",
    "code": "KYC_NOT_VERIFIED",
    "details": {}
  },
  "requestId": "d2c3b4a5-0000-0000-0000-000000000000"
}

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "limit": 60,
      "remaining": 0,
      "resetInSeconds": 12
    }
  },
  "requestId": "a1b2c3d4-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

Paste your PalPluss API key in the username field and leave the password field empty — it is ignored.

Get your key from console → Settings → API Keys (starts with pk_live_ or pk_test_).

In your own code, send the key directly: Authorization: Basic YOUR_API_KEY

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.

Show child attributes

requestId

string<uuid>

required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"

Get Transaction Get Service Wallet Balance

Get Started

Guides

SDKs

STK Push

Transactions

B2C Payouts

Service Wallet

Payment Channels

Initiate B2C Payout

Key notes

Receiving the result (`callbackUrl`)

Wallet requirements

Failure and reversal

Authorizations

Body

Response

​Key notes

​Receiving the result (callbackUrl)

​Wallet requirements

​Failure and reversal

Authorizations

Body

Response

Key notes

Receiving the result (`callbackUrl`)

Wallet requirements

Failure and reversal