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

POST /v1/payments

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

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

Параметр Тип Обяз. Описание
orderId number да Идентификатор заказа. Источник: `GET /v1/orders`
paySystemId number да Идентификатор платёжной системы. На каждом портале свой набор систем. REST API не выставляет эндпоинт для перечисления; 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 Название платёжной системы (берётся из карточки paySystemId)

Остальные поля совпадают с переданными в запросе + 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
  }
}

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

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

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

#Ошибки

HTTP Код Описание
400 BITRIX_ERROR Не переданы обязательные поля — сообщение содержит их список (Required fields: orderId или paySystemId)
400 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`.

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