Skip to main content

​
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. Payment form

​
Key Terms

Before we go further, let’s define a few concepts you’ll see throughout these docs:
TermWhat it means
Payment gatewayService that processes card transactions (Stripe, Adyen, Worldpay, etc.). You need an account with at least one.
Merchant accountYour account with a payment gateway that lets you accept payments and receive funds.
TokenA 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 DSSSecurity standard for handling card data. More card data you touch = more compliance burden.

​
The Form: Build or Borrow?

When it comes to building that payment form, Orchestra gives you two paths, each with different tradeoffs:
ApproachWhat You GetWhat You HandlePayment Methods
1. Payments LibraryPre-built UI, hosted card entry, PCI handledStyling, callback handlingCards + APMs (Apple Pay, Google Pay, PayPal, UPI and more)
2. REST APIFull control over UI and flowBuilding the form, tokenization flowCards only
What you’ll actually build: If you choose the Payments Library: 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. Payments Library popup flow If you choose the REST API: You build your own form. You collect card details, send them to Orchestra’s tokenization endpoint, receive a token. Then you use that token to charge. Card data passes through your server briefly once (or you use a third-party vault to avoid this entirely). REST API flow How to choose between them: Choose Payments Library if:
  • You want the fastest path to production with minimal PCI compliance burden
  • You need to support alternative payment methods (Apple Pay, Google Pay, PayPal, UPI)
  • Pre-built UI components work for your use case
Choose REST API if:
  • You need pixel-perfect brand control over every aspect of the payment experience
  • You’re already using a token vault provider
  • You need to integrate payments into mobile apps or custom flows
Either way, both approaches use the same backend processing, so you’re getting the same reliability and feature set. Both paths allow you to charge immediately, or store the token to charge later (subscriptions, saved payment methods, one-click checkout). Compare in detail: API vs Library
Your foundational choice: Library vs API determines your PCI compliance path, development timeline, and UI control. Everything else we cover works with either approach.

​
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 MethodGeographic CoverageNotes
Cards (Visa, Mastercard, Amex, etc.)GlobalVia any configured gateway
Google Pay70+ countriesPre-built UI included
Apple Pay70+ countriesPre-built UI included
PayPal200+ countriesPre-built UI included
UPIIndiaPre-built UI included
Bank transfersSelect marketsRegional 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? We can add new payment methods at no cost to you. Contact us to discuss your requirements and timeline.

​
Behind the Form: What Actually Happens

When the customer clicks “Pay”: Payment routing flow See all supported 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 all supported providers.

​
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 (an 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 in-person purchases. 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, hotel check-outs where the final amount might vary, or any scenario where you want to hold funds before finalizing the charge. Charge vs Authorize + Capture 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?

Here’s an important point upfront: if you’re only using one payment gateway, you should integrate with them directly. Stripe’s API is excellent, Adyen’s dashboard is powerful, and direct integrations are often the right choice when you only need one provider. We’re not trying to compete with single-gateway integrations. Orchestra becomes valuable when your business needs multiple gateways working together:
ReasonExample
FailoverPrimary gateway down? Route to backup automatically.
Geographic coverageAdyen for EU, local processor for Brazil, different provider for APAC.
Payment methodsGateway A for cards, Gateway B for bank transfers, PayPal for wallets.
Cost optimizationRoute Visa to cheaper processor, Amex to the one with better rates.
Partner requirementsYour merchants have existing processor relationships you need to support.
Avoiding lock-inAdd/remove gateways without rewriting integration code.
Future growthNeed a new gateway next year? Add credentials, update routing logic. Your integration code doesn’t change. See all 90+ supported gateways. If we don’t support it yet, we’ll add it (2-4 weeks, no cost to you).
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
await charge({
  amount: 49.99,
  currency: 'USD',
  card: cardToken,
  paymentGatewayAccountNames: ['stripe-primary', 'adyen-backup', 'worldpay-emergency']
});
You can also implement your own custom failover logic based on specific error conditions. Because Orchestra’s API is unified across all providers, this kind of intelligent routing is straightforward to build: 
async function chargeWithSmartFailover(payment) {
  try {
    return await charge({ ...payment, paymentGatewayAccountName: 'stripe-primary' });
  } catch (error) {
    if (error.code === 'RATE_LIMIT') {
      return await charge({ ...payment, paymentGatewayAccountName: 'adyen-high-volume' });
    }
    if (error.code === 'CURRENCY_NOT_SUPPORTED') {
      return await charge({ ...payment, paymentGatewayAccountName: 'worldpay-multi-currency' });
    }
    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:
ApproachHowPCI Impact
Full OutsourcingCard 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 VaultReceive or collect card details independently and store them with Orchestra. You receive a token to use for future charges.Card data transits your server only once for a short time frame
Third-Party Vault EnhancementUse 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. 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 'adyen-eu';
  if (transaction.region === 'LATAM') return 'local-processor-brazil';
  if (transaction.amount > 10000) return 'stripe-high-value';
  return 'primary-gateway';
}

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:
  1. 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.
  2. 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.
  3. 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 in 5 minutes.
// Same code structure, different provider
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'stripe-eu' });
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'adyen-us' });
await charge({ amount: 49.99, currency: 'USD', card: cardToken, paymentGatewayAccountName: 'worldpay-apac' });
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?
  • 1. Payments Library: The hosted popup returns it in your callback after the customer enters their card
  • 2. REST API: You send card details to the /tokenize endpoint, receive a token back
Once you have a token, you never handle raw card numbers again. Tokens are gateway-agnostic. The same token works across all your configured gateways. 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 (whether through the Payments Library or REST API), 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. Token storage and reuse The token is yours to keep. If you later add a new gateway or switch providers, the same tokens 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:
  • Generally not a payment processor - Orchestra typically doesn’t process payments itself. You’ll need merchant accounts with payment processors, and Orchestra routes transactions to them on your behalf. However, we can provide payment processing services through agreements with our US and EU partners where that makes sense for your integration.
  • Not a single-gateway replacement - If you only need one payment gateway like Stripe, you should use Stripe directly. Orchestra adds value when you need to work with multiple providers.
  • 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. However, we can integrate with external fraud services on demand.
  • 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. However, we can add reconciliation capabilities on demand.
  • 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.
Clear boundaries: Orchestra is primarily a routing and translation layer between your application and payment processors. You typically need your own processor accounts, fraud tools, and reconciliation systems. We handle the integration complexity, though we can also provide payment processing services through partnerships where appropriate.

​
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, the two integration approaches available to you, 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 in 5 minutes.

Quickstart

First API call in 5 minutes