Skip to main content
This page describes Orchestra’s technical architecture for developers who want to understand how the system works under the hood.

​
System Overview

Orchestra Architecture Overview

​
Components

​
API Gateway

The entry point for all requests. Handles:
  • TLS termination
  • Authentication (API key validation)
  • Rate limiting
  • Request routing to internal services

​
Payment Gateway Service

Processes payment transactions:
  • Translates Orchestra’s unified API to provider-specific formats
  • Routes transactions to the specified Payment Gateway Account
  • Handles provider responses and normalizes them
  • Manages transaction state (authorization, capture, void, refund)

​
Payment Gateway Accounts Service

Manages provider connections:
  • Stores encrypted credentials
  • Validates account configuration
  • Handles credential rotation

​
Tokenization Service

Secures card data:
  • Encrypts and stores card details
  • Issues tokens for stored cards
  • Retrieves card data for transactions (never exposed to your systems)

​
Data Flow: Charge Transaction

1

Request Received

Your server sends a POST to /PaymentGateway/charge with amount, currency, payment gateway account name, and card details (or token).
2

Authentication

API Gateway validates your API key and checks permissions.
3

Account Resolution

Payment Gateway Service looks up the specified Payment Gateway Account to get provider type and credentials.
4

Token Resolution (if applicable)

If you sent a cardToken, Tokenization Service retrieves the stored card data.
5

Provider Call

Payment Gateway Service translates your request to the provider’s format and sends it to the provider’s API.
6

Response Processing

Provider response is normalized to Orchestra’s format and returned to you.

​
Security

​
Data at Rest

  • All sensitive data (credentials, card numbers) encrypted with AES-256
  • Encryption keys managed via HSM (Hardware Security Module)
  • Database access restricted to service accounts

​
Data in Transit

  • All API traffic over TLS 1.2+
  • Provider communications over their required secure protocols
  • No sensitive data in URLs or logs

​
PCI Compliance

Orchestra is PCI DSS Level 1 compliant. When you use Orchestra’s tokenization, card data never touches your systems, reducing your PCI scope. See our PCI compliance documentation for details.

​
Reliability

​
Availability

  • Multi-region deployment
  • Automatic failover between availability zones
  • 99.9% uptime SLA

​
Failover

Orchestra supports two approaches for payment failure recovery: 1. Built-in Sequential Failover (Payments Library) When using the Payments Library, pass a list of fallback Payment Gateway Accounts in the session request. Orchestra tries each one in order until a payment succeeds or all fail: 
{
  "operation": "CHARGE",
  "paymentGatewayAccountId": "stripe-primary",
  "fallbackUpgs": [
    { "paymentGatewayAccountId": "adyen-backup" },
    { "paymentGatewayAccountId": "worldpay-fallback" }
  ],
  "amount": 99.99,
  "currencyCode": "USD"
}
If stripe-primary fails, Orchestra automatically tries adyen-backup, then worldpay-fallback. 2. Custom Retry Logic (REST API) When using the REST API directly, implement your own failover logic for full control over retry conditions: 
async function chargeWithFailover(amount, currency, cardToken) {
  const providers = ['stripe-primary', 'adyen-backup'];

  for (const provider of providers) {
    try {
      const result = await charge(amount, currency, provider, cardToken);
      if (result.success) return result;
    } catch (error) {
      console.log(`${provider} failed, trying next`);
    }
  }

  throw new Error('All providers failed');
}
The built-in approach is simpler, while custom logic lets you add conditions like retrying only on specific error codes or routing based on transaction attributes.

​
Latency

Typical response times:
OperationLatency
Tokenization50-100ms
Charge/Authorize200-500ms (depends on provider)
Balance check20-50ms
Provider latency dominates transaction times. Orchestra adds minimal overhead (~20-50ms).

Charge Payments

Implement your first charge

Multi-Gateway Failover

Set up automatic failover

Tokenization

Securely store card data

API Reference

Full endpoint documentation