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

# Serving Many Merchants

> Run payments for many merchants, each with its own payment provider, from one Orchestra integration.

This guide is for platforms that take payments for their own customers, where each customer (merchant) has its own account with a payment provider. You integrate once. Each merchant's provider credentials are stored with Orchestra, and every transaction names the merchant account to use.

## The Model

* Your platform has **one Orchestra account**.
* Each merchant's provider credentials become **one Payment Gateway Account**, with a name you choose, for example `m1042adyen` for merchant 1042 on Adyen.
* Every transaction **names the Payment Gateway Account** to use. That is how a charge reaches the right merchant's provider.

A merchant can have more than one Payment Gateway Account, for example a primary provider and a backup.

<Note>
  Payment Gateway Account names use letters and digits only, 3 to 64 characters. A name that includes your own merchant ID makes the mapping easy to follow.
</Note>

## Add Merchants Through the API

Adding merchants one by one in the portal does not scale. Create each merchant's Payment Gateway Account through the API when the merchant connects their provider in your platform:

```bash theme={null}
curl -X PUT https://api.orchestrasolutions.com/PaymentGatewayAccounts/m1042adyen \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "paymentGatewayName": "Adyen",
    "credentials": [
      { "Key": "...", "Value": "..." }
    ]
  }'
```

The same call replaces the credentials if the account already exists. Each provider needs different credential fields: the [List Gateways](/guides/rest-api/utilities/list-gateways) endpoint returns them. See [Gateway Accounts](/guides/rest-api/utilities/gateway-accounts) for listing, reading and deleting accounts.

<Warning>
  A Payment Gateway Account belongs to the user of the API key that created it, and only that user's API keys can use it. Create accounts and charge with API keys of the same user. See [User Assignment](/getting-started/generate-api-key#user-assignment).
</Warning>

## Charge for a Merchant

Pass the merchant's Payment Gateway Account name on each transaction.

REST API:

```json theme={null}
{
  "paymentGatewayAccountName": "m1042adyen",
  "amount": 25.00,
  "currency": "EUR",
  "card": { "cardNumber": "@YOUR_TOKEN", "expirationYear": 2027, "expirationMonth": 12 }
}
```

Payments Library session:

```json theme={null}
{
  "operation": "CHARGE",
  "paymentGatewayAccountId": "m1042adyen",
  "allowedeWalletAccountIds": ["cardPay"],
  "mode": "LIVE",
  "currencyCode": "EUR",
  "countryCode": "DE",
  "amount": 25.00
}
```

To fail over, list the same merchant's backup accounts in `fallbackUpgs`, in the order you want them tried. See [Multi-Gateway Failover](/guides/rest-api/multi-gateway-failover).

## Optional: One User per Merchant

For stricter separation, give each merchant (or group of merchants) its own user in your Orchestra account. An account admin creates users in the [portal](https://portal.orchestrasolutions.com/#/users). Each user's API keys can use only that user's Payment Gateway Accounts and tokens.

Consider the trade-off before you choose this: tokens also belong to a user, so a card stored under one user cannot be charged with another user's API key.

## Payment Methods in the Payments Library

Every payment method the Payments Library shows, cards included, uses an [eWallet Account](/getting-started/create-ewallet-account). eWallet Accounts are set up in the portal. In each session, name the eWallet Accounts to offer in `allowedeWalletAccountIds`.

Some methods hold merchant-specific details and need an eWallet Account per merchant. Bank Pay, for example, holds the bank details the payment is sent to. See [Supported Payment Methods](/guides/library/supported-payment-methods) for each method's setup.

## Merchants Without a Payment Provider

If a merchant does not have an account with a payment provider, we can set up the merchant account for them. [Contact us](https://orchestrasolutions.com/support/) to discuss it. It is then used exactly like any other Payment Gateway Account.

## Related

<CardGroup cols={2}>
  <Card title="Add a Payment Provider" icon="building-columns" href="/getting-started/add-payment-provider">
    Provider credentials and the portal steps
  </Card>

  <Card title="Generate API Key" icon="key" href="/getting-started/generate-api-key">
    Keys, users and what each key can use
  </Card>

  <Card title="Multi-Gateway Failover" icon="rotate" href="/guides/rest-api/multi-gateway-failover">
    Backup providers per transaction
  </Card>

  <Card title="PCI Scope and Compliance" icon="shield-check" href="/concepts/pci-scope-and-compliance">
    What you and your compliance officer need to know
  </Card>
</CardGroup>