## 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](/docs/entities/crm-payments/products-add). Fields are passed flat at the JSON root, without a `fields` wrapper.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `entityTypeId` | number | yes | CRM item type. For a deal, `2` |
| `entityId` | number | yes | CRM item ID. For a deal, the ID from [`GET /v1/deals`](/docs/entities/deals/list) |
| `paySystemId` | number | no | Payment system ID, a non-negative integer. List: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list). 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

```bash
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

```bash
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 |
|------|-----|---------|
| `success` | boolean | `true` on success |
| `data.id` | number | ID of the created payment |
| `data.accountNumber` | string | Payment number: the linked order number and the payment's sequence number separated by `/`, for example `1029/2` |
| `data.paid` | string | Paid mark, `N` for a new payment |
| `data.datePaid` | null | `null` for a new payment |
| `data.empPaidId` | null | `null` for a new payment |
| `data.paySystemId` | number | Payment system ID, either the one passed or the one assigned automatically. List: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `data.sum` | number | Payment amount, `0` for a new payment |
| `data.currency` | string | Currency code. List: [`GET /v1/currencies`](/docs/entities/currencies/list) |
| `data.paySystemName` | string | Payment system name |
| `meta.readbackUnavailable` | boolean | Returned 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 |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_FIELDS` | `entityTypeId` or `entityId` is missing, or the value is not a positive integer |
| 400 | `READONLY_FIELD` | The body contains a field other than `entityTypeId`, `entityId` and `paySystemId` |
| 400 | `INVALID_PARAMS` | `paySystemId` is negative or not an integer |
| 404 | `ENTITY_NOT_FOUND` | No CRM item with this `entityTypeId` and `entityId` exists |
| 422 | `BITRIX_NO_EFFECT` | The payment was not created, for example because no payment system with this `paySystemId` exists. No new payment appears on the item |
| 422 | `BITRIX_ERROR` | CRM 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 |
| 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 missing |

Full list of common API errors: [Errors](/docs/errors).

## See also

- [Add a line item to a payment](/docs/entities/crm-payments/products-add)
- [Available product rows](/docs/entities/crm-payments/available-products)
- [List CRM payments](/docs/entities/crm-payments/list)
- [Mark a payment as paid](/docs/entities/crm-payments/pay)
- [Pay systems](/docs/entities/pay-systems)
- [CRM payments](/docs/entities/crm-payments)