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

List payments

GET /v1/payments

Returns a list of order payments with support for filtering and auto-pagination.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50, Vibecode automatically requests several pages from Bitrix24
offset number 0 Skip N records. When offset ≥ 2500, limit ≤ 500 is recommended
select string — Field selection: ?select=id,orderId,sum,paid
order object — Sorting: ?order[id]=desc
filter object — Filtering by key payment fields.
Filtering syntax. Example: ?filter[orderId]=19

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/payments?limit=10&filter[paid]=true&order[id]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/payments?limit=10&filter[paid]=true&order[id]=desc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments?limit=10&filter[paid]=true&order[id]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} payments`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments?limit=10&filter[paid]=true&order[id]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of payments (each contains all payment fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "accountNumber": "19/1",
      "orderId": 19,
      "paySystemId": 11,
      "paySystemName": "Cash",
      "sum": 0,
      "currency": "USD",
      "paid": false,
      "datePaid": "2020-05-14T20:00:00.000Z",
      "dateBill": "2020-05-14T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ebe943aacfa0"
    },
    {
      "id": 19,
      "accountNumber": "21/1",
      "orderId": 21,
      "paySystemId": 11,
      "paySystemName": "Cash",
      "sum": 0,
      "currency": "USD",
      "paid": false,
      "datePaid": "2020-05-17T20:00:00.000Z",
      "dateBill": "2020-05-17T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ec2368b6e74d"
    }
  ],
  "meta": {
    "total": 99,
    "hasMore": true
  }
}

Key fields are shown. For the full payment response, see GET /v1/payments/:id.

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filtering by a field that is not in the payment schema
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

Auto-pagination: when limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

When to use search instead of list: POST /v1/payments/search passes parameters in the request body rather than the query string — suited for complex filters with many conditions.

The isReturn field is a string with three values. It accepts "N" (regular payment), "Y" (return) and "P" (partial return) — filtering by it works on these string values.

See also