Accepting mobile money in Express

Install

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

npm install @ultraner/sdk

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

The Express trap

`express.json()` replaces the raw body before your handler sees it. Mount `express.raw()` on the webhook route only, leaving JSON parsing everywhere else.

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.

const { Ultraner } = require('@ultraner/sdk');
const { randomUUID } = require('node:crypto');

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

app.post('/pay', async (req, res) => {
  const payment = await ultraner.payments.createMnoCharge({
    amount: req.body.amount,       // whole shillings, TZS has no minor unit
    currency: 'TZS',
    provider: 'Vodacom',           // provider code, not brand name
    account_number: req.body.phone,
  }, { idempotencyKey: randomUUID() });

  res.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.

const crypto = require('node:crypto');

// Raw body for this route only; JSON everywhere else.
app.post('/webhooks/ultraner',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Ultraner-Signature');
    const expected = crypto
      .createHmac('sha256', process.env.ULTRANER_WEBHOOK_SECRET)
      .update(req.body)            // the Buffer, not JSON.stringify(...)
      .digest('hex');

    const valid = crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
    if (!valid) return res.status(400).end();

    const event = JSON.parse(req.body.toString());
    res.status(200).end();         // acknowledge first
    void handle(event);            // then do the work
  });