Skip to main content

Moyasar Payment Gateway

The ECOSIRE Moyasar Payment Gateway module wires Moyasar -- Saudi Arabia's leading SAMA-licensed, PCI DSS Level 1 certified payment processor -- into Odoo's native payment.provider framework. It handles the full card lifecycle: 3-D Secure 2 redirect checkout, authorize-then-capture, full and partial refunds, hosted invoice links, and real-time webhook event processing with HMAC-SHA256 signature verification. Amounts are converted between SAR and halalas transparently so Odoo operators never touch raw minor-unit arithmetic.

Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: LGPL-3

Try before you buy

A live demo is available at demo.ecosire.com. Contact [email protected] for a demo walkthrough on sandbox.

Key Features​

  • Native Odoo payment.provider integration (provider code: moyasar)
  • mada (Saudi domestic debit) and Visa / Mastercard credit-debit card support
  • 3-D Secure 2 redirect flow -- mandatory for mada under SAMA mandate
  • SAR / halalas conversion handled automatically (1 SAR = 100 halalas)
  • Full and partial refunds initiated directly from the Odoo payment transaction
  • Authorize / capture two-step flow for deferred settlement
  • Hosted invoice (payment link) support via Moyasar /invoices endpoint
  • Webhook handler with HMAC-SHA256 signature verification (X-Moyasar-Signature)
  • Single API host for both test and live modes -- environment selected by key prefix
  • ECOSIRE license enforcement on credential saves

Honest scope note: Apple Pay and STC Pay wallet flows are present in the Moyasar API but require additional merchant-side configuration (Apple Pay domain association; STC Pay OTP flow) that has not been verified against a live account. Both are guarded with a clear UserError rather than silently failing. Webhook CRUD management may be dashboard-only -- the module instructs you to register the URL manually in the Moyasar dashboard.

Prerequisites​

RequirementDetails
Odoo version17, 18, or 19 (Community or Enterprise)
ECOSIRE licenseActive license for ecosire_payment_moyasar
Moyasar merchant accountLive account from dashboard.moyasar.com (required for real charges)
mada acceptanceMust be explicitly enabled on your Moyasar account by Moyasar support
CurrencySAR only (Moyasar KSA gateway; multi-currency not supported)
Odoo payment moduleIncluded in Odoo core -- no separate install needed

Installation​

  1. Download the module ZIP from your ECOSIRE Dashboard.
  2. Extract it to your Odoo addons directory: 
    unzip ecosire-payment-moyasar-*.zip -d /opt/odoo/addons/
  3. Restart the Odoo service: 
    sudo systemctl restart odoo
  4. Navigate to Apps, click Update Apps List.
  5. Search for "ECOSIRE Payment | Moyasar" and click Install.
  6. Activate your ECOSIRE license when prompted (see Configuration -- Step 1).

Configuration​

Step 1: Activate Your ECOSIRE License​

Before the provider accepts API credentials, the license must be active.

  1. Navigate to Settings > ECOSIRE License.
  2. Enter your license key received after purchase.
  3. Click Activate. The status should show Active.

Saving Moyasar API keys on the provider record without an active license raises a UserError.

Step 2: Obtain Moyasar API Keys​

  1. Log in to the Moyasar Dashboard.
  2. Go to Account Settings > API Keys.
  3. Copy your Publishable Key -- it starts with pk_test_ (sandbox) or pk_live_ (production).
  4. Copy your Secret Key -- it starts with sk_test_ (sandbox) or sk_live_ (production).
  5. Both keys are required. The publishable key is used in the payment form; the secret key authenticates all server-side API calls via HTTP Basic Auth (key as username, empty password).
Live charging requires a real merchant account

Test keys (sk_test_* / pk_test_*) work against the same Moyasar API host as production -- no separate sandbox URL. You must have an approved live Moyasar merchant account before switching to sk_live_* keys and accepting real payments.

Step 3: Configure the Payment Provider in Odoo​

  1. Navigate to Accounting > Configuration > Payment Providers (or Website > Configuration > Payment Providers for eCommerce).
  2. Click Moyasar in the provider list (or click Create and select Moyasar).
  3. Enter the following fields (visible only to System Administrators):
FieldWhere to find itNotes
Moyasar Publishable KeyMoyasar Dashboard > API KeysStarts with pk_test_ or pk_live_
Moyasar Secret KeyMoyasar Dashboard > API KeysStarts with sk_test_ or sk_live_; stored as a password field
Moyasar Webhook SecretYou choose; set same value in Moyasar DashboardUsed to verify X-Moyasar-Signature on webhook requests
  1. Set the State:
    • Test Mode -- use sk_test_* / pk_test_* keys. No real charges.
    • Enabled -- use sk_live_* / pk_live_* keys for live transactions.
  2. Click Save.

Step 4: Register the Webhook and Return URL in Moyasar Dashboard​

The module exposes two public endpoints on your Odoo installation:

