Как формируется подпись

Вы получили от менеджера тестовые настройки, среди которых есть open_key (merchant_id) и secret_key, которые являются открытым и закрытым ключами для формирования подписи.

Для формирования подписи мы используем HMAC SHA256.

Проще всего использовать готовый класс или модуль (посмотреть). Если вы сами реализуете подпись, то ниже вы найдёте подробности формирования подписи для различных случаев.

Вы должны подписывать каждый свой запрос/ответ, а так же проверять подпись от PlatBox из соображений безопасности платежей.

Подпись для формирования iframe/страницы

Для того, чтобы открыть iframe/страницу с окном оплаты, необходимо подписать определённую строку значений параметров.

  1. Составить строку для подписи. Строка состоит из сконкатенированных значений определенных полей. Последовательность (сортировка по алфавиту): 'account_additional', 'account_id' (обязательное), 'account_location', 'amount', 'currency', 'merchant_id' (обязательное), 'order', 'project' (обязательное), 'receipt_data', 'redirect_url'

  2. Подписать строку с помощью секретного ключа, алгоритм HMAC SHA256.

  3. Поместить полученную подпись последним параметром sign.

Описание параметров участвующих в подписи:

Параметр Описание
account_id Идентификатор учётной записи пользователя (например, номер телефона).
account_additional Любые дополнительные данные, необходимые для однозначной идентификации пользователя.
account_location Идентификатор региона расположения учётной записи. Может использоваться, если мерчант поддерживает несколько географически распределённых и при этом независимых экземпляров системы.
amount Сумма платежа в минорных единицах валюты (копейки, центы и т.д.).
currency Код валюты в ISO 4217 (RUB, USD, EUR и т.д.).
merchant_id Ваш Id (= Open Key) в системе, выдается при регистрации менеджером.
order Данные заказа. Может быть любой строкой, которую мы вам вернем в запросах callback, для идентификации заказа на вашей стороне.
project Идентификатор пакета товаров (товары, объеденные в логическую группу, товары и пакеты регистрируются заранее)

Внимание! Если вы планируете использовать разные проекты с разными интерфейсами, товарами и т.д. (к примеру, у вас две разных игры, требующие двух разных форм оплаты в разной цветовой гамме), то обязательно нужно предусмотреть возможность передачи параметра project в зависимости от проекта.
receipt_data Данные в формате [{"qty":..,"price":..,"tax":..,"desc":".."}], где qty - целое число описывающее количество единиц товара, price - стоимость единицы товара в минорных единицах, tax - тип налогооблажения, доступные варианты 1,2,3,4,5,6 (1-18%, 2-10%, 3-0%, 4-без НДС, 5-18/118, 6-10/110), desc - строковое описание единицы товара. Примечание: данный параметр можно использовать, если у вас заключен договор с Атол
redirect_url URL, куда будет перенаправлен ваш пользователь после завершения оплаты.

Дополнительные параметры, которые не участвуют в подписи

Параметр Описание
order_label Информация о заказе, отображаемая на форме оплаты

Пример на языке php:

<?php
/**
 * Указываем настройки, полученные от менеджера
 */
$secretKey = "INSERT YOUR SECRET KEY";
$openKey   = "INSERT YOUR OPEN KEY";
$project   = "INSERT YOUR PROJECT";
$url       = "https://paybox-v4-beta.platbox.com/pay";

/**
 * Указываем параметры платежа
 */
$paramsForTransaction = [
    'account_id'  => 'support-merchant@platbox.com',
    'amount'      => 1000,
    'currency'    => 'RUB',
    'merchant_id' => $openKey,
    'order'       => 'Order_1',
    'project'     => $project,
];

/**
 * Получаем подпись
 */
ksort($paramsForTransaction);
$stringForSign = implode('', $paramsForTransaction);
$sign          = hash_hmac('sha256', $stringForSign, $secretKey);

/**
 * Собираем все параметры, необходимые для создания ссылки в общий массив
 */
$linkParams = array_merge($paramsForTransaction, ['sign' => $sign]);

/**
 * Получаем ссылку на платежную форму
 */
$url = $url."?".http_build_query($linkParams);
// Получилось: https://paybox-v4-beta.platbox.com/pay?account_id=support-merchant%40platbox.com&amount=1000&currency=RUB&merchant_id=INSERT+YOUR+OPEN+KEY&order=Order_1&project=INSERT+YOUR+PROJECT&sign=331e40c6ff7b61f0116ea9bcbb01883f7c3ac0ab5f3c762bd99de418df2e3e72

Подпись для http-запросов

Как PlatBox подписывает свои запросы/ответы, и как вы должны подписывать свои запросы/ответы:

  1. Взять тело запроса (тело приходит в json формате), которое будет отправлено. Без сортировок и привидений типов.
  2. Подписать его с помощью секретного ключа, алгоритм HMAC SHA256.
  3. Поместить в заголовок запроса X-Signature.

Пример на языке php:

<?php
/**
 * Получение тела запроса
 */
$rawData = file_get_contents("php://input");

/**
 * Настройка секретного ключа
 */
$secretKey = 'secret';

/**
 * Получение входящей подписи
 */
$incomingSignature = $_SERVER['HTTP_X_SIGNATURE'];

/**
 * Генерация подписи по входящему телу запроса
 */
$generateSignature = hash_hmac('sha256', $rawData, $secretKey);

/**
 * Сравнение входящей подписи и сгенерированной подписи
 */
if ($generateSignature == $incomingSignature) {
    /**
     * Подписи сошлись, запрос валиден
     */
} else {
    /**
     * Подписи не сошлись, запрос не валиден
     */
}

Пример

Возьмём секретный ключ "secret" и тело запроса:


    {
        "account": {
            "id": " +79859999999"
        },
        "currency": "RUB",
        "merchant_id": "12444",
        "order": {
            "type": "order_id",
            "order_id": "23ew4erf9"
        },
        "payer": {
            "phone_number": "79091120000"
        },
        "project": "test_project"
    }

Получившаяся подпись будет 1353adf5b6137c476bc66891d30d82cbdb4055335f1d5f2d3d42f1cd96245a59.