QRoute — Payment Orchestration

QRoute is the payment-orchestration layer of the QoinPay Enterprise suite. Where QGate handles acquiring against a single downstream processor, QRoute decides which processor, acquirer, or rail each transaction should use — and what to do when the first choice is unavailable or uneconomic. It runs on your own infrastructure under a perpetual license and sits alongside QGate as the routing brain of your payments estate.

This article covers what QRoute orchestrates, its routing strategies, failover behavior, per-tenant policies, and capability profiles. QRoute is entitled and activated like every other module; see the licensing lifecycle documentation for how editions and features are keyed.

Why orchestration

Enterprises rarely rely on a single acquirer. Multiple acquiring relationships exist for redundancy, for better economics in different regions or card brands, and to meet local processing requirements. Without orchestration, that choice is hard-coded in application logic and expensive to change. QRoute externalizes the decision into a policy engine so that adding an acquirer, shifting volume, or reacting to an outage is a configuration change — not a code deployment.

QRoute runs on your infrastructure alongside QGate, orchestrating across acquirers and rails.

The routing decision

When a transaction arrives, QRoute evaluates it against an ordered set of routing rules and produces a candidate list: the acquirers or rails eligible to process it, ranked by the active strategy. QGate then attempts the ranked candidates in order until one succeeds or the list is exhausted. Three strategies can be combined:

Least-cost routing (LCR) — ranks candidates by the effective cost of processing the specific transaction, accounting for interchange band, scheme fees, acquirer markup, currency, and any negotiated tiers. LCR is what most enterprises adopt first, because it directly reduces cost of acceptance.
Health-based routing — continuously scores each acquirer connector on live signals: authorization rate, latency, timeout ratio, and error codes. Degraded acquirers are down-ranked or temporarily removed from candidate lists before customers feel the impact.
Capability routing — filters candidates to those that actually can process the transaction: the right card brand, currency, payment method, 3DS version, or region.

Strategies are layered: capability filtering first (hard constraints), then health scoring (avoid the sick), then least-cost ordering (optimize the survivors).

// config/qroute.php — strategy stack
return [
    'strategy' => ['capability', 'health', 'least_cost'],
    'health' => [
        'window_seconds'   => 300,
        'min_auth_rate'    => 0.80,
        'max_timeout_ratio'=> 0.05,
        'eject_after'      => 5,   // consecutive failures
        'recover_probe'    => 30,  // seconds before half-open retry
    ],
];

Failover

Failover is the runtime consequence of the candidate list. When an authorization attempt against the top candidate fails with a retryable condition — a timeout, a connector error, or a soft decline that scheme rules permit re-attempting — QRoute advances to the next candidate. Hard declines (insufficient funds, stolen card, do-not-honor) are never retried across acquirers, because re-presenting them wastes fees and can trip scheme re-submission limits.

Health scoring and failover reinforce each other. A connector that begins timing out is ejected by the circuit breaker after the configured threshold, moves to a half-open state after the recovery probe interval, and is only restored to full rotation once probe traffic succeeds. This prevents a struggling acquirer from absorbing repeated failed attempts.

Per-tenant policies

In multi-tenant deployments — a payment facilitator, a group treasury serving many subsidiaries, or a SaaS platform serving merchants — routing must differ by tenant. QRoute scopes every policy to a tenant so that one subsidiary can prioritize a regional acquirer while another optimizes purely for cost, all within the same installation.

PUT /api/v1/routing/policies/tenant_acme
{
  "strategy": ["capability", "least_cost"],
  "pin": {
    "amex": "acquirer_global_1"
  },
  "exclude": ["acquirer_legacy_x"],
  "fallback": "acquirer_global_2"
}

Policies support pinning (force a brand or method to a named acquirer), exclusion (never route a tenant to a given connector), and an explicit fallback of last resort. Policy changes are versioned and take effect without restarting the gateway.

Capability profiles

A capability profile is the declarative description of what an acquirer connector can do: supported card brands and networks, settlement currencies, payment methods, 3DS versions, MCC restrictions, per-transaction limits, and supported regions. QRoute uses these profiles to build the capability filter at the top of the strategy stack. Keeping capabilities in a profile — rather than in code — means onboarding a new acquirer is a matter of registering its connector and publishing its profile.

POST /api/v1/routing/connectors
{
  "id": "acquirer_global_2",
  "profile": {
    "brands": ["visa", "mastercard"],
    "currencies": ["USD", "EUR", "GBP"],
    "methods": ["card"],
    "threeds": ["2.2.0"],
    "regions": ["EU", "UK", "US"],
    "max_amount": 1000000
  }
}

Editions and deployment

QRoute is licensed with the acquiring stack. Least-cost and capability routing are available in the base entitlement; health-based routing, circuit breaking, and multi-tenant policy scoping are Enterprise-tier capabilities that pair with QGate Enterprise. Deploy QRoute as a stateless service co-located with QGate so routing decisions add negligible latency to the authorization path; the routing configuration and health state are shared through the same MariaDB cluster.

For the acquiring and settlement mechanics that QRoute orchestrates, see the QGate overview. For endpoint, signing, and webhook details, see the API integration guide.