# Payments

Manage order payments: create, get, update, delete, search, aggregate. A payment is a separate entity linked to an order via the `orderId` field. A single order can have several payments (for example, a partial prepayment plus a balance payment on delivery), each with its own payment system and status.

Bitrix24 API: `sale.payment.*`
Scope: `sale`

## Operations

- [Create a payment](./payments/create.md) — `POST /v1/payments`
- [List payments](./payments/list.md) — `GET /v1/payments`
- [Get a payment](./payments/get.md) — `GET /v1/payments/:id`
- [Update a payment](./payments/update.md) — `PATCH /v1/payments/:id`
- [Delete a payment](./payments/delete.md) — `DELETE /v1/payments/:id`
- [Search payments](./payments/search.md) — `POST /v1/payments/search`
- [Payment fields](./payments/fields.md) — `GET /v1/payments/fields`
- [Aggregate payments](./payments/aggregate.md) — `POST /v1/payments/aggregate`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Payment identifier (read-only) |
| `accountNumber` | string | Sequential payment number within the Bitrix24 account (read-only) |
| `orderId` | number | Order identifier. Source: [`GET /v1/orders`](./orders/list.md) |
| `paySystemId` | number | Payment system identifier. Each Bitrix24 account has its own set of systems. You can find the ID from existing payments: `GET /v1/payments` or `POST /v1/payments/aggregate` with `groupBy: "paySystemId"` |
| `paySystemName` | string | Payment system name (read-only, comes from the payment system card) |
| `sum` | number | Payment amount |
| `currency` | string | Payment currency. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `paid` | boolean | Whether the payment is marked as received |
| `datePaid` | datetime | Payment marking date |
| `dateBill` | datetime | Invoice issue date |
| `responsibleId` | number | Responsible employee. Source: [`GET /v1/users`](/docs/entities/users) |
| `isReturn` | string | Return flag: `"N"` (regular payment), `"Y"` (return), `"P"` (partial return) |
| `comments` | string | Payment comment |
| `xmlId` | string | External identifier for synchronization |

Full list of fields — [Payment fields](./payments/fields.md).

## What to know before you start

1. **A payment is always linked to an order.** The `orderId` field is required on creation — you cannot create a payment without an existing order, first call [`POST /v1/orders`](./orders/create.md). A single order can have several payments registered (prepayment, balance on delivery) — each as a separate `POST /v1/payments`.
2. **The request body is flat.** On create and update, pass fields directly at the root of the JSON: `{"orderId": 19, "paySystemId": 11, ...}`. No `fields` wrapper is needed.
3. **The `isReturn` field is a string, not a boolean.** It accepts three values: `"N"` (regular payment), `"Y"` (return) and `"P"` (partial return) — filtering and updating work on these strings.
4. **The order total is not recalculated when a payment is created.** Registering a payment does not change the order status (`orders.payed`, `orders.statusId`) — update them with a separate [`PATCH /v1/orders/:id`](./orders/update.md) if you need to mark the order as paid.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Orders | [`GET /v1/orders/:id`](./orders/get.md) | Parent order — `orderId` is specified when creating a payment. |
| Basket items | [`GET /v1/basket-items?filter[orderId]=:id`](./basket-items/list.md) | Items in the same order. |
| Employees | [`GET /v1/users`](/docs/entities/users) | Source of `responsibleId`. |

## Typical scenario

Registering a payment from an external payment gateway:

1. Find the order: [`GET /v1/orders?filter[xmlId]=:externalOrderId`](./orders/list.md) — for example, by the order's external identifier.
2. Create the payment: [`POST /v1/payments`](./payments/create.md) with `orderId`, `paySystemId`, `sum`, `paid: true`, and the payment transaction's `xmlId`.
3. Update the order status after payment: [`PATCH /v1/orders/:id`](./orders/update.md) with `payed: true`, `statusId: "F"` (or another final status).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Payment fields](./payments/fields.md)
- [Orders](./orders.md)
- [Basket items](./basket-items.md)
- [Order statuses](./order-statuses.md)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Entity reference](/docs/entities-index)