Оплата c PCI DSS

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

В некоторых случаях для приема платежей необходимо передавать Банку цифровой отпечаток устройства пользователя. Свяжитесь с менеджером Банка, чтобы узнать, требуется ли это вам.

Чтобы автоматически получать цифровой отпечаток устройства пользователя и отправлять его в Банк, добавьте на страницу оплаты скрипт fp.js между тегами <head> и </head>, как показано в примере ниже. Если в процессе оплаты пользователь проходит несколько страниц, добавьте скрипт на каждую из них:

<script src="https://widget.bank131.ru/fp.js" async></script>

Пример:

<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <title>Пример подключения скрипта fp.js | Банк 131</title>

    <meta
      name="description"
      content="Примеры интеграции форм и элементов для Интернет-коммерции. Банк 131."
    />

    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta name="format-detection" content="telephone=no" />

    <!-- Подключение скрипта. -->
    <script src="https://widget-demo.bank131.ru/fp.js" async></script>
  </head>

  <body>
    <main>
      <header>
        <h1>Пример подключения скрипта fp.js</h1>
      </header>
    </main>
  </body>
</html>

Здесь описан платеж с холдированием: деньги сначала блокируются на карте, а потом списываются с нее. Этот шаг можно пропустить.

Этот платеж проходит с подтверждением: когда банк готов принять платеж, он присылает вам вебхук ready_to_capture и ждет ответа (см. шаги 4–5). Можно исключить этот шаг и проводить все платежи по другому сценарию — без подтверждения.

Шаг 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: 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. Начните платеж

Отправьте запрос на проведение платежа с помощью метода session/start/payment (этот метод подходит, если сессия уже была создана). В параметре session_id передайте идентификатор сессии, созданной на первом шаге. В поле payment_method.type передайте значение card. В объекте card передайте данные банковской карты пользователя.

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

cURL
PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/session/start \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
  -d '{
    "session_id": "3230",
    "payment_method": {
        "type": "card",
        "card": {
            "number": "4242424242424242",
            "expiration_month":"12",
            "expiration_year":"22",
            "security_code":"123",
            "cardholder_name":"John Doe"
        }
    },
    "customer": {
            "reference": "user123",
                "contacts": [
                    {
                        "email": "user@gmail.com"
                    }
                ]
        },
    "metadata": "good"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;

$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()
    ->startPaymentSession('session_id')
    ->setCard(
        new BankCard(
            '4242424242424242',
            '02',
            '22',
            '123',
            'cardholder name'
        )
    )
    ->setCustomer(new Customer('lucky'))
    ->setMetadata('good')
    ->build();

$response = $client->session()->startPayment($request);

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

Банк 131 отправит вам вебхук ready_to_confirm (на адрес для вебхуков, который вы заранее передали менеджеру Банка). Это значит, что платеж можно провести и Банк ждет вашего подтверждения (или отмены).

В теле вебхука придут все данные для платежа, их нужно проверить.

В ответ следует отдавать HTTP-код 200.

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

cURL

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
}

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

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

Пример запроса 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: 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
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: 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');

Шаг 5. Проведите пользователя через 3-D Secure

Если карта пользователя требует 3-D Secure, Банк 131 пришлет вам вебхук action_required с данными для редиректа. Перенаправьте пользователя на адрес, который придет в поле customer_interaction.redirect.url.

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

cURL

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -d '{
    "type": "action_required",
    "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": "131",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
                    "reference": "user123",
                    "contacts": [
                        {
                            "email": "user@gmail.com"
                        }
                    ]
                },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "8801"
          }
        },
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://bank131.ru?foo=bar",
            "base_url": "https://bank131.ru"
            "method": "POST",
            "qs": {
              "foo": "bar"
            },
            "params": {
              "paReq": "sdfew^//asdhbv",
              "MD": "abc75daefnn"
            }
          }
        }
      }]
    }
  }
}'

Пример обработки вебхука с помощью 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::ACTION_REQUIRED) {
    $session = $hook->getSession();
    //do your logic here
}

Шаг 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: 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
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: 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
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: 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. Узнайте результат оплаты

Дождитесь вебхука payment_finished или запросите статус платежа с помощью метода session/status.

Результат платежа приходит в поле payment.status.

Если статус succeeded, значит, оплата прошла успешно. Если статуc failed — оплата не прошла из-за ошибки.

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

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

Схема оплаты с PCI DSS (без платежной формы)

Схема платежа c PCI DSS

Пример:​

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

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

Шаг 2. Начните платеж​

Пример запроса​

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

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

Пример обработки вебхука с помощью SDK​

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

Пример запроса confirm_request​

Пример запроса cancel_request​

Шаг 5. Проведите пользователя через 3-D Secure​

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

Пример обработки вебхука с помощью SDK​

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

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

Пример обработки вебхука с помощью SDK​

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

Пример запроса capture_request​

Пример запроса cancel_request​

Шаг 8. Узнайте результат оплаты​

Схема оплаты с PCI DSS (без платежной формы)​

Пример:

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

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

Шаг 2. Начните платеж

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

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

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

Пример обработки вебхука с помощью SDK

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

Пример запроса confirm_request

Пример запроса cancel_request

Шаг 5. Проведите пользователя через 3-D Secure

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

Пример обработки вебхука с помощью SDK

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

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

Пример обработки вебхука с помощью SDK

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

Пример запроса capture_request

Пример запроса cancel_request

Шаг 8. Узнайте результат оплаты

Схема оплаты с PCI DSS (без платежной формы)