Sign every server request
Authenticate with a merchant API key and HMAC-SHA256 over the exact body bytes and backend path.
Required headers#
- X-API-KEY: your merchant API key. Send it only from your server over HTTPS.
- X-TIMESTAMP: Unix seconds, within five minutes of server time. Synchronize your server clock.
- X-NONCE: a fresh unique value for every HTTP attempt.
- X-SIGNATURE: lowercase hexadecimal HMAC-SHA256 of the canonical string, using the API key as signing secret.
- Content-Type: application/json for JSON bodies. For direct create also persist and send an Idempotency-Key UUID.
Canonical string#
Use uppercase HTTP method and newline separators, with no trailing newline. Hash the UTF-8 body bytes exactly as sent; do not reserialize JSON after signing. An empty GET body hashes as the empty string.
The public base URL ends in /transaction, but that proxy prefix is stripped before validation. Sign /api/v1/transactions, not /transaction/api/v1/transactions. Exclude the query string from the signed path.
METHOD
/api/v1/transactions
UNIX_SECONDS
UNIQUE_NONCE
SHA256_HEX_OF_RAW_BODYSafe retries and idempotency#
A fresh nonce is required even when retrying the same logical operation. Keep the same persisted Idempotency-Key and merchantReference for direct transaction creation. Duplicate create returns 409; it does not return the original 201 response. Reconcile the existing transaction before attempting another operation.
The hosted session endpoint does not provide idempotency. Avoid automatic retries that could create multiple sessions. The provided helper clients do not silently retry or follow redirects.
Keep credentials on the server#
Store keys in your server secret configuration. Do not embed them in JavaScript bundles, browser URLs, screenshots or support tickets. Replace exposed keys in the dashboard and update the server configuration.
The Developer Portal is public documentation. It does not request, store or execute with your API keys. Its request builder generates placeholders only.
