JazzCash Payment Gateway
The ECOSIRE JazzCash Payment Gateway module integrates JazzCash — Pakistan's leading mobile-money and card payment gateway (operated by Jazz, a Veon subsidiary) — directly into Odoo's native payment framework. Customers at checkout are redirected to the JazzCash hosted page where they can pay by card, mobile wallet (MWALLET), or over-the-counter (OTC) at a Jazz franchise. The module handles HMAC-SHA256 SecureHash signing server-side, verifies every IPN notification with constant-time comparison, and maps JazzCash response codes to Odoo transaction states automatically.
Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: Up to 3 domain activations
Explore the module live at demo.ecosire.com before purchasing.
Key Features
- Native
payment.providerintegration — no third-party bridge required - Hosted-checkout redirect flow (card, JazzCash wallet, OTC on a single JazzCash page)
- HMAC-SHA256
SecureHashcomputed server-side only — never exposed to the browser or logs - IPN webhook (
/payment/jazzcash/ipn) with constant-time signature verification - Return-URL handler (
/payment/jazzcash/return) for synchronous browser redirect - Idempotent notification processing —
pp_TxnRefNode-duplication prevents double-posting on IPN retries - PKR currency enforcement — JazzCash is hidden automatically for non-PKR transactions
- Test/Sandbox vs Production switching via Odoo provider state
- Configurable endpoint paths — verify and adjust base URLs and API paths against your merchant integration guide
- Full ECOSIRE license enforcement via
ecosire_license_client
Prerequisites
- Odoo 17, 18, or 19 (Community or Enterprise edition)
- An active ECOSIRE license for this module
- A JazzCash merchant account (contact Jazz Business / merchant services at jazzcash.com.pk/business/merchant-services for onboarding)
- Merchant credentials obtained from Jazz during onboarding: Merchant ID, API Password, and Integrity Salt
- Your Odoo site must be accessible over HTTPS so JazzCash can deliver IPN notifications
JazzCash integrator documentation is gated behind a merchant account and NDA with Jazz. Sandbox credentials are also distributed during onboarding — there is no publicly accessible test account. Contact Jazz to start onboarding before configuring this module for production use.
Installation
- Download the module ZIP from your ECOSIRE Dashboard
- Extract to your Odoo addons directory:
unzip ecosire-payment-jazzcash-*.zip -d /opt/odoo/addons/ - Restart the Odoo service:
sudo systemctl restart odoo - Navigate to Apps, click Update Apps List
- Search for "ECOSIRE Payment | JazzCash" and click Install
- Enter your ECOSIRE license key when prompted under Settings > ECOSIRE License
Configuration
Step 1: Activate Your ECOSIRE License
- Go to Settings > ECOSIRE License
- Enter the license key you received after purchase and click Activate
- A green status indicator confirms the license is active
- Without an active license, writing to the JazzCash provider record is blocked
Step 2: Open the JazzCash Payment Provider
- Navigate to Accounting > Configuration > Payment Providers (or Website > Configuration > Payment Providers if using eCommerce)
- Locate JazzCash in the list and click to open it
- All credential fields are restricted to the System group (base.group_system); log in as an administrator
Step 3: Enter Merchant Credentials
All three fields are required and are stored server-side only — they are never written to JS or logs:
| Field | Description | Where to find it |
|---|---|---|
jazzcash_merchant_id — Merchant ID | Your pp_MerchantID assigned by Jazz during onboarding | JazzCash merchant welcome email or portal |
jazzcash_password — API Password | The API credential (pp_Password) — NOT your Jazz portal login password | JazzCash merchant integration guide (PDF) |
jazzcash_integrity_salt — Integrity Salt | The HMAC secret used to compute pp_SecureHash; keep strictly server-side | JazzCash merchant integration guide (PDF) |
Step 4: Verify Endpoint Paths
The module ships with community-corroborated default paths. JazzCash's authoritative integration PDF is distributed to registered merchants and is the definitive source. Check these fields against your integration guide and correct them if your merchant account uses different paths:
| Field | Default value |
|---|---|
| Sandbox Base URL | https://sandbox.jazzcash.com.pk |
| Production Base URL | https://payments.jazzcash.com.pk |
| Hosted Checkout Path | /ApplicationAPI/API/2.0/Purchase/SecuredHashPost |
| Transaction Inquiry Path | /ApplicationAPI/API/2.0/Purchase/DoTransactionInquiry |
| Refund Path | /ApplicationAPI/API/2.0/Purchase/DoRefundTransaction |
| SecureHash Separator | & (ampersand) — change to ` |
Step 5: Set Provider State (Test vs Live)
- Test — connects to
https://sandbox.jazzcash.com.pkusing your sandbox credentials (obtained during merchant onboarding); no real money moves - Enabled — connects to the production URL and charges real PKR amounts
Set the state on the provider form. The module automatically selects the correct base URL based on this setting.
Step 6: Configure IPN and Return URLs in the JazzCash Merchant Portal
Log in to your JazzCash merchant portal and set:
| Setting | Value |
|---|---|
| IPN / Notification URL | https://<your-domain>/payment/jazzcash/ipn |
| Return URL (pp_ReturnURL) | Sent per-transaction by Odoo; also set https://<your-domain>/payment/jazzcash/return as the fallback |
JazzCash will POST the transaction result to both the IPN URL (asynchronously, server-to-server) and the Return URL (synchronously, via the customer's browser). Both are verified with pp_SecureHash before Odoo updates any financial state.
Usage
Checkout Flow
- Customer adds items to cart and proceeds to checkout
- JazzCash appears in the payment method selector (only for PKR-denominated orders)
- Customer selects JazzCash and clicks Pay Now
- Odoo builds the
SecuredHashPostparameter set, computespp_SecureHashserver-side, and redirects the customer's browser to the JazzCash hosted page - On the JazzCash page, the customer chooses card, mobile wallet (MWALLET), or OTC and completes payment
- JazzCash redirects the customer back to
/payment/jazzcash/returnand separately sends an IPN POST to/payment/jazzcash/ipn - Odoo verifies the
pp_SecureHash, mapspp_ResponseCodeto a transaction state, and confirms or cancels the order
Transaction States
JazzCash pp_ResponseCode | Odoo Transaction State |
|---|---|
000 | Done (confirmed) |
121 | Pending (payment processing) |
115 | Cancelled (insufficient balance) |
197 | Cancelled (transaction expired) |
200 | Cancelled (invalid mobile number) |
400 | Cancelled (declined) |
157, 09 | Error (duplicate or system error) |
Refunds
The JazzCash refund API path (DoRefundTransaction) is gated behind merchant-tier agreements and not universally available. The module exposes the refund path as a configurable field. If your merchant account supports API refunds, configure the correct path and initiate refunds from the Odoo payment transaction form. If not, process refunds from your JazzCash merchant portal and reconcile manually in Odoo by registering a credit note.
API Details
| Field | Value |
|---|---|
| Auth method | HMAC-SHA256 (pp_SecureHash) over sorted pp_* parameter values |
| Sandbox URL | https://sandbox.jazzcash.com.pk (configurable) |
| Production URL | https://payments.jazzcash.com.pk (configurable) |
| Hosted checkout path | /ApplicationAPI/API/2.0/Purchase/SecuredHashPost (configurable) |
| Odoo IPN route | /payment/jazzcash/ipn |
| Odoo return route | /payment/jazzcash/return |
| Currency | PKR only |
| Amount format | Paisa (PKR × 100, integer — e.g. PKR 100 = 10000) |
| Key credential fields | jazzcash_merchant_id, jazzcash_password, jazzcash_integrity_salt |
JazzCash does not publish a publicly crawlable API reference. All default endpoint paths in this module are derived from community integration patterns and expert knowledge, not a verified public spec. Always cross-check the paths above against the integration PDF distributed by Jazz during merchant onboarding, and update the configurable fields on the provider record if they differ.
Troubleshooting
| Issue | Solution |
|---|---|
| "JazzCash Integrity Salt is not configured" | Enter the Integrity Salt on the provider form under the Credentials tab; all three merchant credential fields are required |
| SecureHash mismatch on IPN | Confirm the Integrity Salt and SecureHash Separator match your JazzCash integration guide exactly; a single wrong character breaks the HMAC |
| JazzCash not appearing at checkout | Confirm the order currency is PKR; JazzCash is automatically hidden for all other currencies |
| Sandbox payments failing | Confirm the provider state is set to Test and that you are using sandbox credentials (not your production Merchant ID); sandbox credentials are provided separately by Jazz during onboarding |
pp_ResponseCode 157 — Duplicate transaction | The pp_TxnRefNo was already used; Odoo generates unique references but if a transaction was partially created, reset or cancel it before retrying |
pp_ResponseCode 09 — System error | Transient error on the JazzCash side; retry after a short delay; if persistent, contact Jazz merchant support |
| IPN not received / order stays Pending | Verify the IPN URL https://<your-domain>/payment/jazzcash/ipn is publicly reachable over HTTPS; check your server firewall and Nginx/Apache configuration; JazzCash retries IPN up to 3 times |
| Refund raises UserError | Your merchant tier may not support API refunds; process the refund from the JazzCash merchant portal and reconcile in Odoo with a credit note |
| License not active | Verify your ECOSIRE license key under Settings > ECOSIRE License; writing to the JazzCash provider is blocked without an active license |
| Currency symbol missing / PKR not found | Activate the PKR currency in Accounting > Configuration > Currencies |