E-commerce plugins overview

Qasimha store plugins add "Qasimha — pay in instalments" as a payment method on your online store. The plugin creates the checkout, sends the shopper to the Qasimha hosted checkout, confirms the result with the Qasimha API, and keeps the store order in step through webhooks, fulfilment, refunds and cancellations.

All plugins follow the same flow. Menus, field names, order statuses and some admin actions differ per platform; each platform page lists them.

Supported platforms

Every platform needs:

• the store currency set to Saudi riyal (SAR) — the method hides itself for any other currency;
• the store served over HTTPS (the API refuses plain http return URLs except on localhost);
• a Qasimha merchant account with API keys for the environment you use.

What every plugin does

1. Checkout redirect. When the shopper places the order, the plugin builds a checkout session from the store order (items, tax, shipping, discount, customer, shipping address and return links), stores the Qasimha order id on the store order, and redirects the shopper to the Qasimha hosted checkout.

   • If the same order reference was already sent (for example a double click), the shopper is sent to the existing checkout.
   • If Qasimha declines, the shopper sees one neutral line. The reason is never shown.

2. Return route. When the shopper comes back, the plugin ignores the URL parameters for the decision. It reads the order from the Qasimha API with the secret key and marks the store order paid only when all three hold:

   • the Qasimha order status is Confirmed;
   • its orderReferenceId matches the reference the plugin sent;
   • its totalAmount equals the store order total to the halala.

   Anything else leaves the order unpaid and shows a "payment not completed" message.

3. Webhook. Qasimha sends signed events to a URL on your store. The plugin checks the signature, ignores repeated deliveries of the same event, reads the order again from the API and applies the same rule as the return route. This is what confirms an order when the shopper closes the browser before returning.

4. Fulfil. The plugin tells Qasimha the order is fulfilled. Fulfilment releases the merchant settlement. WooCommerce, Magento and PrestaShop do this when the order is completed or shipped; Salesforce does it from a scheduled job; on OpenCart and Odoo you press a button on the order.

5. Refund from the admin. A refund made in the store admin is sent to Qasimha. A refusal such as AMOUNT_EXCEEDED is shown to the admin as Qasimha wrote it. The Salesforce cartridge does not send refunds; it only records refund events as order notes.

6. Cancel. Cancelling an unpaid store order cancels the Qasimha order while it is still open (AwaitingCheckout). On Salesforce this happens when the shopper cancels on the hosted checkout.

The plugins also show the Qasimha instalment widget on product and cart pages and a card at checkout. The widget uses only the publishable key; it never calculates an instalment itself.

See Order lifecycle for the statuses and Return URLs for why the return page is not proof of payment.

Common settings

Most plugins' settings pages have these fields. Exact labels and exceptions are on each platform page. For example, Salesforce keeps the secret key in a Business Manager service credential and has no Test connection button, and OpenCart has no title or description fields.

Sandbox and production

The plugins choose the API host from the environment and key prefix. You never type a hostname. See Authentication.

Before you go live

• Full test order paid in sandbox: store order marked paid, Qasimha order id visible on the order.
• Declined and cancelled checkouts tested: store order not marked paid, shopper sees a neutral message.
• Webhook endpoint registered and a test delivery accepted (no 401/400 in the plugin log).
• Fulfilment, a partial refund and a full refund tested from the store admin (where the platform supports admin refunds).
• Environment switched to Production, sk_live_ and pk_live_ keys saved, Test connection passes.
• Production webhook endpoint registered and the production webhook secret saved.
• Store currency is SAR and the site runs on HTTPS with a valid certificate.
• Debug log turned off (errors and warnings are still logged).
• Only trusted admin accounts can open the plugin settings.

Security

• The secret key and webhook secret stay in the platform's protected settings on your server. The browser only ever sees the publishable key. WooCommerce, Magento and PrestaShop encrypt the keys at rest; OpenCart and Odoo store them in the database as plain values behind admin permissions, so limit database and backup access.
• Settings pages are protected by the platform's own CSRF token and admin permission checks.
• The webhook route has no CSRF token by design (it is called by Qasimha, not a browser). It is protected by the HMAC signature instead. See Webhook signatures.
• No card data passes through your store, so the store stays in PCI DSS SAQ-A scope.

Platform guides