Skip to main content

PayTabs Payment Gateway

The ECOSIRE PayTabs module integrates Odoo's native payment framework with the PayTabs PT2 REST API, giving merchants in Saudi Arabia, UAE, Egypt, Jordan, Oman, Bahrain, Kuwait, Pakistan, Iraq, and globally a fully compliant checkout experience. Customers pay on a PayTabs-hosted page (SAQ-A PCI scope -- no card data ever passes through Odoo), and every inbound IPN callback is verified with HMAC-SHA256 before any transaction state changes.

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

Key Features​

  • Hosted Payment Page (HPP) checkout -- SAQ-A PCI scope, card data never touches Odoo
  • Region-aware base URL routing: 10 regions each with a dedicated PayTabs endpoint (SA, AE, EG, JO, OM, BH, KW, PK, IQ, Global)
  • Server-key authentication per region -- region-specific, never portable across regions
  • HMAC-SHA256 IPN callback signature verification on the raw request body before any state change
  • Full and partial refund support (tran_type=refund)
  • Manual capture and void of authorizations (tran_type=capture / void)
  • Recurring / token-based charges for Odoo Subscriptions (tran_class=recurring)
  • Payment methods: Visa, Mastercard, AMEX, Mada (KSA), Meeza (Egypt), Apple Pay, Google Pay (subject to merchant dashboard activation)
  • Currency filtering -- checkout list automatically hides PayTabs for unsupported currencies
  • Works everywhere Odoo payment is used: eCommerce, Invoicing, Sales, Subscriptions

Prerequisites​

  • Odoo 17, 18, or 19 (Community or Enterprise edition)
  • An active ECOSIRE license for this module
  • A live PayTabs merchant account in your target region
  • Profile ID and Server Key from the PayTabs dashboard (Developers > API Credentials)
  • Your Odoo instance must be reachable from the internet for IPN callbacks to function
Live charges require a real merchant account

The Test mode in Odoo allows configuration and sandbox flows. To process real payments, you need an approved PayTabs merchant account for your region. PK local wallets (JazzCash / Easypaisa) are integrator-gated and require separate onboarding with PayTabs Pakistan -- they are not part of the generic PT2 API.

Installation​

  1. Download the module ZIP from your ECOSIRE Dashboard
  2. Extract to your Odoo addons directory: 
    unzip ecosire-payment-paytabs-*.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 PayTabs" and click Install
  6. Enter your ECOSIRE license key when prompted (Settings > ECOSIRE License)

Configuration​

Step 1: Obtain PayTabs Credentials​

  1. Log in to your PayTabs Merchant Dashboard (or the region-specific portal for SA, EG, JO, etc.)
  2. Go to Developers > API Credentials
  3. Copy your Profile ID (numeric) and Server Key (alphanumeric string)
  4. Note which region the account belongs to -- the server key is bound to exactly one region endpoint and is not portable across regions

Step 2: Configure the Payment Provider in Odoo​

  1. Navigate to Accounting > Configuration > Payment Providers
  2. Find PayTabs in the list (installed by the module) and click to open it
  3. Set the following fields:
FieldDescription
paytabs_regionSelect your merchant region (SA, AE, EG, JO, OM, BH, KW, PK, IQ, or Global)
paytabs_profile_idNumeric Profile ID from the PayTabs dashboard
paytabs_server_keyMerchant Server Key -- visible to Odoo administrators only
  1. Set the State to Test during initial setup; switch to Enabled after verifying a sandbox payment
  2. Click Publish if you want the provider to appear on your eCommerce checkout

Step 3: Configure Webhook and Return URLs​

PayTabs needs two URLs from your Odoo instance configured in the PayTabs merchant dashboard under Developers > IPN / Callback Settings:

URL TypePath
Return URL (browser redirect)https://<your-odoo-domain>/payment/paytabs/return
IPN Callback URL (server-to-server)https://<your-odoo-domain>/payment/paytabs/callback

The IPN callback URL is the authoritative source of truth: every callback is verified using HMAC-SHA256 over the raw request body with your Server Key as the secret. The connector rejects any callback that fails signature verification with HTTP 400 before touching any transaction record.

Signature verification

The Server Key you enter in Odoo is used both for API authentication (sent as the authorization header on every outbound request) and for verifying incoming IPN signatures. Keep the same Server Key in both places -- mismatches cause all callbacks to be rejected.

