Как подписать запрос
Все запросы к Zetplat должны быть подписаны. В заголовках запросов необходимо передавать данные для идентификации: идентификатор вашего проекта и подпись запроса.
| Название | Обязательность | Тип | Описание |
|---|---|---|---|
X-Project-Id | + | string | Идентификатор проекта. Выдается менеджером Zetplat |
X-Signature | + | string | Подпись запроса |
X-Submerchant-Id | - | string | Идентификатор плательщика (юридического лица) |
Пример запроса с аутентификацией
curl -X POST \
https://proxy-demo.zetplat.com/api/v1/transaction/initiate \
-H 'Content-Type: application/json' \
-H 'X-Project-Id: your_project_name' \
-H 'X-Signature: signature' \
-d '{
// тело запроса
}'
Подпись запросов
Подпись нужна для проверки подлинности (запрос действительно пришел от отправителя) и целостности (данные не были изменены при передаче).
Принцип двусторонней проверки:
-
Zetplat проверяет, что запросы к нам пришли именно от вас и дошли без изменений.
-
Вы точно так же проверяете уведомления, которые приходят от Zetplat.
Для формирования и проверки подписи используется пара ключей: публичный (открытый) и секретный (приватный).
Генерация ключевой пары
Вы самостоятельно генерируете ключевую пару на своей стороне. Алгоритм подписи — RSA.
Свой публичный ключ вы передаете Zetplat (чтобы мы могли проверять ваши запросы), а секретный ключ храните у себя и никому не передаете.
Формирование подписи тела запроса
Каждый запрос к Zetplat должен сопровождаться подписью.
Что именно подписывать: тело запроса целиком, в том виде, в котором оно отправляется на сервер (после сериализации в JSON).
Алгоритм: SHA-256.
Формат подписи: Base64.
Чем подписывать: вашим секретным ключом.
Проверка входящих запросов от Zetplat
Все запросы, которые Zetplat отправляет вам (например, уведомления), подписываются на нашей стороне с использованием нашего секретного ключа.
Для проверки подлинности запросов от Zetplat используйте наш публичный ключ. Проверяйте подпись каждого входящего запроса с алгоритмом SHA‑256 — подпись передаётся в формате Base64. Любой запрос, не прошедший проверку подписи, должен отвергаться как недостоверный.
Публичные ключи Zetplat
Примеры генерации и проверки подписи
- OpenSSL
- PHP
# Генерация приватного ключа
$ openssl genrsa -out private.pem 2048
# Генерация публичного ключа из приватного
$ openssl rsa -in private.pem -pubout > public.pem
# Формирование содержимого файла myfile.txt
$ echo test > myfile.txt
# Генерация подписи
$ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt
# Готовая подпись для передачи
$ base64 sha256.sign
# Проверка подписи
$ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt
Verified OK
$data = "test";
//Получение указателя на приватный и публичный ключи
$privateKey = openssl_pkey_get_private("file://private.pem");
$publicKey = openssl_pkey_get_public("file://public.pem");
//Генерация подписи по данным с использованием приватного ключа
openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256);
openssl_free_key($privateKey);
//Для передачи подпись кодируем в формат Base64
$base64Signature = base64_encode($signature);
//При получении подписи декодируем ее обратно из Base64
$decodedSignature = base64_decode($base64Signature);
//Проверяем полученную подпись с использованием публичного ключа (1 - успех)
$isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256);