Adyen

Configuration API

The Configuration API allows you to manage your balance platform where you can create account holders, balance accounts, cards, and business accounts.…

Payments#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Configuration API allows you to manage your balance platform where you can create account holders, balance accounts, cards, and business accounts.

Authentication

Each request to the Configuration API must be signed with an API key. Generate an API key in your Customer Area if you have a platform setup or marketplace setup.

If you have an Adyen Issuing integration, generate an API key in your Balance Platform Customer Area.

To connect to the API, add an X-API-Key header with the API key as the value, for example:

curl
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...

Versioning

The Configuration API supports versioning using a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number.

For example:

https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders

Going live

When going live, generate an API key in your live Customer Area if you have an Adyen for Platforms integration or live Balance Platform Customer Area if you have an Adyen Issuing integration.You can then use the API key to send requests to https://balanceplatform-api-live.adyen.com/bcl/v2.

Endpoints 97

Platform

  • GETGet a balance platform/balancePlatforms/:idReturns a balance platform.
  • GETGet all account holders under a balance platform/balancePlatforms/:id/accountHolders?offset=0&limit=0Returns a paginated list of all the account holders that belong to the balance platform. To fetch multiple pages, use the query parameters. For example, to…
  • GETGet all transaction rules for a balance platform/balancePlatforms/:id/transactionRulesReturns a list of transaction rules associated with a balance platform.

Account holders

  • POSTCreate an account holder/accountHoldersCreates an account holder linked to a legal entity.
  • GETGet an account holder/accountHolders/:idReturns an account holder.
  • PATCHUpdate an account holder/accountHolders/:idUpdates an account holder. When updating an account holder resource, if a parameter is not provided in the request, it is left unchanged.
  • GETGet all balance accounts of an account holder/accountHolders/:id/balanceAccounts?offset=0&limit=0Returns a paginated list of the balance accounts associated with an account holder. To fetch multiple pages, use the query parameters. For example, to limit…
  • GETGet a tax form/accountHolders/:id/taxForms?formType=US1099k&year=0&legalEntityId=stringGenerates a tax form for account holders operating in the US. For more information, refer to US tax forms for marketplaces or platforms .
  • GETGet all transaction rules for an account holder/accountHolders/:id/transactionRulesReturns a list of transaction rules associated with an account holder.
  • GETGet summary of tax forms for an account holder/accountHolders/:id/taxFormSummary?formType=stringReturns a summary of all tax forms for an account holder.

Balance accounts

  • POSTCreate a balance account/balanceAccountsCreates a balance account that holds the funds of the associated account holder.
  • GETGet a balance account/balanceAccounts/:idReturns a balance account and its balances for the default currency and other currencies with a non-zero balance.
  • PATCHUpdate a balance account/balanceAccounts/:idUpdates a balance account.
  • GETGet payment instruments linked to a balance account/balanceAccounts/:id/paymentInstruments?offset=0&limit=0&status=stringReturns a paginated list of the payment instruments associated with a balance account. To fetch multiple pages, use the query parameters.For example, to limit…
  • GETGet all transaction rules for a balance account/balanceAccounts/:id/transactionRulesReturns a list of transaction rules associated with a balance account.

Balances

  • GETGet all balance webhook settings/balancePlatforms/:balancePlatformId/webhooks/:webhookId/settingsReturns all balance webhook settings configured for triggering balance webhooks.
  • POSTCreate a balance webhook setting/balancePlatforms/:balancePlatformId/webhooks/:webhookId/settingsConfigures the criteria for triggering balance webhooks. Adyen sends balance webhooks to notify you of balance changes in your balance platform. They can be…
  • GETGet a balance webhook setting by id/balancePlatforms/:balancePlatformId/webhooks/:webhookId/settings/:settingIdReturns the details of a specific balance webhook setting configured for triggering balance webhooks.
  • DELETEDelete a balance webhook setting by id/balancePlatforms/:balancePlatformId/webhooks/:webhookId/settings/:settingIdDeletes a balance webhook setting that contains the conditions for triggering balance webhooks.
  • PATCHUpdate a balance webhook setting by id/balancePlatforms/:balancePlatformId/webhooks/:webhookId/settings/:settingIdUpdates the conditions the balance change needs to meet for Adyen to send a balance webhook.

