Install the on-site widget

@qasimha/widget adds a <qasimha-widget> element to your pages. It shows the shopper what they would pay in instalments, before they reach checkout. It is one script with no dependencies. It draws inside Shadow DOM (an isolated part of the page), so your CSS and the widget's CSS do not mix.

The widget only displays plans. It does not start a checkout. To take payment, create a checkout session on your server (see Checkout flows).

What it shows

The popup shows the plans offered for the amount, the schedule of the selected plan (due dates, amounts, fees, total), "How it works?" and "Why Qasimha?".

Requirements

Load the widget

Set the configuration first, then load the script. Pick one way to load it.

<script>
  window.qasimhaWidgetConfig = {
    publicKey: 'pk_test_...', // required
    lang: 'ar',               // 'ar' (default) or 'en'
    country: 'SA'             // only SA is supported
  };
</script>
<script defer
        src="https://cdn.qasimha.com/widget/0.1.0/qasimha-widget.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>

npm install @qasimha/widget

Then place elements where you want them:

<qasimha-widget type="summary" amount="1200" inline-type="2"></qasimha-widget>
<qasimha-widget type="card-snippet"></qasimha-widget>
<qasimha-widget type="faq"></qasimha-widget>

If you use React or Angular, the Web SDKs can load and configure the widget for you.

Configuration

window.qasimhaWidgetConfig keys:

Every value is checked. A bad style value is ignored. A bad publicKey, country or apiBaseUrl stops rendering.

Element attributes

Changing any of these attributes re-renders the element by itself.

The headline plan is the first plan the API returns. Qasimha decides the order.

Your own template (inline-type="0")

Write your own markup inside the element. Mark the nodes the widget should fill with data-qasimha:

<qasimha-widget type="summary" amount="1200" inline-type="0">
  أو <span data-qasimha="instalments"></span> دفعات ×
  <span data-qasimha="instalment-amount"></span>
  <button type="button" data-qasimha="learn-more">المزيد</button>
</qasimha-widget>

When there are no plans, the whole element is hidden, so your template never shows without numbers.

Prices that change on the page

On a single-page store, when the price changes, either update the amount attribute or call the refresh function:

window.QasimhaWidget.refresh();   // Promise<void>: re-reads the config, re-renders every element
window.QasimhaWidget.version;     // '0.1.0'
document.querySelector('qasimha-widget').whenRendered(); // Promise<void>, useful in tests

Language and right-to-left

• Arabic is the default and renders right-to-left; English renders left-to-right.
• Set the language for the page with lang in the config, or per element with the lang attribute.
• Amounts always use the Saudi riyal symbol to the left of the number, in a left-to-right span, in both languages. Digits are Latin, with a thousands separator, e.g. 1,200 and 300.50.

Where the numbers come from

The summary type reads plans from the plans endpoint with your publishable key. That endpoint is documented in Plans widget API. The widget keeps each answer in memory for the life of the page, and ten badges for the same price make one request.

The widget fails closed: it shows nothing, never a guessed or computed number, when:

• the config is invalid (publicKey, country, apiBaseUrl);
• amount is malformed or zero;
• the request fails, times out (5 seconds) or returns a non-2xx status;
• the response is not a success, the currency is not SAR, or there are no plans;
• amount is below the minimum or above the maximum for your account;
• type is unknown.

Failures are not cached. The next refresh() or attribute change tries again.

Content Security Policy

If your site sends a CSP header, allow:

Modern browsers get the widget styles through adoptedStyleSheets and need no style-src change.

Brand fonts

The widget can use Qasimha's Outreque (Latin) and Zanjabeel (Arabic) fonts. It registers them under its own names, so your store's fonts are never replaced. It looks for them in fonts/ beside the bundle, or in fontsUrl. If they are not there, it uses the system font and nothing else changes. Set fonts: false to always use your store's font.

Styling

• CSS custom properties on the element: --qw-primary, --qw-on-primary, --qw-text, --qw-muted, --qw-border, --qw-bg, --qw-surface, --qw-radius, --qw-font-size, --qw-scale.
• For deeper changes, pass CSS in the css config key. It can target classes such as .qw-badge, .qw-pill, .qw-link, .qw-money, .qw-faq, .qw-dialog.

What the widget never does

• No cookies, no localStorage or sessionStorage, no tracking.
• No third-party requests. It only calls the Qasimha plans endpoint and, if hosted, the font files.
• No eval, no inline event handlers, no postMessage, no iframe. Text is set with DOM APIs, never innerHTML.
• No invented numbers. No plans from the API means nothing on screen.
• No card data and no shopper data. It holds only your publishable key, so embedding it keeps you in PCI DSS SAQ-A scope.

Troubleshooting

Next steps