Web SDKs

The web SDKs are browser packages for React and Angular. They do three things:

• Present the hosted checkout, by redirecting the page or opening a popup window.
• Read the result when the shopper comes back to your return page.
• Show instalment plans on product, cart and checkout pages, with their own components or with the on-site widget.

They do not create checkout sessions and they do not hold your secret key.

How it fits together

Your server creates the session with a server SDK and your secret key. The browser package only works with what your server gives it.

Browser (web SDK)              Your backend (secret key)          Qasimha
-----------------              -------------------------          -------
load config      -- GET /api/qasimha/config --> publishable key, return URLs
plan components  ------------------------------------------------> GET /widget/plans (pk_...)
pay button       -- POST /api/checkout --> checkout.createSession -> POST /pay/session/create
                 <------- paymentUrl ------
redirect / popup ------------------------------------------------> hosted checkout
return page      <------------ merchantUrl?orderId=...&status=... -
confirm          -- GET /api/orders/:id --> orders.get ------------> GET /merchant/orders/{id}

The /api/... paths on the left are your routes. The SDK READMEs and the demo use these names; you can choose your own.

The flow

1. Your backend returns the browser configuration: publishable key, language, return URLs (merchantUrl), and optionally the widget script. Never the secret key.
2. The shopper clicks pay. The SDK calls your createSession function, which posts the basket to your backend.
3. Your backend prices the basket from its own catalogue, calls the server SDK (checkout.createSession) and returns paymentUrl and orderId.
4. The SDK sends the shopper to paymentUrl, in the same tab (redirect) or a popup.
5. Qasimha sends the shopper back to your return URL with orderId, orderReferenceId and status added.
6. The SDK reads those values. Your page then asks your backend to read the order with the secret key before showing "paid".
7. Your backend also receives the signed webhook, which is the durable record.

Redirect or popup

There is no iframe mode: the hosted checkout refuses to be framed. In popup mode the popup also lands on your return URL, and the SDK passes the result to the original tab over a same-origin BroadcastChannel (a browser channel between tabs of the same site). The React and Angular packages use the same popup name and channel messages, so they work together.

Packages

Both need a backend that uses one of the Qasimha server SDKs: @qasimha/sdk (Node.js), qasimha/php-sdk (PHP), Qasimha.Sdk (.NET) or com.qasimha:qasimha-sdk (Java).

Demo store and demo backend

Each web package ships with a demo store (Arabic and English) that uses the SDK the way a merchant would. Each server SDK ships a demo merchant backend. All demo backends expose the same HTTP API, so either store runs against any backend.

The demo backend is a good model for the server side you need to write:

The demo backend reads its settings from environment variables:

Mock mode needs no Qasimha account. The mock has a checkout page with Approve, Simulate decline and Cancel buttons, on a different origin from the store, so redirect and popup behave as in production. With test keys, the store quotes real UAT plans and sends the shopper to the real hosted checkout.

Security

• Your secret key (sk_...) lives only on your server. Both SDKs refuse a secret key in their config.
• Amounts are computed on your server from your own prices. The browser never sends prices.
• Confirm every outcome on your server before fulfilment.
• The SDKs store nothing (no cookies, no storage). Payment happens on the Qasimha hosted page, so no card data touches your pages and you stay in PCI DSS SAQ-A scope.

Choose your framework