Introduction to Payment Orchestration

Start at the End

Your customer sees a payment form. They enter their card. They click “Pay.” They see a confirmation. That’s it. That’s what you’re building toward. Everything else is infrastructure to make that moment happen reliably, securely, and at scale.

Key Terms

Before we go further, let’s define a few concepts you’ll see throughout these docs:

Term	What it means
Payment gateway	Service that processes card transactions (Stripe, Adyen, Worldpay, etc.). You need an account with at least one.
Merchant account	Your account with a payment gateway that lets you accept payments and receive funds.
Token	A reference to stored card details. You use tokens instead of raw card numbers for security. Cards can be tokenized with Orchestra (gateway-agnostic) or with the payment gateway directly (gateway-specific).
PCI DSS	Security standard for handling card data. More card data you touch = more compliance burden.

The Form: The Payments Library Is the Answer

The Payments Library is Orchestra’s answer to card capture: it is the form. You embed our JavaScript. When the user clicks “Pay,” a popup overlay appears over your page (your site grays out behind it). They enter card details in that popup. You receive the payment result and, optionally (if selected), a token for the card in a callback. You can store the card with Orchestra or with the payment gateway directly. Card data never touches your servers, which is what keeps you out of PCI scope.

	What You Get	What You Handle	Payment Methods
Payments Library	Pre-built UI, hosted card entry, PCI handled	Styling, callback handling	Cards + APMs (Apple Pay, Google Pay, PayPal, UPI and more)

Once the Library has captured a token, the REST API takes over: charging that token, authorizing and capturing, refunds, voids, recurring billing, and transaction status. That is the standard integration, and it’s what the rest of this guide, and the REST API reference, assume. Can you build your own form and post raw cards through the REST API instead? The schema allows it: the charge endpoint accepts raw card fields as well as token references. But building your own card form means cardholder data passes through your frontend and backend, which puts you in PCI DSS scope. It’s possible, not the intended integration, and worth doing only if you already have a specific reason to hold card data yourself (an existing token vault provider, for example). How the Library and API work together: API vs Library

Your foundational choice: the Payments Library handles capture and determines your PCI compliance path. The REST API handles what your backend does with the payment after that. Both are normally part of the same integration.

What Payment Methods Can You Accept?

Beyond traditional card payments, the Payments Library gives you access to multiple payment methods that your customers might prefer:

Payment Method	Geographic Coverage	Notes
Cards (Visa, Mastercard, Amex, etc.)	Global	Via any configured gateway
Google Pay	70+ countries	Pre-built UI included
Apple Pay	70+ countries	Pre-built UI included
PayPal	200+ countries	Pre-built UI included
UPI	India	Pre-built UI included
Bank transfers	Select markets	Regional availability varies

One of the benefits of this approach is consistency: the same callback receives results regardless of which payment method your customer chooses. Your integration code stays the same whether they paid with a Visa card, Apple Pay, or PayPal.

Need a payment method we don’t support yet? Request an integration. We add new payment methods at no cost to you, and a new one takes on average two weeks to integrate.

Behind the Form: What Actually Happens

When the customer clicks “Pay”:

For the full list, see our integrations page or call List All Payment Gateways. Here’s the key insight: Orchestra sits between your application and your payment gateways. You talk to one API, and Orchestra handles the translation to each gateway’s specific requirements. This means you send the same request format regardless of which gateway you’re using, and you get back normalized responses that look the same whether the payment went through Stripe, Adyen, or any other provider.

The orchestration advantage: This unified API is why you can switch from Stripe to Adyen by changing one parameter instead of rewriting your integration. The same request format works across every supported provider.

The Payment Lifecycle

When you’re ready to collect money from a customer, you have two approaches to choose from, depending on your business needs: 1. Charge (and optionally tokenize) - This is the straightforward approach: authorize and capture (and optionally tokenize) in one step, and money moves immediately. You’ll use this when you can fulfill the order right away, like with digital goods, subscription signups, or services delivered straight away. 2. Authorize → Capture - This two-step approach lets you reserve funds now and collect later. It’s perfect for situations where you need some time before fulfilling the order, like shipping physical goods, rentals where the final amount might vary, or any scenario where you want to hold funds before finalizing the charge.

Both operations work identically across all your gateways. You can also void (cancel an authorization before capture) or refund (return funds after capture).

Why Multiple Gateways?

If your business uses one payment gateway and will never need another, a direct integration with that gateway may be enough. Orchestra becomes valuable when you work with more than one: several gateways for your own business, or one gateway per merchant when you serve many merchants. Orchestra becomes valuable when your business needs multiple gateways working together:

