Для AI-агентов: markdown этой страницы — /docs-content/entities/pay-systems/create.md индекс документации — /llms.txt

Создать платёжную систему

POST /v1/pay-systems

Создаёт платёжную систему на зарегистрированном REST-обработчике. Поля передаются в корне JSON, без обёртки fields.

Поля запроса (body)

Поле Тип Обяз. Описание
name string да Название платёжной системы. Не может быть пустым.
personTypeId integer да Идентификатор типа плательщика из GET /v1/person-types. Тип должен принадлежать реестру, указанному в entityRegistryType.
bxRestHandler string да Код обработчика из поля code ответа GET /v1/pay-systems/handlers. Обработчик должен быть зарегистрирован.
description string нет Описание платёжной системы.
active string нет Активность: Y — активна, N — неактивна.
newWindow string нет Открытие страницы оплаты в новом окне: Y или N.
xmlId string нет Внешний идентификатор.
logo array нет Логотип в формате [filename, base64]. Размер файла после декодирования — до 2 МиБ.
settings object | array нет Настройки обработчика с исходными бизнес-ключами. Каждый элемент — объект или массив с TYPE и VALUE.
entityRegistryType string нет Реестр: ORDER, CRM_INVOICE или CRM_QUOTE. Для заказов передайте ORDER.

Передайте непустой объект JSON. Поля вне таблицы отклоняются.

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/pay-systems" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Оплата по счёту",
    "personTypeId": 5,
    "bxRestHandler": "my_payment_handler",
    "entityRegistryType": "ORDER",
    "active": "N",
    "xmlId": "invoice-20261014"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/pay-systems" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Оплата по счёту",
    "personTypeId": 5,
    "bxRestHandler": "my_payment_handler",
    "entityRegistryType": "ORDER",
    "active": "N",
    "xmlId": "invoice-20261014"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pay-systems', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Оплата по счёту",
    "personTypeId": 5,
    "bxRestHandler": "my_payment_handler",
    "entityRegistryType": "ORDER",
    "active": "N",
    "xmlId": "invoice-20261014"
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pay-systems', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Оплата по счёту",
    "personTypeId": 5,
    "bxRestHandler": "my_payment_handler",
    "entityRegistryType": "ORDER",
    "active": "N",
    "xmlId": "invoice-20261014"
  }),
})

const { success, data } = await res.json()

Поля ответа

HTTP 201. Возвращается созданная платёжная система.

Поле Тип Описание
success boolean Всегда true при успехе.
data object Созданная платёжная система. Полный состав: Поля платёжных систем.

Пример ответа

Показаны основные поля. Полный состав: Поля платёжных систем.

JSON 
{
  "success": true,
  "data": {
    "id": 41,
    "name": "Оплата по счёту",
    "actionFile": "my_payment_handler",
    "newWindow": "N",
    "active": "N",
    "entityRegistryType": "ORDER",
    "personTypeId": 5,
    "xmlId": "invoice-20261014"
  }
}

Пример ответа при ошибке

400 — в теле передано неподдерживаемое поле unexpected:

JSON 
{
  "success": false,
  "error": {
    "code": "READONLY_FIELD",
    "message": "Field 'unexpected' is not writable for this operation"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Некорректный тип поля, формат логотипа или элемент настроек, который не является объектом либо массивом.
400 MISSING_REQUIRED_FIELDS Пустое тело JSON, отсутствует обязательное поле или передан пустой name.
400 READONLY_FIELD В теле передано поле, недоступное для этой операции.
413 PAYLOAD_TOO_LARGE Логотип после декодирования превышает 2 МиБ либо тело JSON превышает 3 МиБ.
404 ENTITY_NOT_FOUND Созданная платёжная система не найдена при последующем чтении.
403 BITRIX_ACCESS_DENIED Нет доступа к операции создания.
422 BITRIX_ERROR Бизнес-ошибка. Подробности — в error.message.
502 BITRIX_RESPONSE_INVALID Некорректная структура ответа на операцию или последующее чтение.
403 SCOPE_DENIED API-ключ не имеет скоупа pay_system.
403 WRITE_BLOCKED_READONLY_KEY Ключ разрешает только чтение.
401 TOKEN_MISSING У ключа нет настроенных данных доступа к Битрикс24.

Полный список общих ошибок API — Коды ошибок.

Смотрите также