Выплата с номинального счета на банковскую карту

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

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

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

Токен нужен для работы с виджетом. Отправьте запрос на создание токена token, передайте в нем тип виджета, с которым хотите работать. В ответе придет токен.

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

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 '{
  "tokenize_widget": {
    "access": true
  }
}'

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()
    ->setTokenizeWidget()
    ->build();

$response    = $client->widget()->issuePublicToken($request);
$publicToken = $response->getPublicToken();

Шаг 2. Покажите получателю форму для сбора данных карты

Для этого нужно подключить нашу JavaScript-библиотеку и добавить виджет для токенизации на страницу, где получатель сможет заполнить форму с данными своей карты.

Получатель введет данные карты, а вы получите токенизированные данные, с которыми можно проводить выплату.

Инициализировать виджет можно с помощью токена, который вы получили на предыдущем шаге.

Как добавить виджет для токенизации

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

Отправьте запрос на создание платежной сессии session/multi/create/nominal, затем — на создание выплаты с идентификатором этой сессии session/multi/start/payment/nominal. В объекте encrypted_card передайте токенизированные данные банковской карты, полученные из виджета.

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

При выплате с номинального счета параметр beneficiary_id является обязательным для любого типа карт.

Если вы отправляете деньги на карту российского банка, вам понадобятся:

номер карты,
имя получателя,
и сумма в копейках (чтобы передать 100 рублей, в поле amount_details.amount укажите 10000).

Посмотреть параметры для выплаты на российские карты

Как заполнять данные бенефициара

Для выплат с номинального счета необходимо указывать данные бенефициара. В качестве данных бенефициара мы ожидаем получить ИНН бенефициара. Данные бенефициара указываются в объекте participant_details , в списке данных отправителя sender или данных получателя recipient. Если ваш бенефициар является отправителем - укажите его ИНН в блоке sender, если он является получателем, то укажите в блоке recipient. До старта выплат вам необходимо передать список данных ваших бенефициаров вашему менеджеру.

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

curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "Назначение платежа"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "****************"
      }
    }
  },
  "participant_details": {
    "sender": {
      "full_name": "Данные отправителя",
      "beneficiary_id": "1234567890"
    },
    "recipient": {
      "full_name": "Иванов Иван Иванович"
    }
  },
  "amount_details": {
    "amount": 293400,
    "currency": "RUB"
  },
  "customer": {
    "reference": "123456789012"
  }
}'

Пример старта выплаты

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "metadata": "good"
}'

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

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

В ответ следует отдавать 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_14667043",
    "status": "in_progress",
    "created_at": "2022-09-14T09:32:19.891392Z",
    "updated_at": "2022-09-14T09:32:20.494410Z",
    "payments": [
      {
        "id": "po_7639847",
        "status": "pending",
        "created_at": "2022-09-14T09:32:20.100149Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "mastercard",
            "last4": "8371",
            "country_iso3": "RUS"
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 293400,
            "currency": "RUB"
          },
          "gross": {
            "amount": 293400,
            "currency": "RUB"
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "Название компании",
            "beneficiary_id": "123456789"
          },
          "recipient": {
            "full_name": "Иванов Иван Иванович"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_6933973",
        "status": "pending",
        "created_at": "2022-09-14T09:32:20.099952Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "Перевод согласно оферты",
              "card_mask": "553691******8371"
            }
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 293400,
            "currency": "RUB"
          },
          "gross": {
            "amount": 293400,
            "currency": "RUB"
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "Название компании",
            "beneficiary_id": "1234567890"
          },
          "recipient": {
            "full_name": "Иванов Иван Иванович"
          }
        }
      }
    ],
    "next_action": "confirm"
  },
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "Название компании",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Банк 131",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Перевод согласно оферты",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

Шаг 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_14667043",
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "Название компании",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Банк 131",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Перевод согласно оферты",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

Пример запроса 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_14667043",
  "confirm_information": {
    "transfer_details": {
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mastercard",
          "last4": "8371",
          "country_iso3": "RUS"
        }
      },
      "customer": {
        "account_number": "40702810700200000000",
        "name": "Название компании",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "recipient": {
        "account_number": "30233810000000000000",
        "name": "Банк 131",
        "bank_name": "Банк 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822000000000"
      },
      "purpose": "Перевод согласно оферты",
      "amount": {
        "amount": 293400,
        "currency": "RUB"
      }
    }
  }
}'

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

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

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

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

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

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

Шаг 2. Покажите получателю форму для сбора данных карты​

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

Как заполнять данные бенефициара​

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

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

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