> ## Documentation Index
> Fetch the complete documentation index at: https://docs.palpluss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payment Channel

> Register an M-Pesa shortcode as a payment channel.

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

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


## OpenAPI

````yaml POST /payment-wallet/channels
openapi: 3.1.0
info:
  title: PalPluss API
  version: '1.0'
  summary: >-
    Payment infrastructure for Kenya — STK Push, B2C payouts, and wallet
    management.
  description: >
    The PalPluss API gives developers programmatic access to M-Pesa STK Push
    collections,

    B2C payouts, service wallet top-ups, and payment channel management.


    **Base URL:** `https://api.palpluss.com/v1`


    All requests must be authenticated with an API key using HTTP Basic Auth.

    All responses are wrapped in a standard envelope. See [Errors](#tag/errors)
    for error codes.


    Amounts are in **KES (Kenyan Shillings)** unless stated otherwise. Phone
    numbers

    are normalized to the `254XXXXXXXXX` format internally.
  contact:
    name: PalPluss Developer Support
    email: developer@palpluss.com
    url: https://palpluss.com/developers
servers:
  - url: https://api.palpluss.com/v1
    description: Production
  - url: https://sandbox.palpluss.com/v1
    description: Sandbox
security:
  - BasicAuth: []
tags:
  - name: STK Push
    description: >
      Initiate M-Pesa STK Push payment prompts. The customer receives a PIN
      prompt on their

      phone and confirms payment. PalPluss delivers the result asynchronously to
      your webhook URL.
  - name: Transactions
    description: >-
      Query the status of any transaction by ID, or list all transactions with
      filters.
  - name: B2C Payouts
    description: >
      Send money directly to a customer's M-Pesa number. Requires KYC approval
      and sufficient

      B2C wallet balance. Payouts are processed asynchronously.
  - name: Service Wallet
    description: >
      The service wallet holds pre-funded tokens used to pay PalPluss
      transaction fees.

      Top up via STK Push. Balance is deducted with each API call.
  - name: Payment Channels
    description: >
      Payment channels represent the M-Pesa shortcodes (Paybill / Till)
      associated with your

      account. Channels are used to route STK Push requests to a specific
      shortcode.
paths:
  /payment-wallet/channels:
    post:
      tags:
        - Payment Channels
      summary: Create payment channel
      description: >
        Registers an M-Pesa shortcode (Paybill or Till Number) as a payment
        channel.

        You can pass a `channelId` when initiating STK Push to route the payment
        through

        a specific shortcode.


        Mark a channel as `isDefault: true` to use it automatically when no
        `channelId`

        is specified in payment requests.
      operationId: createChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChannelRequest'
            examples:
              paybill:
                summary: Paybill channel
                value:
                  name: Main Collections Paybill
                  type: PAYBILL
                  shortcode: '123456'
                  accountNumber: ACCOUNT001
                  isDefault: true
              till:
                summary: Till Number channel
                value:
                  name: Store Till
                  type: TILL_NUMBER
                  shortcode: '987654'
                  isDefault: false
      responses:
        '200':
          description: Channel created successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentChannel'
              examples:
                success:
                  value:
                    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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateChannelRequest:
      type: object
      required:
        - name
        - type
        - shortcode
      properties:
        name:
          type: string
          description: Human-readable label for the channel.
          example: Main Collections Paybill
        type:
          $ref: '#/components/schemas/ChannelType'
        shortcode:
          type: string
          description: M-Pesa shortcode (Paybill number or Till number).
          example: '123456'
        accountNumber:
          type: string
          nullable: true
          description: Account number for Paybill channels (not used for Till).
          example: ACCOUNT001
        isDefault:
          type: boolean
          default: false
          description: |
            Set this channel as the default for payment requests that do not
            specify a `channelId`.
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
        - requestId
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Response payload. Shape varies by endpoint.
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this API request. Include in support tickets.
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
    PaymentChannel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        category:
          type: string
          example: PAYMENT_WALLET
        type:
          $ref: '#/components/schemas/ChannelType'
        shortcode:
          type: string
          example: '123456'
        name:
          type: string
          example: Main Collections Paybill
        accountNumber:
          type: string
          nullable: true
          example: ACCOUNT001
        isDefault:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
    ChannelType:
      type: string
      enum:
        - PAYBILL
        - TILL_NUMBER
        - SEND_MONEY
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
        - requestId
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              description: Human-readable error description.
              example: Invalid API key
            code:
              type: string
              description: Machine-readable error code.
              example: INVALID_API_KEY
            details:
              type: object
              description: Optional structured details about the error.
        requestId:
          type: string
          format: uuid
          example: c1b2a3d4-e5f6-7890-abcd-ef1234567890
  responses:
    BadRequest:
      description: Validation error — check the request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid_phone:
              value:
                success: false
                error:
                  message: Invalid phone number format.
                  code: INVALID_PHONE
                  details: {}
                requestId: a1b2c3d4-0000-0000-0000-000000000000
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            invalid_key:
              value:
                success: false
                error:
                  message: Invalid or revoked API key.
                  code: INVALID_API_KEY
                  details: {}
                requestId: a1b2c3d4-0000-0000-0000-000000000000
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        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`

````