API interaction

Endpoint

How to generate a request

<server address> + /api/v{API version number} + <required method>

For the version number, only the major part (before the point) is used. Currently, the API version is 1.0, so the address for sending a request for a test payout will be as follows:

https://demo.smart-glocal.com/api/v1/session/start/payout

Server address

For testing: https://demo.smart-glocal.com
For live transactions: https://proxy.smart-glocal.com

Request format

All the data in requests to Smart Glocal and notifications from Smart Glocal is transmitted using the HTTP POST method. Message parameters are packed into a JSON object.

Authentication

In the headers of your requests to Smart Glocal, always pass the following data for authentication:

your project identifier
request signature

Headers

Name	Mandatory	Type	Description
X-PARTNER-PROJECT	+	string	Project identifier (from your Smart Glocal manager)
X-PARTNER-SIGN	+	string	Request signature
X-PARTNER-SUBMERCHANT	-	string	Payer's identifier (for legal entities)

Request example with authentication

curl -X POST \
  https://demo.smart-glocal.com/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    // request body
}'

Request signature

The signature is needed to verify the authenticity and integrity of requests. Smart Glocal verifies that the requests received are in fact from you (and are complete); you verify Smart Glocal's notifications the same way.

To create and verify a signature, you will need a secret key and a public key. Using your public key Smart Glocal will verify signatures of your incoming payments.

Generating a key pair

You need to generate a pair of keys on your side using the RSA signature algorithm.

Creating request body signature

The signature must be transmitted together with the request to Smart Glocal. You need to sign the request body as a whole in the form in which it is sent to Smart Glocal's server (after serializing the request body into JSON to send it over HTTP).

Use your secret key for signing the request. Create a signature using the SHA-256 algorithm. The resulting signature must then be transmitted in the Base64 format.

Verifying incoming requests from Smart Glocal

All outgoing requests from Smart Glocal are signed using Smart Glocal's own secret key.

Using Smart Glocal's public key, you need to verify the signatures of the requests coming from Smart Glocal on your side. The algorithm used is SHA-256. The signature is transmitted in the Base64 format.

Smart Glocal's public keys

Signature generation and validation examples

OpenSSL
PHP

# Generating a private key
$ openssl genrsa -out private.pem 2048

# Generating a public key based on the private key
$ openssl rsa -in private.pem -pubout > public.pem

# Creating myfile.txt file contents
$ echo test > myfile.txt

# Generating a signature
$ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt

# Signature ready for transfer
$ base64 sha256.sign

# Checking the signature
$ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt
Verified OK

$data = "test";

//Obtaining the pointer to the private and public keys
$privateKey = openssl_pkey_get_private("file://private.pem");
$publicKey  = openssl_pkey_get_public("file://public.pem");

//Generating a signature based on the data using the private key
openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256);
openssl_free_key($privateKey);

//Encoding the signature into Base64 to transmit it
$base64Signature = base64_encode($signature);

//On receiving the signature, decoding it from Base64
$decodedSignature = base64_decode($base64Signature);

//Validating the received signature using the public key (success = 1)
$isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256);

Idempotency key

An idempotency key is a unique request identifier. You can generate it and use it to ensure that no request with the same unique identifier is attempted more than once. For example, this way you can avoid duplicate payments and payouts.

The idempotency key lifetime is 24 hours.

Format

Specify the idempotency key in the request header.

Name	Mandatory	Type	Description
X-PARTNER-IDEMPOTENCY-KEY	-	string	Idempotency key (from 4 to 64 characters)

Example of a request with an idempotency key

curl -X POST \
  https://proxy.smart-glocal.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: idempotency_key' \
  -d '{
    // request body
}'

Methods supporting the idempotency key feature

Errors

idempotency_key_params_mismatch - The key has already been used for another session
idempotency_key_already_exists - The previous request with the same key is still in progress
idempotency_key_not_supported - This method cannot be used with an idempotency key

See more about the Errors

Endpoint​

How to generate a request​

Server address​

Request format​

Authentication​

Headers​

Request example with authentication​

Request signature​

Generating a key pair​

Creating request body signature​

Verifying incoming requests from Smart Glocal​

Smart Glocal's public keys​

Signature generation and validation examples​

Idempotency key​

Format​

Example of a request with an idempotency key​