# ЮKassa: Отправить чек по 54-ФЗ вместе с платежом

Сценарий из mcp-everything. Актуально на 2026-10-11.

Для компаний и ИП, которые используют Чеки от ЮKassa или стороннюю онлайн-кассу.

1. Добавь в POST /payments объект receipt: receipt.customer с контактом покупателя (для Чеков от ЮKassa — email) и receipt.items — список позиций.
2. Для каждой позиции обязательны description, quantity, amount и vat_code. Для Чеков от ЮKassa vat_code: 1 — без НДС, 2 — 0%, 3 — 10%, 11 — 22%.
3. Укажи payment_subject (commodity — товар, service — услуга) и payment_mode (full_payment — полный расчет, full_prepayment — полная предоплата). Для сторонних касс значения сверь с официальной документацией.
4. Проверь, что чек зарегистрирован: GET /receipts с payment_id платежа.

```bash
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {"value": "1000.00", "currency": "RUB"},
        "capture": true,
        "confirmation": {"type": "redirect", "return_url": "https://example.ru/orders/72"},
        "description": "Оплата заказа № 72",
        "receipt": {
          "customer": {"email": "user@example.ru"},
          "items": [
            {
              "description": "Кружка",
              "quantity": 1,
              "amount": {"value": "1000.00", "currency": "RUB"},
              "vat_code": 1,
              "payment_subject": "commodity",
              "payment_mode": "full_payment"
            }
          ]
        }
      }'
```

