Платеж банковской картой

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

Если вы приняли решение не собирать и не хранить данные банковских карт на своей стороне, принимайте платежи через нашу платежную форму.

Данный сценарий не учитывает шаг с холдированием платежа. Как провести платеж с холдированием

1. Создайте платежную сессию (session/create). В ответе придет идентификатор платежной сессии.

   Также вы можете использовать метод session/init/payment.В этом случае сразу передайте все параметры платежа и пропустите следующий шаг.

   Пример

   cURL

   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"
     }'

   PHP

   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 передайте идентификатор сессии, созданной на первом шаге.
   • В поле type объекта payment_details передайте значение card.
   • В объекте bank_card передайте данные банковской карты пользователя.
   Пример

   cURL

   curl -X POST \
     https://demo.bank131.ru/api/v1/session/start/payment \
     -H 'Content-Type: application/json' \
     -H 'X-PARTNER-PROJECT: your_project_name' \
     -H 'X-PARTNER-SIGN: signature' \
     -d '{
       "session_id": "ps_3230",
       "payment_details": {
         "type": "card",
         "card": {
           "type": "bank_card",
           "bank_card": {
             "number": "4242424242424242",
             "expiration_month": "01",
             "expiration_year": "26",
             "security_code": "123"
           }
         }
       },
       "customer": {
         "reference": "user123",
         "contacts": [{
           "email": "user@gmail.com"
         }]
       },
       "metadata": "good"
     }'

   PHP

   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.

   Пример

   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"
         }]
       }
     }'

   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
   }

4. Подтвердите (session/confirm) или отмените (session/cancel) оплату.

   Пример подтверждения

   cURL

   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"
     }'

   PHP

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

   Пример отмены платежа

   cURL

   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"
     }'

   PHP

   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. Если вы получили вебхук action_required с данными для редиректа в поле customer_interaction.redirect.url, это значит, что для проведения платежа пользователю нужно пройти 3D Secure. Перенаправьте пользователя по ссылке.

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

   cURL

   curl -X POST \
     https://partner.ru \
     -H 'Content-Type: application/json' \
     -H 'X-PARTNER-SIGN: signature' \
     -d '{
       "type": "action_required",
       "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_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

   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::ACTION_REQUIRED) {
       $session = $hook->getSession();
       //do your logic here
   }

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

   Результат платежа приходит в поле status массива acquiring_payments/payment_list.

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

   Какие бывают статусы платежа >

Схема платежа картой без платежной формы