Magento 2

The Qasimha_Payment module adds "Qasimha - Pay in instalments" to Magento Open Source and Adobe Commerce. It places the order, sends the shopper to the Qasimha hosted checkout, confirms the result with the Qasimha API before invoicing, and keeps the order in step through webhooks, fulfilment, refunds and cancellations. It uses the Qasimha PHP SDK for every API call.

Requirements

Item	Requirement
Magento	Open Source or Adobe Commerce 2.4.4 or later
PHP	8.1 or later
Order currency	`SAR` only
HTTPS	Required for return and webhook URLs
Composer package	`qasimha/module-payment`
Module name	`Qasimha_Payment`

Install

Run from the Magento root:

composer require qasimha/module-payment
bin/magento module:enable Qasimha_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy en_US ar_SA
bin/magento cache:flush

setup:upgrade creates one table, qasimha_webhook_event, which records webhook deliveries already processed.

Configure

Go to Stores → Configuration → Sales → Payment Methods → Qasimha - Pay in instalments.

Field	What to enter
Enabled	Off by default. Set to Yes.
Environment	Sandbox (`sk_test_` key) or Production (`sk_live_` key). A key that does not match the environment is refused.
Sandbox / Production API key	Your secret key. Encrypted with Magento's encryption key; shown obscured after save.
Publishable key	`pk_test_...` or `pk_live_...`. Loaded by the on-site widget.
Webhook secret	Encrypted at rest; used to verify every delivery.
Webhook URL	Read-only. The URL to register with Qasimha.
Title / Description (English, Arabic)	Shown at checkout. The Arabic pair is used on Arabic store views.
Minimum / Maximum order total	Limits for showing the method and the widget. Empty means Qasimha's own plan limits apply.
Applicable countries	Billing country. Defaults to Saudi Arabia.
Show widget on product page / cart page	Instalment summary under the price and under the cart totals.
Debug log	Writes call outcomes to `var/log/qasimha.log`.

The method appears only for SAR orders and only once a key is saved for the selected environment.

Register the webhook

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

The same URL is shown read-only in the Webhook URL field. The webhook answers:

Status	Meaning
`200`	Processed, duplicate, or nothing to do
`400`	Bad signature, stale timestamp, or a body that is not an event
`500`	Module not configured (no key or no webhook secret)

How a payment flows

Place order. The order is saved as pending_payment and the confirmation email is held back. The shopper goes to qasimha/checkout/start.
Session. The module creates the checkout session from the order, stores the Qasimha order id and checkout URL on the order payment, and redirects the shopper.
Return. qasimha/checkout/return reads only its own order and token parameters, reads the order from the API and marks it paid only when it is Confirmed, the reference matches and the grand total matches to the halala.
Webhook. Applies the same rule when Qasimha sends an event.

Order status changes

Event	What happens to the Magento order
Order placed	`pending_payment`; confirmation email held
Qasimha order `Confirmed` (return or webhook)	Capture transaction, paid invoice, `processing`, order and invoice emails sent
Declined at checkout creation	Order cancelled with an admin comment; cart restored; shopper sees one neutral line
Any other error at checkout creation	Order cancelled with the error in a comment; cart restored
Return with `Declined`, `Expired`, `Cancelled` or `Voided`	Order cancelled; cart restored
`order.voided`, `order.expired` or `order.declined` event on an unpaid order	Order cancelled
Refund event (`order.refunded`)	Comment with the refunded amount; no credit memo is created

The order view shows the Qasimha order id, status, fulfilment time and refunded amount under Payment Information. Every change the module makes adds a status-history comment naming the Qasimha order id.

Widget placement

Product page: <qasimha-widget type="summary"> under the price, using the displayed final price. On configurable products the amount does not follow option changes until the page reloads.
Cart page: under the cart totals.
Checkout: the method card shows <qasimha-widget type="card-snippet"> with your title and description.

The widget script is bundled. The module adds the Qasimha API host to connect-src through etc/csp_whitelist.xml, so Magento's CSP allows it. Language follows the store view locale (ar_* is Arabic, otherwise English). See Plans widget.

Fulfilment, refunds and cancellations

Fulfilment: the first shipment reports fulfilment to Qasimha with the order total and the first tracking number, once. Orders with nothing to ship are fulfilled when their invoice is paid.
Refund: create a credit memo and press Refund (online). The module calls Qasimha first; the credit memo is created only if Qasimha accepts. A refusal such as AMOUNT_EXCEEDED is shown as Qasimha worded it.
Refund made in the Merchant Portal: recorded as a comment on the order. Create the credit memo yourself as an offline refund.
Cancel from admin: cancelling or voiding an unpaid order cancels the Qasimha order if it is still open. A Qasimha order that already ended is left alone and never blocks the store.
Shopper cancels on the hosted checkout: qasimha/checkout/cancel reads the order first; if it is still open it is cancelled in Qasimha and in the store.

Test in UAT

Environment Sandbox, sk_test_ and pk_test_ keys saved, method Enabled.
Webhook URL registered for sandbox and the secret saved.
Widget shows on a product page, the cart and the checkout method card.
Complete a hosted checkout: order moves to processing with a paid invoice.
Cancel on the hosted checkout: order cancelled, cart restored.
Ship the order with a tracking number: a fulfilment comment appears.
Online credit memo for part of the order, then one for more than is left: the second is refused with Qasimha's message.
var/log/qasimha.log shows no errors.

Troubleshooting

Qasimha is not offered at checkout

Check that the method is enabled, a key is saved for the selected environment, the order currency is SAR, the billing country is in Applicable countries, and the total is inside the minimum/maximum range.

Webhook returns 500

The module has no secret key or no webhook secret for the selected environment. Save both in the module settings.

Webhook returns 400

The signature did not match, the timestamp is older than 5 minutes, or the body is not an event. Check that the webhook secret matches the endpoint in the Merchant Portal and that the server clock is correct.

Widget amount does not change when I pick a product option

Known limitation: on configurable products the widget uses the price shown when the page loaded.

What to send to Qasimha support

The order reference and the requestId from var/log/qasimha.log.

Security

Keys: secret keys and the webhook secret use Magento\Config\Model\Config\Backend\Encrypted and are decrypted only when an API client is built.
Browser: only the publishable key.
Return route: the return token is compared in constant time. A request without a valid token goes to the cart. The order is never changed on the strength of a URL parameter or a webhook body.
Webhook route: a POST exempt from the form key (CsrfAwareActionInterface) because the HMAC signature is its authentication. There is no unsigned path. Deliveries are de-duplicated on X-Qasimha-Event-Id. See Webhook signatures.
Logs: API keys, the webhook secret, request bodies and shopper data are never logged.
PCI DSS: no card data is handled; the store stays in SAQ-A scope.

Report a vulnerability privately through your Qasimha integration manager; do not open 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.