Webhooks

Get a server-to-server notification the moment a payment settles.

Webhooks are how you reliably learn a payment’s outcome. Pass a webhook_url when you create a payment and Pesarc will POST a JSON event to it as the payment progresses.

Receiving events

// POST /api/pesarc/webhook
export async function POST(req: Request) {
  const payload = await req.text();          // read the RAW body for verification
  const signature = req.headers.get("pesarc-signature") ?? "";

  if (!verify(payload, signature, process.env.PESARC_WEBHOOK_SECRET!)) {
    return new Response("bad signature", { status: 400 });
  }

  const event = JSON.parse(payload);
  switch (event.type) {
    case "payment.settled":
      await fulfil(event.data.reference);
      break;
    case "payment.expired":
    case "payment.failed":
      await cancel(event.data.reference);
      break;
  }
  return new Response("ok");
}

Event shape

{
  "type": "payment.settled",
  "data": {
    "id": "pay_...",
    "reference": "order_1042",
    "amount": 50000,
    "currency": "NGN",
    "status": "settled",
    "metadata": { "orderId": "order_1042" }
  }
}

Rules of thumb

Verify the signature against the raw request body before trusting an event.

Treat delivery as at-least-once — make your handler idempotent on data.id.

Respond 2xx quickly; do slow work asynchronously so Pesarc doesn’t retry.

Reconcile with GET /checkout/:id if you ever miss an event.

The signature header name and scheme are configured with your webhook secret in the Developers screen. If you haven’t set a webhook secret yet, do that before relying on webhooks in production.