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 Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPayment identifier

Fields to update (body)

Parameter Type Description
ParameterorderId Typenumber DescriptionThe order the payment is linked to. Source: GET /v1/orders
Parametersum Typenumber DescriptionNew payment amount
Parametercurrency Typestring DescriptionPayment 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
Parameterpaid Typeboolean DescriptionWhether the payment is marked as received
ParameterdatePaid Typedatetime DescriptionPayment marking date
ParameterdateBill Typedatetime DescriptionInvoice issue date
Parametercomments Typestring DescriptionPayment comment
ParameterxmlId Typestring DescriptionExternal identifier
ParameterresponsibleId Typenumber DescriptionResponsible employee
ParameterisReturn Typestring DescriptionReturn 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
Fielddata Typeobject DescriptionThe 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
HTTP400 CodeREADONLY_FIELD DescriptionThe 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
HTTP422 CodeBITRIX_ERROR DescriptionA payment with this ID was not found
HTTP400 CodeBITRIX_ERROR DescriptionInvalid field value — for example, an unknown paySystemId
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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