Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Check account holder capabilities

Check which actions account holders are allowed to do in your platform.

A capability is an action that an account holder can do in your platform, such as use their card to withdraw cash from an ATM. Different capabilities require different verification checks.

Default capabilities

In most cases, default capabilities are configured for your platform during the design phase. When you create an account holder, these capabilities are requested for them by default.

If an account holder needs to have specific capability that's not part of the default configuration, you'll need to request for the capability.

How it works

The following diagram illustrates the verification process.

  1. Capabilities are requested for the account holder by default, or when you specifically request for a capability for them.
  2. Adyen checks if there are verification requirements that must be met. If there are any, Adyen runs the verification asynchronously. Adyen sends all verification-related updates through notification webhooks.
  3. If the verification fails, the account holder can retry the verification by providing new or revised legal entity information. They can also provide additional documents.

If the verification is successful, the account holder is allowed to use the capability. Once a capability is allowed, you can still control the use of the capability by disabling it.

List of capabilities

The following table shows capabilities that you can request for your users.

Capability Description
issueCard Allow the account holder to issue cards.
withdrawFromAtm Allow the account holder to withdraw cash from ATMs. This capability has levels.
withdrawFromAtmInRestrictedCountries Allow the account holder to withdraw cash from ATMs in restricted countries. This capability has levels.
useCardInRestrictedCountries Allow the account holder to use the card to pay for goods and services in restricted countries. This capability has levels.
useCardInRestrictedIndustries Allow the account holder to use the card to pay for goods and services from restricted industries. This capability has levels.
receiveFromBalanceAccount Allow balance accounts to receive funds from other balance accounts.
receiveFromPlatformPayments Allow balance accounts to receive funds from split payments.
receiveFromTransferInstrument Allow balance accounts to receive funds from verified transfer instruments.
sendToBalanceAccount Allow a balance account to transfer funds to other balance accounts.
sendToTransferInstrument Allow balance accounts to transfer funds to verified transfer instruments. For example, when paying out to bank accounts.

Capability levels

A capability can also have different levels: low, medium, or high. Levels increase the capability, but also require additional checks and increased monitoring. Adyen runs checks based on the requested capability and the capability level.

The amounts below are the threshold amounts per card, per day.

Capability Low Medium High
withdrawFromAtm 0 Less than or equal to 750 EUR More than 750 EUR and less than 1000 EUR
withdrawFromAtmInRestrictedCountries 0 Less than or equal to 500 EUR More than 500 EUR and less than 1000 EUR
useCardInRestrictedCountries 0 Greater than 0 Greater than 0
useCardInRestrictedIndustries 0 Greater than 0 Greater than 0

Step 1: (Optional) Request a capability

Default capabilities are automatically requested when you create an account holder. However, your account holders might need additional capabilities if, for example, your business expands its financial product offering. In these cases, you must request the additional capabilities.

The following tabs show how to request a capability.

Default capabilities are automatically requested when you create an account holder. However, if you need to request a specific capability, you must update the account holder and include the capabilities map.

In your PATCH /accountHolders/{id} request, set the capability that you are requesting as the key, and specify the following fields in the object:

Here is an example of how you would update an existing account holder to request the withdrawFromAtm capability with level medium. If you're requesting for multiple capabilities, add another set of key-value object.

Request a capability
curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \
-H "content-type: application/json" \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-X PATCH \
-d '{
  "capabilities" : {
    "withdrawFromAtm" : {
      "requested" : true,
      "requestedLevel" : "medium"
    }
  }
}'

You receive a response informing you that the capability has been requested and the verification status is pending.

Response
{
  "balancePlatform": "YOUR_BALANCE_PLATFORM",
  "id": "AH32272223222B5D3755J3C3C",
  "legalEntityId": "LE00000000000000000000001",
  "description": "S.Hopper",
  "capabilities": {
    "withdrawFromAtm": {
      "requested": true,
      "requestedLevel": "medium",
      "allowed": false,
      "verificationStatus": "pending"
    }
  }
}

Step 2: (Optional) View capabilities

View an account holder's capabilities and their verification status by using your Balance Platform Customer Area or by making a GET /accountHolders/{id} request. The following tabs explain both methods.

When you make a GET /accountHolders/{id} request, refer to the following response parameters in the capabilities object:

  • allowed: Boolean that indicates whether the capability is allowed.
  • verificationStatus: The status of the checks. The possible values are invalid, pending, rejected, or valid.
  • problems array: When this array is not empty, this means that there are errors that you need to address. Refer to verification error codes for a list of verification errors.

Step 3: Get updates

To get updates about verification status and capability changes, listen to balancePlatform.accountHolder.updated webhooks. If you haven't done so already, make sure that you have set up webhooks and that your server is properly accepting notifications.

The examples below show webhooks when the capability is not allowed because the verification is invalid, and when verification is successful and the account holder is permitted to use the capability.

When the checks have been completed and all are successful, Adyen sends a balancePlatform.accountHolder.updated webhook with:
  • verificationStatus: Set to valid.
  • allowed: Set to true.
balancePlatform.accountHolder.updated webhook - verification completed
{
  "environment" : "test",
  "type" : "balancePlatform.accountHolder.updated",
  "data" : {
    "balancePlatform" : "YOUR_BALANCE_PLATFORM",
    "date" : "2021-01-01T00:00:00+01:00",
    "accountHolder" : {
    "balancePlatform" : "YOUR_BALANCE_PLATFORM",
    "description" : "Test Account holder",
    "id" : "AH00000000000000000000001",
    "legalEntityId" : "LE00000000000000000000001",
    "capabilities" : {
       """ : {
         "requested" : true,
         "requestedLevel" : "medium",
         "requestedSettings" : {},
         "allowed" : true,
         "allowedLevel" : "medium",
         "allowedSettings" : {
            "maxAmount: {
              "value": 750000,
              "currency": "EUR
            },
            "interval": "daily"
         },
         "enabled" : true,
         "verificationStatus": "valid"
       }
    }
  }
}

In the webhook, refer to the following in the capabilities object:

  • allowed: Boolean that indicates whether the capability is allowed.
  • verificationStatus: The status of the checks. The possible values are invalid, pending, rejected, or valid.
  • problems array: When this array is not empty, this means that there are errors that you need to address. Refer to verification error codes for a list of verification errors.

Step 4: Provide the required information

If the webhook or the API response has a problems array, check the remediatingActions array. In this array, you'll find the actions that you can take to resolve the error, such as updating the data or uploading additional documents.

From our webhook example, let's say that the legal entity reviewed their name and now needs to update their data. To do this, send a PATCH /legalEntities/{id} request.

After you update the data, Adyen sends another balancePlatform.accountHolder.updated with the verificationStatus set to pending.

You'll again get updates about the status of the verification from the webhook or by making an API request.

Enable or disable a capability

To allow or prevent an account holder from using a capability, update the capability in your Balance Platform Customer Area or request a PATCH /accountHolders/{id}. The following tabs explain both methods.

To disable a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.

Deactivate a capability
curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \
-H "content-type: application/json" \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-X PATCH \
-d '{
    "capabilities": {
        "sendToTransferInstrument": {
            "enabled": false
        }
    }
}'

See also