Sample code

// ussd.js — a Sendexa USSD backend in Node.js (Express).
//
//   npm install express
//   SENDEXA_SIGNING_KEY=ussd_your_key node ussd.js
//
// Edit menu.json for your screens and the `actions` below for your data.
const crypto = require("crypto");
const express = require("express");
const menu = require("./menu.json");

const SIGNING_KEY = process.env.SENDEXA_SIGNING_KEY; // Dashboard → USSD → Codes → Backend & signing key
const PORT = process.env.PORT || 3000;

// ── Your business logic ───────────────────────────────────────────────────
// Each action receives the session's values ({ phone, ...what they typed })
// and returns values to show on the screen, or { goto: "screen" } to jump.
const actions = {
  async trackOrder({ orderId }) {
    const order = await findOrder(orderId);
    if (!order) return { goto: "not_found" };
    return { status: order.status };
  },

  async quoteOrder({ orderId }) {
    const order = await findOrder(orderId);
    if (!order) return { goto: "not_found" };
    return { amount: order.amount.toFixed(2) };
  },

  async requestPayment({ orderId, amount, phone }) {
    // Start the MoMo charge here (Paystack, Hubtel, your bank…), but don't
    // wait for the customer to approve it: replies must arrive within 8s.
    console.log(`Charge ${phone} GHS ${amount} for order ${orderId}`);
    return {};
  },
};

// Demo data so the sample runs as-is. Replace with your database.
const ORDERS = {
  1042: { status: "out for delivery", amount: 120 },
  1043: { status: "being packed", amount: 45.5 },
};
async function findOrder(id) {
  return ORDERS[id] ?? null;
}

// ── Menu engine (no changes needed below) ─────────────────────────────────
// Sessions live in memory. Running more than one server? Use Redis instead.
const sessions = new Map();
const SESSION_TTL_MS = 5 * 60 * 1000;

const fill = (text, vars) => text.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? "");

async function show(session, name, notice) {
  const screen = menu.screens[name];
  if (!screen) throw new Error(`menu.json has no screen "${name}"`);

  if (screen.action) {
    const action = actions[screen.action];
    if (!action) throw new Error(`No action "${screen.action}" in ussd.js`);
    const { goto, ...values } = (await action(session.vars)) ?? {};
    Object.assign(session.vars, values);
    if (goto) return show(session, goto);
  }

  const text = (notice ? `${notice}\n` : "") + fill(screen.text, session.vars);
  if (screen.end) {
    sessions.delete(session.id);
    return { ussdString: text, end: true };
  }
  session.screen = name;
  session.at = Date.now();
  sessions.set(session.id, session);
  return { ussdString: text, end: false };
}

async function handle({ sessionId, msisdn, action, userInput, ussdString }) {
  let session = sessions.get(sessionId);
  if (session && Date.now() - session.at > SESSION_TTL_MS) session = undefined;

  // A new dial (or a session we no longer have): show the first screen.
  if (action === "start" || !session) {
    session = { id: sessionId, screen: menu.start, vars: { phone: msisdn }, history: [] };
    return show(session, menu.start);
  }

  const screen = menu.screens[session.screen];
  const input = String(userInput ?? ussdString ?? "").trim();

  if (screen.options) {
    const target = screen.options[input];
    if (!target) return show(session, session.screen, "Invalid choice.");
    if (target === "back") return show(session, session.history.pop() ?? menu.start);
    session.history.push(session.screen);
    return show(session, target);
  }

  if (screen.input) {
    if (screen.pattern && !new RegExp(screen.pattern).test(input)) {
      return show(session, session.screen, screen.error ?? "That doesn't look right.");
    }
    session.vars[screen.input] = input;
    session.history.push(session.screen);
    return show(session, screen.next);
  }

  return show(session, menu.start);
}

// X-Sendexa-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
function signatureIsValid(rawBody, header) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!SIGNING_KEY || !match) return false;
  const [, t, v1] = match;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", SIGNING_KEY).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

const app = express();
app.use(express.json({ verify: (req, _res, buf) => (req.rawBody = buf.toString("utf8")) }));

app.post("/ussd", async (req, res) => {
  if (!signatureIsValid(req.rawBody, req.get("x-sendexa-signature"))) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  try {
    res.json(await handle(req.body));
  } catch (error) {
    console.error(error);
    res.json({ ussdString: "Sorry, something went wrong. Please dial again.", end: true });
  }
});

app.listen(PORT, () => console.log(`USSD backend listening on :${PORT}/ussd`));

#!/usr/bin/env bash
# test-ussd.sh — dial your USSD backend like Sendexa does, signed and all.
#
#   SENDEXA_SIGNING_KEY=ussd_your_key ./test-ussd.sh http://localhost:3000/ussd 1 1042
#
# Everything after the URL is what the dialer types, one screen at a time.
URL="${1:-http://localhost:3000/ussd}"
shift
KEY="${SENDEXA_SIGNING_KEY:?Set SENDEXA_SIGNING_KEY to the signing key of your code}"
PHONE="${PHONE:-233244000000}"
SESSION="test-$(date +%s)"

send() {
  local body t sig
  if [ -z "$1" ]; then
    body=$(printf '{"sessionId":"%s","msisdn":"%s","ussdString":"","messageType":"0","action":"start","ussdCode":"144","fullCode":"*889*144#"}' "$SESSION" "$PHONE")
  else
    body=$(printf '{"sessionId":"%s","msisdn":"%s","ussdString":"%s","messageType":"0","action":"continue","userInput":"%s","ussdCode":"144","fullCode":"*889*144#"}' "$SESSION" "$PHONE" "$1" "$1")
  fi
  t=$(date +%s)
  sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$KEY" | sed 's/^.*= //')
  curl -s "$URL" -H "Content-Type: application/json" -H "X-Sendexa-Signature: t=$t,v1=$sig" -d "$body"
  echo
}

echo "> (dial)"
send ""
for input in "$@"; do
  echo "> $input"
  send "$input"
done