Routing & Smart Retries

MVS Pay decides which connector authorizes a payment and what happens when a connector declines. Both decisions run inside Hyperswitch, not in MVS code. The orchestration service (apps/mvs-pay-extensions) and the SDK (@mvs/mvs-pay-sdk) only configure the rules and flip the toggles; the actual selection and retry logic execute in the Hyperswitch router on every payment.

This is a direct application of ADR-007: Maximum native Hyperswitch bias — surface every Hyperswitch feature through the SDK or UI rather than rebuilding a parallel engine MVS-side. Routing, the decision-engine MAB, and Smart Retries are listed in that ADR as the canonical “native features are first-class consumers” cases.

How the pieces fit together

The three configuration surfaces map cleanly onto the SDK:

Source of truth:

• apps/mvs-pay-extensions/src/routes/routing.ts
• apps/mvs-pay-extensions/src/routes/routing-dynamic.ts
• apps/mvs-pay-extensions/src/routes/smart-retries.ts
• packages/mvs-pay-sdk/src/namespaces/routing.ts, routing-dynamic.ts, smart-retries.ts
• packages/mvs-pay-sdk/src/data/gsm-seed.ts

Static routing rules

A static routing rule is a Hyperswitch routing algorithm scoped to a business profile. MVS Pay supports the four upstream variants, validated at the service edge in routing.ts against a local Zod mirror of the SDK’s CreateRoutingInput discriminated union (the SDK exports types only, so the runtime schema is re-declared inline — keep both in lockstep when the union grows).

The advanced rule-DSL

The advanced variant carries a list of rules, each with a name, a routing_type (priority or volume_split), an output (connector list or weighted split), and statements. Each statement is an array of conditions:

1
{
2
  "lhs": "amount",                         // field to test
3
  "comparison": "greater_than",            // equal | not_equal | greater_than |
4
                                           // less_than | contains | not_contains
5
  "value": { "type": "number", "value": 5000 }  // type: number | str |
6
                                                 //       str_array | number_array
7
}

A full advanced algorithm posted through the SDK:

1
await client.routing.create({
2
  name: "High-value cards to Adyen",
3
  profile_id: profileId,
4
  algorithm: {
5
    type: "advanced",
6
    data: {
7
      default_selection: { connector: "stripe" },
8
      rules: [
9
        {
10
          name: "big-ticket",
11
          routing_type: "priority",
12
          output: ["adyen", "cybersource"],
13
          statements: [
14
            {
15
              condition: [
16
                {
17
                  lhs: "amount",
18
                  comparison: "greater_than",
19
                  value: { type: "number", value: 5000 },
20
                },
21
              ],
22
            },
23
          ],
24
        },
25
      ],
26
    },
27
  },
28
});

Lifecycle: create, activate, deactivate

Creating a rule does not activate it. Activation is a separate step, profile-scoped. The service exposes:

On activate/deactivate the service also writes a mirror of the active algorithm id onto the tenant’s MerchantExtension row. setActiveRoutingId() finds the MerchantExtension whose hyperswitchProfileId matches the rule’s profile_id and overwrites routingAlgorithmId; if no profile matches it falls back to the tenant’s isDefault row. This lets the operator UI surface the active rule without an extra Hyperswitch round-trip.

Simulating a rule before activation

The operator UI calls POST /api/routing/simulate (a Next.js route handler in apps/mvs-pay, not a service route). The page comment states the simulator runs the same evaluator the rule-DSL editor targets, so the “Simulate” button is faithful to the real engine. The simulate response carries chosen, candidates[], matchedRule, and notes[].

Control Center deep-link (the escape hatch)

The rule-DSL editor is deliberately a thin shell over Hyperswitch’s algorithm JSON. When a rule is too complex for the editor (or you need volume_split_priority, or any field the editor doesn’t expose), the footer deep-links the Hyperswitch Control Center routing screen:

https://hyperswitch.payments.internal/routing

This URL is hardcoded in apps/mvs-pay/app/(dashboard)/routing/page.tsx (HYPERSWITCH_CONTROL_CENTER_ROUTING_URL) because the Control Center lives outside the per-org surface and is not threaded through env. It is an internal hostname; it resolves only from inside the cluster / VPN, not from the public internet.

