BankID + КЕП

Зміст

1 Зміст
2 Опис
3 Чекліст інтеграції
4 Взаємодія
5 Обмеження
6 API параметри
7 Приклад запиту
8 Callback
9 Перевірка

Опис

Продукт BankID + КЭП (P-Sign) використовується для отримання даних про клієнта разом зі сканами документів через сервіс BankID ПриватБанк, та подальшим підписанням отриманих сканів КЕП (кваліфікаований електронний підпис) за допомогою додатку Privat24.

Чекліст інтеграції

Інтугрувати API метод цього розділу.

Відобразити клієнту кнопку на сайті / додатку.

Відобразити клієнту QR код або авторедірект в Privat24 на підпис документів.

Отримати успішний Callback Bank ID з даними про клієнта.

Отримати успішний Callback P-Sign з підписаними документами.

Сценарії використання:

Клієнт натискає на сайті / додатку кнопку "Верифікація документів".
Клієнта редиректить на сайт або додаток Privat24 де він проходить авторизацію.
Якщо клієнт на десктопі — сканує QR за допомогою додатку Privat24, авторизується та вводить свій пароль КЕП.
Якщо клієнт на смартфоні — одразу редиректиться на форму для вводу свого пароля КЕП в додатку Privat24 (авторизація була виконана попереднім кроком).
Після підписання клієнта редіректить на сторінку успішної верифікації документів.

На даный момент тільки для кліентів ПриватБанк.

HTTP METHOD: POST

API ENDPOINT: https://sign.platon.ua/api

Параметр	Значення	Опис

Параметр	Значення	Опис
`action` Обов'язковий	`GET_BANKID_SIGN`	API метод
`client_key` Обов'язковий	String	API ключ мерчанта в системі PSP Platon саме для BankID + КЕП
`client_request_id` Обов'язковий	String	Унікальним ідентифікатор запиту мерчанту
`success_url` Обов'язковий	String	URL на сторінку успішної верифікації документів
`error_url` Обов'язковий	String	URL на сторінку невдалої верифікації документів
`bankid_callback_url` Обов'язковий	String	URL, куди буде відправлено Callback Bank ID з даними про клієнта
`callback_url` Обов'язковий	String	URL, куди буде відправлено Callback P-Sign з підписаними документами
`mode` Обов'язковий	`test` `prod`	Переключення режиму тестового (`test`) та прод (`prod`) середовищ
`itn` не Обов'язковий	String	Вказати ІНН клієнта якщо він наявний. Якщо ІНН немає - параметр не передавати.
`hash` Обов'язковий	String	Контрольний підпис `md5( strtoupper( strrev($client_password). strrev($client_request_id) ) )`

<?php
$client_key = '******';
$client_password = '******************';
$client_request_id = microtime(); // рандом
$mode = 'prod';
$success_url = 'https://*************'; 
$error_url = 'https://*************';
$bankid_callback_url = 'https://*************'; 
$callback_url = 'https://*************';
$hash = md5(
          strtoupper(
            strrev($client_password).
            strrev($client_request_id)
          )
        );
?>

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>BANK-ID SIGN</title>
  </head>
  <body>
    <form method="POST" action="https://sign.platon.ua/api">
      <input type="hidden" name="action" value="GET_BANKID_SIGN">
      <input type="hidden" name="client_key" value="<?= $client_key ?>">
      <input type="hidden" name="client_request_id" value="<?= $client_request_id ?>">
      <input type="hidden" name="success_url" value="<?= $success_url ?>">
      <input type="hidden" name="error_url" value="<?= $error_url ?>">
      <input type="hidden" name="bankid_callback_url" value="<?= $bankid_callback_url ?>">
      <input type="hidden" name="callback_url" value="<?= $callback_url ?>">
      <input type="hidden" name="mode" value="<?= $mode ?>">
      <input type="hidden" name="hash" value="<?= $hash ?>">
      <button type="submit">START BANK-ID SIGN</button>
    </form>
  </body>
</html>

<?php
declare(strict_types=1);

// ---------- ПЕРЕМЕННЫЕ
$client_key = 'PL-*****';
$api_password = '********************';

$client_request_id = 'PL-11917';

$privateKey = ''; // приватный ключ для расшифровки (можно не указывать)
$downloadFolder = './docs/';

$hash = md5(strtoupper(strrev($api_password).strrev($client_request_id)));

if (! array_key_exists('personal_data', $_POST) || ! array_key_exists('hash', $_POST)) {
    echo "не прислано данные!\n";
    return;
}

if  ($hash !== $_POST['hash']) {
    echo "подписи не совпадают!\n";
}

function isJson($string): bool
{
    json_decode($string);
    return json_last_error() === JSON_ERROR_NONE;
}

// расшифровка
$personalData = $_POST['personal_data'];
if (! isJson($_POST['personal_data'])) {
    openssl_private_decrypt(base64_decode($personalData), $decrypted, $privateKey);
    $personalData = $decrypted;
}
$personalData = json_decode($personalData, true);

// скачивание файлов
foreach ($personalData['scans'] as $scan) {
    $filename = $downloadFolder.$scan['type'].'.'.$scan['extension'];
    file_put_contents($filename, fopen($scan['link'], 'r'));
    echo "файл сохранен! $filename\n";
}

// персональные данные
var_dump($personalData);

IP адреси сервера відправки:

104.248.247.85
104.21.35.224
172.67.180.63

Редірект клієнта при успішній верифікації документів:

После успешной авторизации на success_url будет перенаправлен браузер клиента и методом GET переданы параметры.

При успешном запросе:

При неуспешном запросе:

Для індивідуальної перевірки необхідно завантажити файли документів підписаних КЕП на офіційний ресурс Центрального засвідчувального органу.