The API is fully merchant-account aware, which means that every transaction, buyer, payment method, and most other resources are accessed within the context of a specific merchant account.

Support for multiple merchant accounts in one instance is a premium feature. In a standard instance, all your API calls will be associated with the default merchant account without any extra effort.

​
Managing accounts

Merchant accounts can be managed via the dashboard as well as via the API.

​
API keys

API keys can only be created by administrators via the dashboard, they can not be managed via the API. Keys can be created to either have access to a specific merchant account, or to all merchant accounts. These so-called admin keys and can be used to make API calls on behalf of any merchant account. Restricted API keys, or merchant keys, can only be used to make API calls on behalf of the merchant account they are associated with.

Admin keysMerchant keys
AccessAll merchant accountsOne merchant account
HeaderOptional, defaults to defaultDefaults to account associated to key
Use casePlatforms calling the API on behalf of merchantsMerchants making their own API calls

​
Merchant account header

Most API endpoints can only access and operate on records in one merchant account at a time. Every request will be processed within the context of that one merchant account, and it will only allow for using other resources from within the same merchant account.

For example, an API call to create a transaction will associate that transaction with the merchant account for which the request is made, and it can only use buyers, payment methods, connections, and flow rules that belong to the same merchant account.

To identify the merchant account to use you can set the X-GR4VY-MERCHANT-ACCOUNT-ID header. For example, the following request fetches a list of buyers for the legendary-games-uk account on the legendary-games instance.

curl https://api.sandbox.legendary-games.gr4vy.app \
  -H "X-GR4VY-MERCHANT-ACCOUNT-ID: legendary-games-uk"  \
  -H "AUTHORIZATION: bearer [token]"

In a single merchant instance, the X-GR4VY-MERCHANT-ACCOUNT-ID header can be omitted and the API will fall back to the default merchant account ID. Additionally, when using a merchant key the header can be omitted and the API will fall back to the merchant account associated with the key.

​
Admin APIs

A few endpoints are not merchant aware and therefore can only be accessed by admin keys. The only public endpoints currently affected are the GET /api-logs endpoint. Setting the X-GR4VY-MERCHANT-ACCOUNT-ID on this API will not have any effect.

​
SDK usage

Each of our SDKs supports setting the merchant account ID. This will automatically set the X-GR4VY-MERCHANT-ACCOUNT-ID for each request to this value. Without setting the ID explicitly its value will fall back to default.

const client = new Client({
  gr4vyId: 'demo',
  privateKey: key,
  debug: true,
  merchantAccountId: "my-merchant-account-id"
})