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 account holders.

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

In most cases, default capabilities are configured for your platform during the design phase. These capabilities are automatically requested when you create an account holder. However, if you need to request a specific capability, you need to 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 for withdrawFromAtm capability. 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/v1/accountHolders/AH32272223222B5D3755J3C3C \
-H "content-type: application/json" \
-H "X-API-Key: YOUR_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": "LE322JC223222D5CR2PHBG46C",
  "description": "S.Hopper",
  "capabilities": {
    "withdrawFromAtm": {
      "requested": true,
      "requestedLevel": "medium",
      "allowed": false,
      "verificationStatus": "pending"
    }
  }
}

Step 2: Get updates

To get updates about verification status and capability changes, you can either:

In the webhook and API response, 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.

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 there are problems with the verification, Adyen sends a balancePlatform.accountHolder.updated with:
  • verificationStatus: Set to invalid.
  • allowed: Set to false.
  • problems: Contains verificationErrors, subErrors, and remediatingActions arrays.
balancePlatform.accountHolder.updated webhook - with verification errors array
{
  "environment":"test",
  "type":"balancePlatform.accountHolder.updated",
  "data":{
    "balancePlatform":"YOUR_BALANCE_PLATFORM",
    "date":"2021-01-02T00:00:00+01:00",
    "accountHolder":{
      "balancePlatform":"YOUR_BALANCE_PLATFORM",
      "description":"Test Account holder",
      "id":"AH32272223222B5D3755J3C3C",
      "legalEntityId":"LE322JC223222D5CR2PHBG46C",
      "capabilities":{
        "":{
          "requested":true,
          "requestedLevel":"medium",
          "requestedSettings":{

          },
          "allowed":false,
          "allowedLevel":"",
          "allowedSettings":{

          },
          "enabled":false,
          "verificationStatus":"invalid",
          "problems":[
            {
              "entity":{
                "id":"LE322JC223222D5CR2PHBG46C",
                "type":"LegalEntity"
              },
              "verificationErrors":[
                {
                  "code":"1_30",
                  "message":"Individual details couldn't be verified",
                  "remediatingActions":[
                    {
                      "code":"1_300",
                      "message":"Update individual details"
                    }
                  ],
                  "subErrors":[
                    {
                      "code":"1_3001",
                      "message":"The name and date of birth couldn't be verified.",
                      "remediatingActions":[
                        {
                          "code":"1_301",
                          "message":"Upload an ID document"
                        },
                        {
                          "code":"1_300",
                          "message":"Update individual details"
                        }
                      ],
                      "type":"invalidInput"
                    },
                    {
                      "code":"1_3000",
                      "message":"The user couldn't be verified.",
                      "remediatingActions":[
                        {
                          "code":"1_300",
                          "message":"Update individual details"
                        },
                        {
                          "code":"1_301",
                          "message":"Upload an ID document"
                        }
                      ],
                      "type":"invalidInput"
                    }
                  ],
                  "type":"invalidInput"
                }
              ]
            }
          ]
        }
      }
    }
  }
}
In general, when there are verification errors, the legal entity associated with the account holder has to review and provide the required information.
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" : "AH32272223222B5D3755J3C3C",
    "legalEntityId" : "LE322JC223222D5CR2PHBG46C",
    "capabilities" : {
       """ : {
         "requested" : true,
         "requestedLevel" : "medium",
         "requestedSettings" : {},
         "allowed" : true,
         "allowedLevel" : "medium",
         "allowedSettings" : {
            "maxAmount: {
              "value": 750000,
              "currency": "EUR
            },
            "interval": "daily"
         },
         "enabled" : true,
         "verificationStatus": "valid"
       }
    }
  }
}

Step 3: 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.

Disabling a capability

When the account holder has a capability, they are allowed to perform the action but you can still control the use of the capability.

In case you want to temporarily stop an account holder from using a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.

Disable a capability
curl https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders/AH32272223222B5D3755J3C3C \
-H "content-type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-X PATCH \
-d '{
  "capabilities" : {
    "withdrawFromAtm" : {
      "enabled" : false
    }
  }
}'

See also