API authentication

Required headersCopy Anchor Link

Protected operations require merchant-id and signature. Obtain the ID and API key for your active merchant in the console. The key is a secret string, not a bearer token.

The signature is lowercase hexadecimal HMAC-SHA256 using the API key over JSON.stringify(parsedBody || {}). There is no sha256= prefix in this header.

import { createHmac } from 'node:crypto';

// Підписує JSON так само, як gateway, щоб серверна інтеграція не залежала від пробілів raw body.
export function signRequest(body, apiKey) {
  return createHmac('sha256', apiKey)
    .update(JSON.stringify(body || {}))
    .digest('hex');
}

For a GET with no body, sign the two-byte JSON object {}. Path and query parameters are not included. Keep JSON property order stable: the gateway does not sort keys. Send monetary amounts as strings to avoid number conversion.

Sending a requestCopy Anchor Link

Serialize the same body object that you sign, then send it as application/json. Your merchant identity comes from the header; do not add a merchant_id property to the JSON body.

Every endpoint has cURL, JavaScript/Node.js, Python and PHP tabs with a complete request. The protected GET examples sign {} and send no body; public checkout examples omit merchant credentials.

The Python, PHP and cURL samples embed an already compact JSON string. Keep it compact when editing it. A signature over pretty-printed JSON, escaped /, or ASCII-escaped Unicode differs from the gateway's parsed and reserialized JSON. When building bodies dynamically, ensure the encoding matches JavaScript JSON.stringify: preserve property order, use literal UTF-8, and avoid floats and numeric object keys. In Python use json.dumps(body, ensure_ascii=False, separators=(',', ':')); in PHP use json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS | JSON_THROW_ON_ERROR). Keep amounts as strings and verify any nested metadata serialization too.

The quickstart shows a complete Node.js function; the creation reference provides all four language variants.

Access and key rotationCopy Anchor Link

Only an active merchant can authenticate. If source restrictions are enabled, the request must also come from an allowed IP address. 401 indicates missing or invalid credentials; 403 API_SOURCE_NOT_ALLOWED indicates a source policy refusal.

Rotating the API key invalidates signatures made with the old API key. Update your server configuration and verify the integration. Webhook verification uses a separate signing secret and a different message format; see webhooks.

Store secrets in your server's environment or secret manager. Never embed an API key in frontend JavaScript, public examples, URLs, or logs.