Create Payment Channel

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

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

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

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

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

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.

Show child attributes

requestId

string<uuid>

required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"

Top Up Service Wallet Update Payment Channel

Get Started

Guides

SDKs

STK Push

Transactions

B2C Payouts

Service Wallet

Payment Channels

Create Payment Channel

What is a payment channel?

Default channel

Channel types

Authorizations

Body

Response

​What is a payment channel?

​Default channel

​Channel types

Authorizations

Body

Response

What is a payment channel?

Default channel

Channel types