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 the account holder by default.
If an account holder needs to have specific capability that is not part of the default configuration, you need to request 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 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. When a capability is allowed, you can still control the use of the capability by disabling it.
List of capabilities
| The user can... | API capability value | Notes |
|---|---|---|
| Have an Adyen-issued card. | issueCard | |
| Use the Adyen-issued card. | useCard | |
| Withdraw cash from ATMs. | withdrawFromAtm | This capability has levels. |
| Withdraw cash from ATMs in restricted countries. | withdrawFromAtmInRestrictedCountries | This capability has levels. |
| Receive funds from verified bank accounts. | receiveFromTransferInstrument | |
| Transfer funds to verified transfer instruments from balance accounts. | sendToTransferInstrument | From LEM API v3, this capability is verified at the level of the transfer instrument. This means, for example, that transfers are possible to a verified card independently of the verification status of other transfer instruments that the legal entity has. |
| Use the Adyen-issued card to pay for goods and services in restricted countries. | useCardInRestrictedCountries | This capability has levels. |
| Use the card to pay for goods and services from restricted industries. | useCardInRestrictedIndustries | This capability has levels. |
| Use an Adyen-issued card when they are not the individual account holder. | authorisedPaymentInstrumentUser | This capability is automatically requested when the legal entity of the account holder is an organization. |
| Transfer funds to other balance accounts in your platform. | sendToBalanceAccount | This capability is only required if the balance accounts are not under the same account holder. |
| Receive funds from other balance accounts in your platform. | receiveFromBalanceAccount | This capability is only required if the balance accounts are not under the same account holder. |
Capability levels
Capabilities for card issuing can also have different levels: low, medium, or high. Levels increase the capability, but may also require more 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 EUR 750 | More than EUR 750 and less than EUR 1500 |
| withdrawFromAtmInRestrictedCountries | 0 | Less than or equal to EUR 500 | More than EUR 500 and less than EUR 1000 |
| useCardInRestrictedCountries | 0 | Less than or equal to EUR 1500 | Greater than EUR 1500 |
| useCardInRestrictedIndustries | 0 | Industry-specific limits apply | Industry-specific limits apply |
Step 1: (Optional) Request a capability
Some capabilities are automatically requested when you create an account holder. However, your account holders may 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 to 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.
You receive a response informing you that the capability has been requested and the verification status is 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.
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.