BitriPay
ONE QR. ONE GATEWAY. EVERY ELIGIBLE RAIL.Pay Local. Fund Global. Settle Your Way.
developers

How a payment decides which way to go

A payment can usually travel several ways, and they are not equally good at two in the morning. Routing on measured success, cost and latency — with a breaker on failing rails — is the difference between resilience and a bad night.

Most payment integrations contain a decision nobody revisits: the provider chosen in the first week.

It works. Then one night it does not — not down, just slow and failing one payment in five — and every payment degrades with it. The business finds out from customers.

Routing is a measurement problem

A payment can usually go several ways. The ways are not equally good, and which one is best changes by the hour.

So the question is not which provider did we pick but which of these can carry this payment, right now, best.

Scored on what actually happened

Each candidate connector is scored on three measured things: its recent success rate, the total cost of using it, and its observed latency.

Those numbers come from telemetry kept in fifteen-minute buckets over twenty-four hours — optionally keyed by amount band and prefix, because a rail that is excellent for small local payments is not necessarily excellent for large ones.

It is a measurement, not a preference list somebody wrote once.

The breaker

A connector that fails repeatedly has its circuit opened: it stops being offered at all.

After a cooldown it goes half-open — one payment is allowed through as a test. If that succeeds the circuit closes and normal traffic resumes. If it fails, back to open.

The effect is that a recovering rail is tested with a single payment rather than with all of your customers.

Failover that will not double-charge

This is where naive retry logic causes real damage.

Failover happens only for errors that guarantee no money moved. For anything ambiguous — a timeout, an unknown response code — the status is checked first.

A payment that might have succeeded is not retried. Losing a sale to caution is recoverable. Charging a customer twice is a refund, a complaint and a reputation.

Your policy

A merchant can bias routing towards cheapest, fastest or most reliable, and restrict which rails a payment may use at all.

What you cannot do is force a rail whose breaker is open. That is not a limitation; it is the entire value of having a breaker.

You can see what happened

Every payment records the connector that carried it and the attempts before it. The dashboard shows the route the payment actually took — not the route it was supposed to take, which is the number most systems give you and the one that is useless during an incident.

What it costs

Nothing extra. You pay the rate of whichever rail carried the payment, and the dashboard tells you which one did.

What you can check

These are facts about the running platform, not adjectives. Each one is visible in the product, in the API reference or in the ledger.

  • Scores come from telemetry kept in fifteen-minute buckets over twenty-four hours, optionally keyed by amount band and prefix, rather than from a static preference list.
  • The breaker moves closed → open after consecutive faults → half-open after a cooldown → closed on the next success, so a recovering rail is tested with one payment rather than all of them.
  • Health is a state per connector — healthy, degraded, unavailable, maintenance — derived from the circuit, the last probe and recent success.
  • Failover only happens for errors that guarantee no money moved; anything ambiguous triggers a status check first.
  • A merchant can bias routing towards cheapest, fastest or most reliable per payment.

What it costs

Included. You pay the rate of whichever rail carried the payment, and the dashboard shows which one did.

Is it switched on?

Whether this is available depends on the authorisations in place and on what the administrator of a given deployment has switched on. That changes, and an article does not — so the live answer lives on the feature page, which reads it from the platform itself: Smart Route on the features page.

Frequently asked questions

Could a retry charge my customer twice?

Failover happens only for errors that guarantee no money moved. For anything ambiguous — a timeout, an unknown code — the status is checked first. Not retrying is better than retrying into a double charge.

Can I force a particular rail?

You can bias the routing policy towards cheapest, fastest or most reliable, and restrict which rails a payment may use. What you cannot do is force a rail whose breaker is open, which is the point of having one.

How do I know which rail was used?

Every payment records the connector that carried it, along with the attempts before it. The dashboard shows the route a payment actually took, not the one it was supposed to take.

build on bitripay smart route
Try it with a free account

Send with a QR code, add money by card or mobile money, issue a virtual card. Sandbox balances let you explore before any real money moves.

Open an account

Keep reading