Integration Guide

ROHOPAY_API_KEY=live_xxx            # server-side only, never in the browser
ROHOPAY_WEBHOOK_SECRET=xxx          # from Dashboard → Webhooks
ROHOPAY_CALLBACK_URL=https://your-app.com/api/webhooks/rohopay

{ "success": true,  "data": { "...": "..." }, "message": "Payment request initiated" }
{ "success": false, "error": { "code": "INVALID_PHONE", "message": "…" } }

import crypto from "crypto";

const BASE = "https://api.rohopay.com";
const KEY = process.env.ROHOPAY_API_KEY!;
const SECRET = process.env.ROHOPAY_WEBHOOK_SECRET!;

async function call(path: string, init: RequestInit & { idempotencyKey?: string } = {}) {
  const { idempotencyKey, ...rest } = init;
  const res = await fetch(`${BASE}${path}`, {
    ...rest,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
    },
  });
  const json = await res.json().catch(() => ({}));
  return { ok: res.ok, status: res.status, data: json.data, error: json.error ?? json };
}

type Pay = {
  phone: string;       // 256XXXXXXXXX
  amount: number;      // whole units — no ×100
  currency: string;    // UGX | KES | TZS | RWF
  description: string;
  callback_url: string;
  idempotencyKey: string;
};

export const collect = ({ idempotencyKey, ...body }: Pay) =>
  call("/api/v1/collect", {
    method: "POST",
    idempotencyKey,
    body: JSON.stringify({ ...body, payment_method: "mobile_money" }),
  });

export const disburse = ({ idempotencyKey, ...body }: Pay) =>
  call("/api/v1/disburse", { method: "POST", idempotencyKey, body: JSON.stringify(body) });

export const getTransaction = (reference: string) =>
  call(`/api/v1/transactions/${encodeURIComponent(reference)}`);

/** Verify against the RAW body — never a re-serialised object. */
export function verifySignature(rawBody: string, header: string | null): boolean {
  if (!SECRET || !header) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

export function normalizeUgandaPhone(phone: string): string {
  let p = phone.trim().replace(/[\s-]/g, "");
  if (p.startsWith("+")) p = p.slice(1);
  if (p.startsWith("0")) p = "256" + p.slice(1);
  return p.startsWith("256") ? p : "256" + p;
}

// POST /api/deposits/mobile-money
const deposit = await db.deposit.create({ data: { userId, amount, status: "PENDING" } });

const res = await collect({
  phone: normalizeUgandaPhone(phoneNumber),
  amount,                         // whole UGX
  currency: "UGX",
  description: `Deposit ${deposit.id}`,
  callback_url: process.env.ROHOPAY_CALLBACK_URL!,
  idempotencyKey: `collect:${deposit.id}`,   // stable per business event
});

if (!res.ok || !res.data?.reference) {
  await db.deposit.update({ where: { id: deposit.id }, data: { status: "FAILED" } });
  return Response.json({ error: res.error?.message ?? "Could not start payment" }, { status: 502 });
}

await db.deposit.update({
  where: { id: deposit.id },
  data: { rohopayReference: res.data.reference },
});
return Response.json({ status: "PENDING", message: "Approve the prompt on your phone." });

{
  "status": "pending",
  "amount": 20000,          // requested
  "wallet_debit": 20000,    // what your wallet was charged
  "recipient_amount": 19100 // what the phone receives (amount − fee)
}

{
  "event": "deposit.successful",
  "transaction_id": "01j2k3m4n5p6q7r8s9t0uvwx",
  "reference": "ref_abc123",
  "status": "successful",
  "amount": 50000,
  "currency": "UGX",
  "type": "collection",
  "environment": "live",
  "provider": "rohopay",
  "timestamp": "2026-07-15T08:31:47Z"
}

// POST /api/webhooks/rohopay
export async function POST(req: Request) {
  const raw = await req.text();                                   // raw bytes
  if (!verifySignature(raw, req.headers.get("x-rohopay-signature"))) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }

  const { type, status, reference } = JSON.parse(raw);
  if (!reference || (status !== "successful" && status !== "failed")) {
    return Response.json({ received: true });                     // not actionable
  }

  if (type === "collection") {
    const dep = await db.deposit.findFirst({ where: { rohopayReference: reference } });
    if (dep && dep.status === "PENDING") {                        // exactly-once guard
      await db.$transaction(async (tx) => {
        if (status === "successful") {
          await tx.deposit.update({ where: { id: dep.id }, data: { status: "APPROVED" } });
          await tx.wallet.update({ where: { userId: dep.userId }, data: { balance: { increment: dep.amount } } });
        } else {
          await tx.deposit.update({ where: { id: dep.id }, data: { status: "REJECTED" } });
        }
      });
    }
  }

  if (type === "disbursement") {
    const wd = await db.withdrawal.findFirst({ where: { rohopayReference: reference } });
    if (wd && (wd.status === "PENDING" || wd.status === "PROCESSING")) {
      await db.$transaction(async (tx) => {
        if (status === "successful") {
          await tx.withdrawal.update({ where: { id: wd.id }, data: { status: "COMPLETED" } });
        } else {                                                  // failed → give the money back
          await tx.withdrawal.update({ where: { id: wd.id }, data: { status: "REJECTED" } });
          await tx.wallet.update({ where: { userId: wd.userId }, data: { balance: { increment: wd.amount } } });
        }
      });
    }
  }

  return Response.json({ received: true });
}

const stuck = await db.deposit.findMany({
  where: { status: "PENDING", createdAt: { lt: new Date(Date.now() - 5 * 60_000) } },
});
for (const dep of stuck) {
  const { data } = await getTransaction(dep.rohopayReference);
  if (data?.status === "successful" || data?.status === "failed") {
    await applyTerminalStatus(dep, data.status);   // same function the webhook uses
  }
}