API interaction
Endpoint
How to generate a request
<server address> + /api/v{API version number} + <address for sending the necessary method requests>
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 payment will look like this:
https://demo.smart-glocal.com/api/v1/session/init/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 the signature, you will need a secret and public key. Your public key is specified in the Application for recognition and verification of electronic signature key. Using the 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 key:
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