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, the 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

Field Type Description
id number Payment identifier (read-only)
orderId number Order identifier. Source: GET /v1/orders
paySystemId number Payment system identifier. You can find the ID from existing payments: GET /v1/payments or POST /v1/payments/aggregate with groupBy: "paySystemId"
paySystemName string Payment system name (read-only, filled from the payment system card)
paySystemIsCash boolean Whether the payment system accepts cash (read-only)
paySystemXmlId string External identifier of the payment system for synchronization (read-only)
sum number Payment amount
currency string Payment currency. List: GET /v1/currencies
paid boolean Whether the payment is marked as received
datePaid datetime | null Date the payment was marked as received. null if the payment is not marked
empPaidId number | null Employee who marked the payment (read-only). Source: GET /v1/users
comments string | null Payment comment. null if not set
accountNumber string Sequential payment number within the Bitrix24 account (read-only)
dateBill datetime Invoice issue date
datePayBefore datetime | null Payment due date — date only. In the response the time is always midnight in the Bitrix24 account timezone and carries no separate meaning. null if not set
xmlId string External identifier for synchronization
responsibleId number | null Responsible employee. Source: GET /v1/users. null if not assigned
empResponsibleId number | null Employee responsible for the payment (read-only). Source: GET /v1/users
dateResponsibleId datetime | null Date the responsible employee was assigned (read-only). null if no responsible employee is assigned
isReturn string Return flag: "N" regular payment, "Y" return, "P" partial return
marked boolean Whether the payment is flagged as problematic
reasonMarked string | null Reason for the flag. null if there is no flag
empMarkedId number | null Employee who set the flag (read-only). Source: GET /v1/users
dateMarked datetime | null Date the payment was flagged as problematic (read-only). null if there is no flag
psStatus string | null Payment status according to the payment system. null if the payment did not go 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 according to the payment gateway
psCurrency string | null Payment currency according to the payment gateway
psResponseDate datetime | null Payment gateway response date
psInvoiceId string | null Invoice identifier on the payment gateway side
payVoucherNum string | null Payment voucher number. null if there is no payment voucher
payVoucherDate datetime | null Payment voucher date. null if there is no payment voucher
payReturnNum string | null Return document number. null if there was no return
payReturnDate datetime | null Return date. null if there was no return
payReturnComment string | null Return comment. null if there was no return
empReturnId number | null Employee who processed the return (read-only). Source: GET /v1/users
priceCod number Cash-on-delivery amount. 0 if no cash-on-delivery is set
companyId number | null Paying company from CRM. Source: GET /v1/companies. null if not set
externalPayment boolean Payment created in an external system
id1c string | null Payment identifier in the ERP. null if the payment is not synchronized with the ERP
version1c string | null Payment version in the ERP. null if the payment is not synchronized with the ERP
updated1c boolean Whether the payment was updated via ERP

The aggregatable array lists the fields available for numeric functions and groupBy in POST /v1/payments/aggregate: sum, currency, paid, paySystemId, orderId, responsibleId. The batch array lists the operations available in POST /v1/batch: create, update, delete.

Response example

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 — no 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

Full list of common API errors — Errors.

See also