Hosted checkout in the browser

TypeScript for web storefronts. Open the hosted portal in a browser window or an in-page modal.

esaalat· TypeScript

On this page

Install Quick start Options Result Errors Fulfilment

Install

Install the package from npm.

npm install esaalat

No runtime dependencies. The package includes ESM, CommonJS, TypeScript types and an IIFE build.

Quick start

Create the client, then call open() from the buyer's click handler.

1import { EsaalatCheckout } from "esaalat";
2
3const checkout = new EsaalatCheckout({
4  publishableKey: "pk_live_...",
5  locale: "ar",
6});
7
8button.addEventListener("click", async () => {
9  const result = await checkout.open({
10    amount: "5000.00",
11    currency: "YER",
12    externalOrderId: "order-123",
13  });
14
15  if (result.status === "VERIFIED") {
16    // Show success; fulfil only after payment.verified.
17  }
18});

The default is a browser window. Use presentation: 'modal' for an iframe, or as the fallback when the popup is blocked.

Options

Constructor and open() options. Amounts are decimal strings.

Option	Type	Required	Description
`publishableKey`	`string`	Required	Dashboard → API Keys. Safe to embed; it can only create checkout sessions.
`locale`	`"ar" \| "en"`	Optional	Portal language. Defaults to `ar`; `open({ locale })` overrides it for one checkout.
`presentation`	`"window" \| "modal"`	Optional	Defaults to `window`. `modal` embeds the portal in an iframe and is also used when a popup is blocked.
`apiBaseUrl`	`string`	Optional	API root. Defaults to `https://api.esaalat.com/api/v1`.
`portalBaseUrl`	`string`	Optional	Fallback portal origin when the API response has no `portal_url`. Defaults to `https://pay.esaalat.com`.
`amount`	`string`	Optional	Order total, for example `"5000.00"`. Required unless `items` or `sessionToken` is supplied.
`items`	`array`	Optional	Order lines with `name`, `price`, optional `description` and `quantity`. When sent, the server ignores `amount`.
`externalOrderId`	`string`	Optional	Your order reference. Returned in the result and in the `payment.verified` webhook as `order_id`.
`sessionToken`	`string`	Optional	Open a session created by your server instead of creating one in the browser. Takes precedence over `amount` and `items`.
`portalUrl`	`string`	Optional	Portal URL for a server-created session. Optional; the SDK builds one from `portalBaseUrl` when omitted.
`idempotencyKey`	`string`	Optional	UUID v4 retry key. Reuse it when retrying a create; generated per call when omitted.
`simulateResult`	`string`	Optional	Demo outcome: `VERIFIED`, `UNDERPAID`, `OVERPAID`, `CANCELLED` or `EXPIRED`. Refused unless the key allows simulation.

Result

A checkout ends with one of these statuses.

Full JSON reply

{
  "status": "VERIFIED",
  "reason": null,
  "sessionToken": "640c912d-3ffe-4703-b951-52970c693c41",
  "intentCode": "ZR269MP",
  "amount": "5000.00",
  "paidAmount": null,
  "currency": "YER",
  "externalOrderId": "order-123",
  "merchantName": "Esaalat Store"
}

Status	Meaning
`VERIFIED`	The payment matched the order and the amount was verified.
`WRONG_AMOUNT`	The payment matched the order, but the amount differs. Read `paidAmount` to see what arrived.
`EXPIRED`	The buyer did not finish before the payment window closed.
`CANCELLED`	The buyer closed the checkout, or the intent was cancelled.
`FAILED`	The portal could not load a valid session.

VERIFIED is not permission to fulfil. Confirm the order from the signed payment.verified webhook first.

Errors

These errors occur before a checkout opens. A checkout that opens but ends with a bad status returns a result, not an exception.

Code	When it happens
`configuration`	Missing `publishableKey`, an invalid API URL, or no `amount`, `items` or `sessionToken`.
`network`	The request timed out or could not reach the API.
`api`	The API returned a non-2xx response. The error includes the HTTP status and response body where the platform supports it.
`session`	The response was not a valid session, the session is unknown, or the portal URL is invalid.
`unavailable`	The checkout could not be presented, for example because the host activity or app root no longer exists.
`aborted`	The operation was cancelled before it settled.

Failures reject with EsaalatCheckoutError. Check code, and status for HTTP errors.

Fulfilment

Use the SDK result only for the buyer's screen. Confirm the order from the signed payment.verified webhook before fulfilment.

API reference