WritingSeptember 2026
Why Payment Provider Routing Becomes Infrastructure
Adding another provider adds another API client. Supporting another provider reliably adds states, identities, failure modes and operational decisions.
When you build a payment product, adding another provider initially looks like an integration task. You create another client, map its responses, handle its webhooks, and give the application a way to call it. That model works until the second or third provider starts behaving differently from the first one.
At Xpend, we reached that point gradually. We had operations that needed different payment rails, providers with different capabilities, and provider-specific details that couldn't safely be treated as interchangeable. The problem stopped being “how do we integrate another API?” and became “how do we decide which provider owns this operation, and how do we keep that decision correct for its entire lifecycle?”
That is where provider routing starts becoming infrastructure.
Providers are not interchangeable APIs
The first thing that becomes apparent is that providers don't expose the same version of a payment operation. A payout might require one provider's bank code, while another provider uses a different code for the same bank. A bill product may have an identifier that only has meaning within the provider that issued it. A virtual account may have its own lifecycle and reconciliation requirements.
That means provider selection cannot happen independently at every step. Suppose a user is making a bank transfer. We resolve their bank, resolve the account, create the payout, and eventually receive an asynchronous event telling us what happened. If each of those steps is allowed to independently ask, “Which provider should I use?”, we have created a system that can make a different decision halfway through the operation.
The provider needs to become part of the operation's state. Once a payout is associated with a provider, the bank mapping, account resolution, execution and webhook handling need to remain consistent with that provider. Otherwise a perfectly valid bank code from one system can become meaningless when passed to another.
We ended up introducing a distinction between a canonical bank identity and the code used by a particular provider. The canonical identity answers which bank we're talking about. The provider-specific code answers how that provider expects us to refer to it. That sounds minor until you have to support more than one payment rail.
Routing should describe capabilities, not vendors
Another change was moving provider selection away from business logic. Instead of having payment code decide that a particular operation should call Flutterwave or Boundless directly, we model the capability first: NGN payout, NGN deposit, airtime, bills, virtual account. The router can then resolve an appropriate provider for that capability and scope.
This separation matters because adding a provider should not require rewriting every business flow that happens to use it. The provider implementation knows how to talk to the external system. The routing layer knows which provider should handle a capability. The business operation should mostly care about the capability it needs.
It also gives us somewhere to put decisions that don't belong inside an API client. A provider can have an adapter implemented but still not be ready to handle production traffic. Its credentials may be missing. Its operational verification may not have been completed. The route may exist but remain disabled. Those are different states, and treating them as the same thing makes production behavior harder to reason about.
Fallback is not just retry logic
This became one of the more important design decisions. It is tempting to think about multiple providers as redundancy: if provider A fails, call provider B. That isn't always safe.
For some operations, choosing a secondary provider for a new transaction can be reasonable. For others, silently switching providers is something the system should never do. Virtual accounts are one example where provider identity is sticky and runtime substitution is explicitly disallowed. So we ended up treating fallback as a capability-specific policy rather than a generic retry mechanism.
There are three different behaviors in the system. For NGN payouts, a new operation can use a configured secondary provider when the primary cannot serve it. For deposits, airtime and bills, changing the route is an administrative decision for future operations; the resolver does not silently substitute another provider when the primary is unusable. For virtual accounts, there is no runtime fallback.
The important part isn't the names of those policies. It is the realization that “we have another provider available” doesn't answer whether the application is allowed to use it at that moment. That decision belongs to the payment system, not to an exception handler.
Once money is moving, provider choice becomes state
This is where the problem becomes less like ordinary application routing. Imagine a payout was created using provider A. The bank account was resolved using provider A's bank directory. The provider-specific bank code was stored with the payout. Later, provider A becomes unavailable.
Should the system move that payout to provider B?
The answer in our system is no.
Provider B may represent the same bank differently. Its account-resolution contract may be different. Its webhook will arrive through a different channel. Its product or transaction identifiers may not mean the same thing. The operation has already crossed a boundary.
So the routing decision for a new operation and the provider identity of an existing operation are two different things. The former can be operational policy. The latter is part of the transaction's state.
That also affects webhooks. When an event arrives, we don't want to ask the router which provider currently handles that capability. The router might give us a completely different answer from the one that created the transaction. The webhook needs to establish which provider owns the transaction and reject an event that doesn't match that persisted identity.
Provider routing therefore reaches into reconciliation and event processing. It isn't just a function that returns a provider client.
Readiness is another layer
We also had to separate several things that initially seem like one question: “Can this provider handle this operation?” There is a difference between having an adapter, having credentials, having a configured route, being operationally verified, and actually allowing execution.
A provider might have a working adapter for bills but still not be cleared for production bills. Another provider might have the credentials configured but require additional operational verification before activation. This led to an explicit readiness model: is the capability implemented, is the provider configured, has it been verified, is the route enabled, and can it execute this operation right now?
Those questions sound administrative, but they are part of the engineering system. If the only state available is “the API client exists,” the application has very little information with which to make a safe routing decision.
Switching providers is an operational action
Once provider selection lives in the database, changing it becomes something an operator can control rather than something that requires a code deployment. That introduces another responsibility: a production provider switch shouldn't be equivalent to changing a feature flag.
In our implementation, activating a provider goes through a preflight check. Provider verification and route activation are separate operations, and activation is recorded in an activity log. Verifying that a provider works is not the same thing as deciding to put it on the production path, and the separation gives us an audit trail when something changes.
The code that talks to a provider should not have to know who is authorized to make that decision. That belongs in the operational layer around the routing system.
The bank-code problem made this concrete
One of the clearest examples came from bank directories. A bank has a real-world identity, but providers don't necessarily agree on the identifier used to represent it. We found cases where the same bank had different provider-specific codes. That meant a bank selected from one provider's directory could not simply have its code passed to another provider.
The solution was to establish a canonical bank identity and map that identity to the code required by the provider handling the payout. Account resolution, bank mapping and payout execution then stay on the same provider. It is a small example of a larger rule: external identifiers are part of the boundary between systems. Once you have multiple providers, those boundaries need to be explicit.
The hard part is controlling change
Looking back at the provider work, the APIs themselves weren't the most interesting part. The harder questions were about change: what happens when the primary provider is unavailable, when a fallback is acceptable, what happens to transactions that already selected a provider, who owns an incoming webhook, how we know whether a provider is ready for production, who is allowed to activate it, and how we make those decisions without scattering provider-specific assumptions throughout the application.
Those questions pushed us toward a routing system that is deliberately more boring than the APIs it connects to. The router needs to be deterministic. Provider identity needs to persist. Fallback needs explicit boundaries. Operational readiness needs to be separate from implementation.
That is the part I think is easy to miss when looking at payment-provider integrations from the outside. Adding another provider adds another API client. Supporting another provider reliably adds another set of states, identities, failure modes and operational decisions.
Once provider choice has consequences beyond the initial API call, routing stops being plumbing. It becomes part of the infrastructure that keeps the payment system coherent. That is the problem we are actually solving at Xpend.