[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-entities\u002Fpayments":3,"docs-tabs-entities\u002Fpayments":6},{"content":4,"lastmod":5},"# Оплаты\n\nУправление оплатами заказов: создание, получение, обновление, удаление, поиск, агрегация. Оплата — отдельная сущность, привязанная к заказу по полю `orderId`. У одного заказа может быть несколько оплат (например, частичная предоплата + доплата при доставке), каждая со своей платёжной системой и статусом.\n\nБитрикс24 API: `sale.payment.*`\nСкоуп: `sale`\n\n## Операции\n\n- [Создать оплату](.\u002Fpayments\u002Fcreate.md) — `POST \u002Fv1\u002Fpayments`\n- [Список оплат](.\u002Fpayments\u002Flist.md) — `GET \u002Fv1\u002Fpayments`\n- [Получить оплату](.\u002Fpayments\u002Fget.md) — `GET \u002Fv1\u002Fpayments\u002F:id`\n- [Обновить оплату](.\u002Fpayments\u002Fupdate.md) — `PATCH \u002Fv1\u002Fpayments\u002F:id`\n- [Удалить оплату](.\u002Fpayments\u002Fdelete.md) — `DELETE \u002Fv1\u002Fpayments\u002F:id`\n- [Поиск оплат](.\u002Fpayments\u002Fsearch.md) — `POST \u002Fv1\u002Fpayments\u002Fsearch`\n- [Поля оплаты](.\u002Fpayments\u002Ffields.md) — `GET \u002Fv1\u002Fpayments\u002Ffields`\n- [Агрегация оплат](.\u002Fpayments\u002Faggregate.md) — `POST \u002Fv1\u002Fpayments\u002Faggregate`\n\n## Ключевые поля\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор оплаты (только чтение) |\n| `accountNumber` | string | Порядковый номер оплаты на портале (только чтение) |\n| `orderId` | number | Идентификатор заказа. Источник: [`GET \u002Fv1\u002Forders`](.\u002Forders\u002Flist.md) |\n| `paySystemId` | number | Идентификатор платёжной системы. На каждом портале свой набор систем. Узнать ID можно из существующих оплат: `GET \u002Fv1\u002Fpayments` или `POST \u002Fv1\u002Fpayments\u002Faggregate` с `groupBy: \"paySystemId\"` |\n| `paySystemName` | string | Название платёжной системы (только чтение, приходит из карточки платёжной системы) |\n| `sum` | number | Сумма оплаты |\n| `currency` | string | Валюта оплаты. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `paid` | boolean | Помечена ли оплата как поступившая |\n| `datePaid` | datetime | Дата отметки оплаты |\n| `dateBill` | datetime | Дата выставления счёта |\n| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `isReturn` | string | Признак возврата: `\"N\"` (обычная оплата), `\"Y\"` (возврат), `\"P\"` (частичный возврат) |\n| `comments` | string | Комментарий к оплате |\n| `xmlId` | string | Внешний идентификатор для синхронизации |\n\nПолный список полей — [Поля оплаты](.\u002Fpayments\u002Ffields.md).\n\n## Что нужно знать перед работой\n\n1. **Оплата всегда привязана к заказу.** Поле `orderId` обязательно при создании — без существующего заказа оплату создать нельзя, сначала вызовите [`POST \u002Fv1\u002Forders`](.\u002Forders\u002Fcreate.md). На один заказ можно зарегистрировать несколько оплат (предоплата, доплата при доставке) — каждая отдельным `POST \u002Fv1\u002Fpayments`.\n2. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{\"orderId\": 19, \"paySystemId\": 11, ...}`. Обёртка `fields` не нужна.\n3. **Поле `isReturn` — строка, а не boolean.** Принимает три значения: `\"N\"` (обычная оплата), `\"Y\"` (возврат) и `\"P\"` (частичный возврат) — фильтр и обновление работают по этим строкам.\n4. **Сумма заказа не пересчитывается при создании оплаты.** Регистрация оплаты не меняет статус заказа (`orders.payed`, `orders.statusId`) — обновите их отдельным [`PATCH \u002Fv1\u002Forders\u002F:id`](.\u002Forders\u002Fupdate.md), если нужно отметить заказ как оплаченный.\n\n## Связанные сущности\n\n| Сущность | Эндпоинт | Назначение |\n|----------|----------|-----------|\n| Заказы | [`GET \u002Fv1\u002Forders\u002F:id`](.\u002Forders\u002Fget.md) | Родительский заказ — `orderId` указывается при создании оплаты. |\n| Позиции корзины | [`GET \u002Fv1\u002Fbasket-items?filter[orderId]=:id`](.\u002Fbasket-items\u002Flist.md) | Товары в том же заказе. |\n| Сотрудники | [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) | Источник `responsibleId`. |\n\n## Типичный сценарий\n\nРегистрация оплаты от внешнего платёжного шлюза:\n\n1. Найти заказ: [`GET \u002Fv1\u002Forders?filter[xmlId]=:externalOrderId`](.\u002Forders\u002Flist.md) — например, по внешнему идентификатору заказа.\n2. Создать оплату: [`POST \u002Fv1\u002Fpayments`](.\u002Fpayments\u002Fcreate.md) с `orderId`, `paySystemId`, `sum`, `paid: true`, `xmlId` платёжной транзакции.\n3. Обновить статус заказа после оплаты: [`PATCH \u002Fv1\u002Forders\u002F:id`](.\u002Forders\u002Fupdate.md) с `payed: true`, `statusId: \"F\"` (или другим финальным статусом).\n\n## Лимиты\n\n| Лимит | Значение |\n|-------|----------|\n| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |\n| Автоматическая пагинация | включается при `limit > 50` |\n| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |\n| Batch-запросы | до 50 операций в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch) |\n| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) |\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Fpayments\u002Ffields.md)\n- [Заказы](.\u002Forders.md)\n- [Позиции корзины](.\u002Fbasket-items.md)\n- [Статусы заказов](.\u002Forder-statuses.md)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Справочник сущностей](\u002Fdocs\u002Fentities-index)\n","2026-06-29",{"payments\u002Fcreate.md":7,"payments\u002Flist.md":8,"payments\u002Fget.md":9,"payments\u002Fupdate.md":10,"payments\u002Fdelete.md":11,"payments\u002Fsearch.md":12,"payments\u002Ffields.md":13,"payments\u002Faggregate.md":14},"\n## Создать оплату\n\n`POST \u002Fv1\u002Fpayments`\n\nРегистрирует новую оплату для существующего заказа. Тело запроса плоское — без обёртки `fields`.\n\n## Поля запроса (тело)\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `orderId` | number | да | Идентификатор заказа. Источник: [`GET \u002Fv1\u002Forders`](..\u002Forders\u002Flist.md) |\n| `paySystemId` | number | да | Идентификатор платёжной системы. На каждом портале свой набор систем. Узнать ID можно из существующих оплат через [`GET \u002Fv1\u002Fpayments`](.\u002Flist.md) или [`POST \u002Fv1\u002Fpayments\u002Faggregate`](.\u002Faggregate.md) с `groupBy: \"paySystemId\"` |\n| `sum` | number | нет | Сумма оплаты. Если не передать — Битрикс24 берёт остаток от суммы заказа |\n| `currency` | string | нет | Валюта оплаты. По умолчанию — валюта заказа. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `paid` | boolean | нет | Помечена ли оплата как поступившая. По умолчанию `false` |\n| `datePaid` | datetime | нет | Дата отметки оплаты (в формате ISO 8601) |\n| `dateBill` | datetime | нет | Дата выставления счёта |\n| `datePayBefore` | datetime | нет | Срок оплаты |\n| `responsibleId` | number | нет | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `comments` | string | нет | Комментарий к оплате |\n| `xmlId` | string | нет | Внешний идентификатор (например, ID транзакции платёжного шлюза) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderId\": 19,\n    \"paySystemId\": 11,\n    \"sum\": 1500,\n    \"currency\": \"RUB\",\n    \"paid\": true,\n    \"comments\": \"Оплата через платёжный шлюз\",\n    \"xmlId\": \"txn_abc123\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderId\": 19,\n    \"paySystemId\": 11,\n    \"sum\": 1500,\n    \"currency\": \"RUB\",\n    \"paid\": true,\n    \"comments\": \"Оплата через платёжный шлюз\",\n    \"xmlId\": \"txn_abc123\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    orderId: 19,\n    paySystemId: 11,\n    sum: 1500,\n    currency: 'RUB',\n    paid: true,\n    comments: 'Оплата через платёжный шлюз',\n    xmlId: 'txn_abc123',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Payment ID:', data.id)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    orderId: 19,\n    paySystemId: 11,\n    sum: 1500,\n    currency: 'RUB',\n    paid: true,\n    comments: 'Оплата через платёжный шлюз',\n    xmlId: 'txn_abc123',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\nВозвращается полный объект созданной оплаты.\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор созданной оплаты |\n| `accountNumber` | string | Порядковый номер оплаты на портале (генерируется автоматически) |\n| `paySystemName` | string | Название платёжной системы (берётся из карточки `paySystemId`) |\n\nОстальные поля совпадают с переданными в запросе + `datePaid` \u002F `dateBill` могут быть проставлены автоматически.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 217,\n    \"accountNumber\": \"98\u002F2\",\n    \"orderId\": 19,\n    \"paySystemId\": 11,\n    \"paySystemName\": \"Наличные\",\n    \"sum\": 1500,\n    \"currency\": \"RUB\",\n    \"paid\": true,\n    \"datePaid\": \"2026-05-13T11:50:24.000Z\",\n    \"dateBill\": \"2026-05-13T11:50:24.000Z\",\n    \"responsibleId\": 1,\n    \"comments\": \"Оплата через платёжный шлюз\",\n    \"xmlId\": \"txn_abc123\",\n    \"isReturn\": \"N\",\n    \"marked\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — не переданы обязательные поля:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Required fields: orderId, paySystemId\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Не переданы обязательные поля — сообщение содержит их список (`Required fields: orderId, paySystemId`) |\n| 422 | `BITRIX_ERROR` | Несуществующий `orderId` или `paySystemId` |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Номер оплаты генерируется автоматически.** Поле `accountNumber` присваивается Битрикс24 при создании в формате `\u003CorderAccount>\u002F\u003Cseq>` (например, `19\u002F1`) и не может быть передано в запросе.\n\n**Несколько оплат на один заказ.** У одного заказа может быть несколько оплат — например, частичная предоплата и доплата при доставке. Каждая регистрируется отдельным `POST \u002Fv1\u002Fpayments` с тем же `orderId` и разными `paySystemId` или `sum`.\n\n**Статус заказа не обновляется автоматически.** После регистрации оплаты статус заказа (`orders.payed`, `orders.statusId`) остаётся прежним — обновите его отдельным вызовом [`PATCH \u002Fv1\u002Forders\u002F:id`](..\u002Forders\u002Fupdate.md).\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Список оплат](.\u002Flist.md)\n- [Получить оплату](.\u002Fget.md)\n- [Обновить оплату](.\u002Fupdate.md)\n- [Обновить заказ](..\u002Forders\u002Fupdate.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Список оплат\n\n`GET \u002Fv1\u002Fpayments`\n\nВозвращает список оплат заказов с поддержкой фильтрации и автоматической пагинации.\n\n## Параметры\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `limit` | number | `50` | Количество записей (до 5000). При `limit > 50` Вайбкод автоматически запрашивает несколько страниц у Битрикс24 |\n| `offset` | number | `0` | Пропустить N записей. При `offset ≥ 2500` рекомендуется `limit ≤ 500` |\n| `select` | string | — | Выборка полей: `?select=id,orderId,sum,paid` |\n| `order` | object | — | Сортировка: `?order[id]=desc` |\n| `filter` | object | — | Фильтрация по ключевым полям оплаты.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `?filter[orderId]=19` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments?limit=10&filter[paid]=true&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments?limit=10&filter[paid]=true&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments?limit=10&filter[paid]=true&order[id]=desc', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Найдено ${meta.total} оплат`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments?limit=10&filter[paid]=true&order[id]=desc', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив оплат (каждая содержит все поля оплаты) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 17,\n      \"accountNumber\": \"19\u002F1\",\n      \"orderId\": 19,\n      \"paySystemId\": 11,\n      \"paySystemName\": \"Наличные\",\n      \"sum\": 0,\n      \"currency\": \"RUB\",\n      \"paid\": false,\n      \"datePaid\": \"2020-05-14T20:00:00.000Z\",\n      \"dateBill\": \"2020-05-14T20:00:00.000Z\",\n      \"responsibleId\": 1,\n      \"isReturn\": \"N\",\n      \"comments\": \"\",\n      \"xmlId\": \"bx_5ebe943aacfa0\"\n    },\n    {\n      \"id\": 19,\n      \"accountNumber\": \"21\u002F1\",\n      \"orderId\": 21,\n      \"paySystemId\": 11,\n      \"paySystemName\": \"Наличные\",\n      \"sum\": 0,\n      \"currency\": \"RUB\",\n      \"paid\": false,\n      \"datePaid\": \"2020-05-17T20:00:00.000Z\",\n      \"dateBill\": \"2020-05-17T20:00:00.000Z\",\n      \"responsibleId\": 1,\n      \"isReturn\": \"N\",\n      \"comments\": \"\",\n      \"xmlId\": \"bx_5ec2368b6e74d\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 99,\n    \"hasMore\": true\n  }\n}\n```\n\nПоказаны основные поля. Полный ответ оплаты — см. [`GET \u002Fv1\u002Fpayments\u002F:id`](.\u002Fget.md).\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'sale' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Фильтр по полю, которого нет в схеме оплаты |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Автоматическая пагинация:** при `limit > 50` Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе.\n\n**Когда использовать `search` вместо `list`:** [`POST \u002Fv1\u002Fpayments\u002Fsearch`](.\u002Fsearch.md) передаёт параметры в теле запроса, а не в строке запроса — подходит для сложных фильтров с множеством условий.\n\n**Поле `isReturn` — строка с тремя значениями.** Принимает `\"N\"` (обычная оплата), `\"Y\"` (возврат) и `\"P\"` (частичный возврат) — фильтр по нему работает по этим строковым значениям.\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Поиск оплат](.\u002Fsearch.md)\n- [Получить оплату](.\u002Fget.md)\n- [Создать оплату](.\u002Fcreate.md)\n- [Заказ](..\u002Forders\u002Fget.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Получить оплату\n\n`GET \u002Fv1\u002Fpayments\u002F:id`\n\nВозвращает одну оплату по идентификатору со всеми полями.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор оплаты |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Оплата:', data.sum, data.currency, '—', data.paySystemName)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор оплаты |\n| `accountNumber` | string | Порядковый номер оплаты на портале |\n| `orderId` | number | Идентификатор заказа |\n| `paySystemId` | number | Идентификатор платёжной системы |\n| `paySystemName` | string | Название платёжной системы |\n| `paySystemIsCash` | boolean | Принимает ли платёжная система наличные (только чтение) |\n| `paySystemXmlId` | string | Внешний идентификатор платёжной системы (только чтение) |\n| `sum` | number | Сумма оплаты |\n| `currency` | string | Валюта оплаты |\n| `paid` | boolean | Помечена ли оплата как поступившая |\n| `datePaid` | datetime \\| null | Дата отметки оплаты. `null`, если оплата не отмечена |\n| `dateBill` | datetime | Дата выставления счёта |\n| `datePayBefore` | datetime \\| null | Срок оплаты. `null`, если не задан |\n| `dateMarked` | datetime \\| null | Дата пометки оплаты как проблемной (только чтение). `null`, если пометки нет |\n| `dateResponsibleId` | datetime \\| null | Дата назначения ответственного (только чтение). `null`, если ответственный не назначен |\n| `responsibleId` | number \\| null | Ответственный сотрудник. `null`, если не назначен |\n| `comments` | string \\| null | Комментарий к оплате. `null`, если не задан |\n| `xmlId` | string | Внешний идентификатор |\n| `isReturn` | string | Признак возврата: `\"N\"` обычная оплата, `\"Y\"` возврат, `\"P\"` частичный возврат |\n| `marked` | boolean | Помечена ли оплата как проблемная |\n| `reasonMarked` | string \\| null | Причина пометки. `null`, если пометки нет |\n| `empPaidId` | number \\| null | Сотрудник, отметивший оплату (только чтение) |\n| `empResponsibleId` | number \\| null | Сотрудник, ответственный за оплату (только чтение) |\n| `empMarkedId` | number \\| null | Сотрудник, поставивший пометку (только чтение) |\n| `empReturnId` | number \\| null | Сотрудник, оформивший возврат (только чтение) |\n| `psStatus` | string \\| null | Статус оплаты по данным платёжной системы. `null`, если оплата не проводилась через платёжную систему |\n| `psStatusCode` | string \\| null | Код статуса от платёжной системы |\n| `psStatusDescription` | string \\| null | Описание статуса от платёжной системы |\n| `psStatusMessage` | string \\| null | Сообщение от платёжной системы |\n| `psSum` | number \\| null | Сумма оплаты по данным платёжного шлюза |\n| `psCurrency` | string \\| null | Валюта оплаты по данным платёжного шлюза |\n| `psResponseDate` | datetime \\| null | Дата ответа платёжного шлюза |\n| `psInvoiceId` | string \\| null | Идентификатор счёта на стороне платёжного шлюза |\n| `payVoucherNum` | string \\| null | Номер платёжного поручения. `null`, если поручения нет |\n| `payVoucherDate` | datetime \\| null | Дата платёжного поручения. `null`, если поручения нет |\n| `payReturnNum` | string \\| null | Номер документа возврата. `null`, если возврата не было |\n| `payReturnDate` | datetime \\| null | Дата возврата. `null`, если возврата не было |\n| `payReturnComment` | string \\| null | Комментарий к возврату. `null`, если возврата не было |\n| `priceCod` | number | Сумма наложенного платежа |\n| `companyId` | number \\| null | Компания-плательщик из CRM. `null`, если не задана |\n| `externalPayment` | boolean | Оплата создана во внешней системе |\n| `id1c` | string \\| null | Идентификатор оплаты в 1С. `null`, если оплата не синхронизирована с 1С |\n| `version1c` | string \\| null | Версия оплаты в 1С. `null`, если оплата не синхронизирована с 1С |\n| `updated1c` | boolean | Обновлена ли оплата через 1С |\n\nПолный список полей со ссылками на источники идентификаторов — [Поля оплаты](.\u002Ffields.md).\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 17,\n    \"accountNumber\": \"19\u002F1\",\n    \"orderId\": 19,\n    \"paySystemId\": 11,\n    \"paySystemName\": \"Наличные\",\n    \"paySystemIsCash\": true,\n    \"paySystemXmlId\": \"bx_61372545d32ae\",\n    \"sum\": 0,\n    \"currency\": \"RUB\",\n    \"paid\": false,\n    \"datePaid\": \"2020-05-14T20:00:00.000Z\",\n    \"dateBill\": \"2020-05-14T20:00:00.000Z\",\n    \"datePayBefore\": null,\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2020-05-15T12:08:16.000Z\",\n    \"responsibleId\": 1,\n    \"empPaidId\": null,\n    \"empResponsibleId\": 1,\n    \"empMarkedId\": null,\n    \"empReturnId\": null,\n    \"comments\": \"\",\n    \"reasonMarked\": null,\n    \"xmlId\": \"bx_5ebe943aacfa0\",\n    \"id1c\": null,\n    \"version1c\": null,\n    \"updated1c\": false,\n    \"externalPayment\": false,\n    \"isReturn\": \"N\",\n    \"marked\": false,\n    \"priceCod\": 0,\n    \"companyId\": null,\n    \"payReturnNum\": null,\n    \"payReturnDate\": null,\n    \"payReturnComment\": null,\n    \"payVoucherNum\": null,\n    \"payVoucherDate\": null,\n    \"psStatus\": null,\n    \"psStatusCode\": null,\n    \"psStatusDescription\": null,\n    \"psStatusMessage\": null,\n    \"psSum\": null,\n    \"psCurrency\": null,\n    \"psInvoiceId\": null,\n    \"psResponseDate\": null\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — оплата не найдена:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"payment is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Оплата с таким ID не найдена |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Обновить оплату](.\u002Fupdate.md)\n- [Удалить оплату](.\u002Fdelete.md)\n- [Список оплат](.\u002Flist.md)\n- [Заказ](..\u002Forders\u002Fget.md)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Обновить оплату\n\n`PATCH \u002Fv1\u002Fpayments\u002F:id`\n\nОбновляет поля существующей оплаты. Передавайте только изменяемые поля плоско в корне JSON — без обёртки `fields`.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор оплаты |\n\n## Поля для обновления (тело)\n\n| Параметр | Тип | Описание |\n|----------|-----|---------|\n| `orderId` | number | Заказ, к которому привязана оплата. Источник: [`GET \u002Fv1\u002Forders`](..\u002Forders\u002Flist.md) |\n| `sum` | number | Новая сумма оплаты |\n| `currency` | string | Валюта оплаты |\n| `paid` | boolean | Помечена ли оплата как поступившая |\n| `datePaid` | datetime | Дата отметки оплаты |\n| `dateBill` | datetime | Дата выставления счёта |\n| `comments` | string | Комментарий к оплате |\n| `xmlId` | string | Внешний идентификатор |\n| `responsibleId` | number | Ответственный сотрудник |\n| `marked` | boolean | Помечена ли оплата как проблемная |\n| `reasonMarked` | string | Причина пометки |\n| `isReturn` | string | Признак возврата: `\"N\"`, `\"Y\"`, `\"P\"` |\n\nРедактируются все поля оплаты, кроме служебных (`id`, `accountNumber`, `paySystemName`, `empPaidId`, `empResponsibleId`, `empMarkedId`, `empReturnId`). Полный набор доступных полей виден в ответе [`GET \u002Fv1\u002Fpayments\u002F:id`](.\u002Fget.md).\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"paid\": true,\n    \"datePaid\": \"2026-05-13T12:00:00\",\n    \"comments\": \"Подтверждено банком\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"paid\": true,\n    \"datePaid\": \"2026-05-13T12:00:00\",\n    \"comments\": \"Подтверждено банком\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    paid: true,\n    datePaid: '2026-05-13T12:00:00',\n    comments: 'Подтверждено банком',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F17', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    paid: true,\n    datePaid: '2026-05-13T12:00:00',\n    comments: 'Подтверждено банком',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `data` | object | Обновлённый объект оплаты со всеми полями |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 17,\n    \"accountNumber\": \"19\u002F1\",\n    \"orderId\": 19,\n    \"paySystemId\": 11,\n    \"paySystemName\": \"Наличные\",\n    \"sum\": 0,\n    \"currency\": \"RUB\",\n    \"paid\": true,\n    \"datePaid\": \"2026-05-13T09:00:00.000Z\",\n    \"dateBill\": \"2020-05-14T20:00:00.000Z\",\n    \"responsibleId\": 1,\n    \"comments\": \"Подтверждено банком\",\n    \"xmlId\": \"bx_5ebe943aacfa0\",\n    \"isReturn\": \"N\",\n    \"marked\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — оплата не найдена:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"payment is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Оплата с таким ID не найдена |\n| 400 | `BITRIX_ERROR` | Некорректное значение поля — например, неизвестный `paySystemId` |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Поле `paySystemId` подтягивается автоматически.** Вайбкод перед обновлением оплаты получает текущее значение `paySystemId` через `GET \u002Fv1\u002Fpayments\u002F:id` и автоматически добавляет его в запрос, если оно не передано. Это даёт семантику `PATCH` с одним полем — без необходимости каждый раз указывать платёжную систему.\n\n**Поля `accountNumber` и `paySystemName` доступны только для чтения.** `accountNumber` присваивается при создании оплаты, `paySystemName` заполняется из карточки платёжной системы по `paySystemId`. Эти значения проставляет Битрикс24, при обновлении они игнорируются.\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Получить оплату](.\u002Fget.md)\n- [Список оплат](.\u002Flist.md)\n- [Удалить оплату](.\u002Fdelete.md)\n- [Обновить заказ](..\u002Forders\u002Fupdate.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Удалить оплату\n\n`DELETE \u002Fv1\u002Fpayments\u002F:id`\n\nУдаляет оплату по идентификатору. Восстановить удалённую оплату через API нельзя — создавайте новую при необходимости.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор оплаты |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F217\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F217\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F217', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Оплата удалена')\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002F217', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Оплата удалена')\n}\n```\n\n## Ответ\n\nПри успешном удалении возвращается HTTP-статус `204 No Content` с пустым телом — успех проверяется по статусу.\n\n## Пример ответа\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Пример ответа при ошибке\n\n422 — оплата не найдена:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"payment is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Оплата с таким ID не найдена или уже удалена |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Заказ не удаляется.** Удаление оплаты не затрагивает родительский заказ — заказ остаётся, поле `sumPaid` пересчитывается автоматически.\n\n**Альтернатива — пометка возврата.** Чтобы сохранить запись о платеже, используйте [`PATCH \u002Fv1\u002Fpayments\u002F:id`](.\u002Fupdate.md) с `{\"isReturn\": \"Y\", \"comments\": \"...\"}` — оплата останется в выборках с `filter[isReturn]=Y`.\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Обновить оплату](.\u002Fupdate.md)\n- [Список оплат](.\u002Flist.md)\n- [Получить оплату](.\u002Fget.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Поиск оплат\n\n`POST \u002Fv1\u002Fpayments\u002Fsearch`\n\nПоиск оплат с фильтрацией и автоматической пагинацией. Аналогичен [`GET \u002Fv1\u002Fpayments`](.\u002Flist.md), но параметры передаются в теле POST-запроса — подходит для сложных запросов с большим количеством условий.\n\n## Поля запроса (тело)\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `filter` | object | — | Фильтрация по полям оплаты.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering) |\n| `limit` | number | `50` | Количество записей (до 5000) |\n| `select` | string[] | — | Выборка полей: `[\"id\", \"orderId\", \"sum\", \"paid\"]` |\n| `order` | object | — | Сортировка: `{ \"id\": \"desc\" }` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderId\": 19, \"paid\": true },\n    \"limit\": 10,\n    \"select\": [\"id\", \"orderId\", \"sum\", \"currency\", \"paid\", \"datePaid\"]\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderId\": 19, \"paid\": true },\n    \"limit\": 10,\n    \"select\": [\"id\", \"orderId\", \"sum\", \"currency\", \"paid\", \"datePaid\"]\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { orderId: 19, paid: true },\n    limit: 10,\n    select: ['id', 'orderId', 'sum', 'currency', 'paid', 'datePaid'],\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log('Найдено:', meta.total)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { orderId: 19, paid: true },\n    limit: 10,\n    select: ['id', 'orderId', 'sum', 'currency', 'paid', 'datePaid'],\n  }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив оплат |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 17,\n      \"orderId\": 19,\n      \"sum\": 0,\n      \"currency\": \"RUB\",\n      \"paid\": false,\n      \"datePaid\": \"2020-05-14T20:00:00.000Z\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 1,\n    \"hasMore\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — фильтр по несуществующему полю:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'foo' for entity 'payments'. Available: id, orderId, paySystemId, sum, currency, paid, ...\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Фильтр по полю, которого нет в схеме оплаты |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`select` ограничивает поля в ответе.** Если передан `select`, в каждом элементе `data[]` будут только перечисленные поля. Без `select` возвращаются все поля оплаты.\n\n**Поле `isReturn` — строка.** Принимает `\"N\"`, `\"Y\"` и `\"P\"` — фильтр и обновление работают по этим значениям.\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Список оплат](.\u002Flist.md)\n- [Получить оплату](.\u002Fget.md)\n- [Заказ](..\u002Forders\u002Fget.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Поля оплаты\n\n`GET \u002Fv1\u002Fpayments\u002Ffields`\n\nВозвращает схему полей оплаты: типы, флаги только-для-чтения, список агрегируемых полей.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Поля оплаты:', Object.keys(data.fields))\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор оплаты (только чтение) |\n| `orderId` | number | Идентификатор заказа. Источник: [`GET \u002Fv1\u002Forders`](..\u002Forders\u002Flist.md) |\n| `paySystemId` | number | Идентификатор платёжной системы. Узнать ID можно из существующих оплат: [`GET \u002Fv1\u002Fpayments`](.\u002Flist.md) или [`POST \u002Fv1\u002Fpayments\u002Faggregate`](.\u002Faggregate.md) с `groupBy: \"paySystemId\"` |\n| `paySystemName` | string | Название платёжной системы (только чтение, заполняется из карточки платёжной системы) |\n| `paySystemIsCash` | boolean | Принимает ли платёжная система наличные (только чтение) |\n| `paySystemXmlId` | string | Внешний идентификатор платёжной системы для синхронизации (только чтение) |\n| `sum` | number | Сумма оплаты |\n| `currency` | string | Валюта оплаты. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `paid` | boolean | Помечена ли оплата как поступившая |\n| `datePaid` | datetime | Дата отметки оплаты |\n| `empPaidId` | number | Сотрудник, отметивший оплату (только чтение). Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `comments` | string | Комментарий к оплате |\n| `accountNumber` | string | Порядковый номер оплаты на портале (только чтение) |\n| `dateBill` | datetime | Дата выставления счёта |\n| `datePayBefore` | datetime | Срок оплаты |\n| `xmlId` | string | Внешний идентификатор для синхронизации |\n| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `empResponsibleId` | number | Сотрудник, ответственный за оплату (только чтение). Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `dateResponsibleId` | datetime | Дата назначения ответственного сотрудника (только чтение) |\n| `isReturn` | string | Признак возврата: `\"N\"` обычная оплата, `\"Y\"` возврат, `\"P\"` частичный возврат |\n| `marked` | boolean | Помечена ли оплата как проблемная |\n| `reasonMarked` | string | Причина пометки |\n| `empMarkedId` | number | Сотрудник, поставивший пометку (только чтение). Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `dateMarked` | datetime | Дата пометки оплаты как проблемной (только чтение) |\n| `psStatus` | string | Статус оплаты по данным платёжной системы |\n| `psStatusCode` | string | Код статуса от платёжной системы |\n| `psStatusDescription` | string | Описание статуса от платёжной системы |\n| `psStatusMessage` | string | Сообщение от платёжной системы |\n| `psSum` | number | Сумма оплаты по данным платёжного шлюза |\n| `psCurrency` | string | Валюта оплаты по данным платёжного шлюза |\n| `psResponseDate` | datetime | Дата ответа платёжного шлюза |\n| `psInvoiceId` | string | Идентификатор счёта на стороне платёжного шлюза |\n| `payVoucherNum` | string | Номер платёжного поручения |\n| `payVoucherDate` | datetime | Дата платёжного поручения |\n| `payReturnNum` | string | Номер документа возврата |\n| `payReturnDate` | datetime | Дата возврата |\n| `payReturnComment` | string | Комментарий к возврату |\n| `empReturnId` | number | Сотрудник, оформивший возврат (только чтение). Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `priceCod` | number | Сумма наложенного платежа |\n| `companyId` | number | Компания-плательщик из CRM. Источник: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies) |\n| `externalPayment` | boolean | Оплата создана во внешней системе |\n| `id1c` | string | Идентификатор оплаты в 1С |\n| `version1c` | string | Версия оплаты в 1С |\n| `updated1c` | boolean | Обновлена ли оплата через 1С |\n\nМассив `aggregatable` перечисляет поля, доступные для числовых функций и `groupBy` в [`POST \u002Fv1\u002Fpayments\u002Faggregate`](.\u002Faggregate.md): `sum`, `currency`, `paid`, `paySystemId`, `orderId`, `responsibleId`. Массив `batch` — операции для [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch): `create`, `update`, `delete`.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": { \"type\": \"number\", \"readonly\": true },\n      \"orderId\": { \"type\": \"number\", \"readonly\": false },\n      \"paySystemId\": { \"type\": \"number\", \"readonly\": false },\n      \"paySystemName\": { \"type\": \"string\", \"readonly\": true },\n      \"paySystemIsCash\": { \"type\": \"boolean\", \"readonly\": true },\n      \"paySystemXmlId\": { \"type\": \"string\", \"readonly\": true },\n      \"sum\": { \"type\": \"number\", \"readonly\": false },\n      \"currency\": { \"type\": \"string\", \"readonly\": false },\n      \"paid\": { \"type\": \"boolean\", \"readonly\": false },\n      \"datePaid\": { \"type\": \"datetime\", \"readonly\": false },\n      \"empPaidId\": { \"type\": \"number\", \"readonly\": true },\n      \"comments\": { \"type\": \"string\", \"readonly\": false },\n      \"accountNumber\": { \"type\": \"string\", \"readonly\": true },\n      \"dateBill\": { \"type\": \"datetime\", \"readonly\": false },\n      \"datePayBefore\": { \"type\": \"datetime\", \"readonly\": false },\n      \"xmlId\": { \"type\": \"string\", \"readonly\": false },\n      \"responsibleId\": { \"type\": \"number\", \"readonly\": false },\n      \"empResponsibleId\": { \"type\": \"number\", \"readonly\": true },\n      \"dateResponsibleId\": { \"type\": \"datetime\", \"readonly\": true },\n      \"isReturn\": { \"type\": \"string\", \"readonly\": false },\n      \"marked\": { \"type\": \"boolean\", \"readonly\": false },\n      \"reasonMarked\": { \"type\": \"string\", \"readonly\": false },\n      \"empMarkedId\": { \"type\": \"number\", \"readonly\": true },\n      \"dateMarked\": { \"type\": \"datetime\", \"readonly\": true },\n      \"psStatus\": { \"type\": \"string\", \"readonly\": false },\n      \"psStatusCode\": { \"type\": \"string\", \"readonly\": false },\n      \"psStatusDescription\": { \"type\": \"string\", \"readonly\": false },\n      \"psStatusMessage\": { \"type\": \"string\", \"readonly\": false },\n      \"psSum\": { \"type\": \"number\", \"readonly\": false },\n      \"psCurrency\": { \"type\": \"string\", \"readonly\": false },\n      \"psResponseDate\": { \"type\": \"datetime\", \"readonly\": false },\n      \"psInvoiceId\": { \"type\": \"string\", \"readonly\": false },\n      \"payVoucherNum\": { \"type\": \"string\", \"readonly\": false },\n      \"payVoucherDate\": { \"type\": \"datetime\", \"readonly\": false },\n      \"payReturnNum\": { \"type\": \"string\", \"readonly\": false },\n      \"payReturnDate\": { \"type\": \"datetime\", \"readonly\": false },\n      \"payReturnComment\": { \"type\": \"string\", \"readonly\": false },\n      \"empReturnId\": { \"type\": \"number\", \"readonly\": true },\n      \"priceCod\": { \"type\": \"number\", \"readonly\": false },\n      \"companyId\": { \"type\": \"number\", \"readonly\": false },\n      \"externalPayment\": { \"type\": \"boolean\", \"readonly\": false },\n      \"id1c\": { \"type\": \"string\", \"readonly\": false },\n      \"version1c\": { \"type\": \"string\", \"readonly\": false },\n      \"updated1c\": { \"type\": \"boolean\", \"readonly\": false }\n    },\n    \"aggregatable\": [\"sum\", \"currency\", \"paid\", \"paySystemId\", \"orderId\", \"responsibleId\"],\n    \"batch\": [\"create\", \"update\", \"delete\"]\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'sale' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Создать оплату](.\u002Fcreate.md)\n- [Обновить оплату](.\u002Fupdate.md)\n- [Список оплат](.\u002Flist.md)\n- [Агрегация оплат](.\u002Faggregate.md)\n- [Заказы](..\u002Forders.md)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n","\n## Агрегация оплат\n\n`POST \u002Fv1\u002Fpayments\u002Faggregate`\n\nПодсчёт количества оплат и числовые агрегации (`sum`, `avg`, `min`, `max`) по полю `sum`. Поддерживает фильтрацию и группировку по `paySystemId`, `orderId`, `currency`, `paid`, `responsibleId`.\n\n## Стандартные поля\n\n| Поле | Назначение |\n|------|------------|\n| `sum` | Единственное числовое поле — подходит для `sum` \u002F `avg` \u002F `min` \u002F `max` (название поля и функции совпадают, но это разные сущности) |\n| `paySystemId`, `orderId`, `responsibleId` | Идентификаторы — используются в `groupBy` (по платёжной системе, заказу, ответственному) |\n| `currency` | Категориальное — используется в `groupBy` (по валюте) |\n| `paid` | Логическое — используется в `groupBy` (оплачено \u002F не оплачено) |\n\nПолный список агрегируемых полей перечислен в таблице выше.\n\n## Поля запроса (тело)\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `aggregate` | array | нет | Массив агрегаций: `[{ \"field\": \"sum\", \"function\": \"sum\" }]`. Функции: `count`, `sum`, `avg`, `min`, `max`. Для `count` поле — `\"*\"`. Без параметра — только `count` (один запрос в Битрикс24, записи не выгружаются) |\n| `filter` | object | нет | Фильтрация — те же поля, что в [`GET \u002Fv1\u002Fpayments`](.\u002Flist.md). [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering) |\n| `groupBy` | string \\| string[] | нет | Поле или массив полей для группировки (максимум 5) |\n| `groupOrderBy` | array | нет | Сортировка групп: `[{ \"field\": \"sum:sum\", \"direction\": \"desc\" }]` |\n| `groupLimit` | number | нет | Ограничение количества возвращаемых групп (1-1000) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [{ \"field\": \"sum\", \"function\": \"sum\" }],\n    \"groupBy\": \"paySystemId\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [{ \"field\": \"sum\", \"function\": \"sum\" }],\n    \"groupBy\": \"paySystemId\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [{ field: 'sum', function: 'sum' }],\n    groupBy: 'paySystemId',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log(data.groups)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fpayments\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [{ field: 'sum', function: 'sum' }],\n    groupBy: 'paySystemId',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Другие сценарии\n\nПодсчёт записей — `count` с полем `\"*\"`, самый быстрый запрос без выгрузки записей. Без массива `aggregate` результат тот же:\n\n```json\n{ \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }] }\n```\n\nСумма всех принятых оплат:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"sum\", \"function\": \"sum\" }],\n  \"filter\": { \"paid\": true }\n}\n```\n\nТоп-3 платёжных систем по сумме с сортировкой:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"sum\", \"function\": \"sum\" }],\n  \"groupBy\": \"paySystemId\",\n  \"groupOrderBy\": [{ \"field\": \"sum:sum\", \"direction\": \"desc\" }],\n  \"groupLimit\": 3\n}\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.count` | number | Общее количество оплат, соответствующих фильтру |\n| `data.aggregates` | object | Результаты агрегаций: `{ \"sum\": { \"sum\": ..., \"avg\": ... } }` |\n| `data.groups` | array | Группы (только при `groupBy`) |\n| `data.meta.totalRecords` | number | Общее количество записей |\n| `data.meta.recordsProcessed` | number | Количество обработанных записей (до 5000) |\n| `data.meta.truncated` | boolean | `true`, если записей больше 5000 |\n| `data.meta.groupTotal` | number | Количество групп до `groupLimit` |\n| `data.meta.groupsTruncated` | boolean | Был ли список групп обрезан `groupLimit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 99,\n    \"aggregates\": {\n      \"sum\": { \"sum\": 8475.87 }\n    },\n    \"groups\": [\n      {\n        \"paySystemId\": 11,\n        \"count\": 87,\n        \"aggregates\": { \"sum\": { \"sum\": 5870.5 } }\n      },\n      {\n        \"paySystemId\": 6,\n        \"count\": 8,\n        \"aggregates\": { \"sum\": { \"sum\": 2025.37 } }\n      },\n      {\n        \"paySystemId\": 25,\n        \"count\": 4,\n        \"aggregates\": { \"sum\": { \"sum\": 580 } }\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 99,\n      \"recordsProcessed\": 99,\n      \"truncated\": false,\n      \"groupTotal\": 3,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nБез `groupBy` поле `data.groups` в ответе отсутствует.\n\n## Пример ответа при ошибке\n\n400 — поле в `groupBy` вне списка агрегируемых:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"groupBy field 'foo' is not aggregatable on this entity. Available: sum, currency, paid, paySystemId, orderId, responsibleId.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | Неизвестная функция агрегации |\n| 400 | `INVALID_PARAMS` | Несуществующее числовое поле в `aggregate[].field` — сообщение `Field 'foo' not found. Available numeric fields: …` |\n| 400 | `INVALID_PARAMS` | Поле в `groupBy` вне списка агрегируемых — сообщение `groupBy field 'foo' is not aggregatable on this entity. Available: …` |\n| 400 | `INVALID_PARAMS` | Передано больше 5 полей в `groupBy` |\n| 400 | `INVALID_PARAMS` | Зарезервированные ключевые слова в `groupBy`: `count`, `aggregates`, `meta`, `groups` |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`count` против числовых функций.** `count` считается одним запросом в Битрикс24 — записи не выгружаются, ответ возвращается быстро на любом объёме. `sum` \u002F `avg` \u002F `min` \u002F `max` подгружают записи постранично (максимум 5000) и считают на стороне Вайбкод. При более чем 5000 записях `meta.truncated` будет `true`.\n\n**Группировка по `currency` важна на мультивалютных порталах.** Сумма всех оплат в `data.aggregates.sum.sum` без `groupBy: \"currency\"` смешивает разные валюты — реальный смысл получается только при разделении.\n\n## Смотрите также\n\n- [Поля оплаты](.\u002Ffields.md)\n- [Список оплат](.\u002Flist.md)\n- [Поиск оплат](.\u002Fsearch.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n"]