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
entityTypeId (query) number yes CRM item type. For a deal — 2
entityId (query) number yes CRM item ID. For a deal — the ID from GET /v1/deals
filter (query) object no Filter by payment fields from the "Response fields" table — exact value match only; keys cannot contain comparison operators.
Filtering syntax. Example: ?filter[paid]=Y
order (query) object no Sort 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
success boolean true on success
data array Payments of the item. An empty array if the item has no payments
data[].id number Payment ID
data[].accountNumber string Payment number: the linked order number and the payment sequence number separated by /, for example 1029/2
data[].paid string Paid mark: Y — paid, N — not paid
data[].datePaid string | null Time of the last "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. The sum of the payment's items; 0 for a new payment
data[].currency string Currency code. List: GET /v1/currencies
data[].paySystemName string Payment system name
meta.total number Number 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
400 MISSING_REQUIRED_FIELDS entityTypeId or entityId is missing, or the value is not a positive integer
400 UNKNOWN_FILTER_FIELD filter 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
404 ENTITY_NOT_FOUND No CRM item exists with this entityTypeId and entityId
422 BITRIX_ERROR Bitrix24 rejected the request; the reason is in error.message
403 BITRIX_ACCESS_DENIED The key's user has no access to the CRM item or the payment in Bitrix24
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 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