Developer guide

// server.js — Node.js / Express (ESM)
import express from "express";
import crypto  from "node:crypto";

const app = express();

// Capture raw bytes before JSON parsing — required for HMAC verification
app.use(express.json({
  verify: (_req, _res, buf) => { _req.rawBody = buf; },
}));

const VEGAPAY_API    = "https://vegapay.ng/api"; // dev: https://dev.vegapay.ng/api
const VEGAPAY_KEY    = process.env.VEGAPAY_API_KEY;
const WEBHOOK_SECRET = process.env.VEGAPAY_WEBHOOK_SECRET;

// ── 1. Create a checkout when a buyer places an order ─────────────────────
app.post("/orders/:orderId/checkout", async (req, res) => {
  const { orderId }     = req.params;
  const { amountKobo } = req.body; // integer kobo from your cart

  const r = await fetch(`${VEGAPAY_API}/checkout`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${VEGAPAY_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amountKobo,
      reference:  orderId,                               // your unique order id
      returnUrl:  `https://shop.example/orders/${orderId}`,
      webhookUrl: "https://shop.example/webhooks/vegapay",
    }),
  });

  if (!r.ok) return res.status(502).json({ error: "checkout_failed" });
  const { data } = await r.json();

  await db.orders.update(orderId, {
    vegaCheckoutId: data.checkoutId,
    status:         "awaiting_payment",
  });

  // Return the URL — the client redirects the customer there to pay
  res.json({ checkoutUrl: data.checkoutUrl });
});

// ── 2. Receive the signed webhook when VegaPay matches the transfer ────────
app.post("/webhooks/vegapay", async (req, res) => {
  const sig   = req.headers["x-vegapay-signature"] ?? "";
  const evtId = req.headers["x-vegapay-event"]    ?? "";

  if (!verifyWebhook(req.rawBody, sig, WEBHOOK_SECRET))
    return res.status(401).send("invalid signature");

  const { type, reference } = req.body;

  if (type === "payment.matched") {
    // Guard against duplicate delivery — idempotency on the event id
    const seen = await db.fulfillments.has(evtId);
    if (!seen) {
      await db.orders.update(reference, { status: "paid" });
      await fulfillOrder(reference);
      await db.fulfillments.insert(evtId);
    }
  }

  res.sendStatus(200); // always acknowledge promptly
});

// ── Signature helper ──────────────────────────────────────────────────────
function verifyWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)  // exact received bytes
    .digest("hex");
  const got = Buffer.from(parts.v1 ?? "", "hex");
  const exp = Buffer.from(expected, "hex");
  return fresh && got.length === exp.length && crypto.timingSafeEqual(got, exp);
}

app.listen(3001);

// client.js — redirect customer to the VegaPay checkout
async function startPayment(orderId, amountKobo) {
  const res = await fetch(`/orders/${orderId}/checkout`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ amountKobo }),
  });
  const { checkoutUrl } = await res.json();
  window.location.href = checkoutUrl; // customer pays, then returns via returnUrl
}

// ── On your returnUrl page  (/orders/:id?status=matched) ──────────────────
// ?status is a UX hint only — trust the signed webhook for fulfilment,
// not the redirect (a browser tab could be closed before returning).
const status = new URLSearchParams(window.location.search).get("status");
if (status === "matched") showSuccess();
else                       showPending(); // webhook may arrive seconds later