Security Best Practices

Overview

Payment security depends on protecting API keys, verifying webhook signatures, preventing replay attacks, isolating sandbox/live environments, and keeping fulfillment idempotent.

Step-by-step guide

1. Store API keys only in backend or device configuration.
2. Never expose API keys in browser JavaScript.
3. Use separate sandbox and live keys.
4. Install the Android app only from the SMS Pay dashboard or docs link.
5. Verify webhook signatures against the raw request body.
6. Reject old or replayed webhook deliveries when possible.
7. Fulfill only once per payment intent.
8. Rotate secrets after exposure or team changes.

API key handling

Good:

SMS_PAY_LIVE_KEY=sk_live_xxxxxxxxxxxxxxxxx

Bad:

<script>
  window.SMS_PAY_KEY = "sk_live_xxxxxxxxxxxxxxxxx";
</script>

Webhook signature verification

import crypto from "node:crypto";

export function verifyWebhook(rawBody: Buffer, signature: string, secret: string) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const left = Buffer.from(signature);
  const right = Buffer.from(expected);

  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

Request and response samples

Signed webhook request:

POST /webhooks/sms-pay
X-Webhook-Id: delivery_123
X-Webhook-Event: payment.paid
X-Webhook-Signature: sha256=<hex>
X-Webhook-Timestamp: 2026-05-05T10:01:00.000Z
Content-Type: application/json

{
  "event": "payment.paid",
  "environment": "LIVE",
  "timestamp": "2026-05-05T10:01:00.000Z",
  "data": {
    "payment_intent_id": "pi_live_123",
    "amount": "500",
    "currency": "BDT",
    "customer_reference": "SP7A91BC2D0",
    "merchant_reference": "ORDER-10045"
  }
}

Expected response:

HTTP/1.1 200 OK

Replay protection

Recommended controls:

• Store every X-Webhook-Id you process.
• Ignore duplicate webhook IDs.
• Check X-Webhook-Timestamp and reject very old requests when your infrastructure allows.
• Store fulfillment by payment intent ID so payment.paid cannot ship twice.

Android app security

Install the SMS Pay Android app only from the official SMS Pay download link. The app is not on the Play Store yet.

Use a trusted merchant phone, allow SMS permission only for the SMS Pay app, and keep the device online. If the device is lost or replaced, disable the old device from the dashboard before connecting a new one.

Edge cases and constraints

• Treat all browser input as untrusted, including checkout transaction IDs.
• Never mark an order paid from the customer’s screen alone.
• Do not share live keys with support users.
• Use HTTPS webhook URLs only.
• Keep sandbox and live credentials in separate deployment variables.
• Rotate webhook secrets if endpoint code or logs exposed them.