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

Оплаты

Управление оплатами заказов: создание, получение, обновление, удаление, поиск, агрегация. Оплата — отдельная сущность, привязанная к заказу по полю orderId. У одного заказа может быть несколько оплат (например, частичная предоплата + доплата при доставке), каждая со своей платёжной системой и статусом.

Битрикс24 API: sale.payment.* Скоуп: sale

Для оплаты по сделке см. оплаты CRM: связанный заказ создаёт Битрикс24. ID оплаты одинаков в обоих разделах; здесь нужен уже существующий заказ.

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

POST /v1/payments

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

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

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

Примеры

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

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

Terminal 
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
  }
}

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

409 — валюта оплаты не совпадает с валютой заказа:

JSON 
{
  "success": false,
  "error": {
    "code": "CURRENCY_MISMATCH",
    "message": "Payment currency \"USD\" does not match order 19, which is in \"RUB\"."
  }
}

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

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

Ошибки

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

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

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

Валюта берётся у заказа. Битрикс24 хранит оплату в валюте её заказа и присланную валюту не применяет. Раньше запрос с чужой валютой отвечал 201, а оплата сохранялась в валюте заказа — без единого замечания. Теперь несовпадение отклоняется с 409 CURRENCY_MISMATCH; чтобы унаследовать валюту заказа, не передавайте поле вовсе. Валюту заказа показывает GET /v1/orders/:id.

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

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

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

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