Формат работы с 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

# Генерация приватного ключа
$ 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

PHP

$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 '{
    // тело запроса
  }'

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

• session/create
• session/init/payout
• session/start/payout
• session/init/payment
• session/start/payment
• session/confirm
• session/capture
• session/cancel
• session/refund

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

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

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

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