Skip to main content

Multi-Gateway Payment Manager

The ECOSIRE Multi-Gateway Payment Manager is a premium orchestration layer that sits on top of Odoo's native payment framework (payment.provider / payment.transaction). It works generically with any enabled payment provider -- Stripe, Adyen, Mollie, PayPal, Authorize.Net, or any ECOSIRE gateway connector -- without hard-depending on any single gateway module. The module decides which provider handles a charge and gives finance a single pane of glass across all of them.

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

Try it on the demo

Explore the module live at demo.ecosire.com before purchasing.

Key Features​

  • Smart routing rules -- choose the best provider per transaction by amount range, currency, country, and payment method; priority-ordered and company-scoped
  • Provider failover chains -- ordered fallback so a disabled or declining provider automatically rolls over to the next eligible one
  • Routing simulator -- test a scenario (amount, currency, country, payment method) and see which provider would be selected without creating a real transaction
  • Unified reconciliation -- one cross-provider view of every payment.transaction with gross / fee / net columns and a workflow (Draft, In Progress, Reconciled)
  • Per-provider fee analytics -- OWL + Chart.js dashboard showing effective fee %, success/decline rates, volume trend, and provider mix
  • Webhook signature verifier -- generic constant-time HMAC helper (SHA-256 / SHA-1 / SHA-512) any gateway connector can route inbound webhooks through
  • Fee model on providers -- configure percentage + fixed fee per provider; the module computes estimated fee and net amount on every transaction automatically
  • Multi-company scoped -- all operational models carry company_id with record rules; routing rules and failover chains are company-isolated
  • License enforcement -- ECOSIRE license gate on routing and smart-charge entry points

How it works (orchestrator, not connector)​

This module has no external API contract. It never calls a gateway API itself. Individual gateway connectors (Stripe, Adyen, etc.) each own their own API calls. This module is the conductor: it selects which provider should handle a charge and aggregates the transaction data Odoo's native payment framework already records.

payment.routing.rule       -> selects payment.provider for a transaction
payment.failover.chain     -> ordered fallback provider list
payment.transaction        -> +fee/net/recon columns, ecosire_create_routed_transaction()
payment.reconciliation.session/line -> cross-provider settlement view
payment.webhook.verifier   -> generic HMAC verify() for inbound webhooks

Prerequisites​

  • Odoo 17, 18, or 19 (Community or Enterprise edition)
  • An active ECOSIRE license for this module (ecosire_payment_manager)
  • At least one Odoo payment provider enabled (Stripe, Adyen, Mollie, PayPal, Authorize.Net, or any other payment.provider-compatible gateway)
  • For live charging: a real merchant account with each provider you intend to route to -- this module does not create gateway merchant accounts

Installation​

  1. Download the module ZIP from your ECOSIRE Dashboard
  2. Extract to your Odoo addons directory: 
    unzip ecosire-multi-gateway-payment-manager-*.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 Multi-Gateway Payment Manager" and click Install
  6. Enter your ECOSIRE license key when prompted at Settings > ECOSIRE License

Configuration​

Step 1: Activate your ECOSIRE license​

  1. Navigate to Settings > ECOSIRE License
  2. Enter the license key from your ECOSIRE Dashboard
  3. Click Activate and confirm the module shows Active

The routing engine (payment.routing.rule.route) and the smart-charge entry point (ecosire_create_routed_transaction) are both license-gated and will raise an error until the license is active.

Step 2: Configure fee models on your providers​

  1. Go to Payment Manager > Configuration > Providers (or Payment > Configuration > Payment Providers)
  2. Open a provider record (e.g. Stripe)
  3. On the ECOSIRE tab fill in:
    • Fee % (ecosire_fee_percent) -- per-transaction percentage fee charged by the provider (e.g. 2.9 for 2.9 %)
    • Fixed Fee (ecosire_fee_fixed) -- flat amount added per transaction (e.g. 0.30 for $0.30)
    • Fee Currency -- currency for the fixed fee (defaults to company currency)
  4. Optionally configure webhook verification (see Step 4 below)
  5. Repeat for each provider

These values drive the fee/net columns on every transaction and the analytics dashboard. They are informational (set by finance based on your gateway contract) -- the module does not retrieve fee data from gateway APIs.

Step 3: Create routing rules​

  1. Go to Payment Manager > Configuration > Routing Rules and click New
  2. Fill in the rule:
    • Name -- a descriptive label (e.g. "High-value EUR to Adyen")
    • Sequence -- lower runs first; the first matching active rule wins
    • Target Provider -- the payment.provider to route to when this rule matches
    • Min Amount / Max Amount -- inclusive amount band (leave 0 for no bound)
    • Currency -- match only this currency (leave blank for any)
    • Countries -- match the partner's country (leave empty for any)
    • Payment Methods -- match specific methods (leave empty for any)
    • Failover Chain -- optional: if the target provider is unavailable, fall back to this chain
  3. Save and set Active to True
  4. Create additional rules as needed; they are evaluated in sequence order

