Hosted checkout in React Native

A native modal around the hosted portal. Mount one host next to the app root.

esaalat-react-native· TypeScript

On this page

Install Quick start Options Result Errors Fulfilment

Install

Install the package and its WebView peer.

npm install esaalat-react-native react-native-webview

react-native-webview is a peer dependency.

Quick start

Mount CheckoutHost once, then call open() from any screen.

1import {
2  CheckoutHost,
3  EsaalatCheckout,
4} from "esaalat-react-native";
5
6const checkout = new EsaalatCheckout({
7  publishableKey: "pk_live_...",
8  locale: "ar",
9});
10
11// Mount once, next to your app root.
12<CheckoutHost checkout={checkout} />;
13
14const result = await checkout.open({
15  amount: "5000.00",
16  currency: "YER",
17  externalOrderId: "order-123",
18});

open() stays pending until a result. A second open() while the modal is visible is rejected.

Options

Constructor and open() options. presentation and zIndex are not exposed.

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.
`apiBaseUrl`	`string`	Optional	API root. Defaults to `https://api.esaalat.com/api/v1`.
`portalBaseUrl`	`string`	Optional	Fallback portal origin when the 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`.
`externalOrderId`	`string`	Optional	Your order reference. Returned in the result and in the `payment.verified` webhook.
`sessionToken`	`string`	Optional	Open a session created by your server instead of creating one in the app.
`portalUrl`	`string`	Optional	Portal URL for that session. Optional; the SDK builds it 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.

open() rejects with EsaalatCheckoutError. A missing host is a configuration error.

Fulfilment

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

API reference