Reason	Example
Failover	Primary gateway down? Route to backup automatically.
Geographic coverage	Adyen for EU, local processor for Brazil, different provider for APAC.
Payment methods	Gateway A for cards, Gateway B for bank transfers, PayPal for wallets.
Cost optimization	Route Visa to cheaper processor, Amex to the one with better rates.
Partner requirements	Your merchants have existing processor relationships you need to support.
Avoiding lock-in	Add/remove gateways without rewriting integration code.
Future growth	Need a new gateway next year? Add credentials, update routing logic. Your integration code doesn’t change. For the full list, see our integrations page or call List All Payment Gateways. If we don’t support it yet, we’ll add it at no cost to you. A new integration takes on average two weeks.

The orchestration value: One integration that speaks to all of them.

Without Orchestration vs With Orchestration

Decision checkpoint: If you recognize your business in this table, Orchestra can help. If you only need one gateway and don’t anticipate adding more, integrate directly with that provider - their APIs are excellent and you’ll avoid the orchestration layer.

Challenges Orchestra Helps You Overcome

Here’s where multi-gateway payment integration gets complicated - and how Orchestra helps:

Challenge: Gateway goes down, you lose sales When your payment gateway has an outage, every transaction fails and you lose sales. Orchestra helps you build resilience by supporting automatic sequential failover:

// Orchestra tries each in order until one succeeds or the list ends
await charge({
  amount: 49.99,
  currency: 'USD',
  card: cardToken,
  paymentGatewayAccountName: 'stripePrimary',
  fallbackUpgs: [
    { paymentGatewayAccountName: 'adyenBackup' },
    { paymentGatewayAccountName: 'worldpayEmergency' }
  ]
});

You can also implement your own custom failover logic based on specific error conditions. Because Orchestra’s API is unified across all providers, your own routing and retry rules are straightforward to write:

async function chargeWithMyRules(payment) {
  try {
    return await charge({ ...payment, paymentGatewayAccountName: 'stripePrimary' });
  } catch (error) {
    if (error.code === 'RATE_LIMIT') {
      return await charge({ ...payment, paymentGatewayAccountName: 'adyenHighVolume' });
    }
    if (error.code === 'CURRENCY_NOT_SUPPORTED') {
      return await charge({ ...payment, paymentGatewayAccountName: 'worldpayMultiCurrency' });
    }
    throw error;
  }
}

Challenge: Storing cards securely (PCI DSS compliance) Handling raw card numbers puts you in PCI DSS scope (the security standard governing how businesses handle cardholder data). Options:

Approach	How	PCI Impact
Full Outsourcing	Card entry happens in Orchestra’s hosted card forms. Process a charge, or tokenize the card for later use, directly from the card form. Card data never touches your servers.	SAQ-A eligible if you’re a merchant, SAQ-D if you’re a service provider*
Token Vault	Receive or collect card details independently and store them with Orchestra. You receive a token to use for future charges.	In scope for the systems that receive and send the card. Orchestra removes the storage burden only.
Third-Party Vault Enhancement	Use cards stored with a third-party token vault to process charges through your selected PSP. Card never reaches your system.	SAQ-A eligible if you’re a merchant, SAQ-D if you’re a service provider*

*We can provide guidance prepared by our auditors on how to fill out the SAQ-D for service providers when using Orchestra. See PCI Scope and Compliance. The less card data you handle, the simpler your compliance. Full Outsourcing (via the Payments Library) is the easiest path.

Challenge: You want routing control, not a black box Some payment orchestrators make routing decisions for you using their own rules engine. That’s not how Orchestra works, and we consider this a competitive advantage. When you use someone else’s routing rule engine, you’re constrained by the types of rules and logic that they thought of. That might cover most cases, but who’s to say your business fits that category? With Orchestra, you set up your own rules based on your own logic and criteria. You’re not limited by someone else’s assumptions about how routing should work - you have complete flexibility to implement exactly what your business needs.

function selectGateway(transaction) {
  // Your business logic, your criteria, your data
  if (transaction.cardCountry === 'EU') return 'adyenEu';
  if (transaction.region === 'LATAM') return 'localProcessorBrazil';
  if (transaction.amount > 10000) return 'stripeHighValue';
  return 'primaryGateway';
}

await charge({ ...payment, paymentGatewayAccountName: selectGateway(transaction) });

The tradeoff to understand: This approach means you’re responsible for writing and maintaining the routing logic. If you’re looking for drag-and-drop rules configuration in a graphical interface, Orchestra isn’t the right fit. We’ve chosen to provide flexibility and control over prescriptive automation, because we believe developers should own their business logic.

Why these patterns work: Orchestra normalizes the differences between gateways. The failover code you write for Stripe/Adyen works identically for any provider pair - same error codes, same response format, same authentication.

The Infrastructure You’ll Need

