Odoo

The payment_qasimha module adds Qasimha as a redirect payment provider on Odoo's standard payment form. It sends the shopper to the Qasimha hosted checkout and marks the order paid only after reading the Qasimha order back from the API. Odoo has no Qasimha SDK, so the module carries its own small Python client built on requests.

Requirements

Item	Requirement
Odoo	17 (Community and Enterprise)
Odoo modules	`payment` and `website_sale`
Python dependency	`requests` (shipped with Odoo)
Website currency	`SAR`
Customers	Saudi Arabia (the provider and payment method are restricted to it)
HTTPS	Required
Module	`payment_qasimha`, version `17.0.1.0.0`
License	LGPL-3

Install

Copy or clone the repository so that the payment_qasimha/ folder sits in an addons path.
Update the apps list.
Install Payment Provider: Qasimha.

With the official Docker image, mount the module into the extra addons path:

docker run -v "$PWD/payment_qasimha":/mnt/extra-addons/payment_qasimha:ro ... odoo:17

The provider record is created disabled. Enabling it activates the Qasimha payment method.

Configure

Go to Website → Configuration → Payment Providers → Qasimha (or Invoicing → Configuration).

Setting	What to enter
Environment	Sandbox (`sk_test_` / `pk_test_`) or Production (`sk_live_` / `pk_live_`). A key whose prefix disagrees with the environment is refused on save.
Secret key	Your `sk_test_...` or `sk_live_...` key. Readable by Settings administrators only.
Publishable key	Used only by the widget. Must belong to the same environment as the secret key.
Webhook URL / Register webhook	The URL the module answers on. Register webhook creates the endpoint through the API and stores the signing secret once. You can also paste the secret from the Merchant Portal by hand.
Test connection	Checks the key against the API and shows the order counts.
Minimum / maximum amount	Hides the provider and the badge outside the range. `0` means no limit. Odoo's own Maximum Amount also applies.
Instalment badge on product pages / cart	Turns the widget on for each place.
State	Odoo's Test Mode or Enabled. Both use the Environment above.

Test Mode does not pick the sandbox
Odoo's Test Mode state does not switch Qasimha to sandbox. The Environment field and the key prefix decide which Qasimha environment is used.

Register the webhook

Press Register webhook, or register this URL in the Merchant Portal and paste the secret:

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

The webhook answers in JSON:

Status	Meaning
`200`	Received (applied, duplicate, or no matching transaction)
`400`	Bad body
`401`	Bad signature, or no secret saved
`503`	Qasimha API could not be read — Qasimha retries

How a payment flows

Pay. When the shopper confirms Qasimha on the payment form, the module creates the checkout session from the sale order, stores the Qasimha order id on the transaction (qasimha_order_id, also provider_reference), and redirects the shopper.
Return. The shopper comes back to /payment/qasimha/return. The module reads only its own parameters (reference, token, outcome), checks the token, reads the order from Qasimha, and sets the transaction to done only when the order is Confirmed, its orderReferenceId is the transaction reference, and its total equals the transaction amount to the halala.
Webhook. Applies the same rule when Qasimha sends an event.

The order reference is Odoo's transaction reference (S00042, then S00042-1, S00042-2 on each new attempt), so a shopper who retries is not blocked by a duplicate reference.

Transaction states

Situation	Odoo transaction state
Qasimha order `Confirmed` (or a later paid state), reference and total match	done
Declined at checkout creation or on return	error, with one neutral decline line
Other API failure at checkout creation	stays draft; shopper sees "Your Qasimha payment was not completed…" and can try again
`Cancelled`, `Expired` or `Voided`	cancel
Confirmed order whose reference or total does not match	error (logged for the merchant)
Order still open after a cancel or failure return	Module cancels the Qasimha order; transaction cancel
Order still open after a success return	pending until the webhook arrives
Refund event	Note added on the sale order

Widget placement

Product page: <qasimha-widget type="summary"> under the price (website_sale.product_price). The amount updates when the shopper changes the product variant.
Cart: under the cart total (website_sale.total).
Payment step: <qasimha-widget type="card-snippet"> in the provider's inline form.

The widget script is bundled in the module (the Odoo Apps store does not allow remote scripts). See Plans widget.

Fulfilment, refunds and cancellations

Fulfilment: press Fulfil on Qasimha on a paid transaction. It reports the transaction amount, once. Fulfilment is what releases your settlement.
Refund: press Refund on the transaction. The module calls Qasimha first; the refund child transaction is created (and set done) only if Qasimha accepts. A refusal such as AMOUNT_EXCEEDED is shown verbatim. Partial refunds are supported.
Cancel: cancelling a sale order with an open Qasimha transaction, or pressing Cancel Qasimha Checkout on the transaction, cancels the Qasimha order while it is still AwaitingCheckout.

Test in UAT

Environment Sandbox, sk_test_ and pk_test_ keys saved; Test connection shows the counts.
Register webhook pressed (or secret pasted) for sandbox.
Website currency SAR; a test customer with a Saudi Arabia address.
Badge shows on a product page, the cart and the payment step.
Complete a hosted checkout: transaction done.
Cancel on the hosted checkout: transaction cancel.
Fulfil on Qasimha on the paid transaction.
Partial Refund, then a refund above the remaining amount: the second is refused with Qasimha's message.

Troubleshooting

Qasimha does not appear on the payment form

Check that the provider state is Enabled or Test Mode, the website currency is SAR, the customer is in Saudi Arabia, and the amount is inside both the Qasimha range and Odoo's Maximum Amount.

Key refused on save

The key prefix does not match Environment. Use sk_test_ / pk_test_ for Sandbox and sk_live_ / pk_live_ for Production.

Transaction stays pending after checkout

The Qasimha order was still open when the shopper returned. The webhook completes it. Check that the webhook is registered and the secret is saved.

Where are the logs?

In the odoo.addons.payment_qasimha logger, plus chatter messages on the linked sale orders. Lines carry references, Qasimha order ids, statuses, API codes and request ids.

Security

Keys: qasimha_api_key, qasimha_webhook_secret and the per-transaction return token are fields restricted to base.group_system, shown as password fields and never logged. They are stored as plain values in the database, so limit database and backup access. The secret key is never sent to the browser.
CSRF: the settings form and action buttons are normal Odoo form actions (session and CSRF token, base.group_system on the buttons).
Return routes: GETs that change nothing on the strength of their parameters; the orderId/status that Qasimha appends are logged as hints only.
Webhook route: csrf=False by design; protected by the HMAC signature (several v1 values during rotation, constant-time compare, 5-minute tolerance). See Webhook signatures.
Transport: TLS certificate validation cannot be turned off; redirects are never followed; each POST carries an Idempotency-Key. See Idempotency.
PCI DSS: no card data touches Odoo; 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.