Authorization

Protected API methods require authorization with an HMAC-SHA256 signature.

Required headers

Each request must include three required headers:

Signature generation

The signature is generated from the timestamp and request body.

Format description

Signature algorithm:

• Get the current Unix time in seconds
• Get the request body
• Convert JSON to canonical format
• Build the string: timestamp + "." + canonicalBody
• Sign the string with HMAC-SHA256 using api_secret
• Pass the timestamp and signature in request headers

Important requirements:

• api_secret must not be sent in the request
• api_secret must be stored only on the merchant server
• The signature must be calculated separately for each request
• X-Timestamp must match the time when the signature was generated
• The request body sent to the API must exactly match the body used to calculate the signature
• For requests without a body, sign a string in this format: {timestamp}

Examples:

PHPPythonJS

Authorization errors

{
  "status": 401,
  "message": "Invalid X-Timestamp"
}

{
  "status": 401,
  "message": "Expired X-Timestamp"
}

{
  "status": 401,
  "message": "Invalid X-Signature"
}

{
  "status": 401,
  "message": "Invalid token"
}

{
  "status": 401,
  "message": "Merchant secret not configured"
}

{
  "status": 500,
  "message": "Internal Server Error"
}