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
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
marked boolean Whether the payment is flagged as problematic
reasonMarked string Reason for the flag
isReturn string Return flag: "N", "Y", "P"

All 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
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 by paySystemId. These values are set by Bitrix24 and are ignored on update.

See also