С помощью ЮKassa вы можете получить специальный токен банковской карты, который можно использовать одновременно для приема платежей и проведения выплат.
Универсальный токен — это сохраненный способ оплаты, который используется для автоплатежей.
Чтобы получить универсальный токен, вам нужно сохранить способ оплаты — привязать банковскую карту пользователя к вашему магазину. Для этого нужно провести успешный платеж. Идентификатором сохраненного способа оплаты станет идентификатор успешно проведенного платежа. Этот идентификатор и есть универсальный токен.
Чтобы сделать выплату, вам нужно передать идентификатор сохраненного способа оплаты в запросе на создание выплаты, а чтобы сделать платеж — передать идентификатор в запросе на создание платежа. Платежи с использованием идентификатора сохраненного способа оплаты будут безакцептными — пользователю не нужно будет подтверждать списание денег.
Сохранить способ оплаты можно двумя способами: сделать платеж на минимальную сумму, а затем отменить его, чтобы деньги вернулись пользователю, или сохранить способ оплаты во время оплаты товара или услуги.
Для платежа с сохранением способа оплаты можно использовать любой сценарий интеграции, если там есть оплата банковской картой. Рекомендуется выбрать те варианты интеграции, где есть только карта и нет других способов оплаты. Рекомендуемые варианты интеграции приведены в разделе Подготовка к интеграции этой статьи.
Сначала сохраните способ оплаты, затем используйте его при выплатах и платежах.
Общий сценарий сохранения способа оплаты
- Вы сообщаете пользователю, что сохраните данные его банковской карты и будете их использовать для платежей и выплат.
- Пользователь соглашается с условиями.
- Вы создаете платеж — отправляете ЮKassa POST-запрос с указанием, что нужно сохранить способ оплаты.
- ЮKassa возвращает вам созданный объект платежа в статусе
pending
и ссылку на страницу оплаты. - Вы перенаправляете пользователя на страницу оплаты.
- Пользователь вводит данные банковской карты.
- ЮKassa передает данные эквайеру.
- При необходимости эквайер просит пользователя пройти аутентификацию по 3-D Secure.
- Пользователь проходит проверку.
- Эквайер сообщает ЮKassa результаты проведения платежа.
- ЮKassa сообщает пользователю результаты проведения платежа.
- Пользователь возвращается на ваш сайт.
- Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
- ЮKassa возвращает вам созданный объект платежа в актуальном статусе —
waiting_for_capture
(деньги авторизованы и ожидают списания) илиcanceled
(платеж отменен). - Если объект в статусе
waiting_for_capture
, вы проверяете, что способ оплаты сохранен, и сохраняете идентификатор способа оплаты. - Вы отменяете платеж — отправляете ЮKassa POST-запрос с идентификатором платежа.
- ЮKassa возвращает вам объект платежа в статусе
canceled
. - Вы отображаете пользователю результат сохранения способа оплаты.
Общий сценарий проведения выплаты с использованием сохраненного способа оплаты
- Вы создаете выплату — отправляете ЮKassa POST-запрос с идентификатором сохраненного способа оплаты.
- ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
- Эквайер обрабатывает запрос и сообщает результат выполнения операции.
- ЮKassa возвращает вам объект выплаты с финальным статусом —
succeeded
(выплата успешна) илиcanceled
(выплата отменена).
Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе
pending
, это значит, что эквайер еще обрабатывает распоряжение на перевод. Чтобы узнать финальный статус, повторяйте запрос на проведение выплаты с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).Общий сценарий проведения платежа с использованием сохраненного способа оплаты
- Вы создаете платеж — отправляете ЮKassa POST-запрос с идентификатором сохраненного способа оплаты.
- ЮKassa отправляет эквайеру распоряжение на списание денег с банковской карты пользователя.
- Эквайер обрабатывает запрос и сообщает результат выполнения операции.
- ЮKassa возвращает вам объект платежа с финальным статусом —
succeeded
(платеж успешен) илиcanceled
(платеж отменен).
Если вы проводите платеж в две стадии, платеж вернется в статусе
waiting_for_capture
(деньги авторизованы и ожидают списания) или canceled
(платеж отменен). Если платеж в статусе waiting_for_capture
, для завершения платежа вам нужно списать оплату или отменить платеж.Для подключения сообщите менеджеру ЮKassa, что хотите принимать платежи и проводить выплаты с использованием универсального токена. Менеджер при необходимости создаст вам магазин или шлюз (если у вас их не было).
Формат взаимодействия для платежей и выплат одинаковый, отличие только в данных для аутентификации запросов: для приема платежей нужно использовать логин и секретный ключ магазина, а для проведения выплат — логин и секретный ключ шлюза.
Что нужно для приема платежей:
- Получить идентификатор магазина и секретный ключ.
- Согласовать с менеджером ЮKassa использование автоплатежей.
- Настроить уведомления.
- Выбрать сценарий интеграции. Рекомендуется использовать те варианты интеграции, где есть только банковская карта:
- Оплата банковской картой на готовой странице ЮKassa
- Виджет ЮKassa в виде отдельной формы для оплаты банковской картой (доступно только после согласования с менеджером)
- Checkout.js (нужно согласовать с менеджером)
- Оплата банковской картой в вашей платежной форме (нужен сертификат соответствия PCI DSS)
- Реализовать сохранение способа оплаты.
- Реализовать проведение автоплатежа (платеж с использованием сохраненного способа оплаты).
Вам нужно получить идентификатор шлюза и секретный ключ и реализовать проведение выплаты с использованием сохраненного способа оплаты. Дополнительно согласовывать ничего не надо.
Чтобы сохранить способ оплаты, нужно в запросе на создание платежа передать параметр
save_payment_method
со значением true
.Есть два варианта, как сохранить способ оплаты:
- Только сохранение способа оплаты — вы проводите платеж на минимальную сумму (чтобы убедиться, что карта действительна), а затем отменяете платеж.
- Платеж с сохранением способа оплаты — вы принимаете оплату за товар или услугу и в процессе сохраняете данные карты.
Шаг 1. Сообщите пользователю, что ему нужно привязать к вашему сервису свою банковскую карту. Подробно расскажите, что это значит и как это работает:
- Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
- Что нужно сделать для привязки: расскажите, что пользователю нужно сделать платеж на минимальную сумму. Для оплаты нужно использовать ту карту, которую он хочет привязать к вашему сервису. Деньги потом вернутся ему на счет.
- Как можно отказаться от использования карты для платежей и выплат.
Получите от пользователя согласие на привязку его карты для проведения выплат и безакцептных платежей.
Шаг 2. Когда пользователь перейдет к привязке банковской карты, начните проводить платеж с сохранением способа оплаты в соответствии с выбранным сценарием интеграции. В запросе на создание платежа дополнительно передайте параметр
save_payment_method
со значением true
, чтобы сохранить способ оплаты, и параметр capture
со значением false
, чтобы провести платеж в две стадии.Пример платежа банковской картой с сохранением способа оплаты
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1.00", "currency": "RUB" }, "payment_method_data": { "type": "bank_card" }, "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url" }, "capture": false, "save_payment_method": true, "description": "Оплата заказа №37", "metadata": { "order_id": "37" } }'
Шаг 3. Если платеж вернулся в статусе
pending
и с параметром confirmation_url
, перенаправьте пользователя на confirmation_url
для подтверждения платежа.Пример платежа в статусе pending
{ "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "status": "pending", "amount": { "value": "1.00", "currency": "RUB" }, "description": "Оплата заказа №37", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "payment_method": { "type": "bank_card", "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "saved": false }, "created_at": "2022-05-26T11:37:17.497Z", "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url", "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c" }, "test": false, "paid": false, "refundable": false, "metadata": { "order_id": "37" } }
Шаг 4. Дождитесь, когда пользователь подтвердит оплату и платеж перейдет в статус
waiting_for_capture
. Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .Шаг 5. Убедитесь, что оплата была банковской картой и способ оплаты сохранен: в объекте платежа параметр
payment_method.type
со значением bank_card
, а значение параметра payment_method.saved
изменилось на true
.Пример платежа в статусе waiting_for_capture
{ "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "status": "waiting_for_capture", "amount": { "value": "1.00", "currency": "RUB" }, "description": "Оплата заказа №37", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "payment_method": { "type": "bank_card", "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "saved": true, "title": "Bank card *4444", "card": { "first6": "555555", "last4": "4444", "expiry_year": "2030", "expiry_month": "12", "card_type": "MasterCard", "issuer_country": "RU" } }, "created_at": "2022-05-26T11:37:17.497Z", "expires_at": "2022-06-02T11:37:55.385Z", "test": false, "paid": true, "refundable": false, "metadata": { "order_id": "37" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } } }
Шаг 6. Сохраните идентификатор способа оплаты
payment_method.id
. Этот идентификатор и будет универсальным токеном. Его нужно будет использовать при проведении выплат и безакцептных платежей.Шаг 7. Отмените платеж .
Пример запроса на отмену платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ }'
Пример платежа в статусе canceled
{ "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "status": "canceled", "amount": { "value": "1.00", "currency": "RUB" }, "description": "Оплата заказа №37", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "payment_method": { "type": "bank_card", "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "saved": true, "title": "Bank card *4444", "card": { "first6": "555555", "last4": "4444", "expiry_year": "2030", "expiry_month": "12", "card_type": "MasterCard", "issuer_country": "RU" } }, "created_at": "2022-05-26T11:37:17.497Z", "test": false, "paid": false, "refundable": false, "metadata": { "order_id": "37" }, "cancellation_details": { "party": "merchant", "reason": "canceled_by_merchant" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } } }
Шаг 8. Сообщите пользователю результаты сохранения данных банковской карты.
Шаг 1. Сообщите пользователю, что при оплате сохраните данные его банковской карты. Подробно расскажите, что это значит и как это работает:
- Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
- Как можно отказаться от использования карты для платежей и выплат.
Получите от пользователя согласие на привязку его карты для проведения выплат и безакцептных платежей.
Шаг 2. Когда пользователь перейдет к оплате товара или услуги, начните проводить платеж с сохранением способа оплаты в соответствии с выбранным сценарием интеграции. В запросе на создание платежа дополнительно передайте параметр
save_payment_method
со значением true
.Пример платежа банковской картой с сохранением способа оплаты
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1.00", "currency": "RUB" }, "payment_method_data": { "type": "bank_card" }, "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url" }, "capture": false, "save_payment_method": true, "description": "Оплата заказа №37", "metadata": { "order_id": "37" } }'
Шаг 3. Если платеж вернулся в статусе
pending
и с параметром confirmation_url
, перенаправьте пользователя на confirmation_url
для подтверждения платежа.Пример платежа в статусе pending
{ "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "status": "pending", "amount": { "value": "1.00", "currency": "RUB" }, "description": "Оплата заказа №37", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "payment_method": { "type": "bank_card", "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "saved": false }, "created_at": "2022-05-26T11:37:17.497Z", "confirmation": { "type": "redirect", "return_url": "https://example.com/return_url", "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c" }, "test": false, "paid": false, "refundable": false, "metadata": { "order_id": "37" } }
Шаг 4. Дождитесь, когда пользователь подтвердит оплату и платеж перейдет в статус
succeeded
или waiting_for_capture
(если проводили платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .Шаг 5. Убедитесь, что оплата была банковской картой и способ оплаты сохранен: в объекте платежа параметр
payment_method.type
со значением bank_card
, а значение параметра payment_method.saved
изменилось на true
.Пример платежа в статусе waiting_for_capture
{ "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "status": "waiting_for_capture", "amount": { "value": "1.00", "currency": "RUB" }, "description": "Оплата заказа №37", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "payment_method": { "type": "bank_card", "id": "2a217a2d-000f-5000-9000-1bd6f124af9c", "saved": true, "title": "Bank card *4444", "card": { "first6": "555555", "last4": "4444", "expiry_year": "2030", "expiry_month": "12", "card_type": "MasterCard", "issuer_country": "RU" } }, "created_at": "2022-05-26T11:37:17.497Z", "expires_at": "2022-06-02T11:37:55.385Z", "test": false, "paid": true, "refundable": false, "metadata": { "order_id": "37" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } } }
Шаг 6. Сохраните идентификатор способа оплаты
payment_method.id
. Этот идентификатор и будет универсальным токеном. Его нужно будет использовать при проведении выплат и безакцептных платежей.Шаг 7. Если платеж проходит в две стадии, подтвердите или отмените платеж.
Шаг 8. Сообщите пользователю результаты платежа.
Создайте выплату
: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для выплаты на банковскую карту с использованием сохраненного способа оплаты:
- в объекте
amount
передайте сумму, которую нужно выплатить пользователю; сумма должна укладываться в лимиты; - в параметре
description
передайте описание выплаты; - в параметре
payment_method_id
передайте идентификатор сохраненного способа оплаты.
Пример запроса на создание выплаты
curl https://api.yookassa.ru/v3/payouts \ -X POST \ -u <Идентификатор шлюза>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "100.00", "currency": "RUB" }, "payment_method_id": "<Идентификатор сохраненного способа оплаты>", "description": "Выплата по заказу №1", "metadata": { "order_id": "37" } }'
В ответ на запрос ЮKassa вернет созданный объект выплаты .
Пример созданного объекта выплаты
{ "id": "po-285ec15d-0003-5000-a000-08d1bec7dade", "amount": { "value": "100.00", "currency": "RUB" }, "status": "pending", "payout_destination": { "type": "bank_card", "card": { "first6": "555555", "last4": "4477", "card_type": "MIR", "issuer_country": "RU", "issuer_name": "Sberbank Of Russia" } }, "description": "Выплата по заказу №37", "created_at": "2021-06-21T14:28:45.132Z", "metadata": { "order_id": "37" }, "test": false }
Если вы получили объект выплаты в статусе
pending
, дождитесь, когда статус изменится на succeeded
или canceled
. Для этого повторяйте запрос с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом.Пример запроса на получение информации о выплате
curl https://api.yookassa.ru/v3/payouts/{payout_id} \ -X GET \ -u <Идентификатор шлюза>:<Секретный ключ> \
Пример объекта выплаты в статусе succeeded
{ "id": "po-285ec15d-0003-5000-a000-08d1bec7dade", "amount": { "value": "100.00", "currency": "RUB" }, "status": "succeeded", "payout_destination": { "type": "bank_card", "card": { "first6": "555555", "last4": "4477", "card_type": "MIR", "issuer_country": "RU", "issuer_name": "Sberbank Of Russia" } }, "description": "Выплата по заказу №37", "created_at": "2021-06-21T14:28:45.132Z", "metadata": { "order_id": "37" }, "test": false }
Создайте платеж
: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для проведения платежа с использованием сохраненного способа оплаты:
- в объекте
amount
передайте сумму, которую нужно списать с карты пользователя; - в параметре
description
передайте описание платежа; - в параметре
payment_method_id
передайте идентификатор сохраненного способа оплаты; - в параметре
capture
передайте значениеtrue
, если хотите провести платеж в одну стадию и сразу списать деньги, и значениеfalse
, если хотите провести платеж в две стадии и списать деньги потом.
Пример запроса на создание платежа
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": "Заказ №105" }'
В ответ на запрос ЮKassa вернет созданный объект платежа .
При успешной оплате в объекте
payment_method
будет отображаться информация о платежных данных сохраненного способа, который вы использовали при платеже.Пример платежа в статусе succeeded
{ "id": "255350c9-000f-5000-a000-1f211b3ea0a7", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2018-07-18T17:20:50.825Z", "created_at": "2018-07-18T17:18:39.345Z", "description": "Заказ №72", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22e18a2f-000f-5000-a000-1db6312b7767", "saved": true, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "MasterCard", "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "test": false }
Если проводите платеж в две стадии, подтвердите или отмените платеж.
Выплаты на банковские картыВыплаты самозанятымТестирование выплатНеуспешные выплатыКоды ответа (состояния) HTTP