Выплата с номинального счета
Вы можете отправлять выплаты с номинального счета:
Выплата на банковскую карту
Этот сценарий описывает отправку выплаты на банковскую карту c номинального счета. Выплата будет произведена в два списания, одно на сумму платежа, другое на комиссию. Эти списания будут отражены в банковской выписке в ДБО.
Вы можете получить токенизированные данные карты с помощью виджета для токенизации и безопасно провести выплату.
Шаг 1. Сгенерируйте публичный токен
Токен нужен для работы с виджетом. Отправьте запрос на создание токена token
,
передайте в нем тип виджета, с которым хотите работать. В ответе придет токен.
Пример запроса
curl -X POST \
http://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"tokenize_widget": {
"access": true
}
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem')
);
$client = new Client($config);
$request = RequestBuilderFactory::create()
->issuePublicTokenBuilder()
->setTokenizeWidget()
->build();
$response = $client->widget()->issuePublicToken($request);
$publicToken = $response->getPublicToken();
Шаг 2. Покажите получателю форму для сбора данных карты
Для этого нужно подключить нашу JavaScript-библиотеку и добавить виджет для токенизации на страницу, где получатель сможет заполнить форму с данными своей карты.
Получатель введет данные карты, а вы получите токенизированные данные, с которыми можно проводить выплату.
Инициализировать виджет можно с помощью токена, который вы получили на предыдущем шаге.
Шаг 3. Начните выплату
Отправьте запрос на создание платежной сессии session/multi/create/nominal
,
затем — на создание выплаты с идентификатором этой сессии session/multi/start/payment/nominal
.
В объекте EncryptedCard
передайте токенизированные данные банковской карты,
полученные из виджета.
Вы можете узнать информацию о токене или о карте с помощью метода
token/info
. В том числе — получить последние 4 цифры номера карты, чтобы показать пользователю, куда придет выплата.
При выплате с номинального счета параметр
beneficiary_id
является обязательным для любого типа карт.
Если вы отправляете деньги на карту российского банка, вам понадобятся:
- номер карты;
- имя получателя;
- и сумма в копейках (если платите 100 рублей, в поле
amount_details.amount
нужно передать10000
).
Посмотреть параметры для выплаты на российские карты
Как заполнять данные бенефициара
Для выплат с номинального счета необходимо указывать данные бенефициара. В качестве данных бенефициара мы ожидаем получить ИНН бенефициара. Данные бенефициара указываются в объекте participant_details
, в списке данных отправителя sender
или данных получателя recipient
.
Если ваш бенефициар является отправителем - укажите его ИНН в блок sender
, если он является получателем, то укажите в блоке recipient
. До старта выплат вам необходимо передать список данных ваших бенефициаров вашему менеджеру.
Примеры запросов
Создание сессии
curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d {
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_nominal_account",
"transfer_from_nominal_account": {
"description": "Назначение платежа"
}
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "****************"
}
}
},
"participant_details": {
"sender": {
"full_name": "Данные отправителя",
"beneficiary_id": "1234567890"
},
"recipient": {
"full_name": "Иванов Иван Иванович"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"customer": {
"reference": "123456789012"
}
}
Старт выплаты
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
-d '{
"session_id": "3230",
"metadata": "good"
}'
Шаг 4. Дождитесь уведомления о готовности сделать выплату
Банк 131 отправит вам обязательный вебхук ready_to_confirm
(на адрес
для вебхуков, который вы заранее передали менеджеру Банка). Это значит,
что выплату можно провести, и Банк ждет вашего подтверждения (или отмены).
В теле вебхука придут все данные для выплаты. Вам необходимо сохранить объект confirm_information
— он понадобится для подтверждения выплаты.
В ответ следует отдавать HTTP-код 200.
Пример вебхука ready_to_confirm
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_14667043",
"status": "in_progress",
"created_at": "2022-09-14T09:32:19.891392Z",
"updated_at": "2022-09-14T09:32:20.494410Z",
"payments": [
{
"id": "po_7639847",
"status": "pending",
"created_at": "2022-09-14T09:32:20.100149Z",
"customer": {
"reference": "123456789012"
},
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"amounts": {
"net": {
"amount": 293400,
"currency": "RUB"
},
"gross": {
"amount": 293400,
"currency": "RUB"
}
},
"participant_details": {
"sender": {
"full_name": "ООО Название компании",
"beneficiary_id": "123456789"
},
"recipient": {
"full_name": "Иванов Иван Иванович"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_6933973",
"status": "pending",
"created_at": "2022-09-14T09:32:20.099952Z",
"customer": {
"reference": "123456789012"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_nominal_account",
"transfer_from_nominal_account": {
"description": "Перевод согласно оферты",
"card_mask": "553691******8371"
}
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"amounts": {
"net": {
"amount": 293400,
"currency": "RUB"
},
"gross": {
"amount": 293400,
"currency": "RUB"
}
},
"participant_details": {
"sender": {
"full_name": "ООО Название компании",
"beneficiary_id": "1234567890"
},
"recipient": {
"full_name": "Иванов Иван Иванович"
}
}
}
],
"next_action": "confirm"
},
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "ООО Название компании",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "ООО Банк 131",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Перевод согласно оферты",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
},
Шаг 5. Подтвердите или отмените выплату
Проверьте данные для выплаты и подтвердите, что готовы её провести (с помощью
запроса confirm_request
) или отмените (отправьте запрос cancel_request
).
Пример запроса confirm_request
curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "ps_14667043",
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "ООО Название компании",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "ООО Банк 131",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Перевод согласно оферты",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
}'
Пример запроса cancel_request
curl -X POST \
https://demo.bank131.ru/api/v1/session/cancel \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "ps_14667043",
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "ООО Название компании",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "ООО Банк 131",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Перевод согласно оферты",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
} '
Шаг 6. Дождитесь уведомления о результате выплаты
Банк 131 отправит вам обязательный вебхук payment_finished
. В теле вебхука придут все данные, с которыми
проводилась выплата. Результат выплаты приходит в поле payment.status
.
Если статус succeeded
, значит, выплата прошла успешно.
Если статуc failed
— выплата не прошла из-за ошибки.
Пример обработки вебхука с помощью SDK
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;
$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem'),
file_get_contents('/path/to/bank131/public_key.pem')
);
$client = new Client($config);
$hook = $client->handleWebHook('sign from headers', 'request body');
if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) {
$session = $hook->getSession();
//do your logic here
}
Выплата на банковский счет
Этот сценарий описывает отправку выплаты на банковский счет c номинального счета. Выплата будет произведена в два списания, одно на сумму платежа, другое на комиссию (если комиссия есть). Эти списания будут отражены в банковской выписке в ДБО. API позволяет отправлять выплаты самозанятым, ИП, физическим и юридическим лицам на счета в российских банках. Все параметры передаются в открытом виде.
На какие счета можно отправить
Вы можете отправить выплаты только на счета, которые начинаются с этих цифр:
- 40817810
- 42301810
- 42302810
- 42303810
- 42304810
- 42305810
- 42306810
- 42307810
- 40802810
- 40702810 (для счетов юридических лиц)
- 40701810
- 40502810
Если счет начинается с других цифр, выплата не пройдет.
Шаг 1. Начните выплату
Отправьте запрос на создание платежной сессии c одновременным стартом выплатыapi/v1/session/init/payout/nominal
.
Обязательные параметры для выплаты российских организаций
Название | Тип | Описание |
---|---|---|
payment_method | PaymentMethod | Платежные данные |
type | string | значение: bank_account |
bank_account | BankAccountPaymentMethod | Банковский счет |
system_type | string | Система банковских переводов. Всегда: ru |
ru | BankAccountRU | Объект банковского счета |
bik | string | БИК банка получателя |
account | string | Банковский счет получателя |
full_name | string | ФИО физического лица. В случае выплаты на счет ИП, передается в следующем формате: ИП <ФИО> . |
inn | string | ИНН. Необходимо указать при выплатах на счета юридического лица или ИП. |
kpp | string | КПП. Необходимо указать при выплатах на счета юридического лица или ИП. |
description | string | Назначение выплаты. Как сформировать |
participant_details | ParticipantDetails | Информация об участниках выплаты |
sender | Participant | Данные получателя |
account | string | Номер банковского номинального счета, с которого будет осуществляться выплата. |
beneficiary_id | string | ИНН бенефициара или выгодоприобретателя. Необходимо указать только при выплатах с номинального счета. |
recipient | Participant | Данные получателя |
beneficiary_id | string | ИНН бенефициара или выгодоприобретателя. Необходимо указать только при выплатах с номинального счета. |
amount_details | AmountDetails | Сумма |
amount | int | Сумма в копейках. Значение должно быть больше нуля. Если отправляете 100 рублей, нужно передать 10000 |
currency | string | Код валюты согласно ISO 4217. Регистр не важен. Всегда: rub |
Обязательные параметры для нерезидентов
Название | Тип | Описание |
---|---|---|
payment_method | PaymentMethod | Платежные данные |
type | string | значение: bank_account |
bank_account | BankAccountPaymentMethod | Банковский счет |
system_type | string | Система банковских переводов. Всегда: ru |
ru | BankAccountRU | Объект банковского счета |
bik | string | БИК банка получателя |
inn | string | ИНН получателя, 10 цифр для юридических лиц, 12 цифр - для физических. Необходимо указать при выплатах на счета юридических лиц. |
kpp | string | KПП получателя, 9 цифр. Необходимо указать при выплатах на счета юридических лиц. |
account | string | Банковский счет получателя |
full_name | string | ФИО физического лица. В случае выплаты на счет ИП, передается в следующем формате: ИП <ФИО> . При выплате юридическому лицу — наименование юрлица, если предусмотрено договором. Важно: если наименование или ФИО указано некорректно, банк-получатель может отказать в зачислении и деньги вернутся на счет отправителя. |
description | string | Назначение выплаты с кодом валютной операции (согласуется с менеджером в Банке 131). Как сформировать |
amount_details | AmountDetails | Сумма |
amount | int | Сумма в копейках. Значение должно быть больше нуля. Если отправляете 100 рублей, нужно передать 10000 |
currency | string | Код валюты согласно ISO 4217. Регистр не важен. Всегда: rub |
participant_details | ParticipantDetails | Информация об участниках выплаты |
sender | Participant | Данные отправителя |
full_name | string | Имя. Необходимо указать, если отправитель — физическое лицо. |
company_name | string | Название компании. Необходимо указать, если отправитель — юридическое лицо. |
address_line | string | Адрес. Важно: страну и город необходимо указать в следующих полях, в данном поле их дублировать не нужно. |
country_iso3 | string | Страна (ISO-3166-1 alpha-3) |
city | string | Город |
recipient | Participant | Данные получателя |
full_name | string | Имя получателя. |
Как заполнять данные бенефициара
Для выплат с номинального счета необходимо указывать данные бенефициара. В качестве данных бенефициара мы ожидаем получить ИНН бенефициара. Данные бенефициара указываются в объекте participant_details
, в списке данных отправителя sender или данных получателя recipient
.
Если ваш бенефициар является отправителем - укажите его инн в блок sender
, если он является получателем, то укажите в блоке recipient
. До старта выплат вам необходимо передать список данных ваших бенефициаров Вашему менеджеру.
Как формировать назначение выплаты
В назначении выплаты (поле BankAccountRU.description
) по российским законам
необходимо указывать:
- вид операции (например, оплата услуг);
- основание платежа (например, договор №);
- наименование работ, услуг, товаров;
- облагается НДС или нет.
Если ваша организация зарегистрирована не в России, необходимо добавить код вида валютной операции в следующем формате: {VO<код вида валютной операции>} без отступов и пробелов. Код необходимо согласовать заранее с менеджером в Банке 131.
Назначение выплаты не должно содержать следующие символы:
?
,!
. Максимальная длина: 210 символов.
Пример назначения выплаты
Перевод средств по договору № 5015553456 Иванов Иван Иванович НДС не облагается
Пример назначения выплаты для нерезидентов
{VO99090} Перевод средств по договору № 5015553456 Иванов Иван Иванович НДС не облагается
Пример запроса для выплаты на счет физического лица
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"payment_method": {
"type": "bank_account",
"bank_account": {
"ru": {
"bik": "044525974",
"account": "40817810400003869535",
"full_name": "Иванов Иван Иванович",
"description": "Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается"
},
"system_type": "ru"
}
},
"amount_details": {
"amount": 300,
"currency": "rub"
},
"participant_details": {
"sender": {
"account": "40702810300200000013"
},
"recipient":{
"beneficiary_id": "1234567890"
}
}
}'
Пример запроса для выплаты на счет юридического лица
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"payment_method": {
"type": "bank_account",
"bank_account": {
"ru": {
"bik": "044525974",
"account": "40702810500000000001",
"full_name": "ООО Наименование организации",
"inn": "1111111111",
"kpp": "156605101",
"description": "Перечисление денежных средств по договору за декабрь 2022 г. НДС не облагается."
},
"system_type": "ru"
}
},
"amount_details": {
"amount": 300,
"currency": "rub"
},
"participant_details": {
"sender": {
"account": "40702810300200000013"
},
"recipient":{
"beneficiary_id": "1234567890"
}
}
}'
Шаг 2. Дождитесь уведомления о готовности сделать выплату
Банк 131 отправит вам обязательный вебхук ready_to_confirm
(на адрес
для вебхуков, который вы заранее передали менеджеру Банка). Это значит,
что выплату можно провести, и Банк ждет вашего подтверждения (или отмены).
В теле вебхука придут все данные для выплаты. Вам необходимо сохранить объект confirm_information
— он понадобится для подтверждения выплаты.
В ответ следует отдавать HTTP-код 200.
Пример вебхука ready_to_confirm
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_260159",
"status": "in_progress",
"created_at": "2023-01-17T13:41:59.352487Z",
"updated_at": "2023-01-17T13:42:01.657512Z",
"payments": [
{
"id": "po_67428",
"status": "pending",
"created_at": "2023-01-17T13:41:59.594022Z",
"payment_method": {
"type": "bank_account",
"bank_account": {
"system_type": "ru",
"ru": {
"bik": "049205131",
"account": "40702810300000000006",
"full_name": "Наименование организации-получателя",
"description": "Перечисление денежных средств по договору № 1 НС от 01.09.2021 комиссия площадки за декабрь 2022 г. НДС не облагается.",
"is_fast": false
}
}
},
"amount_details": {
"amount": 2700,
"currency": "RUB"
},
"amounts": {
"net": {
"amount": 2700,
"currency": "RUB"
}
}
}
]
}
}
Шаг 3. Подтвердите или отмените выплату
Проверьте данные для выплаты и подтвердите, что готовы её провести (с помощью
запроса confirm_request
) или отмените (отправьте запрос cancel_request
. При подтверждении выплыты объект confirm_information является обязательным. Данный запрос является платежным поручением на перевод денежных средств.
Пример запроса confirm_request
curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "ps_1048967",
"confirm_information":{
"account_details": {
"sender": {
"account_number": "40702810300200000013",
"name": "Наименование мерчанта Банка 131",
"bank_name": "ООО \"Банк 131\"",
"bik": "049205131",
"correspondent_account_number": "30101810822029205131",
"inn": "3316004790",
"kpp": "156605101"
},
"recipient": {
"account_number": "40702810300000000006",
"name": "Наименование организации-получателя",
"bank_name": "ООО \"Банк 131\"",
"bik": "049205131",
"correspondent_account_number": "30101810822029205131"
}
}
}
}'
Пример запроса cancel_request
curl -X POST \
https://demo.bank131.ru/api/v1/session/cancel \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "ps_1048967",
"confirm_information":{
"account_details": {
"sender": {
"account_number": "40702810300200000013",
"name": "Наименование мерчанта Банка 131",
"bank_name": "ООО \"Банк 131\"",
"bik": "049205131",
"correspondent_account_number": "30101810822029205131",
"inn": "3316004790",
"kpp": "156605101"
},
"recipient": {
"account_number": "40702810300000000006",
"name": "Наименование организации-получателя",
"bank_name": "ООО \"Банк 131\"",
"bik": "049205131",
"correspondent_account_number": "30101810822029205131"
}
}
}
}'
Шаг 4. Дождитесь уведомления о результате выплаты
Банк 131 отправит вам обязательный вебхук payment_finished
. В теле вебхука придут все данные, с которыми
проводилась выплата. Результат выплаты приходит в поле payment.status
.
Если статус succeeded
, значит, выплата прошла успешно.
Если статуc failed
— выплата не прошла из-за ошибки.
Возврат выплаты
Выплата, которую вы отправили на счет в российском банке, может вернуться. В этом случае в течение 5 дней вам придет возврат.
Помните: вы можете воспользоваться функциональностью уведомления о пополнении номинального счета. Чтобы получать уведомление каждый раз, когда средства поступают на ваш номинальный счет в результате внутрибанковских или межбанковских операций, просто сообщите вашему менеджеру Банка адрес, на который вы хотите получать такие уведомления. Данный вебхук позволит вам оперативно получать информацию о пополнении и текущем балансе номинального счета без необходимости авторизации и мониторинга состояния счета в интернет-банке.