## Payment fields

`GET /v1/payments/fields`

Returns the payment field schema: types, read-only flags, and a list of aggregatable fields.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/payments/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/payments/fields" \
  -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/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Payment fields:', Object.keys(data.fields))
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/payments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
```

## Response fields

The table describes the response envelope and the fields in the `data.fields` schema. For payment fields, the type of their values is shown. Each schema field is an object with the keys `type`, `readonly`, `label`, and `description`.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Payment schema and available operations |
| `data.fields` | object | Payment field dictionary: each key is a field name, and each value is an object describing the field. The dictionary fields are listed below |
| `id` | number | Payment ID (read-only) |
| `orderId` | number | Order ID. Source: [`GET /v1/orders`](../orders/list.md) |
| `paySystemId` | number | Payment system ID. Available IDs are returned by [GET /v1/pay-systems](/docs/entities/pay-systems/list) |
| `paySystemName` | string | Payment system name (read-only, populated from the payment system record) |
| `paySystemIsCash` | boolean | Whether the payment system accepts cash (read-only) |
| `paySystemXmlId` | string | External payment system ID for synchronization (read-only) |
| `sum` | number | Payment amount |
| `currency` | string | Payment currency, inherited from the order. On creation, a value that differs from the order currency is rejected with `409 CURRENCY_MISMATCH`. On update, the field is not checked — see [Create a payment](./create.md). List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `paid` | boolean | Whether the payment is marked as received |
| `datePaid` | datetime \| null | Date the payment was marked as received. `null` if no date is set |
| `empPaidId` | number \| null | Employee who marked the payment as received (read-only). Source: [`GET /v1/users`](/docs/entities/users) |
| `comments` | string \| null | Payment comment. `null` if not set |
| `accountNumber` | string | Sequential payment number on the Bitrix24 account (read-only) |
| `dateBill` | datetime | Invoice issue date |
| `datePayBefore` | datetime \| null | Payment due date, with no meaningful time component. The time component in the response is always midnight in the Bitrix24 account time zone and has no separate meaning. Bitrix24 marks the field as deprecated: it is still stored and returned, but new integrations should not rely on it. `null` if not set |
| `xmlId` | string | External ID for synchronization |
| `responsibleId` | number \| null | Responsible employee. Source: [`GET /v1/users`](/docs/entities/users). `null` if not assigned |
| `empResponsibleId` | number \| null | Employee responsible for the payment (read-only). Source: [`GET /v1/users`](/docs/entities/users) |
| `dateResponsibleId` | datetime \| null | Date the responsible employee was assigned (read-only). `null` if no responsible person is assigned |
| `isReturn` | string | Refund flag: `"N"` for a regular payment, `"Y"` for a refund, `"P"` for a partial refund |
| `marked` | boolean | Whether the payment is flagged as problematic. Accepted only on creation: on update, writing to this field is rejected with `400 READONLY_FIELD`. Marked as `readonlyOnUpdate` in the `/fields` response |
| `reasonMarked` | string \| null | Reason for the flag. `null` if it is not flagged. Accepted only on creation: on update, writing to this field is rejected with `400 READONLY_FIELD`. Marked as `readonlyOnUpdate` in the `/fields` response |
| `empMarkedId` | number \| null | Employee who set the flag (read-only). Source: [`GET /v1/users`](/docs/entities/users) |
| `dateMarked` | datetime \| null | Date the payment was flagged as problematic (read-only). `null` if it is not flagged |
| `psStatus` | string \| null | Payment system status flag: `"Y"` means the payment was confirmed, `"N"` means it was not confirmed. This is not status text. `null` if the payment was not processed through a payment system |
| `psStatusCode` | string \| null | Status code from the payment system |
| `psStatusDescription` | string \| null | Status description from the payment system |
| `psStatusMessage` | string \| null | Message from the payment system |
| `psSum` | number \| null | Payment amount reported by the payment gateway |
| `psCurrency` | string \| null | Payment currency reported by the payment gateway |
| `psResponseDate` | datetime \| null | Payment gateway response date |
| `psInvoiceId` | string \| null | Invoice ID on the payment gateway side |
| `payVoucherNum` | string \| null | Payment order number. `null` if there is no payment order |
| `payVoucherDate` | datetime \| null | Payment order date. `null` if there is no payment order |
| `payReturnNum` | string \| null | Refund document number. `null` if there has been no refund |
| `payReturnDate` | datetime \| null | Refund date. `null` if there has been no refund |
| `payReturnComment` | string \| null | Refund comment. `null` if there has been no refund |
| `empReturnId` | number \| null | Employee who processed the refund (read-only). Source: [`GET /v1/users`](/docs/entities/users) |
| `priceCod` | number | Cash on delivery amount. `0` if no cash on delivery amount is set |
| `companyId` | number \| null | Payer company from CRM. Source: [`GET /v1/companies`](/docs/entities/companies). Bitrix24 accepts the field on creation and update but does not use it, so the value does not affect the payment. `null` if not set |
| `externalPayment` | boolean | Payment was created in an external system |
| `id1c` | string \| null | Payment ID in ERP. `null` if the payment is not synchronized with ERP |
| `version1c` | string \| null | Payment version in ERP. `null` if the payment is not synchronized with ERP |
| `updated1c` | boolean | Whether the payment was updated through ERP |

The `data.aggregatable` array lists the fields for `groupBy` in [`POST /v1/payments/aggregate`](./aggregate.md) (numeric functions accept any field of type `number`): `sum`, `currency`, `paid`, `paySystemId`, `orderId`, `responsibleId`. The `data.batch` array lists operations for [`POST /v1/batch`](/docs/batch): `create`, `update`, `delete`.

## Response example

In addition to `type` and `readonly`, each field contains `label` (a short name) and `description` (an explanation) in English. Request headers do not switch the language. They are omitted from the example below for brevity.

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "orderId": { "type": "number", "readonly": false },
      "paySystemId": { "type": "number", "readonly": false },
      "paySystemName": { "type": "string", "readonly": true },
      "paySystemIsCash": { "type": "boolean", "readonly": true },
      "paySystemXmlId": { "type": "string", "readonly": true },
      "sum": { "type": "number", "readonly": false },
      "currency": { "type": "string", "readonly": false },
      "paid": { "type": "boolean", "readonly": false },
      "datePaid": { "type": "datetime", "readonly": false },
      "empPaidId": { "type": "number", "readonly": true },
      "comments": { "type": "string", "readonly": false },
      "accountNumber": { "type": "string", "readonly": true },
      "dateBill": { "type": "datetime", "readonly": false },
      "datePayBefore": { "type": "datetime", "readonly": false },
      "xmlId": { "type": "string", "readonly": false },
      "responsibleId": { "type": "number", "readonly": false },
      "empResponsibleId": { "type": "number", "readonly": true },
      "dateResponsibleId": { "type": "datetime", "readonly": true },
      "isReturn": { "type": "string", "readonly": false },
      "marked": { "type": "boolean", "readonly": false },
      "reasonMarked": { "type": "string", "readonly": false },
      "empMarkedId": { "type": "number", "readonly": true },
      "dateMarked": { "type": "datetime", "readonly": true },
      "psStatus": { "type": "string", "readonly": false },
      "psStatusCode": { "type": "string", "readonly": false },
      "psStatusDescription": { "type": "string", "readonly": false },
      "psStatusMessage": { "type": "string", "readonly": false },
      "psSum": { "type": "number", "readonly": false },
      "psCurrency": { "type": "string", "readonly": false },
      "psResponseDate": { "type": "datetime", "readonly": false },
      "psInvoiceId": { "type": "string", "readonly": false },
      "payVoucherNum": { "type": "string", "readonly": false },
      "payVoucherDate": { "type": "datetime", "readonly": false },
      "payReturnNum": { "type": "string", "readonly": false },
      "payReturnDate": { "type": "datetime", "readonly": false },
      "payReturnComment": { "type": "string", "readonly": false },
      "empReturnId": { "type": "number", "readonly": true },
      "priceCod": { "type": "number", "readonly": false },
      "companyId": { "type": "number", "readonly": false },
      "externalPayment": { "type": "boolean", "readonly": false },
      "id1c": { "type": "string", "readonly": false },
      "version1c": { "type": "string", "readonly": false },
      "updated1c": { "type": "boolean", "readonly": false }
    },
    "aggregatable": ["sum", "currency", "paid", "paySystemId", "orderId", "responsibleId"],
    "batch": ["create", "update", "delete"]
  }
}
```

## Error response example

403 — missing scope:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Create a payment](./create.md)
- [Update a payment](./update.md)
- [List payments](./list.md)
- [Aggregate payments](./aggregate.md)
- [Orders](../orders.md)
- [Entity API](/docs/entity-api)