Tip: A rule with no conditions (all fields blank) acts as a catch-all default route. Place it at a high sequence number (e.g. 99) to serve as fallback.

Step 4: Set up failover chains​

  1. Go to Payment Manager > Configuration > Failover Chains and click New
  2. Name the chain (e.g. "Primary Fallback")
  3. Add Provider Lines in order of preference: set a sequence and select the provider
  4. Each line shows the current provider state (Enabled / Test / Disabled) in read-only
  5. Attach the chain to a routing rule's Failover Chain field

When the routing engine selects a provider that is not in enabled or test state, the failover chain yields the next eligible provider. If no chain is configured and no eligible provider exists, the system raises a UserError rather than silently failing.

Step 5: Configure webhook signature verification (optional)​

If a gateway connector routes inbound webhook payloads through the generic verifier:

  1. Open the provider record
  2. On the ECOSIRE tab set:
    • Webhook Secret (ecosire_webhook_secret) -- the shared secret your gateway portal gives you (visible to System Administrator group only)
    • Webhook Algorithm -- HMAC-SHA256 (default), HMAC-SHA1, or HMAC-SHA512
  3. The verifier strips a leading algo= prefix that some gateways prepend to the signature header before comparing
Webhook URL and return URL

This module is an orchestrator -- it does not register its own webhook or return URL. Each gateway connector registers its own /payment/<provider>/webhook and /payment/<provider>/return routes. Configure those URLs in your gateway merchant portal as directed by the individual connector's documentation.

Step 6: Test with the routing simulator​

  1. Go to Payment Manager > Configuration > Test Routing (or click Test Routing from the Routing Rules list)
  2. Enter a scenario: amount, currency, country, payment method
  3. Click Simulate to see which provider the engine would select
  4. No real transaction is created

Usage​

Processing a payment via the routing engine​

When a connector or custom code calls payment.transaction.ecosire_create_routed_transaction(vals):

  1. If provider_id is not supplied in vals, the routing engine evaluates rules in sequence and returns the first matching enabled provider
  2. If the selected provider is not in enabled or test state, the failover chain (if configured) yields the next eligible one
  3. A draft payment.transaction is created with the selected provider, the matched routing rule reference (ecosire_routed_by_rule_id), and a ecosire_failover_used flag
  4. The gateway connector's own code then performs the actual API call to capture the charge

For standard Odoo checkout flows (website payment, invoice payment), the existing Odoo payment widget continues to work unchanged. The routing engine is an additional entry point for programmatic or multi-gateway scenarios.

Reconciliation sessions​

  1. Go to Payment Manager > Reconciliation
  2. Click New, give the session a name, set Date Start and Date End
  3. Click Collect Transactions -- the session snapshots all payment.transaction records in the period (across all providers) and builds per-provider summary lines showing: gross, fee, net, transaction count, success count, effective fee %, and success rate
  4. Review each provider line and mark individual transactions as Matched or flag Discrepancies
  5. Click Mark as Reconciled to set the session to Done and stamp all pending transactions as matched

Analytics dashboard​

Go to Payment Manager > Dashboard to view:

  • KPI row -- Gross volume, total fees, net volume, transaction count, overall success rate, and number of active providers for the selected period
  • Provider breakdown table -- per-provider gross / fee / net / count / success rate / effective fee %
  • Volume trend chart -- daily gross volume line chart over the selected period
  • Period selector -- 7, 30, 90 days (configurable via the period parameter to /ecosire_payment_manager/dashboard_data)

Troubleshooting​

IssueSolution
"No eligible payment provider could be routed"No routing rule matched and no enabled provider exists as fallback. Check that at least one provider is in enabled or test state and create a catch-all routing rule.
"Provider X is unavailable and no failover provider is configured"The matched provider is disabled. Either re-enable it, add it to a failover chain with an alternative, or create a routing rule that points to an available provider.
License error on routing or smart-chargeActivate your ECOSIRE license at Settings > ECOSIRE License. The routing engine and smart-charge entry point are license-gated.
Fee and net amounts show 0.00Set Fee % and/or Fixed Fee on the provider record. The module computes fees from these fields -- it does not fetch fee data from the gateway API.
Webhook signature verification returns FalseCheck that Webhook Secret on the provider matches the secret in your gateway portal exactly. Some gateways prepend sha256= -- the verifier strips this automatically. Ensure the raw request body (before JSON parsing) is passed as the payload.
Reconciliation session shows wrong totalsCheck the date range. Transactions are matched on create_date. If the provider's time zone differs, adjust the date range by one day.
Dashboard shows no dataEnsure transactions exist for the selected period and company. The dashboard endpoint filters by the active company; switch companies if needed.
Routing rule is not matchingRun the routing simulator (Payment Manager > Configuration > Test Routing) with the exact amount, currency, and country to see which rule matches and why.

Support​

Last updated on