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.
- Capabilities are requested for the account holder by default, or when you specifically request for a capability for them.
- 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 webhooks.
- 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. |
| useCard | Allow the account holder to use 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. |
| authorisedPaymentInstrumentUser | Use an Adyen-issued card when they are not the individual account holder. This capability is automatically requested when the legal entity of the account holder is an organization. |
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 |
For capabilities withdrawFromAtmInRestrictedCountries, useCardInRestrictedCountries and useCardInRestrictedIndustries the actual amount depends on the specific restricted country or industry.
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.
In your PATCH /accountHolders/{id} request, set the capability that you are requesting as the key, and specify the following fields in the object:
- requested: Set this to true.
- requestedLevel: Set this to the desired capability level.
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.
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.
{
"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 in 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 webhooks.
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.
{
"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" : {
"withdrawFromAtm"" : {
"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.
curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \
-u "ws123456@BalancePlatform.YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X PATCH \
-d '{
"individual": {
"name": {
"firstName" : "Simone",
"lastName" : "Hopper"
}
}
}'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.