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

Mark a CRM payment as paid

POST /v1/crm-payments/:id/pay

Marks a CRM payment as paid and records when the mark was set and which employee set it. The mark does not transfer money, but it can trigger automation rules, an email or an online receipt.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPayment ID. Payments of an item: GET /v1/crm-payments

Send no request body or send {}.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/565/pay" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/565/pay" \
  -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/crm-payments/565/pay', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log(`Payment ${data.accountNumber} marked as paid: ${data.datePaid}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/565/pay', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Response fields

Returns the payment after the mark is set.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionPayment ID
Fielddata.accountNumber Typestring DescriptionPayment number: the linked order number and the payment sequence number, separated by /
Fielddata.paid Typestring DescriptionY — the payment is marked as paid
Fielddata.datePaid Typestring DescriptionTime the payment was last marked as paid, ISO 8601 with a time zone offset
Fielddata.empPaidId Typenumber DescriptionID of the employee who set the mark — the key's user. A repeated call for a payment that is already marked does not change the value. List: GET /v1/users
Fielddata.paySystemId Typenumber DescriptionPayment system ID. List: GET /v1/pay-systems
Fielddata.sum Typenumber DescriptionPayment amount
Fielddata.currency Typestring DescriptionCurrency code. List: GET /v1/currencies
Fielddata.paySystemName Typestring DescriptionPayment system name
Fieldmeta.readbackUnavailable Typeboolean DescriptionPresent only as true when the mark is set but the payment could not be read back. In that case data contains only id. You do not need to repeat the request — get the payment by this id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 565,
    "accountNumber": "1029/2",
    "paid": "Y",
    "datePaid": "2026-10-05T09:29:34+00:00",
    "empPaidId": 1317,
    "paySystemId": 3,
    "sum": 0,
    "currency": "USD",
    "paySystemName": "Bank transfer (Contacts)"
  }
}

Error response example

404 — no payment with this ID:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Payment has not been found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo payment with this id
HTTP400 CodeREADONLY_FIELD DescriptionThe request body is not empty
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header is sent with an empty body. Send {} as the body or remove the header
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not confirm the mark
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 not sent

Full list of common API errors — Errors.

Known specifics

A repeated mark does not change the payment. A call for a payment that is already marked as paid returns 200 with the same datePaid and empPaidId.

A payment marked as paid cannot be deleted. Before deleting it, remove the mark with POST /v1/crm-payments/:id/unpay.

See also