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

`POST /v1/pay-systems`

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

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

|Поле|Тип|Обяз.|Описание|
|---|---|---|---|
|`name`|string|да|Название платёжной системы. Не может быть пустым.|
|`personTypeId`|integer|да|Идентификатор типа плательщика из [`GET /v1/person-types`](/docs/entities/person-types/list). Тип должен принадлежать реестру, указанному в `entityRegistryType`.|
|`bxRestHandler`|string|да|Код обработчика из поля `code` ответа [`GET /v1/pay-systems/handlers`](/docs/entities/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 — личный ключ

```bash
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-приложение

```bash
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|Созданная платёжная система. Полный состав: [Поля платёжных систем](/docs/entities/pay-systems/fields).|

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

Показаны основные поля. Полный состав: [Поля платёжных систем](/docs/entities/pay-systems/fields).

```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 — [Коды ошибок](/docs/errors).

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

- [Список платёжных систем](/docs/entities/pay-systems/list)
- [Получить платёжную систему](/docs/entities/pay-systems/get)
- [Изменить платёжную систему](/docs/entities/pay-systems/update)
- [Удалить платёжную систему](/docs/entities/pay-systems/delete)
- [Обработчики платёжных систем](/docs/entities/pay-systems/handlers)
- [Платёжные системы](/docs/entities/pay-systems)