## Создать оплату

`POST /v1/payments`

Регистрирует новую оплату для существующего заказа. Тело запроса плоское — без обёртки `fields`.

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

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `orderId` | number | да | Идентификатор заказа. Источник: [`GET /v1/orders`](../orders/list.md) |
| `paySystemId` | number | да | Идентификатор платёжной системы. На каждом портале свой набор систем. Узнать ID можно из существующих оплат через [`GET /v1/payments`](./list.md) или [`POST /v1/payments/aggregate`](./aggregate.md) с `groupBy: "paySystemId"` |
| `sum` | number | нет | Сумма оплаты. Если не передать — Битрикс24 берёт остаток от суммы заказа |
| `currency` | string | нет | Валюта оплаты. По умолчанию — валюта заказа. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `paid` | boolean | нет | Помечена ли оплата как поступившая. По умолчанию `false` |
| `datePaid` | datetime | нет | Дата отметки оплаты (в формате ISO 8601) |
| `dateBill` | datetime | нет | Дата выставления счёта |
| `datePayBefore` | datetime | нет | Срок оплаты. В ответах возвращается только дата — время всегда полночь по времени портала |
| `responsibleId` | number | нет | Ответственный сотрудник. Источник: [`GET /v1/users`](/docs/entities/users) |
| `comments` | string | нет | Комментарий к оплате |
| `xmlId` | string | нет | Внешний идентификатор (например, ID транзакции платёжного шлюза) |

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/payments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 19,
    "paySystemId": 11,
    "sum": 1500,
    "currency": "RUB",
    "paid": true,
    "comments": "Оплата через платёжный шлюз",
    "xmlId": "txn_abc123"
  }'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/payments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 19,
    "paySystemId": 11,
    "sum": 1500,
    "currency": "RUB",
    "paid": true,
    "comments": "Оплата через платёжный шлюз",
    "xmlId": "txn_abc123"
  }'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 19,
    paySystemId: 11,
    sum: 1500,
    currency: 'RUB',
    paid: true,
    comments: 'Оплата через платёжный шлюз',
    xmlId: 'txn_abc123',
  }),
})

const { success, data } = await res.json()
console.log('Payment ID:', data.id)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 19,
    paySystemId: 11,
    sum: 1500,
    currency: 'RUB',
    paid: true,
    comments: 'Оплата через платёжный шлюз',
    xmlId: 'txn_abc123',
  }),
})

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

## Поля ответа

Возвращается полный объект созданной оплаты.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор созданной оплаты |
| `accountNumber` | string | Порядковый номер оплаты на портале (генерируется автоматически) |
| `paySystemName` | string | Название платёжной системы (заполняется из карточки платёжной системы) |

Остальные поля совпадают с переданными в запросе + `datePaid` / `dateBill` могут быть проставлены автоматически.

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

```json
{
  "success": true,
  "data": {
    "id": 217,
    "accountNumber": "98/2",
    "orderId": 19,
    "paySystemId": 11,
    "paySystemName": "Наличные",
    "sum": 1500,
    "currency": "RUB",
    "paid": true,
    "datePaid": "2026-05-13T11:50:24.000Z",
    "dateBill": "2026-05-13T11:50:24.000Z",
    "responsibleId": 1,
    "comments": "Оплата через платёжный шлюз",
    "xmlId": "txn_abc123",
    "isReturn": "N",
    "marked": false
  }
}
```

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

422 — не переданы обязательные поля:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: orderId, paySystemId"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 422 | `BITRIX_ERROR` | Не переданы обязательные поля — сообщение содержит их список (`Required fields: orderId, paySystemId`) |
| 422 | `BITRIX_ERROR` | Несуществующий `orderId` или `paySystemId` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Номер оплаты генерируется автоматически.** Поле `accountNumber` присваивается Битрикс24 при создании в формате `<orderAccount>/<seq>` (например, `19/1`) и не может быть передано в запросе.

**Несколько оплат на один заказ.** У одного заказа может быть несколько оплат — например, частичная предоплата и доплата при доставке. Каждая регистрируется отдельным `POST /v1/payments` с тем же `orderId` и разными `paySystemId` или `sum`.

**Статус заказа не обновляется автоматически.** После регистрации оплаты статус заказа (`orders.payed`, `orders.statusId`) остаётся прежним — обновите его отдельным вызовом [`PATCH /v1/orders/:id`](../orders/update.md).

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

- [Поля оплаты](./fields.md)
- [Список оплат](./list.md)
- [Получить оплату](./get.md)
- [Обновить оплату](./update.md)
- [Обновить заказ](../orders/update.md)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)