API Keys and Authentication
Authenticate server-side merchant API requests with API keys.
Use API keys for server-to-server merchant API calls. Keep keys on your backend only. Do not place them in browser JavaScript, mobile apps, checkout pages, or client-side widget configuration.
Base URL
https://api.stafiel.com
Request Headers
Every API key request must include the authentication and client-mode headers.
Requests with JSON bodies must also include Content-Type: application/json.
| Header | Required | Default | Description |
|---|---|---|---|
X-API-Key |
Yes | None | Merchant API key created in the Merchant Dashboard. Keep this value server-side only. |
X-App-Client |
Yes | None | Request mode identifier. Use merchant-client for live API keys. |
Content-Type |
Required for requests with a body | None | Use application/json when sending a JSON request body, such as checkout session creation. |
Live API keys must use X-App-Client: merchant-client. Test API keys must use
X-App-Client: merchant-client-testnet. If the key mode and header mode do not
match, Stafiel returns 401 AUTH_FAILED.
Header Example
X-API-Key: mk_live_your_api_key
X-App-Client: merchant-client
Content-Type: application/json
Merchant ID
Most order endpoints require merchantId. The value must match the merchant
bound to the API key. Requests for another merchant are rejected.
Rate Limits
API key requests are rate limited. Limits may vary by endpoint, merchant, request mode, plan, traffic pattern, and operational risk controls.
When a request is rate limited, the API returns 429 RATE_LIMIT_EXCEEDED.
If the response includes Retry-After or rate-limit reset headers, wait for the
indicated time before retrying.
Design your integration to retry with backoff, avoid tight polling loops, and reuse idempotency keys when retrying checkout session creation.
Key Management
Create, rotate, and revoke API keys from the Merchant Dashboard. Store API keys in a secret manager or server environment variable. Rotate a key immediately if it may have been exposed.