Easypaisa Payment Gateway

The ECOSIRE Easypaisa Payment Gateway module adds a native Odoo payment.provider for Easypaisa, Pakistan's leading mobile-money and digital-payments platform operated by Telenor Microfinance Bank (TMB) under SBP Branchless Banking Regulations. Customers in Pakistan can pay via their Easypaisa mobile account (OTP), debit/credit card through the Easypaisa-hosted page, or the Easypaisa app -- all from your standard Odoo eCommerce checkout, online invoice payment link, or sales-order payment flow.

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

Try it on the demo

A live demo is available. Contact [email protected] to request access.

Key Features

• Native Odoo payment provider (code = 'easypaisa') -- integrates with eCommerce, invoicing, and sales-order payment links without custom code
• Hosted-redirect card / Easypaisa-app flow (PCI-DSS SAQ-A friendly -- card data never touches your server)
• Mobile-account OTP charge initiation (EP-PAY-01)
• HMAC-SHA256 request signing on every outbound call; merchant secret (hashKey) is stored on the provider record (visible only to Odoo system administrators, never hardcoded)
• Signature-verified asynchronous webhook (postBack) controller -- HMAC verified on arrival, then independently re-confirmed via the inquiry endpoint (EP-INQ-01) before the transaction is marked done; callbacks are never trusted alone
• Idempotent webhook handling -- safe against Easypaisa callback redelivery
• Full refund support (EP-REF-01), where enabled for your merchant tier
• PKR-only currency enforcement -- Easypaisa processes Pakistani Rupees only; the provider is hidden automatically for non-PKR transactions
• Configurable sandbox vs production mode (Test / Enabled) with separate base URLs
• Configurable HMAC field order and hash algorithm (SHA-256 or legacy MD5) to match your merchant kit without a code change

Prerequisites

• Odoo 17, 18, or 19 (Community or Enterprise edition)
• An active ECOSIRE license for ecosire_payment_easypaisa
• A formal merchant agreement with Telenor Microfinance Bank (Easypaisa) -- live payment processing requires a signed merchant contract; sandbox credentials are provided after NDA/agreement signing via the Easypaisa merchant portal
• Python requests library (auto-installed if your server has internet access during install)
• Odoo payment and account modules (both standard -- no Enterprise dependency)

Installation

1. Download the module ZIP from your ECOSIRE Dashboard
2. Extract to your Odoo addons directory:

   unzip ecosire-easypaisa-*.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 | Easypaisa" and click Install
6. Enter your ECOSIRE license key when prompted

Configuration

Step 1: Activate your ECOSIRE license

1. Go to Settings > ECOSIRE License
2. Enter the license key you received from ECOSIRE after purchase
3. Click Activate -- the license must be active before the Easypaisa API will process requests

Step 2: Obtain Easypaisa merchant credentials

Contact the Easypaisa business / integrations team at [email protected] or via the merchant portal to complete integrator onboarding. After agreement signing you will receive:

