Формат работы с API

Версия API

В настоящее время мы поддерживаем две версии API.

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

API v1	API v2
`payments`	`payout_list`
`payment_method`	`payout_details`
`acquiring_payments`	`payment_list`

Адрес для отправки запросов

Как сформировать

<адрес сервера> + /api/v{номер версии API} + <адрес для отправки запросов нужного метода>

Например:

API v1: https://proxy-demo.pikepayments.com/api/v1/session/init/payout
API v2: https://proxy-demo.pikepayments.com/api/v2/session/init/payout

Адрес сервера

Для тестирования https://proxy-demo.pikepayments.com
Для реальных операций https://proxy.pikepayments.com

Формат запросов

Все данные в запросах к Pike и уведомлениях от Pike передаются методом POST по протоколу HTTP. Параметры сообщения упаковываются в JSON-объект.

Аутентификация

В заголовках запросов к Pike необходимо передавать данные для идентификации: идентификатор вашего проекта и подпись запроса.

Название	Обязательность	Тип	Описание
`X-PARTNER-PROJECT`	+	string	Идентификатор проекта. Выдается менеджером Pike
`X-PARTNER-SIGN`	+	string	Подпись запроса
`X-PARTNER-SUBMERCHANT`	-	string	Идентификатор плательщика (юридического лица)

Пример запроса с аутентификацией

curl -X POST \
  https://proxy-demo.pikepayments.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    // тело запроса
  }'

Подпись запроса

Подпись нужна, чтобы проверять подлинность и целостность запросов. Pike проверяет, что запросы пришли именно от вас (и дошли целиком), вы проверяете таким же образом уведомления от Pike.

Для формирования и проверки подписи нужны публичный и приватный ключи. С помощью вашего публичного ключа Pike будет проверять подпись ваших входящих запросов.

Генерация ключевой пары

Вам нужно сгенерировать на своей стороне пару ключей с алгоритмом подписи RSA.

Формирование подписи тела запроса

Вместе с запросом в Pike необходимо передавать подпись. Подписывать необходимо тело запроса целиком, в том виде, в котором оно отправляется на сервер Pike (после сериализации тела запроса в JSON для отправки по HTTP).

Используйте для подписи ваш приватный ключ. Сформируйте подпись с алгоритмом SHA-256. Полученную подпись необходимо передавать в формате Base64.

Проверка входящих запросов от Pike

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

С помощью публичного ключа Pike вам необходимо проверять подписи запросов и вебхуков от Pike на своей стороне. Используется алгоритм SHA-256. Подпись передается в формате Base64.

Публичные ключи Pike

Примеры генерации и проверки подписи

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);

Ключ идемпотентности

Ключ идемпотентности — это уникальный идентификатор операции. Вы можете его самостоятельно генерировать и использовать, когда есть необходимость запретить повторное выполнение той же операции до ее завершения. Например, чтобы не сделать двойную выплату или списание.

Срок действия ключа составляет 24 часа.

Формат

Идентификатор ключа идемпотентности указывается в заголовке запроса.

Название	Обязательность	Тип	Описание
`X-PARTNER-IDEMPOTENCY-KEY`	-	string	Ключ идемпотентности. Формат: от 4 до 64 знаков

Пример запроса с ключом идемпотентности

curl -X POST \
  https://proxy-demo.pikepayments.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \
  -d '{
    // тело запроса
  }'

Список методов с поддержкой ключа идемпотентности

Список возможных ошибок

idempotency_key_params_mismatch — Ключ уже был использован ранее для другой сессии.
idempotency_key_already_exists — Предыдущий запрос с таким же ключом еще не обработан.
idempotency_key_not_supported — Метод не поддерживает использование ключа идемпотентности.

Платежная сессия

Все операции в API проходят в рамках платежной сессии. Одна платежная сессия может объединять несколько операций, например, платеж и возврат.

Версия API​

Адрес для отправки запросов​

Как сформировать​

Адрес сервера​

Формат запросов​

Аутентификация​

Пример запроса с аутентификацией​

Подпись запроса​

Генерация ключевой пары​

Формирование подписи тела запроса​

Проверка входящих запросов от Pike​

Публичные ключи Pike​

Примеры генерации и проверки подписи​

Ключ идемпотентности​

Формат​

Пример запроса с ключом идемпотентности​

Платежная сессия​