Esaalat server SDK for Node.js

Install

npm install esaalat

Create the session

import { createEsaalatServer } from "esaalat/server";

// Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
const esaalat = createEsaalatServer();

// Your server fixes the amount; the browser only ever receives the token.
const session = await esaalat.sessions.create({
  orderId: "order-12345",
  amount: 5000, // whole riyals, as a number or a string
});

// session.session_token → open the checkout from your page
// session.portal_url    → or redirect the buyer straight to it

Verify the webhook

// Keep the raw body: a parsed-and-restringified object will not match.
app.post(
  "/esaalat/webhooks",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const { payload } = await esaalat.webhooks.verify(
        req.body,
        req.header("X-Esaalat-Signature") ?? ""
      );

      if (payload.event === "payment.verified") {
        releaseOrder(payload.order_id); // idempotent on intent_id
      }
      res.sendStatus(200);
    } catch {
      res.sendStatus(400); // anything but 2xx schedules a retry
    }
  }
);

What it handles for you

• •Token cached — One token per process, refreshed from the JWT's own exp a minute early, so an integration does not start returning 401s at the hour boundary.
• •Idempotency automatic — One key per create call, reused on every retry: a 429 or a timeout cannot create the same order twice.
• •Retries — 429, 5xx and network failures, honouring Retry-After.
• •Typed errors — Every failure carries a code, the HTTP status, the offending field and the API's per-field errors.
• •Server-only — Only the session token reaches the browser. The client secret stays on your server, where it belongs.

Configuration

Before you go live

• •The client throws if a window exists, so a bundler cannot ship it to a page.
• •Amounts are whole Yemeni riyals; a fraction is refused before the request leaves your process.
• •One package, two entries: esaalat for the browser, esaalat/server for this.