SwapnoPay Console

scienceProduction Payment Flow Sandbox

Zero mocks: Dispatches real REST orders, simulates genuine carrier SMS parsing, and delivers signed HMAC webhooks with live round-trip latency.

1. Zero-SDK Production Architecture

SwapnoPay is intentionally engineered around Direct HTTP REST APIs + Standard Webhooks + Hosted Checkout. You do not need to install or maintain any third-party NPM, Composer, PyPI, or Go SDK packages, nor any CMS plugin.

• Order Creation: Your backend sends a standard POST JSON request over HTTPS to register a pending order intent (amount, tran_id, cus_phone, callback_url).
• Customer Checkout: Redirect the customer or embed widget.html?merchant_id=...&amount=...&order_id=... inside an <iframe>.
• Android SIM Bridge: Your dedicated Android phone running the SwapnoPay Merchant App receives the carrier SMS from bKash (16247), Nagad (16167), Rocket (16216), or Upay (16268) and forwards it to POST /v1/payment/verify.
• Instant Settlement & Webhook: The gateway atomically verifies the TrxID and amount, emits a real-time Socket.io event to the checkout widget, and dispatches a signed HMAC-SHA256 webhook to your server.

2. API Authentication & Key Isolation

All server-to-server REST calls must authenticate using your sk_live_... (or sk_sandbox_...) Secret API Key via either header:

Authorization: Bearer sk_live_your_secret_api_key
x-api-key: sk_live_your_secret_api_key
Content-Type: application/json

Security Rule: Never expose your sk_live_... Secret Key or whsec_... Webhook Secret in client-side browser JavaScript or mobile app bundles. Only pass merchant_id and order_id to the public Checkout Widget.

3. Production REST API Endpoints Reference

4. Webhook HMAC-SHA256 Verification & Idempotency

Every outbound webhook POST request includes the X-SwapnoPay-Signature header in the format t=<unix_timestamp>,v1=<hex_hmac_sha256>. The signature is computed over ${timestamp}.${rawRequestBody} using your Webhook Secret:

// Standard Node.js Express Webhook Verification (Zero SDK)
const crypto = require('node:crypto');

app.post('/api/swapnopay/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sigHeader = req.headers['x-swapnopay-signature'] || '';
  const parts = Object.fromEntries(sigHeader.split(',').map(p => p.split('=')));
  if (!parts.t || !parts.v1) return res.status(400).send('Malformed signature header');

  // 1. Replay Attack Protection: Reject webhooks older than 5 minutes (300s)
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) > 300) {
    return res.status(401).send('Webhook timestamp expired');
  }

  // 2. Compute HMAC-SHA256 over "${timestamp}.${rawBody}"
  const rawBody = req.body.toString('utf8');
  const expected = crypto
    .createHmac('sha256', process.env.SWAPNOPAY_WEBHOOK_SECRET)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))) {
    return res.status(401).send('Invalid HMAC signature');
  }

  const event = JSON.parse(rawBody);
  // 3. Enforce idempotency using event.trx_id & event.order_id before fulfilling order
  res.status(200).json({ received: true });
});

5. Android SIM Bridge & Production Go-Live Checklist

1. Dedicated Android Device: Install the SwapnoPay Merchant App on an Android phone containing your active bKash/Nagad/Rocket/Upay SIM cards.
2. OS Background Permissions: Grant RECEIVE_SMS, READ_SMS, and POST_NOTIFICATIONS permissions, and set Battery Usage to Unrestricted so the foreground socket & WorkManager queue never sleep.
3. HTTPS Webhook Endpoint: Configure a public TLS (https://) callback URL in the Dashboard and verify it returns HTTP 200 within 5 seconds.
4. Idempotent Fulfillment: Store trx_id with a UNIQUE database constraint in your application database so replayed webhooks never double-credit a customer.
5. Switch Environment to Live: Replace sk_sandbox_... with your live sk_live_... key and verify device online status via GET /v1/payment/device-status.