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. Verify Android SMS Agent signatures.
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": "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 SMS Agent security

The Android SMS Agent sends:

X-Api-Key: sk_live_xxxxxxxxxxxxxxxxx
X-Signature: sha256=<hmac-of-raw-body>

The server validates both the API key and signature before storing the SMS event.

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.