OpenCart

The Qasimha extension adds "Qasimha - pay in instalments" to an OpenCart 4 store. The shopper is sent to the Qasimha hosted checkout and comes back to your thank-you page. The store marks the order paid only after it has read the order back from Qasimha. Fulfilment, refunds and status checks run from the order page.

Requirements

Install

1. Download qasimha-opencart-<version>.ocmod.zip from the extension's releases.
2. In the admin, open Extensions → Installer, upload the file, then press Install on the row that appears.
3. Open Extensions → Extensions, choose the type Payments, find Qasimha and press Install. This creates the tables oc_qasimha_order and oc_qasimha_webhook_event and registers the storefront events for the widget.
4. Press Edit and fill in the settings below.

If your Arabic language uses a directory other than ar (for example ar-sa), copy extension/qasimha/admin/language/ar and extension/qasimha/catalog/language/ar to that name.

Uninstalling from the Payments list removes the events and the webhook table but keeps oc_qasimha_order, so past orders keep their Qasimha order id.

Configure

Go to Extensions → Extensions → Payments → Qasimha → Edit.

Order status mapping

Set these on the Order statuses tab.

The extension never moves an order backwards. A paid order is not set back to pending by a later webhook.

Register the webhook

Register this URL in the Merchant Portal and paste the secret into Webhook secret:

https://<your-store>/index.php?route=extension/qasimha/payment/qasimha.webhook

The webhook answers:

The event body only says which order to look at. The extension reads the order from Qasimha before changing anything.

How a payment flows

1. Confirm. The shopper presses Continue to Qasimha. The extension creates the checkout session from the order, sets Awaiting checkout and redirects the shopper.
2. Reference. The reference is the OpenCart order id. If the shopper cancels and places the same order again, the next attempt is <id>-2, <id>-3, and the abandoned Qasimha order is cancelled.
3. Return. The shopper returns to the qasimha.callback route with the order id and a token. The extension checks the token, reads the order from Qasimha, and marks it paid only when it is Confirmed with the same reference and total. Otherwise OpenCart's payment-failed page is shown.
4. Decline. The shopper sees one line — "Your Qasimha payment was not completed. Please choose another payment method." — and never a reason.

Widget placement

With a publishable key saved, the extension shows the instalment summary (<qasimha-widget type="summary">) on product pages (under the price) and the cart page (under the totals), and a "pay in instalments with Qasimha" card at checkout.

Placement is a list of CSS selectors tried left to right, separated by ||. The widget is inserted after the first match. Defaults for the OpenCart 4 default theme:

• Product page: #content h2 || .product-price || .price
• Cart page: #checkout-total || #content .table:last-of-type

Change them if your theme uses different markup. The widget is only injected when the shopper's currency is SAR and renders nothing when the amount is outside your plans. If you use a Content Security Policy, allow connect-src for the Qasimha API host of your environment; the script itself is served from your store. See Plans widget.

Fulfilment, refunds and cancellations

Open Sales → Orders, then an order paid with Qasimha. The Qasimha tab shows the Qasimha order id, reference, environment and last known status, with three actions:

• Check status — reads the order again and shows captured, refunded and refundable amounts.
• Fulfil in Qasimha — reports the whole order as fulfilled, once. The order moves to the Fulfilled status.
• Refund via Qasimha — enter an amount and an optional reason. History is updated only when Qasimha accepts. A refund above the refundable amount shows Qasimha's AMOUNT_EXCEEDED message as is.

When the shopper cancels on the hosted checkout, the cancel route cancels the Qasimha order and returns the shopper to the cart.

Test in UAT

• Environment Sandbox, sk_test_ and pk_test_ keys saved; Test connection passes.
• Webhook URL registered for sandbox and the secret saved.
• Widget shows under the product price and the cart totals (adjust selectors if not).
• Complete a hosted checkout: order moves to Payment confirmed (default Processing).
• Cancel on the hosted checkout: you are back in the cart.
• Fulfil in Qasimha: order moves to Fulfilled.
• Partial refund, then a refund larger than what is left: the second shows AMOUNT_EXCEEDED.
• storage/logs/qasimha.log shows no errors.

Troubleshooting

Security

• Admin: every save and button checks the admin user_token and the modify permission on extension/qasimha/payment/qasimha. Give that permission only to trusted admin users.
• Keys: the secret keys and webhook secret are saved in OpenCart's setting table without encryption and shown masked on the settings page. Restrict database and backup access accordingly.
• Browser: only the publishable key.
• Return route: checks a per-attempt token and reads the order from Qasimha before changing it.
• Webhook route: verifies the HMAC signature (5-minute tolerance, secret rotation) and de-duplicates on the event id. See Webhook signatures.
• Logs: secret keys, the webhook secret and customer data are never written; key-shaped strings are masked.
• PCI DSS: no card data passes through the store; you stay in SAQ-A scope.

Report security issues privately, never in a public issue.

Next steps