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

Payments

Manage order payments: create, get, update, delete, search, aggregate. A payment is a separate entity linked to an order via the orderId field. A single order can have several payments (for example, a partial prepayment plus a balance payment on delivery), each with its own payment system and status.

Bitrix24 API: sale.payment.* Scope: sale

Create a payment

POST /v1/payments

Registers a new payment for an existing order. The request body is flat — no fields wrapper.

Request fields (body)

Parameter Type Req. Description
orderId number yes Order identifier. Source: GET /v1/orders
paySystemId number yes Payment system identifier. Each Bitrix24 account has its own set of systems. You can find the ID from existing payments via GET /v1/payments or POST /v1/payments/aggregate with groupBy: "paySystemId"
sum number no Payment amount. If omitted, Bitrix24 takes the remaining balance of the order total
currency string no Payment currency. Defaults to the order currency. List: GET /v1/currencies
paid boolean no Whether the payment is marked as received. Defaults to false
datePaid datetime no Payment marking date (in ISO 8601 format)
dateBill datetime no Invoice issue date
datePayBefore datetime no Payment due date. In responses only the date is returned — the time is always midnight in the Bitrix24 account timezone
responsibleId number no Responsible employee. Source: GET /v1/users
comments string no Payment comment
xmlId string no External identifier (for example, the payment gateway's transaction ID)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/payments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 19,
    "paySystemId": 11,
    "sum": 1500,
    "currency": "USD",
    "paid": true,
    "comments": "Payment via payment gateway",
    "xmlId": "txn_abc123"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/payments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 19,
    "paySystemId": 11,
    "sum": 1500,
    "currency": "USD",
    "paid": true,
    "comments": "Payment via payment gateway",
    "xmlId": "txn_abc123"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 19,
    paySystemId: 11,
    sum: 1500,
    currency: 'USD',
    paid: true,
    comments: 'Payment via payment gateway',
    xmlId: 'txn_abc123',
  }),
})

const { success, data } = await res.json()
console.log('Payment ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 19,
    paySystemId: 11,
    sum: 1500,
    currency: 'USD',
    paid: true,
    comments: 'Payment via payment gateway',
    xmlId: 'txn_abc123',
  }),
})

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

Response fields

Returns the full object of the created payment.

Field Type Description
id number Identifier of the created payment
accountNumber string Sequential payment number within the Bitrix24 account (generated automatically)
paySystemName string Payment system name (filled from the payment system card)

The remaining fields match those passed in the request, plus datePaid / dateBill may be set automatically.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 217,
    "accountNumber": "98/2",
    "orderId": 19,
    "paySystemId": 11,
    "paySystemName": "Cash",
    "sum": 1500,
    "currency": "USD",
    "paid": true,
    "datePaid": "2026-05-13T11:50:24.000Z",
    "dateBill": "2026-05-13T11:50:24.000Z",
    "responsibleId": 1,
    "comments": "Payment via payment gateway",
    "xmlId": "txn_abc123",
    "isReturn": "N",
    "marked": false
  }
}

Error response example

422 — required fields are missing:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: orderId, paySystemId"
  }
}

Errors

HTTP Code Description
422 BITRIX_ERROR Required fields are missing — the message contains their list (Required fields: orderId, paySystemId)
422 BITRIX_ERROR Non-existent orderId or paySystemId
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

The payment number is generated automatically. The accountNumber field is assigned by Bitrix24 on creation in the format <orderAccount>/<seq> (for example, 19/1) and cannot be passed in the request.

Several payments per order. A single order can have several payments — for example, a partial prepayment and a balance payment on delivery. Each is registered with a separate POST /v1/payments using the same orderId and different paySystemId or sum.

The order status is not updated automatically. After a payment is registered, the order status (orders.payed, orders.statusId) stays the same — update it with a separate PATCH /v1/orders/:id call.

See also