Routing and fallback

Next (sandbox). Two simulated payment aggregator partners stand in for real ones until partners are chosen. No real money moves.

TatvaPay sends each payment to a licensed payment aggregator (PA) partner. With more than one partner, it picks one per payment and can try a second one when the first fails on its own side.

Bound or routed mandates

• A mandate bound to one partner always uses that partner. If the partner is unavailable, the payment fails with bound_rail_unavailable; it never moves to another partner silently.
• A routed mandate ("rail": "routed", with the instrument's method, upi, card or netbanking, and optionally the bank's four-letter code) lets TatvaPay choose. The consent wording says so before the owner authorises it.

How the partner is chosen

The router is a fixed set of rules with a version (for example routing-2026-10-01.1), written into every payment's receipt with its reasons:

1. The mandate's bound partner, if any.
2. Partners that take the payment method and amount.
3. Partners the merchant allows (routing settings, Payments → Routing).
4. Not a partner whose circuit breaker is open, or that our status checks see down.
5. Ranked by the merchant's choice: balanced, highest success, lowest cost, or the merchant's own order. Success is measured over the last 15 minutes; healthy partners come before degraded ones.

Fallback, once

A payment is tried on a second partner at most once, under the same payment and Idempotency-Key, and only when the first partner failed on its own side: unreachable, a partner error, its route declining, or a timeout that a status check confirmed failed. Never:

• after a decline by the buyer's bank or the buyer (insufficient funds, wrong PIN, do not honour) or a risk decline;
• for a mandate bound to one partner;
• above the buyer's always-ask amount without their approval;
• for a Payment Recovery retry, which a person approved for one charge;
• when the merchant turned fallback off.

Never charged twice

A timeout is never retried blind. The payment stays processing until the partner's status or its webhook says what happened; only a confirmed failure may fall back. Duplicate and late webhooks are ignored, and a contradicting one is shown to a person; nothing moves on its own.

Decline codes

Every partner's codes map to one set of TatvaPay codes (failure_reason on a payment), each saying whether it is soft or hard, whether it may succeed later, whether fallback applies, and what the buyer can do. UPI and RuPay network codes are mapped provisionally until a partner confirms them.