لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/crm-payments.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

CRM payments

Payments of a CRM item, such as a deal: creating a payment, filling it with products from the item's product rows, setting the "paid" mark and removing it.

Bitrix24 API: crm.item.payment.* Scope: crm

Create a CRM payment

POST /v1/crm-payments

Creates an empty payment for a CRM item, such as a deal: no line items, a zero amount and no "paid" mark.

Products are added to the payment in the next step, as payment line items. Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldentityTypeId Typenumber Requiredyes DescriptionCRM item type. For a deal, 2
FieldentityId Typenumber Requiredyes DescriptionCRM item ID. For a deal, the ID from GET /v1/deals
FieldpaySystemId Typenumber Requiredno DescriptionPayment system ID, a non-negative integer. List: GET /v1/pay-systems. If omitted or 0, a payment system is assigned automatically and its ID is returned in the response

The amount and the paid mark cannot be set at creation.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 8761, "paySystemId": 1 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 8761, "paySystemId": 1 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityTypeId: 2, entityId: 8761, paySystemId: 1 }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entityTypeId: 2, entityId: 8761, paySystemId: 1 }),
})

const { data } = await res.json()

Response fields

The HTTP status of a successful response is 201.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionID of the created payment
Fielddata.accountNumber Typestring DescriptionPayment number: the linked order number and the payment's sequence number separated by /, for example 1029/2
Fielddata.paid Typestring DescriptionPaid mark, N for a new payment
Fielddata.datePaid Typenull Descriptionnull for a new payment
Fielddata.empPaidId Typenull Descriptionnull for a new payment
Fielddata.paySystemId Typenumber DescriptionPayment system ID, either the one passed or the one assigned automatically. List: GET /v1/pay-systems
Fielddata.sum Typenumber DescriptionPayment amount, 0 for a new payment
Fielddata.currency Typestring DescriptionCurrency code. List: GET /v1/currencies
Fielddata.paySystemName Typestring DescriptionPayment system name
Fieldmeta.readbackUnavailable Typeboolean DescriptionReturned only with the value true when the payment was created but could not be read back. In that case data contains only id. Do not create it again. Fetch the payment by this id instead

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 565,
    "accountNumber": "1029/2",
    "paid": "N",
    "datePaid": null,
    "empPaidId": null,
    "paySystemId": 1,
    "sum": 0,
    "currency": "USD",
    "paySystemName": "Bank transfer (Companies)"
  }
}

Error response example

400 — paySystemId is negative or not an integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "paySystemId must be a non-negative integer."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionentityTypeId or entityId is missing, or the value is not a positive integer
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field other than entityTypeId, entityId and paySystemId
HTTP400 CodeINVALID_PARAMS DescriptionpaySystemId is negative or not an integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo CRM item with this entityTypeId and entityId exists
HTTP422 CodeBITRIX_NO_EFFECT DescriptionThe payment was not created, for example because no payment system with this paySystemId exists. No new payment appears on the item
HTTP422 CodeBITRIX_ERROR DescriptionCRM items of this type have no payments, for example a lead with entityTypeId equal to 1. The message says that payment creation is unavailable for this entity
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the CRM item or the payment in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is not allowed to write
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is missing

Full list of common API errors: Errors.

See also