Waterfall & Fallback
When a provider fails or is unavailable, the orchestrator automatically retries with the next candidate in the ranked list.
The waterfall turns a provider failure into a simple detour: instead of failing outright, the
transaction is retried with the next provider in the ranked candidate list that
priority tiers and tie-break scoring produced for this payment —
there is no separate fallback_chain object to configure; it's simply "the rest of the ranked
list."
How a fallback unfolds
MTN MoMo (priority 100)5038010msunavailableOrange Money (priority 100)200910msacceptedBoth candidates here sit in the same priority tier (100); Orange Money was simply next in the tie-break-ranked order after MTN MoMo failed. This whole sequence is recorded as one Routing Log decision for the payment.
Configuring fallback behavior
No retry_on / timeout_ms configuration
This page previously described a per-team fallback policy object with retry_on,
max_attempts, and timeout_ms fields. None of that is configurable today. The one real,
platform-wide knob is below.
orchestration.executor.max_attemptsconfigoptionaldefault : 3There is no merchant-configurable list of which failure types trigger a fallback (e.g. no way to
say "don't fall back on declined"): whether a given provider failure is retried across the
waterfall is decided by the payment executor, not by team-level settings.
Idempotency and waterfall
The waterfall is safe with respect to double charges: only one attempt can succeed, and the idempotency key protects the entire operation. The customer is never charged twice, even if multiple providers are attempted.