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.

In another language, ensure its JSON encoding produces the same string as JavaScript JSON.stringify after parsing. Unicode, escaping, numeric values, and property order deserve explicit checks. The quickstart includes a complete Node.js request.

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.