Authorization

All API requests must be authorized using an API Key and a request signature.

Getting Keys

Each merchant receives:

1. API Key — a unique terminal key for identification (each terminal has its own)
2. Secret Key — a secret merchant key for signing requests (shared across all terminals)

Important

Keep your Secret Key secure. Do not share it with third parties or publish it publicly.

Request Headers

Each API request must contain the following headers:

Header	Description
Content-Type	application/json
X-Identity	Your API Key
X-Signature	Request signature

Creating a Signature

The signature is created using the HMAC-SHA1 algorithm and transmitted in Base64 encoding.

String to Sign

{METHOD}{URL}{BODY}

Where:

• METHOD — HTTP method (GET, POST, etc.)
• URL — full request URL including protocol
• BODY — request body in JSON format (empty string for GET)

JavaScript Example

const crypto = require('crypto');

const method = 'POST';
const url = 'https://api.bopay.io/v1/payments';
const body = JSON.stringify({
  amount: 5000,
  method: 'SBP',
  ext_id: 'order_12345'
});

const stringToSign = method + url + body;

const signature = crypto
  .createHmac('sha1', secretKey)
  .update(stringToSign)
  .digest('base64');

Python Example

import hmac
import hashlib
import base64
import json

method = 'POST'
url = 'https://api.bopay.io/v1/payments'
body = json.dumps({
    'amount': 5000,
    'method': 'SBP',
    'ext_id': 'order_12345'
})

string_to_sign = method + url + body

signature = base64.b64encode(
    hmac.new(
        secret_key.encode(),
        string_to_sign.encode(),
        hashlib.sha1
    ).digest()
).decode()

PHP Example

$method = 'POST';
$url = 'https://api.bopay.io/v1/payments';
$body = json_encode([
    'amount' => 5000,
    'method' => 'SBP',
    'ext_id' => 'order_12345'
]);

$stringToSign = $method . $url . $body;

$signature = base64_encode(
    hash_hmac('sha1', $stringToSign, $secretKey, true)
);

Request Example

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

Authorization Errors

Code	Description
AUTH_001	Invalid API Key
AUTH_002	Invalid signature
AUTH_004	Missing X-Identity header
AUTH_005	Merchant blocked
AUTH_006	Missing X-Signature header
AUTH_007	Terminal disabled