## 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`](/docs/entities/deals/list) |
| `filter` (query) | object | no | Filter by payment fields from the "Response fields" table — exact value match only; keys cannot contain comparison operators.<br>[Filtering syntax](/docs/filtering). 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

```bash
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

```bash
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`](/docs/entities/users/list) |
| `data[].paySystemId` | number | Payment system ID. List: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `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`](/docs/entities/currencies/list) |
| `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](/docs/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

- [Get a payment](/docs/entities/crm-payments/get)
- [Create a payment](/docs/entities/crm-payments/create)
- [Available product rows](/docs/entities/crm-payments/available-products)
- [CRM payments](/docs/entities/crm-payments)
- [Filtering syntax](/docs/filtering)