Before you can start processing payments through Orchestra, you’ll need to set up a few pieces of infrastructure:

Payment gateway accounts - You’ll need relationships with actual payment gateways like Stripe, Adyen, Worldpay, or others to process payments. Orchestra routes transactions to these providers, but doesn’t replace them.
Gateway credentials stored in Orchestra - Once you have accounts with your chosen processors, you’ll store each processor’s API keys with Orchestra. This lets you reference them by name in your API requests rather than managing credentials in your own code.
Orchestra API key - Finally, you’ll need an API key from Orchestra to authenticate your requests to our platform.

Want to test immediately? Orchestra provides mock payment gateways (NULLSuccess/NULLFailure) that require no external accounts. See the Quickstart to start testing.

// Same code structure, different provider
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'stripeEu' });
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'adyenUs' });
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'worldpayApac' });

Orchestra uses major currency units (49.99), not minor units/cents (4999). If your payment gateway works in minor units, Orchestra converts automatically from major to minor units - keeping your requests to Orchestra consistent across all payment gateways.

Where does cardToken come from? The Payments Library: the hosted popup returns it in your callback after the customer enters their card. (A /tokenize REST endpoint also exists for backends that already lawfully hold card data, but sending raw card details through your own systems puts you in PCI DSS scope and is not the standard integration.) Once the Library has produced a token, your backend never handles raw card numbers. Cards stored in Orchestra’s vault are gateway-agnostic: the same token works with all your configured gateways. A gateway token works only with the gateway that issued it. Saving Cards for Future Charges Many businesses need to charge customers multiple times without asking for card details again. This comes up in scenarios like subscriptions, repeat customers, or one-click checkout experiences. When a customer enters their card for the first time through the Payments Library, you can store it with Orchestra and receive a token back. You save that token in your database linked to the customer, and then use it for all future charges. Your customer never has to re-enter their card details.

The token is yours to keep. If you later add a new gateway or switch providers, cards stored in Orchestra’s vault still work. No need to ask customers to re-enter their cards.

What Orchestra Doesn’t Do

To set clear expectations, here’s what Orchestra isn’t designed to do:

Not a payment processor - Orchestra does not process payments itself. You need merchant accounts with payment processors, and Orchestra routes transactions to them on your behalf.
Not a fraud engine - For fraud detection and prevention, you’ll want to use your payment gateways’ built-in fraud tools or dedicated fraud prevention services. Orchestra passes through fraud-related data but doesn’t make fraud decisions.
Not a reconciliation system - While Orchestra returns transaction references that you can use for reconciliation, the actual reconciliation of funds happens in your payment processor dashboards.
Not a rules engine - Orchestra doesn’t provide a drag-and-drop UI for configuring routing rules. Your routing logic lives in your application code, where you have full control and flexibility.
Never holds your money - money moves directly between the payment provider and the merchant. Orchestra does not hold, split or pay out funds.
Not for in-store card terminals - Orchestra handles online payments.

Clear boundaries: Orchestra is primarily a routing and translation layer between your application and payment processors. You typically need your own processor accounts and fraud tools. We handle the integration complexity.

Ready to Build?

At this point, you should have a solid understanding of how payment orchestration works and how Orchestra implements it. You’ve learned about the customer experience you’re building toward, how the Library and the API work together, how payment operations flow, and the infrastructure you’ll need to get started. You also understand when Orchestra makes sense (multiple gateways) and when it doesn’t (single gateway), along with the key challenges it helps you overcome around failover, PCI compliance, and routing control. Ready for your next step? Let’s build a working charge.

Quickstart

Make your first API call

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Introduction to Payment Orchestration

Start at the End

Key Terms

The Form: The Payments Library Is the Answer

What Payment Methods Can You Accept?

Behind the Form: What Actually Happens

The Payment Lifecycle

Why Multiple Gateways?

Challenges Orchestra Helps You Overcome

The Infrastructure You’ll Need

What Orchestra Doesn’t Do

Ready to Build?

Quickstart

​Start at the End

​Key Terms

​The Form: The Payments Library Is the Answer

​What Payment Methods Can You Accept?

​Behind the Form: What Actually Happens

​The Payment Lifecycle

​Why Multiple Gateways?

​Challenges Orchestra Helps You Overcome

​The Infrastructure You’ll Need

​What Orchestra Doesn’t Do

​Ready to Build?

Quickstart

Start at the End

Key Terms

The Form: The Payments Library Is the Answer

What Payment Methods Can You Accept?

Behind the Form: What Actually Happens

The Payment Lifecycle

Why Multiple Gateways?

Challenges Orchestra Helps You Overcome

The Infrastructure You’ll Need

What Orchestra Doesn’t Do

Ready to Build?