Channels

A channel is an entry point for payments inside your merchant account: a website, a Telegram bot, a mobile app, a terminal. Channels separate traffic sources within one account. Your contract, verification and settlements stay at the account level.

The default channel

Every account has a default channel. A payment without channel_id runs on it, so with one traffic source you do not need to do anything.

Create and manage channels

Channels are managed in the merchant portal, on the Channels page: create a channel, edit it, pause it, make it the default, delete or restore it. The API has no endpoints for managing channels.

• Code — lowercase Latin letters, digits, - and _; 3–64 characters; starts with a letter and ends with a letter or digit; unique within your account. Example: steam_bot.
• Type — web, bot, mobile_app, pos, marketplace, api, invoice or other.
• Payment page branding — a channel can have its own logo, primary colour and support link. Fields left empty use your account’s payment page settings.
• Currencies — the currencies the channel accepts. A payment in another currency gets 400 CURRENCY_NOT_ALLOWED in POST /v2/payments, POST /v2/payments/checkout and POST /widget/v1/session. A channel without a list accepts every supported currency.

Pass the channel in payment requests

Add channel_id to POST /v2/payments/checkout or POST /v2/payments. It accepts the channel’s code, its ch_… ID or its UUID. An unknown channel, or one that is paused, deleted or inactive, returns 400 BAD_REQUEST.

API keys bound to a channel

If your API key is bound to a channel:

• payments created with it run on that channel, and channel_id can be omitted;
• a channel_id of another channel returns 403 FORBIDDEN;
• it sees only its channel’s payments: GET /v2/payments lists only them, and another channel’s payment returns 404 on get, capture, void and refund.

Webhooks

Payment status events (payment.requires_action, payment.succeeded, payment.failed, payment.expired) carry the channel in data.metadata.channel_id — the UUID of the channel the payment ran on. Use it to route events of different channels. payment.refunded has no metadata.

MAXFI sets channel_id in metadata itself: if your request puts channel_id or merchant_id into metadata, these keys are removed.