EndpointURL patternPurpose
Return (3DS callback)https://<your-domain>/payment/moyasar/returnCustomer is redirected here after 3DS authentication
Webhookhttps://<your-domain>/payment/moyasar/webhookReceives signed event notifications (payment.paid, payment.failed, etc.)

To register the webhook:

  1. In the Moyasar Dashboard, go to Developers > Webhooks.
  2. Add a new webhook with the URL https://<your-domain>/payment/moyasar/webhook.
  3. Choose the events to receive (at minimum: payment.paid, payment.failed, payment.authorized, payment.captured, payment.refunded).
  4. Copy the Webhook Secret Moyasar generates and paste it into the Moyasar Webhook Secret field on the Odoo provider record.

The callback_url (return URL) is passed automatically with each payment creation request -- no manual registration in the Moyasar dashboard is required for it.

Step 5: Publish the Provider​

  1. On the provider record, click Published to make it visible on your checkout or payment pages.
  2. For eCommerce, navigate to your Shop to verify the Moyasar option appears at checkout.

Usage​

Checkout Flow (3DS Redirect)​

  1. Customer selects Moyasar / mada / card at checkout.
  2. Odoo creates a payment transaction and posts to Moyasar POST /payments with callback_url set to /payment/moyasar/return.
  3. Moyasar returns a transaction_url (status: initiated). The customer is redirected there for 3DS authentication.
  4. After 3DS, Moyasar redirects the customer to /payment/moyasar/return?id=<payment_id>&status=<status>.
  5. The return controller fetches the authoritative payment object via GET /payments/{id} and updates the Odoo transaction state.

Authorize and Capture​

When the provider is configured for two-step capture:

  1. Payment is created in authorized state -- a hold is placed on the card but funds are not settled.
  2. From the Odoo payment transaction, click Capture to trigger POST /payments/{id}/capture and settle funds.
  3. Authorized holds expire after the gateway's hold period (typically 7 days for cards) if not captured.

Refunds​

  1. Open the paid payment transaction in Accounting > Accounting > Payments or from the sales order.
  2. Click Refund.
  3. Enter the amount (full or partial). Partial refund sends amount in halalas to POST /payments/{id}/refund.
  4. The transaction state updates to cancel / refunded on success.

For B2B invoice collection without embedding a checkout form:

  1. From the payment provider configuration, use the hosted invoice feature.
  2. Odoo calls POST /invoices and returns a Moyasar-hosted payment URL.
  3. Share the URL with your customer. They pay on Moyasar's hosted page without entering card details on your site.

API Details​

FieldValue
Auth methodHTTP Basic Auth (Secret Key as username, empty password)
API base URLhttps://api.moyasar.com/v1 (same for test and live)
Test vs liveDetermined by key prefix: sk_test_* = sandbox, sk_live_* = live
Supported currencySAR only (amounts in halalas: multiply SAR by 100)
3DS flowtransaction_url redirect on POST /payments
Return URL/payment/moyasar/return
Webhook URL/payment/moyasar/webhook
Webhook signatureHMAC-SHA256 of raw request body; header X-Moyasar-Signature
Key config fieldsmoyasar_publishable_key, moyasar_secret_key, moyasar_webhook_secret

Payment Status Mapping​

Moyasar statusOdoo transaction state
initiatedpending
paiddone
captureddone
authorizedauthorized
failedcancel
refundedcancel
voidedcancel

Troubleshooting​

IssueCauseSolution
Webhook signature verification failed (403)Webhook Secret mismatch between Odoo and Moyasar dashboardEnsure the Moyasar Webhook Secret on the Odoo provider exactly matches the secret shown in the Moyasar dashboard webhook configuration
UserError: Moyasar secret key is not configuredSecret key field emptyGo to Accounting > Configuration > Payment Providers > Moyasar and enter sk_test_* or sk_live_* key
ValidationError: key must start with sk_test_ or sk_live_Incorrect key pastedKeys are case-sensitive; copy directly from the Moyasar dashboard API Keys page
Payment stays in pending / never reaches doneReturn URL not reachable or 3DS not completedConfirm https://<your-domain>/payment/moyasar/return is publicly accessible; check Odoo logs for return-handler errors
UserError: Moyasar action not available for Apple PayApple Pay gated pending merchant configApple Pay requires Moyasar merchant-session configuration and Apple Pay domain verification -- contact [email protected]
STC Pay OTP flow raises UserErrorSTC Pay confirm endpoint not yet verifiedSTC Pay OTP flow is gated pending official endpoint documentation; contact [email protected]
Currency error at checkoutNon-SAR currency on providerMoyasar only accepts SAR; set the Odoo company currency to SAR or restrict the provider to SAR-denominated transactions
mada card declinedmada not enabled on Moyasar accountContact Moyasar support to enable mada acceptance on your merchant account; 3DS2 is mandatory for mada by SAMA mandate
License not active error on credential saveECOSIRE license inactiveVerify your license at Settings > ECOSIRE License
Webhook events not receivedWebhook URL not registered in Moyasar dashboardRegister https://<your-domain>/payment/moyasar/webhook in Moyasar Dashboard > Developers > Webhooks

Support​

Last updated on