Перейти к основному содержимому

Выплата на банковскую карту по токену

Данный способ доступен, если:

  • У вас уже есть токенизированный номер карты.

  • Вы принимаете платежи и создаете рекурренты.
    В таком случае вы можете использовать токены для совершения выплат.

  • Вы приняли решение не хранить карточные данные, для которых необходимо выполнять дополнительные требования стандарта PCI DSS.
    Для использования этого метода обратитесь к вашему менеджеру в Банке 131.

Обратите внимание:

  • Возможность выплаты не зависит от проекта (X-PARTNER-PROJECT в header запроса), на котором был получен токен.
  • Вы можете проводить выплаты с использованием токена в том числе c расчетных счетов и с номинальных счетов.

Шаг 1. Сгенерируйте токен​

Если вы приняли решение не хранить на своей стороне данные банковских карт, отправьте запрос на создание токена методом tokenize/elements. В ответе придет токен.

Пропустите этот шаг, если у вас уже есть токен для рекуррентных выплат или токен, полученный через виджет.

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

Отправьте запрос на создание платежной сессии 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: signature' \
-d '{
}'
Пример ответа
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z"
  }
}

Шаг 3. Начните выплату​

Начните выплату, используя метод session/start/payout.

В запросе передайте:

  • Идентификатор сессии, полученный на предыдущем шаге.
  • Один из следующих параметров, в зависимости от типа имеющихся у вас данных:

Вы можете узнать информацию о токене или о карте с помощью метода token/info. В том числе — получить последние 4 цифры номера карты, чтобы показать пользователю, куда придет выплата.

Пример запроса
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: signature' \
-d '{
  "session_id": "ps_3230",
  "payment_method": {
    "type": "card",
    "card": {
      "type": "tokenized_card",
      "tokenized_card": {
        "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  },
  "metadata": "good"
}'
Пример ответа
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}'

Для выплат по токенизированным картам вы также можете использовать следующие запросы:

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

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

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

Пример вебхука
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",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user123@test.ru"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}'

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

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

Пример запроса session/confirm
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"
}'
Пример запроса session/cancel
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"
}'

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

Банк 131 отправит вам вебхук payment_finished. В теле вебхука придут все данные, с которыми проводилась выплата. Результат выплаты приходит в поле payment.status.

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

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