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"
}{
"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"
}Payment Channels
Create Payment Channel
Register an M-Pesa shortcode as a payment channel.
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"
}{
"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"
}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 achannelId 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
SetisDefault: 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
| Type | Description |
|---|---|
PAYBILL | M-Pesa Paybill shortcode. Requires an accountNumber. |
TILL_NUMBER | M-Pesa Till Number (Buy Goods). No account number needed. |
SEND_MONEY | Direct M-Pesa send money. |
Authorizations
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
Human-readable label for the channel.
Example:
"Main Collections Paybill"
Available options:
PAYBILL, TILL_NUMBER, SEND_MONEY M-Pesa shortcode (Paybill number or Till number).
Example:
"123456"
Account number for Paybill channels (not used for Till).
Example:
"ACCOUNT001"
Set this channel as the default for payment requests that do not
specify a channelId.