Managed payout schedules

  • GETGet all managed payout schedules on a balance account/balanceAccounts/:balanceAccountId/payoutSchedules?currency=string&cursor=string&limit=10Returns a list of all managed payout schedules that are configured on a balance account. You can use query parameters to filter the elements that are returned…
  • POSTApply a managed payout schedule to a balance account/balanceAccounts/:balanceAccountId/payoutSchedulesApply a managed payout schedule to a balance account. This payout schedule is based on an existing payout schedule in your balance platform.
  • GETGet a specific managed payout schedule on a balance account/balanceAccounts/:balanceAccountId/payoutSchedules/:idReturns the specified payout schedule.
  • DELETEDelete a managed payout schedule on a balance account/balanceAccounts/:balanceAccountId/payoutSchedules/:idDelete a payout schedule applied to a balance account.
  • PATCHUpdate a managed payout schedule on a balance account/balanceAccounts/:balanceAccountId/payoutSchedules/:idUpdate a managed payout schedule applied to a balance account. If an optional parameter is not included in the request, it remains unchanged.
  • GETView executions of a managed payout schedule/balanceAccounts/:balanceAccountId/payoutSchedules/:id/executions?results=string&limit=10&offset=1View information about the executions of a managed payout schedule on the specified balance account. An execution is an attempt to make a payout according to…
  • GETGet all managed payout schedules on your balance platform/balancePlatforms/:balancePlatformId/payoutSchedules?countryCode=string&currency=stringReturns a list of all the payout schedules that are configured for your balance platform. You can use query parameters to filter the elements that are…
  • GETGet a specific managed payout schedule on your balance platform/balancePlatforms/:balancePlatformId/payoutSchedules/:idReturns the specified managed payout schedule configured on your balance platform.

Custom payout schedules (sweeps)

  • GETGet all sweeps for a balance account/balanceAccounts/:balanceAccountId/sweeps?offset=0&limit=0Returns a list of the sweeps configured for a balance account. To fetch multiple pages, use the query parameters. For example, to limit the page to 5 sweeps…
  • POSTCreate a sweep/balanceAccounts/:balanceAccountId/sweepsCreates a sweep that results in moving funds from or to a balance account. A sweep pulls in or pushes out funds based on a defined schedule, amount, currency,…
  • GETGet a sweep/balanceAccounts/:balanceAccountId/sweeps/:sweepIdReturns a sweep.
  • DELETEDelete a sweep/balanceAccounts/:balanceAccountId/sweeps/:sweepIdDeletes a sweep for a balance account.
  • PATCHUpdate a sweep/balanceAccounts/:balanceAccountId/sweeps/:sweepIdUpdates a sweep. When updating a sweep resource, note that if a request parameter is not provided, the parameter is left unchanged.
  • GETView executions of a custom payout schedule/balanceAccounts/:balanceAccountId/sweeps/:sweepId/executions?results=string&limit=10&cursor=stringReturns a paginated list of executions of a custom payout schedule on a balance account. You can use query parameters to filter the executions that are…

Authorized card users

  • GETGet authorized users for a card./paymentInstruments/:paymentInstrumentId/authorisedCardUsersReturns the authorized users for a card.
  • POSTCreate authorized users for a card./paymentInstruments/:paymentInstrumentId/authorisedCardUsersAssigns authorized users to a card. Users must have the authorisedPaymentInstrumentUser capability to be able to use the card.
  • DELETEDelete the authorized users for a card./paymentInstruments/:paymentInstrumentId/authorisedCardUsersDeletes the list of authorized users assigned to a card.
  • PATCHUpdate the authorized users for a card./paymentInstruments/:paymentInstrumentId/authorisedCardUsersUpdates the list of authorized users for a card. >This request replaces all existing authorized users for the card.

