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

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

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

curl — OAuth application

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionPayment schema and available operations
Fielddata.fields Typeobject DescriptionPayment field dictionary: each key is a field name, and each value is an object describing the field. The dictionary fields are listed below
Fieldid Typenumber DescriptionPayment ID (read-only)
FieldorderId Typenumber DescriptionOrder ID. Source: GET /v1/orders
FieldpaySystemId Typenumber DescriptionPayment system ID. Available IDs are returned by GET /v1/pay-systems
FieldpaySystemName Typestring DescriptionPayment system name (read-only, populated from the payment system record)
FieldpaySystemIsCash Typeboolean DescriptionWhether the payment system accepts cash (read-only)
FieldpaySystemXmlId Typestring DescriptionExternal payment system ID for synchronization (read-only)
Fieldsum Typenumber DescriptionPayment amount
Fieldcurrency Typestring DescriptionPayment 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. List: GET /v1/currencies
Fieldpaid Typeboolean DescriptionWhether the payment is marked as received
FielddatePaid Typedatetime | null DescriptionDate the payment was marked as received. null if no date is set
FieldempPaidId Typenumber | null DescriptionEmployee who marked the payment as received (read-only). Source: GET /v1/users
Fieldcomments Typestring | null DescriptionPayment comment. null if not set
FieldaccountNumber Typestring DescriptionSequential payment number on the Bitrix24 account (read-only)
FielddateBill Typedatetime DescriptionInvoice issue date
FielddatePayBefore Typedatetime | null DescriptionPayment 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
FieldxmlId Typestring DescriptionExternal ID for synchronization
FieldresponsibleId Typenumber | null DescriptionResponsible employee. Source: GET /v1/users. null if not assigned
FieldempResponsibleId Typenumber | null DescriptionEmployee responsible for the payment (read-only). Source: GET /v1/users
FielddateResponsibleId Typedatetime | null DescriptionDate the responsible employee was assigned (read-only). null if no responsible person is assigned
FieldisReturn Typestring DescriptionRefund flag: "N" for a regular payment, "Y" for a refund, "P" for a partial refund
Fieldmarked Typeboolean DescriptionWhether 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
FieldreasonMarked Typestring | null DescriptionReason 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
FieldempMarkedId Typenumber | null DescriptionEmployee who set the flag (read-only). Source: GET /v1/users
FielddateMarked Typedatetime | null DescriptionDate the payment was flagged as problematic (read-only). null if it is not flagged
FieldpsStatus Typestring | null DescriptionPayment 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
FieldpsStatusCode Typestring | null DescriptionStatus code from the payment system
FieldpsStatusDescription Typestring | null DescriptionStatus description from the payment system
FieldpsStatusMessage Typestring | null DescriptionMessage from the payment system
FieldpsSum Typenumber | null DescriptionPayment amount reported by the payment gateway
FieldpsCurrency Typestring | null DescriptionPayment currency reported by the payment gateway
FieldpsResponseDate Typedatetime | null DescriptionPayment gateway response date
FieldpsInvoiceId Typestring | null DescriptionInvoice ID on the payment gateway side
FieldpayVoucherNum Typestring | null DescriptionPayment order number. null if there is no payment order
FieldpayVoucherDate Typedatetime | null DescriptionPayment order date. null if there is no payment order
FieldpayReturnNum Typestring | null DescriptionRefund document number. null if there has been no refund
FieldpayReturnDate Typedatetime | null DescriptionRefund date. null if there has been no refund
FieldpayReturnComment Typestring | null DescriptionRefund comment. null if there has been no refund
FieldempReturnId Typenumber | null DescriptionEmployee who processed the refund (read-only). Source: GET /v1/users
FieldpriceCod Typenumber DescriptionCash on delivery amount. 0 if no cash on delivery amount is set
FieldcompanyId Typenumber | null DescriptionPayer company from CRM. Source: GET /v1/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
FieldexternalPayment Typeboolean DescriptionPayment was created in an external system
Fieldid1c Typestring | null DescriptionPayment ID in ERP. null if the payment is not synchronized with ERP
Fieldversion1c Typestring | null DescriptionPayment version in ERP. null if the payment is not synchronized with ERP
Fieldupdated1c Typeboolean DescriptionWhether the payment was updated through ERP

The data.aggregatable array lists the fields for groupBy in POST /v1/payments/aggregate (numeric functions accept any field of type number): sum, currency, paid, paySystemId, orderId, responsibleId. The data.batch array lists operations for POST /v1/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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate 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.

See also