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

List CRM payments

GET /v1/crm-payments

Returns all payments of one CRM item, such as a deal, with filtering and sorting by payment fields.

Parameters

Parameter Type Required Description
ParameterentityTypeId (query) Typenumber Requiredyes DescriptionCRM item type. For a deal — 2
ParameterentityId (query) Typenumber Requiredyes DescriptionCRM item ID. For a deal — the ID from GET /v1/deals
Parameterfilter (query) Typeobject Requiredno DescriptionFilter by payment fields from the "Response fields" table — exact value match only; keys cannot contain comparison operators.
Filtering syntax. Example: ?filter[paid]=Y
Parameterorder (query) Typeobject Requiredno DescriptionSort by payment fields from the "Response fields" table: asc, desc, ASC or DESC. Example: ?order[id]=desc

There is no pagination: the response contains all payments of the item in a single call. The method accepts no other query parameters, including limit and offset.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-payments?entityTypeId=2&entityId=8761&order[id]=asc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-payments?entityTypeId=2&entityId=8761&order[id]=asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({ entityTypeId: '2', entityId: '8761', 'order[id]': 'asc' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/crm-payments?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data, meta } = await res.json()
console.log(`Payments: ${meta.total}`, data.map(p => `${p.accountNumber} — ${p.paid}`))

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({ entityTypeId: '2', entityId: '8761', 'order[id]': 'asc' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/crm-payments?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionPayments of the item. An empty array if the item has no payments
Fielddata[].id Typenumber DescriptionPayment ID
Fielddata[].accountNumber Typestring DescriptionPayment number: the linked order number and the payment sequence number separated by /, for example 1029/2
Fielddata[].paid Typestring DescriptionPaid mark: Y — paid, N — not paid
Fielddata[].datePaid Typestring | null DescriptionTime of the last "paid" mark, ISO 8601 with a time zone offset. null if the payment was never marked
Fielddata[].empPaidId Typenumber | null DescriptionID of the employee who last marked the payment. List: GET /v1/users
Fielddata[].paySystemId Typenumber DescriptionPayment system ID. List: GET /v1/pay-systems
Fielddata[].sum Typenumber DescriptionPayment amount. The sum of the payment's items; 0 for a new payment
Fielddata[].currency Typestring DescriptionCurrency code. List: GET /v1/currencies
Fielddata[].paySystemName Typestring DescriptionPayment system name
Fieldmeta.total Typenumber DescriptionNumber of payments in data

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 563,
      "accountNumber": "1029/1",
      "paid": "N",
      "datePaid": null,
      "empPaidId": null,
      "paySystemId": 19,
      "sum": 3000,
      "currency": "USD",
      "paySystemName": "Card payment"
    },
    {
      "id": 565,
      "accountNumber": "1029/2",
      "paid": "Y",
      "datePaid": "2026-10-05T09:29:34+00:00",
      "empPaidId": 1317,
      "paySystemId": 3,
      "sum": 0,
      "currency": "USD",
      "paySystemName": "Bank transfer (Contacts)"
    }
  ],
  "meta": {
    "total": 2
  }
}

Error response example

400 — filtering or sorting by a field that is not in the response:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Filter and order support only payment response fields."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionentityTypeId or entityId is missing, or the value is not a positive integer
HTTP400 CodeUNKNOWN_FILTER_FIELD Descriptionfilter or order contains a field that is not in the "Response fields" table, a key with a comparison operator, or a sort direction other than asc, desc, ASC, DESC; or another query parameter was passed
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo CRM item exists with this entityTypeId and entityId
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request; the reason is in error.message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the CRM item or the payment in Bitrix24
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not provided

Full list of common API errors — Errors.

Known specifics

Removing the mark does not clear the time and author of the last mark. After the mark is removed, the datePaid and empPaidId fields keep the values of the last mark. Only paid reflects the current state.

See also