Integration docs

You're helping me integrate mbpay (a Bangladeshi MFS payment gateway: bKash, Nagad, Rocket, Upay, Tap) into my Next.js App Router project. mbpay confirms payments by matching customer-submitted transaction IDs against SMS received on the merchant's Android device, then fires a signed webhook to my server.

Use the published npm package `mbpay`. API base URL: http://localhost:4000

Do these in order:

1. Install the SDK:
   ```
   npm install mbpay
   ```

2. Add these env vars to my `.env.local` (template values — I'll fill in real ones from /dashboard/brands):
   ```
   MBPAY_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   MBPAY_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   MBPAY_HMAC_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   MBPAY_API_BASE_URL=http://localhost:4000
   ```

3. Create `lib/mbpay.ts` exporting a single shared client:
   ```ts
   import { Mbpay } from 'mbpay';
   export const mbpay = new Mbpay({
     publicKey: process.env.MBPAY_PUBLIC_KEY!,
     secretKey: process.env.MBPAY_SECRET_KEY!,
     hmacSecret: process.env.MBPAY_HMAC_SECRET!,
     apiBaseUrl: process.env.MBPAY_API_BASE_URL,
   });
   ```

4. Create the deposit page at `app/deposit/page.tsx` (server component):
   - Calls `mbpay.getPaymentOptions()` to list active providers.
   - Renders one button per (provider, channel) pair showing `channel_label` + the wallet phone number.
   - Has an amount input.
   - On submit, calls a server action (`app/deposit/actions.ts`) that runs `mbpay.initiatePayment({ mfsAccountId: <picked wallet.id>, amount, endUserRef: <orderId>, successUrl, failUrl })` and redirects to `payment.checkout_url`.

5. Create the webhook receiver at `app/api/mbpay-webhook/route.ts`:
   - POST handler.
   - Reads raw body with `const rawBody = await req.text();` — CRITICAL: do NOT use `req.json()` because the HMAC is computed over the exact bytes.
   - Calls `mbpay.verifyWebhook(rawBody, req.headers.get('x-mbpay-signature'))`.
   - On valid signature, parses JSON: `const event = JSON.parse(rawBody) as import('mbpay').WebhookPayload;`
   - Calls a `creditOrderIdempotent(event.end_user_ref, event.amount, event.id)` helper — implement it to update my orders table, deduplicating on `event.id` (mbpay retries up to 10×).
   - Returns `new Response('ok', { status: 200 })` on success, `new Response('bad signature', { status: 401 })` on verify failure.

6. After this works locally, I'll deploy and set my public webhook URL in the mbpay dashboard at /dashboard/brands → Webhook URL.

Constraints:
- All mbpay calls happen server-side. NEVER expose secretKey or hmacSecret to the browser.
- Send amount with 2 decimals (500.00, not 500) — the matcher compares against the SMS body byte-for-byte.
- The webhook handler MUST be idempotent — dedupe on `event.id` or you'll double-credit.
- Match the existing TypeScript style, file structure, and lint rules of this project.
- Don't ask clarifying questions — read the existing codebase to figure out conventions.

// app/api/mbpay-webhook/route.ts  (Next.js App Router)
import type { NextRequest } from 'next/server';
import type { WebhookPayload } from 'mbpay';
import { mbpay } from '@/lib/mbpay';
import { creditOrderIdempotent } from '@/lib/orders';

export async function POST(req: NextRequest): Promise<Response> {
  // CRITICAL: capture the raw bytes — the signature is computed over them.
  const rawBody = await req.text();
  const sig     = req.headers.get('x-mbpay-signature');

  if (!mbpay.verifyWebhook(rawBody, sig)) {
    return new Response('bad signature', { status: 401 });
  }

  const event = JSON.parse(rawBody) as WebhookPayload;
  // event.status === 'matched'
  // event.end_user_ref is YOUR reference (the orderId you sent in initiatePayment)
  // event.txn_id is the bKash/Nagad TrxID the user submitted
  //
  // Idempotency: mbpay retries up to 10 times with exponential backoff.
  // Your handler MUST tolerate duplicates — dedupe on event.id.
  await creditOrderIdempotent(event.end_user_ref, event.amount, event.id);

  // Return 200 within 10s to mark delivery successful.
  return new Response('ok', { status: 200 });
}

// Manual signing — only if you can't or don't want to use the SDK.
// Sign EVERY /api/v1/* request with three headers.
import { createHmac } from 'node:crypto';

const PUBLIC_KEY  = process.env.MBPAY_PUBLIC_KEY!;
const SECRET_KEY  = process.env.MBPAY_SECRET_KEY!;
const API_BASE    = 'http://localhost:4000';

export async function mbpayFetch(path: string, body?: unknown) {
  const payload = body === undefined ? '' : JSON.stringify(body);
  const ts      = Math.floor(Date.now() / 1000).toString();
  const sig     = createHmac('sha256', SECRET_KEY)
    .update(`${ts}.${payload}`)
    .digest('hex');

  const res = await fetch(`${API_BASE}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: {
      'x-brand-key': PUBLIC_KEY,
      'x-timestamp': ts,
      'x-signature': sig,
      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
    },
    body: body === undefined ? undefined : payload,
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`mbpay ${res.status}: ${err}`);
  }
  return res.json();
}