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
id (path) number yes Payment 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
success boolean true on success
data.id number Payment ID
data.accountNumber string Payment number: the linked order number and the payment sequence number, separated by /
data.paid string Y — the payment is marked as paid
data.datePaid string Time the payment was last marked as paid, ISO 8601 with a time zone offset
data.empPaidId number ID 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
data.paySystemId number Payment system ID. List: GET /v1/pay-systems
data.sum number Payment amount
data.currency string Currency code. List: GET /v1/currencies
data.paySystemName string Payment system name
meta.readbackUnavailable boolean Present 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
404 ENTITY_NOT_FOUND No payment with this id
400 READONLY_FIELD The request body is not empty
400 FST_ERR_CTP_EMPTY_JSON_BODY The Content-Type: application/json header is sent with an empty body. Send {} as the body or remove the header
400 INVALID_ID id is not a positive integer
422 BITRIX_NO_EFFECT Bitrix24 did not confirm the mark
422 BITRIX_ERROR Bitrix24 rejected the request. The reason is in error.message
403 BITRIX_ACCESS_DENIED The key's user has no access to the CRM item or the payment in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is not allowed to write
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY X-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