Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em inglês
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

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/v2/accountHolders/AH32272223222B5D3755J3C3C \
-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": "LE322JC223222D5CR2PHBG46C",
  "description": "S.Hopper",
  "capabilities": {
    "withdrawFromAtm": {
      "requested": true,
      "requestedLevel": "medium",
      "allowed": false,
      "verificationStatus": "pending"
    }
  }
}

Step 2: (Optional) Check capabilities

You can check an account holder's capabilities and their verification status in your Balance Platform Customer Area or by making a GET /accountHolders/{id} request.

To check the capabilities of an account holder in your Customer Area:

  1. Log in to your Balance Platform Customer Area.
  2. Go to Account holders and then select an account holder ID. You can also search for an account holder by using the account holder ID or reference, or by using the ID of the linked legal entity.
  3. On the account holder details page, you can see the capabilities that have been requested for the account holder, if the capabilities are enabled and allowed, and their verification status.
  4. If there is a verification error for a capability, you see a verification error code and message.

If you make a GET /accountHolders/{id} request, in the 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.

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" : "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"
       }
    }
  }
}

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.

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/v2/accountHolders/AH32272223222B5D3755J3C3C \
-H "content-type: application/json" \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-X PATCH \
-d '{
  "capabilities" : {
    "withdrawFromAtm" : {
      "enabled" : false
    }
  }
}'

See also