Merchant Authentication to Pay service

After a successful integration, use the following base URLs to access our endpoints:

Production: https://pay.billerbase.com
Sandbox: https://pay-sandbox.billerbase.com

Integration steps

After the merchant confirms their readiness to integrate with Core Billing, the billing manager will provide the following data for the integration process with the payment gateway:

code – the merchant code,
publicKey – the public access key that must be used in the x-public-key header,
secretKey – the private access key that must be used to generate x-token for each request.

To start using the Authorization service, you need to integrate valid headers that will be used for authentication and authorization.

Please note that all new headers are MANDATORY and must be included in the request for every Pay service endpoint.

New headers

x-public-key

a public key that identifies the merchant account (there may be several for one merchant);
required for validation and generation of x-token;
replaces the Brand header.

x-buyer-ip

contains information about the buyer’s IP address;
required for validation and generation of x-token;
cannot be null or an empty string; must be a valid IPv4/IPv6 address;
replaces the x-client-ip header and other standard headers related to the buyer’s IP address.

x-date

contains the date and time when the request is sent;
required for validation and generation of x-token;
format: Y-m-dTH:i:s (for example, 2024-01-27T23:59:59).

x-token

generated on the merchant side.

Principles of x-token generation

Using the hmac(sha256) hashing algorithm, build a hash from the string secretKey + x-public-key + x-buyer-ip + x-date, using secretKey as the key.

var moment = require('moment');
var CryptoJS = require('crypto-js');

pm.environment.set('x-date', moment().format(("Y-m-dTH:mm:s")));
var xDateHeader = pm.environment.get('x-date'),
    xPublicKeyHeader = publicKey 
                    ?? pm.environment.get('x-public-key')
                    ?? pm.globals.get('x-public-key'),
    xSecretKeyHeader = secretKey
                    ?? pm.environment.get('x-secret-key') 
                    ?? pm.globals.get('x-secret-key'),
    xBuyerIpHeader = pm.globals.get('x-buyer-ip');

var tokenString = xSecretKeyHeader + xPublicKeyHeader + xBuyerIpHeader + xDateHeader;
var token = CryptoJS.HmacSHA256(tokenString, xSecretKeyHeader).toString(CryptoJS.enc.Hex);
console.log("secret = " + token);
console.log("date = " + xDateHeader);
console.log("PublicKey = " + xPublicKeyHeader);
console.log("secretKey = " + xSecretKeyHeader);
console.log("ip = " + xBuyerIpHeader);

pm.request.addHeader("x-date: " + xDateHeader);
pm.request.addHeader("x-public-key: " + xPublicKeyHeader);
pm.request.addHeader("x-buyer-ip: " + xBuyerIpHeader);
pm.request.addHeader("x-token: " + token);

<?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']
);
print_r(['x-token' => $xToken]);
/*
Array
(
    [x-token] => 5cdc01c2d66c52a513f58e077d85660468852fc141d305888416a151a05dc159
)
*/

Authorization procedure

After all Integration steps have been completed, the successful authorization flow will look as follows (step by step):

The merchant’s service sends a request to a specific Pay service endpoint.
When the Pay service receives the request, it takes the headers from the request (x-public-key, x-buyer-ip, x-date, x-token) as well as the endpoint URL and forwards them to the Authorization service.
The Authorization service validates the received data:
a. Based on the received x-public-key, it determines the merchant account, checks that it is active, and obtains its secretKey;
b. Generates an x-token from the received data using the same algorithm as the merchant;
c. Compares the generated x-token with the one received from the Pay service;
d. 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. 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 or 403;
f. Checks the merchant account’s access to the requested endpoint;
g. Sends a 200 status with the merchant code back to the Pay service.
The Pay service receives the 200 status and sends the request to other services on behalf of this merchant.
The Pay service returns the response to the merchant.

Note: If at any stage of the checks and validation performed by the Authorization service a mismatch is detected, the merchant will receive a 500 or 401 error in future releases.

{
  "uuid": null,
  "message": "Unauthorized service use is forbidden",
  "code": 0,
  "traceId": "e8977d1cfc799423d8eb7e8d9000965f"
}