## Базовые 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 <Идентификатор магазина>:<Секретный ключ>
```

## Методы сценария

### POST /payments — Создание платежа

Чтобы принять платеж, нужно создать объект платежа — Payment. Он содержит всю необходимую информацию о платеже (сумму, валюту и статус). Платеж проходит линейный жизненный цикл, последовательно переходя из статуса в статус.

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

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Idempotence-Key` | header | string | да | Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7 |
| `amount` | body | object | да | Сумма платежа. Иногда партнеры ЮKassa берут с пользователя дополнительную комиссию, которая не входит в эту сумму. Сумма указывается вместе с кодом валюты. Валюта должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и с валютой аккаунта (shopId в личном кабинете), если не разделяете. |
| `amount.value` | body | string | да | Сумма в выбранной валюте, всегда в дробном формате. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00. |
| `amount.currency` | body | string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY) | да | Трехбуквенный код валюты в формате ISO-4217. Пример: RUB. |
| `description` | body | string | нет | Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru». |
| `receipt` | body | object | нет | Данные для формирования чека. Параметр передается, если вы компания или ИП и используете Чеки от ЮKassa, либо если вы компания или ИП, используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: «Платеж и чек одновременно» или «Сначала чек, потом платеж». |
| `receipt.customer` | body | object | нет | Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone). |
| `receipt.items` | body | object[] | нет | Список товаров в заказе. Если вы используете Чеки от ЮKassa, можно передать до 80 товаров, если стороннюю онлайн-кассу — до 100 товаров. |
| `receipt.internet` | body | boolean | нет | Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — платеж проведен онлайн, через интернет (например, на сайте или в приложении); false — платеж проведен офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true. Если вы принимаете платежи офлайн, передайте false. |
| `receipt.tax_system_code` | body | integer | нет | Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения; в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует. |
| `receipt.timezone` | body | integer | нет | Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс. |
| `receipt.receipt_industry_details` | body | object[] | нет | Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2. |
| `receipt.receipt_operational_details` | body | object | нет | Операционный реквизит чека (тег в 54 ФЗ — 1270). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2. |
| `recipient` | body | object | нет | Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта. |
| `recipient.gateway_id` | body | string | нет | Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта. |
| `payment_token` | body | string | нет | Одноразовый токен для проведения оплаты, сформированный с помощью Checkout.js или мобильного SDK. |
| `payment_method_id` | body | string | нет | Идентификатор сохраненного способа оплаты. |
| `payment_method_data` | body | object | нет |  |
| `payment_method_data.type` | body | string (bank_card, cash, sberbank, tinkoff_bank, yoo_money, mobile_balance, b2b_sberbank, sbp) | нет |  |
| `payment_method_data.card` | body | object | нет | Данные банковской карты (необходимы, если вы собираете данные карты пользователей на своей стороне). |
| `payment_method_data.phone` | body | string | нет | Телефон пользователя, на который придет смс с кодом платежа (для внесения наличных). Указывается в формате ITU-T E.164, например 79000000000. Поле можно оставить пустым: пользователь сможет заполнить его при оплате на стороне ЮKassa. |
| `payment_method_data.payment_purpose` | body | string | нет | Назначение платежа (не больше 210 символов). |
| `payment_method_data.vat_data` | body | object | нет |  |
| `payment_method_data.electronic_certificate` | body | object | нет | Данные от ФЭС НСПК для оплаты по электронному сертификату. Неоходимо передавать только при оплате со сбором данных на вашей стороне. |
| `payment_method_data.articles` | body | object[] | нет | Корзина покупки (в терминах НСПК) — список товаров, которые можно оплатить по сертификату. Необходимо передавать только при оплате на готовой странице ЮKassa. |
| `confirmation` | body | object | нет | Данные, необходимые для инициирования выбранного сценария подтверждения платежа пользователем. |
| `confirmation.type` | body | string (redirect, external, qr, embedded, mobile_application) | нет | Код сценария подтверждения платежа пользователем. Возможные значения: redirect — перенаправление пользователя на готовую страницу ЮKassa или страницу партнера; external — ожидание, что пользователь самостоятельно подтвердит платеж; qr — формирование QR-кода и его отображение на странице оплаты, чтобы пользователь подтвердил платеж; embedded — отображение платежного виджета ЮKassa; mobile_application — перенаправление пользователя в платежное приложение партнера. |
| `confirmation.locale` | body | string (ru_RU, en_US) | нет | Язык интерфейса, писем и сообщений, которые будет видеть или получать пользователь. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен. |
| `confirmation.enforce` | body | boolean | нет | Запрос на проведение платежа с аутентификацией по 3-D Secure. Сработает, если вы по умолчанию принимаете оплату банковской картой без подтверждения платежа пользователем; в остальных случаях аутентификацией по 3-D Secure управляет ЮKassa. Чтобы принимать платежи без дополнительного подтверждения пользователем, напишите вашему менеджеру ЮKassa. |
| `confirmation.return_url` | body | string | нет | URL, на который вернется пользователь после подтверждения или отмены платежа на веб-странице. Не более 2048 символов. |
| `save_payment_method` | body | boolean | нет | Сохранение платежных данных для проведения автоплатежей. Возможные значения: * true — сохранить способ оплаты (сохранить платежные данные); * false — провести платеж без сохранения способа оплаты. Доступно только после согласования с менеджером ЮKassa. |
| `capture` | body | boolean | нет | Автоматический прием поступившего платежа. Возможные значения: * true — оплата списывается сразу (платеж в одну стадию); * false — оплата холдируется и списывается по вашему запросу (платеж в две стадии: https://yookassa.ru/developers/payment-acceptance/getting-started/payment-process#capture-and-cancel). По умолчанию false. |
| `client_ip` | body | string | нет | IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-подключения. |
| `metadata` | body | object | нет | Любые дополнительные данные, которые нужны вам для работы (например, внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе ЮKassa. Ограничения: не более 16 ключей, название ключа — не больше 32 символов, значение ключа — не больше 512 символов, тип данных — строка в формате UTF-8. |
| `airline` | body | object | нет | Объект с данными для продажи авиабилетов. Используется только для платежей банковской картой. |
| `airline.ticket_number` | body | string | нет | Уникальный номер билета. Если номер билета известен при создании платежа, ticket_number — обязательный параметр; если неизвестен, передайте booking_reference вместо ticket_number. |
| `airline.booking_reference` | body | string | нет | Номер бронирования. Обязателен, если не указан ticket_number. |
| `airline.passengers` | body | object[] | нет | Список пассажиров. |
| `airline.legs` | body | object[] | нет | Список перелетов. |
| `transfers` | body | object[] | нет | Данные о распределении денег: суммы переводов и магазины, в пользу которых они совершаются. Передаются, если вы используете Сплитование платежей. |
| `deal` | body | object | нет | Сделка, в рамках которой проводится платеж. Передается, если вы используете Безопасную сделку. |
| `deal.id` | body | string | нет | Идентификатор сделки. |
| `deal.settlements` | body | object[] | нет | Данные о распределении денег. |
| `merchant_customer_id` | body | string | нет | Идентификатор покупателя в вашей системе, например адрес электронной почты или номер телефона. Не более 200 символов. Передается, если вы хотите сохранить банковскую карту и предложить ее для автоплатежей в платежном виджете ЮKassa. |
| `payment_order` | body | object | нет | Платежное поручение — распоряжение банку на перевод для оплаты жилищно-коммунальных услуг (ЖКУ), сведения о платеже для регистрации в ГИС ЖКХ. Нужно передавать при оплате ЖКУ. Кроме обязательных параметров, должен быть передан хотя бы один из параметров: payment_document_id, payment_document_number, account_number, unified_account_number или service_id. |
| `receiver` | body | object | нет |  |
| `receiver.type` | body | string (mobile_balance, digital_wallet, bank_account) | нет | Код получателя платежа. |
| `receiver.phone` | body | string | нет | Номер телефона для пополнения. Максимум 15 символов. Указывается в формате ITU-T E.164. Пример: 79000000000. |
| `receiver.account_number` | body | string | нет | Идентификатор электронного кошелька для пополнения. Максимум 20 символов. |
| `receiver.bic` | body | string | нет | Банковский идентификационный код (БИК) банка, в котором открыт счет. Формат — 9 символов. |
| `statements` | body | object[] | нет | Данные для отправки выписок; обязательны, если пользователь должен получить выписку после платежа. Сейчас доступен один тип — выписка об оплате: информация об успешном платеже, которую ЮKassa отправляет на электронную почту пользователя. Отправляется, если платеж проведен банковской картой, через SberPay или СБП; доступна для всех сценариев интеграции. |
| `pos_link` | body | object | нет | Данные о кассовой ссылке для проведения платежа в офлайне. |
| `pos_link.id` | body | string | нет | Идентификатор кассовой ссылки в ЮKassa. |
| `pos_link.expires_at` | body | string | нет | Срок действия оплаты. Может составлять от 1 до 20 минут с момента создания платежа, по умолчанию 20 минут. Указывается по UTC и передается в формате ISO 8601. Пример: 2024-10-18T10:51:18.139Z |

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

```
{
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "capture": true,
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.ru/return"
  },
  "description": "Оплата заказа № 72"
}
```

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

```json
{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}
```

### GET /receipts — Список чеков

Запрос позволяет получить список чеков, отфильтрованный по заданным критериям. Можно запросить чеки по конкретному платежу, чеки по конкретному возврату или все чеки магазина.

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

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `created_at.gte` | query | string | нет | Фильтр по времени создания: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z |
| `created_at.gt` | query | string | нет | Фильтр по времени создания: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z |
| `created_at.lte` | query | string | нет | Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («до такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z |
| `created_at.lt` | query | string | нет | Фильтр по времени создания: время должно быть меньше указанного значения («до такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z |
| `status` | query | string (pending, succeeded, canceled) | нет | Фильтр по статусу чека. Возможные значения: pending — в обработке, succeeded — успешно зарегистрирован, canceled — отменен. Пример: status=succeeded |
| `payment_id` | query | string | нет | Фильтр по идентификатору платежа (получить все чеки для указанного платежа). Пример: payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9 В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата. |
| `refund_id` | query | string | нет | Фильтр по идентификатору возврата (получить все чеки для указанного возврата). Пример: refund_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9 В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата. |
| `limit` | query | integer | нет | Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10 |
| `cursor` | query | string | нет | Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor необходимо использовать значение параметра next_cursor, полученное в ответе на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут. |

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

```json
{
  "type": "list",
  "items": [
    {
      "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "type": "payment",
      "status": "succeeded",
      "items": [
        {
          "description": null,
          "quantity": null,
          "amount": null,
          "vat_code": null
        }
      ]
    }
  ]
}
```

## Нюансы

- 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 частичная предоплата, аванс и кредит не поддерживаются.

## Другие сценарии

- [Принять оплату с переадресацией на ЮKassa](https://mcp-everything.ru/integrations/yookassa/scenarios/prinyat-oplatu-s-pereadresatsiey.md)
- [Двухстадийная оплата: заблокировать и списать](https://mcp-everything.ru/integrations/yookassa/scenarios/dvuhstadiynaya-oplata-zablokirovat.md)
- [Вернуть деньги покупателю](https://mcp-everything.ru/integrations/yookassa/scenarios/vernut-dengi-pokupatelyu.md)
- [Автоплатежи: сохранить способ оплаты и списывать без покупателя](https://mcp-everything.ru/integrations/yookassa/scenarios/avtoplatezhi-sohranit-sposob-oplaty.md)
- [Узнавать об оплате через HTTP-уведомления](https://mcp-everything.ru/integrations/yookassa/scenarios/uznavat-ob-oplate-cherez-http.md)
- [Выгрузить платежи за период](https://mcp-everything.ru/integrations/yookassa/scenarios/vygruzit-platezhi-za-period.md)

---

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