Recurring top ups

  • GETGet recurring top ups for a specific balanceAccountId/balanceAccounts/:balanceAccountId/recurringTopUps?limit=10&cursor=stringView all recurring top ups configured for a specific balanceAccountId. For more information, refer to Manage recurring top-ups.
  • POSTCreate recurring top up/balanceAccounts/:balanceAccountId/recurringTopUpsCreate a recurring top up configuration. For more information, refer to Create recurring top-ups.
  • DELETEDelete a recurring top up/balanceAccounts/:balanceAccountId/recurringTopUps/:topUpIdDelete a recurring top up configuration by topUpId. For more information, refer to Manage recurring top-ups.
  • PATCHUpdate a RecurringTopUp/balanceAccounts/:balanceAccountId/recurringTopUps/:topUpIdUpdate the configuration of an existing recurring top up. For more information, refer to Manage recurring top-ups.

Payment instruments

  • POSTCreate a payment instrument/paymentInstrumentsCreates a payment instrument to issue a physical card, a virtual card, or a business account to your user. For more information, refer to Issue cards or Issue…
  • POSTReveal the data of a payment instrument/paymentInstruments/revealReturns the encrypted data of a specified payment instrument. These data include: The primary account number (PAN) The card verification code (CVC) The expiry…
  • GETGet a payment instrument/paymentInstruments/:idReturns the details of a payment instrument.
  • PATCHUpdate a payment instrument/paymentInstruments/:idUpdates a payment instrument. Once a payment instrument is already active, you can only update its status. However, for cards created with inactive status,…
  • GETGet network token activation data/paymentInstruments/:id/networkTokenActivationDataGet the network token activation data for a payment instrument.
  • POSTCreate network token provisioning data/paymentInstruments/:id/networkTokenActivationDataCreate provisioning data for a network token. Use the provisioning data to add a user's payment instrument to their digital wallet.
  • GETList network tokens/paymentInstruments/:id/networkTokensList the network tokens connected to a payment instrument.
  • GETGet the PAN of a payment instrument/paymentInstruments/:id/revealReturns the primary account number (PAN) of a payment instrument. To make this request, your API credential must have the following role: * Balance Platform…
  • GETGet all transaction rules for a payment instrument/paymentInstruments/:id/transactionRulesReturns a list of transaction rules associated with a payment instrument.

Payment instrument groups

  • POSTCreate a payment instrument group/paymentInstrumentGroupsCreates a payment instrument group to associate and group payment instrument resources together. You can apply a transaction rule to a payment instrument group.
  • GETGet a payment instrument group/paymentInstrumentGroups/:idReturns the details of a payment instrument group.
  • GETGet all transaction rules for a payment instrument group/paymentInstrumentGroups/:id/transactionRulesReturns a list of all the transaction rules associated with a payment instrument group.

Transaction rules

  • POSTCreate a transaction rule/transactionRulesCreates a transaction rule. When your user makes a transaction with their Adyen-issued card, the transaction is allowed or declined based on the conditions…
  • GETGet a transaction rule/transactionRules/:transactionRuleIdReturns the details of a transaction rule.
  • DELETEDelete a transaction rule/transactionRules/:transactionRuleIdDeletes a transaction rule.
  • PATCHUpdate a transaction rule/transactionRules/:transactionRuleIdUpdates a transaction rule. * To update only the status of a transaction rule, send only the status parameter. All other parameters not provided in the…

Bank account validation

  • POSTValidate a bank account/validateBankAccountIdentificationValidates bank account identification details. You can use this endpoint to validate bank account details before you make a transfer or create a transfer…

Network tokens

  • GETGet a network token/networkTokens/:networkTokenIdReturns the details of a network token.
  • PATCHUpdate a network token/networkTokens/:networkTokenIdUpdates the status of the network token.

Grant accounts

  • GETGet a grant account/grantAccounts/:idDeprecated. Returns the details of the grant account.

