Authentication

Merchant Authentication

The Pay service uses header-based authentication with HMAC verification

to ensure that requests originate from an authorized merchant.

------------------------------------------------------------------------

Overview

Every request to the Pay service must:

  1. Include required authentication headers
  2. Provide a valid HMAC-SHA256 signature (x-token)
  3. Pass authorization checks performed by the Authorization service

If any validation fails, the request is rejected.

------------------------------------------------------------------------

Authentication Headers

All requests must include the following headers.

Required

x-public-key

Identifies the merchant account.

x-buyer-ip

Buyer IP address (IPv4 or IPv6).

x-date

Request timestamp in the following format:

Y-m-d\TH:i:s

Example:

2024-01-27T23:59:59

x-token

HMAC-SHA256 signature generated using the merchant's secretKey.

x-id

Calling service identifier.

x-source

Channel context:

  • shop
  • cp
  • staff
  • directlink

------------------------------------------------------------------------

Generating the x-token

To authenticate a request, generate a signature using the following

string:

secretKey + x-public-key + x-buyer-ip + x-date

Concatenate values exactly in this order. No separators.

------------------------------------------------------------------------

PHP Example

<?php

$json = '{
  "x-buyer-ip": "10.10.10.10",
  "x-date": "2024-01-27T23:59:59",
  "x-public-key": "aa46a835-36fa-4f75-ba3d-dc8785912345",
  "secretKey": "secret-key-test123123123abc"
}';

$data = json_decode($json, true);

$xToken = hash_hmac(
    'sha256',
    $data['secretKey'] .
    $data['x-public-key'] .
    $data['x-buyer-ip'] .
    $data['x-date'],
    $data['secretKey']
);

echo $xToken;

Authorization procedure

  1. The merchant’s service sends a request to a specific Pay service endpoint.
  2. When the Pay service receives the request, it takes the headers from the request

(x-public-key, x-buyer-ip, x-date, x-token, x-id, x-source) as well as the endpoint URL and forwards them to the Authorization service.

  1. The Authorization service validates the received data:

a. Merchant resolution

  • Based on the received x-public-key, determines the merchant account;
  • Checks that the account is active;
  • Obtains the account secretKey.

b. Token generation

  • Generates an x-token from the received data using the same algorithm as the merchant.

c. Token comparison

  • Compares the generated x-token with the one received from the Pay service.

d. x-id validation (identify calling service)

  • Extracts the x-id header;
  • Checks whether such a service exists in the access configuration;
  • Checks whether this service is allowed to call the specific endpoint;
  • If access is missing — returns 403 Forbidden.

e. x-source processing (request channel type)

  • Reads x-source;
  • Determines the channel context (shop / cp / staff / directlink);
  • Configures further business logic based on the channel;
  • If the type is incorrect or not allowed — returns 400 Bad Request or 403 Forbidden.

f. Endpoint access

  • Checks the merchant account’s access to the requested endpoint.

g. Success response

  • Sends 200 OK status with the merchant code back to the Pay service.
  1. The Pay service receives the 200 status and sends the request to other services on behalf of this merchant.
  2. The Pay service returns the response to the merchant.

Authorization flow diagram

Authorization flow