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

# Update Payment Channel

> Update the name, account number, or default status of a payment channel.

Update channel metadata without affecting active transactions.

## Partial updates

Send only the fields you want to change. Omit everything else.

```bash theme={null}
# Rename a channel
curl -X PATCH "https://api.palpluss.com/v1/payment-wallet/channels/CHANNEL_ID" \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"name": "Primary Collections Paybill"}'

# Set a channel as default
curl -X PATCH "https://api.palpluss.com/v1/payment-wallet/channels/CHANNEL_ID" \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"isDefault": true}'
```

The `shortcode` and `type` fields cannot be changed after creation. Delete and recreate the channel if you need to update these.


## OpenAPI

````yaml PATCH /payment-wallet/channels/{id}
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/{id}:
    patch:
      tags:
        - Payment Channels
      summary: Update payment channel
      description: >
        Updates the name, account number, or default status of an existing
        channel.

        Only the fields you include in the request body are updated.
      operationId: updateChannel
      parameters:
        - name: id
          in: path
          required: true
          description: The channel ID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChannelRequest'
            examples:
              rename:
                summary: Rename channel
                value:
                  name: Primary Collections Paybill
              set_default:
                summary: Set as default
                value:
                  isDefault: true
      responses:
        '200':
          description: Channel updated successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentChannel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateChannelRequest:
      type: object
      description: All fields are optional. Only provided fields are updated.
      properties:
        name:
          type: string
          example: Primary Collections Paybill
        accountNumber:
          type: string
          nullable: true
          example: ACCOUNT002
        isDefault:
          type: boolean
          example: true
    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
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            not_found:
              value:
                success: false
                error:
                  message: Transaction not found.
                  code: TRANSACTION_NOT_FOUND
                  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`

````