Authentication
Authenticate API requests with your business API key and identifiers, and understand live vs test keys.
ShadhinPay has two authentication schemes. Which one you use depends on the surface you're calling.
| Surface | Scheme | Used by |
|---|---|---|
| Integration API (payments, refunds, invoices) | API key | Your server-side code |
Dashboard API (/me/**, admin) | JWT bearer | The ShadhinPay dashboard itself |
If you're integrating ShadhinPay into your own product, you use API keys. The JWT scheme powers the dashboard UI and isn't part of the integration surface.
API keys
Create API keys in the dashboard under your business (see Businesses & providers). Keys come in two kinds:
- Live —
sk_live_…— moves real money. Requires an Active account. - Test —
sk_test_…— for the sandbox; no real money moves.
A key's full value is shown only once at creation. ShadhinPay stores only a hash plus the last four characters. If you lose it, rotate to get a new one.
Keep keys server-side
API keys are secrets. Never embed them in a browser, mobile app, or any client-side code. Make ShadhinPay calls from your backend only.
Required headers
Every call to the integration API includes three headers that identify the business and authenticate the request:
Client-Id: HM_4f8c2b1a
Business-Id: HB_71c4a09e
X-Api-Key: sk_live_aB3kC9...9xQ2| Header | What it is |
|---|---|
Client-Id | Your merchant (client) identifier |
Business-Id | The business the request applies to |
X-Api-Key | The secret API key for that business |
A full request looks like:
curl -X POST https://api.shadhinpay.pay/api/v1/payments \
-H "Client-Id: HM_4f8c2b1a" \
-H "Business-Id: HB_71c4a09e" \
-H "X-Api-Key: sk_live_aB3kC9...9xQ2" \
-H "X-Idempotency-Key: order-7831-attempt-1" \
-H "Content-Type: application/json" \
-d '{ "amount": "500.00", "currency": "BDT", "merchantTxnId": "order-7831", "callbackUrl": "https://shop.example.com/return" }'Live vs test
The environment is determined by the key and the base URL together:
- Use
sk_test_…againsthttps://sandbox.shadhinpay.payfor testing. - Use
sk_live_…againsthttps://api.shadhinpay.payfor production.
A test key can't be used to move real money, and a live key can't create sandbox payments — mismatches are rejected. See Testing.
Authentication errors
All authentication failures return 401 with a uniform errorType — the API
deliberately doesn't reveal which part was wrong, to avoid leaking information.
errorType | Meaning |
|---|---|
INVALID_API_KEY | The key is missing, wrong, revoked, or doesn't match the business |
AUTHENTICATION_ERROR | Credentials couldn't be verified |
SESSION_EXPIRED | (Dashboard/JWT) the session token is no longer valid |
See Errors for the complete catalogue.
Rotating and revoking keys
- Rotate a key to roll to a new secret with a 24-hour grace period — both the old and new key work during the overlap, so you can deploy without downtime. After the grace period the old key stops working.
- Revoke a key to kill it immediately if it's compromised.
Both actions are done in the dashboard and require two-factor authentication.