## 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`](/docs/entities/crm-payments/list) |

Send no request body or send `{}`.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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`](/docs/entities/users/list) |
| `data.paySystemId` | number | Payment system ID. List: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `data.sum` | number | Payment amount |
| `data.currency` | string | Currency code. List: [`GET /v1/currencies`](/docs/entities/currencies/list) |
| `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](/docs/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](/docs/entities/crm-payments/delete) it, remove the mark with [`POST /v1/crm-payments/:id/unpay`](/docs/entities/crm-payments/unpay).

## See also

- [Remove the paid mark](/docs/entities/crm-payments/unpay)
- [Update a CRM payment](/docs/entities/crm-payments/update)
- [Get a CRM payment](/docs/entities/crm-payments/get)
- [CRM payments](/docs/entities/crm-payments)