Сценарии выплат
Какие бывают сценарии
Выплаты по API могут проходить с использованием токена или без него.
Выбор сценария зависит от способа получения выплаты, и от того, есть ли у вас сертификат безопасности PCI DSS.
Выплата на банковскую карту без PCI DSS
В этом случае вы не можете хранить и отправлять данные банковской карты получателя в открытом виде, поэтому выплату можно провести только по токену — с помощью виджета токенизации.
Виджет позволяет получить данные карты пользователя и передать в запросе в безопасном токенизированном виде.
Как провести выплату на банковскую карту с виджетом
Чтобы показать пользователю, на какую банковскую карту придут выплаты, используйте метод
token/info
. Он позволяет получить последние 4 цифры номера карты по её токену.
Выплата на банковскую карту с PCI DSS, на банковский счет, через СБП, в кошелек QIWI или ЮMoney (Yandex.Money)
Токен использовать не нужно, все параметры для выплаты можно передать в открытом виде.
Платежная сессия
В рамках платежной сессии PaymentSession
проходят все операции в API — выплаты,
платежи, возвраты. Вы можете отправлять выплаты двумя способами:
- с одновременным стартом сессии и выплаты (одним запросом
session/init/payout
); - или сначала создать сессию, а потом отправить выплату (двумя запросами:
session/create
иsession/start/payout
). Например, чтобы сразу получить идентификатор сессии и следить по нему за тем, что происходит с выплатой.
Основной сценарий выплат
Эти шаги нужны только для выплаты по токену
- Вы отправляете запрос на создание токена для доступа к JavaScript-библиотеке.
- Создаете виджет с этим токеном, показываете пользователю и получаете данные карты в токенизированном виде.
Токенизированные данные карты можно сохранить, чтобы потом отправлять деньги на эту карту.
- Отправляете выплату любым способом:
- сначала отправляете запрос на создание платежной сессии
session/create
, затем — на создание выплаты с идентификатором этой сессии (session/start/payout
) - или создаете сессию одновременно с выплатой (
session/init/payout
).
В запросе на выплату передаете способ получения и все параметры, обязательные для этого способа.
- Убеждаетесь, что Банк 131 готов провести выплату и ждет вашего подтверждения. Есть два варианта:
- получить от Банка 131 вебхук
ready_to_confirm
- или отправлять запрос
session/status
и дождаться, когда в полеsession.next_action
вернется значениеconfirm
.
- Подтверждаете проведение выплаты (
confirm_request
) или отменяете её (cancel_request
). - Получаете от Банка 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
с идентификатором сессии, в которую входит эта выплата. Можно выбрать любой вариант
или комбинировать как удобно.
Возможные статусы выплаты:
in_progress
— в обработке,pending
— ожидает вашего подтверждения (confirm_request
) или отмены (cancel_request
),succeeded
— выплата прошла успешно,failed
— выплата прошла с ошибкой.