API credentials

Your API credentials are a project and a secret, which authenticate API requests from your server.

Important: never use the secret key in client-side (frontend) code.`

We provide set of sandbox credentials to help you integrate API while compliance procedures not finished. Sandbox behaviour can differ from production, we suggest to run production tests as well.

Once your company passes the regulatory compliance procedures, production values for the project and secret key are issued.

HMAC Authentication

We use HMAC to authenticate entire request bodies. This approach is common in the payment industry, but it isn't standardized by API standards such as OpenAPI yet.

HMAC authentication is required for all API calls except /card/getToken

To account for JSON serialization differences, our specification defines a custom serialization format for HMAC calculations. As our API only uses flat lists of key-value pairs, there is no need to define serialization for nested structures.

To authenticate a request using an HMAC do the following:

  • sort the values in the case-sensitive ascending order

  • concatenate the sorted list using the "|" character

  • construct HMAC-SHA256 using your secret key

  • convert the resulting value to a lowercase ASCII hex string

  • pass the string as an extra signature parameter to the API call

For example, for the following request parameters in ASCII encoding:

project = "d7d86391b36b4543bc1cf87cbd2ee6c9"
payment_id = "38013333"

the 41 data bytes for HMAC calculation would be:

33 38 30 31 33 33 33 33 7c 64 37 64 38 36 33 39 31 62 33 36 62 34 35 34 33 62 63 31 63 66 38 37 63 62 64 32 65 65 36 63 39

(corresponds to ASCII "38013333|d7d86391b36b4543bc1cf87cbd2ee6c9" and not "d7d86391b36b4543bc1cf87cbd2ee6c9|38013333" because "38013333" is lexicographically smaller)

The secret key is provided as a hexadecimal string, so "c8a4e2cc008ae5cc32de78c498b1ac53b921360d611373900aead96c410b5de0'" corresponds to the following 32 octets:

c8 a4 e2 cc 00 8a e5 cc 32 de 78 c4 98 b1 ac 53 b9 21 36 0d 61 13 73 90 0a ea d9 6c 41 0b 5d e0

When the above two octet strings are used in HMAC-SHA256 calculation, the following HMAC value should be produced:

0a 5e a9 ee 64 d6 de c3 cc ff d1 3c 4e 6e 03 89 2f 8b 3e 8a ba c5 f7 b3 af 18 f9 50 9d 77 ce 38

The parameters and the HMAC value are then serialized as a single JSON object:

{
  project: "d7d86391b36b4543bc1cf87cbd2ee6c9",
  payment_id: "38013333",
  signature: "0a5ea9ee64d6dec3ccffd13c4e6e03892f8b3e8abac5f7b3af18f9509d77ce38"
}