Skip to main content
POST
/
payment-wallet
/
channels
curl --request POST \
  --url https://api.palpluss.com/v1/payment-wallet/channels \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Main Collections Paybill",
  "type": "PAYBILL",
  "shortcode": "123456",
  "accountNumber": "ACCOUNT001",
  "isDefault": true
}
'
{
  "success": true,
  "data": {
    "id": "8b3f1a2c-0000-0000-0000-000000000001",
    "tenantId": "b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d",
    "category": "PAYMENT_WALLET",
    "type": "PAYBILL",
    "shortcode": "123456",
    "name": "Main Collections Paybill",
    "accountNumber": "ACCOUNT001",
    "isDefault": true,
    "createdAt": "2026-03-01T07:00:00.000Z"
  },
  "requestId": "f4e5d6c7-0000-0000-0000-000000000000"
}
Register a Paybill or Till shortcode to route payments through a specific M-Pesa account.

​
What is a payment channel?

A payment channel maps an M-Pesa shortcode to your PalPluss account. When initiating an STK Push, specify a channelId to route the payment through that shortcode. Use channels when:
  • You operate multiple M-Pesa shortcodes (e.g. different products or business units)
  • You need to direct specific transaction types to dedicated shortcodes

​
Default channel

Set isDefault: true to use a channel automatically when no channelId is supplied on payment requests. Only one channel can be the default at a time — setting a new default removes the flag from the previous one.

​
Channel types

TypeDescription
PAYBILLM-Pesa Paybill shortcode. Requires an accountNumber.
TILL_NUMBERM-Pesa Till Number (Buy Goods). No account number needed.
SEND_MONEYDirect M-Pesa send money.

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
​
name
string
required

Human-readable label for the channel.

Example:

"Main Collections Paybill"

​
type
enum<string>
required
Available options:
PAYBILL,
TILL_NUMBER,
SEND_MONEY
​
shortcode
string
required

M-Pesa shortcode (Paybill number or Till number).

Example:

"123456"

​
accountNumber
string | null

Account number for Paybill channels (not used for Till).

Example:

"ACCOUNT001"

​
isDefault
boolean
default:false

Set this channel as the default for payment requests that do not specify a channelId.

Response

Channel created successfully.

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