Оплата через платежную форму по шагам

Этот сценарий описывает отправку платежа на банковскую карту через платежную форму. Это вариант подходит, если вы не можете собирать данные банковских карт и хранить на своей стороне (у вас нет сертификата PCI DSS).

Вы можете получить токенизированные данные карты с помощью виджета платежной формы и безопасно провести оплату.

Описан платеж с холдированием денег на карте и последующим списанием.

Шаг 1. Создайте платежную сессию

Отправьте запрос на создание сессии session/create. В ответе придет идентификатор платежной сессии. В рамках одной сессии можно провести несколько действий: например, платеж и возврат.

Подробнее о сессиях

В заголовках запроса следует передать идентификатор вашего проекта и подпись запроса.

Подробнее о формате запросов

Пример запроса на создание сессии

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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
  -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 -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 '{
        "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

ccurl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "acquiring_payments": [
            {
                "id": "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

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 самостоятельно перенаправит пользователя на страницу для 3-D Secure (если карта пользователя этого требует).

Пример запроса 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": "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 -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": "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 -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -d '{
    "type": "ready_to_capture",
    "session": {
        "id": "3230",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "acquiring_payments": [
            {
                "id": "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

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 -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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
  -d '{
    "session_id": "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 -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": "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, значит, оплата прошла успешно. Если статуc failed — оплата не прошла из-за ошибки.

Подробнее о статусах платежа

Готово, платеж отправлен.

Схема оплаты через платежную форму

Схема платежа через платежную форму

← Сплит-платежи по APIОплата с PCI DSS →