Skip to main content
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.
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.

​
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:
The same call replaces the credentials if the account already exists. Each provider needs different credential fields: the List Gateways endpoint returns them. See Gateway Accounts for listing, reading and deleting accounts.
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.

​
Charge for a Merchant

Pass the merchant’s Payment Gateway Account name on each transaction. REST API:
Payments Library session:
To fail over, list the same merchant’s backup accounts in fallbackUpgs, in the order you want them tried. See 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. 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. 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 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 to discuss it. It is then used exactly like any other Payment Gateway Account.

Add a Payment Provider

Provider credentials and the portal steps

Generate API Key

Keys, users and what each key can use

Multi-Gateway Failover

Backup providers per transaction

PCI Scope and Compliance

What you and your compliance officer need to know