#Обновить оплату

PATCH /v1/payments/:id

Обновляет поля существующей оплаты. Передавайте только изменяемые поля плоско в корне JSON — без обёртки fields.

#Параметры

Параметр Тип Обяз. Описание
id (path) number да Идентификатор оплаты

#Поля для обновления (body)

Параметр Тип Описание
sum number Новая сумма оплаты
currency string Валюта оплаты
paid boolean Помечена ли оплата как поступившая
datePaid datetime Дата отметки оплаты
dateBill datetime Дата выставления счёта
comments string Комментарий к оплате
xmlId string Внешний идентификатор
responsibleId number Ответственный сотрудник
marked boolean Помечена ли оплата как проблемная
reasonMarked string Причина пометки
isReturn string Признак возврата: "N", "Y", "P"

Редактируются все поля оплаты, кроме служебных (id, accountNumber, paySystemName, empPaidId, empResponsibleId, empMarkedId, empReturnId). Полный набор доступных полей виден в ответе `GET /v1/payments/:id`.

#Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/payments/17" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paid": true,
    "datePaid": "2026-05-13T12:00:00",
    "comments": "Подтверждено банком"
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/payments/17" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paid": true,
    "datePaid": "2026-05-13T12:00:00",
    "comments": "Подтверждено банком"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments/17', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    paid: true,
    datePaid: '2026-05-13T12:00:00',
    comments: 'Подтверждено банком',
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments/17', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    paid: true,
    datePaid: '2026-05-13T12:00:00',
    comments: 'Подтверждено банком',
  }),
})

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

#Поля ответа

Поле Тип Описание
data object Обновлённый объект оплаты со всеми полями

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

JSON 
{
  "success": true,
  "data": {
    "id": 17,
    "accountNumber": "19/1",
    "orderId": 19,
    "paySystemId": 11,
    "paySystemName": "Наличные",
    "sum": 0,
    "currency": "RUB",
    "paid": true,
    "datePaid": "2026-05-13T09:00:00.000Z",
    "dateBill": "2020-05-14T20:00:00.000Z",
    "responsibleId": 1,
    "comments": "Подтверждено банком",
    "xmlId": "bx_5ebe943aacfa0",
    "isReturn": "N",
    "marked": false
  }
}

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

422 — оплата не найдена:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "payment is not exists"
  }
}

#Ошибки

HTTP Код Описание
422 BITRIX_ERROR Оплата с таким ID не найдена
400 BITRIX_ERROR Некорректное значение поля — например, неизвестный paySystemId
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Поле paySystemId подтягивается автоматически. Вайбкод перед обновлением оплаты получает текущее значение paySystemId через GET /v1/payments/:id и автоматически добавляет его в запрос, если оно не передано. Это даёт привычную семантику PATCH с одним полем — без необходимости каждый раз указывать платёжную систему.

Поля accountNumber, orderId, paySystemName доступны только для чтения. Их значения проставляются Битрикс24 (accountNumber — при создании, paySystemName — из карточки paySystemId); попытка изменить — игнорируется.

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