Оплата через платежную форму по шагам
Этот сценарий описывает отправку платежа на банковскую карту через платежную форму. Это вариант подходит, если вы не можете собирать данные банковских карт и хранить на своей стороне (у вас нет сертификата PCI DSS).
Вы можете получить токенизированные данные карты с помощью виджета платежной формы и безопасно провести оплату.
Описан платеж с холдированием денег на карте и последующим списанием.
Шаг 1. Создайте платежную сессию
Отправьте запрос на создание сессии session/create
. В ответе придет
идентификатор платежной сессии.
Пример запроса на создание сессии
- cURL
- PHP
curl -X POST \
https://demo.bank131.ru/api/v1/session/create \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "order123"
}'
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()
->createPaymentSession()
->setAmount(10000, 'rub')
->setMetadata('order123')
->build();
$response = $client->session()->create($request);
Шаг 2. Сгенерируйте публичный токен
Токен нужен для работы с виджетом. Отправьте запрос на создание токена token
,
передайте в нем идентификатор сессии и тип виджета, который будете вызывать.
В ответе придет токен.
Если хотите добавить в платежную форму чекбокс Соглашаюсь на автоплатежи, передайте в поле
show_recurrent_checkbox
значениеtrue
. Это нужно, чтобы проводить рекуррентные списания.
Пример запроса
- cURL
- PHP
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: signature' \
-d '{
"acquiring_widget": {
"session_id": "ps_123456"
}
}'
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()
->setAcquiringWidget(
'test_ps_id',
'http://success.url',
'http://failed.url',
false
)
->build();
$publicTokenResponse = $client->widget()->issuePublicToken($request);
$publicToken = $publicTokenResponse->getPublicToken();
Шаг 3. Покажите получателю платежную форму
Для этого нужно подключить нашу JavaScript-библиотеку и добавить виджет платежной формы. Покупатель вводит данные своей карты и нажимает Оплатить, и Банк 131 инициирует платеж без вашего участия.
Шаг 4. Дождитесь уведомления о готовности провести платеж
Банк 131 отправит вам вебхук ready_to_confirm
(на адрес
для вебхуков, который вы заранее передали менеджеру Банка). Это значит,
что платеж можно провести и Банк ждет вашего подтверждения (или отмены).
В теле вебхука придут все данные для платежа, их нужно проверить.
В ответ следует отдавать HTTP-код 200.
Пример вебхука ready_to_confirm
- cURL
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "pm_2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "good"
}
]
}
}'
Пример обработки вебхука с помощью SDK
- PHP
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::READY_TO_CONFIRM) {
$session = $hook->getSession();
//do your logic here
}
Шаг 5. Подтвердите или отмените оплату
Проверьте данные для платежа и подтвердите, что готовы его провести (с помощью
запроса confirm_request
) или отмените (отправьте запрос cancel_request
).
Если вы подтверждаете оплату, Банк 131 самостоятельно перенаправит пользователя на страницу для 3D Secure (если карта пользователя этого требует).
Пример запроса confirm_request
- cURL
- PHP
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: signature' \
-d '{
"session_id": "ps_3230"
}'
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);
$response = $client->session()->confirm('session_id');
Пример запроса cancel_request
- cURL
- PHP
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: signature' \
-d '{
"session_id": "ps_3230"
}'
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);
$response = $client->session()->cancel('session_id');
Шаг 6. Дождитесь вебхука ready_to_capture
Банк 131 сообщает вам с помощью вебхука ready_to_capture
, что сумма платежа
успешно заморожена на банковской карте пользователя.
Пример вебхука ready_to_capture
- cURL
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
"type": "ready_to_capture",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "pm_2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "good"
}
]
}
}'
Пример обработки вебхука с помощью SDK
- PHP
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::READY_TO_CAPTURE) {
$session = $hook->getSession();
//do your logic here
}
Шаг 7. Проведите списание или отмените
Спишите захолдированную сумму (capture_request
) или отмените холдирование
(cancel_request
).
Пример запроса capture_request
- cURL
- PHP
curl -X POST \
https://demo.bank131.ru/api/v1/session/capture \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
"session_id": "ps_3230"
}'
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);
$response = $client->session()->capture('session_id');
Пример запроса cancel_request
- cURL
- PHP
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: signature' \
-d '{
"session_id": "ps_3230"
}'
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);
$response = $client->session()->cancel('session_id');
Шаг 8. Дождитесь уведомления об успешной оплате
Банк 131 отправит вам вебхук payment_finished
.
В теле вебхука придут все данные, с которыми проводился платеж. Результат
платежа приходит в поле payment.status
.
Если статус succeeded
, значит, оплата прошла успешно.
Если статус failed
— оплата не прошла из-за ошибки.
Готово, платеж отправлен.