API key and security management

To work with the Syncra Merchant API V2, your application needs API credentials. The platform uses separate keys to identify requests from the merchant to the gateway and to verify incoming notifications (webhooks) from the gateway to the merchant.

Types of access keys

1. API Token (merchant token):

   • A unique string (64 hexadecimal characters) used as the public identifier.
   • Sent in the X-Merchant-Token header on every API request.
   • Used to authorize requests and determine the merchant's permissions.

2. Webhook Secret (signature secret):

   • A private cryptographic key (a 32-byte secret) used to compute HMAC-SHA256 signatures.
   • Never transmitted over the network in plain text.
   • Used by the merchant to generate the X-Signature signature on outgoing requests and to verify the X-Signature signature on incoming webhooks.
   • Shown in the dashboard only once, on creation or rotation.

Obtaining API keys

Access keys are issued in the platform Admin Cabinet or via the dedicated issuance endpoint:

POST /api/v1/p2p/merchant/api-keys

Response example (200 OK)

The response fields are token and secret (top level, no data wrapper; NOT api_token / webhook_secret):

{
  "token": "a1b2c3d4e5f607182930a4b5c6d7e8f901a2b3c4d5e6f7081920a3b4c5d6e7f8",
  "secret": "whsec_920ab3e09819cd8e412cfab9e87d0c3c"
}

API version (api_version)

When a merchant is created or edited in the admin panel, the API Version parameter is available:

• API V2 (default): the full new Syncra V2 API with kopeck support, HMAC-SHA256, and alphabetic currency codes.
• API V1 (compatibility mode): emulates the legacy platform behavior (HMAC-SHA512, ; separators, integer-encoded statuses). Used for a seamless migration without changes to merchant code.

For a seamless transition from the legacy gateway, select version v1 when registering the merchant.

API key rotation (Token Rotation)

If a token is compromised, or on your company's security schedule (for example, every 90 days), you must rotate the keys.

POST /api/v1/p2p/merchant/api-keys/rotate

Response example (200 OK)

Rotation returns the new pair in the same token / secret fields (top level, no data wrapper; NOT api_token / webhook_secret):

{
  "token": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "secret": "whsec_1f2e3d4c5b6a7988071625344352f1e0d0c9b8a7f6e5d4c3b2a190807"
}

Dual key validity window (Grace Period)

The Grace Period is confirmed platform behavior (deployed and verified by a live E2E): after a successful rotation, a 15-minute window applies during which the gateway accepts requests signed with either the new or the old key pair:

• On the rotation request, the system atomically generates a new "token + secret" pair — it is valid immediately.
• The old pair remains valid for up to 15 minutes, giving your application time to safely update its configuration and restart services without downtime (Zero-Downtime Migration).
• The window is strictly pair-scoped: only the complete old pair (old token + old secret) is valid. Mixed combinations (old token + new secret, or the other way around) are rejected with 401 Unauthorized.
• Outgoing webhooks are signed with the new secret from the moment of rotation — do not wait for the window to close before verifying callbacks.
• The window duration is configured by the operator via the MERCHANT_KEY_GRACE_PERIOD environment variable; a value of 0 disables the window completely (rotation instantly kills the old pair).

Emergency shutoff (API Kill-Switch)

If you discover a key leak or unauthorized transactions, contact the platform operator: they instantly block all of the merchant's API requests with the Kill-Switch toggle.

POST /api/v1/p2p/merchants/{merchant_id}/kill-switch

• This is a bodyless toggle: each call flips the state (blocked ↔ unblocked) and returns the merchant object with the current kill_switch. The endpoint has no request fields (active/reason).
• Admin-only: the endpoint is available only to a platform operator JWT session (role admin/platform_admin). The HMAC pair and the merchant's cabinet session get 403 Permission Denied ("admin role required") — a merchant cannot disable itself; if you suspect a compromise, ask the operator to rotate the keys and apply the block.
• While the kill switch is active, every API request from this merchant is rejected with 403 Forbidden (merchant is disabled). The status and the block reason are visible to the merchant in the cabinet: GET /api/v1/p2p/my-merchant → the kill_switch / kill_switch_reason fields (see My Merchant).

Key storage security

• Never store the API token and the Webhook Secret in your application's source code (hardcoded keys).
• Use environment variables (ENV) or dedicated secret managers (HashiCorp Vault, AWS Secrets Manager, Google Secret Manager).
• Restrict access to configuration files on your servers.
• Use the IP Whitelisting feature in the dashboard to restrict the list of servers allowed to make requests with your token.