لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/payments.md فهرس التوثيق — /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

For a deal payment see CRM payments: Bitrix24 creates the linked order. The payment ID is identical in both sections; this section requires an existing order.

Create a payment

POST /v1/payments

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

Request fields (body)

Parameter Type Required Description
ParameterorderId Typenumber Requiredyes DescriptionOrder ID. Source: GET /v1/orders
ParameterpaySystemId Typenumber Requiredyes DescriptionPayment system ID. Each Bitrix24 account has its own set of systems. Available IDs are returned by GET /v1/pay-systems
Parametersum Typenumber Requiredno DescriptionPayment amount. If omitted, Bitrix24 uses the outstanding order amount
Parametercurrency Typestring Requiredno DescriptionPayment currency. Inherited from the order: if the field is provided and differs from the order currency, the request is rejected with 409 CURRENCY_MISMATCH. List: GET /v1/currencies
Parameterpaid Typeboolean Requiredno DescriptionWhether the payment is marked as received. Defaults to false
ParameterdatePaid Typedatetime Requiredno DescriptionDate the payment was marked as received (in ISO 8601 format)
ParameterdateBill Typedatetime Requiredno DescriptionInvoice issue date
ParameterdatePayBefore Typedatetime Requiredno DescriptionPayment due date. Responses return only the date — the time is always midnight in the Bitrix24 account time zone
ParameterresponsibleId Typenumber Requiredno DescriptionResponsible employee. Source: GET /v1/users
Parametercomments Typestring Requiredno DescriptionPayment comment
ParameterxmlId Typestring Requiredno DescriptionExternal ID (for example, the payment gateway 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 through a 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 through a 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 through a 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 through a payment gateway',
    xmlId: 'txn_abc123',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionCreated payment with all fields. Object structure — Payment fields

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 through a payment gateway",
    "xmlId": "txn_abc123",
    "isReturn": "N",
    "marked": false
  }
}

Error response example

409 — the payment currency does not match the order currency:

JSON 
{
  "success": false,
  "error": {
    "code": "CURRENCY_MISMATCH",
    "message": "Payment currency \"USD\" does not match order 19, which is in \"EUR\"."
  }
}

Errors

HTTP Code Description
HTTP409 CodeCURRENCY_MISMATCH DescriptionThe provided currency does not match the currency of order orderId
HTTP422 CodeBITRIX_ERROR DescriptionRequired fields are missing — the message lists them (Required fields: orderId, paySystemId)
HTTP422 CodeBITRIX_ERROR DescriptionThe orderId or paySystemId does not exist
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Errors.

Known specifics

The currency comes from the order. The payment is stored in the order currency. If the provided currency does not match the order currency, the request is rejected with 409 CURRENCY_MISMATCH. To inherit the order currency, omit the currency field. The order currency is returned by GET /v1/orders/:id.

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

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

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

See also