Dynamic routing — the decision-engine MAB

Dynamic routing lets Hyperswitch override the static choice using runtime signals. The connector recommendation is computed by the decision-engine, a Rust service from Juspay that runs a Multi-Armed Bandit (MAB) over per-connector success rates. The Hyperswitch router queries it over an in-cluster ClusterIP on every payment where the profile has dynamic routing enabled. See the Decision-engine runbook for deploy and operation.

routing-dynamic.ts exposes six pass-through routes. There is no MVS-side logic beyond tenant-scoping and Zod validation — every route forwards to Hyperswitch’s per-profile dynamic-routing toggles.

The three modes are orthogonal and may be enabled together:

• success-rate-based — the MAB exploits the highest-scoring connector, exploring others a fixed fraction of the time.
• elimination — temporarily drops a connector that flaps (fails repeatedly in a sliding window) so the next payment skips it.
• contract — routes a fixed percentage to a connector to satisfy a signed volume SLA.

1
// Route 20% of card volume through the MAB; the rest follows the static rule.
2
await client.routing.dynamic.toggleSuccessBased({
3
  merchantId,
4
  profileId,
5
  enable: "dynamic_connector_selection",
6
});
7
await client.routing.dynamic.setSuccessBasedSplit({
8
  merchantId,
9
  profileId,
10
  splitPct: 20,
11
});

MAB tuning parameters

These live in the decision-engine chart values (deploy/decision-engine/values.yaml), not in MVS application code. They are documented here because they explain the routing behavior an engineer will observe:

Reading scores

1
const window = await client.routing.dynamic.getScoreWindow({
2
  merchantId,
3
  profileId,
4
});
5
// window.entries: [{ connector, successRate, sampleSize, ... }]

State lives in Redis, shared across decision-engine replicas, so the score window is global to the merchant, not per-pod. The operator UI surfaces this read-only at /routing/dynamic-stats. The successRateScoreReconcileWorkflow (Temporal, Track D) also consumes getScoreWindow to emit Datadog metrics — see the Temporal worker surface.

To disable dynamic routing globally without uninstalling the engine, set decisionEngine.url: "" in deploy/hyperswitch/values-prod.yaml (the router then falls back to static rules); Argo CD reconciles in ~60s. Full rollback in the Decision-engine runbook.

Smart Retries — native decline recovery

Smart Retries is Hyperswitch’s native auto-retry engine. When a connector declines, Hyperswitch consults the gateway_status_map (GSM) to decide whether to retry the attempt on an alternate connector, escalate to step-up 3DS, or surface the decline. The retry engine runs inside Hyperswitch — the /v1/smart-retries routes only configure the rules and the on/off switch.

Smart Retries is two cooperating halves:

1
// Enable (maxRetries defaults to 3 server-side if omitted)
2
await client.smartRetries.enable({ merchantId, profileId, maxRetries: 3 });
3
// → { enabled: true }
4
5
await client.smartRetries.disable({ merchantId, profileId });
6
// → { enabled: false }

The gateway_status_map (GSM)

A GSM rule maps a connector’s decline code to a decision. The relevant fields:

Wildcard rows (connector: "*") apply to every connector unless a more specific (connector, code) rule overrides them — Hyperswitch’s GSM lookup respects the fallback pattern.

Seeded default rules

POST /v1/smart-retries/gsm/seed with { "connector": "<name>" } iterates a server-side DEFAULT_GSM_RULES list and posts every rule matching the requested connector plus the wildcard rules.

The default list covers stripe, adyen, cybersource, braintree, and finix, plus one network-level wildcard. The pattern is: soft declines → retry (usually with step_up_possible: true), hard declines → do_not_retry.

1
await client.smartRetries.seedDefaults({ connector: "stripe" });
2
// → { rulesSeeded: n }   (single round-trip; extensions iterates server-side)

GSM CRUD

The remaining routes pass straight through to Hyperswitch’s /v1/gsm:

1
// Override a seeded rule to stop retrying a code
2
await client.smartRetries.updateGsmRule(ruleId, { decision: "do_not_retry" });

For the full operational procedure (enable, seed, verify, troubleshoot), see the Smart Retries runbook.

What lives where

Gaps & caveats