Grant offers

  • GETGet all available grant offers/grantOffers?accountHolderId=stringDeprecated. Returns a list of all grant offers available for accountHolderId specified as a query parameter.
  • GETGet a grant offer/grantOffers/:grantOfferIdDeprecated. Returns the details of a single grant offer.

Card orders

  • GETGet a list of card orders/cardorders?id=string&cardManufacturingProfileId=string&status=string&txVariantCode=string&createdSince=2024-01-01T00:00:00Z&createdUntil=2024-01-01T00:00:00Z&lockedSince=2024-01-01T00:00:00Z&lockedUntil=2024-01-01T00:00:00Z&serviceCenter=string&offset=0&limit=0Returns a paginated list of card orders.
  • GETGet card order items/cardorders/:id/items?offset=0&limit=0Returns the item list of a specific card order.

Direct debit mandates

  • GETGet a list of mandates/mandates?balanceAccountId=string&paymentInstrumentId=string&cursor=stringReturns a list of all direct debit mandates created for a business account.
  • GETGet a specific mandate/mandates/:mandateIdReturns the details of the specified direct debit mandate.
  • PATCHAmend a mandate/mandates/:mandateIdAmend the specified direct debit mandate.
  • POSTCancel a mandate/mandates/:mandateId/cancelCancel a specified direct debit mandate.

Manage card PIN

  • POSTChange a card PIN/pins/changeChanges the personal identification number (PIN) of a specified card. To make this request, your API credential must have the following role: * Bank Issuing…
  • POSTReveal a card PIN/pins/revealReturns an encrypted PIN block that contains the PIN of a specified card. You can use the decrypted data to reveal the PIN in your user interface. To make…
  • GETGet an RSA public key/publicKey?purpose=string&format=stringGet an RSA) public key to encrypt or decrypt card data. You need the RSA public key to generate the encryptedKey required to: Change a PIN. Reveal a PIN.…

Transfer routes

  • POSTCalculate transfer routes/transferRoutes/calculateReturns available transfer routes based on a combination of transfer country, currency, counterparty, and priorities. Use this endpoint to find optimal…

SCA device management

  • POSTBegin SCA device registration/scaDevicesBegins the registration process for a new Strong Customer Authentication (SCA) device.
  • DELETEDelete an SCA device/scaDevices/:deviceIdDeletes a Strong Customer Authentication (SCA) device.
  • PATCHFinish registration process for a SCA device/scaDevices/:deviceIdFinishes the registration process for a new Strong Customer Authentication (SCA) device.
  • POSTCreate a new SCA association for a device/scaDevices/:deviceId/scaAssociationsCreates an association between an SCA-enabled device and an entity, such as an account holder. This action does not guarantee the association is immediately…

Transfer limits - balance account level

  • GETFilter and view the transfer limits/balanceAccounts/:id/transferLimits?scope=perDay&transferType=instant&status=activeFilter and view the transfer limits configured for a balance account using the balance account's unique id and the available query parameters.
  • POSTCreate a transfer limit/balanceAccounts/:id/transferLimitsCreate a transfer limit for your balance account using the unique id of your balance account.
  • POSTApprove pending transfer limits/balanceAccounts/:id/transferLimits/approveApprove transfer limits that are pending SCA authentication.
  • GETGet all current transfer limits/balanceAccounts/:id/transferLimits/current?scope=perDay&transferType=instantGet all transfer limits that currently apply to a balance account using the unique id of the balance account.
  • GETGet the details of a transfer limit/balanceAccounts/:id/transferLimits/:transferLimitIdGet the details of a transfer limit using its unique transferLimitId.
  • DELETEDelete a scheduled or pending transfer limit/balanceAccounts/:id/transferLimits/:transferLimitIdDelete a scheduled or pending transfer limit using its unique transferLimitId. You cannot delete an active limit.

