# ЮKassa: Принять оплату с переадресацией на ЮKassa

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

Покупатель платит на странице ЮKassa и возвращается на сайт. Подходит большинству интернет-магазинов.

1. Создай платеж: POST /payments с amount, capture: true, confirmation.type = redirect и confirmation.return_url. Передай заголовок Idempotence-Key — новый для каждой новой операции.
2. Сохрани id платежа в заказе и перенаправь покупателя по ссылке confirmation.confirmation_url из ответа.
3. Когда покупатель вернется на return_url, проверь статус на сервере: GET /payments/{payment_id}. Оплата прошла, если status = succeeded.
4. Если status = canceled, причина — в cancellation_details. Для повторной попытки создай новый платеж с новым ключом идемпотентности.

```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",
        "metadata": {"order_id": "72"}
      }'
```

## Базовые 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 /payments/{payment_id} — Информация о платеже

Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.

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

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `payment_id` | path | string | да | Идентификатор платежа. |

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

```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"
  }
}
```

## Нюансы

- 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://mcp-everything.ru/integrations/yookassa/scenarios/dvuhstadiynaya-oplata-zablokirovat.md)
- [Вернуть деньги покупателю](https://mcp-everything.ru/integrations/yookassa/scenarios/vernut-dengi-pokupatelyu.md)
- [Отправить чек по 54-ФЗ вместе с платежом](https://mcp-everything.ru/integrations/yookassa/scenarios/otpravit-chek-po-54-fz-vmeste.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