PrestaShop

The qasimha module adds "Qasimha — pay in instalments" as a payment option on a PrestaShop 8 store. It uses the Qasimha PHP SDK for every API call, keeps your secret keys encrypted in the configuration table, and loads only the instalment widget (with your publishable key) in the shopper's browser.

Requirements

Item	Requirement
PrestaShop	8.0 or later
PHP	8.1 or later
Shop currency	Saudi riyal
HTTPS	SSL enabled (plain `http` works only on `localhost`)
Module name	`qasimha` (tab Payment)
License	AFL-3.0

Install

In the back office, go to Modules → Module Manager → Upload a module.
Upload the release zip. It contains the module folder (qasimha/qasimha.php) and the SDK in its own vendor/ directory.

Developers installing from source:

composer install --no-dev

Then copy the directory to modules/qasimha and install it from Module Manager.

Configure

Go to Modules → Module Manager → Qasimha → Configure.

Setting	What to enter
Enable Qasimha	The payment option is offered only when this is on and a secret key is saved for the selected environment.
Environment	Sandbox (`sk_test_` / `pk_test_`) or Production (`sk_live_` / `pk_live_`).
Sandbox / Production secret key	Shown masked after saving. Leave blank to keep the saved key.
Publishable key	Used only by the widget. Must belong to the selected environment.
Webhook URL	Read-only. The URL to register with Qasimha.
Register webhook	Creates the webhook endpoint for the selected environment through the API (or rotates the secret of the endpoint it created earlier) and stores the secret, encrypted. Needs a key with the `webhooks:manage` scope.
Sandbox / Production webhook secret	Paste the secret from the Merchant Portal here if you do not use Register webhook.
Minimum / maximum order amount	Hides the payment option outside the range. Blank means no limit.
Widget on product / cart pages	Instalment summary under the product price and under the cart.
Debug log	Adds info lines to Advanced Parameters → Logs (object `Qasimha`). Errors and warnings are always logged.
Test connection	Checks the saved key of the selected environment against the API.

The page warns you when the shop currency is not the riyal, the module is enabled without a key, a saved key can no longer be decrypted, the publishable key belongs to the other environment, no webhook secret is saved, or SSL is off.

Register the webhook

Use one of two options:

Register webhook button: needs a secret key with the webhooks:manage scope. See Authentication.
Manual: register the URL shown in Webhook URL in the Merchant Portal and paste the secret into the webhook secret field for that environment.

https://<your-store>/module/qasimha/webhook

The exact URL depends on your shop's URL settings; copy it from the Webhook URL field.

The webhook answers:

Status	Meaning
`200`	Received
`400`	Bad body
`401`	Bad signature, or no secret saved
`503`	Qasimha API unreachable — Qasimha retries

A shop in maintenance mode answers with the maintenance page; Qasimha retries.

Order states

State	When
Qasimha — awaiting checkout (created by the module)	The order exists and the shopper is on the hosted checkout.
Payment accepted (`PS_OS_PAYMENT`)	The Qasimha order is `Confirmed` with a matching reference and total. The payment's transaction id is the Qasimha order id.
Canceled (`PS_OS_CANCELED`)	The shopper cancelled or was declined, or Qasimha voided, cancelled or expired the order. A private note says which.
Payment error (`PS_OS_ERROR`)	The checkout session could not be created. The shopper gets the cart back.
Refunded (`PS_OS_REFUND`)	Qasimha reports the order fully refunded.

How a payment flows

Place order. The module creates the PrestaShop order in the awaiting state, creates the checkout session and redirects the shopper.
Return. The shopper comes back to module/qasimha/return. The module checks its own token, reads the order from Qasimha and marks it paid only when it is Confirmed, its orderReferenceId equals the PrestaShop order reference, and its total equals total_paid_tax_incl to the halala.
Not finished yet: if the Qasimha order is still open, the shopper sees "Payment not completed" with a Return to Qasimha link.
Webhook. Applies the same rule when Qasimha sends an event.

The order reference is the PrestaShop order reference (for example XKBKNABJK), which is new for each attempt. A cart split over several carriers gives several orders with one reference; they form one Qasimha order and move together.

Widget placement

Product page: <qasimha-widget type="summary"> under the product price.
Cart page: under the cart.
Checkout: the widget is loaded on the checkout page.

The widget script is bundled inside the module (PrestaShop Addons does not allow remote scripts). The order page in the back office shows a Qasimha card with the order id, reference, environment and status. See Plans widget.

Fulfilment, refunds and cancellations

Fulfilment: when the order moves to a state flagged shipped or delivered, the module reports fulfilment with the order total. It runs once; a failure is noted and retried on the next such state change.
Refund: add a credit slip (standard or partial refund). The module refunds the slip amount (products + shipping, tax included) through Qasimha.
Cancel: moving an unpaid order to Canceled cancels the Qasimha order while it is still AwaitingCheckout.

A refused refund still leaves a credit slip
PrestaShop 8 creates the credit slip before the module can call Qasimha. If Qasimha refuses the refund (for example AMOUNT_EXCEEDED), you see the error in the back office and a note on the order, but the slip stays. Void the slip, or refund from the Merchant Portal.

Test in UAT

Environment Sandbox, sk_test_ and pk_test_ keys saved, Enable Qasimha on; no warnings on the configuration page.
Register webhook pressed (or secret pasted) for sandbox.
Widget shows under a product price and in the cart.
Complete a hosted checkout: order is Payment accepted with the Qasimha order id as transaction id.
Cancel on the hosted checkout: order Canceled, cart restored.
Move a paid order to a shipped state: a fulfilment note appears.
Partial credit slip refunded at Qasimha; a slip above the remaining amount shows the error.
Advanced Parameters → Logs shows no Qasimha errors.

Troubleshooting

Saved key can no longer be decrypted

Keys are encrypted with a key derived from the shop's _COOKIE_KEY_. If that value changed (for example after moving the shop), enter the secret keys and webhook secret again.

The secret key needs the webhooks:manage scope. Use a key with that scope, or register the URL in the Merchant Portal and paste the secret.

Qasimha is not offered at checkout

Check that Enable Qasimha is on, a secret key is saved for the selected environment, the cart is in riyals, and the total is inside the amount range.

Webhook returns 401

The signature did not match the saved secrets, or no secret is saved. The module tries the selected environment's secret first, then the other one.

Security

Keys: secret keys and webhook secrets are encrypted at rest (libsodium secretbox, AES-256-GCM fallback) under a key derived from _COOKIE_KEY_. Masked on screen; the logger redacts anything shaped like a key.
Browser: only the publishable key.
CSRF: the checkout POST carries Tools::getToken(false); the configuration page requires the back-office admin token and checks Tools::getAdminTokenLite('AdminModules') on every action.
Return routes: GETs that compare a token in constant time and ask the API before changing anything.
Webhook route: no CSRF token by design; protected by the HMAC signature (constant-time compare, 5-minute tolerance, rotated secrets). See Webhook signatures.
PCI DSS: no card data touches the store; you stay in SAQ-A scope.

Report vulnerabilities privately to the security contact in the Merchant Portal, not in a public issue.

Next steps

Plugins overview

The rule every plugin applies and the go-live checklist.

Webhooks

Events Qasimha sends and how retries work.

Order lifecycle

Order statuses from checkout to refund.