Concepts
Authentication
Use API keys for merchant integrations
Reference
Merchant integrations authenticate with an API key in the X-API-Key header. Dashboard login, MFA, password reset, and checkout token endpoints are first-party UI flows and are not part of the public merchant API.
| Key type | Environment | Use |
|---|---|---|
sk_test_... | test | Sandbox development |
sk_live_... | live | Production payments |
Usage
Use the same key on every server-side request.
curl https://api.halfin.xyz/api/v1/invoices \
-H "X-API-Key: $HALFIN_API_KEY"import { createHalfin, listInvoices } from '@halfin/sdk-merchant';
const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY });
const { data } = await listInvoices({ client });# Python SDK coming soon. Use the cURL example for now.Pitfalls
- Do not call login or MFA endpoints from a merchant integration.
- Do not expose live keys in frontend code.
- Do not reuse a live key in sandbox tests.
Troubleshooting
401 unauthorized means the key is missing, malformed, revoked, or from the wrong environment.
403 forbidden means the key is valid but does not have the permission required by the endpoint.