> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How Orchestra connects your application to payment gateways, handles routing, and processes transactions.

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

## System Overview

<img src="https://mintcdn.com/orchestrasolutions/JxGWfuqQpaY3_0EL/images/architecture-overview.svg?fit=max&auto=format&n=JxGWfuqQpaY3_0EL&q=85&s=a43f5cd4b0a3b8f04306a0786f7bd990" alt="Orchestra Architecture Overview" width="1383" height="1216" data-path="images/architecture-overview.svg" />

## 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

<Steps>
  <Step title="Request Received">
    Your server sends a POST to `/PaymentGateway/charge` with amount, currency, payment gateway account name, and card details (or token).
  </Step>

  <Step title="Authentication">
    API Gateway validates your API key and checks permissions.
  </Step>

  <Step title="Account Resolution">
    Payment Gateway Service looks up the specified Payment Gateway Account to get provider type and credentials.
  </Step>

  <Step title="Token Resolution (if applicable)">
    If you sent a `cardToken`, Tokenization Service retrieves the stored card data.
  </Step>

  <Step title="Provider Call">
    Payment Gateway Service translates your request to the provider's format and sends it to the provider's API.
  </Step>

  <Step title="Response Processing">
    Provider response is normalized to Orchestra's format and returned to you.
  </Step>
</Steps>

## 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](https://orchestrasolutions.com/about/pci-compliance/) 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](/guides/library/setup), 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:

```json theme={null}
{
  "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:

```javascript theme={null}
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:

| Operation        | Latency                         |
| ---------------- | ------------------------------- |
| Tokenization     | 50-100ms                        |
| Charge/Authorize | 200-500ms (depends on provider) |
| Balance check    | 20-50ms                         |

Provider latency dominates transaction times. Orchestra adds minimal overhead (\~20-50ms).

## Related Guides

<CardGroup cols={2}>
  <Card title="Charge Payments" icon="credit-card" href="/guides/rest-api/charge">
    Implement your first charge
  </Card>

  <Card title="Multi-Gateway Failover" icon="layer-group" href="/guides/rest-api/multi-gateway-failover">
    Set up automatic failover
  </Card>

  <Card title="Tokenization" icon="lock" href="/guides/rest-api/tokenization">
    Securely store card data
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Full endpoint documentation
  </Card>
</CardGroup>