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

Update a CRM payment

PATCH /v1/crm-payments/:id

Changes a CRM payment's payment system or its "paid" mark: sets the mark or clears it.

Fields are passed flat at the JSON root, without a fields wrapper.

Parameters

Parameter Type Required Description
id (path) number yes Payment ID. List of an item's payments: GET /v1/crm-payments

Request fields (body)

Field Type Required Description
paid boolean no true sets the "paid" mark, false clears it
paySystemId number no ID of an existing payment system. List: GET /v1/pay-systems. The value 0 is rejected, as is the ID of a nonexistent system

Pass at least one of the two fields. The payment amount is the sum of its line items and cannot be set directly.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-payments/565" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paySystemId": 3 }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-payments/565" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paySystemId": 3 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/565', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ paySystemId: 3 }),
})

const { data } = await res.json()
console.log('Payment system:', data.paySystemName)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/565', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ paySystemId: 3 }),
})

const { data } = await res.json()

Response fields

Returns the payment after the change.

Field Type Description
success boolean true on success
data.id number Payment ID
data.accountNumber string Payment number: the linked order number and the payment's sequence number separated by /
data.paid string Paid mark: Y for paid, N for not paid
data.datePaid string | null Time of the latest "paid" mark, ISO 8601 with a time zone offset. null if the payment was never marked
data.empPaidId number | null ID of the employee who last marked the payment. List: GET /v1/users
data.paySystemId number Payment system ID. List: GET /v1/pay-systems
data.sum number Payment amount
data.currency string Currency code. List: GET /v1/currencies
data.paySystemName string Payment system name
meta.readbackUnavailable boolean Returned only with the value true when the change was applied but the payment could not be read back. In that case data contains only id. Do not repeat the request; fetch the payment by this id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 565,
    "accountNumber": "1029/2",
    "paid": "N",
    "datePaid": null,
    "empPaidId": null,
    "paySystemId": 3,
    "sum": 0,
    "currency": "USD",
    "paySystemName": "Bank transfer (Contacts)"
  }
}

Error response example

400 — paid is not a boolean:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "paid must be a boolean."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS The body is missing, is not an object, or is an empty object {}
400 READONLY_FIELD The body contains a field other than paid and paySystemId
400 INVALID_PARAMS paid is not a boolean, for example the string "Y", or paySystemId is negative or not an integer
400 INVALID_ID id is not a positive integer
404 ENTITY_NOT_FOUND No payment with this id exists
422 BITRIX_ERROR No payment system with this paySystemId exists, including 0. Message: Payment system has not been found
422 BITRIX_ERROR Bitrix24 rejected the request; the reason is in error.message
422 BITRIX_NO_EFFECT Bitrix24 did not confirm the change
403 BITRIX_ACCESS_DENIED The key's user has no access to the CRM item or payment in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is not allowed to write
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY X-Api-Key is missing

Full list of common API errors: Errors.

Known specifics

paid has different types in the request and the response. In the request body paid is a boolean, true or false; in the response it is the string Y or N.

paid behaves like the pay and unpay endpoints. paid: true sets the mark, like POST /v1/crm-payments/:id/pay, and paid: false clears it, like POST /v1/crm-payments/:id/unpay. Repeating paid: true on a payment that is already marked paid does not change datePaid. The mark does not transfer money, but it can trigger automation rules, an email or an online receipt.

See also