Step 4: Test the Integration​

  1. With State set to Test, place a test order on your eCommerce or create a test invoice payment
  2. PayTabs will redirect to the HPP; use PayTabs sandbox card numbers from the PayTabs testing guide
  3. After payment, the customer is redirected back to /payment/paytabs/return, which re-confirms status via POST /payment/query
  4. Verify the transaction appears as Done in Accounting > Payments
  5. Once confirmed, change the provider State to Enabled for live transactions

Usage​

Checkout Flow​

  1. Customer selects PayTabs at checkout (eCommerce, invoice payment link, or Sales order)
  2. Odoo creates a payment transaction and calls POST /payment/request with tran_type=sale, tran_class=ecom to create a Hosted Payment Page session
  3. Customer is redirected to the PayTabs HPP and enters card details there
  4. PayTabs processes the payment and sends an IPN callback to /payment/paytabs/callback
  5. Odoo verifies the HMAC-SHA256 signature, then calls POST /payment/query to confirm final status
  6. Transaction state is updated (Done, Error, Pending, or Voided) and the customer is redirected to /payment/status

Refunds​

  1. Open the payment transaction or invoice in Odoo
  2. Click Refund and enter the amount (full or partial)
  3. Odoo calls POST /payment/request with tran_type=refund referencing the original tran_ref
  4. Refunds appear in Accounting > Payments with the source transaction linked

Manual Capture / Void​

For authorization-only flows configured at the PayTabs account level:

  1. Authorized transactions appear with status Authorized in Odoo
  2. Click Capture to settle funds -- Odoo sends tran_type=capture
  3. Click Void to release the hold -- Odoo sends tran_type=void

Recurring / Subscription Charges​

When Odoo Subscriptions generates a renewal charge for a customer with a saved PayTabs token, the connector sends POST /payment/request with tran_class=recurring using the stored token reference. No HPP redirect is needed for subsequent charges.

API Details​

FieldValue
Auth methodServer Key in authorization header (per-region, from merchant dashboard)
Create / capture / void / refundPOST /payment/request (region base URL + /payment/request)
Query transaction statusPOST /payment/query (region base URL + /payment/query)
IPN inbound routePOST /payment/paytabs/callback on your Odoo domain
Return routeGET/POST /payment/paytabs/return on your Odoo domain
Signature schemeHMAC-SHA256 over raw IPN body; secret = Server Key
Key config fieldspaytabs_region, paytabs_profile_id, paytabs_server_key

Region Endpoints​

RegionBase URL
Saudi Arabiahttps://secure.paytabs.sa
UAE / Globalhttps://secure.paytabs.com
Egypthttps://secure-egypt.paytabs.com
Jordanhttps://secure-jordan.paytabs.com
Omanhttps://secure-oman.paytabs.com
Bahrainhttps://secure-bahrain.paytabs.com
Kuwaithttps://secure-kuwait.paytabs.com
Pakistanhttps://secure-pakistan.paytabs.com
Iraqhttps://secure-iraq.paytabs.com

Supported Currencies​

SAR, AED, EGP, JOD, OMR, BHD, KWD, PKR, IQD, USD, EUR, GBP. Transactions in other currencies will not show PayTabs as an option at checkout.

Troubleshooting​

IssueSolution
Signature mismatch / IPN rejected with 400Confirm the Server Key in Odoo's payment provider matches exactly the one in the PayTabs dashboard. Check that your Odoo base URL is HTTPS and accessible from PayTabs servers
"PayTabs is not configured" error at checkoutProfile ID or Server Key is blank on the provider record. Open Accounting > Configuration > Payment Providers > PayTabs and fill both fields
PayTabs not visible at checkoutCheck provider State is Enabled (not Test or Disabled) and that the currency of the transaction is in the supported list
Payment approved but transaction stays PendingThe IPN callback has not been received or failed verification. Check the IPN Callback URL in the PayTabs dashboard matches your Odoo URL exactly. Review Odoo server logs for "IPN signature verification FAILED"
HTTP error from PayTabs (e.g. 401)Wrong Server Key or mismatched region. The server key is bound to a single region -- ensure paytabs_region in Odoo matches your merchant account region
Refund failsRefunds require the original tran_ref. Verify the original transaction has status Approved (status code A) in PayTabs before attempting a refund
JazzCash / Easypaisa not appearingPK local wallets require integrator-gated onboarding with PayTabs Pakistan and are not exposed through the generic PT2 API. Contact PayTabs Pakistan support to enable them on your merchant account
License not activeVerify your ECOSIRE license key at Settings > ECOSIRE License or contact [email protected]

Support​

Last updated on