ЮKassa: POST /payment_methods — Создание способа оплаты

Создает в ЮKassa объект способа оплаты. В запросе передайте код способа оплаты, который хотите сохранить, и при необходимости дополнительные параметры нужной функциональности. Идентификатор созданного способа оплаты можно использовать при проведении автоплатежей или выплат.

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

Параметр	Где	Тип	Обяз.	Описание
`Idempotence-Key`	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
`type`	body	string (bank_card, sbp)	да
`holder`	body	object	нет	Данные магазина, для которого сохраняется способ оплаты.
`holder.gateway_id`	body	string	нет	Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
`client_ip`	body	string	нет	IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-соединения.
`confirmation`	body	object	нет
`confirmation.type`	body	string (redirect, qr)	нет	Код сценария подтверждения пользователем привязки платежного средства к вашему магазину в ЮKassa.
`confirmation.enforce`	body	boolean	нет	Запрос на проведение привязки с аутентификацией по 3-D Secure. Сработает, если вы по умолчанию принимаете оплату банковской картой без подтверждения платежа пользователем; в остальных случаях аутентификацией по 3-D Secure управляет ЮKassa. Чтобы принимать платежи и создавать привязки без дополнительного подтверждения пользователем, напишите вашему менеджеру ЮKassa.
`confirmation.return_url`	body	string	нет	URL, на который вернется пользователь после подтверждения или отмены привязки на веб-странице. Не более 2048 символов.
`confirmation.locale`	body	string (ru_RU, en_US)	нет	Язык интерфейса, писем и смс, которые будут показаны или отправлены пользователю. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен.
`metadata`	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8.
`card`	body	object	нет	Данные банковской карты (необходимы, если вы собираете данные карты пользователей на своей стороне).
`card.number`	body	string	нет	Номер банковской карты.
`card.expiry_year`	body	string	нет	Срок действия, год, YYYY.
`card.expiry_month`	body	string	нет	Срок действия, месяц, MM.
`card.cardholder`	body	string	нет	Имя владельца карты.
`card.csc`	body	string	нет	Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне карты.

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

{
  "type": "bank_card"
}

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

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "bank_card",
  "saved": true,
  "status": "active",
  "holder": {
    "account_id": "123"
  }
}

Базовые 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_payment_method Вся интеграция одним документом: https://mcp-everything.ru/integrations/yookassa.md