Transfer limits - balance platform level

  • GETFilter and view the transfer limits/balancePlatforms/:id/transferLimits?scope=perDay&transferType=instant&status=activeFilter and view the transfer limits configured for your balance platform using the balance platform's unique id and the available query parameters.
  • POSTCreate a transfer limit/balancePlatforms/:id/transferLimitsCreate a transfer limit for your balance platform using the unique id of your balance platform.
  • GETGet the details of a transfer limit/balancePlatforms/:id/transferLimits/:transferLimitIdGet the details of a transfer limit using its unique transferLimitId.
  • DELETEDelete a scheduled or pending transfer limit/balancePlatforms/:id/transferLimits/:transferLimitIdDelete a scheduled or pending transfer limit using its unique transferLimitId. You cannot delete an active limit.

Manage SCA devices

  • GETGet a list of registered SCA devices/registeredDevices?paymentInstrumentId=string&pageNumber=0&pageSize=0Get a paginated list of the SCA devices you have currently registered for a specific payment instrument.
  • POSTInitiate the registration of an SCA device/registeredDevicesInitiates the registration of a user's device for Strong Customer Authentication (SCA). You can register SCA devices for business accounts or Adyen-issued…
  • POSTInitiate an association between an SCA device and a resource/registeredDevices/:deviceId/associationsInitiates an association between a user's registered SCA device and an Adyen resource. For example, you can associate an SCA device with additional business…
  • PATCHComplete an association between an SCA device and a resource/registeredDevices/:deviceId/associationsCompletes an association between a user's registered SCA device and an Adyen resource. For example, you can associate an SCA device with additional business…
  • DELETEDelete a registration of an SCA device/registeredDevices/:id?paymentInstrumentId=stringDeletes an SCA device from the list of registered devices of a specific payment instrument.
  • PATCHComplete the registration of an SCA device/registeredDevices/:idCompletes the registration of an SCA device by validating the authentication data of the device. You can register SCA devices for business accounts or…

SCA association management

  • GETGet a list of devices associated with an entity/scaAssociations?entityType=accountHolder&entityId=string&pageSize=1&pageNumber=0Returns a paginated list of the SCA devices associated with a specific entity.
  • DELETEDelete association to devices/scaAssociationsDeletes one or more SCA associations for a device.
  • PATCHApprove a pending approval association/scaAssociationsApproves a previously created association that is in a pending state.

API details

Base URL
https://balanceplatform-api-test.adyen.com/bcl/v2
Authentication
An API key in the X-API-Key header
HTTP Basic authentication (username and password)
An API key in the clientKey query parameter
Operations
97 operations on 65 pathsGET 47POST 24PATCH 15DELETE 11
3 marked deprecated
Main resources
Payment instruments 9Managed payout schedules 8Account holders 7Custom payout schedules (sweeps) 6Manage SCA devices 6Transfer limits - balance account level 6Balance accounts 5Balances 5Authorized card users 4Direct debit mandates 4
Response formats
application/json
Description format
OpenAPI 3.1.0, API version 2

How to test the Configuration API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Configuration API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the X-API-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get a balance platform” (GET /balancePlatforms/:id), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Configuration API?

The Configuration API allows you to manage your balance platform where you can create account holders, balance accounts, cards, and business accounts.… It is listed under Payments and has 97 endpoints.

Who publishes the Configuration API?

It is listed from Adyen's public API description (an OpenAPI document), not published by Adyen on Swastik Codes. Anyone who controls adyen.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Configuration API?

Requests go to https://balanceplatform-api-test.adyen.com/bcl/v2. Endpoint paths are added to this base URL.

How do I authenticate with the Configuration API?

It accepts 3 methods: an API key in the X-API-Key header; HTTP Basic authentication (username and password); an API key in the clientKey query parameter.

How many endpoints does the Configuration API have?

97 operations on 65 paths (47 GET, 24 POST, 15 PATCH, 11 DELETE). The largest groups are Payment instruments, Managed payout schedules, Account holders, Custom payout schedules (sweeps).

Is forking the Configuration API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.