Telr Payment Gateway

The ECOSIRE Telr Payment Gateway module integrates Odoo with the Telr hosted-payment-page gateway, the leading payment processor across the UAE and the wider MENA region. Customers are redirected to a secure Telr-hosted page for card entry; Odoo never touches raw card data. Payment status is confirmed server-side on every browser return and IPN callback, and full or partial refunds can be issued directly from the Odoo back end.

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

Key Features

• Native Odoo payment-framework integration (payment.provider + payment.transaction — redirect flow)
• order/create — creates a Telr hosted-payment order and redirects the customer to the secure Telr page
• order/check — server-side confirmation of payment state on browser return AND after every IPN (IPN payload alone is never trusted)
• order/refund — full and partial refunds from the Odoo back end without leaving Odoo
• IPN webhook at /payment/telr/ipn with signature verification (SHA-256 or MD5, selectable per merchant account)
• Currency filtering — only AED, SAR, USD, GBP, and EUR are offered to customers; unsupported currencies are silently excluded
• Test vs live toggling via the standard Odoo provider state (Test Mode sends ivp_test=1; Enabled sends ivp_test=0)
• License-enforced credential save — credentials cannot be persisted without an active ECOSIRE license
• Per-model access control and multi-company record isolation

Try the demo

A live demo environment is available at https://demo.ecosire.com. Contact [email protected] to request Telr demo access.

Prerequisites

• Odoo 17, 18, or 19 (Community or Enterprise edition)
• An active ECOSIRE license for ecosire_payment_telr
• A Telr merchant account — live charging requires a real Telr account with an approved store. Apply at telr.com
• Your Telr Store ID (ivp_store) and Auth Key (ivp_authkey) from the Telr merchant portal
• For sandbox / test transactions: a Telr test store (Telr issues separate test store credentials; test store IDs follow a different format from live store IDs)
• The requests Python package (standard in most Odoo deployments; install via pip install requests if missing)

Installation

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

   unzip ecosire-payment-telr-*.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 | Telr" and click Install
6. Enter your ECOSIRE license key when prompted (license activation is required before credentials can be saved)

Configuration

Step 1: Obtain Telr Credentials

1. Log in to the Telr merchant portal
2. Navigate to eCommerce > API integration (exact path may vary by account type)
3. Copy your Store ID — this is the numeric ID assigned to your Telr store
4. Copy your Auth Key — this is the secret key shown on the API credentials page; treat it as a password
5. Note the IPN signature scheme your account uses (SHA-256 or MD5); Telr support can confirm this if unsure
6. If you need a test store, contact Telr support to provision one — test store credentials are separate from live credentials

Step 2: Configure the Payment Provider in Odoo

1. Navigate to Accounting > Configuration > Payment Providers
2. Click New or find and open the Telr provider (created automatically on install)
3. Set the Name (e.g. "Telr — UAE Card Payments")
4. Set State to Test Mode for sandbox testing, or Enabled for live payments
5. Under the Credentials tab (visible to administrators only), enter:
   • Telr Store ID (telr_store_id) — your merchant store ID from the Telr portal
   • Telr Auth Key (telr_auth_key) — your secret auth key; stored encrypted, never logged
6. Set the IPN Signature Scheme (telr_ipn_signature_scheme) to match your Telr account:
   • SHA-256 hash — recommended; use this unless Telr support tells you otherwise
   • MD5 hash — select if your account is configured for MD5 IPN signatures
   • Disabled — not recommended; IPN payloads will still be independently re-checked via order/check, but the hash is not validated
7. Optionally set the IPN Signature Secret (telr_ipn_signature_secret) if your Telr account uses a separate IPN salt or secret distinct from the Auth Key; leave blank to use the Auth Key
8. Save the provider — the ECOSIRE license is verified on save

Step 3: Configure Return and Webhook URLs

Telr requires a return URL (browser redirect on payment completion) and an IPN callback URL (server-to-server notification). The module sets these automatically when a payment order is created, using the following routes on your Odoo domain:

Route	Purpose
/payment/telr/return	Browser redirect on successful payment
/payment/telr/cancel	Browser redirect on cancellation or decline
/payment/telr/ipn	Server-to-server IPN callback (POST)

No manual URL entry is required in Odoo. However, you must ensure these routes are publicly reachable from the internet (not behind a VPN or firewall) so that Telr can deliver IPN callbacks.

If you also configure a callback URL in the Telr merchant portal settings, set it to https://<your-odoo-domain>/payment/telr/ipn. Both the IPN URL registered at order creation and this portal-level URL are processed identically.

Step 4: Verify the Integration

1. Go to Website > eCommerce (or any Odoo checkout flow) and add an item to the cart
2. Proceed to checkout and select Telr as the payment method
3. You will be redirected to the Telr-hosted page
4. Use Telr's test card numbers (available from Telr support / developer docs at docs.telr.com) to complete a test transaction
5. After payment, you will be redirected back to /payment/status
6. Confirm the payment transaction record in Accounting > Payment > Transactions shows state Done

