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

Этот сценарий описывает отправку платежа на банковскую карту через платежную форму. Это вариант подходит, если вы не можете собирать данные банковских карт и хранить на своей стороне (у вас нет сертификата 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.

Пример вебхука

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

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. Подтвердите или отмените оплату

Проверьте данные для платежа и подтвердите, что готовы его провести (с помощью запроса session/confirm) или отмените (отправьте запрос session/cancel).

Если вы подтверждаете оплату, Банк 131 самостоятельно перенаправит пользователя на страницу для 3D Secure (если карта пользователя этого требует).

Пример запроса session/confirm

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');

Пример запроса session/cancel

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, что сумма платежа успешно заморожена на банковской карте пользователя.

Пример вебхука

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

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. Проведите списание или отмените

Спишите захолдированную сумму (session/capture) или отмените холдирование (session/cancel).

Пример запроса session/capture

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');

Пример запроса session/cancel

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 — оплата не прошла из-за ошибки.

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

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

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

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

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

Шаг 2. Сгенерируйте публичный токен​

Шаг 3. Покажите получателю платежную форму​

Шаг 4. Дождитесь уведомления о готовности провести платеж​

Шаг 5. Подтвердите или отмените оплату​

Шаг 6. Дождитесь вебхука ready_to_capture​

Шаг 7. Проведите списание или отмените​

Шаг 8. Дождитесь уведомления об успешной оплате​

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