Accepting mobile money in Next.js

Install

Next.js is served by the Node and TypeScript client. There is no Next.js-specific package, and this page does not pretend otherwise: what is below is that client, used the way Next.js is written.

npm install @ultraner/sdk

This client is driven against the live sandbox in CI on every push.

The Next.js trap

In a Route Handler, `await req.json()` consumes the body and re-serialising it will never reproduce the bytes that were signed. Use `await req.text()` for the webhook, then parse after verifying.

Taking a payment

Two things this shows that are easy to get wrong anywhere. The amount is in whole units for most African currencies, so 5000 TZS is five thousand shillings and not fifty. And provideris the network's provider code, not its brand name: Mixx by Yas is still Tigo on the wire.

// app/api/pay/route.ts  —  a Route Handler, so the key stays server-side.
import { Ultraner } from '@ultraner/sdk';
import { randomUUID } from 'node:crypto';

const ultraner = new Ultraner(process.env.ULTRANER_API_KEY!);

export async function POST(req: Request) {
  const { phone, amount } = await req.json();

  const payment = await ultraner.payments.createMnoCharge({
    amount,                        // whole shillings: TZS has no minor unit
    currency: 'TZS',
    provider: 'Vodacom',           // the provider code, not the brand name
    account_number: phone,         // full international form, no plus
  }, { idempotencyKey: randomUUID() });

  // The prompt is on its way to the handset. Nothing has been paid yet.
  return Response.json({ reference: payment.reference, status: payment.status });
}

The response means the request was accepted, not that money moved. A mobile-money charge sends a prompt to the payer's handset and they may take a minute, or never answer. Which is why the next section is not optional.

Receiving the result

The webhook is how you learn a payment succeeded. Verify the signature over the raw bytes before trusting anything in the payload, acknowledge quickly, and do the work afterwards: a slow handler gets retried, and retries mean you will see the same event twice.

// app/api/webhooks/ultraner/route.ts
import crypto from 'node:crypto';

export async function POST(req: Request) {
  // Raw text, not .json(). Re-serialising changes key order and whitespace,
  // and the signature will never match.
  const raw = await req.text();
  const signature = req.headers.get('X-Ultraner-Signature') ?? '';

  const expected = crypto
    .createHmac('sha256', process.env.ULTRANER_WEBHOOK_SECRET!)
    .update(raw)
    .digest('hex');

  // Constant-time: a plain === leaks the signature one byte at a time.
  const valid = signature.length === expected.length && crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
  if (!valid) return new Response('bad signature', { status: 400 });

  const event = JSON.parse(raw);
  // Acknowledge fast. Slow handlers get retried, and retries mean you will
  // see the same event id twice, so key your work on it.
  void handle(event);
  return new Response(null, { status: 200 });
}