Авторизация

Все запросы к Merchant API должны содержать заголовки X-Identity и X-Signature. Запросы к Public API не требуют отправки дополнительных заголовков.

X-Identity

Заголовок X-Identity должен содержать API-ключ терминала.

X-Identity: <API-key>

X-Signature

Заголовок X-Signature должен содержать строку, закодированную в формате Base64, подписанную секретным ключом мерчанта по алгоритму HMAC-SHA1.

Строка для подписи формируется путём конкатенации следующих элементов в указанном порядке:

1. HTTP-метод запроса (GET, POST);
2. полный URL запроса, включая протокол, домен и строку параметров;
3. тело запроса — если оно присутствует.

Пример строки для подписи:

POSThttps://api.bopay.io/v1/payments{"ext_id":"order_12345","amount":5000,"method":"SBP"}

Для запросов GET тело отсутствует, поэтому строка формируется конкатенацией только метода и URL:

GEThttps://api.bopay.io/v1/payments/550e8400-e29b-41d4-a716-446655440000

Тело запроса

Подписывается тело в том виде, в котором оно передаётся в запросе — байт в байт. Повторная сериализация JSON перед подписью изменяет порядок ключей или форматирование и приводит к ошибке AUTH_002.

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

Полученная строка подписывается секретным ключом по алгоритму HMAC-SHA1, результат кодируется в Base64 и передаётся в заголовке X-Signature.

X-Signature: <Signature>

Примеры кода

function calculateSignature(string $method, string $url, string $bodyContent, string $secret): string
{
    $stringToSign = $method . $url . $bodyContent;
    return base64_encode(hash_hmac('sha1', $stringToSign, $secret, true));
}

const crypto = require('crypto');

function calculateSignature(method, url, bodyContent, secret) {
  const stringToSign = method + url + bodyContent;
  return crypto.createHmac('sha1', secret).update(stringToSign).digest('base64');
}

import hmac
import hashlib
import base64

def calculate_signature(method, url, body_content, secret):
    string_to_sign = f"{method}{url}{body_content}"
    hashed = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha1)
    return base64.b64encode(hashed.digest()).decode()

Пример запроса

curl -X POST https://api.bopay.io/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -d '{"ext_id":"order_12345","amount":5000,"method":"SBP"}'

Отладка подписи

Для терминала может быть включён режим отладки. При включённом режиме ответ на запрос с неверной подписью дополнительно содержит объект debug с канонической строкой, которую ожидал сервер:

{
  "error": "AUTH_002",
  "message": "Invalid signature",
  "debug": {
    "string_to_sign": "POSThttps://api.bopay.io/v1/payments{\"ext_id\":\"order_12345\"}",
    "signature_received": "9v3Xh..."
  }
}

Сравнение этой строки с той, что формируется на стороне мерчанта, позволяет локализовать расхождение. Режим включается по запросу и предназначен только для периода интеграции.

Коды ошибок авторизации приведены в разделе Ошибки.