For AI agents: markdown of this page — /docs-content-en/entities/payments/update.md documentation index — /llms.txt

Update a payment

PATCH /v1/payments/:id

Updates fields of an existing payment. Pass only the changed fields flat at the root of the JSON — no fields wrapper.

Parameters

Parameter Type Req. Description
id (path) number yes Payment identifier

Fields to update (body)

Parameter Type Description
orderId number The order the payment is linked to. Source: GET /v1/orders
sum number New payment amount
currency string Payment currency. Inherited from the order: Bitrix24 stores a payment in the currency of its order. On update a mismatch with the order is not checked — the request body carries no order, and whether the value sent is applied has not been measured. On create a mismatch is refused with 409 CURRENCY_MISMATCH — see Create a payment
paid boolean Whether the payment is marked as received
datePaid datetime Payment marking date
dateBill datetime Invoice issue date
comments string Payment comment
xmlId string External identifier
responsibleId number Responsible employee
isReturn string Return flag: "N", "Y", "P"

The problematic-payment flag marked and its reason reasonMarked are not accepted on update — the platform assigns the value, and a request carrying either field is refused with 400 READONLY_FIELD. Set them when creating the payment.

The remaining payment fields are editable except the service ones (id, accountNumber, paySystemName, empPaidId, empResponsibleId, empMarkedId, empReturnId). The full set of available fields is visible in the GET /v1/payments/:id response.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/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": "Confirmed by the bank"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/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": "Confirmed by the bank"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Confirmed by the bank',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Confirmed by the bank',
  }),
})

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

Response fields

Field Type Description
data object The updated payment object with all fields

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 17,
    "accountNumber": "19/1",
    "orderId": 19,
    "paySystemId": 11,
    "paySystemName": "Cash",
    "sum": 0,
    "currency": "USD",
    "paid": true,
    "datePaid": "2026-05-13T09:00:00.000Z",
    "dateBill": "2020-05-14T20:00:00.000Z",
    "responsibleId": 1,
    "comments": "Confirmed by the bank",
    "xmlId": "bx_5ebe943aacfa0",
    "isReturn": "N",
    "marked": false
  }
}

Error response example

422 — payment not found:

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

Errors

HTTP Code Description
400 READONLY_FIELD The body carried the problematic-payment flag marked or its reason reasonMarked. The check runs before the call to Bitrix24, so this refusal arrives even for a non-existent id. Both fields are accepted when creating the payment
422 BITRIX_ERROR A payment with this ID was not found
400 BITRIX_ERROR Invalid field value — for example, an unknown paySystemId
403 SCOPE_DENIED The API key does not have the sale scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The paySystemId field is pulled in automatically. Before updating a payment, Vibecode fetches the current paySystemId value via GET /v1/payments/:id and automatically adds it to the request if it was not passed. This gives single-field PATCH semantics — without having to specify the payment system every time.

The accountNumber and paySystemName fields are read-only. accountNumber is assigned when the payment is created, and paySystemName is filled from the payment system card identified by paySystemId. These values are set by Bitrix24 and are ignored on update.

See also