Payment orchestration is a layer that sits between your checkout and several payment providers, so one integration can send each payment to whichever provider your rules choose. It decides the route, translates requests into each provider's format, falls back to another provider when one fails, and keeps track of every payment's status after checkout.
If you only have one provider, you probably do not need it yet. Once you have two or more, or you expect to, the question becomes whether to buy an orchestration platform or build a thin layer of your own. This guide covers how the layer works, where it tends to break, and how to make that call.
Why platforms end up with more than one payment provider
Most companies start with a single processor and are happy for a while. The second provider usually arrives for a specific business reason, not a technical one.
You might be entering a new country where your current provider does not offer local payment methods. A large customer might insist on paying through their own bank's rails. Your finance team might want a second quote to compare fees against, or your operations team might have lived through an outage and want a backup route.
Each of those is reasonable on its own. The trouble starts when every new provider gets wired straight into the checkout code. Soon you have two or three sets of status codes, refund logic and webhook handlers, all slightly different, and every product change has to be tested against each one.
Orchestration pulls that provider-specific code behind one interface. Your product code asks to authorize, capture, refund or cancel a payment, and the layer works out which provider to call and how.
What an orchestration layer is made of
Vendors describe orchestration in different ways, but the working parts are fairly consistent. We will use our own payment provider orchestration case study as the reference, because it shows the parts that tend to get skipped in sales material.
Connectors
A connector is the adapter for one provider. It maps your shared payment request into that provider's request format, and maps the response, including error codes, back into your shared model.
In the case study, connectors translate authorization, capture and cancellation requests. Typed interfaces define which operations each connector supports, and conversion functions handle the mapping in both directions. Type checking catches a request in the wrong shape, but the case page is plain that provider behavior still has to be checked at runtime, and that adding a connector there meant a new application build.
That last point matters when you compare options. A connector is code someone has to write, test and maintain every time a provider changes its API.
Routing rules
Routing decides which provider gets a payment. The case study's rules pick a provider by conditions, by volume splits, or by fallback settings.
- Conditions route on facts about the payment, such as currency, country, payment method or amount.
- Volume splits send a share of traffic to each provider, which is useful when you are testing a new one or honoring a volume commitment.
- Fallback names the provider to try when the first choice is unavailable or declines in a way that is worth retrying elsewhere.
Keep the rules readable by someone outside engineering. Finance and operations will want to know why a payment went where it did, and a rule they can read is easier to audit than routing logic buried in code.
Who owns the routing rules
Adyen's orchestration guide notes that most platforms use static rules. Those rules need regular checks and updates to keep working, which Adyen calls an ongoing operational commitment. Buying a platform does not hand that work to the vendor. Primer, which sells orchestration, describes its Workflows feature as a way for merchants to build payment flows from their own business logic without code. The vendor supplies the rule editor, and the merchant still decides what the rules say.
A rule change usually starts with a business event. A provider raises its fees, a new local payment method goes live, or approvals fall in one country. We recommend naming one person who watches for those events and signs off on rule changes. We would put that role in payments operations or finance, with engineers on hand for any change the rule model cannot express. Adyen warns that a complex setup with no one in charge of it can add points of failure instead of removing them.
The owner needs four things from the system, whether it is bought or built:
- A review step, so a rule edit is checked before it moves live traffic
- A change log of who edited which rule, when and why
- A volume split that sends a small share of payments through a new rule first, so a bad rule affects only a few payments
- The measurements in the "What to measure" section below, broken down by route
Status tracking
A payment has a life well past the checkout button. It can be authorized, captured, partly refunded, disputed or left pending while a provider runs its own checks.
The case study made a distinction that many integrations blur. A provider may confirm a payment before the merchant's own app has heard about it. Treating those as one status hides a real difference: the payment may still need a check, or the merchant update may just need another try. So the integration kept two records apart, one for the financial operation and one for the work still waiting to go out.
That split is what lets an operator tell a pending payment apart from an undelivered merchant notification.
Scheduled recovery work
Pending checks, refund-status requests and outbound webhooks all outlive the checkout. In the case study, these jobs were stored in the database, schedulers picked up due records, and each retry raised the attempt count and recorded the next run time. If a process stopped, its outstanding job stayed in the database, ready to pick up later.
This is the part teams most often underestimate. Routing gets the attention in demos, but recovery work is what decides whether a payment quietly gets lost when something fails at the wrong moment.
Authorize, capture and cancel
Card payments can usually be split into two steps. Authorization reserves the funds on the customer's payment method, and capture actually takes them. Cancelling an authorization releases the hold.
Stripe's documentation is a useful neutral reference here: an authorization has to be captured before it expires, the validity window varies by card brand and transaction type, and some payment methods do not support separate authorization and capture at all. Check each provider's own documentation for its rules.
For an orchestration layer, that creates three practical requirements:
- Each connector must say which operations it supports. If one provider cannot hold funds for later capture on a given method, routing has to know before it sends the payment there.
- Capture deadlines must be tracked per payment. If your business captures on shipment, a scheduled job needs to know when each authorization runs out on the provider that holds it.
- Refunds and disputes must go back through the same layer. In the case study, refunds and disputes pass through the same integration layer that handled the original payment. That keeps the full history of one payment in one place, even when it started on a different provider from the one you would pick today.
Failures, retries and idempotency
Payments fail in untidy ways. A request can time out after the provider has already charged the card. A webhook can arrive twice, or before your own record exists. A provider can return a decline you could retry and one you should not, using codes that look alike.
The rule that saves you is idempotency. Every request that moves money should carry a unique key, and the receiving side should treat a repeated key as the same request, not a new one. The IETF has a working draft, "The Idempotency-Key HTTP Header Field", that describes this pattern for HTTP APIs, including what to do when a key is reused with a different payload. It is still a draft, so treat it as guidance on the pattern rather than a finished standard.
In practice, you need idempotency in three places:
- Outbound to providers. Your retry after a timeout must not create a second charge.
- Inbound from providers. A duplicate webhook should update nothing the second time.
- Inbound from your own product. A double-clicked "Pay" button or a mobile app retrying on a bad connection should not start two payments.
Fallback adds one more trap. If provider A timed out, you do not know whether it charged the card. Sending the payment to provider B straight away can mean charging twice. A safer pattern is to fall back only on clear failures, such as a connection refused before the request was sent or an explicit decline, and to send unclear outcomes to a status check first.
When the orchestration layer itself fails
Once every payment passes through one layer, that layer can stop checkout on its own. An outage there cuts off every provider behind it. Adyen lists this as a "new point of failure" in its guide to payment orchestration. Stripe names dependence on third-party providers as a challenge, because an outage can disrupt the whole payment process. Adyen sells a single-provider setup as its alternative, which shapes its view. The risk is still real, and it applies to a layer you build as much as to one you buy.
The usual protection is a direct integration with at least one provider, kept outside the layer for the payment flows that matter most. One business on Adyen's customer panel concluded that resilience needs several layers. In its view, that means an orchestration platform and more than one payment provider, plus direct links to a provider for times when the orchestrator is down. The cost of that fallback belongs in the business case from the start. Your team maintains one provider integration twice, inside the layer and outside it, and has to test the switch between them.
The switch to the direct path carries the same double-charge risk as provider fallback. If a call to the layer times out, the layer may already have sent the payment to a provider, so a second try on the direct path can charge the customer twice. We use the fallback rule from the previous section here too, so checkout moves to the direct path only on a clear failure, such as a refused connection, and an unclear outcome waits for a status check.
An idempotency key can add a second guard when the same provider sits behind both paths. It works only if the layer forwards your key to that provider unchanged. If the layer sends its own key instead, the provider sees two different keys for one payment and cannot spot the repeat. With a bought platform, this is a question for the vendor before your team relies on the guard. In a layer we build, passing the merchant's key through unchanged is a design rule.
Two more controls keep an outage small. The first is short timeouts between checkout and the layer, with a pause on calls once errors pass a set level. Customers then reach the direct path or a clear error quickly. The second is a single record. Payments taken on the direct path need to flow into the same status tracking, refunds and reconciliation as every other payment. Without that step, finance ends up with two records of the same day's sales.
A bought platform adds a second kind of dependency. Adyen notes that the quality of an orchestrator's API affects how much your own roadmap comes to depend on it. A missing connector or payment method becomes a wait on the vendor's schedule. Before signing, we would ask the vendor three things:
- What its uptime commitment covers, and what happens when it is missed
- How it fails over between regions
- How it reports incidents, and how quickly
A layer you build needs the same planning. It should run in more than one availability zone. The database-backed recovery jobs described earlier must also be safe to repeat, so a restart does not send a refund or a webhook twice.
Tokenization and the vault
To charge a returning customer, something has to store their payment details. Many teams search for "payment orchestration or vault" because they are unsure whether they need one, the other or both.
A vault stores sensitive card data and hands back a token you can use instead. An orchestration layer routes payments. They often appear together because a provider-neutral vault lets you send a saved card to more than one provider. If the card is stored only inside provider A, you may not be able to route that customer's next payment to provider B.
In the case study, saved payment details could sit in a separate vault, and merchant-sensitive fields used merchant-specific keys held behind a master key or an external key management service.
Whether you run the vault yourself or use a third party's is a separate decision from orchestration, and it is mostly a compliance decision.
3DS, network tokens and account updater
Vaults and orchestration platforms often come with three card features. Each one leaves data with one provider that a payment routed to a different provider may need. With 3DS that data is the result of one payment check, and with network tokens and account updates it is the stored card itself.
3-D Secure (3DS) is a protocol that checks the person paying is the real cardholder, which helps cut fraud. Stripe notes that strong customer authentication under PSD2 in the EEA, and similar rules in the UK, India, Japan and Australia, may require 3DS for card payments. In other regions 3DS is optional. Our reading is that a US-only platform can treat 3DS as a choice, and that 3DS becomes a routing concern once the platform sells into those markets. The issuer may also approve the check without showing the customer any challenge at all, which Stripe calls a frictionless flow. A passed check does not guarantee that liability for fraud moves to the issuer.
In an orchestrated setup, 3DS can run outside the processor that approves the payment. Stripe is one processor that accepts 3DS results from a third-party provider, but only in some of the countries where it takes card payments. India is one country where Stripe does not accept them. The layer then has to carry each result to whichever provider gets the payment, in a form it accepts. We treat this as a connector feature, like separate capture. Some providers may not take 3DS results from outside. The routing rules need to know which ones, so they never send such a provider a payment that was checked somewhere else.
Network tokens replace the card number (PAN) with a 16-digit token that the card network issues. Adyen says each token is unique to one shopper and one merchant, and each transaction uses a single-use cryptogram. Visa issues these tokens through the Visa Token Service. Mastercard's service is MDES, and Mastercard says it is replacing MDES for Merchants with a product called Secure Card on File. The network keeps the token valid when card details change, including when a card expires or is lost and the customer gets a new one.
Who holds the network token decides how far it can travel. Adyen, for one, lets merchants forward the network tokens it holds for them to another PCI-compliant party, for example a second payment provider. A token that cannot leave one provider ties that customer to it.
Account updater services keep stored cards current. Visa Account Updater (VAU) lets issuers, acquirers and qualified merchants swap updated card details for recurring payments, cards on file and some other payment types. Its updates carry new card numbers and expiry dates, and they can also flag a closed account or pass on a cardholder advice. Mastercard's Automatic Billing Updater (ABU) gives card number and expiry date updates. A merchant can pull them by inquiry or subscribe to have them pushed. Stripe says automatic card updates are widely supported in the United States, and it also notes three limits on coverage. Updates need the card issuer to take part, support in other countries varies, and Stripe says it cannot identify in advance which cards will get them.
Where those updates land is the orchestration problem. If one provider enrolled the card and receives its updates, the copy held for your other routes can go out of date. In our analysis, the same card can then fail on one route and work on another.
The vendor should state which of the three features it handles and where it keeps the results. It should also say whether those tokens and card updates can be exported or forwarded to another provider, and that answer belongs in the contract.
How orchestration affects PCI scope
The PCI Data Security Standard applies to entities that store, process or transmit cardholder data or sensitive authentication data. If your orchestration layer touches raw card numbers, it is in scope.
Tokenization can reduce how much of your environment handles card data, but the PCI Security Standards Council's tokenization guidance is clear that it does not remove the obligation. In its words, tokenization solutions "do not eliminate the need to maintain and validate PCI DSS compliance". The same guidance says you have to confirm that card numbers cannot be retrieved from any system you treat as out of scope.
So the design question to ask early is which component sees the card number. If card details go straight from the customer's browser to a provider or a third-party vault, and your layer only ever sees tokens, your scope is likely smaller than if your servers receive the card number and pass it on. Your qualified security assessor makes the final call on scope, not your vendor and not us.
Build vs buy
There is no universally right answer. Here is how the options usually compare.
| Question | Buy an orchestration platform | Build your own layer |
|---|---|---|
| How many providers do you need now? | Useful when you need many connectors quickly | Practical when you need two or three you already know |
| Who maintains connectors? | The vendor, on their schedule | Your team, on yours |
| Routing logic | Configured within the platform's rule model | Written to match your business exactly |
| Vault and PCI scope | Often bundled; check what the vendor's attestation actually covers | You choose a vault and design scope from day one |
| Recovery work and status model | Defined by the platform | Designed around your own payment states |
| Data ownership | Check export rights and token portability before signing | Yours by default |
| Lock-in | Moving away later means re-integrating | Moving a connector means changing your own code |
| Pricing | Usually platform fees on top of provider fees | Engineering and ongoing maintenance |
Buying tends to make sense when payments are not core to your product, you need many providers or local methods fast, and the platform already supports the ones you need. Ask early how it handles a provider it does not support yet, and whether you can take your tokens with you if you leave.
Building tends to make sense when you have a small number of providers, your payment states do not fit a generic model (marketplaces, split payouts, held funds), or you are a payments or fintech company where routing is part of the product. Even then, a thin layer over a few connectors is usually enough. You do not need to recreate a whole platform.
There is also a middle path. Some teams buy a vault for tokens and PCI scope and build only the routing and status layer on top.
What to measure
Whichever route you take, the layer is only as useful as what it lets you see. Useful measurements include:
- Success rate by provider and route, so routing decisions rest on your own traffic rather than a vendor's averages.
- Declines by reason code, mapped into your shared model, so a soft decline on one provider and a hard decline on another are not counted as the same thing.
- How often fallback fires, and whether the fallback provider then succeeds.
- Age of pending payments and pending jobs, so a stuck status check is visible before a customer asks about it.
- Webhook delivery backlog, kept separate from payment status.
- Settlement and reconciliation mismatches per provider, which is where routing changes often show up first. Our guide on how payment reconciliation works covers that side.
- Cost per payment by route, using your actual fee reports.
We have not put benchmark numbers here on purpose. Success rates and costs depend heavily on your industry, customers and providers, and any figure we quoted would not tell you much about yours.
Where this fits in a larger platform
Orchestration is one integration among many. If you are working through the wider integration picture, our piece on how API integrations differ from one another explains why payment connectors behave differently from, say, a CRM sync. Our pages on software for fintech and digital banking teams and financial services software cover the surrounding work, and our API integration and development services page covers what we build.
FAQ
What is payment orchestration in simple terms?
It is a layer that connects your checkout to several payment providers through one interface and decides which provider handles each payment.
Is a payment orchestration platform the same as a payment gateway?
No. A gateway connects you to one processing path. An orchestration platform sits above one or more gateways and processors and routes between them.
Do I need orchestration if I only use one provider?
Usually not. It becomes useful when you add a second provider, need local payment methods your current provider lacks, or want a fallback route.
Does payment orchestration remove PCI DSS obligations?
No. Tokenization can reduce the parts of your system that handle card data, but the PCI Security Standards Council says it does not eliminate the need to maintain and validate compliance.
What is the difference between payment orchestration and a vault?
A vault stores card data and issues tokens. Orchestration routes payments. A provider-neutral vault is what lets orchestration send a saved card to more than one provider.
How long does it take to build an orchestration layer?
It depends on how many providers, payment methods and payment states you need. We would scope it in discovery rather than guess here.
If you are weighing whether to buy or build, or you already have two providers wired into your checkout and want them behind one layer, you can get a range for your payment integration and we will start from the providers and payment flows you actually have.
