Сценарии выплат
Какие бывают сценарии
Выплаты по API могут проходить с использованием токена или без него.
Выбор сценария зависит от способа получения выплаты, и от того, есть ли у вас сертификат безопасности PCI DSS.
Выплата на банковскую карту без PCI DSS
В этом случае вы не можете хранить и отправлять данные банковской карты получателя в открытом виде, поэтому выплату можно провести только по токену — с помощью виджета токенизации.
Виджет позволяет получить данные карты пользователя и передать в запросе в безопасном токенизированном виде.
Как провести выплату на банковскую карту с виджетом
Чтобы показать пользователю, на какую банковскую карту придут выплаты, используйте метод
token/info
. Он позволяет получить последние 4 цифры номера карты по её токену.
Выплата на банковскую карту с PCI DSS, на банковский счет, через СБП, в кошелек ЮMoney (Yandex.Money)
Токен использовать не нужно, все параметры для выплаты можно передать в открытом виде.
Платежная сессия
В рамках платежной сессии session
проходят все операции в API — выплаты,
платежи, возвраты. Вы можете отправлять выплаты двумя способами:
- с одновременным стартом сессии и выплаты (одним запросом
session/init/payout
); - или сначала создать сессию, а потом отправить выплату (двумя запросами:
session/create
иsession/start/payout
). Например, чтобы сразу получить идентификатор сессии и следить по нему за тем, что происходит с выплатой.
Основной сценарий выплат
- С токеном
- Без токена
Отправьте запрос на создание токена для доступа к JavaScript-библиотеке.
Создайте виджет с этим токеном и покажите его пользователю для получения данных карты в токенизированном виде.
Сохраните токенизированные данные карты, чтобы потом отправлять деньги на эту карту.
Отправьте выплату любым способом:
- сначала отправьте запрос на создание платежной сессии
session/create
, затем — на создание выплаты с идентификатором этой сессии (session/start/payout
) - сразу создайте сессию одновременно с выплатой (
session/init/payout
).
В запросе на выплату передайте способ получения и все параметры, обязательные для этого способа.
- сначала отправьте запрос на создание платежной сессии
Дождитесь уведомления (
ready_to_confirm
) от Банка 131, что он готов провести выплату и ждет вашего подтверждения.Если у вас вебхуки отключены, отправьте запрос
session/status
и дождитесь, когда в полеsession.next_action
вернется значениеconfirm
.Подтвердите проведение выплаты (
session/confirm
) или отмените её (session/cancel
).Дождитесь от Банка 131 вебхука
payment_finished
со статусом выплаты. Статусsucceeded
означает, что выплата прошла успешно.
Отправьте выплату любым способом:
- сначала отправьте запрос на создание платежной сессии
session/create
, затем — на создание выплаты с идентификатором этой сессии (session/start/payout
) - сразу создайте сессию одновременно с выплатой (
session/init/payout
).
В запросе на выплату передайте способ получения и все параметры, обязательные для этого способа.
- сначала отправьте запрос на создание платежной сессии
Дождитесь уведомления (
ready_to_confirm
) от Банка 131, что он готов провести выплату и ждет вашего подтверждения.Если у вас вебхуки отключены, отправьте запрос
session/status
и дождитесь, когда в полеsession.next_action
вернется значениеconfirm
.Подтвердите проведение выплаты (
session/confirm
) или отмените её (session/cancel
).Дождитесь от Банка 131 вебхука
payment_finished
со статусом выплаты. Статусsucceeded
сообщает вам, что выплата прошла успешно.
Выплата на счет в российском банке может вернуться в течение 5 дней. Тогда вам придет вебхук
payment_refunded
. Подробнее о возврате выплаты
Сценарий выплаты самозанятому
Если проводите выплаты самозанятому, сценарий будет немного отличаться.
- Вы проверяете до старта выплаты (в самом начале), является ли человек самозанятым
и привязан ли он к Банку 131 (по ИНН, с помощью пары запросов
check
иrequest/status
). - Если ИНН самозанятый, но не привязан к Банку 131, тут же привязываете его с помощью специального виджета для привязки.
- Если всё в порядке, проводите выплату по общему сценарию. Вместе с выплатой отправляете
данные для фискализации:
session/init/payout/fiscalizaton
илиsession/start/payout/fiscalizaton
.
Подробнее о выплатах самозанятым
Выплата одним запросом
Для выплат на банковский счет или карту с PCI DSS есть упрощенный сценарий:
отправляете выплату запросом session/init/payout
и получаете результат из вебхука payment_finished
или с помощью метода session/status
.
Как провести выплату одним запросом
Выплата в иностранной валюте
Выплаты, инициированные в иностранной валюте, проводятся по такому сценарию:
- создаете запрос на создание платёжной сессии
session/create
, - создаете запрос на создание выплаты с идентификатором этой сессии
session/start/payout
, - ожидаете вебхук
ready_to_confirm
о готовности сделать выплату.
Подробнее о выплатах в иностранной валюте
Статусы выплаты
Статус выплаты возвращается в поле status
в объекте Payment
. Чтобы его узнать,
дождитесь вебхука от Банка 131 или отправьте запрос session/status
с идентификатором сессии, в которую входит эта выплата. Можно выбрать любой вариант
или комбинировать как удобно.