Payment Flow

The integration follows the Odoo redirect-provider pattern:

1. Checkout — the customer selects Telr and clicks Pay; Odoo calls POST /gateway/order/create with the amount, currency, cart reference, return/cancel/IPN URLs, and the Telr credentials
2. Redirect — Telr returns a hosted-page URL (order.url); Odoo redirects the customer's browser to this Telr-hosted page
3. Customer pays — the customer enters card details on the Telr-hosted page; no card data ever reaches Odoo
4. Return — on completion (success or decline) the browser is redirected back to /payment/telr/return or /payment/telr/cancel
5. Server-side check — the return controller calls POST /gateway/order/check using the cart reference; the response from Telr is authoritative for the final payment state (never the browser-forwarded parameters alone)
6. IPN — Telr also sends a server-to-server IPN to /payment/telr/ipn; the module verifies the ivp_hash signature, then calls order/check again to confirm state before updating the transaction
7. Done — Odoo sets the payment.transaction to done (status A), cancel (status D or V), or error (status E); pending is set for status H (on hold / pending review)

Refunds

To refund a captured payment:

1. Open the relevant invoice or payment record in Odoo
2. Click Refund (or issue a credit note and register the refund via the standard Odoo flow)
3. The module calls POST /gateway/order/refund with the original transaction reference and the refund amount
4. Partial refunds (amount less than the original captured amount) are supported

API Details

Field	Value
Auth method	Store ID + Auth Key posted as form fields (ivp_store / ivp_authkey)
Live endpoint	https://secure.telr.com
Test endpoint	https://secure.telr.com (same host; test vs live is controlled by credentials and ivp_test)
Create order	POST /gateway/order/create
Check status	POST /gateway/order/check
Refund	POST /gateway/order/refund
IPN callback (inbound)	POST /payment/telr/ipn on your Odoo domain
Supported currencies	AED, SAR, USD, GBP, EUR
Key provider fields	telr_store_id, telr_auth_key, telr_ipn_signature_scheme, telr_ipn_signature_secret

Supported Payment Methods

The following payment methods are available via the Telr hosted page, subject to your merchant account configuration with Telr:

Method	Region	Notes
Visa / Mastercard / Amex	Global	Standard card payment
mada	Saudi Arabia	Saudi domestic debit scheme; requires Telr mada enablement
Apple Pay	UAE / KSA	Enabled per Telr merchant account
Samsung Pay	UAE / KSA	Enabled per Telr merchant account
STC Pay	Saudi Arabia	Saudi Telecom digital wallet; enabled per account
Telr Wallet	MENA	Telr stored-value wallet

PK wallet note

JazzCash and Easypaisa (Pakistan) are integrator-gated on the Telr side and require a separate onboarding process with Telr before they are available. These methods are not exposed by default in this module. Contact [email protected] if you need PK wallet support.

Features gated behind verified merchant API reference

The following flows are documented blocking-unknowns in the ECOSIRE Telr API contract. They raise a clear UserError until the verified Telr merchant API reference is supplied per-account:

• Two-step authorize / capture / void (auth-only at booking, capture at checkout)
• Tokenisation / recurring payments (subscription billing with stored card tokens)

If your use case requires either of these, contact [email protected].

Troubleshooting

Issue	Solution
License error on saving credentials	Verify your ECOSIRE license at Settings > ECOSIRE License; the license must be active before credentials can be saved
IPN signature verification FAILED in logs	The IPN Signature Scheme setting does not match your Telr account configuration; check with Telr support whether your account uses SHA-256 or MD5 and update the provider accordingly
Payment stuck in Pending after return	The order/check call could not confirm status A; check Odoo server logs for a Telr gateway error; also verify the Store ID and Auth Key are for the correct environment (test vs live)
Currency not offered at checkout	Only AED, SAR, USD, GBP, and EUR are supported; the Telr provider is automatically hidden for other currencies
Test transactions charge real money	The State is set to Enabled instead of Test Mode, or live credentials are entered instead of test credentials; switch to Test Mode and use Telr test store credentials
Could not reach the Telr gateway	Network connectivity issue between Odoo server and secure.telr.com; verify firewall rules and that outbound HTTPS is allowed
Telr gateway error: ... in UI	The Telr API returned an error envelope; the error message is displayed verbatim; common causes are incorrect Store ID, expired Auth Key, or invalid amount
Refund declined	The original transaction must be in captured (status A) state; voided or already-refunded transactions cannot be re-refunded; partial refunds must not exceed the captured amount
IPN not received	Ensure /payment/telr/ipn is reachable from the internet (not behind a VPN); verify the callback URL is set on the Telr provider or passed in ivp_callbackurl

Support

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