ЮKassa: Автоплатежи: сохранить способ оплаты и списывать без покупателя

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

Для подписок и повторных списаний. Сохранение способа оплаты доступно после согласования с менеджером ЮKassa.

  1. Создай первый платеж с save_payment_method: true: POST /payments. Покупатель подтверждает его как обычно.
  2. После успешной оплаты проверь в ответе GET /payments/{payment_id}, что payment_method.saved = true, и сохрани payment_method.id.
  3. Для следующих списаний создай платеж с payment_method_id = сохраненный id: POST /payments. Подтверждение покупателя не требуется.
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {"value": "2.00", "currency": "RUB"},
        "capture": true,
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
        "description": "Заказ №37"
      }'

Базовые URL

Авторизация

Тип: 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"
}

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

{
  "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 да Идентификатор платежа.

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

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

Нюансы

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

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