Routing Strategy Deep Dive
Provider selection, candidate ordering, and fallback behavior during confirm.
On confirm, which provider is tried is determined together by routing_strategy (optional API field) and your account settings. This field is not a separate "Strategy Execution" product step; after the routing plan is built, the provider adapter runs for each candidate. The goal is not a single if-else; attempts should be ordered, traceable, and backed up when needed.
How Is Strategy Sent?
In the confirm body, routing_strategy takes one of these two forms:
| Field | Meaning |
|---|---|
payment_provider_config_id | Single config for explicit routing, or an ordered candidate list with at least two configs |
provider_identifier | Single provider identifier, or an ordered candidate list with at least two identifiers |
If you do not send a strategy, the account default pool and fallback rules apply.
When you provide multiple IDs, order matters: candidates are generally processed in the order you give.
How Is the Candidate List Built?
Summary flow:
- A provider pool compatible with the payment and payment method is derived.
- Incompatible candidates are filtered out.
- If the request does not narrow the list, account fallback policy may look at the broader pool.
- The result is reflected in the routing plan record created during confirm.
The plan lets operations and the dashboard track which candidate was tried in which order.
Single Candidate vs Multiple Candidates
- Single config or single provider: You target that path directly; if it is not suitable, confirm may return an error or
REQUIRES_PAYMENT_METHOD. - Multiple configs or providers: Ordered retry model; if the first attempt fails or is a "soft" decline, the next candidate may be tried (rules depend on the candidate pool).
In the dashboard, the routing_origin field summarizes whether the last confirm was merchant-direct or autopilot-like multi-candidate.
When Does Fallback Kick In?
If the narrow list you provide on confirm ends up empty, or you send no strategy at all, the account-level suitable config pool may apply. This helps keep payments flowing during outages; it is good to track fallback usage separately in reporting.
Operational Recommendations
- Read routing plans and charge attempts together; multiple attempts under one payment are normal.
- Track success rate and latency by provider.
- Make fallback rate a separate metric; persistent fallback may indicate a configuration issue.