# ЮKassa: POST /invoices — Создание счета

Создает в ЮKassa объект счета. В запросе передайте данные о заказе, которые отобразятся на странице счета, и данные для проведения платежа.

Документация: https://yookassa.ru/developers/api#create_invoice

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Idempotence-Key` | header | string | да | Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7 |
| `payment_data` | body | object | да | Данные для проведения платежа по выставленному счету. |
| `payment_data.amount` | body | object | да | Сумма платежа. Должна быть в пределах лимитов. Указывается вместе с кодом валюты. Должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, или с валютой аккаунта (shopId в личном кабинете), если не разделяете. |
| `payment_data.receipt` | body | object | нет | Данные для формирования чека. Параметр передается, если вы компания или индивидуальный предприниматель и используете Чеки от ЮKassa, либо используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж. |
| `payment_data.recipient` | body | object | нет | Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта. |
| `payment_data.save_payment_method` | body | boolean | нет | Сохранение платежных данных для проведения автоплатежей. Возможные значения: * true — сохранить способ оплаты (сохранить платежные данные); * false — провести платеж без сохранения способа оплаты. Доступно только после согласования с менеджером ЮKassa. |
| `payment_data.capture` | body | boolean | нет | Автоматический прием поступившего платежа. Возможные значения: * true — оплата списывается сразу (платеж в одну стадию); * false — оплата холдируется и списывается по вашему запросу (платеж в две стадии: https://yookassa.ru/developers/payment-acceptance/getting-started/payment-process#capture-and-cancel). По умолчанию false. |
| `payment_data.client_ip` | body | string | нет | IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-соединения. |
| `payment_data.description` | body | string | нет | Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru». |
| `payment_data.metadata` | body | object | нет | Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8. |
| `cart` | body | object[] | да | Корзина заказа — список товаров или услуг, который отобразится на странице счета перед оплатой. |
| `delivery_method_data` | body | object | нет |  |
| `delivery_method_data.type` | body | string (self, sms, email) | нет | Код способа доставки счета. |
| `delivery_method_data.phone` | body | string | нет | Номер телефона, на который ЮKassa отправит смс со ссылкой на счет. Указывается в формате ITU-T E.164, например 79000000000. |
| `delivery_method_data.email` | body | string | нет | Адрес электронной почты, на который ЮKassa отправит письмо со ссылкой на счет. |
| `expires_at` | body | string | да | Срок действия счета — дата и время, до которых можно оплатить выставленный счет. Указывается по UTC и передается в формате ISO 8601. Пример: 2024-10-18T10:51:18.139Z |
| `locale` | body | string (ru_RU, en_US) | нет | Язык интерфейса, писем и смс, которые будут показаны или отправлены пользователю. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен. |
| `description` | body | string | нет | Описание выставленного счета (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь на странице счета. Например: «Счет на оплату по договору 37». |
| `metadata` | body | object | нет | Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8. |

Пример запроса:

```
{
  "payment_data": {
    "amount": {
      "value": "1000.00",
      "currency": "RUB"
    }
  },
  "cart": [
    {
      "description": "string",
      "price": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "quantity": 1
    }
  ],
  "expires_at": "2024-10-18T10:51:18.139Z"
}
```

Пример ответа:

```json
{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "succeeded",
  "cart": [
    {
      "description": "string",
      "price": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "quantity": 1
    }
  ],
  "created_at": "2017-11-03T11:52:31.827Z"
}
```

## Базовые URL

- Основной: `https://api.yookassa.ru/v3`

## Авторизация

Тип: Basic Auth

HTTP Basic Auth: имя пользователя — идентификатор магазина (shopId, раздел Настройки — Магазин) или шлюза для выплат (agentId, раздел Настройки выплат), пароль — секретный ключ (раздел Интеграция — Ключи API). Для тестового магазина ключ выпускается автоматически. Участники партнерской программы используют OAuth 2.0 и передают Bearer-токен. Секретный ключ и OAuth-токен нельзя публиковать.

```
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>
```

## Нюансы

- capture по умолчанию false: без capture: true платеж останется в статусе waiting_for_capture и в момент expires_at отменится автоматически, деньги вернутся покупателю.
- Для POST и DELETE обязателен заголовок Idempotence-Key — до 64 символов, рекомендуется UUID. Повтор с тем же ключом в течение 24 часов вернет результат первого запроса; для новой операции нужен новый ключ.
- HTTP 500 не значит, что операция не прошла: результат неизвестен. Повтори запрос с теми же данными и тем же ключом идемпотентности или запроси объект через GET.
- Возврат покупателя на return_url не означает успешную оплату — статус проверяй на сервере или по HTTP-уведомлению.
- Сумма — строка с точкой и двумя знаками: "1000.00", вместе с кодом валюты.
- Методы /webhooks работают только с OAuth-токеном в партнерской программе. Обычный магазин настраивает уведомления в личном кабинете.
- Вернуть платеж можно в течение трех лет с момента создания. Комиссия ЮKassa за платеж не возвращается.
- Для Чеков от ЮKassa частичная предоплата, аванс и кредит не поддерживаются.

---

Если этого недостаточно — официальная документация: https://yookassa.ru/developers/api#create_invoice
Вся интеграция одним документом: https://mcp-everything.ru/integrations/yookassa.md