Skip to main content

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

NameMandatoryTypeDescription
X-PARTNER-PROJECT+stringProject identifier (from your Smart Glocal manager)
X-PARTNER-SIGN+stringRequest signature
X-PARTNER-SUBMERCHANT-stringPayer'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

# 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

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.

NameMandatoryTypeDescription
X-PARTNER-IDEMPOTENCY-KEY-stringIdempotency 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