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 cardNumber holds an Orchestra token (@ followed by the token), the Tokenization Service retrieves the stored card from Orchestra’s vault. A gateway token sent in userToken is passed to that gateway unchanged.
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

  • Sensitive data (credentials, card numbers) is encrypted at rest
  • Database access is restricted to service accounts

​
Data in Transit

  • All API traffic requires TLS
  • Provider communications use their required secure protocols
  • No sensitive data in URLs or logs

​
PCI Compliance

Orchestra is PCI DSS Level 1 compliant. When card capture happens inside the Payments Library, card data never touches your systems, reducing your PCI scope. See PCI Scope and Compliance for the per-method scope breakdown and SAQ guidance, and our PCI compliance documentation for certification details.

​
Reliability

​
Failover

Orchestra supports two approaches for payment failure recovery: 1. Built-in Sequential Failover Pass a list of fallback Payment Gateway Accounts in the fallbackUpgs array. Orchestra tries each one in order until a payment succeeds, the list ends, or the primary gateway returns a reason code that stops failover. This works in Payments Library session requests and in REST charge and authorize requests. In a session request, each entry uses paymentGatewayAccountId:
If stripePrimary fails, Orchestra automatically tries adyenBackup, then worldpayFallback. In REST charge and authorize requests, each entry uses paymentGatewayAccountName instead. 2. Custom Retry Logic (REST API) If you need your own retry conditions, you can also write the failover logic yourself:
The built-in approach is simpler, while custom logic lets you add your own conditions, such as retrying only on specific error codes or routing based on transaction attributes.

Charge Payments

Implement your first charge

Multi-Gateway Failover

Set up automatic failover

Tokenization

Securely store card data

API Reference

Full endpoint documentation