# Create channel

Creates a new channel for transaction routing and control

Channels are used to control back business transactions and enable routing based on the source of the transaction.

This endpoint generates the following events:
- [Channel event](https://developers.pismo.io/events/docs/cash-management-channel-1)

See [Data and reporting](doc:data-reporting-overview) for more information on events and setting up event notifications.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Banking - Transaction banking",
    "version": "0.9.0",
    "description": "Transaction banking API",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Channels",
      "description": "Channel management endpoints"
    }
  ],
  "components": {
    "schemas": {
      "ChannelCode": {
        "description": "Alphanumeric channel code identifier",
        "type": "string",
        "minLength": 1,
        "maxLength": 20,
        "pattern": "^[a-zA-Z0-9]+$",
        "example": "GDP"
      },
      "ChannelCreatedAt": {
        "description": "Timestamp when the channel was created in RFC3339 format with milliseconds",
        "type": "string",
        "format": "date-time",
        "example": "2026-02-26T10:30:00.123Z"
      },
      "ChannelDescription": {
        "description": "Optional description of the channel",
        "type": "string",
        "maxLength": 255,
        "example": "GDP channel"
      },
      "CreateChannelRequest": {
        "description": "Request body to create a new channel",
        "type": "object",
        "required": [
          "channel"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/ChannelCode"
          },
          "description": {
            "$ref": "#/components/schemas/ChannelDescription"
          }
        }
      },
      "CreateChannelResponse": {
        "description": "Response body for created channel",
        "type": "object",
        "required": [
          "channel",
          "created_at"
        ],
        "properties": {
          "channel": {
            "$ref": "#/components/schemas/ChannelCodeResponse"
          },
          "created_at": {
            "$ref": "#/components/schemas/ChannelCreatedAt"
          },
          "description": {
            "$ref": "#/components/schemas/ChannelDescription"
          }
        }
      },
      "ChannelCodeResponse": {
        "description": "Alphanumeric channel code identifier",
        "type": "string",
        "example": "GDP"
      },
      "ErrorCode": {
        "description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 12,
        "example": "WPMT0017"
      },
      "ErrorMessage": {
        "description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
        "type": "string",
        "minLength": 1,
        "maxLength": 1000,
        "example": "Invalid JSON payload received: Error unmarshalling request"
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "$ref": "#/components/schemas/ErrorMessage"
          }
        }
      }
    },
    "responses": {
      "401Unauthorized": {
        "description": "Access token is missing or invalid"
      },
      "403Forbidden": {
        "description": "The request has been lost"
      },
      "500InternalServer": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "Generic internal error": {
                "value": {
                  "code": "ECMN9999",
                  "message": "Internal error"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/corporate/v1/channels": {
      "post": {
        "summary": "Create channel",
        "description": "Creates a new channel for transaction routing and control\n\nChannels are used to control back business transactions and enable routing based on the source of the transaction.\n\nThis endpoint generates the following events:\n- [Channel event](https://developers.pismo.io/events/docs/cash-management-channel-1)\n\nSee [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) for more information on events and setting up event notifications.\n",
        "operationId": "post-corporate-v1-channels",
        "tags": [
          "Channels"
        ],
        "requestBody": {
          "description": "Create channel request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChannelRequest"
              },
              "examples": {
                "New channel": {
                  "value": {
                    "channel": "GDP",
                    "description": "GDP channel"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. Returns the created channel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateChannelResponse"
                },
                "examples": {
                  "Created channel": {
                    "value": {
                      "channel": "GDP",
                      "description": "GDP channel",
                      "created_at": "2026-02-26T10:30:00.123Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Invalid JSON": {
                    "summary": "Invalid JSON payload",
                    "value": {
                      "code": "WCCL0001",
                      "message": "Invalid JSON payload received: Error unmarshalling request"
                    }
                  },
                  "channel required": {
                    "summary": "Channel required",
                    "value": {
                      "code": "WCCL0002",
                      "message": "channel is a required field"
                    }
                  },
                  "channel contains character not permitted": {
                    "summary": "channel contains character not permitted",
                    "value": {
                      "code": "WCCL0002",
                      "message": "channel contains character not permitted"
                    }
                  },
                  "channel max": {
                    "summary": "channel exceeds maximum length",
                    "value": {
                      "code": "WCCL0002",
                      "message": "channel must be a maximum of 20 characters in length"
                    }
                  },
                  "description max": {
                    "summary": "description exceeds maximum length",
                    "value": {
                      "code": "WCCL0002",
                      "message": "description must be a maximum of 255 characters in length"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "409": {
            "description": "Conflict. Channel already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Channel already exists": {
                    "value": {
                      "code": "WCCL0003",
                      "message": "Channel 'GDP' already exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}
```