API & merchant accounts
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 keys | Merchant keys | |
|---|---|---|
| Access | All merchant accounts | One merchant account |
| Header | Optional, defaults to default | Defaults to account associated to key |
| Use case | Platforms calling the API on behalf of merchants | Merchants 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"
})