Credential	Description
Store ID (storeId)	Numeric merchant store identifier
Store Name (storeName)	Merchant store name string
Hash Key (hashKey)	HMAC secret key -- treat as a password
Sandbox base URL	Provided in your sandbox kit (default: https://easypaisasandbox.com/api)
Production base URL	Provided in your production kit (default: https://easypaisa.com.pk/tpg)
Hash algorithm / field order	SHA-256 (v2+) or MD5 (legacy v1); canonical field order for HMAC

Merchant-gated access

Easypaisa's developer portal and sandbox credentials require a signed merchant agreement. The connector's default API base URLs are the values reported in integration guides -- verify them against your merchant kit before going live, as TMB may issue different URLs per merchant tier.

Step 3: Configure the payment provider in Odoo

1. Navigate to Invoicing (or Accounting) > Configuration > Payment Providers
2. Find Easypaisa (created automatically during module install) and click to open
3. Under the Credentials tab, enter your merchant details (visible to Odoo system administrators only):
   • Store ID -- easypaisa_store_id
   • Store Name -- easypaisa_store_name
   • Hash Key (Secret) -- easypaisa_hash_key
4. Verify or update the API URLs tab:
   • Sandbox Base URL -- easypaisa_sandbox_url (used when provider state is Test)
   • Production Base URL -- easypaisa_production_url (used when state is Enabled)
5. Confirm the Hash Algorithm (easypaisa_hash_algorithm): select SHA-256 (v2+) for current API or MD5 (legacy v1) as specified in your merchant kit
6. If your merchant kit specifies a different HMAC canonical field order, update the Hash Field Order (easypaisa_hash_fields) -- comma-separated field names; the default follows the contract's reported ordering
7. Set the provider State:
   • Test -- routes to the sandbox URL; use this during integration testing
   • Enabled -- routes to the production URL; requires a live merchant account

Step 4: Configure webhook and return URLs

Easypaisa requires two URLs registered in your merchant portal or communicated to the Easypaisa integrations team:

URL	Path	Purpose
Return URL (browser redirect)	/payment/easypaisa/return	After hosted-page checkout, the customer's browser returns here
Webhook / postBack URL	/payment/easypaisa/webhook	Easypaisa sends the authoritative async payment result here

Replace yourdomain.com with your Odoo server's public domain, for example:

• Return URL: https://yourodoo.com/payment/easypaisa/return
• Webhook URL: https://yourodoo.com/payment/easypaisa/webhook

Your server must be publicly reachable on HTTPS for Easypaisa to deliver webhook callbacks. The webhook endpoint does not require Odoo login -- it accepts POST requests from Easypaisa's servers.

Usage

Checkout flow (hosted card / Easypaisa app)

1. Customer reaches the payment step in eCommerce checkout, an invoice payment link, or a sales-order payment page
2. Easypaisa appears as a payment option (only for PKR transactions)
3. Customer selects Easypaisa and clicks Pay
4. Odoo calls EP-PAY-02 (/tpg/initiate) with a signed payload; Easypaisa returns a redirectUrl
5. Customer is redirected to the Easypaisa-hosted page to complete card or app payment
6. After payment, the customer's browser returns to /payment/easypaisa/return and then to the Odoo payment status page
7. Easypaisa delivers the authoritative result asynchronously to /payment/easypaisa/webhook; the connector verifies the HMAC signature, re-confirms status via EP-INQ-01, and updates the Odoo transaction to Done or Error

Mobile-account OTP flow

1. Customer selects Easypaisa and enters their registered mobile number (MSISDN)
2. Odoo calls EP-PAY-01 (/tpg/pay) with the customer's mobile number
3. Easypaisa sends an OTP to the customer's phone
4. Customer confirms the OTP in the Easypaisa app or SMS prompt
5. Easypaisa posts the result to the webhook; the connector verifies and updates the transaction

Refunds

1. Open the paid transaction in Invoicing > Accounting > Payments (or from the transaction list under the Easypaisa provider)
2. Click Refund -- the connector calls EP-REF-01 (/tpg/refund) with the original transaction reference
3. Only full refunds are supported (support_refund = 'full_only'); partial refunds require a manual process via the Easypaisa merchant portal
4. Refund availability depends on your merchant tier agreement with Easypaisa

Viewing transaction details

Each Odoo payment transaction created by this connector carries two additional fields:

• Easypaisa Transaction ID -- the gateway reference number returned by Easypaisa
• Easypaisa Mobile Account -- the customer MSISDN used for an OTP-based payment

Find these on the transaction form view under Invoicing > Configuration > Payment Transactions.

API Details

Field	Value
Auth method	HMAC-SHA256 per-request signing (no OAuth2 bearer token)
Sandbox base URL	https://easypaisasandbox.com/api (REPORTED -- verify from merchant kit)
Production base URL	https://easypaisa.com.pk/tpg (REPORTED -- verify from merchant kit)
Hosted payment	POST /tpg/initiate (EP-PAY-02)
OTP payment	POST /tpg/pay (EP-PAY-01)
Status inquiry	POST /tpg/inquire (EP-INQ-01)
Refund	POST /tpg/refund (EP-REF-01)
Webhook (callback)	POST /payment/easypaisa/webhook on your Odoo server
Currency	PKR only
Key config fields	easypaisa_store_id, easypaisa_store_name, easypaisa_hash_key, easypaisa_sandbox_url, easypaisa_production_url, easypaisa_hash_algorithm, easypaisa_hash_fields

Gated features

Two flows are implemented but gated behind a clear UserError until confirmed with Easypaisa:

• QR-code payments (EP-PAY-03) -- requires QR to be enabled for your merchant tier; contact [email protected]
• v2 token-based authentication (EP-AUTH-01) -- unconfirmed flow; this connector uses per-request HMAC signing which is confirmed to work

Troubleshooting

Issue	Likely Cause	Solution
"Easypaisa is not fully configured" error	Store ID, Store Name, or Hash Key is missing	Enter all three credentials on the payment provider record under Credentials
Signature mismatch / response code 09	Hash Key is wrong, or field order / algorithm mismatch	Verify easypaisa_hash_key exactly matches your merchant kit; check easypaisa_hash_algorithm (SHA-256 vs MD5) and easypaisa_hash_fields order
Webhook callback rejected (400 INVALID SIGNATURE)	Easypaisa is sending a different HMAC than expected	Confirm the Hash Key and hash field order with the Easypaisa integration team; check Odoo server logs for the rejected callback details
Transaction stuck in Pending after customer payment	Webhook URL is not reachable by Easypaisa	Ensure your Odoo server is publicly accessible on HTTPS; verify the postBack URL registered with Easypaisa matches /payment/easypaisa/webhook on your domain
"Easypaisa base URL is not configured" error	Production base URL is blank while provider is Enabled	Set easypaisa_production_url from your merchant kit on the provider
Payment option not showing at checkout	PKR currency not selected, or provider is in disabled state	Confirm the invoice / order is in PKR; set provider state to Test or Enabled
"License not active" error	ECOSIRE license not activated or expired	Go to Settings > ECOSIRE License and verify / reactivate your license key
Refund failed	Refunds not enabled for your merchant tier	Contact [email protected] to confirm refund eligibility; for urgent cases use the Easypaisa merchant portal directly
QR payment raises UserError	Feature is merchant-tier gated	Contact Easypaisa to enable QR-code payment for your account
Sandbox URLs not working	Sandbox base URL mismatch	Verify the sandbox URL from your Easypaisa sandbox kit and update easypaisa_sandbox_url on the provider

Support

• General Troubleshooting
• Email: [email protected]
• Support Portal