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

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

POST /v1/payments

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

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

Параметр Тип Обяз. Описание
orderId number да Идентификатор заказа. Источник: GET /v1/orders
paySystemId number да Идентификатор платёжной системы. На каждом портале свой набор систем. Узнать ID можно из существующих оплат через GET /v1/payments или POST /v1/payments/aggregate с groupBy: "paySystemId"
sum number нет Сумма оплаты. Если не передать — Битрикс24 берёт остаток от суммы заказа
currency string нет Валюта оплаты. По умолчанию — валюта заказа. Список: 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
  }
}

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

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 — Ошибки.

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

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

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

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

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