API Keys

Overview

API keys authenticate merchant server-side integrations. They are scoped to one merchant and one environment. Sandbox keys create sandbox payment intents and manage sandbox webhooks. Live keys create live payment intents and manage live webhooks.

Merchant API authentication uses X-Api-Key.

X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

Dashboard-only routes use a logged-in dashboard JWT session. Do not use dashboard JWTs for merchant backend integrations.

Step-by-step guide

1. Open Dashboard -> API Keys.
2. Create a sandbox key for development.
3. Store the key in your backend environment variables.
4. Use the key in the X-Api-Key header.
5. Create a separate live key for production.
6. Rotate keys if a key is exposed or a developer leaves your team.

Code example

const gateway = {
  baseUrl: "https://api.smspaybd.com",
  apiKey: process.env.SMS_PAY_SANDBOX_KEY!,
};

async function gatewayFetch(path: string, init: RequestInit = {}) {
  return fetch(`${gateway.baseUrl}${path}`, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": gateway.apiKey,
      ...init.headers,
    },
  });
}

Request and response samples

GET /v1/payments/intents?limit=10
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

{
  "data": [
    {
      "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
      "environment": "SANDBOX",
      "amount": "500",
      "currency": "BDT",
      "status": "PENDING",
      "merchantReference": "ORDER-10045",
      "receiverMsisdn": "01700000001",
      "checkoutUrl": "https://smspaybd.com/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e",
      "expiresAt": "2026-05-05T10:05:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

Endpoint authentication matrix

Edge cases and constraints

• Never expose API keys in browser JavaScript.
• Never paste live keys into sandbox tools.
• Do not send an environment field; the server derives environment from the key.
• Use a different key for sandbox and live deployments.
• Revoke old keys after rotation.
• API keys are not OAuth bearer tokens in the current API. Use X-Api-Key.