# Adyen Docs — Full Markdown Corpus > Developer and merchant documentation for Adyen payments, Adyen for Platforms, Issuing, point-of-sale, and risk-management products. Every page is also available as Markdown by appending `.md` to the URL. > > This file is the concatenation of every public Markdown page on the site. It > is intended for ingestion by AI tools that accept a single document (ChatGPT > custom GPTs, Claude Projects, Cursor @docs, Perplexity Spaces, RAG > pipelines). Each page begins with a Markdown metadata block followed by the > page body; pages are separated by a horizontal rule. --- # Source: https://docs.adyen.com/.md Section: Home Title: Home --- title: "Home" url: "https://docs.adyen.com" source_url: "https://docs.adyen.com.md" canonical: "https://docs.adyen.com" last_modified: "2026-01-05T09:54:00+01:00" language: "en" --- Read about [Intelligent Money Movement](/intelligent-money-movement), our new offering that connects payments, funds management, and payouts. # Welcome to Adyen docs Explore guides, examples, and resources for every step of your Adyen journey. ![hero image](/user/pages/docs/online-payments-hero.jpg) * Online payments * In-person payments * Adyen for Platforms * Intelligent Money Movement - [Get started](/online-payments/integration-checklist/) [Get an overview of the steps to take to set up a test account](/online-payments/integration-checklist/) - [Accept payments](/online-payments/build-your-integration/) [Choose your integration type and build your integration](/online-payments/build-your-integration/) - [Add payment methods](/payment-methods/) [See which payment methods you can use to accept online payments](/payment-methods/) - [Webhooks](/development-resources/webhooks/) [Receive important updates related to payments and your account](/development-resources/webhooks/) - [Release notes](/online-payments/release-notes/) [Get informed on the latest updates for your online payments integration](/online-payments/release-notes/) ## Discover our developer resources * API Explorer Use Adyen's interactive API reference * Server-side libraries Find a library in your preferred language * Example integrations Have a look at our online payments examples * Testing tools Use API logs, test card numbers, and more * API Diff Tool Compare API versions ![](/user/pages/docs/online-payments-api-explorer.svg) [See full reference in API Explorer](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) ![](/user/pages/docs/online-payments-server-side-libraries.svg) [See installation steps ](/development-resources/libraries/)[Inspect the code in GitHub](https://github.com/adyen#server-side) ![](/user/pages/docs/online-payments-example-integrations.svg) [Explore code samples](https://github.com/adyen-examples#%EF%B8%8F-official-integration-examples) ![](/user/pages/docs/online-payments-api-logs.svg) [Debug using logs](/development-resources/logs-resources/api-logs/) ![](/user/pages/docs/online-payments-test-cards.svg) [Find a test card number](/development-resources/test-cards-and-credentials/test-card-numbers/) ![](/user/pages/docs/api-diff-tool.svg) [Try out the tool](https://docs.adyen.com/api-explorer/api-diff-tool) * [Get started](/point-of-sale/get-started/tapi-checklist/) [Get an overview of how to build an in-person payments integration](/point-of-sale/get-started/tapi-checklist/) * [Terminal API](/point-of-sale/design-your-integration/terminal-api/) [Learn how Terminal API works with our payment terminals](/point-of-sale/design-your-integration/terminal-api/) * [Payment terminals](/point-of-sale/what-we-support/select-your-terminals/) [Choose a terminal model, like countertop, portable, unattended, and more](/point-of-sale/what-we-support/select-your-terminals/) * [Tap to Pay](/point-of-sale/ipp-mobile/) [Accept in-person payments on your phone or other mobile device](/point-of-sale/ipp-mobile/) * [Release notes](/point-of-sale/firmware-release-notes/) [Get informed on the latest software updates for your payment terminals](/point-of-sale/firmware-release-notes/) ## Discover our developer resources * API Explorer Use Adyen's interactive API reference * Server-side libraries Find a library that supports Terminal API * Example integrations Have a look at our in-person payments examples * Testing tools Use API logs and Adyen POS test cards ![](/user/pages/docs/ipp-api-explorer.svg) [See full reference in API Explorer](https://docs.adyen.com/api-explorer/Management/latest/post/companies/_companyId_/terminalOrders) ![](/user/pages/docs/ipp-server-side-libraries.svg) [See installation steps ](/development-resources/libraries/)[Inspect the code in GitHub](https://github.com/Adyen#server-side) ![](/user/pages/docs/ipp-example-integrations.svg) [Explore code samples](https://github.com/adyen-examples) ![](/user/pages/docs/ipp-api-logs.svg) [Debug using logs](/development-resources/logs-resources) ![](/user/pages/docs/ipp-test-cards.svg) [How to use test cards](/point-of-sale/testing-pos-payments/test-card-v3/) * [Get started](/adyen-for-platforms-model) [Discover which Adyen for Platforms offering is best for you](/adyen-for-platforms-model) * [Platforms](/platforms) [Embed online and in-person payments into your SaaS platform, or act as a payment facilitator](/platforms) * [Marketplaces](/marketplaces) [Embed online payments into your marketplace, ecommerce website, or mobile app](/marketplaces) * [Financial products](/platforms/financial-products) [Issue cards, create business accounts, or offer business financing to your users](/platforms/financial-products) * [Classic platforms](/classic-platforms) [Adyen for Platforms integrations before Aug 1, 2022](/classic-platforms) ## Discover our developer resources * API Explorer Use Adyen's interactive API reference * Server-side libraries Find a library in your preferred language * Postman collections Fork Adyen's Postman collections * API Logs See the details of past API requests * API Diff Tool Compare API versions ![](/user/pages/docs/afp-api-explorer.svg) [See full reference in API Explorer](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) ![](/user/pages/docs/afp-server-side-libraries.svg) [See installation steps ](/development-resources/libraries/)[Inspect the code in GitHub](https://github.com/adyen#server-side) ![](/user/pages/docs/afp-postman-collection.svg) [Explore code samples](https://www.postman.com/adyendev/workspace/adyen-apis/collection/25716737-0a4fc86d-e9c9-4d5d-a6d5-b4167d276005) ![](/user/pages/docs/afp-api-logs.svg) [Debug using logs](/development-resources/logs-resources/api-logs) ![](/user/pages/docs/api-diff-tool.svg) [Try out the tool](https://docs.adyen.com/api-explorer/api-diff-tool) * [Get started](/intelligent-money-movement) [Learn how to manage your cash flow from end to end with Adyen](/intelligent-money-movement) * [Enterprise accounts](/payouts/payout-service/enterprise-accounts) [Store and manage your business funds in an Adyen account with banking capabilities](/payouts/payout-service/enterprise-accounts) * [Payouts](/payouts/payout-service) [Make payouts to third parties in multiple locations and currencies](/payouts/payout-service) * [Enterprise issuing](/issuing/account-structure-resources/issuing-enterprise) [Issue cards to manage your business expenses](/issuing/account-structure-resources/issuing-enterprise) ## Discover our developer resources * API Explorer Use Adyen's interactive API reference * Server-side libraries Find a library in your preferred language * Postman collections Fork Adyen's Postman collections ![](/user/pages/docs/imm-api-explorer.svg) [See full reference in API Explorer](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) ![](/user/pages/docs/imm-server-side-libraries.svg) [See installation steps ](/development-resources/libraries/)[Inspect the code in GitHub](https://github.com/adyen#server-side) ![](/user/pages/docs/imm-postman-collection.svg) [Explore our collections](https://www.postman.com/adyendev/adyen-apis/collection/lt40o48/transfers-api-v4) ## Join our Dev Community * [Tech blog](https://www.adyen.com/knowledge-hub/articles?topics=1kgqEExzn0tr8RXaHk6Aqe) [Stories from the team building Adyen’s payments infrastructure.](https://www.adyen.com/knowledge-hub/articles?topics=1kgqEExzn0tr8RXaHk6Aqe) * [Postman collections](https://github.com/Adyen/adyen-postman) [All our APIs available as Postman collections.](https://github.com/Adyen/adyen-postman) * [GitHub repo](https://github.com/Adyen) [Source code for all of our libraries, SDKs, and plug-ins.](https://github.com/Adyen) * [Stack Overflow](https://stackoverflow.com/tags/adyen) [Community answers to common developer questions.](https://stackoverflow.com/tags/adyen) * [Adyen developers](https://twitter.com/adyendevs) [Connect with our developer community and discover even more tools for your integration.](https://twitter.com/adyendevs) * [Developer newsletter](https://www.adyen.com/newsletter/developers) [Get the latest news for developers directly in your inbox.](https://www.adyen.com/newsletter/developers) ![](/user/pages/docs/in-person-payments-hero.jpg) ![](/user/pages/docs/afp-hero.jpg) --- # Source: https://docs.adyen.com/about-our-customer-area.md Section: Transitioning to our unified Customer Area Title: Transitioning to our unified Customer Area Description: Learn what changes to expect as the Customer Area replaces the Balance Platform Customer Area. --- title: "Transitioning to our unified Customer Area" description: "Learn what changes to expect as the Customer Area replaces the Balance Platform Customer Area." url: "https://docs.adyen.com/about-our-customer-area" source_url: "https://docs.adyen.com/about-our-customer-area.md" canonical: "https://docs.adyen.com/about-our-customer-area" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Transitioning to our unified Customer Area Learn what changes to expect as the Customer Area replaces the Balance Platform Customer Area. [View source](/about-our-customer-area.md) Starting in Q3 2025, all Balance Platform Customer Area users will transition to Adyen's unified platform - the Customer Area - where you can manage all your Adyen business in one place with the latest features. The Balance Platform Customer Area will be no longer be accessible after February 28, 2026. Most changes will be done automatically, but some user actions will be required. This page describes the timeline and [what you need to do](#what-do-you-need-to-do). ## Why this change is important The Customer Area supports all user journeys, including Issuing and Financial Products, and brings all functionality together in one platform. This reduces confusion, simplifies platform management, and improves the overall user experience. In the Customer Area, you gain: * Access to [reporting tools](/account/users/#users-within-a-company) that help you monitor which users have Customer Area access. * Faster and more secure login using [Single Sign-On (SSO)](/account/single-sign-on/). * The ability to [submit support tickets](https://help.adyen.com/en_US/knowledge/account/access-your-customer-area/how-do-i-reach-adyen-support) directly from the Customer Area. * Improved navigation, including the option to pin frequently used pages so they stay at the top of the menu. * The option to [subscribe to notifications](/account/notification-center/) to stay informed about fraud alerts, service disruptions, and other important updates. ## What do you need to do? Starting in Q3 2025, all users should use the Customer Area instead of the Balance Platform Customer Area. If you do not have a Customer Area account, you will be prompted to set one up when you access the Balance Platform Customer Area. The setup process includes steps to: 1. Create a password. 2. Register a [multifactor authentication (MFA)](/account/multifactor-authentication/) device. You must complete this setup for both the [Customer Area TEST environment](https://ca-test.adyen.com/ca/) and the [Customer Area LIVE environment](https://ca-live.adyen.com/ca/). If you already have a Customer Area account, no further action is needed. If access to specific features is missing, contact your admin to assign the correct [roles](https://docs.adyen.com/account/user-roles/#platforms). ## Timeline The Customer Area will replace the Balance Platform Customer Area in four stages. The steps below describe what Adyen will do at each stage, along with any required actions from admins and other users. These timelines are indicative and subject to change. Final dates will be confirmed closer to Q3 2025. The following users will *not* be affected: * Users who already have a Customer Area account. * Users with duplicate email addresses in the Balance Platform Customer Area. *** #### Stage 1 – September 1, 2025 Your users will be prompted on how to set up their account for the Customer Area TEST environment when they access the Balance Platform Customer Area. The setup process includes steps to: 1. Create a password. 2. Register a [multifactor authentication (MFA)](/account/multifactor-authentication/) device. They will receive a confirmation email once the process is successful. In the Customer Area TEST environment, your users are able to: * View account holder details, capabilities, and legal entity information. * Initiate and view transfers. * View balance accounts. * Configure scheduled payouts. * View Adyen payment instruments. * Access reports, API credentials, and webhook configurations. *** #### Stage 2 – September 8, 2025 Your users will be prompted on how to set up their account for the Customer Area LIVE environment when they access the Balance Platform Customer Area. The setup process includes steps to: 1. Create a password. 2. Register a [multifactor authentication (MFA)](/account/multifactor-authentication/) device. They will have access to the same functionality as described in Stage 2. *** #### Stage 3 – October 9, 2025 Adyen will disable the ability to create new users in both the [Balance Platform Customer Area TEST environment](https://balanceplatform-test.adyen.com/balanceplatform/) and the [Balance Platform Customer Area LIVE environment](https://balanceplatform-live.adyen.com/balanceplatform/). As an admin, activate your Customer Area test account by following the instructions in the [Balance Platform Customer Area TEST environment](https://balanceplatform-test.adyen.com/balanceplatform/). This ensures you can continue managing access for your users. The setup process includes steps to: 1. Create a password. 2. Register a [multifactor authentication (MFA)](/account/multifactor-authentication/) device. *** #### Stage 4 – February 2026 Users can no longer access the Balance Platform Customer Area TEST or the Balance Platform Customer Area LIVE environments. ## What are the differences between the Balance Platform Customer Area and the Customer Area? The Customer Area introduces several changes in how account access, navigation, and user management are handled. These are: * **Account-level access**: in the Customer Area, access is granted at the account level either on a [company account or a merchant account](/platforms/account-structure-resources/). * **User management**: users are [managed directly](/account/users) in the Customer Area. * **Navigation structure**: pages from the Balance Platform Customer Area are still available, but they appear under different sections in the Customer Area. The table below outlines the changes to the navigation structure. Unchanged items are not included in this table. | Balance Platform Customer Area navigation | Customer Area navigation | | ----------------------------------------- | ----------------------------------------------- | | Transfers | Transactions > Transfers | | Payment instruments | Financial products > Payment instruments | | Score > Overview | Accounts & balances > Score | | Score > Case management | Accounts & balances > Score > View Cases | | Score > High risk list | Accounts & balances > Score > High risk lists | | Score > Automated actions | Accounts & balances > Score > Automated actions | | Score > Risk rules | TBD | | Issuing > Card orders | Financial products > Card orders | | Issuing > Transaction rules | Financial products > Transaction rules | | Issuing > Disputes | Financial products > Issuing disputes | | Issuing > Relayed authorization | Financial products > Relayed authorization | | Capital | Financial products > Capital | | Insights > KYC verification insights | Insights > KYC verification insights | | Developers > API credentials | Developers > API credentials > Platforms tab | | Developers > Webhooks | Developers > Webhooks > Platforms tab | | Users | Account > Users | | Settings > Hosted onboarding | Settings > Hosted onboarding | | Settings > Report columns | Settings > Report columns | | Reports | Reports > Balance platform tab | ## Will my login credentials change? Yes. As part of the setup in the Balance Platform Customer Area, you are asked to create a new password and register a MFA device for both the [Customer Area TEST environment](https://ca-test.adyen.com/ca/) and [Customer Area LIVE environment](https://ca-live.adyen.com/ca/). After completing setup, you can log in using your email, password, and MFA device. ## How many times can I send the verification email to set up my Customer Area user? The verification email can only be sent once. If it is deleted or lost, you will need to contact your Customer Area admin to ask for a new one. ## How much time do I have to set up my Customer Area user after receiving the verification email? You have two weeks to complete the setup. After that, the link expires, and you will need to ask your Customer Area admin to send a new verification email. ## What roles will I get in the Customer Area? Your roles in the Customer Area are mapped from your existing Balance Platform Customer Area roles. Some roles are equivalent to a bundle of Customer Area roles, which are listed in the table below. | Balance Platform Customer Area role | Customer Area role | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Balance platform admin role**\* | Merchant user management Balance platform base role View account holders PII View bank transfers PII View payment instrument PII Merchant standard role Manage API credentials Generate Balance Platform reports Download Balance Platform reports Merchant Marketplace Risk Role Download tax form Manage account holders & legal entities | | **Balance platform base role** | Balance platform base role Merchant allowed own password reset Merchant standard role | | **Developer**\*\* | Manage API credentials Merchant technical integrator | | **Manage hosted onboarding themes** | Merchant manage hosted onboarding | | **Permits access to Balance Platform capital overview and details** | Capital base role | | **Configure report columns** | Generate Balance Platform reports | | **Download reports** | Download Balance Platform reports | | **Generate and schedule reports** | Generate Balance Platform reports | | **Risk admin** | Merchant Marketplace Risk Admin | | **Risk base** | Merchant Marketplace Risk | | **Unchanged roles** | Download KYC documents Download tax form Manage account holder capabilities Manage account holders & legal entities View account holders PII View KYC documents Manage relayed authorization configuration Update card status View payment instrument PII Manage issuing disputes Manage transaction rules Download transfer confirmation letter Initiate internal transfers Initiate payouts to transfer instruments Configure scheduled payouts View bank transfers PII Capital base role | \* Users with the **Balance platform admin role** should have full company account access when the Merchant accounts available to them after the transition include all Merchant accounts in the company.\ \*\* Users with the **Developer role**, who do not have existing admin permissions, will only have access to the **Webhooks** and **API credentials** pages at the merchant level. To access these pages at the company level, a Customer Area admin must update their permissions. ## As an admin, how can I copy a user’s merchant account access and their roles from the Balance Platform Customer Area to the Customer Area? If a user has an active account in both the Balance Platform Customer Area (BPCA) and the Customer Area, admins can copy the user’s merchant account access and their roles from the BPCA to the Customer Area. Only merchant account access and roles that the user does *not* already have in the Customer Area are added. To perform this action, the admin must have the **Merchant admin** or **Merchant user management** role.\ Additionally, admins will only be able to assign roles or accounts that they have access to. If the admin does not have access, they will be able to see the name of the role or the merchant account, but not be able to assign it. To copy a user’s merchant account access and roles: 1. Go to **Account** > **Users** in the Customer Area. 2. Open the **User details** page of the target user. 3. Select **Copy access from balance platform**.\ If the target user already has the same merchant account access and roles in the Customer Area as they do in the BPCA, the **Copy access from balance platform** button is disabled. 4. If the user has multiple BPCA accounts, select which BPCA account(s) to copy from.\ A **Migrated** label is shown for BPCA accounts where the access already matches the Customer Area. 5. If the user has merchant account–level access, select which merchant accounts to add.\ Only merchant accounts that the user does *not* already have access to in the Customer Area are shown.\ If the target user has company account–level access, this step is skipped because the user already has full account access. 6. Select which roles to copy.\ Only roles that the user does *not* already have assigned in the Customer Area are shown. 7. Review the summary and select **Confirm**. ## Will I lose any data? No, your transfers, balance accounts, account holders, and payment instruments are visible in the Customer Area. ## Will there be any downtime? No, both environments are accessible during this process. ## Will API functionalities be affected? No, your API integrations will remain functional and unchanged. ## What happens to my Balance Platform Customer Area deep links? Deep links to the Balance Platform Customer Area will stop working after the deprecation deadline. To avoid broken links, update all existing links, for example those stored in tools such as Salesforce, to the new Customer Area URLs. To link to a page in the Customer Area, you must include the correct merchant account in the URL.\ The merchant account in the link must belong to the Balance Platform where the entity you are linking to, for example, an account holder, transfer, or balance account, was created. To get a link with the correct merchant account: 1. Open the page in the Customer Area. 2. Open the account selector panel. 3. Select the kebab menu (⋮) in the top-right corner. 4. Select **Copy link to this page**. Use the examples in the following table to understand how Balance Platform Customer Area URLs map to the new Customer Area format in the **Customer Area TEST environment**. | Balance Platform Customer Area URL | Customer Area URL | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | | | | | | | | | Use the examples in the following table to understand how Balance Platform Customer Area URLs map to the new Customer Area format in the **Customer Area LIVE environment**. | Balance Platform Customer Area URL | Customer Area URL | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | | | | | | | | | ## How can I grant access to a third-party integrator? You can grant access to your technical integrator using the [Manage partner user](/account/users/partner-users) feature in the Customer Area. ## Where can I find more information about the Customer Area? * [Create and manage users and roles in the Customer Area](/account/users) * [Platform-specific roles and permissions](/account/user-roles/#platforms) * [How to access the Customer Area](https://help.adyen.com/knowledge/account/access-your-customer-area) * [Customer Area help resources](https://help.adyen.com/academy/how-to-videos/customer-area) * [Adyen for Platforms help resources](https://help.adyen.com/academy/how-to-videos/adyen-for-platforms) --- # Source: https://docs.adyen.com/account.md Section: Account Title: Account Description: Learn how to manage your Adyen account through the Customer Area. --- title: "Account" description: "Learn how to manage your Adyen account through the Customer Area." url: "https://docs.adyen.com/account" source_url: "https://docs.adyen.com/account.md" canonical: "https://docs.adyen.com/account" last_modified: "2021-05-03T13:45:00+02:00" language: "en" --- # Account Learn how to manage your Adyen account through the Customer Area. [View source](/account.md) With Adyen, you get access to the [Customer Area](https://ca-test.adyen.com/). This is an online dashboard where you can manage your integration across different channels, regions, and currencies: ##### Customer Area webinar To learn more about managing your Adyen account, [sign up for an upcoming webinar](https://help.adyen.com/academy/webinars). * Manage all your payments and [payment methods](/payment-methods). * Manage how you get paid, and get insight into to the balances on your account. * Download reports and view charts about authorisation rates, history of sales, and other payment activity. To learn more about the Customer Area, you can also watch a video here: Embedded video (Vimeo): ## Set up your account Set up your Adyen account to match your business needs. [![](/user/themes/adyen/images/illustrations/company.svg)](/account/account-structure) ###### [Account structure](/account/account-structure) [Understand Adyen's account structure and how to set it up for your business.](/account/account-structure) [![](/user/pages/docs/12.account/users2.svg?decoding=auto\&fetchpriority=auto)](/account/users) ###### [Users](/account/users) [Give your team members access to different parts of your Adyen account.](/account/users) ## Payments Manage the payments that you process through Adyen. [![](/user/pages/docs/12.account/overview.svg?decoding=auto\&fetchpriority=auto)](/account/manage-payments) ###### [Manage payments](/account/manage-payments) [Look up and refund, cancel, or capture payments.](/account/manage-payments) [![](/user/pages/docs/12.account/puzzle.svg?decoding=auto\&fetchpriority=auto)](/account/payments-lifecycle) ###### [Payments lifecycle](/account/payments-lifecycle) [Learn about payment statuses and how you can track them.](/account/payments-lifecycle) ## Finance Manage your finances with Adyen. [![](/user/pages/docs/12.account/payout.svg?decoding=auto\&fetchpriority=auto)](/account/getting-paid) ###### [Getting paid](/account/getting-paid) [Find out how you get the money from the payments processed with Adyen.](/account/getting-paid) [![](/user/pages/docs/12.account/abacus.svg?decoding=auto\&fetchpriority=auto)](/account/balances) ###### [Balances](/account/balances) [Learn about the balances on your merchant account and how to manage them.](/account/balances) [![](/user/themes/adyen/images/illustrations/document-filled.svg)](/reporting/downloading-reports) ###### [Reports](/reporting/downloading-reports) [Subscribe to reports for reconciliation and other financial tasks.](/reporting/downloading-reports) --- # Source: https://docs.adyen.com/account/account-structure.md Section: Account Title: Account structure Description: Understand Adyen's account structure and how to set it up for your business. --- title: "Account structure" description: "Understand Adyen's account structure and how to set it up for your business." url: "https://docs.adyen.com/account/account-structure" source_url: "https://docs.adyen.com/account/account-structure.md" canonical: "https://docs.adyen.com/account/account-structure" last_modified: "2023-10-19T11:14:00+02:00" language: "en" --- # Account structure Understand Adyen's account structure and how to set it up for your business. [View source](/account/account-structure.md) With Adyen, you have a single [company account](#company-account), and one or more sub-accounts called [merchant accounts](#merchant-accounts). If you have several merchant accounts, you can additionally group them together in [account groups](#account-groups). If processing point-of-sale payments, you can additionally have one or more **stores** under each merchant account, to represent your physical store locations. For more information, refer to [Account structure for in-person payments](/point-of-sale/design-your-integration/determine-account-structure). ## Company account Your company account represents your core business entity with us. The company account holds all your merchant accounts and [users](/account/users), and is where your [monthly invoice](/reporting/invoice-reconciliation/payment-processing-invoice) is issued to by default. ## Merchant accounts Your payments are processed in sub-accounts called merchant accounts. The merchant account is where you receive the payout of funds, as well as the reports used for [reconciliation](/reporting/settlement-reconciliation). It is also where you configure payment methods, processing currencies, and override risk management rules set at company level. The number of merchant accounts you should have depends on your business. For many of our customers, it is enough to have a single merchant account. However, having multiple merchant accounts might be useful or even required in some cases. For guidance on choosing an account structure that works best for your business, refer to [Define your account structure](/account/define-account-structure). For example, an online business selling tea to shoppers in Europe and in the US can have two merchant accounts for processing payments in Europe and in the US, respectively: ![](/user/pages/docs/12.account/01.account-structure/account-structure.svg?decoding=auto\&fetchpriority=auto) ## Account groups Account groups provide an additional layer to manage your company account in case you have several merchant accounts. By grouping several merchant accounts into an account group, you can give users access to all merchant accounts in that group. For example, depending on their [user roles](/account/user-roles), users can: * Search for payments across all merchant accounts in the account group. * View and download reports across all merchant accounts in the account group. You can create as many account groups as you like, however one merchant account can only belong to one account group. To learn how to create account groups, refer to [Create an account group](/account/manage-account-structure#create-account-group). For example, you could create an account group for all merchant accounts in a certain country or region. If you have several brands under your company account, you could create a separate account group for each brand. The example below shows a business with merchant accounts in the Netherlands, Germany, Sweden, and in the US. The merchant accounts in the Netherlands, Germany, and Sweden belong to the Account group EU. ![](/user/pages/docs/12.account/01.account-structure/account-groups.svg?decoding=auto\&fetchpriority=auto) ## Next steps ###### [Define your account structure](/account/define-account-structure) [Determine which account structure works best for your business.](/account/define-account-structure) ###### [Manage your account structure](/account/manage-account-structure) [Request new merchant accounts and create account groups.](/account/manage-account-structure) --- # Source: https://docs.adyen.com/account/balances.md Section: Account Title: Balances Description: Learn about the balances held in your company and merchant accounts and how to manage them. --- title: "Balances" description: "Learn about the balances held in your company and merchant accounts and how to manage them." url: "https://docs.adyen.com/account/balances" source_url: "https://docs.adyen.com/account/balances.md" canonical: "https://docs.adyen.com/account/balances" last_modified: "2021-11-22T11:32:00+01:00" language: "en" --- # Balances Learn about the balances held in your company and merchant accounts and how to manage them. [View source](/account/balances.md) Balances refer to a collection of funds that belong to your business and are held in your Adyen merchant accounts. You can check these balances at the merchant account level or at the company account level (this shows the sum of the balances in all the merchant accounts). Checking and managing these balances allow you as a business to: 1. Keep track of your balance history 2. Ensure that you have enough funds to cover potential refunds or chargebacks 3. Monitor the settlement of your sales funds 4. Monitor the amount you receive in your payouts Your Adyen account can hold two types of balances: * [Available funds](#available-funds) * [Deposit](#deposit) You can [view](/account/view-your-balances-pilot) and [manage](/account/manage-your-balances-pilot) these balances in the CA or using the Balance Control API. In your merchant account, you can also use the [activity log](#activity-log) to see details of the events that caused balance adjustments. ## Available funds The available funds on a merchant account refers to the balances held in your merchant account that you can adjust. The available funds on a company account refers to the sum of the available funds on all the merchant accounts under the company. To get the total amount of available funds, you can sum up the following balances: * **Pending**: the gross amount of sales and refunds that have not yet been settled by the respective card scheme or payment method. * **Next payout**: the current amount to be settled to your bank account at the next moment of payout. This amount changes over time as sales, refunds, and other adjustments are processed. For more information, see [Next payout](/account/balances-pilot/next-payout). * **Reserve**: the available amount you configure to cover for refunds, chargebacks, and other operational expenses. The reserve is only used if you have insufficient in-process funds to process these transactions. For more information, see [Reserve](/account/balances-pilot/reserve) * **Negative refund allowance:** the additional balance to issue refunds even when your reserve is too low or insufficient. Adyen decides who is eligible to get a negative refund allowance. ## Deposit The **Deposit** is the amount withheld by Adyen to cover potential losses and liabilities due to payment processing. Adyen holds the deposit to protect you from settlement uncertainties in case of extreme scenarios, such as the COVID-19 pandemic for example. By holding the necessary funds, we can consistently maintain the cash outflow without having to block payouts during unforeseen events. Unlike the reserve, you cannot determine your own deposit amount. Adyen calculates the deposit requirement for your account daily, based on variables such as your processing volume and the number of chargebacks and refunds. We can increase or decrease the deposit requirements based on changes in these variables. If the deposit requirement increases, funds from your sales are booked to the deposit. If the deposit requirement decreases, the excess deposit is released and added to the next payout amount. For more details, see [Deposit](/account/balances-pilot/deposit). ## Activity log The **Activity log** provides a historic overview of the past activities, such as balance transfers, payouts, adjustments, currency exchange, and top-ups. ## Next steps [View your balances](/account/view-your-balances-pilot) [Stay updated about the balances in your company and merchant accounts.](/account/view-your-balances-pilot) [Manage your balances](/account/manage-your-balances-pilot) [Stay updated about the balances in your company and merchant accounts.](/account/manage-your-balances-pilot) --- # Source: https://docs.adyen.com/account/balances/deposit.md Section: Account Title: Deposit Description: Learn about the deposit on your merchant account and how to manage it. --- title: "Deposit" description: "Learn about the deposit on your merchant account and how to manage it." url: "https://docs.adyen.com/account/balances/deposit" source_url: "https://docs.adyen.com/account/balances/deposit.md" canonical: "https://docs.adyen.com/account/balances/deposit" last_modified: "2021-11-22T11:28:00+01:00" language: "en" --- # Deposit Learn about the deposit on your merchant account and how to manage it. [View source](/account/balances/deposit.md) The **Deposit** is the amount withheld by Adyen to cover potential losses and liabilities due to payment processing. Adyen holds the deposit to protect you from settlement uncertainties in case of extreme scenarios, such as the COVID-19 pandemic for example. By holding the necessary funds, we can consistently maintain the cash outflow without having to block payouts during unforeseen events. Unlike the reserve, you cannot determine your own deposit amount. [Adyen calculates the deposit requirement](#how-deposit-works) for your account daily, based on variables such as your processing volume and the number of chargebacks and refunds. We can increase or decrease the deposit requirements based on changes in these variables. If the deposit requirement increases, funds from your sales are booked to the deposit. If the deposit requirement decreases, the excess deposit is released and added to the next payout amount. ## Check your deposit details To check your deposit details, you need the [user role](/account/user-roles): * **Merchant financial** To check your deposit details: 1. Log in to your [live Customer Area](https://ca-live.adyen.com/), and switch to the merchant account. 2. Go to **Finance** > **Balances overview** 3. Select the **Deposit** tab. ![Deposit overview](/user/pages/docs/12.account/15.balances/15.deposit/deposit-overview.png) ## Why you need a deposit As part of its [acquiring](/get-started-with-adyen/adyen-glossary/#acquirer-or-acquiring-bank) operations, Adyen holds full financial responsibility for incoming [chargebacks](/get-started-with-adyen/adyen-glossary/#chargeback). When shoppers use their right for a chargeback via a [chargeback-supporting payment method](/payment-methods/?features%5B0%5D=chargebacks), Adyen deducts the related funds from your next payout. However, it can happen that your account doesn't have enough funds available to cover the chargeback. For example, if you stop processing payments with Adyen. In this case, we use the deposit to cover the chargeback amount. The funds held by Adyen as a deposit are exclusively owned by you. If you stop processing payments with Adyen, the deposit will be gradually paid back to you after the deduction of chargeback costs. As soon as Adyen has no more potential exposure to chargebacks, which is approximately six months after the processing has stopped, the remaining deposit will be returned to you. ## How the deposit is calculated The deposit calculation is based on the difference between the potential exposure and available coverage. * [Exposure](#exposure) is a sum of estimated potential losses on your merchant account. * [Coverage](#coverage) is a sum of ways to cover these potential losses. Adyen estimates the exposure that we have for your merchant account based on transaction data. This process always runs daily *before the payout* to ensure that the exposure on your merchant account does not exceed the current coverage by more than **EUR10,000**. If the total exposure exceeds the total coverage by more than EUR10,000, then Adyen automatically withholds funds from your next payout to cover the exposure. The process ensures that if you stop processing with Adyen, then we can cover any potential losses related to your merchant account. ### Calculation example If the estimated exposure is EUR25,000, and the coverage is EUR18,000, then the above-mentioned threshold of EUR10,000 is not exceeded. So, we do not withhold any funds from your next payout and the required *deposit remains unchanged*. However, if the exposure increases to EUR30,000, and the coverage is still EUR18,000, then the above-mentioned threshold of EUR10,000 is exceeded by EUR2,000. This means that the required *deposit will be increased* by EUR12,000 — the actual difference between the exposure and the coverage. ## Exposure Exposure consists of three components: fulfillment exposure, chargeback exposure, and refund exposure. * **Fulfillment exposure**\ Fulfillment exposure is calculated based on the transactions that have been paid, but the product or service is delivered at a later date. The calculation incorporates the value of transactions processed through credit cards, direct debit, and Buy Now Pay Later (BNPL) during the *order fulfillment time*—the average number of days it takes for a product or service to be completely delivered to a shopper. * **Chargeback and refund exposure**\ Adyen uses a forward-looking method to calculate [chargeback](/get-started-with-adyen/adyen-glossary/#chargeback) and [refund](/get-started-with-adyen/adyen-glossary/#refund-definition) exposure. This method uses historical data to predict how many chargebacks and refunds will happen in the future. This prediction is based on the past 180 days of data, which includes factors such as the timing and amount of reversals, as well as the likelihood of reversal over time. **Calculation**\ We consider the following factors when calculating chargeback and refund exposure: * The expected reversal rate, which is based of the past 180 days of data to understand if, how often and when chargebacks and refunds occur. * The total amount of payments that could potentially be reversed (chargebackable volume). We multiply the expected reversal rate by the chargebackable volume to get an estimate of the chargeback and refund exposure. ## Coverage Coverage is composed of two components: processing coverage and securities coverage. **Processing coverage** consists of your pending balance and payable balance. The processing coverage counts towards the required deposit and will be used to fill up the current deposit in case the required deposit increases. * **Pending balance**\ The total amount of funds that are approved to be paid out to Adyen from [card schemes](/get-started-with-adyen/adyen-glossary/#card-networks-or-card-schemes) and [local payment methods](/get-started-with-adyen/adyen-glossary/#local-payment-methods-or-alternative-payment-methods) on your behalf, meaning that they were successfully authorized and captured. Settlement timelines may vary based on the type of transaction. * **Payable balance**\ The total amount of funds received by Adyen from [card schemes](/get-started-with-adyen/adyen-glossary/#card-networks-or-card-schemes) and [local payment methods](/get-started-with-adyen/adyen-glossary/#local-payment-methods-or-alternative-payment-methods) that have been settled and are about to be paid out to you. Note that in some cases, the [payout can become negative](/account/balances/next-payout#negative-payable). **Securities coverage** corresponds to funds or instruments held by Adyen to offset the exposure after the deduction of processing coverage. * **Bank guarantee**\ Adyen can accept a bank guarantee which can be used as a partial or full substitute to the deposit. However, bank guarantees are reviewed on a case-by-case basis. * **Actual deposit**\ This component corresponds to the part of the coverage that compensates for the difference between total exposure and total coverage. If the required deposit is higher than the actual deposit balance, funds will be deducted from your next payout until the required deposit amount is met. * **Accepted risk**\ This component represents the exposure that Adyen accepts on a merchant account before increasing the deposit. The amount of accepted risk allocated to you is determined on a case-by-case basis, based on the analysis of your financial stability and volume of transactions. ## Deposit types Depending on the order fulfillment time and the type of industry you operate in, there are two models that can be applied to your deposit calculation: 1. **Standard deposit** This deposit calculation uses a fixed fulfillment time assumption to calculate the fulfillment exposure. This approach is used for the majority of merchants processing with Adyen. 2. **Delivery date deposit & airline date of travel deposit** The delivery date deposit and the airline date of travel deposit are used if you operate in industries where order fulfillment times can vary significantly. Such industries include but are not limited to ticketing, airlines, hospitality, car rental, and event planning. When orders have different fulfillment times, it is difficult to accurately estimate the fulfillment exposure for a given merchant account. In these cases, we use a dynamic model to calculate the exposure of all unfulfilled transactions at a given time. With this model of deposit calculation, we require you to send `deliveryDate` with each transaction which includes the date of the event. For example, a flight or a hotel check-in. ## Optimize your deposit The deposit is calculated algorithmically and is consistently applied to all merchant accounts. However, there are some ways you can optimize your deposit amount: * [Implement Unified Commerce](#unified-commerce-payment-solution) * [Manage order fulfillment time](#fulfillment-time) * [Manage chargeback rates](#chargeback-rates) * [Supply a bank guarantee](#bank-guarantee) ### Unified Commerce payment solution You can implement Adyen's [point-of-sale](/point-of-sale) solution in addition to the ecommerce offering. Point-of-sale transactions have zero order fulfillment time and lower chargeback and refund rates. ### Reduce order fulfillment time You can reduce your deposit by limiting the period between the time the transaction is processed and the fulfillment of the related goods or services. For example, by default, a monthly subscription service will have an order fulfillment time of 30 days. However, if you decide to bill shoppers at the end of the month instead of the beginning of the month, the order fulfillment time for the subscription will be zero. To check your order fulfillment time: 1. Log in to your [live Customer Area](https://ca-live.adyen.com/), and switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select the **Deposit** tab. Under **Fulfillment exposure**, you'll see **Conf. delivery days**. If your fulfillment time **Conf. delivery days** differs from your actual fulfillment time, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Manage chargeback rates You can reduce your exposure by limiting the number of chargebacks on your account. As chargeback exposure is based on historical chargeback data, a reduction in the chargeback rate will lead to a reduction in the deposit requirement. This can be managed by enabling [3D Secure](/online-payments/3d-secure) or changing the [risk settings](/get-started-with-adyen/adyen-glossary/#risk-management). ### Supply a bank guarantee You can manage your deposit requirement by supplying Adyen with a bank guarantee. A bank guarantee is equivalent to cash held in deposit. --- # Source: https://docs.adyen.com/account/balances/next-payout.md Section: Account Title: Next payout Description: Learn about the next payout and why it might be negative. --- title: "Next payout" description: "Learn about the next payout and why it might be negative." url: "https://docs.adyen.com/account/balances/next-payout" source_url: "https://docs.adyen.com/account/balances/next-payout.md" canonical: "https://docs.adyen.com/account/balances/next-payout" last_modified: "2023-03-23T12:24:00+01:00" language: "en" --- # Next payout Learn about the next payout and why it might be negative. [View source](/account/balances/next-payout.md) The **Next payout** balance is the current amount to be settled to your bank account at the next moment of payout. This amount will change over time as sales, refunds, and other adjustments are being processed. ## Negative next payout ##### More on this topic Read frequently asked questions about the [negative payout balance](https://help.adyen.com/knowledge/finance/balances/why-did-i-receive-a-negative-balance-notification). If the expenses of a merchant account exceed the amount of processed payments, the next payout balance might become negative. The expenses incurred by a merchant account include: * Chargebacks, refunds, and payouts. * Invoice deductions. * Transaction fees. For example, fees for refunds. A negative next payout balance may prevent you from processing refunds and payouts, or from receiving your deposit. If you have set up a [reserve with auto-funding](/account/balances/reserve#auto-funding), the amount needed to balance out the negative next payout will be debited from your payout bank account. If you haven't set up a reserve with auto-funding, you have the following options to eliminate the negative next payout balance: * [Transfer balance from another merchant account](/account/balances/reserve#transfer-balance) that has a positive next payout balance. * [Top up your Adyen account](/account/balances/reserve#top-up). ## See also * [Monthly finance report](/reporting/monthly-and-daily-finance-report) * [Account structure](/account/account-structure) --- # Source: https://docs.adyen.com/account/balances/reserve.md Section: Account Title: Reserve Description: Make sure that you always have enough funds for refunds, chargebacks, and other operational expenses. --- title: "Reserve" description: "Make sure that you always have enough funds for refunds, chargebacks, and other operational expenses." url: "https://docs.adyen.com/account/balances/reserve" source_url: "https://docs.adyen.com/account/balances/reserve.md" canonical: "https://docs.adyen.com/account/balances/reserve" last_modified: "2023-08-28T17:50:00+02:00" language: "en" --- # Reserve Make sure that you always have enough funds for refunds, chargebacks, and other operational expenses. [View source](/account/balances/reserve.md) Setting up a reserve helps make sure you always have enough funds for refunds, chargebacks, and other operational expenses. For example, when you refund a payment, the funds are deducted from your pending and next payout balances. If you have insufficient funds in both your pending and next payout balance to process the refund, the refund amount is deducted from the reserve. If you have not set up a reserve, or if the reserve does not have enough funds for the refund either, the refund fails. Adyen does not automatically retry refund requests that failed due to insufficient funds. When enough funds are available again, resubmit the failed refund request. An overview of all refunds that were not processed due to insufficient funds is available in the [Modifications not processed](/reporting/modifications-not-processed/) report. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online](/online-payments) or [point-of-sale](/point-of-sale) integration with Adyen. | | **[API credential roles](/development-resources/api-credentials/roles/)** | To [manage your reserve using the API](#transfer-balance), make sure you have the credentials for Balance Control API with the following role:- **Balance control API - Balances management** | | **[Customer Area roles](/account/user-roles)** | To manage your reserve using the Customer Area, make sure that you have one of the following roles:- **Merchant financial** - **Merchant admin** | ## Set up a reserve Setting up a reserve means defining a threshold. The threshold is the amount that you want to be available in the reserve. The amount that is needed to fill the reserve up to this threshold is deducted from your payable balance when the [payout batch](/account/sales-day-payout) closes. To set up a reserve, you need the following [user role](/account/user-roles): * **Merchant financial** To set up a reserve for a merchant account, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. On the **Balance** tab, at **Reserve** select **Edit threshold**. 4. Under **Change reserve threshold** enter the amount that you want to be available in the reserve. 5. Select **Save**. ## Receive notifications about your reserve We can send you a [Customer Area notification](/account/notification-center) when the reserve balance drops below a certain percentage of the reserve threshold. For example, if you set the percentage to **30%** and the reserve threshold is **EUR 1200**, you get a notification when the reserve balance drops below **EUR 360**. To receive notifications when the reserve balance drops below a certain value, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. On the **Balance** tab, at **Reserve** select **Edit threshold**. 4. Switch on the **Low reserve balance alert (%)** toggle to enable [Customer Area notifications](/account/notification-center). 5. Select **Save**. ## Add funds to your reserve You have the following options to add funds to your reserve: * [Increase the threshold](#threshold): the amount needed to fill the reserve is deducted from the payable balance. * [Set up auto-funding](#auto-funding): the amount needed to fill the reserve is debited from your bank account. * [Top up your Adyen account](#top-up): for payments made in **EUR** or **USD**, the funds are added to your reserve within two business days. For most other currencies, the funds are added to your reserve within three business days. * [Make a transfer from another merchant account](#transfer-balance): the amount needed to fill the reserve is transferred from your other merchant account that has more funds available. ### Change the reserve threshold This is what happens when you change the reserve threshold: * If you **increase the threshold**, the amount needed to fill the reserve up to the new threshold is deducted from your payable balance when the payout batch closes. * If you **lower the threshold**, the amount above the new threshold is added to your payable balance when the payout batch closes. For example, if you start with a threshold of **EUR 7000** and increase it to **EUR 9000**, we move **EUR 2000** from the payable to fill the reserve. If you lower the threshold of **EUR 7000** to **EUR 4000**, we move **EUR 3000** from the reserve to your payable balance. To change the reserve threshold, you need the following [user role](/account/user-roles): * **Merchant financial** To change the reserve threshold for a merchant account, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select **Control your balances**. 4. Under **Reserve balance**, select **Change threshold**. 5. Enter the new threshold and select **Save**. ### Set up auto-funding With auto-funding, we initiate a direct debit payment when a certain percentage of the reserve has been used. For example, if you set the percentage to **30%** and the reserve threshold is **EUR 1200**, automatic funding is triggered when the reserve balance drops below **EUR 840**. We then initiate a direct debit payment to fill the reserve up to the threshold value of **EUR 1200**. The amount needed to fill the reserve is debited from the bank account where you receive the payouts for this merchant account. You can only use auto-funding for payout bank accounts in **EUR**, **GBP**, or **USD**. To set up auto-funding, you need both the [user roles](/account/user-roles): * **Merchant financial** * **Merchant admin** To set up auto-funding for a merchant account, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select **Control your balances**. 4. Under **Auto-funding**, select **Request**. 5. Under **Request auto-funding**, enter a number to indicate a percentage of the reserve threshold.\ For example, enter **30** to trigger automatic funding when **30%** of the reserve threshold has been used. 6. Select **Request auto-funding**. ### Top up your Adyen account The fastest way of transferring funds to your account is to generate a top-up payment. When we receive the top-up payment, we add the funds to your reserve. This can take up to four business days. Any amount above the reserve threshold is transferred back to you with the next payout. Therefore, you may need to [change the reserve threshold](#threshold). For some currencies, for example **ZAR**, you need to [use specific details](https://help.adyen.com/knowledge/payments/refunds/how-can-i-transfer-funds-into-my-adyen-account) for your bank transfer. To generate a top-up payment, you need the following [user role](/account/user-roles): * **Merchant financial** To transfer funds into your Adyen account, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select **Top up**. 4. Select the reason for your top-up payment. 5. Select the currency and enter the amount that you want to add to the reserve. 6. Select **Top up with your bank account** or **Other top up methods**. 7. In the new window that opens, complete the payment. For payments made in **EUR** or **USD**, the funds are added to your reserve within two business days. For most other currencies, the funds are added to your reserve within three business days. If you fund your account in a currency different from your reserve currency, this will credit your payable instead of your reserve. This is done to offset any negative payable amounts in that particular currency. ### Make a transfer from another merchant account ##### Use an API to transfer balance Automate the process or build your own implementation with the [/balanceTransfers](https://docs.adyen.com/api-explorer/BalanceControl/latest/post/balanceTransfers) endpoint. You can transfer balance between two merchant accounts under the same company account and legal entity. For this to work, these two merchant accounts must have at least one common processing currency. This currency is used to transfer balance. You can transfer balances using the Customer Area or the Balance Control API. ### Tab: Customer Area To transfer balances using the [Customer Area](https://ca-test.adyen.com/), you need the following [user role](/account/user-roles): * **Merchant financial** To make a funds transfer from one merchant account to another, in your [Customer Area](https://ca-test.adyen.com/): 1. Switch to the merchant account which you want to transfer the balances *from*. 2. Go to **Finance** > **Balances overview**. 3. Select **Transfer balance**. 4. Select the currency and enter the amount that you want to transfer. 5. Select the destination account: the merchant account that you want to transfer the amount to. 6. Optional: Deselect **Reconfigure reserve if necessary**, if you do not want to change the configured [reserve threshold](#threshold) of the destination account. 7. Select **Move**. ### Tab: Balance Control API To make a funds transfer using the Balance Control API, you need the following [user role](/account/user-roles): * **Balance control API - Balances management** To transfer balance from one merchant account to another: 1. Make a POST `/balanceTransfer` request. In the request body, specify the following parameters: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `amount.value` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The amount of the balance transfer, in minor units. | | `amount.currency` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The currency of the balance transfer. | | `fromMerchant` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the source merchant account from which funds are deducted. | | `reference` | | Your reference for the balance transfer. **Format**: Maximum length: 80 characters. | | `toMerchant` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the destination merchant account to which funds are transferred. | | `type` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of balance transfer. Set this to **credit**. | The following example shows how to transfer funds from **MerchantAccount1** to **MerchantAccount2**. ```bash curl https://balance-control-test.adyen.com/balance-control/api/v2/balanceTransfers \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 3000 }, "reference": "Your reference for the balance transfer", "fromMerchant": "MerchantAccount1", "toMerchant": "MerchantAccount2", "type": "credit" }' ``` 2. Verify that you receive a response with HTTP status **200**, that includes the following parameters: | Parameter | Required | Description | | -------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `pspReference` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | A 16-character unique reference associated with the balance transfer. | | `createdAt` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The date and time at which the balance transfer was performed. | The following example shows the response that you receive after you send a successful request. ```bash { "pspReference": "993617895204576J", "createdAt": "2025-10-29T10:30:00.275+00:00" } ``` The transfer is initiated immediately, and the funds are deducted from the pending balance of the source merchant account. However, it can take up to one hour for the funds to become visible on the pending balance of the target merchant account. ## See also * [Monthly finance report](/reporting/monthly-and-daily-finance-report) * [Account structure](/account/account-structure) --- # Source: https://docs.adyen.com/account/define-account-structure.md Section: Account Title: Defining your account structure Description: Choose an account structure that works best for your business. --- title: "Defining your account structure" description: "Choose an account structure that works best for your business." url: "https://docs.adyen.com/account/define-account-structure" source_url: "https://docs.adyen.com/account/define-account-structure.md" canonical: "https://docs.adyen.com/account/define-account-structure" last_modified: "2019-09-05T12:13:00+02:00" language: "en" --- # Defining your account structure Choose an account structure that works best for your business. [View source](/account/define-account-structure.md) ##### See an example For an example of how a growing business adjusts its account structure, refer to [Example account structures](/account/define-account-structure/example). On this page, you'll learn about the most important factors to consider when defining your account structure. When defining your account structure, there are trade-offs to consider. Having fewer merchant accounts simplifies your operations and minimizes the number of reports you need for reconciliation. But having more merchant accounts allows for increased granularity in reporting, user permissions, and how you get paid. In general, we recommend that you have as few merchant accounts as possible, as long as you have enough to accommodate your business needs. If you need more help defining your account structure, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Legal entities You need at least one merchant account for each legal entity that you process payments with. You cannot link a single merchant account to two legal entities, for example one in the US and another one in France.   However, one legal entity can have multiple merchant accounts. For example, a legal entity in the US can have multiple US merchant accounts, for ecommerce or in-person payments.  ### Invoicing By default, you receive your [monthly invoice](/reporting/invoice-reconciliation/payment-processing-invoice) at the company account level. You will get separate invoices for each merchant account that is under a different legal entity than the company account. ### Acquiring Our merchants often open legal entities with us in regions where we offer local acquiring.  This may provide several benefits such as reduced interchange and scheme fees, increased authorisation rates, as well as faster settlement.   Your acquiring connections are configured at the merchant account level, and a single merchant account can be associated with only one acquiring region. For more information, refer to [Global payment processing](https://www.adyen.com/global-payment-processing). ## Getting paid Adyen pays out to you at the merchant account level. The more merchant accounts you have, the more payout batches you will receive.  Your merchant account must be associated with the legal entity that owns the bank account to which funds will ultimately be settled. If you are accepting payments in multiple currencies, you may link multiple bank accounts to a single merchant account.   Although you may have multiple bank accounts linked to your merchant account, you may only have one bank account per settlement currency. If you want to split funds from different countries/regions in the same currency, you need to create multiple merchant accounts. ## Reporting The reports used for reconciling bank settlements are generated at the merchant account level. You can choose to configure merchant accounts by individual business lines or geography, based on how you want to receive this information. Having fewer merchant accounts reduces the amount of reports required for financial reconciliation, which is especially important to consider if you reconcile manually. ## Risk management Risk rules for [RevenueProtect](/risk-management/configure-standard-risk-rules) and [Dynamic 3D Secure](/risk-management/dynamic-3d-secure) are configured at the company account level, with the option to overrule settings at the merchant account level. Risk rules at the merchant account level are useful if you want to establish a different risk profile based on business line or location. For example, physical goods and digital goods can have different risk factors, and risk considerations for transactions originating in the US can differ from those originating in the EU.  ## User permissions Users with access to the company account have access to all merchant accounts under that company account. To limit [user permissions](/account/user-roles), you need to create separate merchant accounts. You can [limit a user's permissions](/account/users#create) to either specific merchant accounts, or to an [account group](/account/account-structure#account-groups). ## In-person payments We recommend creating separate merchant accounts for ecommerce (online payments) and in-person payments (point of sale). Local legal entities are required for point-of-sale processing, so you need to create a separate merchant account for each region where you process POS payments. If you operate multiple physical stores in the same region, you can link these to one merchant account, using the `storeID` to identify the individual store location. Alternatively, you could create separate merchant accounts for different stores. This is required if you need to: * Receive separate payouts in the same currency or invoices for the different stores. * Limit user credentials to a particular store. For more information, refer to [Set up your Adyen account for in-person payments](/point-of-sale/design-your-integration/determine-account-structure). ## See also * [Account structure](/account/account-structure) * [Example account structures](/account/define-account-structure/example) * [Manage your account structure](/account/manage-account-structure) * [Framework entity onboarding](/account/define-account-structure/framework-onboarding) --- # Source: https://docs.adyen.com/account/define-account-structure/example.md Section: Account Title: Example account structures Description: Walk through an example of how a growing business makes adjustments to account structure. --- title: "Example account structures" description: "Walk through an example of how a growing business makes adjustments to account structure." url: "https://docs.adyen.com/account/define-account-structure/example" source_url: "https://docs.adyen.com/account/define-account-structure/example.md" canonical: "https://docs.adyen.com/account/define-account-structure/example" last_modified: "2019-09-05T12:13:00+02:00" language: "en" --- # Example account structures Walk through an example of how a growing business makes adjustments to account structure. [View source](/account/define-account-structure/example.md) ##### Defining your account structure For general guidelines on choosing your account structure, refer to [Defining your account structure](/account/define-account-structure). Let's assume you are a Dutch merchant with an online business selling tea to customers in the EU. Your legal entity is in the Netherlands, and you also have one physical store in Amsterdam. Below, we show the [simplest possible set up](#minimal) for your business, and how it can change as your business grows: when you launch a [new legal entity](#new-legal-entity), and decide to [manage certain regions separately](#regions). We also show how you can use account groups to more easily [manage a group of merchant accounts](#account-groups). ## Minimal account structure When you first sign up with Adyen, you get: * A company account **TeaShop** * A merchant account **TeaShop\_ECOM** for your online business. Because separate merchant accounts are needed for processing ecommerce and point-of-sale payments, you need to create another merchant account for your physical store, **TeaShop\_POS**. This is the simplest account structure that you could have.\ \ \ ![](/user/pages/docs/12.account/02.define-account-structure/02.example/pos-ecom.svg?decoding=auto\&fetchpriority=auto) You will receive separate reports and payouts for the two merchant accounts, while invoicing is done at the company level. ## New legal entity After some time, you decide to start shipping tea to customers in the US. To be able to make use of Adyen's local acquiring connections for reduced interchange and scheme fees, you launch a new legal entity in the US. Because you have a separate legal entity in the US, you now need to add a new merchant account for processing in the US. Let's call this new merchant account **TeaShop\_US\_ECOM**.\ \ \ ![](/user/pages/docs/12.account/02.define-account-structure/02.example/us-account.svg?decoding=auto\&fetchpriority=auto) You will receive separate reports and payouts for all your three merchant accounts. Because the legal entity linked to **TeaShop\_US\_ECOM** is different from the legal entity linked to your company account (your original legal entity in the Netherlands), you will receive separate invoices for the new merchant account in the US. The invoice for the merchant accounts **TeaShop\_ECOM** and **TeaShop\_POS** is generated at the company level as before. ## Managing regions separately Your business in the Netherlands and Germany has grown so much that you decide it is time to start managing these accounts separately. You hire separate support and financial teams for both locations. You also want to have different payout accounts for receiving funds from these locations. To be able to split funds, reporting, and user permissions, you need to create separate merchant accounts for Germany and the Netherlands—let's call these **TeaShop\_DE\_ECOM** and **TeaShop\_NL\_ECOM**.\ \ \ ![](/user/pages/docs/12.account/02.define-account-structure/02.example/eu-accounts.svg?decoding=auto\&fetchpriority=auto)\ \ \ You will keep the account **TeaShop\_ECOM** for any EU business outside of Germany and the Netherlands. You will receive separate reports and payouts for all your five merchant accounts. The new accounts **TeaShop\_DE\_ECOM** and **TeaShop\_NL\_ECOM** are linked to your legal entity in the Netherlands, and therefore you will receive a joint invoice for these (together with **TeaShop\_ECOM** and **TeaShop\_POS**) at the company level. ## Managing a group of merchant accounts Now that you have more merchant accounts, you might find it useful to [create account groups](/account/manage-account-structure#create-account-group). If you have team members who manage accounts across the EU, you could create an **Account group EU** containing all your accounts in the EU: **TeaShop\_DE\_ECOM**, **TeaShop\_NL\_ECOM**, **TeaShop\_ECOM**, and **TeaShop\_POS**. ![](/user/pages/docs/12.account/02.define-account-structure/02.example/account-group-eu.svg?decoding=auto\&fetchpriority=auto) This allows you to quickly give access to all merchant account in the EU. Users with access to the account group can furthermore search payments across all merchant accounts in the EU. ## See also * [Account structure](/account/account-structure) * [Defining your account structure](/account/define-account-structure) * [Manage your account structure](/account/manage-account-structure) --- # Source: https://docs.adyen.com/account/define-account-structure/framework-onboarding.md Section: Account Title: Framework entity onboarding Description: Learn how to onboard holding companies and their affiliates. --- title: "Framework entity onboarding" description: "Learn how to onboard holding companies and their affiliates." url: "https://docs.adyen.com/account/define-account-structure/framework-onboarding" source_url: "https://docs.adyen.com/account/define-account-structure/framework-onboarding.md" canonical: "https://docs.adyen.com/account/define-account-structure/framework-onboarding" last_modified: "2021-09-03T14:56:00+02:00" language: "en" --- # Framework entity onboarding Learn how to onboard holding companies and their affiliates. [View source](/account/define-account-structure/framework-onboarding.md) ##### Account structure For an example of how a growing business adjusts its account structure, refer to [Example account structures](/account/define-account-structure/example). Framework entity onboarding allows you to onboard multiple legal entities owned by one common holding entity. For example, your company may contain multiple businesses affiliated under one holding entity, referred to as **main contracting entity**. Generally, the holding entity does not act as a commercial player and does not process any payments. Instead, it offers administrative or legal benefits to its affiliates, referred to as **processing entities**. With framework entity onboarding, the main contracting entity is added as a company account and the processing entities are added as new merchant accounts. To learn more about the company account and the merchant account, refer to [Account structure](/account/account-structure). ![](/user/pages/docs/12.account/02.define-account-structure/03.framework-onboarding/company.svg?decoding=auto\&fetchpriority=auto) ## Complete onboarding applications To make use of framework entity onboarding, you need to: 1. [Get a test account](/get-started-with-adyen#test-account) and provide your Adyen sales contact with details about the legal structure of your business. 2. Log in to your [test Customer Area](https://ca-test.adyen.com/). 3. Under the **Application** section, select **Fill out application**. 4. Select **Start application** and fill out the **Main contracting entity** application. Provide information about: * Company * Ownership & control * Contacts Refer to [Application requirements](/get-started-with-adyen/application-requirements#page-introduction) for details. 5. Then, select **Start application** and fill out the **Processing entity** application. Provide information about: * Ecommerce or in-person payments * Company * Payout account * Ownership & control * Contacts Refer to [Application requirements](/get-started-with-adyen/application-requirements#page-introduction) for details. 6. Select **Send request** to submit your applications for review. After you send the request, you will see a message saying that Adyen will review the applications and contact you within the specified timeframe. Note that your account will only go live after the main contracting entity and the first processing entity applications have been submitted, and then approved by Adyen. --- # Source: https://docs.adyen.com/account/email-log-in.md Section: Account Title: Email login Description: Set up email login for your Adyen Customer Area. --- title: "Email login" description: "Set up email login for your Adyen Customer Area." url: "https://docs.adyen.com/account/email-log-in" source_url: "https://docs.adyen.com/account/email-log-in.md" canonical: "https://docs.adyen.com/account/email-log-in" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Email login Set up email login for your Adyen Customer Area. [View source](/account/email-log-in.md) For your existing [Customer Area](https://ca-test.adyen.com/), you can set up email login for all of your users. When you migrate a users to email login, they must log in using their email address. ## Requirements | Requirement | Description | | ---------------------------------------------- | --------------------------------------------------------------- | | **[Customer Area roles](/account/user-roles)** | Make sure that you have the following role:- **Merchant admin** | ## Manage migration for users You must migrate [test Customer Area](https://ca-test.adyen.com/) and [live Customer Area](https://ca-live.adyen.com/) users separately. If a user completes the migration process in the test Customer Area, it only allows them to use email login for the test Customer Area. 1. In your Customer Area, go to **Account** > **Users**. 2. Select **Manage user migration**. In the panel, you can do the following: * Download a report with the [migration statuses](#migration-statuses) of users. * Download a report with the [users that do not have a unique email address](#user-requirements). * [Start migration for users](#start-migration). * [Cancel migration for users](#cancel-migration). ### Migration statuses A user can have one of the following migration statuses: * **Requires review**:\ For users whose migration requires review, the migration status report shows the following values in the **Reason** column: * **EMAIL\_ADDRESS\_ALREADY\_IN\_USE**: the user's email address is being used by more than one account in the Customer Area. To migrate a user, their email address must be assigned to only one user. You must [change the duplicate email addresses](#change-duplicate-email-addresses) before migrating the user. If you do not know which company account the duplicate user belongs to, or if they belong to another organization, reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) with the user in the **CC** field. * **SELECTED\_MIGRATION\_UNAVAILABLE**: the user's email address is being used by a separate email user within the same organization (but not in the same company). Within the same organization, you cannot have an [SSO user](/account/single-sign-on/set-up-sso) and an email login user with the same email address. You must first change the email user's login method before proceeding with the current migration. * **Ready to migrate**:\ You can start migration for the user. * **Pending migration**:\ You started migration for the user, and they must complete the steps. ### Change duplicate email addresses To migrate a user to email login, their email address must be assigned to only one user, because it becomes their username. If you are migrating a user, but their email is being used by more than one account, you must change the email for this user. 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user whose email address you want to change. 3. On the user details page, select **Edit icon**. 4. Change the email address for the user. 5. Select **Save** to complete the process. We send a verification email to the user's new email address, and you can start migration for them. They verify their email address during the migration process. ## Start a migration You can start migration for an individual user or multiple users at the same time. ### Tab: Individual user To start migration for an individual user: 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user you want to migrate. If they are [eligible for migration](#manage-migration-for-users), the **Migration to email-based login is available** message shows. 3. Select **Start migration**. The user that you started migration for receives an email to complete the required steps for migration. ### Tab: Multiple users We recommend that you notify users that you started email migration for them, because we do not email your users when you start migrating multiple users. To start migration for multiple users: 1. In your Customer Area, go to **Account** > **Users**. 2. Select **Manage user migration**. 3. In the **Ready to migrate** box, select **Email** under login method, and then select **Start migration**. 4. Select **Start bulk migration**. The next time the user logs in to the Customer Area, they are prompted to complete the migration. The user needs to login with their previous credentials to complete the migration. The user cannot access the Customer Area until they complete the migration. When the user completes migration, we send them a confirmation email with their credentials. After this, the user cannot access the Customer Area with their previous credentials. You can verify that their new login method is updated to email on the **Users** page. ## Cancel a migration You can cancel a user's migration only if they have not completed the steps of the migration process. Reasons for canceling the process include the following: * The migration is not working, and you want the user to be able to access the Customer Area. Restarting a canceled migration is possible at any time, by [starting the migration](#start-migration) again. ### Tab: Cancel migration for an individual user 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user for whom you want to cancel the migration. 3. On the user details page, select **Cancel migration**. 4. Confirm your choice by selecting **Cancel migration**. We send an email to inform the user about the cancellation. ### Tab: Cancel migration for multiple users 1. In your Customer Area, go to **Account** > **Users**. 2. Select **Manage user migration**. 3. In the **Pending migration** box, select **Cancel migration**. 4. Select **Cancel migration**. You get a pop-up message that tells you if the migration was successfully canceled. If so, we recommend that you notify users that you canceled migration for them. If you have questions or feedback, get in touch with your Adyen contact. --- # Source: https://docs.adyen.com/account/getting-paid.md Section: Account Title: Getting paid Description: Find out how you get the money from the payments processed with Adyen. --- title: "Getting paid" description: "Find out how you get the money from the payments processed with Adyen." url: "https://docs.adyen.com/account/getting-paid" source_url: "https://docs.adyen.com/account/getting-paid.md" canonical: "https://docs.adyen.com/account/getting-paid" last_modified: "2020-11-10T11:31:00+01:00" language: "en" --- # Getting paid Find out how you get the money from the payments processed with Adyen. [View source](/account/getting-paid.md) The funds for all transactions that Adyen processes for you are sent to [your payout account](/account/manage-payout-account-details). Payouts are sent separately to each of your [merchant accounts](/account/account-structure#merchant-accounts). This means you have the option to [change how you get paid](#change-how-you-get-paid) for each of your merchant accounts. ## How payouts work The funds for the transactions Adyen processes for you are assigned to a payable batch based on your [payout model](#payout-model). The [Payable balance](/account/balances) has the most up-to-date information about the current payable batch. The payable batch closes according to the [payout frequency](#payout-frequency). If the Payable balance is positive when the payable batch closes, Adyen instructs the payout to you. The funds you get are [calculated on a net basis](#payout-batches-and-reporting). This means you get your sales from a given period, minus any costs over this period, for example refunds, chargebacks, or transaction costs. ## Payout currencies Adyen supports payouts in different currencies and offers like-for-like (no currency conversion) settlement if the currency is also supported as a settlement currency by the payment method. The currency in which we can settle your payout account depends on the country of the acquiring connection used to route transactions. See the [list of currencies supported in different countries/regions](/account/supported-currencies) for more information about configuring the currency of your payout account. ## Payout models Which transactions are assigned to a payable batch depends on your payout model: * [Sales day payout](/account/sales-day-payout): Get the funds from a whole sales day in a single payout batch, regardless of whether the card scheme or payment method transferred the funds to Adyen. The sales day closing time is [set in the Customer Area](#change-how-you-get-paid), but in some cases you can dynamically [set a different closing time every day](/reporting/dynamic-sales-day/). * [Pass-through payout](/account/pass-through-payout): Get the funds from one sales day in several payout batches, depending on when the card scheme or payment method transfers the funds to Adyen. Sales day payout is the default payout model. In Africa, Brazil, and Turkey, Pass-through payout is the only available payout model. ## Payout frequency How often Adyen pays out to you is determined by the payout frequency. You can [configure the payout frequency](#change-how-you-get-paid) for each of your merchant accounts. Depending on the currencies and banks involved, it may take up to two days for the payout funds to arrive in your account. ### Bank holidays On bank holidays, clearing for a specific currency may be closed and therefore Adyen cannot process payouts. Adyen also cannot receive funds. This impacts when you receive your payout. The exact impact depends on the [payout model](#payout-model) used. More details on the exact impact per payout model can be found on [Sales day payout](/account/sales-day-payout#bank-holidays) and [Pass-through payout](/account/pass-through-payout#bank-holidays). If you want to receive notifications on a weekly basis about your currencies' upcoming bank holidays, enable the **Balances notices** [Customer Area notification](/account/notification-center). For a list of bank holidays, download: * [Adyen observed bank holidays 2026](/account/getting-paid/Adyen_observed_bank_holidays_2026.xlsx) ## Payout batches and reporting With both payout models, Adyen pays you on a net basis. This means your payable batch is made up from your sales figure from which we deduct: * [Transaction costs](https://www.adyen.com/pricing) * [Refunds](/get-started-with-adyen/adyen-glossary/#refund-definition) * [Chargebacks](/get-started-with-adyen/adyen-glossary/#chargeback) * Other adjustments, for example balance transfers. When the payable batch closes, we create a [Settlement details report](/reporting/settlement-detail-report). This report contains information on the transactions that were credited or debited to your account, including the costs associated with these transactions. To get your settlement details report we recommend you [automatically generate and download reports](/reporting/automatically-get-reports). ### Check your payout You can view your payout details in your Customer Area. You must have one of the following [user roles](/account/user-roles): * Merchant admin * Merchant financial * Merchant view payouts * View payout schedule To check your payout: 1. Log in to your [Customer Area](https://ca-live.adyen.com/), and select the merchant account you want to check. 2. Go to **Finance** > **Sales to payouts**. 3. Select the **Payouts** tab . 4. Choose the date range you want to view.\ Bars appear, representing the payout amount for the selected date range. 5. Click on a bar to view more detailed information, such as sales and refund amounts, below the payout chart. To see how to check your payout, you can also watch a video here: Embedded video (Vimeo): ## Change how you get paid You can change how you get paid for each merchant account. This section is about making changes to the payout model and payout frequency. If you want to change the account where you receive the payouts, see [Manage your bank account details](/account/manage-payout-account-details). To manage payout options, you must have one of the following [user roles](/account/user-roles): * Change payout schedule * Merchant admin To change the payout options for a merchant account: 1. Log in to your [live Customer Area](https://ca-live.adyen.com/). 2. Go to **Finance** > **Payout model**.\ Here you see an overview of your merchant accounts and their payout configurations. 3. To make changes, select **Change** and follow the instructions. You can change your: * **Payout model** - Choose between [Sales day payout](/account/sales-day-payout) and [Pass-through payout](/account/pass-through-payout).\ For Sales day payout, you can also change the [payout delay](/account/sales-day-payout#payout-delay) and the [sales day closing time](/account/sales-day-payout#sales-day). * **Payout frequency** - How often you get paid by Adyen. 4. Accept the **Terms & conditions** and select **Submit**. ## See also * [Manage payout account details](/account/manage-payout-account-details) * [Sales day payout](/account/sales-day-payout) * [Dynamic sales day closing time](/reporting/dynamic-sales-day) * [Pass-through payout](/account/pass-through-payout) * [Settlement details report](/reporting/settlement-detail-report) * [Payable balance](/account/balances) --- # Source: https://docs.adyen.com/account/invoice-settings.md Section: Account Title: Configure your invoice settings Description: Manage the settings of your invoices from Adyen. --- title: "Configure your invoice settings" description: "Manage the settings of your invoices from Adyen." url: "https://docs.adyen.com/account/invoice-settings" source_url: "https://docs.adyen.com/account/invoice-settings.md" canonical: "https://docs.adyen.com/account/invoice-settings" last_modified: "2021-12-29T11:20:00+01:00" language: "en" --- # Configure your invoice settings Manage the settings of your invoices from Adyen. [View source](/account/invoice-settings.md) You get invoices for [payment processing](/reporting/invoice-reconciliation/payment-processing-invoice), [payment terminal orders](/point-of-sale/managing-terminals/order-terminals#sales-order-steps), and other services. You can either configure invoice settings [for one account](#configure-settings-for-one-account) or [for multiple accounts at once](#configure-settings-for-multiple-accounts). ## Configure settings for one account Go to the Invoice settings page: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and go to **Finance** > **Invoice overview**. 2. Select the **Invoice settings** button. To learn how to configure invoice settings, you can also watch a video here: Embedded video (Vimeo): To configure the settings for a [merchant account](/account/account-structure#merchant-accounts) instead of your [company account](/account/account-structure#company-account), you need to [switch to the merchant account](/account/manage-account-structure#switching-between-accounts).\ The Invoice settings page includes the following sections: ### Merchant invoicing You can see this section if you are in a merchant account. Switch the toggles for the invoice types you want to enable or disable. If the [legal entity](/account/define-account-structure#legal-entities) of your merchant account is different than that of your company account, you cannot disable these invoices. ### General These settings apply to all invoice types. | Field | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Invoice currency | Select the currency for the charges in your invoices. | | Decimal Separator | Select **Point (1,000.99)** or **Comma (1.000,99)**, depending on how you want numbers to appear in your invoices. | | Receive invoices via email | Select **Enabled** if you want invoices to be sent to your email at the end of each month. | | Alternative charged merchant accountOptional | You can see this if you are in a merchant account. To change the alternative account, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Charged merchant account | You can see this if you are in your company account. To change the merchant account, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Invoice address | The address on your invoices. To change the address, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | ### Invoice-specific settings These settings apply to the invoice type that matches the name of the section. For example, the settings apply to the Payment processing invoice, the section name is **Payment processing**. | Field | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Type of invoice payment | The method that you use to pay the charges in your invoice. To change the type, reach out to your Adyen contact. | | Email address for invoices | The email address where you want your invoice to be sent, if **Receive invoices via email** in General settings is enabled. | | Order numberOptional | This only applies to Payment processing invoices and Terminal services invoices. Enter a combination of numbers and letters that appears in your invoice. | ## Configure settings for multiple accounts You can configure settings for more than one account at once if you [switch to your company account](/account/manage-account-structure#switch-to-your-company-account). 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and go to **Finance** > **Invoice overview**. 2. Select the **Invoice settings** button. 3. Select **Batch edit** from the Invoice settings page. You can configure the following sections: ### Batch edit Select the invoice type you want to configure settings for. **General** is for all invoice types. ### Accounts Choose the accounts you want to configure invoice settings for: 1. Select filters you want for accounts that appear in the table below. 2. Select the settings icon **and choose the **Data density** and **Visible columns** you want in the table. 3. Select the checkbox next to the accounts you want to include. 4. Select the **Set** button. ### Setting 1. Select the edit icon **to configure the [general settings](#general) or [invoice-specific settings](#invoice-specific-settings) for the chosen invoice type. 2. Select the **Set** button. When you are done choosing accounts and configuring settings, select the **Apply changes** button. ## See also * [Account structure](/account/account-structure) * [Manage your account structure](/account/manage-account-structure) * [Payment processing invoice](/reporting/invoice-reconciliation/payment-processing-invoice) --- # Source: https://docs.adyen.com/account/manage-account-structure.md Section: Account Title: Manage your account structure Description: Request new merchant accounts, and create or edit account groups. --- title: "Manage your account structure" description: "Request new merchant accounts, and create or edit account groups." url: "https://docs.adyen.com/account/manage-account-structure" source_url: "https://docs.adyen.com/account/manage-account-structure.md" canonical: "https://docs.adyen.com/account/manage-account-structure" last_modified: "2024-02-27T16:12:00+01:00" language: "en" --- # Manage your account structure Request new merchant accounts, and create or edit account groups. [View source](/account/manage-account-structure.md) This page describes how to: * [Request a new merchant account](#request-merchant-account). * [Delete a merchant account](#delete-merchant-account) * [Create](#create-account-group) and [edit](#edit-account-group) account groups. * [Switch between company and merchant accounts](#switching-between-accounts) in your [Customer Area](https://ca-test.adyen.com/). ## Request a new merchant account To be able to request a new merchant account, you need to have the following [user roles](/account/user-roles) for your company account: * Merchant admin * Merchant additional merchant accounts To request a new merchant account: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). Make sure that you are on your company account. 2. Go to **Account** > **Merchant accounts**, and select **Request new merchant account**. 3. In the **Desired account code** box, enter the name for this merchant account, for example *TeaShop\_NL*. Changing the name of the merchant account later is only possible if you haven't processed any transactions through this merchant account. 4. In the **Channel** drop-down, select whether you are using this merchant account for processing ecommerce or point-of-sale transactions. 5. In the **Payment methods** section, select the payment methods for the new merchant account.\ You can [add more payment methods](/payment-methods/add-payment-methods) at any time. 6. Select **Submit**. ## Delete a merchant account If you no longer use a merchant account, you can request it to be closed. To be able to close a merchant account, you need to have the **Merchant admin** [user role](/account/user-roles). To close a merchant account: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Switch to the merchant account that you want to close. 3. Go to **Settings** > **Close account**. 4. In the **Requested inactivation date** drop-down, select the month starting from when the account should be closed. 5. In the **Reason Category** drop-down, select a reason for closing the account. 6. Select **Request Closure**. The account will become inactive on the first day of the month of your requested inactivation date. As of this date, you can no longer process transactions with this merchant account, and we will stop charging you for our services for this merchant account. After the account becomes inactive, you can still access the inactive merchant account for six months. The six months is counted from the last transaction date, not from the date when the account became inactive. The following examples show how the last transaction date affects how long you can still access the inactive account: * You select July as the **Requested inactivation date**. The last transaction date on the account was January 1. The account becomes inactive on July 1. You can still access the account until August 1. * You select July as the **Requested inactivation date**. The last transaction date on the account was June 30. The account becomes inactive on July 1. You can still access the account until December 1. This allows you to view and download reports, as well as defend chargebacks and process refunds if needed. After this time period, the merchant account becomes permanently closed, and you will no longer access it. ## Create an account group An [account group](/account/account-structure#account-groups) is a group of merchant accounts. Creating an account group allows you to: * Quickly give users access to several merchant accounts. * Search for payments across several merchant accounts. To be able to create new account groups, you need to have: * Manage Merchant Account Groups [user role](/account/user-roles) * Access to the company account To create a new account group: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Navigate to **Settings** > **Account groups**.\ This opens an overview of all your merchant accounts and existing account groups. 3. Select **Add group**. 4. Enter the name for the new group. 5. Select all merchant accounts that you want to add to the new group. 6. Select **Create a new group**. You can now [give users access to the new account group](/account/users#create). ## Edit an account group After you have created an account group, you can add more merchant accounts to the group, or remove merchant accounts from the group. To be able to add or remove merchant accounts, you need to have: * Manage Merchant Account Groups [user role](/account/user-roles) * Access to the company account To add or remove merchant accounts from an account group: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Navigate to **Settings** > **Account groups**.\ This opens an overview of all your merchant accounts and existing account groups. 3. Next to **Add group**, select **Edit**. 4. Select the merchant accounts that you'd like to add or remove. 5. In the lower-right corner, select the action you want to perform: * **Move to group** * **Remove from group** * **Create a group from selection** ## Switching between accounts When navigating in the [Customer Area](https://ca-test.adyen.com/), your view is either at the company level or merchant level. * **Company level**: you see information about all your merchant accounts. A page such as the payment list (under **Transactions** > **Payments**) shows you payments for all merchant accounts that you have access to. * **Merchant level**: you only see information about the currently selected merchant account. The payment list (under **Transactions** > **Payments**) only shows you payments for the currently selected merchant account. You can know whether you are on the company level or merchant level from the account switcher in the upper-left corner. ### Switch to a merchant account To switch to a merchant account, select the name of your company account in the upper-left corner of your [Customer Area](https://ca-test.adyen.com/). Then select the merchant account you want to switch to. ### Switch to your company account To switch to your company account, select the name of your merchant account in upper-left corner of your [Customer Area](https://ca-test.adyen.com/). Then select the name of your company account. ## See also * [Account structure](/account/account-structure) * [Define your account structure](/account/define-account-structure) --- # Source: https://docs.adyen.com/account/manage-account-structure/create-an-organization.md Section: Account Title: Create an organization Description: Give users access to multiple company accounts with one user login. --- title: "Create an organization" description: "Give users access to multiple company accounts with one user login." url: "https://docs.adyen.com/account/manage-account-structure/create-an-organization" source_url: "https://docs.adyen.com/account/manage-account-structure/create-an-organization.md" canonical: "https://docs.adyen.com/account/manage-account-structure/create-an-organization" last_modified: "2024-09-16T10:58:00+02:00" language: "en" --- # Create an organization Give users access to multiple company accounts with one user login. [View source](/account/manage-account-structure/create-an-organization.md) This feature requires additional configuration on our end. Reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), or your Adyen contact to set this up. An organization is a group of company accounts. If you have multiple company accounts and users that need access to more than one company account, you can add them to an organization. When you add a user to an organization, they keep their current [user roles for each company account](#user-roles). A user, with one login, can access multiple company accounts in the same organization in Customer Area. You can only add company accounts that are legally related to each other to an organization. To manage organizations in Customer Area, you must have the following role: * **Merchant admin** ## Add a company account to an organization You must add each company account to an organization individually. To add a company to an organization, do the following: 1. In your [Customer Area](https://ca-test.adyen.com/) company account that you want to add to an organization, go to **Settings** > **Account settings**. 2. Under **User management**, in the **Unified account login** box, select **Add your company** and follow the user interface (UI) instructions to complete the process. 3. After accepting the terms, you get a message to confirm if the company account was added to the organization. ## Copy SSO configuration from the organization The way an organization's SSO is configured is one of the following: * If the first company account added to the organization has SSO, the organization inherits that SSO configuration. * If the first company account added to the organization does not have SSO, the organization inherits the SSO configuration from any of the subsequent companies that has SSO configured. * If none of the company accounts added to the organization have SSO configured, the organization does not get SSO configuration until one of its company accounts sets it up. If you have SSO configured for the organization, you can copy that SSO configuration to the company account: 1. In your [Customer Area](https://ca-test.adyen.com/) company account that you want to add to an organization, go to **Settings** > **Account settings**. 2. Under **User management**, in the **Unified account login** box, select **Copy SSO configuration** and follow the UI instructions to complete the process. 3. After accepting the terms, you get a message to confirm if SSO was configured. ## Manage user migration to SSO If you have set up SSO, you can manage user migration to SSO: 1. In your [Customer Area](https://ca-test.adyen.com/) company account that you want to add to an organization, go to **Settings** > **Account settings**. 2. Under **User management**, in the **Unified account login** box, select **Manage user migration**. 3. On the **Users** page, follow instructions to [migrate users to SSO](/account/single-sign-on/migrate-users-to-sso). Alternatively, in your [Customer Area](https://ca-test.adyen.com/) company account, go to **Users** > **Settings** to [migrate users to SSO](/account/single-sign-on/migrate-users-to-sso). ## Give a user access to a company account in an organization By default, a user does not have access to all company accounts in an organization. If a user does not already have access to a company account in the organization, you can either: * [Create a user for the company with email login](#email-login) * [Create a user for the company with SSO login](#sso-login) For a user that has access to multiple company accounts in one organization, the following changes are reflected for the user under all company accounts: * Editing email address * Editing first or last name * Removing a [Multifactor authentication](/account/multifactor-authentication/) device * [Resetting password](/account/users/#password-reset-email) ### Create a user for the company with email login 1. In your [Customer Area](https://ca-test.adyen.com/) company account that you want to give the user access to, go to **Account** > **Users**. 2. Select **Create new user**. 3. Select the **Email and password** login method for the user. 4. Enter the user's email address, first name, and last name, and follow the UI instruction to complete the process. ### Create a user for the company with SSO login 1. In your [Customer Area](https://ca-test.adyen.com/) company account that you want to give the user access to, go to **Account** > **Users**. 2. Select **Create new user**. 3. Select the **SSO** login method for the user. 4. Enter the user's email address, first name, and last name, and follow the UI instruction to complete the process. ## User roles for each company account When a user joins an organization where they already have access to multiple company accounts, their [user roles](/account/user-roles/) for each company account stay the same. The following example describes a scenario when a user has access to two company accounts. > For Company A, User123 has the user role **Merchant admin**.\ > For Company B, User123 has the user role **Merchant report**. > > Company A and Company B are added to an organization. User123 is added to the organization. > > For Company A, User123 still has the user role **Merchant admin**.\ > For Company B, User123 still has the user role **Merchant report**. After being added to an organization the user still has the same user roles for each account. --- # Source: https://docs.adyen.com/account/manage-payments.md Section: Account Title: Manage payments Description: Learn how to look up and manage payments in your Customer Area. --- title: "Manage payments" description: "Learn how to look up and manage payments in your Customer Area." url: "https://docs.adyen.com/account/manage-payments" source_url: "https://docs.adyen.com/account/manage-payments.md" canonical: "https://docs.adyen.com/account/manage-payments" last_modified: "2023-05-02T15:59:00+02:00" language: "en" --- # Manage payments Learn how to look up and manage payments in your Customer Area. [View source](/account/manage-payments.md) If you need to refund, cancel, or capture a payment, you can do that either using our [APIs](/online-payments/modify-payments), or in your Adyen [Customer Area](https://ca-test.adyen.com/). On this page, we explain how you can: * [Look up detailed information](#look-up-payments) about payments processed through your Adyen account. * [Refund](#refund-a-payment), [cancel](#cancel-a-payment), and [capture](#capture-a-payment) payments in your [Customer Area](https://ca-test.adyen.com/). * Check why a payment was [refused](#refused-payment). ## Look up payments In the [Customer Area](https://ca-test.adyen.com/), you can look up information about all payments processed under your company account for different regions and currencies. To see a list of all payments: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**. For each payment, you can see the following information: * **PSP reference**: Adyen's unique 16-character reference for this payment. * **Merchant reference**: Your reference for this payment. * **Account**: The [merchant account](/account/account-structure) through which this payment was processed.\ To see only payments processed through a specific merchant account, [switch to that merchant account](/account/manage-account-structure#switching-between-accounts). * **Date**: The date of the payment. * **Amount**: The amount of the payment. * **Payment method**: The payment method used to process this payment. * **Status**: The current [status](/account/payments-lifecycle) of the payment. * **Risk score**: The risk score of the payment. This is useful to check if a payment is flagged as fraudulent and [refused](#refused-payment). To learn more about risk scores, see [Risk management](/risk-management). You can use the **Filter** bar at the top of the page to filter payments by **Date**, **Status**, **Amount**, **Currency**, and other properties. You can also use the search box to look for a specific PSP reference, Merchant reference, or payment amount. ### Payment details For more information about a payment, select the **PSP reference** of that payment in the payments list. This opens the **Payment details** page, where you can view details such as: * **Payment lifecycle**: The history of different [statuses](/account/payments-lifecycle) that the payment has gone through. * **Payment events**: You can find the Acquirer Reference Number (ARN) here, which can be used to [track a refund](https://help.adyen.com/knowledge/payments/payment-statuses/how-can-i-check-if-a-refund-has-been-received-by-the-shopper/). * **Processing**: Includes the [fraud score](https://help.adyen.com/knowledge/risk/fraud-score/how-does-the-fraud-score-work) assigned to the payment, whether [3D Secure](/online-payments/3d-secure) was applied, and whether a [liability shift](/online-payments/3d-secure-for-regulation-compliance#3dsecurechargebackliabilityshiftrules) occurred. * **Transaction cost**: Fees associated with the payment. The **Payment details** page also shows shopper details such as name, email, phone number, IP address, and billing or delivery address. By default, these fields are masked. To view unmasked shopper details, your user must have the **Merchant view PII** [user role](/account/user-roles). ## Refund a payment If you want to return the funds to your shopper (for example, if they returned an item), you need to refund the payment. To be able to refund payments, you must have the **Merchant manage payments** [user role](/account/user-roles). To refund a payment: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**, and select the **PSP reference** of the payment that you want to refund.\ This opens the **Payment details** page. 3. Select **Refund payment** in the upper right corner of the page. **Refund payment** is only available if the payment has been captured (if the status is **SentForSettle** or **Settled**). 4. Confirm the details of the refund: * **Amount**: The amount you want to refund. This must be either the same or, in case of a partial refund, less than the captured amount. * **Reference**: Your reference for the refund request. 5. Select the **Refund this payment** checkbox, then select the **Refund payment** button in the lower right corner of the page. ## Cancel a payment ##### Separate capture To learn if a payment method supports separate captures, see the [payment methods overview](/payment-methods). For payment methods that support separate [capture](/online-payments/capture), you must cancel the payment before it has been captured (for example, when an item is out of stock). Canceling the payment releases the funds back to the shopper. To cancel payments, you must have the **Merchant manage payments** [user role](/account/user-roles). To cancel a payment: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**, and select the **PSP reference** of the payment that you want to cancel.\ This opens the **Payment details** page. 3. Select **See all payment actions** in the upper right corner of the page, then **Cancel payment**. **Cancel payment** is only available if the payment has not yet been captured (if the status is **Authorised**). 4. Enter the confirmation code and select **Cancel payment** in the lower right corner of the page. ## Capture a payment For payment methods that support separate [captures](/online-payments/capture), you must capture the payment manually, (for example, when the goods have been shipped). Capturing the payment triggers the funds to be transferred from the customer to your account. To capture payments, you must have the **Merchant manage payments** [user role](/account/user-roles). To capture a payment: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**, and select the **PSP reference** of the payment that you want to capture.\ This opens the **Payment details** page. 3. Select **See all payment actions** in the upper right corner of the page, then **Capture payment**. **Capture payment** is only available if the payment has not yet been captured (if the status is **Authorised**). 4. Confirm the payment details: * **Amount**: The amount you want to capture. * **Reference**: Your reference for the capture request. 5. Select **Capture this payment** checkbox, the **Submit capture request**. ## Check why a payment was refused To find out more about why a payment was refused: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**, and select the **PSP reference** of the refused payment. This opens the **Payment details** page. 3. Check the reason for the refusal in the **Processing** > **Acquirer response** field. For a list of reasons for payment refusals, see [Refusal reasons](/development-resources/refusal-reasons).\ If the value in the **Acquirer response** field is **FRAUD**, you can find out more information within the Customer Area. Select the Fraud scoring number in the **Processing** section. You can then see the risk results page for the payment. Payments with a fraud score of 100 or more are automatically refused. If the **Acquirer response** field only shows **Refused**, ask your shopper to check with their bank to know why the payment was refused. ## Re-authorize a payment There can be cases when you need to re-authorize a payment. For example, if the payment was not captured in time and the authorization expired. If the wrong amount was refunded to a customer, you can also use re-authorize the payment to recover all or part of the funds. ### Risks of re-authorizing * We do not guarantee that you will receive the funds, because the re-authorized payment can still be refused by the issuer. Adyen has no control over this. * It is possible that the customer initiates a chargeback when they see a new charge on their account. We recommend that you reach out to the customer before you re-authorize the payment. * In the event of a chargeback, you will be liable for the chargeback amount. This is because you initiated the payment, not the customer. ### Why Adyen does not reauthorize on behalf of merchant Adyen does not proactively reauthorize transactions. This is because: * You can reauthorize a payment in different ways (for example, using a different card or paying with cash), and Adyen might not have full visibility on the latest status of the payment. * Adyen has no control over the success of reauthorization and has limited visibility on the latest status of the payment. We provide the reauthorization functionality so you can decide to re-authorize the payment yourself. ### How to re-authorize a payment You can re-authorize a payment if the most recent [journal type](/account/payments-lifecycle) is one of the following: * Cancelled * Expired * Refunded * RefundedBulk * RefundedExternally You can only re-authorize payments made using these payment methods: * Card: Mastercard, Visa, American Express, UnionPay, JCB, Diners, Discover, Carte Bancaire, Bancontact * SEPA Direct Debit To re-authorize payments, you must have the **Merchant re-authorise payments** [user role](/account/user-roles). To re-authorize a payment: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Transactions** > **Payments**, and select the **PSP reference** of the payment you want to re-authorize.\ This opens the **Payment details** page. 3. Select **See all payment actions**, then **Re-authorize payment**. If the Re-authorize payment option is not available, check that you have the required user role and that the payment is eligible to be re-authorized. 4. You can optionally fill in the fields below: * **Amount**—if the amount is different from the original transaction amount. * **Reference**: If you leave this blank the original reference for the transaction will be used. * **Capture delay (hours)**: The number of hours after which the payment will be captured. Set this to **0** to capture the payment immediately. If you leave this field blank, the [capture settings](/online-payments/capture) on your account determine when the payment is captured. 5. Select **Submit re-authorization**. ## See also * [Payments lifecycle](/account/payments-lifecycle) * [Payment methods](/payment-methods) * [FAQs: Refunds](https://help.adyen.com/knowledge/payments/refunds/) * [Adyen Academy](https://help.adyen.com/academy) --- # Source: https://docs.adyen.com/account/manage-payout-account-details.md Section: Account Title: Manage your bank account details Description: Manage the bank accounts where you want to receive the funds from Adyen. --- title: "Manage your bank account details" description: "Manage the bank accounts where you want to receive the funds from Adyen." url: "https://docs.adyen.com/account/manage-payout-account-details" source_url: "https://docs.adyen.com/account/manage-payout-account-details.md" canonical: "https://docs.adyen.com/account/manage-payout-account-details" last_modified: "2023-02-20T07:20:00+01:00" language: "en" --- # Manage your bank account details Manage the bank accounts where you want to receive the funds from Adyen. [View source](/account/manage-payout-account-details.md) Your payout account is where Adyen sends the funds from processed transactions. Adyen pays out at the merchant account level, so you need to configure your payout account details for each merchant account. If you are [accepting payments in multiple currencies](/account/supported-currencies), you may link multiple bank accounts to a single merchant account. ## Add your payout account To add your payout account details you must have this [user role](/account/user-roles): * Merchant manage bank accounts Use the tabs below to learn how to add your payout account in the live or test environment: ### Tab: Live 1. Log in to your [live Customer Area](https://ca-live.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**. 4. Select **Add payout account** > **Add new**. Select your bank account's country/region, [choose a supported payout currency](/account/supported-currencies), fill in the bank account details, and upload a bank statement for the account you are adding. 5. Select **Submit**. Our team reviews the payout account details within two business days and will email you the result. After your payout account is approved, you can copy the details from this merchant to one or several other merchant accounts under the same legal entity. ### Tab: Test Adding a payout account on test allows you to test the reconciliation process. 1. Log in to your [test Customer Area](https://ca-test.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**. 4. Select a currency, then select **Create test account**. 5. Select **Submit**. To test the reconciliation process, you also need to [enable automatic generation](/reporting/automatically-get-reports) of the [Settlement details report](/reporting/settlement-detail-report). Watch this video to see how to add a payout account: Embedded video (Vimeo): ## Copy payout account details If you have several merchant accounts under the same legal entity, you can copy approved payout details from one merchant account to another. Copying payout account details saves you from manually introducing the same details and makes sure the information is consistent between merchant accounts. To copy payout account details you must have this [user role](/account/user-roles): * Merchant manage bank accounts To copy payout account details to a merchant account: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**. 4. Select **Add payout account** > **Copy from**. You can only copy details from approved payout accounts. 5. Select the merchant that you want to copy the payout details from, and follow the steps. 6. Select **Submit** to finish copying the payout details.\ The change happens automatically and you do not need to wait for approval. ## Check payout account details To check your payout account details you must have one of these [user roles](/account/user-roles): * Merchant financial * Merchant admin To check your payout account details: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**.\ You get an overview of all payout accounts set up for the selected merchant account. ## Edit your payout account To edit your payout account details you must have this [user role](/account/user-roles): * Merchant manage bank accounts You cannot edit details for accounts pending approval. To edit your payout account details: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**. 4. In the list, find the account you want to edit and select the action button **(...)** > **Edit details**. 5. Make the changes and select **Submit**. The request is forwarded to our team for approval. Our team reviews the changes to your payout account details within two to three business days and will email you the result. ## Remove a payout account To remove a payout account you must have this [user role](/account/user-roles): * Merchant manage bank accounts To remove a payout account: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Switch to the merchant account. 3. Go to **Finance** > **Payout accounts**. 4. In the list, find the account you want to remove and select the action button **(...)** > **Close this account**. 5. Select **Yes, close** to remove the payout account. Removing a payout account doesn't need approval from Adyen. ## See also * [Supported payout currencies](/account/supported-currencies) --- # Source: https://docs.adyen.com/account/manage-your-balances.md Section: Account Title: Manage your balances Description: Manage the balances in your merchant accounts. --- title: "Manage your balances" description: "Manage the balances in your merchant accounts." url: "https://docs.adyen.com/account/manage-your-balances" source_url: "https://docs.adyen.com/account/manage-your-balances.md" canonical: "https://docs.adyen.com/account/manage-your-balances" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Manage your balances Manage the balances in your merchant accounts. [View source](/account/manage-your-balances.md) In your merchant account, you hold the following balances: * Pending balance * Refund reserve * Next payout amount * Deposit * Negative refund allowance The deposit and the negative refund allowance are fixed amounts determined by Adyen, but you can adjust all other balances in your merchant account in the following ways: * [Top up your account](#top-up-your-account) * [Transfer funds between accounts](#transfer-funds-between-accounts) * [Process payments](/account/manage-payments) * [Pay out funds to your bank account](/account/getting-paid) ## Fund allotment When you increase the available balance in your merchant account, the funds first go to your pending balance. After they are settled, these funds are allotted to the other balances held in that account. How these funds are allotted depends on whether you top up the account, or increase balances in another way (using a funds transfer, or by processing payments). ### Tab: Use top-ups You can [top up funds](#top-up-your-account) in your merchant account using the [Customer Area](https://ca-test.adyen.com/). When you do this, you can choose how to allot the funds to the balances held in that account. Choose between the following reasons: * **Funding my reserve balance**: The funds are booked to your refund reserve. If the adjustment causes the funds in the reserve to exceed the [reserve threshold](/account/balances-pilot/reserve#set-up-a-reserve), then we automatically increase the threshold. This ensures that the funds are not paid out with the next payout batch. * **Funding deposit held by Adyen**: The funds are booked to your [deposit](/account/balances-pilot/deposit). * **Offsetting a negative amount in my payable**: The funds are booked to your pending balance, and used to cover any negative balances caused by refunds and chargebacks. If you do not specify a **Reason** for the top-up, we allot the funds according to the following order of priority: 1. If the pending balance or the next payout amount is negative, the funds are booked to the pending balance. Once settled, they move to the next payout amount. 2. If the mandatory deposit requirements are not met, the funds are booked to the [deposit](/account/balances-pilot/deposit). 3. If the reserve balance is below the [threshold](/account/balances-pilot/reserve#set-up-a-reserve), the funds are booked to the refund reserve. 4. If none of the above apply, the funds are booked to the pending balance. Once settled, they move to the next payout amount. ![Top-ups flow diagram](/user/pages/docs/12.account/16.manage-your-balances/top-ups.svg?decoding=auto\&fetchpriority=auto) ### Tab: Use funds transfers / process payments When the balance in your merchant account increases due to processed payments or funds transfers, we allot the funds according to the following order of priority: 1. If the pending balance or the next payout amount is negative, the funds are booked to the pending balance. Once settled, they move to the next payout amount. 2. If the mandatory deposit requirements are not met, the funds are booked to the [deposit](/account/balances-pilot/deposit). 3. If the reserve balance is below the [threshold](/account/balances-pilot/reserve#set-up-a-reserve), the funds are booked to the refund reserve. 4. If none of the above apply, the funds are booked to the pending balance. Once settled, they move to the next payout amount. ![Balance transfers flow diagram](/user/pages/docs/12.account/16.manage-your-balances/balance_transfer_process_payments.svg?decoding=auto\&fetchpriority=auto) ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online](/online-payments) or [point-of-sale](/point-of-sale) integration with Adyen. | | **[API credential roles](/development-resources/api-credentials/roles/)** | To transfer funds using the API, make sure you have the credentials for Balance Control API with the following role:- **Balance control API - Balances management** | | **[Customer Area roles](/account/user-roles)** | To manage your reserve, top up your account, or transfer funds using the Customer Area, make sure that you have the following role:- **Merchant financial** | | **Setup steps** | Before you begin:- Make sure that you [check the balances held by your merchant account](/account/view-your-balances-pilot). | ## Top up your account The fastest way of transferring funds to your account is to generate a top-up payment. When we receive the top-up payment, we add the funds to your reserve, your deposit, or your pending balance, based on how you chose to [allot the funds](#fund-allotment). For payments made in **EUR** or **USD**, the funds are added to your account within two business days. For other currencies, this can take up to four business days. For some currencies, for example **ZAR**, you need to [use specific details](https://help.adyen.com/knowledge/payments/refunds/how-can-i-transfer-funds-into-my-adyen-account) for your bank transfer. To generate a top-up payment, you need the following [user role](/account/user-roles#finance): * **Merchant financial** To top up your merchant account using your [Customer Area](https://ca-test.adyen.com/): 1. Select the correct merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select **Top up**. 4. Select the **Reason** for your top-up payment. 5. Enter the amount that you want to add to the account. 6. Select **Top up with your bank account** or **Other top up methods**. 7. In the new window that opens, complete the payment. ## Transfer funds between accounts You can transfer funds between two merchant accounts under the same company account and [legal entity](/account/define-account-structure#legal-entities). For this to work, these two merchant accounts must have at least one common processing currency. This currency is used to transfer the funds. By transferring balances, you can adjust the balance of your reserve, your deposit, or pending amount. You can do this by using the Customer Area or the Balance Control API. ### Tab: Customer Area To transfer funds using the [Customer Area](https://ca-live.adyen.com/), you need the following [user role](/account/user-roles): * **Merchant financial** To transfer funds from one merchant account to another using the [Customer Area](https://ca-test.adyen.com/): 1. Select the merchant account from which you want to transfer the balances. 2. Go to **Finance** > **Balances overview**. 3. Select **Transfer balance**. 4. Select the currency and enter the amount you want to transfer. 5. Select the destination: the merchant account that you want to transfer the amount to. 6. Optional: Deselect **Reconfigure reserve if necessary**, if you do not want to change the configured [reserve threshold](/account/balances-pilot/reserve#threshold) of the destination account. 7. Select **Move**. ### Tab: Balance Control API To transfer funds using the Balance Control API, your [API credential](/development-resources/api-credentials) must have the following role: * **Balance control API - Balances management** To transfer funds from one merchant account to another: 1. Make a POST `/balanceTransfers` request. In the request body, specify the following parameters: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount.value` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The amount of the funds transfer, in minor units. | | `amount.currency` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The currency of the funds transfer. | | `fromMerchant` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the source merchant account from which funds are deducted. | | `reference` | | Your reference for the funds transfer. **Format**: Maximum length: 80 characters. | | `toMerchant` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the destination merchant account to which funds are transferred. | | `type` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of funds transfer. Possible values:- **credit**: Transfer a positive amount to a different merchant account. This means you are sending funds to that merchant account. - **debit**: Transfer a negative amount to a different merchant account. This means you are pulling fund from that merchant account. - **fee**: Transfer funds to cover fees that were charged to the destination merchant account. - **tax**: Transfer funds to cover taxes that were charged to the destination merchant account. - **adjustment**: Transfer funds to compensate for balance adjustments that were made on the destination merchant account. | Here is an example request to transfer funds from **MerchantAccount1** to **MerchantAccount2** **Make a funds transfer** ```bash curl https://balance-control-test.adyen.com/balance-control/api/v2/balanceTransfers \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 3000 }, "reference": "Your reference for the funds transfer", "fromMerchant": "MerchantAccount1", "toMerchant": "MerchantAccount2", "type": "credit" }' ``` 2. Pay attention to the response, which returns the following parameters: | Parameter | Required | Description | | -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `pspReference` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Adyen's 16-character string reference associated with the funds transfer. | | `createdAt` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The date and time at which the funds transfer was performed. | The following example shows the response that you receive when sending the request: ```bash { "pspReference": "993617895204576J", "createdAt": "2025-10-29T10:30:00.275+00:00" } ``` ## Keep track of balance changes To keep track of adjustments you make to the balances in your Adyen accounts, you can use the activity log in the [Customer Area](https://ca-test.adyen.com/). The activity log gives you a chronological view of all balance adjustments that took place in your merchant account. To view the activity log in your Customer Area: 1. Select the correct merchant account. 2. Go to **Finance** > **Balances overview**. 3. Select the **Activity log** tab. [![img.png](/user/pages/docs/12.account/16.manage-your-balances/example_activity_log.png)](/user/pages/docs/12.account/16.manage-your-balances/example_activity_log.png) ## Next steps [View your balances](/account/view-your-balances-pilot) [Stay updated about the balances in your company and merchant accounts.](/account/view-your-balances-pilot) --- # Source: https://docs.adyen.com/account/multifactor-authentication.md Section: Account Title: Multifactor authentication Description: Learn how to keep your account safe by setting up multifactor authentication. --- title: "Multifactor authentication" description: "Learn how to keep your account safe by setting up multifactor authentication." url: "https://docs.adyen.com/account/multifactor-authentication" source_url: "https://docs.adyen.com/account/multifactor-authentication.md" canonical: "https://docs.adyen.com/account/multifactor-authentication" last_modified: "2024-01-12T10:09:00+01:00" language: "en" --- # Multifactor authentication Learn how to keep your account safe by setting up multifactor authentication. [View source](/account/multifactor-authentication.md) All users with an Adyen Customer Area account must set up Multifactor Authentication (MFA) or [Single Sign-On](/account/single-sign-on/) in the [Customer Area](https://ca-test.adyen.com/). MFA keeps your account secure by requiring an additional form of verification in order to log in. This prevents unauthorized users from accessing your account, even if they have obtained your username and password. Each user can set up one authentication method per device and register two devices through MFA. If you have the **Merchant admin** role, you can: * See user details by going to **Account** > **Users**. * [Manage user access](#manage-devices) by removing devices registered to users in your organization. In your [Customer Area](https://ca-test.adyen.com/), you have two ways to set up MFA for your account: * With an [authenticator app](#authenticator-app), such as Google Authenticator, Okta Verify, or Microsoft Authenticator, which generates time-based one-time passwords on your mobile device. * With [SMS authentication](#sms-authentication), which sends SMS messages with time-based one-time passwords on your mobile device. ## Requirements Before you begin, take into account the following requirements and limitations. | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An integration with Adyen. | | **Limitations** | SMS authentication is only available in the live environment. | | **Hardware** | You must have a verification device: a mobile device that can either run an authenticator app or receive SMS messages. | ## Set up MFA with an authenticator app You must set up MFA on your device the first time you log in to your [Customer Area](https://ca-test.adyen.com/). 1. Enter a device name in the **Create device name** field. 2. Scan the QR barcode to create a new account in the authenticator app on your device. If you want to use a manual code to create a new account in your authenticator app, select **Switch to manual key** and enter the code Adyen provides. 3. Enter the 6-digit verification code from your authenticator app. 4. Select **Add** to register your device with Adyen. After you register your device for MFA with an authenticator app, each time you log in to your [Customer Area](https://ca-test.adyen.com/), you must enter the code from the authenticator app. ## Set up MFA with SMS SMS authentication is only available in the live environment. If you want to add SMS authentication to your [Customer Area](https://ca-test.adyen.com/) account: 1. Go to your user account menu. 2. Select **Profile** ![](/user/themes/adyen/images/illustrations/person.svg) . 3. Under **Multifactor authentication**, select **Add authentication**. 4. Select **Switch to SMS authentication**. 5. Enter your phone number. 6. Enter the 6-digit verification code that you receive on your mobile phone. 7. Select **Add**. After you register your device for MFA with SMS, each time you log in to your [Customer Area](https://ca-test.adyen.com/) account, you must enter the code we send to your device. ## Delete an authentication method To delete an existing authentication method from your account: 1. In your [Customer Area](https://ca-test.adyen.com/), go to your user account menu. 2. Select **Profile** ![](/user/themes/adyen/images/illustrations/person.svg) . 3. Under **Multifactor authentication**, select the delete icon **next to the authentication method you want to remove. 4. Select **Delete**. ## Manage devices If you have a new device, you can remove your registered device and add [MFA with an authenticator app](#authenticator-app) to that new device. To manage the devices used for MFA: 1. In your navigate to the details page of the user whose device you want to manage: **My user** for your own user, or the **User details** page of another user in your organization. 2. Under **Multifactor authentication**, select the delete icon **next to the device you want to remove. 3. Select **Delete**. The next time you log in to Adyen, you must register your new device. ## See also * [Manage users](/account/users) * [User roles](/account/user-roles) --- # Source: https://docs.adyen.com/account/notification-center.md Section: Account Title: Notification center Description: Stay informed of important events related to your Adyen account. --- title: "Notification center" description: "Stay informed of important events related to your Adyen account." url: "https://docs.adyen.com/account/notification-center" source_url: "https://docs.adyen.com/account/notification-center.md" canonical: "https://docs.adyen.com/account/notification-center" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Notification center Stay informed of important events related to your Adyen account. [View source](/account/notification-center.md) Adyen sends you notifications that contain alerts and notices about your accounts, [Adyen's systems](#service-status-messages), and more. In your [Customer Area](https://ca-test.adyen.com/), you can [configure how you receive notifications](#configure-notification-settings). ## Notification center The **Notification center** in your Customer Area appears when you select the **Notification center icon** **on the top navigation bar. The Notification center shows a list of notifications for all the merchant accounts that your [user account](/account/users/) has access to. Each notification includes a link for more details or a link that goes directly to the page in your Customer Area that it is about. When you have an unread notification, a red dot appears on the icon. When you click on the notification, it gets marked as read. The next time you open the Notification center, it no longer appears in the list. You can select **See all notifications** to go to a page that includes all the notifications we have sent you. If you want specific notifications to show up in the Notification center, you can choose them on the [Notifications settings page](#configure-notification-settings). ## Configure notification settings You can choose which notifications you get. 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Notification center** **> **Settings**. 2. Under each section, for each type of notification, select the corresponding toggles to enable or disable it for **Email** or **Notification center**. When the **Email** toggle is enabled, email notifications are sent to the email address linked to your user. ### Settings for chargeback notifications Fraud and dispute notifications are issued for merchant accounts. That means that if you enable **Chargeback notices**, you also need to select the merchant accounts that you want to receive chargeback notifications for. ## Service status messages Service status messages are notifications that give you important information about the status of Adyen's platform, for example scheduled maintenance or service downtime. In your user account, you can see system messages from all the [merchant accounts](/account/account-structure/#merchant-accounts) that you have access to. Each system message specifies the merchant account that it applies to. You can subscribe to [get these notifications by email](#configure-notification-settings) so you do not have to log in to the Customer Area to get these important updates. ## See also * [Manage users](/account/users) * [User roles](/account/user-roles) --- # Source: https://docs.adyen.com/account/pass-through-payout.md Section: Account Title: Pass-through payout Description: Find out how Pass-through payout works. --- title: "Pass-through payout" description: "Find out how Pass-through payout works." url: "https://docs.adyen.com/account/pass-through-payout" source_url: "https://docs.adyen.com/account/pass-through-payout.md" canonical: "https://docs.adyen.com/account/pass-through-payout" last_modified: "2020-11-10T11:36:00+01:00" language: "en" --- # Pass-through payout Find out how Pass-through payout works. [View source](/account/pass-through-payout.md) With Pass-through payout, the funds you get depend on the settlement timelines of the card schemes and payment methods you use. This means the funds from a sales day could be paid out to you in more than one batch. The Pass-through payout model: * Does not allow for reconciliation based on day totals. * Requires automated reconciliation because funds from a sales day are paid out over several days, as part of more than one payout batch. ## How it works Sales are assigned to the payable batch as soon as the schemes or payment methods send the funds to Adyen. The payable batch closes according to your [payout frequency](/account/getting-paid#payout-frequency), and Adyen pays out to you. For example, let's consider a merchant account on Pass-through payout with a daily payout frequency. The sales from Monday, January 1 are paid out in separate batches over the subsequent days, from January 2 to January 7. Each payout therefore contains funds from several sales days. ![](/user/pages/docs/12.account/19.pass-through-payout/pass-through-payout.svg?decoding=auto\&fetchpriority=auto) ### Adjustments Refunds, chargebacks, and other adjustments are added to the payable batch as they occur. For the most up-to-date information about the current payable batch, check your [Payable balance](/account/balances). ## Bank holidays Bank holidays impact when you receive your payout. If you are using the Pass-through payout model, the payout for a currency is delayed when a bank holiday falls on the capture day, the payout day, or in between the capture day and the payout day. With the Pass-through payout model, the funds you receive depend on the settlement timelines of the card schemes and payment methods you use. In case of a bank holiday, the settlement timelines are delayed by one or multiple days. For a list of bank holidays, refer to [Getting Paid](/account/getting-paid#bank-holidays). ## See also * [Manage payout account details](/account/manage-payout-account-details) * [Sales day payout](/account/sales-day-payout) * [Settlement details report](/reporting/settlement-detail-report) * [Payable balance](/account/balances) --- # Source: https://docs.adyen.com/account/payments-lifecycle.md Section: Account Title: Payments lifecycle Description: Learn about payment statuses and how you can track them. --- title: "Payments lifecycle" description: "Learn about payment statuses and how you can track them." url: "https://docs.adyen.com/account/payments-lifecycle" source_url: "https://docs.adyen.com/account/payments-lifecycle.md" canonical: "https://docs.adyen.com/account/payments-lifecycle" last_modified: "2025-09-18T13:20:00+02:00" language: "en" --- # Payments lifecycle Learn about payment statuses and how you can track them. [View source](/account/payments-lifecycle.md) When you make a payment request, the payment starts to go through the payments lifecycle and gets different payment statuses. A payment status gives information about what is happening with the funds for the payment. If the payment has a status that requires action, you must troubleshoot it to make sure that it gets a status with a final outcome. You can view payments, track their statuses, and take action on each payment through your Customer Area. ## Requirements Before you begin, you must meet the following requirements. | Requirement | Description | | ---------------------------------------------- | -------------------------------------------------------------- | | **Integration type** | Any payments integration with Adyen. | | **[Customer Area roles](/account/user-roles)** | Make sure that you have the following role:- **View Payments** | ## How it works A payment gets a status as soon as you make a payment request (for example, when a shopper submits a payment for their online order). You can view and track the payment status in your Customer Area. 1. As soon as the payment gets a status, we add it as an entry to your list of payments. It is identified by its PSP reference and your merchant reference for it. 2. When the payment gets a new status, we update the entry for it. 3. You can modify the payment while it is going through the different statuses of the payment lifecycle. ## View the status of a payment To view the status of a payment in your [Customer Area](https://ca-live.adyen.com/), do the following: 1. For payments, go to **Transactions** > **Payments**. For offers, go to **Transactions** > **Offers**. 2. From the list of payments, find the one you want to view. 3. In the **Status** column, you can see the status for the payment. 4. To view more information about the payment, select the **PSP reference** of the payment from the list. 5. Under **Payment lifecycle**, in the **Journal type** column, you can see each status the payment has had. ## Moving through the payments lifecycle As a payment moves through the lifecycle, it gets different payment statuses. ### Typical payment flows In typical cases, payments go through the following flows. ### Tab: Successful payment ![](/user/pages/reuse/payments/payment-lifecycle/Successful-payment.svg?decoding=auto\&fetchpriority=auto) ### Tab: Unsuccessful payment ![](/user/pages/reuse/payments/payment-lifecycle/Unsuccessful-payment.svg?decoding=auto\&fetchpriority=auto) The following payment statuses are categorized by different parts of the payments lifecycle. ## Offer statuses An offer is the initial part of the payments lifecycle after you send the payment request, before the shopper completes the payment, and the card issuer or payment method approves the transaction. For example: when you send a payment request for a payment method where you redirect the shopper to another website, the offer is created and gets an offer status. When the shopper completes the payment on the other website, the offer becomes a payment and gets a payment status. The following statuses are possible during the offer. *** ### Received The financial institution received the request to make the payment. The shopper must still complete their authorization. > **What happens next:** > > * When the shopper completes the authorization, the payment gets the **Authorised** status. ### Open The [offer](/get-started-with-adyen/payment-glossary#offer) is pending authorization. This applies to a payment where the authorization was asynchronous. For example, the shopper was redirected to the issuer, the payment went through [3D Secure 2 authentication](/online-payments/3d-secure/), or the payment method required a redirect. > **What happens next:** > > * When the shopper completes the authorization, the payment gets the **Authorised** status. ### OfferCancelled The payment was not successfully authorized by the shopper, so the [offer](/get-started-with-adyen/payment-glossary#offer) was canceled. This can also happen when the shopper does not complete the payment, for example, by dropping off. This applies to a payment where the authorization was asynchronous. For example, the shopper was redirected to the issuer, the payment went through 3D Secure 2 authentication, or the payment method required a redirect. > **We recommend that you:** > > * If the funds left the shopper’s account, ask the shopper to contact their issuing bank. > > **What happens next:** > > * This is a final status that cannot change. ## Authorization statuses After the shopper submits a payment request, authorization is the status given to a payment after successfully passing the process of verifying the payment details and performing risk checks. The funds for the payment are reserved. For card payments, we send a request to the corresponding [card network](/get-started-with-adyen/payment-glossary#card-networks-or-card-schemes) to authorize the payment from a [card issuer](/get-started-with-adyen/payment-glossary#issuer-or-issuing-bank) to an acquirer. For non-card payments, we send a request to the corresponding payment method or financial institution to authorize the payment to an acquirer. Authorization is valid for a period of time, when the funds can be [captured](/get-started-with-adyen/payment-glossary#capture-or-clearing-and-settlement) or [canceled](/get-started-with-adyen/payment-glossary#cancel-a-payment). If the funds are not captured during the validity period, it expires. The following statuses are possible during authorization. *** ### Authorised The shopper authorized the payment, and it was approved by the financial institution. > **We recommend that you:** > > * Wait for the payment to be [captured](/online-payments/capture/) before delivering goods or services. If you enabled [delayed automatic capture](/online-payments/capture/#delayed-automatic-capture), you can manually capture the funds. > > **What happens next:** > > * The payment gets captured automatically by default. ### AuthorisedPending The shopper's bank approved the payment, but the card and the payment terminal must confirm that the payment can be made. > **What happens next:** > > * If the payment is authorized, it gets the **Authorised** status. If you [cancel](/online-payments/cancel/) the payment, it gets the **Cancelled** status. ### Cancelled The payment was [cancelled](/online-payments/cancel/), which prevents funds from being transferred for the payment. > **We recommend that you** > > * If the funds for the payment are reserved in the shopper's account, ask the shopper to contact their bank to release the funds. > * Share the PSP reference, time stamps, and amount with the shopper, so that they can ask their bank to help locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### Refused The payment request was received but not approved. The request was rejected by the scheme or financial institution, or by us, if the risk level determined by our machine learning algorithm was rejected. > **We recommend that you:** > > * Check the [refusal reason](/development-resources/refusal-reasons) to understand why the payment was refused. > * Review that your [risk settings are configured](/risk-management/configure-risk-settings/) how you want. > * Ask the shopper to contact their issuing bank. > > **What happens next:** > > * This is a final status that cannot change. ### Error An error occurred while communicating with the financial institution, so the funds for the payment were not processed. > **We recommend that you:** > > * Ask the shopper to make the payment again. > * Verify with your technical team if the payment request was correct. > > **What happens next:** > > * This is a final status that cannot change. ### Retried An error occurred while communicating with the financial institution, so the funds for the payment were not processed. We have retried to authorize the payment. > **We recommend that you:** > > * Wait for a new authorization. > * If the retry fails, ask the shopper to make the payment again. > > **What happens next:** > > * If the authorization gets successfully retried, the payment gets the **Authorised** status. ### Expired The payment has expired, and it is no longer possible to capture it. A payment expires if it gets the **Authorised** status and does not get captured or cancelled after a period of time. This validity period depends on the payment method. For card payments, the validity period is usually 28 days. Some card schemes have [specific validity periods](/online-payments/adjust-authorisation/#validity). > **We recommend that you:** > > * Ask the shopper to make a new payment. For example, you can [send a payment link](/unified-commerce/pay-by-link/create-payment-links/). > > **What happens next:** > > * This is a final status that cannot change. ### HandledExternally This status is for cash payments that have been handled outside our platform. The payment has been registered for bookkeeping purposes only. In the Customer Area, this payment is shown as a transaction without a settlement. > **What happens next:** > > * This is a final status that cannot change. ### ReceivedIncrementalAuth The original [authorized amount was adjusted](/online-payments/adjust-authorisation/). > **What happens next:** > > * When the adjusted amount is processed, the payment gets the **Authorised** status and can be captured. ## Capture and settlement statuses A capture is when reserved funds for an [authorized payment](/get-started-with-adyen/payment-glossary#authorisation) are transferred to us. By default, we capture payments automatically after authorization. Some payment methods support separate authorization and capture. For these payment methods, you can configure capturing payments manually, capture delays, or partial captures. When a capture is processed, the net translation amount of the settlement will be paid out according to your [Sales day payout](/account/sales-day-payout/) schedule. The following statuses are possible during capture and settlement. *** ### SentForSettle The request to transfer funds has been sent to the financial institution, so this payment cannot be cancelled. We are waiting to receive the funds. > **We recommend that you:** > > * Wait up to 10 days after the capture was initiated. If the payment does not get the **Settled** status, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * When the payment is processed, it gets the **Settled** status. ### Settled The funds from the payment have been received by us. This does not mean that the funds have been paid out to you. It depends on your [payout model](/account/getting-paid/#payout-model). > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid out. > > **What happens next:** > > * This is a final status for successful payments. ### SettledBulk This status applies only to payments that we do [acquiring](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) for. The funds from the payment have been received by us. This does not mean that the funds have been paid out to you. It depends on your [payout model](/account/getting-paid/#payout-model). This status means the same thing as the **Settled** status. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid out. > > **What happens next:** > > * This is a final status for successful payments. ### SettleScheduled This status applies only to [Sales day payout](/account/sales-day-payout/) transactions. The payment has been successfully captured. The financial institution has captured the funds from the shopper, and the payment has been confirmed. The net transaction amount of the settlement will be paid out according to your Sales day payout schedule. This status means the same thing as the **SettledAcquirer** status. This status applies to [Sales day payout](/account/sales-day-payout/) transactions only and appears in reports as **Settled**. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid.out. > > **What happens next:** > > * This is a final status for successful payments. ### SettledExternally The payment has been settled with an external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank). We have received confirmation from the acquirer that the funds have been transferred to you. > **What happens next:** > > * This is a final status for successful payments. ### SettledExternallyWithInfo The payment has been settled with an external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank). We have received confirmation from the acquirer that the funds have been transferred to you. > **What happens next:** > > * This is a final status for successful payments. ### SettledInstallment This status applies only to installment payments. One installment of this payment has been settled. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid out. > > **What happens next:** > > * When all installments have settled this payment gets the **SettledInInstallments** status. ### SettledInInstallments This status applies only to installment payments. The full payment amount has been settled in installments. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid out. > > **What happens next:** > > * This is a final status for successful payments. Each installment has the **SettledInstallment** status. ### SettledInstallmentBulk This status applies only to installment payments. The payment has completed been settled in installments. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the settlement will be paid out. > > **What happens next:** > > * You will get the settlement in installments. Each installment has the **SettledInstallment** status. ### SettledReversed The payment has not been settled, because we have not received the funds 30 days after capture. > **We recommend that you:** > > * Wait up to 30 days. If the payment does not get captured again, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * If we receive the funds more than 30 days after capture, the payment gets the **Settled** status. ### CaptureFailed The attempt to [capture](/online-payments/capture/) the payment failed, and the shopper did not transfer funds to you. > **We recommend that you:** > > * Check the **CaptureFailureReason** in the **Transaction Events** to understand why it failed. > * Wait 10 days. If the payment does not get captured again, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * We are attempting to resolve the issue and capture the payment again. ### CapturedWithOtherAcquirer The payment was captured by a different [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) than the authorization. The transaction was processed in a new payment with the same merchant reference. > **What happens next:** > > * This is a final status that cannot change. ## Refund statuses A refund is when a shopper cancels the purchase of a product or service, after they have paid. When you make the refund, the funds are sent back from the [acquirer](/get-started-with-adyen/payment-glossary#acquirer-or-acquiring-bank) to the [issuer](/get-started-with-adyen/payment-glossary#issuer-or-issuing-bank). The following statuses are possible for refunds. *** ### SentForRefund The request to refund the payment has been sent to the financial institution. We are waiting to receive confirmation from the financial institution. > **We recommend that you:** > > * Wait up to 10 days after the refund was initiated. If the payment does not get the **Refunded** status, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * When the payment is processed, it gets the **Refunded** status. ### Refunded The funds were deducted from your account, and the financial institution intends to refund the funds to the shopper's account. It can take up to 40 days for the shopper's account to receive the funds, depending on the financial institution. > **We recommend that you:** > > * If the shopper does not receive the funds after 40 days, you can share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can share this with their financial institution, which can help the shopper attempt to locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedBulk This status applies only to payments that we do [acquiring](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) for. The funds were deducted from your account, and the financial institution intends to refund the funds to the shopper's account. It can take up to 40 days for the shoppers account to receive the funds, depending on the financial institution. > **We recommend that you:** > > * If the shopper does not receive the funds after 40 days, you can share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can share this with their financial institution, which can help them attempt to locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### RefundScheduled The payment has been successfully refunded to the shopper. The financial institution took the funds from your account and refunded the customer and the refund is confirmed. The net transaction amount of the refund will be debited on your behalf with a scheduled delay according to your [Sales day payout](/account/sales-day-payout/) schedule. This status means the same thing as the **RefundAcquirer** status. This status applies only to Sales day payout transactions and appears in reports as **Refunded**. > **We recommend that you:** > > * If the shopper does not receive the funds after 40 days, you can share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can share this with their financial institution, which can help the shopper attempt to locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedExternally The payment was refunded through an external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank), and we received confirmation from the acquirer. > **We recommend that you:** > > * If the shopper did not receive the funds, you should reach out to your acquiring partner for this payment. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedExternallyWithInfo The payment was refunded through an external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank), and we received confirmation from the acquirer. > **We recommend that you:** > > * If the shopper did not receive the funds, you should reach out to your acquiring partner for this payment. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedInstallment This status applies only to installment payments. A single installment payment was refunded. Each installment has the status **Refundedinstallment**. > **We recommend that you:** > > * If the shopper does not receive the funds after 40 days you can share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can share this with their financial institution, which can help the shopper attempt to locate the funds. > > **What happens next:** > > * When all installments are refunded, the payments gets the **Refundedininstallments** status. ### RefundedInInstallments This status applies only to [installment payments](/payment-methods/cards/credit-card-installments/). The payment has been fully refunded in installments. > **We recommend that you:** > > * Wait up to 40 days after the refund was initiated. If the shopper does not receive the funds, share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can ask their financial institution to attempt to locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedInstallmentBulk This status applies only to installment payments. The payment has been fully refunded in installments. > **We recommend that you:** > > * Wait up to 40 days after the refund was initiated. If the shopper does not receive the funds, share the refund letter or [Acquirer Reference Number (ARN)](/get-started-with-adyen/payment-glossary/#acquirer-reference-number) with the shopper. They can ask their financial institution to attempt to locate the funds. > > **What happens next:** > > * This is a final status that cannot change. ### RefundedReversed The refund was attempted, but the shopper did not receive the funds. We returned the funds to your account. A common reason is that the shopper's bank account is no longer valid. > **We recommend that you:** > > * Ask the shopper to contact their issuer or bank. > * Use another method, outside our platform, to transfer the funds to the shopper. > > **What happens next:** > > * This is a final status that cannot change. ### RefundFailed The refund failed, and the shopper did not receive the funds. The funds are still in your account. > **We recommend that you:** > > * Check the **RefundFailureReason** in **Transaction Events** to understand why it failed. > * Wait up to 10 days after the refund was initiated. If the payment has not been recaptured, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * We are attempting to resolve the issue and refund the payment again. If the payment is successfully refunded, the payment gets the **SentForRefund** status. ### RefundNotCleared The shopper received the funds. However, the refund was not settled, because the [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) did not process the refund 30 days after it was initiated. > **What happens next:** > > * If the refund is processed after 30 days, you will see an additional **Refunded** record. ### RefundAuthorised This status applies only to [unreferenced refunds](/online-payments/classic-integrations/modify-payments/refund/#unreferenced-refund). The refund has been recorded, but the refund request was not sent to the financial institution yet. You can still cancel the refund. > **What happens next:** > > * If you do not cancel the refund, the payment gets the **Refunded** status. ### RefundPending This status applies only to unreferenced refunds for in-person payments. The refund has been recorded, but the refund request was not sent to the financial institution yet. You can still cancel the refund. > **What happens next:** > > * If you do not cancel the refund, the payment gets the **Refunded** status. ### RefundScheduledUnconfirmed This status applies to [Sales day payout](/account/sales-day-payout/) transactions only. The institution will take the funds from your account to refund the customer. This is an intermediary step before the refund gets fully captured, and no funds have moved yet. > **What happens next:** > > * After the refund is processed, the payment gets the **RefundScheduled** status. ### UnconfirmedRefundFailed This status applies to [Sales day payout](/account/sales-day-payout/) transactions only. This status can only apply after a RefundScheduledUnconfirmed, in case the payment method did not confirm the refund or because of a technical error. > **We recommend that you:** > > * Initiate the refund again. > > **What happens next:** > > * We attempt to process the refund. If the refund is successful, the payment gets the **RefundScheduled** status. ### AcquirerRefundFailed This status applies to [Sales day payout](/account/sales-day-payout/) transactions only and appears in reports as **RefundFailed**. The acquirer has notified us that the funds for this transaction will not be paid out to us because the capture has failed. > **What happens next:** > > * The funds already paid out by us are reverted and credited to your account. ## Disputes and chargeback statuses A chargeback is a when a shopper submits a request to the [issuer](/get-started-with-adyen/payment-glossary#issuer-or-issuing-bank) to return funds paid to you. Typically, a chargeback occurs after you have refused to refund the shopper. When the chargeback process is initiated, you get a [dispute](/risk-management/understanding-disputes/) that you can accept or defend, and we withdraw the disputed funds from your Adyen account. The chargeback follows the [dispute flow](/risk-management/understanding-disputes/dispute-process-and-flow/). The following statuses are possible for chargebacks. *** ### Chargeback The shopper attempted to reverse the payment, and the issuer has started a [dispute process](/risk-management/understanding-disputes/dispute-process-and-flow).\ We withdraw the disputed funds from your account. > **We recommend that you:** > > * Go to the **Dispute details** page to supply defense documents or accept the chargeback. > > **What happens next:** > > * If you accept the chargeback, this is the final status. > * If your defense is successful, the payment gets the **ChargebackReversed** status. ### ChargebackExternally An external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) has recorded the transaction as a chargeback. The shopper attempted to reverse the payment, and the issuer has started a [dispute process](/risk-management/understanding-disputes/dispute-process-and-flow).\ We withdraw the disputed funds from your account. > **We recommend that you:** > > * Go to the **Dispute details** page to supply defense documents or accept the chargeback. > > **What happens next:** > > * If you accept the chargeback, this is the final status. > * If your defense is successful, the payment gets the **ChargebackReversedExternally** status. ### ChargebackExternallyWithInfo An external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) has recorded the transaction as a chargeback. The shopper attempted to reverse the payment, and the issuer has started a [dispute process](/risk-management/understanding-disputes/dispute-process-and-flow).\ We withdraw the disputed funds from your account. > **We recommend that you:** > > * Go to the **Dispute details** page to supply defense documents or accept the chargeback. > > **What happens next:** > > * If you accept the chargeback, this is the final status. > * If your defense is successful, the payment gets the **ChargebackReversedExternally** status. ### SecondChargeback The [defense](/risk-management/manage-disputes#defending-disputes) of the first chargeback was not successful. The shopper attempted to reverse the payment again. We have withdrawn or will withdraw the disputed funds from your account. > **What happens next:** > > * This is a final status that cannot change. ### ChargebackReversed We have transferred the disputed funds back to your account. You successfully [defended the dispute](/risk-management/manage-disputes#defending-disputes), or the shopper repaid the funds. > **What happens next:** > > * This is a final status for successful disputes. ### ChargebackReversedExternallyWithInfo An external [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) has recorded that the chargeback has was reversed. We have transferred the disputed funds back to your account. You successfully [defended the dispute](/risk-management/manage-disputes#defending-disputes), or the shopper repaid the funds. > **What happens next:** > > * This is a final status for successful disputes. ## Online payout statuses An [online payout](/online-payments/online-payouts/) is when you send funds from your account to another receiver (for example, a supplier or contractor). Your account can be set up for instant card payout or payouts in stages. The following statuses are possible for payouts. *** ### ReceivedPayout We received the [payout](/online-payments/online-payouts/) request. > **What happens next:** > > * When the payout is authorized, we send the funds for the payout. ### PayoutAuthorised The [payout](/online-payments/online-payouts/) is authorized, and funds will be sent to the receiver. > **What happens next:** > > * After it is processed, the payment gets the **SentForPayout** status, followed by the **PaidOut** status. ### RefusedPayout The [payout](/online-payments/online-payouts/) was refused. The request was rejected by the scheme, financial institution, or us, if the risk level determined by our machine learning algorithm was rejected. > **We recommend that you:** > > * Check the refusal reason to understand why the payment was refused. > * Review your risk settings. > * Ask the shopper to contact their issuing bank. > > **What happens next:** > > * This is a final status that cannot change. ### SentForPayout Funds have been sent to the receiver, but the [payout](/online-payments/online-payouts/) is not yet complete. We are waiting to receive confirmation from the financial institution. > **We recommend that you:** > > * Wait up to 10 days after the payout was initiated. If the payment does not get the **PaidOut** status, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * When the payout is processed, the payment gets the **PaidOut** status. ### PaidOut The [payout](/online-payments/online-payouts/) was completed. Funds have been transferred to the receiver. > **We recommend that you:** > > * Find the settlement batch number for each payment event to know when the payout has been deducted from your account. > > **What happens next:** > > * This is a final status that cannot change. ### PaidOutScheduled The [payout](/online-payments/online-payouts/) has been successfully processed and the funds have been sent to the receiver. The net transaction amount of the payout will be debited on your behalf with a scheduled delay according to your [Sales day payout](/account/sales-day-payout/) schedule. This status means the same thing as the **PaidOutAcquirer** status. This status applies to [Sales day payout](/account/sales-day-payout/) transactions only and appears in reports as **PaidOut**. > **What happens next:** > > * This is a final status that cannot change. ### PaidOutExternally The [payout](/online-payments/online-payouts/) was completed with an external acquirer. Funds have been transferred to the receiver. > **We recommend that you:** > > * If the receiver did not receive the funds, you should reach out to your acquiring partner for this payment. > > **What happens next:** > > * This is a final status that cannot change. ### PaidOutExternallyWithInfo The [payout](/online-payments/online-payouts/) was completed with an external acquirer. Funds have been transferred to the receiver. > **We recommend that you:** > > * If the receiver did not receive the funds, you should reach out to your acquiring partner for this payment. > > **What happens next:** > > * This is a final status that cannot change. ### PaidOutReversed This status applies to [Sales day payout](/account/sales-day-payout/) accounts. The [payout](/online-payments/online-payouts/) was reversed, because we did not receive the funds to be paid out or could not finish the payout process. > **We recommend that you:** > > * Verify with your technical team if the payment request was correct. > > **What happens next:** > > * This is a final status that cannot change. ### PayoutError An error occurred while communicating with the financial institution, so the [payout](/online-payments/online-payouts/) was not processed. > **We recommend that you:** > > * Verify with your technical team if the payment request was correct. > > **What happens next:** > > * This is a final status that cannot change. ### PayoutFailed We received your [payout](/online-payments/online-payouts/) request and made a payout request to the card scheme. The payout was not processed by the card scheme. > **We recommend that you:** > > * Check the **PayoutFailureReason** in **Transaction Events** to understand why it failed. > * Wait up to 10 days after the payout failed. If the payment does not get the **PaidOut** status, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). > > **What happens next:** > > * We are attempting to resolve the issue and payout again. If the payment is successfully refunded, the payment gets the **SentForPayout** status. ### AcquirerPayoutFailed This status applies to [Sales day payout](/account/sales-day-payout/) transactions only and appears in reports as **CaptureFailed**. The [acquirer](/get-started-with-adyen/payment-glossary/#acquirer-or-acquiring-bank) has notified us that the funds for this transaction will not be paid out to us because the capture has failed. > **What happens next:** > > * The funds already paid out by us are reverted and debited from your account. ## Stored value statuses [Stored value cards](/point-of-sale/gift-cards-terminal-api/) are payment cards with a monetary value that is stored on the card itself instead of in a bank account. Examples are gift cards, mall cards, meal vouchers, and other prepaid cards. You can make a request to [load funds to the balance](/point-of-sale/gift-cards-terminal-api/load-a-balance/#load-balance-request) of an activated stored value card. The following statuses are possible for requests to load funds to a stored value card. *** ### StoredValueLoadReceived We received the request to [load funds](/point-of-sale/gift-cards-terminal-api/load-a-balance/) to the gift card. > **What happens next:** > > * When it is processed, the payment gets the **StoredValueLoadAuthorised** status. ### StoredValueLoadReversed Funds were successfully [unloaded](https://docs.adyen.com/point-of-sale/gift-cards-terminal-api/void/) from the gift card. > **What happens next:** > > * This is a final status that cannot change. ### StoredValueLoaded Funds were successfully [loaded](/point-of-sale/gift-cards-terminal-api/load-a-balance/) to the gift card. > **What happens next:** > > * This is a final status that cannot change. ### StoredValueSentForLoad The request to [load funds](/point-of-sale/gift-cards-terminal-api/load-a-balance/) to the gift card was received. > **What happens next:** > > * Once processed, the payment will get the **StoredValueLoaded** status. ### StoredValueSentForLoadReversed The request to [unload funds](https://docs.adyen.com/point-of-sale/gift-cards-terminal-api/void/) from the gift card was received. > **What happens next:** > > * Once processed, the payment will get the **StoredValueLoadReversed** status. ## See also * [Manage payments](/account/manage-payments/) * [Reporting](/reporting/) --- # Source: https://docs.adyen.com/account/sales-day-payout.md Section: Account Title: Sales day payout Description: Find out how Sales day payout works. --- title: "Sales day payout" description: "Find out how Sales day payout works." url: "https://docs.adyen.com/account/sales-day-payout" source_url: "https://docs.adyen.com/account/sales-day-payout.md" canonical: "https://docs.adyen.com/account/sales-day-payout" last_modified: "2021-04-19T12:45:00+02:00" language: "en" --- # Sales day payout Find out how Sales day payout works. [View source](/account/sales-day-payout.md) With Sales day payout, the funds you get do not depend on the settlement timelines of the schemes and payment methods used by your shoppers. You get all the funds from a particular [sales day](#sales-day) in a single payout batch, with a fixed [payout delay](#payout-delay). The Sales day payout model provides: * Payouts and reports based on total sales from a single day. * Simplified reconciliation, because you can match a full day's payout with a full day's sales. * Predictable cash flows, because you know which sales are paid each day. Sales day payout is the default payout model. In Africa, Brazil, and Turkey, [Pass-through payout](/account/pass-through-payout) is the only available payout model. Watch this video to see how to use the sales day payout dashboard: Embedded video (Vimeo): ## How it works Sales processed through Adyen in a 24h period are assigned to a payable batch after the [payout delay](#payout-delay). The payable batch closes according to your [payout frequency](/account/getting-paid#payout-frequency), and Adyen pays out to you. For example, let's consider a merchant account on Sales day payout with a payout delay of two days, and a daily payout frequency. All the sales processed though that merchant account on Monday, January 1, are paid out two days later, on Wednesday, January 3. The default frequency for Sales day payout is daily, meaning each payout batch will contain all the sales from one day. You can [change your payout frequency](/account/getting-paid#change-how-you-get-paid) to monthly, for example. In this case, the payout will contain the funds from all the sales days added to the payout batch in the last month. ### Adjustments to your payout Refunds, chargebacks, and other adjustments are added to the payable batch as they occur and are not related to the sales day of the original transaction. If Adyen cannot capture the funds for a sales transaction that we already send you the money for, we will subtract those funds from the current payable batch. For the most up-to-date information about the current payable batch, check your [Next Payout](/account/balances) balance. ## Payout delay The payout delay is how long after the sale the corresponding funds get assigned to a payable batch. For example, with a payout delay of two business days, sales that happened on Monday get assigned to the payout batch on Wednesday. The following table shows an example payout schedule with a daily payout frequency and a payout delay of two days. | Sales day | Payout day | | --------- | --------------------- | | Monday | Wednesday | | Tuesday | Thursday | | Wednesday | Friday | | Thursday | Monday | | Friday | Tuesday the next week | | Saturday | Tuesday the next week | | Sunday | Tuesday the next week | However, the payout delay can increase due to [bank holidays](#bank-holidays). ### Payout delay calculation The payout delay is calculated to be the break-even point, where faster payment methods settle enough funds to make up for the funds not yet settled by the slower payment methods. The payout delay depends on the average settlement duration for the transactions in a merchant account. Your payout delay is influenced by: * Currencies you accept payments in. * Country/region where the transactions are acquired. For a typical mix of payment methods, your payout delay will be: | Payout delay | Situation | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2 business days | At least 80% of the transactions are in AUD, CAD, EUR, GBP, NZD, RON, SEK or USD and these transactions are acquired in the country or region of the applicable currency. | | 3 business days | Other Sales day payout merchant accounts. | | 3 , 7, or 12 business days | You've onboarded with Adyen through a partner connection. The exact payout delay depends on your industry. | Your payout delay is longer if your transactions mainly use schemes or payment methods that have long settlement delays. For example, American Express has a settlement delay of 7 days. If you process most payments through American Express, Adyen will set your payout delay to 7 business days. ## Decreasing your payout delay Adyen can decrease the payout delay for merchants based in the European Economic Area, Switzerland, Australia, New Zealand, Singapore and Hong Kong. To see what payout delay options are available to you, check your [Sales day payout configuration](/account/getting-paid#change-how-you-get-paid). ### Approval of accelerated sales day payout We will review your request for accelerated sales day payouts, and inform you of the outcome by email. If your request is refused, the reason can be one of the following: * **Unsupported currency**.\ Accelerated Sales day payout is not available if more than 20% of the transaction volume is processed in non-standard Sales day payout currencies, and/or transactions are acquired outside the country or region of the applicable currency. Funds will be made available with the default Sales day payout delay. Contact Adyen for a list of the current standard Sales day payout currencies, and to discuss what you can change to be eligible for faster payouts. * **Unsupported payment method mix**.\ Sales day payout is not available for payment methods that pay out numerous days later than the settlement day, or that settle in an unpredictable manner. Funds will be made available using Pass-through settlement: when the funds are received by Adyen. Contact Adyen for a list of the current standard Sales day payout currencies, and to discuss what you can change to be eligible for faster payouts. * **Requested in error**.\ We reject your request if we are informed (for example, by your Adyen Account Manager) that you requested the wrong delay or changed your mind. You can submit a new request for your preferred payout model and payout delay in your Customer Area. Refer to [configure your sales day](/account/getting-paid#change-how-you-get-paid). * **Other reasons**.\ Contact your Account Manager for more information. ## Defining your sales day By default, Adyen defines a sales day from midnight to midnight the next day, in the merchant account's local timezone. If your business requires it, you can [configure a different default sales day](/account/getting-paid#change-how-you-get-paid) to start and end at a different time. For example, a bar might want to set the closing time to 2:00 AM, so that all sales from 2:00 AM up until 1:59:59 AM the next day get settled as a whole, in one payout. Delayed closing times are possible up until 6:00 AM. In some cases you can also dynamically [set a different sales day closing time every day](/reporting/dynamic-sales-day/). ## Payable batch closing and report generation For Sales day payout, the payable batch always closes two hours after your [sales day closing time](/account/getting-paid#payout-frequency). For example, if you set the sales day closing time to midnight local time, Adyen will close the payable batch at 2:00 AM local time. After the payable batch closes we create a bank instruction to pay out to you. Additionally, if you configured to [generate reports automatically](/reporting/automatically-get-reports) we'll start generating your Settlement details report. ## Bank holidays Bank holidays impact when you receive your payout. If you are using the Sales day payout model, the payout delay for a currency increases when a bank holiday falls on the sales day, the payout day, or in between the sales day and the payout day. Here are some examples based on the payout delay of two business days: | Sales day | Bank holiday | Payout | | --------------------------- | --------------------- | --------- | | Monday | — | Wednesday | | Monday | Tuesday and Wednesday | Friday | | Thursday | Monday next week | Tuesday | | Friday, Saturday and Sunday | Monday | Wednesday | For a list of bank holidays, refer to [Getting Paid](/account/getting-paid#bank-holidays). ## See also * [Manage payout account details](/account/manage-payout-account-details) * [Dynamic sales day closing time](/reporting/dynamic-sales-day) * [Pass-Through payout](/account/pass-through-payout) * [Settlement details report](/reporting/settlement-detail-report) * [Payable Balance](/account/balances) --- # Source: https://docs.adyen.com/account/single-sign-on.md Section: Account Title: Single sign-on Description: Find out about single sign-on and how to set it up for your Adyen Customer Area. --- title: "Single sign-on" description: "Find out about single sign-on and how to set it up for your Adyen Customer Area." url: "https://docs.adyen.com/account/single-sign-on" source_url: "https://docs.adyen.com/account/single-sign-on.md" canonical: "https://docs.adyen.com/account/single-sign-on" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Single sign-on Find out about single sign-on and how to set it up for your Adyen Customer Area. [View source](/account/single-sign-on.md) Single sign-on (SSO) lets you use the same set of credentials to securely access several other services, like your work email or your Adyen Customer Area. The Customer Area supports SSO based on the [Security Assertion Markup Language (SAML) 2.0 protocol](https://en.wikipedia.org/wiki/SAML_2.0). SSO solutions that use the SAML 2.0 protocol include Okta, Azure, and Microsoft AD FS. The benefits of using SSO are: * **Improved security**: Controlled user access to the Customer Area. For example, when an employee leaves, their Customer Area access is removed through the SSO solution. * **Better user experience**: Employees use a single set of credentials to log in to the services they need to use. We support: * Authentication using SSO. * [Creating users](/account/single-sign-on/set-up-sso#create-users-sso) who log in using SSO. * [Migrating existing users](/account/single-sign-on/migrate-users-to-sso) to SSO. * [Exchanging service provider information using metadata URL](/account/single-sign-on/set-up-sso#configure-service-provider-in-customer-area). ## How it works Users log in to your identity provider with their SSO credentials. The identity provider then authenticates them and gives them access to the services it is connected to. ![](/user/pages/docs/12.account/07.single-sign-on/how-sso-works.svg?decoding=auto\&fetchpriority=auto) ## Next steps [**Set up SSO**\ Add the Customer Area to your identity provider.](/account/single-sign-on/set-up-sso) [**Migrate users to SSO**\ Allow existing users to log in using SSO.](/account/single-sign-on/migrate-users-to-sso) [**Logging in using SSO**\ How users switch to logging in using SSO.](/account/single-sign-on/log-in-with-sso) --- # Source: https://docs.adyen.com/account/single-sign-on/log-in-with-sso.md Section: Account Title: Log in with single sign-on Description: Learn how to verify your email address to log in to Customer Area using single sign-on (SSO). --- title: "Log in with single sign-on" description: "Learn how to verify your email address to log in to Customer Area using single sign-on (SSO)." url: "https://docs.adyen.com/account/single-sign-on/log-in-with-sso" source_url: "https://docs.adyen.com/account/single-sign-on/log-in-with-sso.md" canonical: "https://docs.adyen.com/account/single-sign-on/log-in-with-sso" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Log in with single sign-on Learn how to verify your email address to log in to Customer Area using single sign-on (SSO). [View source](/account/single-sign-on/log-in-with-sso.md) Single sign-on (SSO) lets you use the same set of credentials to securely access several other services. You use these credentials to log in to your identity provider, which then allows you to access your Customer Area.\ The identity provider is software like Okta, Azure, or Microsoft AD FS. ## Verify your email address When your administrator adds you as a user for the Customer Area, you'll get an automated email asking you to verify your email address. You need to do this procedure separately for your test Customer Area and for your live Customer Area. To verify your email address: 1. On the automated email you received, select **Verify email address**. * If the link expires, you'll need to contact your administrator to request a new link to verify your email address. 2. You are directed to a page with the confirmation message **Email successfully verified**. 3. You can optionally enter your first and last name into the corresponding input fields. Select **Save**. To log in after you verify: 1. In the **Username** field, enter the email address you verified. 2. Select **Next**. * If you are already logged in to your identity provider, you are redirected to your Customer Area. * If you are not logged in your identity provider account, you are redirected to your identity provider to log in. After you log in, you are redirected to your Customer Area. All set! From now on, you must access Customer Area using SSO. You can access Customer Area either [from the log in page](#login-credentials) or by [logging in through your identity provider](#from-identity-provider). ## Log in from Customer Area After verifying your email address, you log in to the Customer Area using your identity provider credentials. Keep in mind that you need to verify your email address separately for the test and live Customer Area. 1. Go to the Customer Area. 2. In the **Username** field, enter the email address you verified. 3. Select **Next**. * If you are already logged in to your identity provider, you are redirected to your Customer Area. * If you are not logged in your identity provider account, you are redirected to your identity provider to log in. After you log in, you are redirected to your Customer Area. ## Log in from your identity provider When you log in to your identity provider and choose to access your Adyen Customer Area, you are redirected there. --- # Source: https://docs.adyen.com/account/single-sign-on/migrate-users-to-sso.md Section: Account Title: Migrating users to single sign-on Description: Allow your existing users access to the Customer Area using single sign-on (SSO). --- title: "Migrating users to single sign-on" description: "Allow your existing users access to the Customer Area using single sign-on (SSO)." url: "https://docs.adyen.com/account/single-sign-on/migrate-users-to-sso" source_url: "https://docs.adyen.com/account/single-sign-on/migrate-users-to-sso.md" canonical: "https://docs.adyen.com/account/single-sign-on/migrate-users-to-sso" last_modified: "2023-07-13T11:07:00+02:00" language: "en" --- # Migrating users to single sign-on Allow your existing users access to the Customer Area using single sign-on (SSO). [View source](/account/single-sign-on/migrate-users-to-sso.md) If you have [set up SSO for your Customer Area](/account/single-sign-on/set-up-sso), you can migrate these users to SSO. After migration, they must use SSO to log in to the Customer Area. Adyen does not require you to migrate your users to SSO. You can decide to migrate some or all of your users. You must migrate [test Customer Area](https://ca-test.adyen.com/) and [live Customer Area](https://ca-live.adyen.com/) users separately. If a user completes the migration process in the test Customer Area, it only allows them to use SSO for the test Customer Area. If a user uses the same email address for multiple company accounts, then they can access only one company account after migrating to SSO. To access multiple company accounts, the user must do one of the following: * Use a different email address for each company account before migrating to SSO. * Use a username, account, and password to login, instead of migrating to SSO. ## Requirements Before you can migrate your users, do the following: * [Set up SSO for your Customer Area company account](/account/single-sign-on/set-up-sso). * Make sure that you have one of the following [roles](/account/user-roles): * **Merchant admin** * **Merchant user management** ## Manage migration for users 1. In your Customer Area, go to the **Manage user migration panel**. 2. Go to **Account** > **Users**. 3. Select **Manage user migration**. In the panel, you can do the following: * Download a report with the [migration statuses](#migration-statuses) of users. * Download a report with the [users that do not have a unique email address](#user-requirements). * [Start migration for users](#start-migration). * [Cancel migration for users](#cancel-migration). ### Migration statuses A user can have one of the following migration statuses: * **Requires review**:\ For users whose migration requires review, the migration status report shows the following values in the **Reason** column: * **EMAIL\_ADDRESS\_ALREADY\_IN\_USE**: the user's email address is being used by more than one account in the Customer Area. To migrate a user to SSO, their email address must be assigned to only one user. You must [change the duplicate email addresses](#change-duplicate-email-addresses) before migrating the user. If you do not know which company account the duplicate user belongs to, or if they belong to another organization, reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) with the user in the CC field. * **SELECTED\_MIGRATION\_UNAVAILABLE**: the user's email address is being used by a separate email user within the same organization (but not in the same company). Within the same organization, you cannot have an SSO user and email user with the same email address. You must first change the email user's login method before proceeding with the current migration. * **Ready to migrate**:\ You can start migration for the user. * **Pending migration**:\ You started migration for the user, and they must complete the steps. ### Change duplicate email addresses To migrate a user to SSO, their email address must be assigned to only one user, because it becomes their username. If you are migrating a user, but their email is being used by more than one account, you must change the email for this user. 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user whose email address you want to change. 3. On the user details page, select **Edit icon**. 4. Change the email address for the user. 5. Select **Save** to complete the process. We send a verification email to the user's new email address, and you can start migration for them. They verify their email address during the migration process. ## Start a migration A user can log in to the Customer Area with one of the following methods: * Username. * Email address. The process of migration depends on how a user logs in. ### Tab: Username You can [migrate individual users](#individual) or [migrate multiple users at a time](#multiple). ### Migrate an individual user 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user you want to migrate. 3. Select **Start migration**. The user receives an email to complete the required steps for migration. The next time the user logs in to the Customer Area, they are prompted to complete the migration. The user needs to login with their **previous credentials** to complete the migration. The user cannot access the Customer Area until they complete the migration. When the user completes migration, we send them a confirmation email with their new SSO credentials. After this, the user cannot access the Customer Area with their previous credentials. You can verify that their new login method is updated to SSO on the **Users** page. ### Migrate multiple users at a time We recommend that you notify users that you started SSO migration for them, because we do email your users when you start migrating multiple users. 1. In your Customer Area, go to **Account** > **Users**. 2. Select **Manage user migration**. 3. In the **Ready to migrate** box, select **SSO** under login method, and then select **Start migration**. 4. Select **Start bulk migration**. You get a pop-up message that tells you if the migration was successfully started. The next time the user logs in to the Customer Area, they are prompted to complete the migration. The user needs to login with their **previous credentials** to complete the migration. The user cannot access the Customer Area until they complete the migration. When the user completes migration, we send them a confirmation email with their new SSO credentials. After this, the user cannot access the Customer Area with their previous credentials. You can verify that their new login method is updated to SSO on the **Users** page. ### Tab: Email address Some users log in with their email address and password. You can migrate a user that logs in with their email address by doing the following: 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user you want to migrate. 3. Under **User details**, enter the **First name** and **Last name**. 4. Under **Login method**, select **SSO via \[YOUR\_COMPANY\_ACCOUNT\_NAME]**. 5. Select **Save**. The user receives an email to complete the required steps for migration. The next time the user logs in to the Customer Area, they are prompted to complete the migration. The user needs to login with their **previous credentials** to complete the migration. The user cannot access the Customer Area until they complete the migration. When the user completes migration, we send them a confirmation email with their new SSO credentials. After this, the user cannot access the Customer Area with their previous credentials. You can change the user's login method from SSO back to email at any time. 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user you want to migrate. 3. Under **Login method**, select **Email**. ## Cancel a migration You can cancel a user's migration only if they have not completed the steps of the migration process. Reasons for canceling the process include the following: * Your identity provider is not working and making it impossible for your user to be migrated to SSO. * The migration is not working, and you want the user to be able to access the Customer Area. Restarting a canceled migration is possible at any time, by [starting the migration](#start-migration) again. ### Tab: Cancel migration for an individual user 1. In your Customer Area, go to **Account** > **Users**. 2. In the user list, select the user for whom you want to cancel the migration. 3. On the user details page, select **Cancel migration**. 4. Confirm your choice by selecting **Cancel migration**. We send an email to inform the user about the cancellation. ### Tab: Cancel migration for multiple users 1. In your Customer Area go to **Account** > **Users**. 2. Select **Manage user migration**. 3. In the **Pending migration** box, select **Cancel migration**. 4. Select **Cancel migration**. You get a pop-up message that tells you if the migration was successfully canceled. If so, we recommend that you notify users that you canceled SSO migration for them. If you have questions or feedback, get in touch with your Adyen contact. --- # Source: https://docs.adyen.com/account/single-sign-on/set-up-sso.md Section: Account Title: Set up single sign-on Description: Learn how to set up single sign-on (SSO) to log in to the Customer Area. --- title: "Set up single sign-on" description: "Learn how to set up single sign-on (SSO) to log in to the Customer Area." url: "https://docs.adyen.com/account/single-sign-on/set-up-sso" source_url: "https://docs.adyen.com/account/single-sign-on/set-up-sso.md" canonical: "https://docs.adyen.com/account/single-sign-on/set-up-sso" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Set up single sign-on Learn how to set up single sign-on (SSO) to log in to the Customer Area. [View source](/account/single-sign-on/set-up-sso.md) Single sign-on (SSO) lets you use the same set of credentials to securely access several other services, like email service or your Customer Area. The Customer Area supports SSO based on the [Security Assertion Markup Language (SAML) 2.0 protocol](https://en.wikipedia.org/wiki/SAML_2.0). SSO solutions that use the SAML 2.0 protocol include identity providers like Okta, Azure, and Microsoft AD FS. ## Before you start To set up SSO for the Customer Area you need: * An SSO solution that supports the SAML 2.0 protocol. * A Customer Area [company account](/account/account-structure#company-account). You cannot set up SSO with a [merchant account](/account/account-structure#merchant-accounts). * A user with one of the following [roles](/account/user-roles): **Merchant admin** or **Merchant user management** * Accept the legal notice about SSO. This must be done by someone authorized to represent your organization. Recommended: * Keep at least one admin user that doesn't log in using SSO so that you can troubleshoot issues. ## Add the Customer Area to your identity provider Get the following information from your service provider: | Adyen field name | Okta | AD FS | Azure | Google | | ---------------- | ----------------------------------------- | ------------------------------ | ------------------------------------ | ----------- | | **SSO URL** | Single sign-on URL | Assertion Consumer Service URL | Reply URL (AssertionConsumerService) | Sign-on URL | | **Entity ID** | Audience URI | Identifier | Identifier (Entity ID) | Entity ID | | **Name ID** | Name ID format (Must be an email address) | IssuanceTransformRules | Unique User Identifier | - | | **Response** | Response | MessageAndAssertion | Response | Response | The metadata file needs to be permanently hosted on a cloud service that is publicly accessible on your end and use it as the Sign-on URL. ### Step 1: Get the Customer Area metadata URL First, do the following in your [test Customer Area](https://ca-test.adyen.com/). Then, repeat it in your [live Customer Area](https://ca-live.adyen.com/). 1. Go to **Settings** > **Single sign-on** and select **Start configuration**. 2. Under **Service provider configuration**, find either the **SSO URL** or **AssertionConsumerService**. Select **Copy URL**.\ You need this URL to configure your identity provider. ### Step 2: Configure your identity provider For Google as your identity provider: the metadata file needs to be permanently hosted on a cloud service that is publicly accessible on your end and use it as the Sign-on URL.\ Make sure that the metadata file is not encrypted. In your identity provider's interface, do the following: 1. Add the URL you copied from the **Service provider configuration** in the Customer Area. 2. Enable SAML2 request signing. 3. Enable SAML2 response signing. 4. In the **SubjectNameID** field, enter an email address. For example, **test\@company.com**.\ If Azure is your identity provider, you must enable the response and assertion (**Sign SAML response and assertion**) signing option in the Azure user interface. 5. Get your identity provider's metadata URL. This is required to configure the service provider in your Customer Area. ### Step 3: Configure the service provider in the Customer Area 1. In your Customer Area, go to **Settings** > **Single sign-on**. 2. Under **Identity provider configuration**, in the **Metadata URL** field, enter your identity provider's metadata URL. You can [change the metadata URL later](#change-the-metadata-url) if you need to.\ If Azure is your identity provider, enter **App federation Metadata Url** in the input field. 3. Select **Fetch configuration**. 4. Check that the fetched details are correct. 5. Select **Save configuration**. After doing this, you can start testing SSO. Your existing users do not automatically have SSO enabled, so you must: * [Create users](#create-users-sso) who log in to the Customer Area using SSO. * [Migrate existing users](/account/single-sign-on/migrate-users-to-sso) to SSO. If you experience issues with your SSO configuration for Customer Area, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Change the metadata URL 1. In your Customer Area, go to **Settings** > **Single sign-on**. 2. Under **Identity provider configuration**, select edit icon **for **Metadata URL**. 3. Select **Fetch new configuration**. 4. After fetching the metadata URL, select **Save configuration**. ## Create users who log in to the Customer Area using SSO The person who you create the user for must already have an account with the identity provider your organization uses. You can create the user either in your Customer Area or by making a Management API request. ### Tab: Customer Area ### In your Customer Area You must have one of the following roles: * Merchant admin * Merchant user management To create new users to login through your identity provider: 1. Log in to your Customer Area. 2. Go to **Account** > **Users**. 3. On the right top of the page, select **Create new user**. 4. For **User details**: * Select the **SSO** option as the login method. * Enter a unique email, a first name, and a last name for the new user. The email address will be the user's username. 5. Select **Continue**. 6. For **Accounts**, you can choose whether this user will have access to all associated merchants accounts or specific groups and accounts. 7. Select **Continue**. 8. For **Roles**, you can only assign roles that your own user already has. For a list of all possible roles, see [user roles](/account/user-roles). 9. Select **Continue**. 10. In the **Summary** page you can check and edit the details, accounts, and roles you assigned to the new user. 11. Select **Create new user**. ### Tab: Management API request ### Make a Management API request The Management API endpoint you use depends on the type of SSO user: * For one with access to a [company account](/account/account-structure#company-account), make a **POST** [/companies/{companyId}/users](https://docs.adyen.com/api-explorer/Management/latest/post/companies/\(companyId\)/users) request. * For one with access to a [merchant account](/account/account-structure#merchant-accounts), make a **POST** [/merchants/{merchantId}/users](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/\(merchantId\)/users) request. Both requests include: | Field | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The user's first and last name. | | `loginMethod` | **SSO** | | `email` | The user's email address. | | `username` | The user's email address that will be their username. This must be the same as the one in the `email` field. | | `timeZoneCode` | The [tz database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of the time zone of the user. For example, Europe/Amsterdam. | | `roles` | The [user roles](/account/user-roles) to assign to this user. You can only assign the ones that your own user already has. | | `accountGroups` | The list of [account groups](/account/account-structure#account-groups) associated with this user. | | `associatedMerchantAccounts` | The list of [merchant accounts](/account/account-structure#merchant-accounts) this user can log in to. | **API request to create a company account user** ```bash curl https://management-test.adyen.com/v3/companies/{companyId}/users \ -H 'x-API-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "name": { "firstName": "FIRST_NAME", "lastName": "LAST_NAME" }, "loginMethod": "SSO", "email": "EMAIL_ADDRESS", "username": "EMAIL_ADDRESS", "timeZoneCode": "Europe/Amsterdam", "roles": [], "accountGroups": [], "associatedMerchantAccounts": [] }' ``` You get a response with the HTTP **200** response code if the user was created. If there's an error, check the [error message](/development-resources/response-handling#error-response-fields) in the response. The new user receives an email with a link to verify their email address for their Customer Area account. If you have questions or feedback, get in touch with your Adyen contact. --- # Source: https://docs.adyen.com/account/supported-currencies.md Section: Account Title: Supported payout currencies Description: Learn what payout currencies Adyen supports in different countries/regions. --- title: "Supported payout currencies" description: "Learn what payout currencies Adyen supports in different countries/regions." url: "https://docs.adyen.com/account/supported-currencies" source_url: "https://docs.adyen.com/account/supported-currencies.md" canonical: "https://docs.adyen.com/account/supported-currencies" last_modified: "2023-02-22T17:25:00+01:00" language: "en" --- # Supported payout currencies Learn what payout currencies Adyen supports in different countries/regions. [View source](/account/supported-currencies.md) For each Adyen acquiring connection, learn which payment methods we acquire, which currencies we settle in, and how we pay out to your bank account. ### How funds reach your bank account Every transaction you process with Adyen goes through three steps: 1. **Acquiring**: Adyen processes the payment through one of our acquiring entities, for example Adyen Singapore. This includes global card schemes such as Visa or Mastercard, and any regional or alternative payment methods enabled on your account. 2. **Settlement**: The funds settle into an Adyen bank account in the settlement currency. The settlement currency depends on the acquiring region and payment method. The location of that bank account depends on both the currency and the acquiring entity, and determines which payment rails we can use to pay you out. 3. **Payout**: Adyen sends the balance to your bank account. You can receive payouts in two ways: * **Local payout**: We send funds through the currency's local payment rails, for example, SEPA in the eurozone or Faster Payments in the UK. Local payouts are faster and avoid SWIFT fees. You need a local bank account in a country that uses that specific currency as the legal tender. * **Cross-border payout**: We send funds through [SWIFT](https://en.wikipedia.org/wiki/SWIFT). Your bank may charge incoming fees, and the transfer can take longer. ### What this means for your payout setup When choosing your settlement currency and payout bank account: * If your bank account is located in a country or region that officially uses that currency (for example, a EUR account in the Eurozone), you receive local payouts. This is the fastest option with the lowest costs. * If your bank account is located outside a country or region that officially uses that currency (for example, an AUD account at a Singaporean bank), payouts are delivered via SWIFT. * Certain currencies can only be paid out to a local bank account within a country or region where that currency is the official legal tender: BRL, INR, MYR, MXN, and AED. SWIFT payouts are not supported for these currencies. You can configure multiple payout currencies for each merchant account. [Add a payout account](/account/manage-payout-account-details#add) for each payout currency. If you have a multi-currency bank account, you can use the same bank details for multiple payout accounts. If your country or region is not listed in the following tables, refer to the country or region of the acquiring connection used to route your transactions. [APAC](#apac) | [Europe](#europe) | [North America](#north-america) | [South America](#south-america) | [Middle East](#middle-east) ## APAC ### Australia (AU) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NZD | New Zealand | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Hong Kong (HK) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AUD | United States | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CAD | United States | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CHF | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HKD | Hong Kong | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | JPY | Japan | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NZD | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SGD | Singapore | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### India (IN) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- | | INR | India | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ### Japan (JP) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | JPY | Japan | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Malaysia (MY) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- | | MYR | Malaysia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ### New Zealand (NZ) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | NZD | New Zealand | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Singapore (SG) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CNY | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HKD | Hong Kong | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | JPY | Japan | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NZD | New Zealand | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SGD | Singapore | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | THB | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Europe ### European Union (EU) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AED | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CAD | Canada | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CHF | Switzerland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CNY | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CZK | Czech Republic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | DKK | Denmark | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HKD | Hong Kong | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HUF | Hungary | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ILS | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ISK | Iceland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | JPY | Japan | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | KWD | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | MXN | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NOK | Norway | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NZD | New Zealand | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | PLN | Poland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | RON | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SEK | Sweden | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SGD | Singapore | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | THB | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | TRY | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ZAR | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### United Kingdom (UK) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AED | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CAD | Canada | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CHF | Switzerland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CZK | Czech Republic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | DKK | Denmark | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HKD | Hong Kong | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HUF | Hungary | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ILS | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | JPY | Japan | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | MXN | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NOK | Norway | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | NZD | New Zealand | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | PLN | Poland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | RON | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SEK | Sweden | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SGD | Singapore | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | THB | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | TRY | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ZAR | Netherlands | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## North America ### Canada (CA) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | CAD | Canada | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### United States (US) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AUD | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | CAD | Canada | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | EUR | Eurozone | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | United Kingdom | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | HKD | Hong Kong | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | JPY | Japan | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## South America ### Brazil (BR) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- | | BRL | Brazil | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ### Mexico (MX) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | MXN | Mexico | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | USD | United States | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Middle East ### United Arab Emirates (UAE) | Settlement currency | Where Adyen holds the funds | Local payout | Cross-border payout | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AED | UAE | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | EUR | UAE | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | GBP | UAE | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | SAR | UAE | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USD | UAE | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## See also * [Manage payout account details](/account/manage-payout-account-details) * [Currency codes](/development-resources/currency-codes) --- # Source: https://docs.adyen.com/account/transaction-description.md Section: Account Title: Transaction description Description: Find out what shoppers see on their bank statement and how you can change it. --- title: "Transaction description" description: "Find out what shoppers see on their bank statement and how you can change it." url: "https://docs.adyen.com/account/transaction-description" source_url: "https://docs.adyen.com/account/transaction-description.md" canonical: "https://docs.adyen.com/account/transaction-description" last_modified: "2024-01-17T16:57:00+01:00" language: "en" --- # Transaction description Find out what shoppers see on their bank statement and how you can change it. [View source](/account/transaction-description.md) When shoppers check their bank statements, they need to be able to easily identify the charges they see. The text that describes charges is known as a *transaction  description*, *statement descriptor*, *shopper statement*, or *billing descriptor*. If shoppers do not recognize a transaction by its description: * There is a higher chance your shopper issues a chargeback. * You can get a fine from the relevant card scheme related to your chargeback rate. To prevent these issues, ensure that your transaction description contains your brand or the (chain) merchant name that is most recognizable to the cardholder (as required by the card schemes), and optionally customize your transaction description. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Any payments integration with Adyen. | | **[API credential roles](/development-resources/api-credentials/roles/)** | To customize transaction descriptions using the Management API, make sure that you have the following role:- **Management API — Payment methods read and write** | | **[Customer Area roles](/account/user-roles)** | To customize transaction descriptions using the Customer Area, make sure that you have one of the following roles:- **Merchant admin** - **Change payment methods** | | **Limitations** | Take into account the following:- You can only customize your transaction description in the live environment. - If you want to define [multiple different descriptions](#multiple-in-ca) by uploading a CSV file, note that the maximum file size is 10 MB. - Not all payment methods allow customization of the transaction description. See the [supported payment methods](#payment-methods). | ## Without customization Without customization, the transaction description consists of the **Name** set in your [live Customer Area](https://ca-live.adyen.com/) under **Settings** > **Account**, combined with the **City** and the **Country/Region** from your merchant account address. The city and country/region are always added to transaction descriptions, even if you customize the description. ## Customization options To help your shoppers easily identify the payments made to your business, you can customize the transaction description by adding information. You can add either of the following: * A [Doing Business As (DBA) name](#dba): a static value that represents your business. * A [dynamic value](#dynamic-values): the transaction-specific shopper statement that is specified in the payment request. * A [combination](#combination) of your DBA name followed by the shopper statement from the payment request. If you do business in Japan, we highly recommend that you [add localized shopper statements in Japanese characters](#japanese-characters). ### Doing Business As (DBA) name Your DBA name is a static value that represents your business. To add your DBA name to your transaction descriptions, you need to turn on this setting, and specify the text to use. We recommend that you set your DBA name to the name by which your shoppers know your business. ### Dynamic values Using dynamic values, you can customize the transaction description for each of your shoppers. For example, you can add the order reference number corresponding to the payment. To add a dynamic, transaction-specific shopper statement to your transaction descriptions, you need to turn on this setting, and [specify a shopper statement](#shopper-statement) in each individual payment request. Be aware of the following: * If you do not turn on dynamic values, the shopper statement from the payment request will *not* appear in your shoppers' bank statements. * If you turn on dynamic values but do not send a shopper statement in the payment request, your DBA name will be used instead. ### Combination To add both your DBA name and a transaction-specific shopper statement to your transaction descriptions, you need to turn on this setting, specify a DBA name, and [specify a shopper statement](#shopper-statement) in each payment request. With this setting, your DBA name is used as a base for the transaction description. The shopper statement defined in the payment request is appended to this description. ## Customer Area or Management API To add information to the transaction description, you can use the live Customer Area or the live Management API. * Using the **live Customer Area**, you have two options: * You can define the *same transaction description* for an individual merchant account or store or for multiple accounts or stores in one go. * Or you can upload a CSV file to define *various different transaction descriptions* for multiple merchant accounts and stores. In both cases the customized transaction description is applied to transactions made using **all the payment methods** that support customization and that have been added to the merchant account or store. * Using a **live Management API** endpoint, you can customize the transaction description **per payment method**. In this way you can use different descriptions for different payment methods. Not all payment methods that are available through the Management API support customization. A payment method-specific customization overrules the general transaction description settings from the Customer Area. ## Check the transaction description In your live Customer Area you can check the transaction description that applies to your merchant account or store. Using the live Management API you can check the transaction description that applies to specific payment methods. ### Tab: Customer Area When using your Customer Area to find out how your business appears on your shoppers' bank statements, you need to have one of the following [roles](/account/user-roles): * **Merchant admin** * **Change payment methods** To check the transaction description for a merchant account or store: 1. Log in to your [live Customer Area](https://ca-live.adyen.com/). 2. Go to the merchant account or store that you want to check the transaction description for. 3. Go to **Settings** > **Transaction description**. 4. Under **Show on bank statements**, check the settings: | Selected setting | Transaction descriptions include | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **A dynamic value** | The shopper statement from the payment request. Or, if the payment request does not contain a shopper statement, the DBA name shown in the box. | | **A static business name** | The DBA name shown in the box. | | **Static name and dynamic value** | A combination of the DBA name shown in the box, followed by the shopper statement from the payment request (if present). | These settings apply to [most card payments and some other payment methods](#payment-methods). ### Tab: Management API To check your transaction descriptions using the Management API, you need to have one of the following [roles](/account/user-roles): * **Management API — Payment methods read and write** * **Management API — Payment methods read** To find out how your business appears on your shopper's bank statements: 1. Make a GET [/merchants/{merchantId}/paymentMethodSettings](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/paymentMethodSettings) request to the live endpoint. 2. In the response, find the relevant payment method and inspect the `transactionDescription` object of that payment method. * `doingBusinessAsName`: the DBA name defined for this payment method. * `type`: determines what information is added to the transaction description. The possible values are: * **fixed**: the `doingBusinessAsName` value. * **dynamic**: the shopper statement from the payment request, or the `doingBusinessAsName` value if the payment request does not contain a shopper statement. * **append**: a combination of the `doingBusinessAsName` value, followed by the shopper statement from the payment request (if present). ## Customize the transaction description When you configure the transaction description, take into account that the description can be a maximum of **22 characters** including spaces for the DBA name, dynamic value, or combination. Anything exceeding that is truncated and left out. What remains is then sent along with the city and country/region. Allowed characters: * Lowercase and uppercase characters: `[a-z]` `[A-Z]` * Numbers: `[0-9]` * Special characters: `.`, `,`, `'`, `_`, `-`, `?`, `+`, `*`, and space. ### Tab: Customer Area When you change the transaction description in the [live Customer Area](https://ca-live.adyen.com/), the changes affect only your current payment methods. If you add a new payment method, its transaction description defaults to your DBA name. We recommend you reconfigure your transaction description after adding a new payment method to ensure your transaction description is consistent across all payment methods. There are two methods to change the transaction description in your live Customer Area: * Define a [single transaction description](#single-in-ca) and select one or more merchant accounts or stores to apply the description to. In this way you can apply the same description to many accounts or stores in one go. * Upload a CSV file with [various transaction descriptions](#multiple-in-ca) for various merchant accounts and stores. In this way you can supply all the different descriptions for all your merchant accounts and stores in one go. The maximum file size of the CSV file is 10 MB. For these tasks, you need to have one of the following [roles](/account/user-roles): * **Merchant admin** * **Change payment methods** ### Define a single description 1. Log in to your [live Customer Area](https://ca-live.adyen.com/). 2. Go to **Settings** > **Transaction description**. 3. Select the tab **Set a single description**. 4. Select the merchant accounts or the stores that you want the transaction description to apply to. 5. Configure the transaction description you want. | Effect | Action | | --------------------------------------------- | ---------------------------------------------------------------------------- | | Add DBA name | Select **A static business name**, and in the box type your DBA name. | | Add shopper statement | Select **A dynamic value**, and in the box type your DBA name. | | Combination of DBA name and shopper statement | Select **Static name and dynamic value**, and in the box type your DBA name. | 6. Select **Save**. Your changes are applied immediately to all transactions processed through the selected merchant accounts or stores. ### Define multiple different descriptions 1. Log in to your [live Customer Area](https://ca-live.adyen.com/). 2. Go to **Settings** > **Transaction description**. 3. Select the tab **Set multiple descriptions**. 4. To download the template CSV file, in the text select the words "**this template**". 5. Fill out the CSV file as described below, and save it under a new name. | Column | Explanation | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **merchantAccountCode** | The unique ID of the merchant account. | | **storeCode** | The unique store ID, if the transaction description should apply to a specific store under the specified merchant account. Leave empty if not applicable. | | **type** | One of the following values, to indicate what to add to the transaction description:- **fixed**: adds the DBA name. - **dynamic**: adds the shopper statement from the payment request. - **append**: adds the DBA name followed by the shopper statement from the payment request (if present). | | **doingBusinessAsName** | Your DBA name. | 6. In the Customer Area, click on the upload box and upload your saved CSV file. 7. Select **Save**. Your changes will be applied within one calendar day. ### Tab: Management API To configure the transaction description for a specific payment method using the Management API, you need to have the following [role](/account/user-roles): * **Management API — Payment methods read and write** You can configure the transaction description while requesting a payment method, or later, when updating a payment method. To configure the transaction description: 1. If you are requesting a new payment method, make a POST [/merchants/{merchantId}/paymentMethodSettings](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/\(merchantId\)/paymentMethodSettings) request to the live endpoint.\ Or if you are updating an existing payment method, make a PATCH [/merchants/{merchantId}/paymentMethodSettings/{paymentMethodId}](https://docs.adyen.com/api-explorer/Management/latest/patch/merchants/\(merchantId\)/paymentMethodSettings/\(paymentMethodId\)) request to the live endpoint. 2. In the request body, for the relevant payment method specify a `transactionDescription` object containing: * `doingBusinessAsName`: the DBA name for this payment method. * `type`: determines what the transaction description consists of. The possible values are: * **fixed**: transaction descriptions consist of the `doingBusinessAsName` value. * **dynamic**: transaction descriptions consist of the shopper statement from the payment request, or of the `doingBusinessAsName` value if the payment request doesn't contain a shopper statement. * **append**: transaction descriptions consist of a combination of the `doingBusinessAsName` value, followed by the shopper statement from the payment request (if present). Your changes are applied immediately to all the transactions processed with that payment method on your merchant account. ## Specify a shopper statement If you want your transaction descriptions to contain a dynamic shopper statement, it is not enough to configure the dynamic value option or the combination option as described under [Customize the transaction description](#customize-the-transaction-description). You also need to add a `shopperStatement` parameter to each payment request. * For ecommerce transactions, add a `shopperStatement` parameter to your [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) or [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. * For point-of-sale transactions, pass the `shopperStatement` inside the [`SaleToAcquirerData` ](/point-of-sale/add-data)parameter of your Terminal API request. ### (Optional) Add a localized transaction description If you are in Japan, go to the [Japan-specific section](#japanese-characters) for instructions. If you are active in a local market that uses a different character set, you can add a localized shopper statement. We support this for ecommerce transactions using the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint. Do the following: * Configure the dynamic value option or the combination option as described under [Customize the transaction description](#customize-the-transaction-description). * In your API request, include both the `shopperStatement` parameter and the `localizedShopperStatement` parameter.\ If you do not include a `localizedShopperStatement` or leave it empty, `shopperStatement` is used.\ For cross-border transactions, `shopperStatement` is used. ## Localized shopper statements in Japan If you do business in Japan, we support the following character sets, in combination with the [other allowed values for transaction descriptions](#customize-the-transaction-description): * ja-Hani (Kanji) * ja-Kana (Katakana) You have various options to set a transaction description in Japanese characters: * For in-person payments, when you create a Japanese store using the Management API, you must provide Kanji and Katakana shopper statements. These statements will then be used for all in-person payments processed for that store. See [Create a store - Japan](/point-of-sale/design-your-integration/determine-account-structure/automate-store-management?tab=create_a_store_-_japan_1_2). * For online payments, you can set what appears in the shopper statement in the following ways: * Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) with the Kanji and Katakana values that you want to set for your account. * [Add shopper statements in Japanese characters to your `/payments` request](#japanese-characters). ### Japanese shopper statement in online payments request In the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, include the `localizedShopperStatement` parameter. Including this parameter overrides any values that are set for your account. **Example of localized shopper statement with Kanji and Katakana values** ```json { "localizedShopperStatement": { "ja-Hani": "アディエン株式会社", "ja-Kana": "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ" } } ``` ### Character width The width of the characters that show up on the shopper's bank statement depends on the card brand and character set: | Brand | Kanji characters | Katakana characters | | ------------------------------------------------------------ | ---------------- | ------------------- | | Visa | Full-width | Half-width | | Mastercard | Full-width | Half-width | | JCB Includes Diners and Discover, which process through JCB. | Full-width | Full-width | ## Supported payment methods The following sections list the payment methods that support customized transaction descriptions. If defined in the Customer Area, the customized transaction description applies to all listed payment methods. This description can be overwritten by a transaction description that has been defined using the Management API for the individual payment method. ### Cards * Cartes Bancaires * China Union Pay (CUP) * Diners * Discover * Eftpos * Girocard * Interac * JCB * Maestro * Mastercard * NYCE * Pulse * Star * Visa ### Wallets Your transaction description configuration also applies if the shopper paid using a wallet payment method that contains one of the card brands above. For example, if a shopper pays with Apple Pay using their Visa card, the transaction description you configured in the Customer Area will be used. Or if you used the Management API to configure a specific transaction description for Visa, that description will be used. ### Other payment methods * Bancontact (BCMC) - both card and mobile integrations * iDEAL ## See also * [Manage payments](/account/manage-payments/) --- # Source: https://docs.adyen.com/account/user-roles.md Section: Account Title: User roles Description: Learn about the different roles and the corresponding permissions. --- title: "User roles" description: "Learn about the different roles and the corresponding permissions." url: "https://docs.adyen.com/account/user-roles" source_url: "https://docs.adyen.com/account/user-roles.md" canonical: "https://docs.adyen.com/account/user-roles" last_modified: "2024-12-09T13:17:00+01:00" language: "en" --- # User roles Learn about the different roles and the corresponding permissions. [View source](/account/user-roles.md) User roles are sets of permissions that determine what the user can do in the [Customer Area](https://ca-test.adyen.com/), such as whether they can look up payments, configure risk settings, or download financial reports. Each user can have one or more roles, depending on the tasks they need to perform. When you first sign up for Adyen, you get an **admin** user with the most common roles assigned to it, including the **Merchant admin** role. As the admin user, you can then [create new users](/account/users#create) for other people in your organization. The admin user can only give out roles that they themselves have. This prevents users from giving out unwarranted permissions, helping to keep your account safe. If you need to assign a role that neither you nor your admin have, reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Manage user roles The following sections describe the user roles grouped by category: * [Account](#account) * [Developer](#developer) * [Donation campaigns](#manage-donation-campaigns) * [Finance](#finance) * [Financial products](#financial-products) * [General](#general) * [In-person payments (POS)](#pos) * [Online payments](#online-payments) * [Partners](#partners) * [Platforms](#platforms) * [Risk](#risk) * [Transactions](#transactions) * [Classic platforms](#classic-platforms) ## Account The following roles allow you to create and manage account-related permissions: | Role | Permissions | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Change payment methods** | The user can [request new payment methods](/payment-methods/add-payment-methods), activate or deactivate payment methods, and configure how payment methods are rendered in your checkout. | | **Manage Merchant Account Groups role** | The user can view and manage [account groups](/account/account-structure#account-groups). This role must be combined with company account access. | | **Merchant additional merchant accounts** | The user can [request new merchant accounts](/account/manage-account-structure#request-merchant-account). | | **Merchant application form** | The user can change and upload application forms for new merchant accounts, without seeing information about other accounts under the same company. | | **Merchant review** | The user can view active merchant review processes for current account. | | **Merchant user management** | The user can [create and edit users](/account/users#create), and give out all roles and account access that they themselves have. | | **Manage account support tickets** | The user can view and manage all the support tickets created from the accounts that they have access to. | ## Developer The following roles allow you to create and manage permissions for APIs, webhooks, and test cards: | Role | Permissions | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Manage API credentials** | The user has full [API credential](/development-resources/api-credentials) management permissions, including generating an API key. | | **Manage test cards** | The user can view, create, and delete [test cards for making test payments](/development-resources/testing/create-test-cards). | | **Merchant technical integrator** | The user can manage [webhooks](/development-resources/webhooks), and [API URLs](/development-resources/live-endpoints). | ## Donation campaigns The following roles allow you to manage donation campaigns using [Adyen Giving](/online-payments/donations). | Role | Permissions | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Donation campaigns viewer** | The user can view donation campaigns and access campaign insights. This role does not give access to payment information. | | **Donation campaigns manager** | The user can create, start, edit, and end donation campaigns and access campaign insights. This role does not give access to payment information. | ## Finance The following roles allow you to create and manage financial-related permissions, such as reports and invoices: | Role | Permissions | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Change payout schedule** | The user can modify payout schedule settings. | | **Manage received invoices (Debtor)** | The user can view invoices submitted by the Adyen payments platform. | | **Manage submitted invoices (Creditor)** | The user can view, add, or edit invoices submitted by the merchant, and view MPL forecast reports. | | **Merchant financial** | The user can view all payment, payout, and Revenue Accelerate information, including the Adyen deposit. The user can also view and subscribe to generic [reports](/reporting) and the conversion, [external settlement](/reporting/settlement-reconciliation/transaction-level/external-settlement-detail-report), and 3D Secure conversion reports. Combined with the **Merchant admin** role, the **Merchant financial** role also gives permissions to manage the [Reserve](/account/balances/reserve). | | **Merchant manage bank accounts** | The user can [manage bank accounts](/account/manage-payout-account-details) for receiving payouts from Adyen. | | **Merchant View Reconciliation role** | The user can view the reconciliation status for the account, as well as associated reports such as the [forecast report](/reporting/settlement-reconciliation/transaction-level/reconcile-installment-payments#forecast-report). | | **See external settlement reports** | The user can view the [external settlement detail report](/reporting/settlement-reconciliation/transaction-level/external-settlement-detail-report). | | **See installment reports** | The user can view the [installments finance reports](/reporting/settlement-reconciliation/transaction-level/reconcile-installment-payments). | | **View Brazil regulatory reports** | The user can generate, schedule, and download Brazil reports. To use this role, the user must also have one of the following roles:- **Balance platform admin role** - **Balance platform base role** - **Download reports** - **Generate and schedule reports** | ## Financial products The following roles allow you to manage your financial products: | Role | Financial products | Permissions | | ---------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Capital base role** | [Adyen Capital](/capital) | The user can view capital grants and grant details. | | **Issue cards** | [Adyen Issuing](/issuing/) | The user can issue cards as payment instruments. To use this role, the user must also have the **Balance platform base role**. | | **Manage issuing disputes** | [Adyen Issuing](/issuing/) | The user can open disputes for payments made with Adyen-issued cards. To use this role, the user must also have the **Balance platform base role**. | | **Manage relayed authorization configuration** | [Adyen Issuing](/issuing/) | The user can view and manage [relayed authorization settings](/issuing/authorisation/relayed-authorisation) for Adyen-issued cards. | | **Manage transaction rules** | [Adyen Issuing](/issuing/) | The user can create and manage [transaction rules](/issuing/authorisation/transaction-rules/) for Adyen-issued cards, business accounts, and other types of outgoing transfers. To use this role, the user must also have the **Balance platform base role**. | | **Update card status** | [Adyen Issuing](/issuing/) | The user can change the status of a card. To use this role, the user must also have the **Balance platform base role**. | | **View card PAN & CVC** | [Adyen Issuing](/issuing/) | The user can view the PAN and CVC of Adyen-issued cards. | | **View payment instrument PII** | [Adyen Issuing](/issuing/), [Adyen Business accounts](/business-accounts) | For Adyen Issuing, the user can view personally identifiable information (PII) in the delivery details for a physical card issued to an [individual](/platforms/verification-requirements/?tab=individual_2#legal-entity-type). For Adyen Business accounts, the user can view the IBAN of an Adyen-issued bank account, if it belongs to a [sole proprietorship](/platforms/verification-requirements?tab=sole_proprietorship_3#legal-entity-type). To use this role, the user must also have the **Balance platform base role**. | ## General The following roles allow you to create and manage resources in your [Customer Area](https://ca-test.adyen.com/): | Role | Permissions | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Download reports** | The user can download all reports. | | **Generate reports** | The user can download and generate all reports. | | **Merchant admin** | The merchant admin has extensive permissions for accounts, reports, and risk, including full API key and user role management. This user can view sensitive data in the Customer Area by default. This user can manage account settings, [payment methods](/payment-methods), [risk configurations](/risk-management/configure-risk-settings), and [dispute materials](/risk-management/manage-disputes), as well as [upload business documents for the Adyen contract](/get-started-with-adyen/prepare-application). The user also has access to generic [reports](/reporting) as well as the risk, conversion, and [DCC reports](/reporting/dcc-transactions-and-fees). | | **Merchant View PII** | The user can view sensitive shopper data in the Customer Area. Examples of sensitive information include shopper data such as billing addresses, card details, and IP addresses. Adyen enables **Merchant View PII** by default for new **Merchant admin** users.Accessing unmasked PII can affect your [PCI DSS compliance level](/development-resources/pci-dss-compliance-guide/merchant-levels). | | **Merchant report** | The user can download, generate, and subscribe to all reports. The user can also view the payment lifecycle dashboard. | | **Merchant standard role** | The user can log in to the [Customer Area](https://ca-test.adyen.com/). This role is enabled by default for all users. If it is disabled, the user cannot log in to the Customer Area. | | **Merchant system messages** | The user can subscribe to [Customer Area notifications](/account/notification-center). | | **Merchant manage hosted onboarding** | The user can create, edit, and manage hosted onboarding themes. | ## In-person payments (POS) The following roles allow you to create and manage POS resources: | Role | Permissions | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Merchant Fix POS Payments role** | The user can [cancel](/point-of-sale/capturing-payments#cancel-authorisation) or [capture](/point-of-sale/capturing-payments) POS payments in the [Customer Area](https://ca-test.adyen.com/). | | **Merchant POS Report role** | The user can generate and download the following reports:- The DCC report. - The POS terminal fleet report. - The POS overview dashboard, which summarizes transaction volumes by entry mode, terminal type, and software.To use this role, the user must also have the **View Payments** role. | | **Merchant POS standard role** | The user can do the following:- View terminal data and configurations. - View product offerings and pricing. - View store lists and store IDs. - View [terminal orders](/point-of-sale/managing-terminals/order-terminals). - View and download fleet reports. | | **Merchant POS Terminal Management Admin role** | The user has full [terminal management](/point-of-sale/managing-terminals) permissions at both company and merchant levels. This includes [ordering](/point-of-sale/managing-terminals/order-terminals), [assigning](/point-of-sale/managing-terminals/assign-terminals), [boarding](/point-of-sale/managing-terminals/board-terminal), [customizing](/point-of-sale/managing-terminals/customize-terminals), and updating terminal configurations. The user can also [create stores](/point-of-sale/design-your-integration/determine-account-structure#create-stores), manage payment methods and Android apps, and access advanced settings such as **Terminal settings** > **Passcodes**, **Remote Access**, and **Terminal API** under **Integrations**. | | **Merchant POS Terminal Management role** | The user can manage terminal configurations on the merchant account level, including [customizing terminals](/point-of-sale/managing-terminals/customize-terminals), and viewing terminal data, contacts, and diagnostics. | | **Merchant POS Terminal Support role** | The user can do the following:- View terminals and [board terminals](/point-of-sale/managing-terminals/board-terminal). - [Move terminals between merchant accounts or stores](/point-of-sale/managing-terminals/assign-terminals). - Manage contacts. - Initiate remote access sessions. - Create support cases in the [Customer Area](https://ca-test.adyen.com/). | | **Merchant POS Terminal View role** | The user can view terminal lists and configurations, and store details. | | **Merchant terminal order role** | The user can view terminal orders, [order new terminals](/point-of-sale/managing-terminals/order-terminals), and [return broken terminals](/point-of-sale/managing-terminals/order-terminals#return-or-replace-terminals). | | **Merchant terminal replacement role** | The user can [place orders for replacement terminals](/point-of-sale/managing-terminals/order-terminals#return-or-replace-terminals). | | **Merchant terminal return role** | The user can view terminal orders and [return broken terminals](/point-of-sale/managing-terminals/order-terminals#return-or-replace-terminals). | | **Merchant view POS Payment Report** | The user can view the POS payment report and the [DCC report](/point-of-sale/currency-conversion#dcc-overview). To use this role, the user must also have the **View Payments** role. | ## Online payments The following roles allow you to create and configure payment links: | Role | Permissions | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Hosted Checkout and Pay by Link Settings** | The user can configure the [Hosted Checkout](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Hosted%2BCheckout) and [Pay by Link](/unified-commerce/pay-by-link) payment pages through the [Customer Area](https://ca-test.adyen.com/). | | **Pay by Link Interface** | The user can create [payment links](/unified-commerce/pay-by-link) through the [Customer Area](https://ca-test.adyen.com/) and Pay By Link App. | ## Partners The following roles allow you to manage partner permissions: | Role | Permissions | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | **Merchant access manage** | The user can view merchant accounts connected to the portal account and request access to manage these merchant accounts. | | **Partner admin** | The user can manage account settings and users, and update the logo for the portal account. | | **Partner marketing resources view** | The user can view and download marketing resources from the Partner Portal. | | **Partner referrals view** | The user can view referrals. | | **Partner referrals manage** | The user can view and add referrals. | | **Partner commissions view** | The user can view the partner commissions statements. | ## Platforms The following roles allow you to create and manage balance platform resources in your [Customer Area](https://ca-test.adyen.com/): | Role | Permissions | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Onboard account holders** | The user can request an account holder and other necessary resources in the Customer Area to initiate the [onboarding on invite flow](/platforms/onboard-users/?tab=onboarding-on-invite_1). | | **Balance platform base role** | The user can view all transfers, accounts, payment instruments, and, if applicable, the pages for [Issuing](/issuing). | | **Balance platform admin role** | The user can view all the pages and personally identifiable information (PII) of users. Users can also manage platform settings, such as:- Create and manage users - Create and manage API credentials - Download and schedule reports | | **Download transfer confirmation letter** | The user can download bank transfer confirmation letters from the **Transfers** page. To use this role, the user must also have the **Balance platform base role**. | | **Download KYC documents** | The user can view and download the content of documents that account holders have uploaded during their onboarding and based on which KYC checks have been performed. To use this role, the user must also have the **Balance platform base role**. | | **Download tax form** | The user can download the [1099-K tax form](/platforms/us-tax-forms) for a US account holder. To use this role, the user must also have the **Balance platform admin role** or **Balance platform base role**. | | **Download Balance Platform reports** | The user can download generated [Balance Platform Reports](/platforms/prepare-reports/generate-download-reports) and view KYC verification insights. | | **Generate Balance Platform reports** | The user can generate, schedule, and download [Balance Platform Reports](/platforms/prepare-reports/generate-download-reports#generate) and view KYC verification insights. | | **Initiate internal transfers** | The user can transfer funds between balance accounts. To use this role, the user must also have the **Balance platform base role**. | | **Initiate payouts to transfer instruments** | The user can transfer funds from a balance account to a transfer instrument linked to the account holder. To use this role, the user must also have the **Balance platform base role**. | | **Manage account holder capabilities** | The user can enable, disable, or request new capabilities for an account holder. To use this role, the user must also have the **Balance platform base role**. | | **Manage account holders & legal entities** | The user can:- Launch hosted onboarding using the **Customer Area**. - Make changes to a legal entity or to transfer instruments. - View KYC verification insights.To use this role, the user must also have the **Balance platform base role**. | | **Configure scheduled payouts** | The user can create, activate, deactivate, or delete sweep configurations for a balance account. To use this role, the user must also have the **Balance platform base role**. | | **Manage new split configuration settings** | The user can create and manage split configuration profiles and rules. | | **Merchant manage hosted onboarding** | The user can create, edit, and manage hosted onboarding themes. | | **View account holders PII** | The user can view unmasked personally identifiable information (PII) belonging to legal entities of type [individual](/platforms/verification-requirements/?tab=individual_2#legal-entity-type), or [sole proprietorship](/platforms/verification-requirements/?tab=sole_proprietorship_3#legal-entity-type). To use this role, the user must also have the **Balance platform base role**. | | **View bank transfers PII** | The user can view unmasked personally identifiable information (PII) related to third-party bank accounts that belong to individuals. This role only applies to the Transfers page. To use this role, the user must also have the **Balance platform base role**. | | **View KYC documents** | The user can view the list of documents that account holders have uploaded while onboarding, and based on which KYC checks have been performed. To use this role, the user must also have the **Balance platform base role**. | | **View new split configuration settings** | The user can view [split configuration](/platforms/automatic-split-configuration/) profiles and rules. | | **View capabilities audit trail** | The user can view the capability audit trail for each account holder, including actions taken by a user to edit the capabilities. To use this role, the user must also have the **Balance platform base role**. | | **View transfer schedules audit trail** | The user can see the audit trail for payout schedules or sweep configurations, including creation, update and deletion events. To use this role, the user must also have the **Balance platform base role**. | | **View transfers** | The user can view transfers and transfer details. | ## Risk The following roles allow you to manage risk and disputes: | Role | Permissions | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Download 3DS data** | The user can download raw 3D Secure data from the [payment details](/account/manage-payments#payment-details) page of each transaction. | | **Management Dynamic 3D Secure Rules** | The user can change the [Dynamic 3D Secure](/risk-management/dynamic-3d-secure) settings. | | **Manage referral lists** | The user can view and change [block and trust lists](/risk-management/configure-manual-risk/referral-rules). | | **Merchant change additional risk settings** | The user can view and allow [Device Fingerprinting](/risk-management/device-fingerprinting) and Persistent Cookies. | | **Merchant change risk settings** | The user can view risk reports, and manage [risk configurations](/risk-management/configure-risk-settings) and [block and trust lists](/risk-management/configure-manual-risk/referral-rules). | | **Merchant dispute management** | The user can [manage payment disputes](/risk-management/manage-disputes) (including chargebacks and RFIs) and [upload defense documents](/risk-management/understanding-disputes/dispute-reason-codes/#defense_requirements). | | **Merchant Manual Review** | The user can view the [manual review](/risk-management/case-management) list and take manual review actions. These actions include adding payment attributes to or removing them from [block and trust lists](/risk-management/configure-manual-risk/referral-rules/). | | **Merchant View Oil Splash role** | The user can view the [shopper DNA oil splash](/risk-management/case-management#use-case-details-to-review-a-case) and use its search functionality. The oil splash provides shopper DNA data from all merchant accounts within the company. | | **Merchant View Risk Results role** | The user can view detailed risk check results for each transaction. | | **Merchant view risk settings** | The user can view [risk configurations](/risk-management/configure-risk-settings) and [block and trust lists](/risk-management/configure-manual-risk/referral-rules). | | **Risk Admin** | This user has full risk management permissions, including viewing risk reports and shopper data. The risk admin can manage [risk configurations](/risk-management/configure-risk-settings), payment [disputes](/risk-management/manage-disputes) (including chargebacks and RFIs), and [block and trust lists](/risk-management/configure-manual-risk/referral-rules), in addition to [manually reviewing payments](/risk-management/case-management) and [uploading defense documents](/risk-management/understanding-disputes/dispute-reason-codes/#defense_requirements). | | **Upload chargebacks role** | The user can upload a CSV file with PSP references for which chargebacks are known to have occurred. The corresponding payment will be labeled as a chargeback in the system. | | **View Risk Reports** | The user can download and subscribe to risk reports. | ## Transactions The following roles allow you to manage payments: | Role | Permissions | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CallCenter user** | The user can access the [Customer Area](https://ca-test.adyen.com/), and make payments in the call center. | | **CallCenter user tokenization role** | The user can use [tokens](/online-payments/tokenization) for recharges in the MOTO call center. | | **Data Protection Officer** | The user can send data protection requests, and configure the transaction retention period in order to restrict company payments visibility. | | **Data Protection Operations** | The user can send data protection requests. | | **Merchant manage payments** | The user can [refund](/account/manage-payments#refund-a-payment), [cancel](/account/manage-payments#cancel-a-payment), or [capture](/account/manage-payments#capture-a-payment) a payment from the **Payment details** page in the [Customer Area](https://ca-test.adyen.com/). This role must be combined with the **View Payments** role. | | **Merchant allow bank-refund role** | The user can refund payments where the payment method used is officially not refundable. The refund will be performed by a bank transfer, and not linked to the payment. Although the payment has been refunded, a chargeback can still occur with a direct debit. | | **Merchant decrypt GiftCards** | The user can view the decrypted giftcard number. | | **Merchant manage CallCenter** | The user can change the call center settings, for example the skin used for the call center. | | **Merchant manage payouts - thirdparty** | The user can manually confirm or decline [payouts](/online-payments/online-payouts) to bank accounts or wallets. | | **Merchant manage payouts - withdrawal** | The user can manually confirm or decline payouts for a withdrawal related to gambling or trading. | | **Merchant submit batch modifications** | The user can create and upload input files for [batch processing of refunds, captures, and cancels](/development-resources/batch-processing/submit-modifications). | | **Merchant submit batch payments** | The user can create and upload input files for [batch processing of payment authorisations](/development-resources/batch-processing). | | **Merchant re-authorise payments** | The user can [re-authorise payments](/account/manage-payments#reauthorize-a-payment) in the [Customer Area](https://ca-test.adyen.com/). | | **Merchant view payouts** | The user can view open and processed payouts in the [Customer Area](https://ca-test.adyen.com/). | | **View Acquiring Details** | The user can view details about the acquiring, for example the [raw acquirer response codes](/development-resources/raw-acquirer-responses). | | **View Payments** | The user can [look up payments](/account/manage-payments#look-up-payments) and offers, and access the payment search pages. This role is enabled by default for all users. | ## Classic platforms The following roles allow you to create and manage resources for [classic platforms integrations](/classic-platforms): | Role | Permissions | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Allow the user to download the payout confirmation letter** | The user can [download the payout letter](/classic-platforms/payouts/track-payouts#download-payout-letter) from the Customer Area. | | **Instruct payouts to bank accounts for all account holders from the customer area** | The user can [initiate payouts](/classic-platforms/payouts/manual-payout) to account holders' bank accounts. | | **Manage HOP settings** | The user can [customize the appearance](/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance) for their hosted onboarding page and can access an onboarding page on behalf of an account holder. | | **Merchant Extended MarketPlace role** | The user can [manage account holders](/classic-platforms/account-holders-and-accounts) and [split configurations](/classic-platforms/split-configuration-for-stores), view [KYC details and reports](/classic-platforms/verification-process), [extend the inactivation or suspension deadline](/classic-platforms/verification-process#inactivation-suspension-deadline), and [download the payout letter](/classic-platforms/payouts/track-payouts#download-payout-letter) from the Customer Area. | | **Merchant MarketPlace role** | The user can view the **Sub-merchants** page, where they can view the KYC status, payout methods, payout history, and transactions of account holders. If [Adyen Score](/classic-platforms/identify-account-holder-risk) is enabled, the user can view the **Case management** and **Risk signals** pages. | | **Merchant Marketplace Risk Role** | In [Adyen Score](/classic-platforms/identify-account-holder-risk), the user can disable payouts, suspend account holders, refund payments, and flag risk signals as false positive. | | **Merchant Marketplace Risk Admin Role** | In [Adyen Score](/classic-platforms/identify-account-holder-risk), the user can do everything included in the **Merchant Marketplace Risk Role**. The user can also configure settings such as create or edit custom risk signals, edit high risk lists, and set weights for risk signals. | | **Manage split configuration settings** | The user can create and manage [split configuration profiles and rules](/classic-platforms/split-configuration-for-stores). | | **Perform and manage Fund Transfers from the customer area** | The user can [transfer funds between accounts](/classic-platforms/fund-transfer#transfer-funds-customer-area). | --- # Source: https://docs.adyen.com/account/users.md Section: Account Title: Manage users Description: Allow members of your organization to manage different parts of your Adyen account. --- title: "Manage users" description: "Allow members of your organization to manage different parts of your Adyen account." url: "https://docs.adyen.com/account/users" source_url: "https://docs.adyen.com/account/users.md" canonical: "https://docs.adyen.com/account/users" last_modified: "2022-01-19T10:10:00+01:00" language: "en" --- # Manage users Allow members of your organization to manage different parts of your Adyen account. [View source](/account/users.md) Users let people in your organization access the [Customer Area](https://ca-test.adyen.com/), where they can view and manage different parts of your Adyen account. You can control a user's permissions by assigning [roles](/account/user-roles), and by specifying which [merchant accounts](/account/account-structure) they can access. When you sign up for an Adyen account, you get an **admin** login for the [Customer Area](https://ca-test.adyen.com/). The admin user has the most common [roles](/account/user-roles) and access to all linked merchant accounts. As the admin user, you can then create new users for other people in your company. On this page, you'll learn how to: * [Check which roles your own user has](#view-own-roles). * [Create](#create) or [duplicate](#duplicate) users. * [Change a user's permissions](#edit). * [Add trusted IP addresses](#add-trusted-ip). * [Delete](#delete) users. * [Get an overview of all users](#users-within-a-company). ## View your own roles To see which [roles](/account/user-roles) are assigned to your own user: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Select the user menu icon in the top right corner. 3. Select **Profile**. 4. In the **Roles** pane, select the arrow to see a list of all roles assigned to your user. You can also search for a specific role. ## Create a user To be able to create users, you need to have one of the following [roles](/account/user-roles): * Merchant admin * Merchant user management To create a user: 1. On the **User details** page, select the login method for the user and fill in the required fields. We recommend single sign-on as the login method. The login method options include: * **SSO**: The user must use [single sign-on](/account/single-sign-on). * **Email and password**: The user must sign in with their email and password. 2. Select **Continue**. 3. For **Accounts**, you can choose which [accounts](/account/account-structure) the user will be able to access. Remember that you can only give access to [merchant accounts](/account/account-structure#merchant-accounts) and [account groups](/account/account-structure#account-groups) that your own user already has. For example, if you give access to an account group that contains merchant accounts A, B, and C, but you only have access to A and B, the new user will also only have access to A and B. 4. For **Roles**, you can only assign roles that your own user already has. For a list of all possible roles, see [user roles](/account/user-roles). If you need to assign a role that neither you nor your admin user has, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). 5. In the **Summary** page you can review and edit the details, accounts, and roles you assigned to the new user. 6. Select **Create new user**. The new user receives an email with a link to verify their email address and set up a password, and to set up [Multifactor Authentication (MFA)](/account/multifactor-authentication) for their [Customer Area](https://ca-test.adyen.com/) account. This new user verification link is only valid for two weeks. If the link expires, you need to [resend an email verification](#email-verification) to the user. ### Resend email verification If the user does not verify their email address and create a password within the link expiry time, you need to resend them an email verification: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Account** > **Users**, and select the user from the **User List**. 3. In the **User details** pane, select **Resend email verification**. The user receives an email with a link to verify their email address and to create a password, and to set up [Multifactor Authentication (MFA)](/account/multifactor-authentication) for their [Customer Area](https://ca-test.adyen.com/) account. This email verification link is only valid for 24 hours. ### Send a password reset email If the user has forgotten their password, you need to send them a password reset email: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Account** > **Users**, and select the user from the **User List**. 3. In the **User details** pane, select **Send password reset**. The user receives an email with a link to create a password for their [Customer Area](https://ca-test.adyen.com/) account. This password reset link is only valid for 24 hours. ## Duplicate an existing user Duplicating an existing user allows you to quickly create a new user with the same permissions as an existing user. This is useful, for example, if several people in your organization need to perform the same payments-related tasks. Because you can only assign permissions that your own user already has, it is possible that the new user has fewer permissions than the user you want to duplicate. For example, if you duplicate a user who has the **Risk admin** role, but you do not have this role yourself, the duplicate user won't have this role either. To be able to duplicate users, you need to have one of the following [roles](/account/user-roles): * Merchant admin * Merchant user management To duplicate an existing user: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Users**. This opens the **Users** list with all users linked to your company account. 2. Select the copy button **in the **Actions** column next to the user that you want to duplicate. 3. Enter a username and email address for the new user. The **Accounts** and **Roles** panes show the accounts and roles the duplicate user has access to. 4. Select **Create user**. The new user receives an email with a link to verify their email address and create a password, and to set up [Multifactor Authentication (MFA)](/account/multifactor-authentication) for their [Customer Area](https://ca-test.adyen.com/) account. This new user link is only valid for two weeks. If the link expires, you need to [resend an email verification](#email-verification) to the user. ## View and change user permissions After you create a user, you may want to assign them other roles or change their account access. Remember that you can only assign roles or give access to accounts that your own user already has. To change user permissions, you need to have one of the following [roles](/account/user-roles): * Merchant admin * Merchant user management To change a user's permissions: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Users**. 2. Select the user from the **User List**. This opens the user details page. 3. Select the edit icon **and make your changes. 4. Select **Save**. ## Add trusted IP addresses As a security measure, you can define a range of trusted IP addresses from which a user can log in. The maximum number of trusted IP addresses you can add is 45. When you add a range of trusted IP addresses for a user, the user is only allowed to log in from that range. Login attempts from outside that range will be blocked. To add trusted IP addresses: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Users**. 2. Select the user from the list. This opens the user details page. 3. In the **Trusted IP addresses** section, select **Add IP address**. 4. Enter the IP address and select a range from the drop-down menu. 5. Select **Add**. ## Delete an existing user If you want to remove the access permissions of a user, for example, because they have left your company, you need to deactivate the user. To be able to deactivate users, you need to have one of the following [roles](/account/user-roles): * Merchant admin * Merchant user management To deactivate an existing user: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Users**. 2. Select the user from the **User List**. This opens the user details page. You cannot deactivate the user you are logged in with. 3. Select **Deactivate user** and then select **Deactivate** in the pop-up window to confirm. This user can now no longer access the [Customer Area](https://ca-test.adyen.com/). If you need to restore the user's access, select **Reactivate user** on the user details page. ## Get an overview of all users The **Users within a company** report includes the roles assigned to a user, and the last time the user logged in to the [Customer Area](https://ca-test.adyen.com/). To be able to generate the **Users within a company** report, you need to have one of the following roles: * Merchant admin * Merchant report To generate this report: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Reports**. 3. Search for the **Users within a company** report. 4. Select **Generate**. This opens a window to configure the report: * To generate the report for a specific user, enter their username. * To generate the report for all users within your company account, leave the username field empty. * You can also exclude accounts, account groups, and roles from the report. 5. Choose the **File type** for the report. 6. Select **Generate report**. This automatically downloads the report. ## See also * [User roles](/account/user-roles) * [Account structure](/account/account-structure) --- # Source: https://docs.adyen.com/account/users/partner-users.md Section: Account Title: Manage partner users Description: Allow partners to manage parts of your Adyen account. --- title: "Manage partner users" description: "Allow partners to manage parts of your Adyen account." url: "https://docs.adyen.com/account/users/partner-users" source_url: "https://docs.adyen.com/account/users/partner-users.md" canonical: "https://docs.adyen.com/account/users/partner-users" last_modified: "2023-06-19T12:51:00+02:00" language: "en" --- # Manage partner users Allow partners to manage parts of your Adyen account. [View source](/account/users/partner-users.md) [Our partners](https://www.adyen.com/partners/network) are organizations that help you integrate with Adyen. For example, they might configure your terminals to accept [in-person payments](/point-of-sale). To allow a partner to manage parts of your Adyen account, add a partner user for them. You can specify which of your merchant accounts a partner can access. You can also assign [user roles](/account/user-roles) to determine what a partner user can view and do. ## Add a partner user To be able to add a partner user, you need to have: * Merchant admin [user role](/account/user-roles) * Access to the company account or merchant account you want to add a partner user to * All the roles and permissions that the partner is requesting To add a new partner user to your company or merchant accounts: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Account** > **Partner users**, and select **Add partner**. 3. Enter the partner user email address and select **Continue**. The email address needs to match your partner's existing Adyen Partner Portal account. If you are unsure what email address your partner has signed up with, contact your partner. 4. Select one or more accounts for your partner to access and select **Continue**. * To give access to all your merchant accounts, select your company account. * For your information security, select only the roles your partner needs. 5. Select the relevant [user roles](/account/user-roles) for your partner and select **Continue**. * For your information security, select only the roles your partner needs. 6. Review the information that you provided and select **Add partner**. 7. Confirm you take responsibility for adding the partner user to your account. After successfully adding a partner user: * You and other admins of your account will receive a confirmation email. * Your partner receives an invitation email. ## View and change partner user roles After you create a partner user, you may want to assign them other roles or change their account access. Remember that you can only assign roles or give access to accounts that your own user already has. To change partner user roles, you need to have one of the following [user roles](/account/user-roles): * Merchant admin * Merchant user management To change a partner user's roles: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Partner users**. 2. Select the relevant partner user. This opens the partner user details page. 3. Select the edit icon **and make your changes. 4. Select **Save**. ## Revoke access After you create a partner user, you may want to (temporarily) revoke their access to your company or merchant accounts. After you revoke access, you can restore access for the previously enabled roles. To revoke a partner user's access to your company or merchant accounts: 1. Log in to your [Customer Area](https://ca-test.adyen.com/), and go to **Account** > **Partner users**. 2. Select the relevant partner user. This opens the partner user details page. 3. Under **User details**, select **Revoke access**. 4. Select **Save**. ## See also * [User roles](/account/user-roles) --- # Source: https://docs.adyen.com/account/view-your-balances.md Section: Account Title: View your balances Description: Stay updated about the balances in your company and merchant accounts. --- title: "View your balances" description: "Stay updated about the balances in your company and merchant accounts." url: "https://docs.adyen.com/account/view-your-balances" source_url: "https://docs.adyen.com/account/view-your-balances.md" canonical: "https://docs.adyen.com/account/view-your-balances" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # View your balances Stay updated about the balances in your company and merchant accounts. [View source](/account/view-your-balances.md) The funds belonging to your business are held in your merchant account as balances. To stay updated about the balances in your accounts, you can view your balance details at the merchant account level or at the company account level (this shows the sum of the balances in all the merchant accounts). To do this, you can use the [Customer Area](https://ca-test.adyen.com/) or the Balance Control API. For more details about the types of balances you can hold, see [Balances](/account/balances-pilot). ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online](/online-payments) or [point-of-sale](/point-of-sale) integration with Adyen. | | **[API credential roles](/development-resources/api-credentials/roles/)** | To view balances using the API, make sure that you have the credentials for Balance Control API with the following role:- **Balance control API - Balances management** | | **[Customer Area roles](/account/user-roles)** | Make sure that you have the following role:- **Merchant financial** | | **Limitations** | You can only view the activity log for your merchant account using the Customer Area. This is not supported for the Balance Control API. | ## View balances at the company level To view balance details at the company account level, you can either use the [Customer Area](https://ca-test.adyen.com/) or the Balance Control API. ### Tab: Customer Area At the company level, you can view the **Balances overview**, which gives you details about the following: * The total available balance for the company account. This is the sum of the available balances for all the merchant accounts under the company. This includes: * **Pending balance**: The sum of the pending balance in all the merchant accounts. This is the amount in the account that has not been settled yet. * **Next payout amount**: The sum of the next payout amount for all merchant accounts. This is the amount that will be settled to your bank account with the next payout. * **Reserve**: The sum of the reserve balance for all merchant accounts. This is the available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your pending and next payout balances. * **Negative refund allowance** (if applicable): The sum of the negative refund allowance for all merchant accounts. This is the additional available amount to cover refunds if the other balances are insufficient. Adyen determines whether you are allowed to have a negative refund allowance. * **Available funds**: The sum of the available funds from all merchant accounts. This is the sum of the pending balance, next payout amount, reserve, and if applicable, the negative refund allowance. * An overview of the available balance for each of the merchant accounts under the company account. Each overview includes: * **Currency**: The currency in which the balance is held. * **Pending balance**: The funds in the merchant account that have not been settled yet. * **Payable amount** (next payout amount): The amount that will be settled to your bank account with the next payout. * **Reserve**: The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your pending and next payout balances. * **Available funds**: The sum of the pending balance, next payout amount, reserve, and if applicable, the negative refund allowance. * **Deposit**: The amount withheld by Adyen to cover potential losses and liabilities due to payment processing. ### View the balances To view the **Balances overview** using the [Customer Area](https://ca-test.adyen.com/): 1. Select your company account. 2. Go to **Finance** > **Balances (Company)**. 3. Select the currency in which you want to see your company's balances. The page loads the balance details for the currency you selected. Note the following details: * **Company balance**: details about the available balance for the company account, in the currency you selected. This is the sum of the available balance in that currency for all the merchant accounts. * **Merchant accounts**: an overview of the available balance for each of the merchant accounts under the company account. ### Tab: Balance Control API At the company level, you can make a request to view the balance details for all merchant accounts under your company account. For each merchant account, the response returns the following: * **Merchant account code**: The unique identifier of the merchant account. * **Pending balance**: The funds in the merchant account that have not been settled yet. * **Next payout amount**: The amount that will be settled to your bank account with the next payout. * **Reserve**: The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your pending and next payout balances. * **Available funds**: The sum of the pending balance, next payout amount, reserve, and if applicable, the negative refund allowance. * **Deposit**: The amount withheld by Adyen to cover potential losses and liabilities due to payment processing. To view the balances for all merchant accounts in your company: 1. Make a GET `/balanceOverview/companies/{companyAccountCode}/balances` request. In your request, specify the following parameters: | Parameter | Type | Required | Description | | -------------------- | ----- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `companyAccountCode` | Path | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of your company account. | | `currency` | Query | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The currency for which you want to view the balances. **Format**: [ISO 3-character currency code](/development-resources/currency-codes#currency-codes). | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ** #### Example request The following example shows a request to view the balances overview of your company account for the USD currency. **View balances overview for company account** ```bash curl https://balance-control-test.adyen.com/balance-control/api/v2/balanceOverview/companies/YOUR_COMPANY_ACCOUNT/balances?currency=USD \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. Note the response, which returns a `merchantBalancesOverview` array containing the balance details for each merchant account under the company account. Each item in the array represents one merchant account, and includes the following parameters: | Parameter | Type | Required | Description | | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `merchantAccount` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the merchant account. | | `availableFund` | Response body | | The sum of the pending balance, next payout amount, reserve, and if applicable, the negative refund allowance. | | `pendingBalance` | Response body | | The funds in the merchant account that have not been settled yet. | | `nextPayout` | Response body | | The amount that will be settled to your bank account with the next payout. | | `reserve` | Response body | | The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your pending and next payout balances. | | `deposit` | Response body | | The amount withheld by Adyen to cover potential losses and liabilities due to payment processing. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ** #### Example response The following is an example response to view the balances overview of your company account for the USD currency. **View balances overview for company account** ```json { "merchantBalancesOverview": [ { "merchantAccount": "MERCHANT_ACCOUNT_1", "availableFund": { "value": 3191, "currency": "USD" }, "nextPayout": { "value": 3191, "currency": "USD" }, "reserve": { "value": 0, "currency": "USD" } }, { "merchantAccount": "MERCHANT_ACCOUNT_2", "availableFund": { "value": 0, "currency": "EUR" }, "reserve": { "value": 0, "currency": "EUR" } }, { "merchantAccount": "MERCHANT_ACCOUNT_3", "availableFund": { "value": 5350, "currency": "GBP" }, "nextPayout": { "value": 5350, "currency": "GBP" }, "reserve": { "value": 0, "currency": "GBP" } }, { "merchantAccount": "MERCHANT_ACCOUNT_4", "availableFund": { "value": 564, "currency": "AUD" }, "nextPayout": { "value": 564, "currency": "AUD" }, "reserve": { "value": 0, "currency": "AUD" } } ] } ``` ## View merchant account balances To view balance details at the merchant account level, you can either use the [Customer Area](https://ca-test.adyen.com/) or the Balance Control API. ### Tab: Customer Area In the [Customer Area](https://ca-test.adyen.com/), you can view the following details: * **Balance overview**: An overview of the balances in your merchant account. This includes the pending, next payout, and reserve balances for the merchant account. * **Activity log**: A history of past activity relating to the balances in your merchant account. * **Deposit**: The amount withheld by Adyen to cover potential losses and liabilities due to payment processing. ### View the balances To view the balance details using the [Customer Area](https://ca-test.adyen.com/): 1. Select the correct merchant account. 2. Go to **Finance** > **Balances overview** 3. Select the **Balance** tab to view the available funds and the deposit.\ The following screenshot shows an example of the **Balances overview** page: [![Balances overview](/user/pages/docs/12.account/16.view-your-balances/balances-overview.png)](/user/pages/docs/12.account/16.view-your-balances/balances-overview.png) 4. Select the **Deposit** tab to view the current deposit configured for the merchant account. 5. Select the **Activity log** tab to view past activity for the merchant account. ### Tab: Balance Control API To view the **Balances overview** using the Balance Control API: 1. Make a GET `/balanceOverview/companies/{merchantAccountCode}/balances` request. In your request, specify the following parameters: | Parameter | Type | Required | Description | | --------------------- | ----- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchantAccountCode` | Path | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of your merchant account. | | `currency` | Query | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The currency for which you want to view the balances. **Format**: [ISO 3-character currency code](/development-resources/currency-codes#currency-codes). | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ** #### Example request Here is an example request to view the balances overview of your merchant account for the USD currency. ```bash curl https://balance-control-test.adyen.com/balance-control/api/v2/balanceOverview/companies/YOUR_MERCHANT_ACCOUNT/balances?currency=USD \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. Note to the response, which returns the following parameters: | Parameter | Type | Required | Description | | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `merchantAccount` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of your merchant account. | | `availableFund` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The sum of the pending balance, next payout amount, reserve, and if applicable, the negative refund allowance. | | `pendingBalance` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The funds in your merchant account that have not been settled yet. | | `nextPayout` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The amount that will be settled to your bank account with the next payout. | | `reserve` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your in-process funds. | | `deposit` | Response body | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The amount withheld by Adyen to cover potential losses and liabilities due to payment processing. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/required.svg?decoding=auto\&fetchpriority=auto) Required for all transactions.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required for particular setups, or issuers and card schemes.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended for all transactions, but not required. ** #### Example response Here is an example response to view the balances overview of your merchant account for the USD currency. ```json { "merchantAccount": "YOUR_COMPANY_ACCOUNT", "availableFund": { "value": 9889873, "currency": "USD" }, "pendingBalance": { "value": -112845, "currency": "USD" }, "nextPayout": { "value": 719, "currency": "USD" }, "reserve": { "value": 2000, "currency": "USD" }, "deposit": { "value": 50000, "currency": "USD" } } ``` ## See also [Manage your balances](/account/manage-your-balances-pilot) [Stay updated about the balances in your company and merchant accounts.](/account/manage-your-balances-pilot) --- # Source: https://docs.adyen.com/adyen-for-platforms-model.md Section: Adyen for Platforms Title: Adyen for Platforms Description: Onboard users of your platform or marketplace, process payments for them, and pay out their funds. --- title: "Adyen for Platforms" description: "Onboard users of your platform or marketplace, process payments for them, and pay out their funds." url: "https://docs.adyen.com/adyen-for-platforms-model" source_url: "https://docs.adyen.com/adyen-for-platforms-model.md" canonical: "https://docs.adyen.com/adyen-for-platforms-model" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Adyen for Platforms Onboard users of your platform or marketplace, process payments for them, and pay out their funds. Adyen for Platforms is an end-to-end payment solution for peer-to-peer marketplaces, on-demand services, crowdfunding platforms, or any other platform business model. Your users can sign up, sell, and get paid all through one solution. With Adyen for Platforms, you can: * Onboard sellers, service providers, or contractors to your platform, and let Adyen verify them before paying out. * Accept payments on behalf of your users. * Decide when and how your users are paid, either utilizing our managed payouts solution, or exercising full control over timing with custom payouts. * Identify fraudulent behavior, stop suspicious payouts, and flag unusual user activities. * Use Adyen-generated reports for your bookkeeping and reconciliation processes to ensure accurate accounting of funds within your platform. ## Adyen for Platforms integration Your business model and payment processing requirements determine how you need to integrate Adyen for Platforms. We offer two models: one for marketplaces, and one for platforms. ### Model comparison | Features | Marketplace | Platform | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Shopper interaction | Directly with you | Directly with your user | | Online payments | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | In-person payments | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Payment facilitators | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Payouts directly to sub-merchant | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Financial products (Card issuing, business accounts, business financing) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Select your model [![Marketplace icon](/user/themes/adyen-docs/assets/icons/marketplaces-black.svg)\ \ **Marketplace**\ \ You have an online marketplace, an ecommerce website, or a mobile app, where your brand is known to both your users and their customers.](/marketplaces) [![Platform icon](/user/themes/adyen-docs/assets/icons/adyen-for-platforms-black.svg)\ \ **Platform**\ \ You have a commerce platform, ordering or point-of-sale solution, retail management system, or you are a payment facilitator.](/platforms) ## Determine which model to integrate #### Decision tree **Need help determining which Adyen for Platforms model is right for you?** Select **Start** and answer some questions to help you determine which Adyen for Platforms model you should integrate. **Have you integrated Adyen for Platforms before Aug 1, 2022?** * **Have you upgraded to the balance platform?** * **Do you process in-person payments on behalf of your users?** * **Our platform model suits your needs** By integrating our platform model, you can make both in-person and online payments part of your product offering. Examples of a platform model include commerce platforms, ordering or point-of-sale solutions, retail management systems, and payment facilitators. For more information on platforms at Adyen, see [Platform model](/platforms). * **Is your brand visible to your users' customers?** Do customers recognize that they are doing business directly with your brand? * **Our marketplace model suits your needs** By integrating our marketplace model, you can make online payments part of your product offering. Examples of a marketplace model include ecommerce websites and mobile apps. For more information on marketplaces at Adyen, see [Marketplace model](/marketplaces). * **Our platform model suits your needs** By integrating our platform model, you can make both in-person and online payments part of your product offering. Examples of a platform model include commerce platforms, ordering or point-of-sale solutions, retail management systems, and payment facilitators. For more information on platforms at Adyen, see [Platform model](/platforms). * **Classic integration** You implemented the [classic Adyen for Platforms integration](/classic-platforms). If you would like to offer additional [financial products](/platforms/financial-products) or enhance payment processing for your users, you can upgrade your integration to our [balance platform](/platforms). Reach out to your Adyen contact to discuss which new Adyen for Platforms model is the best fit for you. * **Do you process in-person payments on behalf of your users?** * **Our platform model suits your needs** By integrating our platform model, you can make both in-person and online payments part of your product offering. Examples of a platform model include commerce platforms, ordering or point-of-sale solutions, retail management systems, and payment facilitators. For more information on platforms at Adyen, see [Platform model](/platforms). * **Is your brand visible to your users' customers?** Do customers recognize that they are doing business directly with your brand? * **Our marketplace model suits your needs** By integrating our marketplace model, you can make online payments part of your product offering. Examples of a marketplace model include ecommerce websites and mobile apps. For more information on marketplaces at Adyen, see [Marketplace model](/marketplaces). * **Our platform model suits your needs** By integrating our platform model, you can make both in-person and online payments part of your product offering. Examples of a platform model include commerce platforms, ordering or point-of-sale solutions, retail management systems, and payment facilitators. For more information on platforms at Adyen, see [Platform model](/platforms). --- # Source: https://docs.adyen.com/business-accounts.md Section: Business accounts Title: Business accounts Description: Enable your users to use Adyen business accounts. --- title: "Business accounts" description: "Enable your users to use Adyen business accounts." url: "https://docs.adyen.com/business-accounts" source_url: "https://docs.adyen.com/business-accounts.md" canonical: "https://docs.adyen.com/business-accounts" last_modified: "2023-07-06T18:07:00+02:00" language: "en" --- # Business accounts Enable your users to use Adyen business accounts. [View source](/business-accounts.md) This feature is in development phase. Some of the APIs, documentation, and processes may change as the feature evolves. If you have any feedback, reach out to your Adyen contact. With your Adyen for Platforms integration, you can take advantage of all the features our infrastructure offers, such as allowing your users to use an Adyen business account. You can implement this solution using either our API integration or our Hosted Onboarding page. When a user has an Adyen business account, they can: * Send and receive domestic and international transfers. They can make business-related fund transfers, such as: * Paying supplier invoices or utilities. * Receive business-related fund transfers from any third party, such as payments from businesses or customers. * Get paid out in a simpler and faster way. They can receive payouts directly to their Adyen business account instead of paying out to a third-party bank account. ## User eligibility To be eligible for an Adyen business account, your users must meet the following criteria: * They must be an organization or a sole proprietor operating in one of the [supported countries](#supported-countriesregions). * Ultimate Beneficial Owners (UBOs) and individuals associated with an organization or a sole proprietor must be tax residents in one of the [supported countries](#supported-countriesregions). * They must provide [additional required information for business accounts](/business-accounts/verification-requirements). ## Supported countries/regions Adyen business bank accounts are available to eligible legal entities operating throughout the United States, the United Kingdom, and the Eurozone (excluding specific Nordic territories). All associated UBOs must also reside in one of these approved regions. | Europe (Eurozone) | | ----------------- | Austria\ Belgium\ Bulgaria\ Croatia\ Cyprus\ Estonia\ France\ Germany\ Greece\ Ireland\ Italy\ Latvia\ Lithuania\ Luxembourg\ Malta\ Netherlands\ Portugal\ Slovakia\ Slovenia\ Spain ***Note:** Accounts are NOT available to any Nordic countries (including Finland, which is in the Eurozone but excluded from this product).* | United Kingdom | | -------------- | Mainland United Kingdom ***Note:** Business accounts are NOT supported for the Channel Islands.* | North America | | ------------- | United States ***Note:** U.S. accounts require state-specific reporting details during onboarding.* ## Acquiring regions An acquiring region is a specific geographic area where your transactions are processed through local banking networks and regulatory frameworks. An acquiring region can consist of a single country (for example, the USA), or a group of countries (for example, Europe/EEA). These regions are defined based on shared financial standards, currencies, and legal requirements. Based on the [countries/regions that are supported for business accounts](#supported-countriesregions), we get the following acquiring regions: * Europe/EEA * United Kingdom * United States ## Next steps Find out how you can get started with your business accounts integration. [required](/business-accounts/get-started) [Get started](/business-accounts/get-started) [See an overview of steps from signing up to going live with business accounts.](/business-accounts/get-started) [required](/business-accounts/integration-checklist) [Integration checklist](/business-accounts/integration-checklist) [Find out the steps to build your business accounts integration.](/business-accounts/integration-checklist) [required](/business-accounts/verification-requirements) [Determine verification requirements](/business-accounts/verification-requirements) [Learn about the additional information required to enable business accounts for your users.](/business-accounts/verification-requirements) --- # Source: https://docs.adyen.com/business-accounts/accept-direct-debits-uk.md Section: Business accounts Title: Accept direct debits in the UK Description: Learn how to allow your users in the UK to accept direct debits. --- title: "Accept direct debits in the UK" description: "Learn how to allow your users in the UK to accept direct debits." url: "https://docs.adyen.com/business-accounts/accept-direct-debits-uk" source_url: "https://docs.adyen.com/business-accounts/accept-direct-debits-uk.md" canonical: "https://docs.adyen.com/business-accounts/accept-direct-debits-uk" last_modified: "2019-12-06T14:44:00+01:00" language: "en" --- # Accept direct debits in the UK Learn how to allow your users in the UK to accept direct debits. [View source](/business-accounts/accept-direct-debits-uk.md) **Limited availability**\ Direct debits in the UK are in pilot phase. Some of the processes and documentation may change as the feature evolves. *** Adyen business accounts support direct debits in the United Kingdom. Your users can authorize direct debits to automatically pay for business expenses, such as paying for utilities or to providers. ## Requirements Before you begin, make sure that you fulfill the following requirements: | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model) integration that includes business accounts. | | **Capabilities** | Make sure that you enabled the following capability for your user: - **sendFundsToThirdParty** | | **Limitations** | The information in this page only applies to accounts in the UK. | | **Setup steps** | Reach out to your Adyen contact to enable direct debits in the UK. | ## Direct debits in the UK A direct debit is an instruction from your user authorizing a counterparty to collect funds from their business account. Your users can authorize direct debits to make single or recurring payments. In the UK, Adyen supports direct debits using the Bankers' Automated Clearing System (BACS). The following diagram shows how Adyen accepts direct debits through BACS. [![](/user/pages/docs/07.business-accounts/24.accept-direct-debits-uk/direct-debit-flow.svg)](/user/pages/docs/07.business-accounts/24.accept-direct-debits-uk/direct-debit-flow.svg) As shown in the diagram, direct debits through BACS work as follows: 1. The counterparty makes a request to collect funds from your user's business account. If this is a recurring payment, the request is made on the frequency authorized by your user. 2. The payment service provider of the counterparty submits the collection request to BACS. 3. BACS sends the collection request to Adyen. 4. Adyen validates that the business account: * Is active and has the required capability for accepting direct debits. * Has an approved [mandate](#mandates-for-direct-debits) linked to it. * Has enough available balance for the direct debit. If these requirements are fulfilled, Adyen approves the collection request. Otherwise, Adyen rejects the direct debit. 5. Adyen notifies your server about the funds collection. 6. Adyen sends a confirmation and the collected funds to BACS. 7. BACS sends the collected funds to the payment service provider of the counterparty. ## Mandates for direct debits A mandate is an authorization from your user that allows a counterparty to perform direct debits on the user's account. The mandate includes information provided by your user, which the counterparty uses to prove the authorization. The information in the mandate includes, for example: * Your user's business account details. * An authorization statement from your user. * Your user's signature or digital confirmation. ## How a mandate is created The following diagram shows the process for mandate creation. [![](/user/pages/docs/07.business-accounts/24.accept-direct-debits-uk/mandate-creation.svg)](/user/pages/docs/07.business-accounts/24.accept-direct-debits-uk/mandate-creation.svg) As shown in the diagram, the process for mandate creation is as follows: 1. Your user shares with the counterparty the information required to create the mandate. 2. The counterparty submits the mandate information to their payment service provider. 3. The payment service provider submits the mandate information to BACS. 4. BACS submits a request to Adyen for creating a mandate. 5. Adyen validates that the business account is active and has the required capability for accepting direct debits.\ If these conditions are fulfilled, Adyen approves the mandate. 6. Adyen notifies your server about the creation of the mandate. 7. Adyen sends a notification of confirmation to BACS. 8. BACS sends a notification of confirmation to the payment service provider of the counterparty. ## Amending or canceling a mandate Your user can [amend a mandate](/business-accounts/accept-direct-debits-uk/manage-mandates-uk#amend-a-mandate) at any moment. By amending the mandate, your user can change the business account that they use for direct debits. For example, consider a user that opens a second business account in your platform, exclusively to handle monthly expenses. Instead of creating a new mandate, your user can amend the ID of the business account. Your user can also [cancel a mandate](/business-accounts/accept-direct-debits-uk/manage-mandates-uk#cancel-a-mandate) at any moment. For example, when a user unsubscribes from a service, they can cancel the mandate to stop future direct debits. The following diagram shows the process for amending or canceling a mandate. ![](/user/pages/docs/07.business-accounts/24.accept-direct-debits-uk/mandate-update.svg?decoding=auto\&fetchpriority=auto) As shown in the diagram, the process for amending or canceling a mandate is as follows: 1. The user amends or cancels the mandate through your application. 2. Your application's server makes an API request to Adyen. 3. Adyen submits the updated mandate information to BACS. 4. BACS sends the updated mandate information to the payment service provider of the counterparty. 5. The payment service provider validates the information and amends or cancels the mandate. 6. The payment service provider notifies the counterparty about the update. 7. The payment service provider sends a notification of confirmation to BACS. 8. BACS sends a notification of confirmation to Adyen. 9. Adyen notifies your server about the update to the mandate. ## Next steps [Manage UK mandates](/business-accounts/accept-direct-debits-uk/manage-mandates-uk) [Learn about the API requests for managing mandates for direct debits in the UK.](/business-accounts/accept-direct-debits-uk/manage-mandates-uk) --- # Source: https://docs.adyen.com/business-accounts/account-structure-resources.md Section: Business accounts Title: Account structure Description: Understand account structures to design an integration that suits your business needs. --- title: "Account structure" description: "Understand account structures to design an integration that suits your business needs." url: "https://docs.adyen.com/business-accounts/account-structure-resources" source_url: "https://docs.adyen.com/business-accounts/account-structure-resources.md" canonical: "https://docs.adyen.com/business-accounts/account-structure-resources" last_modified: "2021-11-03T13:15:00+01:00" language: "en" --- # Account structure Understand account structures to design an integration that suits your business needs. [View source](/business-accounts/account-structure-resources.md) Before you start building your integration, you need to understand the account structure of Adyen business accounts as well as the general [account structure of Adyen for Platforms](/platforms/account-structure-resources). ## Adyen for Platforms structure Adyen business accounts are usually used with an Adyen for Platforms integration. With Adyen for Platforms, your merchant accounts are connected to your **balance platform**. The balance platform is an accounting system that manages the flow of funds within your business. You must have a separate balance platform for each region in which you acquire payments. In your **balance platform**, you can: * [Onboard users](/business-accounts/onboard-users) of your platform and [request capabilities](/business-accounts/manage-account-holders#request-capability) for them. * [Authenticate your account holders](/business-accounts/implement-sca). * [Send funds to third parties](/business-accounts/send-funds). * [Receive funds from third parties](/business-accounts/receive-funds). * [Integrate with the Adyen Open Banking Platform](/business-accounts/open-banking) To enable your users to use business accounts, you must create the following resources for them: * **Account holder**: specifies what your user can do in your platform, for example, receive fund transfers to their balance account and payouts to their verified transfer instrument (bank account). An account holder must be linked to your user's balance account and [main legal entity](/platforms/account-structure-resources/legal-entity-management). * **Balance account**: holds the funds of your user. All financial activities in your platform, such as paying out to a bank account, happen through balance accounts. If your user is using an Adyen business account, you must create two balance accounts for them: one to hold their funds, and one to link to their business account (payment instrument). ## Structure with business accounts Business accounts allow you to make business-related transfers to third parties using Adyen-issued bank accounts (business accounts). When you start using business accounts, we create the following resource in your balance platform: * **paymentInstrument** (business account): an externally-facing resource for interacting with funds on the associated balance account. Creating a payment instrument generates an account number. Each balance account can have only one payment instrument of type **bankAccount**. Here are two examples of a setup: * Example 1: an account holder with one balance account linked to a payment instrument of type **bankAccount**. * Example 2: an account holder with two balance accounts, each linked to a respective payment instrument of type **bankAccount**. ![](/user/pages/docs/07.business-accounts/02.account-structure-resources/business-bank-accounts.svg?decoding=auto\&fetchpriority=auto) --- # Source: https://docs.adyen.com/business-accounts/account-structure-resources/legal-entity-management.md Section: Business accounts Title: Legal entity management Description: Understand legal entities, their importance in the verification process and place in your account structure. --- title: "Legal entity management" description: "Understand legal entities, their importance in the verification process and place in your account structure." url: "https://docs.adyen.com/business-accounts/account-structure-resources/legal-entity-management" source_url: "https://docs.adyen.com/business-accounts/account-structure-resources/legal-entity-management.md" canonical: "https://docs.adyen.com/business-accounts/account-structure-resources/legal-entity-management" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Legal entity management Understand legal entities, their importance in the verification process and place in your account structure. [View source](/business-accounts/account-structure-resources/legal-entity-management.md) As required by payment industry regulations, Adyen must verify the users of your balance platform before you can process payments, pay out their funds, and offer financial products to them. To verify your users, you must create legal entities and associated resources. When you create these resources, you provide Adyen with the [information we require to verify your users](/business-accounts/verification-requirements). ### Resources You must create the following resources for your users: * **Legal entity**: contains information about your user, for example, the legal name, address, and tax information of the organization. Adyen uses this information to perform verification checks as required by payment industry regulations. * **Transfer instrument**: your user's verified bank account where they can receive payouts. * **Supporting document**: a document that allows us to verify the information provided about your user's legal entity or transfer instrument. You can use the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) to manage these resources. The following diagram shows how the resources are connected. ![](/user/pages/docs/07.business-accounts/02.account-structure-resources/03.legal-entity-management/lem_structure_platform.svg?decoding=auto\&fetchpriority=auto) --- # Source: https://docs.adyen.com/business-accounts/account-structure-resources/platform-account-structure.md Section: Business accounts Title: Account structure with business accounts Description: Understand how business accounts can be connected to your platform account. --- title: "Account structure with business accounts" description: "Understand how business accounts can be connected to your platform account." url: "https://docs.adyen.com/business-accounts/account-structure-resources/platform-account-structure" source_url: "https://docs.adyen.com/business-accounts/account-structure-resources/platform-account-structure.md" canonical: "https://docs.adyen.com/business-accounts/account-structure-resources/platform-account-structure" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Account structure with business accounts Understand how business accounts can be connected to your platform account. [View source](/business-accounts/account-structure-resources/platform-account-structure.md) To make your platform more flexible and improve your users' experience, you can offer business accounts to your users. ## Account structure To comply with payment scheme regulations, you must have a balance platform and merchant account in [each region that you are registered and wish to process transactions](/platforms#acquiring-regions). For example, you have a large food delivery company called **Food delivery**, where your users are delivery drivers and restaurants. You want to create **business accounts** for the restaurants to pay their suppliers and partners. You can classify resources based on whether they belong to your platform or to your user(s). ### Resources belonging to your platform * A company account (**FoodDeliveryLLC**), that represents your business entity. * Three merchant accounts, organized by country/region, to manage payment methods available in their area: * **FoodDelivery\_NL** * **FoodDelivery\_DE** * **FoodDelivery\_BE** * Two balance platforms, one for each region in which you acquire payments (**EU** and **US**). * **FoodDelivery\_EU** * **FoodDelivery\_US** * A liable account holder for your platform, and a liable balance account to hold your platform's funds. * A legal entity in each acquiring region, containing information about your platform. ### Resources belonging to each user * One or more stores tied to the respective merchant accounts (based on country of operation), representing your user's restaurant locations: * **Restaurant\_AMS** * **Restaurant\_BER** * **Restaurant\_BRU** * At least one account holder for each country your user operates in, defining their transfer capabilities. * For each account holder, at least one balance account with a defined base currency, to hold your user's funds. * For each account holder, one or more balance accounts to link to your user's business accounts (payment instruments). If your user has multiple business accounts, you can link them all to the same balance account. However, that balance account must be separate from the balance account that holds your user's funds. * For each balance account, a [transfer instrument (verified bank account)](/business-accounts/account-structure-resources/legal-entity-management) to pay out that account's funds. * A legal entity in each country your user operates in, containing information about their business. This information is needed for the required verification checks (KYC). * A business line in each country your user operates in, containing information about their industry. In this case, it is food and delivery services. * A payment instrument, whose transactions are processed using the funds in your user's balance account: * A **business account** for each restaurant, that they can use to pay their suppliers and partners. ### Diagram The following diagram shows how these resources are connected. [![](/user/pages/docs/07.business-accounts/02.account-structure-resources/01.platform-account-structure/business-accounts-afp.svg)](/user/pages/docs/07.business-accounts/02.account-structure-resources/01.platform-account-structure/business-accounts-afp.svg) --- # Source: https://docs.adyen.com/business-accounts/aisp.md Section: Business accounts Title: Get account holder information Description: Learn how to consume our dedicated AISP endpoints for getting account information. --- title: "Get account holder information" description: "Learn how to consume our dedicated AISP endpoints for getting account information." url: "https://docs.adyen.com/business-accounts/aisp" source_url: "https://docs.adyen.com/business-accounts/aisp.md" canonical: "https://docs.adyen.com/business-accounts/aisp" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Get account holder information Learn how to consume our dedicated AISP endpoints for getting account information. [View source](/business-accounts/aisp.md) As part of the open banking framework for Account Information Service Providers (AISPs), Adyen provides endpoints to retrieve the account information on behalf of account holders who have given their consent. This page explains how you, as a third-party AISP, use the `/accounts` endpoint to: * [Get all the accounts of an account holder](#all-accounts) * [Get account details](#account-details) * [Get account balances](#account-balances) * [Get account transactions](#account-transactions) ## Requirements | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Setup steps** | Before you begin, you must:- Complete the [Adyen onboarding steps](/business-accounts/open-banking#onboard-with-adyen). - Have your [access token](/business-accounts/oauth-flow#get-an-access-token) for the Adyen business account. - Have the [consent ID](/business-accounts/oauth-flow#create-a-consent) related to the consent that the account holder gave you. | | | | ## Get all accounts of an account holder To get a list of all Adyen business accounts associated with an account holder: 1. Make a GET `/accounts` request. In the request header, make sure to add the `consent_id` related to the account. **Get all accounts by consent ID** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/aisp/v1/accounts' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Consent_Id: {consent-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. Check the response for the list of accounts associated with an account holder and the details about each account. The response is an array of accounts, where each array item contains the following fields: | Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `resourceId` | A string that represents the ID of the account. | | `ownerName` | Name of the legal account owner. | | `iban` | IBAN of an account. | | `currencyCode` | The three-character [ISO currency code](/development-resources/currency-codes/). | | `product` | Product name of the bank for this account, proprietary definition. | | `status` | The account status. | | `_links` | Links to the account, which can be directly used for retrieving account information from this dedicated account, such as balances and/or transactions. | ```json { "accounts": [ { "resourceId": "S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw", "ownerName": "ADYEN NV", "iban": "NL91ABNA0417164300", "currencyCode": "EUR", "product": "BankAccountNumber", "status": "Active", "_links": { "balances": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw/balances" }, "transactions": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw/transactions" } } } ] } ``` ## Get account details To get detailed information for a specific account identified by its `resourceId`: 1. Make a GET `/accounts/{resourceId}` request, where `resourceId` is the identification of the account that you received in the GET `/accounts` response. In the request header, make sure to add the `consent_id` related to the account. **Get account details** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/aisp/v1/accounts/{resourceId}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Consent_Id: {consent-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. The response of the request may look like this: ```json { "resourceId": "S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw", "ownerName": "Simon Hopper", "iban": "NL91ABNA0417164300", "currencyCode": "EUR", "product": "BankAccountNumber", "status": "Active", "_links": { "balances": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw/balances" }, "transactions": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw/transactions" } } } ``` ## Get account balances To get balance information for a specific account identified by its `resourceId`: 1. Make a GET `/accounts/{resourceId}/balances` request, where `resourceId` is the identification of the account that you received in the GET `/accounts` response. In the request header, make sure to add the `consent_id` related to the account. **Get account balances** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/aisp/v1/accounts/{resourceId}/balances' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Consent_Id: {consent-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. Check the response for details about the account's IBAN, currency, and a list of balances, each detailing the balance type and amount. The response contains the following fields: | Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `balanceType` | Possible values are:- **authorised**: Funds held for pending transactions, this amount is blocked and unavailable for other uses. - **closingBooked**: Balance of the account at the end of the pre-agreed account reporting period. - **expected**: Balance composed of booked entries and pending items known at the time of calculation. - **openingBooked**: Book balance of the account at the beginning of the account reporting period. - **interimAvailable**: Available balance calculated in the course of the account servicer's business day. - **interimBooked**: Balance calculated in the course of the account servicer's business day, at the time specified. - **forwardAvailable**: Forward available balance of money that is at the disposal of the account owner on the date specified. - **nonInvoiced**: Not yet invoiced, for card accounts only. | | `balanceAmount` | The amount and currency of the total available amount. | ```json { "account": { "iban": "NL91ABNA0417164300", "currency": "EUR" }, "balances": [ { "balanceType": "authorised", "balanceAmount": { "amount": "23.49", "currency": "EUR" } }, { "balanceType": "expected", "balanceAmount": { "amount": "24.24", "currency": "EUR" } } ] } ``` ## Get account transactions To get transaction information for a specific account identified by its `resourceId`: 1. Make a GET `/accounts/{resourceId}/transactions` request with the following query parameters, where `resourceId` is the identification of the account that you received in the GET `/accounts` response. In the request header, make sure to add the `consent_id` related to the account. | Query Parameter | Required | Description | | --------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `bookingStatus` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The status of the transaction. Possible values:- **booked**: Transactions settled. - **pending**: Transactions in process. - **both**: Transactions that are both booked and in a pending state. * . | | `dateFrom` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies a starting date or timestamp for filtering data. Must be a valid ISO format, such as yyyy-mm-dd. | | `dateTo` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies an ending date or timestamp for filtering data. Must be a valid ISO format, such as yyyy-mm-dd. | | `pageSize` | | Specifies the maximum number of records that should be included in the API response. The range is from 1 to 50. Default value is 1. | **Get account transactions** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/v1/accounts/{resourceId}/transactions?bookingStatus=booked&dateFrom=2020-01-01&pageSize={account-transactions-page-size}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Consent_Id: {consent-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. Check the response for details about the account's IBAN, currency, and a list of transactions. The response is an array of transactions, each detailing booking date, transaction amount, and creditor information. If consent has been granted for balances, you will also see an array of balances with details. At the end of the response you will see links, to manage the length we implement pagination. These links can be the previous and next pages, as well as direct links to account details. ```json { "account": { "iban": "NL91ABNA0417164300", "currency": "EUR" }, "balances": [ { "balanceType": "expected", "balanceAmount": { "amount": "24.24", "currency": "EUR" } }, { "balanceType": "authorised", "balanceAmount": { "amount": "23.49", "currency": "EUR" } } ], "transactions": { "booked": [ { "transactionId": "EVJN4227K22322295J23J33BN52T4MEUR", "bookingDate": "2023-06-13T11:37:01", "valueDate": "2023-06-13T11:37:01", "transactionAmount": { "amount": "-10.01", "currency": "EUR" }, "creditorName": "Joe Doe", "creditorAccount": { "iban": "NL57INGB4654188101", "currency": "EUR" } }, { "transactionId": "EVJN4227K22322295J23H5XBMJ765REUR", "bookingDate": "2023-06-13T11:25:18", "valueDate": "2023-06-13T11:25:17", "transactionAmount": { "amount": "-11.50", "currency": "EUR" }, "creditorName": "Joe Doe", "creditorAccount": { "iban": "NL57INGB4654188101", "currency": "EUR" } } ] }, "_links": { "next": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw/transactions?bookingStatus=booked&dateFrom=2023-06-10&dateTo=2023-08-01&pageSize=2&cursor=S2B-c2RFJCtoKWxAV11JQmZ9QFx33KH5ubVlwRj02K0ZtRzMgYWQkJVslRXpDdVtwby9GaDQkUEdAdTIsOkZlRXZNU187PyZBOU533UjZHM0hrW018TzN8Om0zemN4MGtrTVYuMkcsL0BzNzo" }, "account": { "href": "/obeu/aisp/v1/accounts/S3B-QyYjNjZ0OyI33Kn86KilYIUx0TVtuOw" } } } ``` ## See also * [Initiate payments](/business-accounts/pisp) * [Confirm funds](/business-accounts/piisp) --- # Source: https://docs.adyen.com/business-accounts/business-account-statement.md Section: Business accounts Title: Account statements for business accounts Description: Automate reconciliation and provide your users with transaction reports. --- title: "Account statements for business accounts" description: "Automate reconciliation and provide your users with transaction reports." url: "https://docs.adyen.com/business-accounts/business-account-statement" source_url: "https://docs.adyen.com/business-accounts/business-account-statement.md" canonical: "https://docs.adyen.com/business-accounts/business-account-statement" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Account statements for business accounts Automate reconciliation and provide your users with transaction reports. [View source](/business-accounts/business-account-statement.md) Adyen provides account statements in the industry-standard CAMT.053 format, which is part of the [ISO 20022](https://www.iso20022.org/) financial messaging standard. CAMT.053 uses structured codes to classify the type and status of each transaction. This ensures consistency and interoperability across financial institutions. Account statements summarize the financial activity in a business account for a specific period, such as a day or a month. You can use these auditable statements to reconcile balances and provide detailed transaction reports to your users. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration that supports [business accounts](/business-accounts/). | | **[API credentials](/development-resources/api-credentials/)** | Generate an API key for **Report user** for the balance platform. Your API credential must have the following role:- **Bank\_Download ReportsRole** | | **[Webhooks](/development-resources/webhooks)** | Your server must be able to receive and accept webhooks. You must subscribe to the [balancePlatform.report.created](https://docs.adyen.com/api-explorer/report-webhooks/latest/post/balancePlatform.report.created) webhook. | | **Setup steps** | Reach out to your Adyen contact to:- Enable the feature on your balance platform. - Configure your [account statement settings](#account-statement-settings). | ### Account statement settings When you contact Adyen to enable the feature, you can customize the following statement configurations: | Feature | Required | Description | Options | | --------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- | | **Timeframe** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Sets the reporting frequency. | Daily, monthly, or both | | **[BAI codes](#bai-codes)** | | Enables Bank Administration Institute codes for standardized transaction classification. | Enabled or disabled | | **Summary** | | Includes a [transaction summary](#transaction-summary-stmttxssummry) block for an overview of totals. | Included or excluded | | **Date format** | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Defines which date is used for transactions in the statement. | Value date or booking date | ## Download an account statement Adyen automatically generates account statements. When a statement is ready: 1. Adyen sends a [balancePlatform.report.created](https://docs.adyen.com/api-explorer/report-webhooks/latest/post/balancePlatform.report.created) webhook message to your configured endpoint in the [Customer Area](https://ca-test.adyen.com/). In the body of the webhook, note the following fields: * `balanceAccount`: An object that contains information about the balance account that the account statement is for. * `fileName`: The name of the file that corresponds to this account statement. * `downloadUrl`: The URL from where you must download the account statement. **Example of an account statement webhook** ```json { "type": "balancePlatform.report.created", "environment": "live", "data": { "balancePlatform": "YOUR_BALANCE_PLATFORM", "id": "CAMT053_BA00000000000000000000001_20260101000000_20260101235959_EUR.xml", "creationDate": "2026-01-02T00:59:59+01:00", "fileName": "CAMT053_BA00000000000000000000001_20260101000000_20260101235959_EUR.xml", "downloadUrl": "https://balanceplatform-live.adyen.com/balanceplatform/reportDownload/statements/v1/balanceaccount/BA00000000000000000000001/CAMT053_BA00000000000000000000001_20260101000000_20260101235959_EUR.xml", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account" } }, "timestamp": "2026-01-02T00:59:59+01:00" } ``` 2. Download the account statement by making a GET request to the URL included in the `downloadUrl` field. In the request, you can use the `-o` flag to specify a custom name for the downloaded file. **Example request to download an account statement** ```bash curl -X GET "https://balanceplatform-api-test.adyen.com/balanceplatform/reportDownload/statements/v1/balanceaccount/BA00000000000000000000001/statement-2026-03-01.xml" \ -H "X-API-Key: REPORT_USER_API_KEY" \ -H "Content-Type: application/xml" \ -o {LOCAL_FILE_NAME}.xml ``` *** ## Account statement elements Adyen provides account statements in ISO 20022 CAMT.053 format. All CAMT.053 statements have the same XML hierarchical structure. The high-level hierarchy structure is the following: * BankToCustomerStatement (BkToCstmrStmt) * GroupHeader (GrpHdr) * Statement (Stmt) * Account (Acct) * Balance (Bal) * Entry (Ntry) * Transaction summary (TxsSummry) * EntryDetails (NtryDtls) * TransactionDetails (TxDtls) Each element in the hierarchy contains nested child elements. The following sections explain the most relevant child elements within each parent element. ** #### Group header block (GrpHdr) Metadata for the entire statement message. Includes general information about the statement and its intended recipient. | Tag | Element name | Description | | --------------- | ---------------------- | ------------------------------------------------------------------------------ | | `` | Group Header | Container for metadata regarding the statement message and recipient. | | `` | Message Identification | Adyen-generated unique ID of the statement message. | | `` | Creation Date Time | The date and time the statement was generated. | | `` | Message Recipient | Contains information regarding the legal entity of the balance platform owner. | | `` | Name | The name of the legal entity receiving the statement. | | `` | Postal Address | The mailing address of the message recipient. | | `` | Post Code | The postal code of the recipient. | | `` | Town Name | The city or town of the recipient. | | `` | Country Sub Division | The state, province, or region of the recipient. | | `` | Country | The ISO country code of the recipient. | | `` | Address Line | Up to 7 lines of additional address information. | | `` | Message Pagination | Used if the statement is split across multiple files. | | `` | Page Number | The current page number of the message. | | `` | Last Page Indicator | Indicates whether this is the final page of the statement. | | `` | Additional Information | General additional information regarding the message. | ** #### Statement block (Stmt) Each `Stmt` represents one account and one currency. A file can contain multiple statements. | Tag | Element name | Description | | ---------------- | -------------------------------- | ------------------------------------------------------ | | `` | Statement | Main container for a specific account statement | | `` | Identification | Unique identifier for the statement | | `` | Creation Date Time | The date and time this statement block was created | | `` | From To Date | Container for the reporting period of the statement | | `` | From Date Time | The start date and time of the reporting period | | `` | To Date Time | The end date and time of the reporting period | | `` | Copy Duplicate Indicator | Indicates whether the statement is a copy or duplicate | | `` | Reporting Source | Identifies the reporting source | | `` | Additional Statement Information | Additional details about the statement | ** #### Account details (Stmt/Acct) Identifies the account the statement applies to. The `` element contains details about the business account for which the statement was generated. | Tag | Element name | Description | | ------------ | -------------- | ------------------------------------------------------------------------------------------------- | | `` | Account | Container for account details. | | `` | Identification | Unique identifier for the account. | | `` | IBAN | Adyen-issued IBAN, used if the account is a SEPA bank account. | | `` | Other | Container for non-IBAN identifiers. | | `` | Identification | Account number for US or UK bank accounts, or the Adyen business account ID for generic accounts. | | `` | Currency | The three-letter ISO currency code of the account. | ** #### Balances (Stmt/Bal) Reports balances at specific points in time. Multiple `` elements can appear within an account statement. Depending on the configuration, either booked balances (`OPBD`, `CLBD`) or value balances (`OPAV`, `CLAV`) are reported. The statement reports balances as either booked or available: * **Booked** balances show transactions that have been fully processed and recorded on the account. * **Available** balances show the funds you can use, after taking into account pending debits or credits. | Tag | Element name | Description | | ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Balance | Container for opening and closing balance data. | | `` | Type | Container for the balance type. | | `` | Code Or Proprietary | Indicates whether a standard ISO code or a proprietary code is used. | | `` | Code | Balance type code. Common values include:* `OPBD` – Opening booked balance * `OPAV` – Opening available balance * `CLBD` – Closing booked balance * `CLAV` – Closing available balance | | `` | Amount | The balance amount, including the currency as an attribute, for example, `Ccy="EUR"`. | | `` | Credit Debit Indicator | Indicates whether the balance is credit (`CRDT`) or debit (`DBIT`). | | `
` | Date | Container for the balance timestamp. | | `` | Date Time | The date and time the balance was recorded. | | `` | Availability | Information about the availability of the balance. | ** #### Entries (Stmt/Ntry) Each `` represents a booked debit or credit that affects the account balance. Multiple entries can appear in a statement. | Tag | Element name | Description | | ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | | `` | Entry | Container for a single transaction booked on the account. | | `` | Entry Reference | Adyen-generated unique identifier for the transaction. | | `` | Amount | The transaction amount, including the currency as an attribute (for example, `Ccy="EUR"`). | | `` | Credit Debit Indicator | Indicates whether the entry is credit (`CRDT`) or debit (`DBIT`). | | `` | Status | The status of the entry, typically `BOOK` (Booked). | | `` | Booking Date | Container for the date the transaction was booked. | | `` (under ``) | Date Time | The date and time the transaction was booked. | | `` | Value Date | Container for the date the funds become available or are debited. | | `` (under ``) | Date Time | The date and time of the value date. | | `` | Account Servicer Reference | Adyen-generated identifier for the transaction. | | `` | [Bank Transaction Code](#bank-transaction-code) | Structured classification (domain, family, sub-family) for the transaction. | | `` | Domain | The broad business area, such as `PMNT` (Payments). | | `` | Family | Defines the transaction type within a domain, such as `ICDT` (Issued Credit Transfer). | | `` | Sub Family Code | Granular classification, such as `BOOK` (Internal book transfer). | | `` | Entry Details | Container for detailed transaction information. | ** #### Transaction summary (Stmt/TxsSummry) Provides aggregated totals for the reporting period. The `` element summarizes entries by [Bank Transaction Code (ISO 20022)](#bank-transaction-code), showing: * The number of entries. * The total amount (``) per code. Each Bank Transaction Code can also be mapped to a corresponding [BAI2 code](#bai-codes-optional). | Tag | Element name | Description | | ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `` | Transaction summary | Container for transaction totals. | | `` | Total entries | Total number and amount of entries. | | `` | Total credit entries | Total number and amount of credit entries. | | `` | Total debit entries | Total number and amount of debit entries. | | `` | Total entries per bank transaction code | Totals grouped by bank transaction code. | | `` | Number of entries | Number of entries. | | `` | Sum | Total gross amount. | | `` | Net total entry amount | Net total amount. | | `` | Credit/debit indicator | Indicates whether totals represent credits or debits. | | `` | Bank transaction code | Structured transaction classification (domain, family, and sub-family) defined by [ISO 20022](#bank-transaction-code). | ** #### Transaction details (Stmt/Ntry/NtryDtls/TxDtls) The `` element contains information about a transfer associated with the transaction, including: * Your transfer reference. * The Adyen-generated transfer ID. These identifiers help you reconcile activity on the business account. | Tag | Element name | Description | | --------------- | -------------------------- | --------------------------------------------------------------------------------------- | | `` | Transaction Details | Container for detailed information about the transfer related to the transaction. | | `` | References | Container for identifiers associated with the transfer. | | `` | Account Servicer Reference | Adyen-generated identifier for the transfer (corresponds to the `id` field in the API). | | `` | Instruction Identification | Your reference for the transfer. | | `` | End To End Identification | Reference intended for the beneficiary. | | `` | Transaction Identification | Adyen-generated internal reference used for tracing and debugging. | | `` | Remittance Information | Container for remittance-related data. | | `` | Unstructured | Description, memo, or remittance information for the transfer. | ### Example account statement The following example shows a CAMT.053 account statement file. It includes the group header, account details, an opening booked balance (`OPBD`), and an entry with its corresponding transaction details. **Example account statement** ```xml CAMT05300000000000000000001 2026-03-02T08:15:00+01:00 0-EUR NL02ABNA0123456789 EUR ADYXNL2AXXX OPBD 00.10 CRDT
2026-03-01T00:00:00+01:00
EVJN422XC22422295HQCGFZ2QX3X3QEUR 1.00 BOOK 2026-03-01T10:23:09+01:00 Fund - AdyenCA-CAD-XXXXX - Fmyc 4IZQR05YMKIOIQP0 ``` ### ISO 20022 Bank Transaction Code In a CAMT.053 account statement, each transaction entry includes a Bank Transaction Code (``) element. This element classifies the transaction using the ISO 20022 Bank Transaction Code structure. This structure helps you identify the type and direction of the transaction. ISO 20022 uses a three-tier classification system to define Bank Transaction Codes. This hierarchy moves from broad business areas to granular transaction details: 1. **Domain**: The broad functional area. On Adyen's balance platform, this is always **PMNT** (Payments). 2. **Family**: The category of transaction, for example, **RCDT** for Received Credit/Inbound. 3. **SubFamily**: The specific outcome or method, for example, **ACDT** for Account Deposit. The following table explains the codes: | Category | Code | Transfer name | Direction | Transfer outcome | Used for | | -------------- | -------- | ------------------- | --------- | ---------------- | ------------------------------------------------------------------ | | **Domain** | **PMNT** | Payment | N/A | N/A | All payment-related transaction types | | **Family** | **RRCT** | Received Real-Time | Inbound | N/A | Instant or real-time inbound transfers | | | **RCDT** | Received Credit | Inbound | N/A | Inbound ACH, wire, same-day, cross-border, and internal transfers | | | **IRCT** | Initiated Real-Time | Outbound | N/A | Instant or real-time outbound transfers | | | **ICDT** | Initiated Credit | Outbound | N/A | Outbound ACH, wire, same-day, cross-border, and internal transfers | | **Sub-family** | **ACDT** | Account Deposit | N/A | Success | Standard deposits, such as instant or ACH | | | **SDVA** | Same-Day Value | N/A | Success | Fast or same-day transfers | | | **PRCT** | Priority Credit | N/A | Success | Urgent or wire transfers | | | **XBCT** | Cross-border Credit | N/A | Success | Transfers via correspondent banks | | | **BOOK** | Booked Transfer | N/A | Success | Internal (book) transfers | | | **OTHR** | Other | N/A | Success | General or uncategorised transfers | | **Any** | **RRTN** | Return | N/A | Reversal | Returns, reversals, or rejections | The following example shows how an inbound wire transfer is represented in ISO 20022. The `` element combines the **Domain**, **Family**, and **SubFamily** codes to classify the transaction: **Example of an ISO 20022 Bank Transaction Code** ```xml PMNT RCDT PRCT ``` ### (Optional) Codes from the Bank Administration Institute (BAI) To enable BAI codes for your account statements, reach out to your Adyen contact. BAI codes are a set of classification codes defined by the [Bank Administration Institute](https://www.bai.org). These codes are used in the BAI2 file format and are common across banking systems for categorizing transactions. When enabled, BAI codes are included in the CAMT.053 statement to provide additional transaction classification alongside ISO 20022 codes. This mapping focuses on the series used for active payment and transfer methods: * **100 to 200 series**: Successful inbound deposits and credit returns. * **400 to 500 series**: Successful outbound disbursements and debit reversals. #### Credits (inbound) Transactions where funds are deposited into the business account. All returned credit transactions use the same ISO 20022 return code (`RRTN`) per transfer family. | Transfer type | Bank Transaction Code—booked transaction | Bank Transaction Code—returned transaction | BAI2—booked transaction | BAI2—returned transaction | | ------------------------ | ---------------------------------------- | ------------------------------------------ | ----------------------- | ------------------------- | | **Instant or real-time** | **PMNT/RRCT/ACDT** | **PMNT/RRCT/RRTN** | **158** | **496** | | **ACH** | **PMNT/RCDT/ACDT** | **PMNT/RCDT/RRTN** | **165** | **557** | | **Fast or same-day** | **PMNT/RCDT/SDVA** | **PMNT/RCDT/RRTN** | **165** | **557** | | **Urgent or wire** | **PMNT/RCDT/PRCT** | **PMNT/RCDT/RRTN** | **195** | **496** | | **Cross-border** | **PMNT/RCDT/XBCT** | **PMNT/RCDT/RRTN** | **208** | **496** | | **Internal or book** | **PMNT/RCDT/BOOK** | **PMNT/RCDT/RRTN** | **206** | **496** | | **Other** | **PMNT/RCDT/OTHR** | **PMNT/RCDT/RRTN** | **195** | **496** | #### Debits (outbound) Transactions where funds are sent or withdrawn from the business account. All returned debit transactions use the same ISO 20022 return code (`RRTN`) per transfer family. | Transfer type | Bank Transaction Code—booked transaction | Bank Transaction Code—returned transaction | BAI2—booked transaction | BAI2—returned transaction | | ------------------------ | ---------------------------------------- | ------------------------------------------ | ----------------------- | ------------------------- | | **Instant or real-time** | **PMNT/IRCT/ACDT** | **PMNT/IRCT/RRTN** | **458** | **196** | | **Regular or ACH** | **PMNT/ICDT/ACDT** | **PMNT/ICDT/RRTN** | **466** | **168** | | **Fast or same-day** | **PMNT/ICDT/SDVA** | **PMNT/ICDT/RRTN** | **466** | **168** | | **Urgent or wire** | **PMNT/ICDT/PRCT** | **PMNT/ICDT/RRTN** | **495** | **196** | | **Cross-border** | **PMNT/ICDT/XBCT** | **PMNT/ICDT/RRTN** | **508** | **196** | | **Internal or book** | **PMNT/ICDT/BOOK** | **PMNT/ICDT/RRTN** | **506** | **196** | | **General or other** | **PMNT/ICDT/OTHR** | **PMNT/ICDT/RRTN** | **495** | **266** | ## See also * [Reports and fee types](/platforms/reports-and-fees/) * [Compliance requirements for account statements](/platforms/compliance-financial-products/account-statements/) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines.md Section: Business accounts Title: Compliance guidelines for business accounts Description: Learn how to remain compliant with financial regulations when offering business accounts in your marketplace or platform. --- title: "Compliance guidelines for business accounts" description: "Learn how to remain compliant with financial regulations when offering business accounts in your marketplace or platform." url: "https://docs.adyen.com/business-accounts/compliance-guidelines" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Compliance guidelines for business accounts Learn how to remain compliant with financial regulations when offering business accounts in your marketplace or platform. [View source](/business-accounts/compliance-guidelines.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. To offer business accounts to users in your platform, you must follow Adyen's guidelines for topics like your user interface (UI), communications, and reporting. These guidelines are required for your platform and Adyen to remain compliant with financial regulations. Further guidance on the Compliance Guidelines is available in Adyen’s [Platform Compliance Guidelines Best Practices and Templates](/business-accounts/compliance-financial-products/platform-compliance.pdf). Specifically, this document provides guidance on the following: * the form of materials that may be accepted to demonstrate compliance with each section of the Guidelines; * best practices for drafting policies that are required under the Guidelines; and * best practices for handling customer complaints, along with suggested templates to be used for responding to complaints. ## Overview of guidelines The table in this section shows an overview of the compliance requirements that your platform must meet for each topic. After your financial product offering is approved by Adyen, before publishing and distributing any new materials related to financial products, you **must** (where pre-approval of the relevant material is required under the Compliance Guidelines): 1. Submit the materials to Adyen for review and pre-approval by sending an email to **merchantkyc\@adyen.com**. 2. Update the materials to reflect any further changes requested by Adyen (if applicable). 3. Re-submit the materials to Adyen for approval (if applicable). Note that you also are required to provide materials for review: * Annually * For periodic review * Upon Adyen's request Select the links in the table for detailed guidelines for each topic. | Topic | Compliance requirements | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[User application and interface](/business-accounts/compliance-guidelines/user-interface)** | Your user application and interface must:- Not present your platform as a bank. - Enable your users to request business accounts. - Collect KYC information and send it to Adyen. - Show and provide access to the required agreements and user terms. - Collect consent from your users. - Show and provide access to the accepted agreements and user terms. - Enable your users to view and access information regarding their business accounts. - For UK and EU users: display a notice indicating whether a successful confirmation/verification of payee has been completed after the user has entered the payment details. - For EU users: provide a Depositor Information Sheet. | | **[Account statements](/business-accounts/compliance-guidelines/account-statements)** | Your account statements must:- Follow templates approved by Adyen. - Contain all the data provided by Adyen. - Include the contact information of your business. | | **[Marketing and communication with users](/business-accounts/compliance-financial-products/marketing-user-communication)** | Ensure that this material:- Follows Adyen's guidelines for collateral materials. - Is approved by Adyen. - Discloses Adyen as the provider of business accounts. | | **[Customer service and support](/business-accounts/compliance-financial-products/customer-service-support)** | Provide to your users:- Guidance on how to get support. - First and second lines of support. - Access to support channels. - Critical support 24/7 for specific notifications. | | **[Customer complaints](/business-accounts/compliance-financial-products/customer-complaints)** | When receiving a complaint, you must:- Acknowledge and respond to the complaint. - Escalate security, legal, and regulatory complaints to Adyen. - Submit quarterly complaint reports to Adyen. | | **[Pricing and eligibility](/business-accounts/compliance-financial-products/pricing-and-eligibility)** | You must submit the following to Adyen for approval:- The fees and/or credits for your users. - Your eligibility criteria to allow users to request business accounts. | | **[Notification and reporting to Adyen](/business-accounts/compliance-financial-products/reporting-to-adyen)** | You must submit the following reports to Adyen:- Daily fraud report. - Daily card status report. - Quarterly complaint report. | | **[Keeping records](/business-accounts/compliance-financial-products/keeping-records)** | For at least five years after the termination of the financial product offering, keep copies of the following:- Customer consent to open accounts. - User interface. - Account statements. - Marketing materials and user communications. | | **[Registration as intermediary in France](/business-accounts/compliance-financial-products/french-intermediary)** | When you are registered in France and offer business accounts to French users, you must:- Register as an intermediary. - Add a disclaimer on your website. - Renew your registration as an intermediary every year. | --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/account-statements.md Section: Business accounts Title: Account statements for business accounts Description: Learn about the requirements for account statements that you present to your users for business accounts. --- title: "Account statements for business accounts" description: "Learn about the requirements for account statements that you present to your users for business accounts." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/account-statements" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/account-statements.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/account-statements" last_modified: "2023-12-12T12:09:00+01:00" language: "en" --- # Account statements for business accounts Learn about the requirements for account statements that you present to your users for business accounts. [View source](/business-accounts/compliance-guidelines/account-statements.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. When offering business accounts or issuing cards to your users, you need to provide them with account statements. Providing account statements allows users to periodically check their transaction history. In these account statements, you must include the data provided by Adyen through its APIs. This data must remain **unchanged**, and your account statement template must be approved by Adyen. The requirements for account statements differ depending on the country or region and the specific product involved. ## Adyen Bank Accounts (EU & US) **Items in bold** are not provided through Adyen's APIs and must be provided by the platform. * Bank Information * The EU countries: * Bank name: Adyen N.V. * Bank Address: Simon Carmiggeltstraat 6, 1011DJ, Amsterdam * Bank Website: [www.adyen.com](http://www.adyen.com) * Statement that Adyen N.V. is the financial institution issuing the bank account. * The US: * Bank name: SF Branch contact information * Bank Address: 505 Brannan St, San Francisco, CA, 94107, United States * Bank Website: [www.adyen.com](http://www.adyen.com) * Statement that the SF Branch is the financial institution issuing the bank account. * **Platform Information** * **Platform name** * **Platform Support service number and email** * **Platform Website** * **Platform contact information for inquiries and customer support** * Account type: Business Bank Account * Account holder details: * Name: Legal Entity name, Doing Business As (DBA) name, as defined in the Legal Entity or Legal Arrangement Screening Procedure * Address: as defined in the Legal Entity or Legal Arrangement Screening Procedure * Account Details: * Account type: Checking Account (consistent with openAPI specification) * Account number: last four digits * Currency code(s): EUR, USD * IBAN (EU) * BIC (EU) * Period of Statement - by date and number of days in statement cycle -(for example, Oct 1, 2024 - October 31, 2024). * Account Balance: * Begin Balance * End Balance * Transaction data: Provide the amount, date, transaction type (ACH, IAT, debit, wire transfer, withdrawal), name of payer/payee and balance after each: * Every debit or withdrawal during the time period * Every credit/deposit during the time period * Every fee assessed * Total debits/withdrawals during the time period * Total credits/deposits during the time period * For interest-bearing accounts: Annual Percentage Yield Earned (APYE), Statement cycle number of days, dollar amount of interest earned in the statement cycle * Reference to Depositor Information Sheet (EU) * Bank disclosures, as detailed in Adyen’s Disclosure and Consent Procedure; * For EU: Deposit Guarantee Scheme (“DGS”)\ *“In the EU, Adyen N.V. is registered with the Dutch deposit guarantee scheme register and eligible funds up to EUR 100,000 are legally protected by the Dutch deposit guarantee scheme.”* * For US: FDIC insurance\ *“Adyen Business Bank Accounts in the U.S. are not insured by the FDIC and are not guaranteed by the Federal Government. If Adyen places deposits in a cash sweep program utilizing FDIC-insured depository institutions, such deposits may be covered by FDIC insurance up to applicable limits in accordance with the FDIC rules, including those relevant to the aggregation of multiple accounts."* ## Adyen Business Accounts (UK) * Payment Service Provider (PSP) Information * PSP name: Adyen N.V. * PSP Address: 12-13 Wells Mews, London W1T 3HE * PSP Website: [www.adyen.com](http://www.adyen.com) * Statement that Adyen N.V. is the financial institution issuing the business account. * **Platform Information** * **Platform name** * **Platform Support service number/email** * **Platform Website** * **Platform contact information for inquiries and customer support** * Account type: Business Account * Account holder details: * Name: Legal Entity name, Doing Business As (DBA) name, as defined in the Legal Entity or Legal Arrangement Screening Procedure * Address: as defined in the Legal Entity or Legal Arrangement Screening Procedure * Account Details: * Account type: E-money Account * Account number: last four digits * Currency code(s): GBP, EUR * Period of Statement - by date and number of days in statement cycle. For example, Oct 1, 2024 - October 31, 2024. * Account Balance: * Begin Balance * End Balance * Transaction data: Provide the amount, date, transaction type (debit, wire transfer, withdrawal), name of payor/payee and balance after each: * Every debit or withdrawal during the time period * Every credit/deposit during the time period * Every fee assessed * Total debits/withdrawals during the time period * Total credits/deposits during the time period * PSP disclosures, as detailed in Adyen’s Disclosure and Consent Procedure Disclosure for the Financial Services Compensation Scheme is not required. This is not applicable to UK Business Accounts as this information is already confirmed by the account holder when onboarding. ## Adyen Issuing Before issuing cards to its users, platforms must submit a sample account statement to Adyen for review. The account statement must include the following information: * Card Issuer Information * Card Issuer name: Adyen N.V. (For US: San Francisco Branch) * Card Issuer Address: * Card Issuer Website: [www.adyen.com](http://www.adyen.com) * Statement that Adyen N.V. (For US: San Francisco Branch) is the financial institution issuing the cards and related account(s).\*\* * **Platform Information** * **Platform name** * **Platform Support service number/email** * **Platform Website** * Account holder Details: * Name: Legal Entity name, Doing Business As (DBA) name, as defined in the Legal Entity- or, Legal Arrangement Screening Procedure * Address: as defined in the Legal Entity or Legal Arrangement Screening Procedure * Account Details: * Account type: 1. Prepaid program: 1. E-money Account (EU/UK); 2. General Use Reloadable Prepaid Card (US) 2. Debit program: 1. Deposit Account (EU) 2. E-money Account (UK) 3. Demand Deposit Account 3. Credit Program: 1. Charge Card Account (EU, UK, US) * Card number: last four digits (PAN) * Currency code(s): EUR, USD, GBP * Period of Statement - by date and number of days in statement cycle. For example, Oct 1, 2024 - October 31, 2024. * Account Balance: * Begin Balance * End Balance * Transaction data: Provide the amount, date, transaction type (debit, wire transfer, withdrawal), name of payor/payee and balance after each: * Every debit or withdrawal during the time period * Every credit/deposit during the time period * Every fee assessed * Total debits/withdrawals during the time period * Total credits/deposits during the time period For EU, downloadable statements are not required if all of the above information is displayed in the user interface. For UK, it must be possible for the user to download a statement containing the above information in a PDF or another durable format. ## Required data The following table shows the data that you must include in account statements for business accounts. You can get most of this data through Adyen's APIs. Any data that you get from Adyen's APIs must remain unchanged. | Required information | Required for EU | Required for US | Required for UK | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Information about the financial institution:- Name: Adyen N.V. - Address: Simon Carmiggeltstraat 6, 1011DJ, Amsterdam - Website: [www.adyen.com](https://www.adyen.com/) - Statement that Adyen N.V. is the financial institution issuing the business account. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Information about the financial institution:- Name: Adyen N.V. San Francisco branch - Address: 505 Brannan Street, San Francisco, CA 94107 - Website: [www.adyen.com](https://www.adyen.com/) - Statement that Adyen N.V. San Francisco branch is the financial institution issuing the business account. | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Information about the payment service provider (PSP):- PSP name: Adyen N.V. London branch - PSP address: 12-13 Wells Mews, London W1T 3HE - PSP website: [www.adyen.com](https://www.adyen.com/) - Statement that Adyen N.V. London branch is the financial institution issuing the business account. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | **Not provided by Adyen's APIs** Information about your platform:- Name of your platform - Website of platform - Your platform's contact information and customer support lines. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Account type: Business bank account | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Account type: Business account | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Account holder details:- Name as defined in the Legal Entity or Legal Arrangement Screening Procedure. If applicable, use the following format: * \[Name of your legal entity], Doing Business As \[Name of your platform] - Address as defined in the Legal Entity or Legal Arrangement Screening Procedure | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Account details:- Account type: Checking account - Account number: the last four digits - Currency code: EUR - IBAN - BIC | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Account details:- Account type: Checking account - Account number: the last four digits - Currency code: USD | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Account details:- Account type: E-money account - Account number: the last four digits - Currency code: GBP, EUR | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | The period of the statement, specifying the date of the beginning and the end of the period. For example: October 1, 2024 - October 31, 2024 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | The account balance, specifying the balance at the beginning and the end of the period of the statement. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Transaction data for every transaction within the period of the statement:- Amount - Date - Transaction type - Name of the payer or payee - Balance after the transaction - Any fees that Adyen charges your users for a specific transaction. For example: currency conversion fees. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Total debits or withdrawals during the period of the statement. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Total credits or deposits during the period of the statement. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For interest-bearing accounts, include:- The Annual Percentage Yield Earned (APYE) - The number of days in the period of the statement - The amount of interest earned in the period of the statement. This amount must be specified in the currency of the account. - Name of the payer or payee - Balance after the transaction | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | A reference to the [Depositor Information Sheet](/business-accounts/compliance-financial-products/user-interface#depositor-info-sheet). | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Provide the disclosure for the **Deposit Guarantee Scheme (DGS)**: > In the EU, Adyen N.V. is registered with the Dutch deposit guarantee scheme register and eligible funds up to EUR 100,000 are legally protected by the Dutch deposit guarantee scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Disclose that the account is not FDIC insured, using the approved statement below: > Adyen Business Bank Accounts in the United States are not insured by the FDIC and are not guaranteed by the Federal Government. If Adyen places deposits in a cash sweep program utilizing FDIC-insured depository institutions, such deposits may be covered by FDIC insurance up to applicable limits in accordance with the FDIC rules, including those relevant to the aggregation of multiple accounts. | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ## Review by Adyen After you have created a template for your account statements, you must submit it to Adyen for review and approval. --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/customer-complaints.md Section: Business accounts Title: Customer complaints and escalation Description: Learn about types of customer complaints and proper complaint handling. --- title: "Customer complaints and escalation" description: "Learn about types of customer complaints and proper complaint handling." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-complaints" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-complaints.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-complaints" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Customer complaints and escalation Learn about types of customer complaints and proper complaint handling. [View source](/business-accounts/compliance-guidelines/customer-complaints.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. Proper handling of complaints is mandatory for all platform that offer one of Adyen's financial services. *Complaints* refer to an expression of dissatisfaction about Adyen products, services, terms, communications, or actions, where a response or resolution is explicitly or implicitly expected. Even if the customer does not use the word "complaint" in their communication, if the content of the inquiry expresses dissatisfaction with Adyen products or services, the inquiry should be treated as a complaint. It is the substance of the complainant’s feedback and not the tone or format, that determines if the inquiry is a complaint. This definition is inclusive of complaints communicated in any form, written or oral, and through any channel. A complaint is not a customer service question or inquiry, either verbal or written, that includes a request to the platform for information and assistance related to a process or product. For example, the following **are not** complaints: * Requests to change an address. * Inquiries regarding account details. * Questions about a product's availability in specific locations or requests for general information. * Questions related to technical assistance (such as error messages) or issues interacting with Adyen's platform or a third-party platform integrated with Adyen's services. * Requests for a refund of fees or a chargeback. However, if any customer request concerning any of the above matters alleges unfair treatment or expresses dissatisfaction, this should be treated as a complaint. ## Complaint handling process The platform must operate a complaints handling process that includes the following features. ### Access to support Provide users with an easily identifiable and accessible way to submit support inquiries. ### Complaint identification Identify complaints that are received through all available customer support channels. The platform can require complaints to be submitted through a complaints form. A link to this form should be provided in customer support channels where a user has raised a complaint. * **Guidance on complaint handling**. Provide clear guidance and information to users on how the platform will work to resolve complaints. This includes: * The platform's acknowledgement of the complaint (within the timelines listed under complaint resolution timelines). * Communicating the ultimate deadline for resolving the complaint (within the timelines listed under complaint resolution timelines). * Providing regular updates on the investigation of the complaint. If the complaint has not been resolved within the specified timelines, the platform must notify the customer of the anticipated timeframe for resolving the complaint. * The platform must investigate the Complaint and take all actions deemed necessary to address the complaint in a timely manner, in accordance with the timelines as outlined under complaint resolution timelines. * For any regulatory and legal complaints, Adyen will be involved in the resolution and work with the platform. * **Complaint resolution timelines**. Adyen expects the platform to: * Acknowledge all user complaints within 5 business days. * Resolve them within 10 business days from the complaint submission date. * Notify users if complaints will take longer than 10 business days to resolve. ### Recordkeeping The platform must maintain records relating to all support inquiries (and complaints) responses for five years from the date of the termination of the Adyen Service and the user's account closure, unless the platform’s own data retention requirements stipulate a longer time period. Such records must be maintained in a durable and accessible format, for example, in the form of a log. ## When to escalate a complaint to Adyen There are several categories of complaints relevant to Adyen’s services that the platform may encounter being in the first and second line support for the user. | Category of compliants | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | General complaints | Operational complaints related to customer service, product functionality, account management, transactions. | | Security complaints | Complaints from the user related, but not limited to:- Fraud - Identity theft - Criminal activity, such as robbery or theft - Unauthorized access to a customer’s information - Account takeover | | Regulatory and legal complaints | Complaints that involve legal or regulatory matters. | Security and Regulatory/Legal complaints must be reported to Adyen within one to two working days. Adyen will then work with a platform to resolve the complaint. The platform is required to forward user complaints to Adyen so Adyen can assist the platform with preparing the response in the following situations: * The platform has received and acknowledged the complaint and is unable to substantively resolve the issue without Adyen's input. * Adyen has a responsibility to handle and resolve the complaint in accordance with the criteria outlined for each type of compliant in the following table. ## Types of complaints to escalate | Type of complaint | Example | Who responds to the user | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Legal** | * Legal action addressed to Adyen, for example, court or official documentation where Adyen is a defendant. * Complaint accompanying threat of legal action, for example, complaint submitted alongside court documentation. * Complaint about official court orders, for example, seizure order or other court orders. | **Adyen** responds to legal actions directly. The **platform** handles the complaint aspect and resolution unless Adyen's input is required for a substantive response. | | **Data Privacy** | - Official court orders against the customer, for example, seizure order or subpoena addressed to Adyen. - Breach of GDPR/UK GDPR, for example, mishandled data, shared data, or requests for access/deletion. - Threat to refer Adyen to a regulator or court for breaching privacy rules. | **Adyen** (responds to the user, Court/FIU, or regulator directly). | | **Regulatory** | * Complaint accompanying regulatory referral (complaint to be considered alongside the referral). * Regulatory referral, for example, customer indicates they will refer Adyen to a regulator/ombudsman. | **Adyen** responds to the regulator/ombudsman. The **platform** handles resolution unless Adyen's input is required for a substantive response. | | **Financial Crime** | - Victim of a financial crime (relevant for bank accounts/cards for refunding/blocking, or chargebacks). - Blocked funds, for example, customer states they are unable to access funds or account has been blocked. | The **platform** performs handling and resolution. | | **Technical Issues** | * Issues caused by an Adyen API or component that requires technical support. | The **platform** performs handling and resolution. | ## Escalation procedure 1. Provide the information as soon as possible, but no later than two business days after the complaint is received. 2. Adyen will forward the complaint to the relevant team based on the criteria in the table. 3. If Adyen needs further information from the platform to prepare a response, the platform must provide a response when Adyen within two business days. 4. Once Adyen has prepared the final response, this will be sent to the platform, and the platform must provide this response to the user in line with the complaints handling timelines in the Compliance Guidelines. ## For Customers in the UK & Ireland ### Receipt and acknowledgement The platform’s complaints resolution process must contain the following additional elements: * Within 5 working days of the platform concluding its investigation of the complaint, the platform must notify the user of * The decision in relation to the complaint (including the reasons for the decision). * If applicable, the terms of any offer or settlement made. * That the user may be entitled to refer their complaint to the relevant ombudsman if they are not satisfied with the platform’s conclusion; and again provide the above contact details of the relevant ombudsman. * The platform’s acknowledgement of the complaint must state that the user may be entitled to raise the complaint with the relevant financial ombudsman in the user’s jurisdiction (in Ireland, the Financial Services and Pensions Ombudsman and in the UK, the Financial Ombudsman Service) where the user is not satisfied with the platform’s or Adyen’s final response to the complaint or the complaint has not been resolved within 15 working days. * The platform must provide the user making the complaint with a point of contact in relation to the complaint. * The acknowledgement should also include the contact details of the relevant ombudsman, as follows: **Ireland**\ *Address: Lincoln House, Lincoln Place, Dublin 2, D02 VH29.\ Phone: +353 1 567 7000\ Email: info\@fspo.ie* **UK**\ *Website: \ Online complaint form: \ Mail: The Financial Ombudsman Service Exchange Tower, London, E14 9SR\ Phone: 0800 023 4 567 (free), 0300 123 9 123, weekdays from 8:00am–5:00pm (GMT). If you are not located in the UK, call +44 20 7964 0500.\ You have 6 months to make a complaint after we send you a final response.* ### Resolution The platform must provide the user making the complaint with regular updates on the investigation of the complaint, at intervals of maximum 15 business days (starting on the date the complaint was received). Where the complaint has not been resolved within 35 working days, the platform must notify the user of the anticipated timeframe for resolving the complaint and that the customer may be entitled to refer the complaint to the relevant ombudsman (providing again the above contact details for the relevant ombudsman). ### Escalation If Adyen receives any complaint directly from BACS and requires your platform to provide any information for Adyen to respond to the complaint, your platform must provide this within two business days. Adyen does not consider that any complaints about the payment services made available to users should be forwarded to Adyen under the DISP 1.7 complaints and forwarding rules. ## See also * [Customer service and support](/business-accounts/compliance-guidelines/customer-service-support) * [Notification and reporting to Adyen](/business-accounts/compliance-guidelines/reporting-to-adyen) * [Overview of compliance guidelines](/business-accounts/compliance-guidelines) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/customer-service-support.md Section: Business accounts Title: Customer service and support Description: Learn about the compliance guidelines you need to follow when offering support to your users. --- title: "Customer service and support" description: "Learn about the compliance guidelines you need to follow when offering support to your users." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-service-support" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-service-support.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/customer-service-support" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Customer service and support Learn about the compliance guidelines you need to follow when offering support to your users. [View source](/business-accounts/compliance-guidelines/customer-service-support.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. The platform is responsible for providing first and second line support to customers. The platform must provide a way for customers to submit support requests and provide resolution support. The platform also serves as Adyen’s point of contact for any communications from customers. ## Customer service essentials The following table outlines the responsibilities of the platform when providing support to customers. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Support teams** | The platform is responsible for the following:- Provide first line support: A general help desk that takes more information, offers simple solutions, and determines if an issue requires escalation to someone with more expertise. - Provide second line support: A team with more technical knowledge who can assist with more complex issues. - Ensure that both the first and the second line support services work effectively: * Customer helplines shall be sufficiently resourced and capable of dealing with unexpected surges in demand of customer support. * Tickets shall be prioritized based on the severity of the issue, ensuring a timely response. * Where relevant, customers shall be provided with a unique case number for their support query. The status of a support query shall be clear for a customer at all times. * In case of expected delays in response (for example, due to an unexpected surge in customer support queries), customers must be informed accordingly. * The information provided by a user needs to be registered properly, allowing for central access by subsequent customer service advisors. | | **Support guidance** | The platform must provide its customers with clear guidance and information on how to receive support:- Guidance should allow customers to easily find key information, with clear signposting to the platform's customer support channels. - Phone system, menus, webpages or web chats must be easy to navigate. | | **Support channels** | The platform must have multiple support channels available and communicate these channels clearly towards their customers:- Support needs to be offered by multiple channels, allowing for live-support (for example, phone, emails, social media channels, video call, in-office support, call-back service), in accordance with the needs of their user base. - If support is offered digitally or though a chatbot, human touch points are required wherever complex needs are identified or if so requested by a merchant. - A reasonable level of support must be provided through channels in the event of an issue arising with their services (for example, IT outage, temporary works or a cyber-attack). - The platform's support channel cannot include any sludge practices or barriers, hindering the ability of customers to raise a support query or file a complaint. - Support channels must be available and free of charge, regardless of the channel used to provide support. | | **Critical support** | The platform must enable 24/7 ability to raise any query or notification by customers about (possible) unauthorized use, fraud, loss or theft of personal security credentials and/or card. | | **Training** | The platform should properly train and equip their front-line staff to deliver good customer support, including training to identify risks of vulnerability. See [Considerations for vulnerable customers](#vulnerable) below for more information. | | **Monitoring** | The platform are required to monitor and assess the quality of support they provide to ensure that customers receive the support they need, and to limit the risk of systematic issues that create unreasonable barriers or costs for customers. | | **Record-keeping** | The platform are requested to maintain records relating to all support queries and responses thereto for five years from the date of the termination of the Adyen Service and the user's account closure, unless the platform's own data retention requirements stipulate a longer time period. | ## Considerations for vulnerable customers (UK and Ireland) Adyen requires platforms to ensure that any customers in vulnerable circumstances receive reasonable assistance and support that they require to engage with Adyen’s financial services. Vulnerable customers are *"customers who, due to their personal circumstances, are especially susceptible to harm, particularly when a firm is not acting with appropriate levels of care"*. Adyen is required to ensure that platforms receive appropriate training for dealing with vulnerable customers. This is to ensure that necessary staff within platforms can understand and recognise vulnerable customers and respond to their needs. For further information refer to [Identifying vulnerable users](/business-accounts/compliance-financial-products/vulnerable-users#identifying-vulnerable-users). The platform must ensure that this information is provided to and understood by all staff members specified. In addition to the general requirements outlined above, customer service and support systems should also incorporate the following requirements to ensure that necessary assistance is provided to vulnerable user: * Communication systems should enable and encourage customers to specify if they have particular needs or require special assistance, and to share/update information in their own time and at their own pace. This should be done with a popup or other prominent notice on the platform's user interface, stating that customers should contact the platform if they require any special assistance. The notice must contain a link, phone number, and email address for the standard support channels. * Digital channels should be complemented with human touchpoints wherever this need is identified. * Customer support channels and information relevant to these should be compatible with assistive technologies such as text-to-speech applications. --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/eu-depositor-info-sheet.md Section: Business accounts Title: EU depositor information sheet Description: Information about deposit protection in the EU. --- title: "EU depositor information sheet" description: "Information about deposit protection in the EU." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/eu-depositor-info-sheet" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/eu-depositor-info-sheet.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/eu-depositor-info-sheet" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # EU depositor information sheet Information about deposit protection in the EU. [View source](/business-accounts/compliance-guidelines/eu-depositor-info-sheet.md) ## Basic information about deposit protection | | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Deposits in Adyen N.V. are protected by: | Dutch statutory Deposit Guarantee Scheme (See (1) below) | | Limit of protection: | EUR 100 000 per depositor per credit institution (See (2) below) The following trademarks are part of your credit Institution: Adyen | | If you have more deposits at the same credit institution: | All your deposits at the same credit institution are ‘aggregated’ and the total is subject to the limit of EUR 100 000 | | If you have a joint account with other person(s): | The limit of EUR 100 000 applies to each depositor separately (See (3) below) | | Reimbursement period in case of credit institution’s failure: | 10 working days (See (4) below) | | Currency of reimbursement: | Euro | | Contact: | De Nederlandsche Bank N.V. PO Box 98, 1000 AB Amsterdam Visiting address: Spaklerweg 1, 1096 BA Amsterdam Telephone (from Monday to Friday between 9:00 and 15:30): from the Netherlands: 0800 020 1068 From abroad: +31 20 524 91 11 Email: | | More information: | Go to , select English as the language, and search for ‘Deposit Guarantee Scheme’. | | **Additional Information:** | | | Other important information: In general, all retail depositors and businesses are covered by Deposit Guarantee Schemes. Exceptions for certain deposits are stated on the website of the responsible Deposit Guarantee Scheme. Your credit institution will also inform you on request whether certain products are covered or not. If deposits are covered, the credit institution shall also confirm this on the statement of account. | | | **Notes** | | | (1) Scheme responsible for the protection of your deposit: Your deposit is covered by the Dutch statutory Deposit Guarantee Scheme. If insolvency of your credit institution should occur, your deposits would be repaid up to EUR 100.000. | | | (2) General limit of protection: If a deposit is unavailable because a credit institution is unable to meet its financial obligations, depositors are repaid by the Dutch Deposit Guarantee Scheme. This repayment covers at maximum EUR 100.000 per credit institution. This means that all deposits at the same credit institution are added up in order to determine the coverage level. If, for instance, a depositor holds a savings account with EUR 90.000 and a current account with EUR 20.000, the depositor will only be repaid EUR 100.000. This method will also be applied if a credit institution operates under different trademarks. Adyen N.V. also trades under Adyen. This means that all deposits with one or more of these trademarks are in total covered up to EUR 100.000. | | | (3) Limit of joint account protection: In case of joint accounts, the limit of EUR 100 000 applies to each depositor. However, deposits in an account to which two or more persons are entitled as members of a business partnership, association or grouping of a similar nature, without legal personality, are aggregated and treated as if made by a single depositor for the purpose of calculating the limit of EUR 100 000. More information can be obtained under go to ‘English’ section, search for ‘Deposit Guarantee Scheme’. | | | (4) Reimbursement: The responsible Deposit Guarantee Scheme is the Dutch statutory Deposit Guarantee Scheme which is executed by De Nederlandsche Bank N.V. (Dutch Central Bank) (DNB); PO box 98 1000 AB Amsterdam; visiting address: Spaklerweg 1, 1096 BA Amsterdam; telephone (from Monday to Friday between 9:00 and 15:30): from the Netherlands: 0800-0201068, from abroad: + 31 20 524 91 11; email: ; website: [www.dnb.nl](http://www.dnb.nl) go to ‘English’ section, search for ‘Deposit Guarantee Scheme’. It will repay your deposits (up to EUR 100 000) within 10 (ten) working days at the latest. If you have not been repaid within these deadlines, you should contact the Deposit Guarantee Scheme since the time to claim reimbursement may be barred after a certain time limit. The reimbursement period will gradually be brought back to 7 (seven) working days. During this transition period, the Dutch Central Bank (DNB) can upon request award you an appropriate amount to cover basic needs. For more information, go to , select English as the language, and search for ‘Deposit Guarantee Scheme’. | | --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/foreign-exchange-fees.md Section: Business accounts Title: Foreign exchange fees Description: Learn about foreign exchange fees. --- title: "Foreign exchange fees" description: "Learn about foreign exchange fees." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/foreign-exchange-fees" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/foreign-exchange-fees.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/foreign-exchange-fees" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Foreign exchange fees Learn about foreign exchange fees. [View source](/business-accounts/compliance-guidelines/foreign-exchange-fees.md) If a user's transaction consists of any type of conversion between currencies, they must be clearly presented with the FX rate and additional fees at the point they make the transaction and in any statements covering the relevant period. Below are examples of good practices when presenting fees. ## Variable Fee This shows an example where a reference rate and a variable fee are charged. | | | | --------------------------------- | ------- | | You pay | £100.00 | | Variable fee | 3% | | Total fees | £3.00 | | You convert | £97.00 | | Exchange rate (1 GBP to 1.30 USD) | 1.30 | | They receive | $126.10 | ## Fixed Fee The following table is an example of a fixed fee presentation: | | | | -------------------------------------- | ------- | | You pay | £100.00 | | Firm exchange rate (1 GBP to 1.26 USD) | 1.26 | | Fixed fee | £0.00 | | Total fees added | £3.00 | | They receive | £126.10 | ### Additional fixed fee examples: | | | | --------------------------------- | --------- | | You convert | £100.00 | | Fixed fee | £5.00 | | You pay | £95.00 | | Exchange rate (1 GBP to 1.30 USD) | 1.30 | | They receive | \\$123.50 | | | | | --------------------------------- | --------- | | You convert | £100.00 | | Fixed fee | £5.00 | | You pay | £105.00 | | Exchange rate (1 GBP to 1.30 USD) | 1.30 | | They receive | \\$130.00 | The Adyen exchange rate includes a 3% markup charge. In both examples, the customer is clearly informed about the fee structure, and can clearly identify how the total cost of the transaction was calculated. The customer can clearly identify the **rate of the conversion**, the **value of the conversion**, and the **fee** that they have paid. ## Third Party Fees The following examples show how third-party fees are presented. | | | | --------------------------------- | ------- | | You convert | £100.00 | | Fixed fee | £5.00 | | Pay all fees? | £15.00 | | You pay | £120.00 | | Exchange rate (1 GBP to 1.30 USD) | 1.30 | | They receive | $130.00 | This includes Adyen's fee for the transaction. When you make an international payment, intermediary banks may deduct fees from the amount you send. Selecting "Pay all fees?" allows you to pay a flat upfront fee which guarantees that the recipient receives the intended amount. | | | | --------------------------------- | ------- | | You convert | £100.00 | | Fixed fee | £5.00 | | You pay | £105.00 | | Exchange rate (1 GBP to 1.30 USD) | 1.30 | | They receive | $130.00 | This includes Adyen's fee for the transaction. The recipient will pay any fees charged by third parties, which will be deducted from this amount. This example above where **intermediary fees** may also be charged and deducted from the total amount the customer intends to send. The above information is based on guidance provided by the [UK Financial Conduct Authority](https://www.fca.org.uk/publications/good-and-poor-practice/consumer-duty-international-payment-pricing-transparency-good-poor-practice) but applies to platforms in all regions. --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/french-intermediary.md Section: Business accounts Title: Registration as an intermediary in France Description: To be allowed to offer Capital in France, register as an intermediary with ORIAS. --- title: "Registration as an intermediary in France" description: "To be allowed to offer Capital in France, register as an intermediary with ORIAS." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/french-intermediary" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/french-intermediary.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/french-intermediary" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Registration as an intermediary in France To be allowed to offer Capital in France, register as an intermediary with ORIAS. [View source](/business-accounts/compliance-guidelines/french-intermediary.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. The French Monetary and Financial Code (CMF) regards your platform as an **intermediary** if the following is true: * You offer Adyen business accounts to French users.\ **and** * Your platform is incorporated and registered in France. In France, intermediation is a regulated activity that requires you to register with [ORIAS](https://www.orias.fr), the organization that is in charge of the French registry of intermediaries in insurance, banking, and finance. ## Requirements Before you begin, take into account the following requirements and limitations. | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | | **Integration type** | An [Adyen for Platforms](/adyen-for-platforms-model/) integration offering financial products. | | **Limitations** | Only applies when registered in France and offering financial products to French users. | ## Proof of professional capacity When you register with ORIAS, you are required to provide proof of professional capacity of at least one of your organization's directors. The director's proof of professional capacity must show experience, a diploma, or training relevant for the financial products to be offered. This proof can be either of the following: * A certificate of employment showing at least six months of experience in the past two years with providing similar financial products. * A relevant diploma. This can be: * A diploma under the Répertoire National des Certifications Professionnelles (RNCP) category NSF 122, 128, 313, or 314, levels 7 to 5. * A diploma from a business school registered with the French Ministry of Education. * A similar foreign diploma officially recognized by [France Education International](https://www.france-education-international.fr). * A certificate from an [approved training organization](https://www.data.gouv.fr/fr/datasets/liste-publique-des-organismes-de-formation-l-6351-7-1-du-code-du-travail/) showing at least 20 hours of training in the financial products to be offered. The director should not be subject to: * The convictions mentioned in Article L500-1 of the CMF: convictions for a felony, a sentence of imprisonment, or a suspended imprisonment of six months or more for certain listed offences. * Disciplinary sanctions no. 3 or 7 mentioned in Article L612-41 of the CMF: a prohibition to carry out certain intermediation operations and any other limitations in the exercise of this activity, or a prohibition of intermediation activities. ## Register as an intermediary To be allowed to offer Adyen business accounts, you have to register with ORIAS as a: * **Level I IOBSP intermediary** if your Nomenclature des Activités Françaises (NAF) code is [NAF 64.19 Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/64.19Z) or [NAF 64.92 Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/64.92z) * **Level II IOBSP intermediary** if your NAF code is [NAF 66.22Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/66.22Z) or [NAF 66.19.99](https://www.insee.fr/fr/metadonnees/cpfr21/sousCategorie/66.19.99). * **Level III IOBSP intermediary** if the above NAF codes do not apply. It usually takes less than two months for ORIAS to validate and accept your registration. After your initial registration as an intermediary, you must renew your registration every year before it expires. 1. Gather the following documents (in PDF, JPG, or PNG format), which you will need to upload to ORIAS in a later step: * Proof of registration with the French Chamber of Commerce. This is referred to as a **kbis extract**. The extract must be less than three months old. * [Proof of professional capacity](#professional-capacity) of at least one of your organization's directors. 2. If you do not have an ORIAS account yet, create an account on the [ORIAS website](https://www.orias.fr/public/enregistrement/index), selecting **Personne morale** and providing the details of one of your organization's directors. 3. Log in to your ORIAS account and proceed as follows: 1. Select the category **Activité IOB** and the subcategory **Mandataire non-exclusif en opérations de banque et en services de paiement**. 2. Select the following: * **Je déclare que l'on ne me confie pas de fonds** to indicate that no funds are entrusted to you. * **Accessoire** to indicate that offering business accounts is not your organization's primary activity. * **Oui**. 3. Provide the kbis extract and the proof of professional capacity of one of your organization's directors. 4. Provide Adyen with your SIREN number and legal name so that Adyen can issue your **Attestation de Mandat** (mandate) and send it to you.\ You can resume the registration process on the ORIAS website when you have received the mandate. 5. Upload your **Attestation de Mandat** to ORIAS. 6. Pay the fees. For questions about the registration you can contact ORIAS directly at . 4. When you receive a confirmation by email that ORIAS has approved your registration, add the following disclaimer on the website where you offer Adyen business accounts: \[YOUR ORGANIZATION], société immatriculée au R.C.S de \[XXXX] sous le numéro \[XXXXX], et inscrit au Registre unique des Intermédiaires en Assurance, Banque et Finance sous le numéro d’immatriculation \[XXXXX] en qualité de Mandataire non exclusif en opérations de banque et en services de paiement. Do not forget to renew your registration every year. ## See also * [Compliance guidelines for Capital](/capital/compliance-guidelines) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/keeping-records.md Section: Business accounts Title: Keeping records Description: Learn about the guidelines for keeping records regarding financial products. --- title: "Keeping records" description: "Learn about the guidelines for keeping records regarding financial products." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/keeping-records" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/keeping-records.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/keeping-records" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Keeping records Learn about the guidelines for keeping records regarding financial products. [View source](/business-accounts/compliance-guidelines/keeping-records.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. While you offer business accounts to your users, your platform must keep detailed records regarding your service. Your platform must keep these service records for at least **five years** after the termination of the business accounts offering (unless your platform's internal data retention requirements indicate a longer timeframe.) ## Types of records | Record type | Examples | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User experience | Screenshots of deployed versions of the financial product, application flow, user dashboard, support pages | | Marketing | All versions of materials described in [Marketing communications](/business-accounts/compliance-financial-products/marketing-user-communication). | | User communications and complaints | Email or website messaging interactions (for example chat or customer support) and documentation related to complaints. Notifications to customers of action taken for loans and charge cards. (UK and IE only)Vulnerable customers: The systems for recording details of customer communications must include the ability to categorise customers as showing signs of vulnerability during an interaction and should include at least the following categorisation options:- **Health**: Physical or mental health conditions that impact a customer's ability to manage their affairs. This could include emotional distress, or any other conditions that means they may require additional support. - **Life Events**: Significant life changes such as bereavement, job loss, or relationship breakdown that can affect resilience and decision-making. - **Resilience**: Low ability to withstand financial or emotional shocks. - **Capability**: Low levels of financial literacy, confidence in managing money, or other relevant skills such as digital literacy. Any communications received from a vulnerable user must be accessible (in accordance with legal requirements) to the staff of the platform responsible for assisting users. | | Statements | Historical statements generated and made available to users | ## See also * [Overview of compliance guidelines](/business-accounts/compliance-guidelines) * [User application and interface](/business-accounts/compliance-guidelines/user-interface) * [Account statements](/business-accounts/compliance-guidelines/account-statements) * [Marketing and communication with users](/business-accounts/compliance-guidelines/marketing-user-communication) * [Customer service and support](/business-accounts/compliance-guidelines/customer-service-support) * [Customer complaints](/business-accounts/compliance-guidelines/customer-complaints) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/marketing-user-communication.md Section: Business accounts Title: Material for marketing and communication with users Description: Learn about the requirements and review process for your collateral material about your Capital offering. --- title: "Material for marketing and communication with users" description: "Learn about the requirements and review process for your collateral material about your Capital offering." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/marketing-user-communication" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/marketing-user-communication.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/marketing-user-communication" last_modified: "2023-12-14T12:09:00+01:00" language: "en" --- # Material for marketing and communication with users Learn about the requirements and review process for your collateral material about your Capital offering. [View source](/business-accounts/compliance-guidelines/marketing-user-communication.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. ### Marketing Materials Collateral material is defined as all communication that the user sees in relation to Adyen's offering through your platform’s interface. We also refer to this communication as *collateral material*. Collateral materials can include, but are not limited to: * Platform web pages, * Platform user interface pages (for example, application flow, customer dashboard, support pages), * Platform marketing communications, * Platform communication to users, * User statements, * Direct mail advertisements, * Other print or media advertisements, * Press or media releases, * Advertisements, * Materials accompanying card distribution(carriers, pin mailers, proprietary packaging) * Physical or Virtual Card Proofs * App store descriptions and screenshots of platforms All collateral material used by the platform must: * Adhere to the general principles listed below for each product offering; and * Include relevant bank disclosures (as detailed in Adyen’s Disclosure and Consent Procedure) for each service offered. For all financial products, all collateral material used by the platform must: * Be reviewed and pre-approved by Adyen before publishing or distributing; * Resubmitted for approval to when changes are made, excluding typographical or grammatical error changes. Changes that do not impact the description or marketing of the Adyen product or service content do not need to be resubmitted for approval. Content can be submitted for use in multiple collateral materials. * Any additional collateral material that the platform wishes to publish following go-live should also be submitted for approval to . ### General Principles #### Communication style * All collateral material must be written in plain language. * Material must be tailored to the target customer, in accordance with their level of sophistication; non-sophisticated customers generally require simpler (jargon-free) communication. * All collateral material should present terms, benefits, limitations, availability and risks of the Service line adequately, accurately, clearly and conspicuously. Collateral materials must not make claims, representations, or statements that are misleading to the target customer. * All representations within the collateral materials should be reasonable and factual. If claims are made that require additional data to support them, source or disclose the additional data. Any research, statistics or claims quoted in collateral materials must be substantiated and refer in the advertisement to the source of the research or statistics, or grounds for the claim, including the date of the research or statistics and any assumptions that have been made based on the research, statistics or claims. * Where used, the collateral material must explain the meaning of any abbreviations or acronyms. * Where more than one financial service is advertised in collateral material, the collateral material must clearly distinguish which service the provided information relates to. #### Testimonials * If using testimonials or endorsements in collateral materials, the testimonial must be a real customer, using the Service they are talking about. The testimonial or endorsement must be attributed to the author of the statement and correctly dated. Permission must be obtained in writing to use the testimonial or endorsement. If any money was paid to the customer for the testimonial or endorsement, a disclaimer must be included stating this fact. * Any comparisons or contrasts in the information provided in collateral material must either be based on verified facts or reasonable assumptions stated within the advertisement. The comparisons or contrasts must be specified in a clear, fair and balanced way and not omit any key information. * The collateral material should include a reference to the Platform’s contact information (i.e., phone number, website address, or email address). #### Vocabulary to avoid * Avoid using exaggerated or unsubstantiated claims or absolute statements that are hard to prove. For example: "all", "never", "always", "fastest", "cheapest", "lightning speed", "prevents all fraud". * Avoid the use of the term "free" if there are charges, costs or fees that may be outlined in user terms. * Avoid using terms such as "pre-approved" or "guaranteed". If using those terms, it must be clear if there are any limitations, conditions, or restrictions on the offer. However, the term "pre-qualified" may be used. * Avoid using terms such as "protected" or "secure". If using those terms, it must be clear if there are any limitations, conditions, or restrictions on the offer. * Materials must not require a consumer credit check or consumer credit report or infer that a consumer credit check is performed in order to grant the product. Forbidden content: * Collateral material must not include language or images that are profane, sexual or political in nature, are offensive, including to racial or religious classes, or language that is defamatory towards other third parties. Format/Layout: * The design and format of all collateral material must not obscure or disguise any key information concerning the service. Key information must always be confirmed in writing. * Any disclosures in the collateral material must be done in the predominant font size, i.e., a font size large enough to read and in a color that visibly contrasts with the background. * Recommended: 8-point font for paper materials; 10-point font for online materials * Key information or disclosures should not be buried in other non-key disclosures or footnotes. Footnotes shall only be used to supplement or elaborate on the key information included in the body text. * Recommended: footnotes should be no more than 2 points smaller than the font size used for the body of the text * All communications should be accessible to users of differing abilities (for example, all websites should be compatible with text-to-speech technology). * Collateral materials may only include a hyperlink linking to information that forms part of the advertisement where the advertisement containing the link specifies the name of the advertised financial service and/or an invitation to discuss the financial service in more detail. In addition, the hyperlink must be displayed prominently and link directly to the additional information on a single webpage. #### Specific disclosures for countries/regions * (UK only) Platforms shall include on their webpage or application a clear explanation on the role of Adyen as provider of the regulated financial service versus the role of the platform. Example below: * "*To facilitate payments and offer financial products, \[Platform] works together with Adyen UK, which is authorised by the Prudential Regulatory Authority and the Financial Conduct Authority.*" * More information on Adyen and its offering can be found in the FCA’s register (firm number [779800](https://register.fca.org.uk/s/firm)) and [Adyen's United Kingdom page](https://www.adyen.com/en_GB/). * (Ireland only): Any webpage on the Platform’s website that relates to a financial service offered in partnership with Adyen, that is accessed from someone based in Ireland, must display the following statement: * "*We work with Adyen N.V. to offer financial services. Adyen N.V., trading as Adyen, is authorised by De Nederlandsche Bank in the Netherlands and is regulated by the Central Bank of Ireland for consumer protection rules.*" ## Product-specific requirements ### Collateral material review principles for Issuing | Representation | EU | UK | US | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Platform’s Card Program Name and network name text the same size | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | (Prepaid Cards Only): Language must not suggest the card is a bank card/bank account card. Note, this requirement **does not apply** to Debit Cards. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | An issuing statement is required to appear anytime the card, payment scheme/network brand marks or logo is portrayed, identified or displayed in any form of collateral. A program can work with Adyen to request a variance from the Schemes. Please refer to each network’s guidelines for approved variances of the below statements. EU - Mastercard: "*This card is issued by Adyen N.V. pursuant to license by Mastercard International.*" - Visa: "*This card is issued by Adyen N.V, pursuant to a license from Visa Europe Limited.*"UK - Mastercard: "*This card is issued by Adyen N.V. London Branch pursuant to license by Mastercard International.*" - Visa: "*This card is issued by Adyen N.V. London Branch, pursuant to a license from Visa Europe Limited.*"US In-House Issuing Programs - Mastercard: "*\[Program name] Mastercard® \[Prepaid Card/Debit Card/Credit Card] is issued by Adyen N.V. pursuant to license by Mastercard International.*" - Visa: "*\[Program name] Visa® \[Prepaid Card/Debit Card/Credit Card] is issued by Adyen N.V. , pursuant to a license from Visa U.S.A. Inc.*" | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For physical and virtual cards, the network standards must be met for required elements, prohibited elements, and card images. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | The use of cards in any marketing material or advertisements must meet network standards and card image standards. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USA PATRIOT Act must be disclosed when an individual’s personal information is collected. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | PREPAID Card Programs: Use language promoting the benefits of the card such as "better than cash", "spend only what you load", "spend only what you have on the card". Avoid using phrases like "better than credit", "no interest", "no debt", "debit card", "credit card". | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For General Purpose Reloadable (GPR) Prepaid Cards Programs: The card must not be marketed or labeled as a gift card or gift certificate, meaning either directly or indirectly offering, advertising or otherwise suggesting the potential use of a general-use prepaid card as a gift for another person. Examples of marketed or labeled as a gift card or gift certificate include: - Using the word "gift" or "present" on a card or accompanying material, including documentation, packaging and promotional displays; - Representing or suggesting that a card can be given to another person, for example, as a "token of appreciation" or a "stocking stuffer," or displaying a congratulatory message on the card or accompanying material; - Incorporating gift-giving or celebratory imagery or motifs, such as a bow, ribbon, wrapped present, candle, or a holiday or congratulatory message, on a card, accompanying documentation, or promotional material. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For Business-Purpose Card Programs: Indicate that the card can be used for "business needs" or "commercial needs" and can not be used for personal, family, or household purposes. Avoid using phrases like "Use card program for anything you want", "personal cards", "use these cards like a payday loan". Do not use consumer use cases in Collateral materials. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Collateral material must truthfully reflect the program scope and specifications agreed upon in the Card Service Agreement. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Any use of the Visa and Mastercard Marks must not degrade, devalue, denigrate, or cause injury or damage to the Marks or the Schemes in any way. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Platform must not use "bank" or "banking" in their website name. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | If the Platform uses "bank" or "banking" in any materials, there must be a disclosure stating that the program is not a bank and the program is provided by Adyen, N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Collateral material review principles for Business Accounts | Representation | EU | UK | US | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Platform must not use "bank" or "banking" in their website name or infer that the Platform itself is the provider of the bank account. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Platform cannot use the word "bank account" but solely "business account" or "e-money account". | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Platform cannot state "open a \[Platform] bank account" or similar language. There must be a disclosure stating that the Platform is not a bank and that the account is a business account provided by Adyen, N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Any FAQ must explain that the accounts are held at: - Adyen, N.V. (EU) - Adyen N.V. London Branch (UK) - Adyen N.V. San Francisco Branch(US) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Provide disclosure that: In the EU, Adyen N.V. is registered with the Dutch deposit guarantee scheme register and eligible funds up to EUR 100,000 are legally protected by the Dutch deposit guarantee scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Provide disclosure that: Business Accounts offered by Adyen N.V. London Branch include issuance of electronic money. Electronic money is not a deposit and therefore not protected by the Financial Services Compensation Scheme. | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Must distinguish that the account is not FDIC Insured using the approved statement below: Adyen Business Bank Accounts in the U.S. are not insured by the FDIC and are not guaranteed by the Federal Government. If Adyen places deposits in a cash sweep program utilizing FDIC insured depository institutions, such deposits may be covered by FDIC insurance up to applicable limits in accordance with the FDIC rules, including those relevant to the aggregation of multiple accounts. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Collateral material Review Principles for Adyen Capital #### Loans | Representation | EU | US | AU | UK | CA | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Disclose that Capital is provided by Adyen N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | | Disclose that Capital is provided by Adyen N.V. London Branch | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Disclose that Capital is provided by Adyen Australia Pty Limited Adyen Capital is provided by Adyen Australia Pty Limited ABN 55 162 682 411. Adyen Capital is offered exclusively for business purposes and not for any personal, domestic or household use. Minimum qualifications and eligibility may change from time to time. Adyen reserves the right to withhold Adyen Capital from users who do not meet minimum qualifications. Please see full terms and conditions. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Include the disclosure: "*Loans are issued by Adyen N.V. San Francisco Branch and subject to credit approval.*" | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | Include disclosure: "*Please note that Loans provided by Adyen do not qualify as regulated credit agreements under the Consumer Credit Act.*" | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Disclose that Capital is provided by Adyen Canada Ltd. | | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Disclose that the rate charged for Capital is fixed. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | #### Merchant Cash Advances (UK only) * Do not misrepresent a cash advance as a loan. * Do not make reference or compare to other loan products or products that have a credit element. * Disclose that Capital is provided by Adyen N.V. London Branch * If a communication names the FCA, PRA or both as the regulator of Adyen, make clear that Merchant Cash Advances are not regulated by the FCA, PRA or both. * Include disclosure: "*Please note that Merchant Cash Advances provided by Adyen do not qualify as regulated credit agreements.*" --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/pricing-and-eligibility.md Section: Business accounts Title: Pricing and eligibility Description: Learn how to disclose prices, fees, and requirements for Capital. --- title: "Pricing and eligibility" description: "Learn how to disclose prices, fees, and requirements for Capital." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/pricing-and-eligibility" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/pricing-and-eligibility.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/pricing-and-eligibility" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Pricing and eligibility Learn how to disclose prices, fees, and requirements for Capital. [View source](/business-accounts/compliance-guidelines/pricing-and-eligibility.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. To offer business accounts to your users, you must clearly explain to them: * [The pricing information of the service](#pricing) * [The eligibility requirements to use the service](#eligibility) ## Pricing In addition to the Adyen supplied agreements, the platform’s terms of service and fee schedule must clearly outline the fees and terms that the platform implements as part of the services program. * (EU and US only) Any increase to user fees charged for an Adyen product must be disclosed to the affected users in writing at least 30 days before the increased fee takes effect. * (UK only) Any increase to user fees charged for an Adyen product must be disclosed to the affected users in writing at least 60 days before the increased fee takes effect. ### Product-specific requirements #### Adyen for Platforms * Disclosure of fees: the platform may charge the user additional fees provided those fees are disclosed to the user in advance of enrollment in the product. * Foreign Exchange (FX): platforms must provide users with a sufficiently clear presentation of costs so that they understand the FX rate and any associated fees both at the point the user confirms they want to convert funds, and in any statement for the period or in a transaction overview in the UI. For additional examples, see the Foreign Exchange Fees section. * Cost and Fee Access: all fees and costs must remain available on request of the user. * (Only for UK) Reasonable Fees: All fees and costs must be reasonable and appropriate. #### Issuing and Bank Accounts * Disclosure of fees: the platform may charge the user additional fees provided those fees are disclosed to the user in advance of enrollment in the product. * Pre-Approval of fees: all fees and costs user is charged by the platform shall be notified to and agreed with Adyen in advance of enrollment in the product. * Cost and Fee Access: all fees and costs must remain available on request of the user. * Reasonable Fees: All fees and costs must be reasonable, appropriate and in line with the actual costs of the platform’s services. #### Business Accounts (EU & UK) * No additional fees for instant payments: the platforms may not impose fees for instant payments which are higher than fees for regular payments. Instant and regular payments must be subject to the same pricing. #### Capital The platform may not charge directly or indirectly additional fees to the user for Adyen Capital. Fees may also not be discounted without prior written approval from Adyen. ## Eligibility In general, the platforms must not be applying additional eligibility criteria for bank accounts, Capital, and Issuing beyond Adyen’s defined requirements. However, if a Platform has additional eligibility requirements for their users to request accounts, Capital or issued cards, those requirements should be submitted to Adyen for review that they have been properly disclosed to the user. Requirements: * Disclosure of requirements: the platform must clearly disclose any platform-specific eligibility requirements to users before offering the product to them. * Reasonable eligibility requirements: Platform specific eligibility requirements must not be discriminatory, unfair, or deceptive. ### Pricing onboarding questionnaire (UK only) In order to assess whether the proposed fees by the platformare reasonable, the platforms are required to respond to the following questions when onboarding | Order for question | Question | | | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | - | - | | 1. | Provide a detailed description of the pricing model and the fees (description + amount) you charge your customer for using your Platform/services. Outline the expected total price to be paid by a customer. This should include a breakdown of any product or feature fees, fixed/variable fees, subscriptions, commissions, service charges, penalty fees, lock-ins or other fees by the customer. | * Adyen for Platforms * Bank Accounts; * Card Issuing; | | | | 2. | Do you charge a specific fee for the payment processing services offered by Adyen? If yes please indicate the amount. | - Adyen for Platforms | | | | 3 | If yes to #3 - Are you charging a blended or interchange fee model? If so, how do you determine which pricing model is offered to whom? (for example, the annual volume is greater than a certain GBP total or by request) | * Adyen for Platforms | | | | 4. | What are the parameters/criteria you base your rate on? What determines where a merchant’s pricing falls within those parameters/criteria? | - Adyen for Platforms | | | | 5. | What is your pricing strategy for Business Accounts? Describe whether you charge for account opening, a monthly account fee, execution of payment transactions, etc. | * Bank Accounts | | | | 6. | What is your pricing strategy for Card Issuing product? Describe whether you charge any fee per card issued, per transaction, etc. | - Card Issuing | | | | 7. | Do you charge any specific fees for foreign exchange services? | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | | 8. | What, if any, discounts, incentives, or promotions, specifically in relation to Adyen's services? | - Adyen for Platforms/li> - Bank Accounts; - Card Issuing | | | | 9. | What, if any, processes do you have in place for reviewing pricing for existing customers? If applicable, please describe the frequency and review process. | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | | 10. | How do you ensure your pricing strategy is fair and transparent? Explain how you internally assess fairness in pricing (e.g., competitive research, customer research/feedback, regulatory caps, A/B-testing,...). | - Adyen for Platforms/li> - Bank Accounts; - Card Issuing | | | | 11. | How do you communicate pricing information to customers to ensure clarity and understanding? Explain the methods used to disclose fees, ensuring customers are fully informed before purchase. Where available, provide copies of such communication. | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | ## See also * [Overview of compliance guidelines](/business-accounts/compliance-financial-products) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/reporting-to-adyen.md Section: Business accounts Title: Notification and reporting to Adyen Description: Learn what situations to notify Adyen of and what reports to submit periodically. --- title: "Notification and reporting to Adyen" description: "Learn what situations to notify Adyen of and what reports to submit periodically." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/reporting-to-adyen" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/reporting-to-adyen.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/reporting-to-adyen" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Notification and reporting to Adyen Learn what situations to notify Adyen of and what reports to submit periodically. [View source](/business-accounts/compliance-guidelines/reporting-to-adyen.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. If your platform offers business accounts, there are specific situations that you must notify Adyen of when they occur. There are also certain reports that you must submit to Adyen. ## When to notify Adyen Platforms must notify Adyen immediately (within 1-2 business days) in the following instances: * The platform receives a Security, Regulatory or Legal Complaint. You must notify Adyen of these complaints, using the [dedicated template](/business-accounts/compliance-guidelines/reporting-to-adyen/Adyen_Complaints_Reporting.xlsx) for complaints reporting. Also see [How to make a complaint](https://www.adyen.com/contact/complaint). * Customer Support Circumstances (these are to be raised through normal Adyen support lines): * The platform, acting reasonably, cannot resolve a user’s request for support. * Any unauthorised use, loss/theft of personal security credentials, (potential) fraud, or illegal/suspicious activity. This applies whether it was reported by the user to the platform or by the software or systems of the platform. * Any (dispute raised by the user about) unauthorised payment or an error on an account statement. * A material incident, potential security breach or personal data breach. * Any material non-compliance by a user that the platform has become aware of or should have been reasonably aware of. For notifications that can be made through API requests, such as a request to block or terminate an account, no additional reporting is required. ## Daily reporting The following information must be submitted by the platform to Adyen daily for each of the services available when such instances occur: * Fraud Report (Accounts and Issuing) * Number of fraud related incidents/disputes (including transactions charged back due to fraud-related reasons and transactions for which fraud losses were recovered by a means other than a chargeback) and subsequent reason codes/descriptions in accordance with Adyen’s API. For fraud reporting, the platform can choose to either integrate with the Disputes API or send reports to an email address communicated by Adyen. ## Periodic reporting To the extent not prohibited by any applicable law, the platform must share reporting with Adyen on a quarterly basis (using the template provided by Adyen) of all users’ complaints that relate to Adyen products. The quarterly reporting period commences on the date of onboarding of the first user in your live environment. The following information must be contained in the quarterly reports: * The date of receipt of the complaint * The date complaint was acknowledged by the platform as received * Current status of the complaint * The date complaint was resolved * The date a resolution was communicated to the customer (if a complaint has been resolved) * Complaint outcome (upheld or not upheld) * User name * User legal entity reference * Country of the user * Brief description of the complaint * Product to which the complaint relates (if applicable) * Complaint category (the substance of the complaint) * Description of steps taken to resolve the complaint * Complaint determination of either "Upheld" or "Not upheld" before they can be closed * "Upheld" means that the platform agrees that there have been failings and that the customer's complaint is justified in whole or in part. * "Not Upheld" means that the platform has not identified any failings and does not agree that the customer's complaint is justified. The template must be sent to within the following deadlines for each quarter: * 10 January * 10 April * 10 July * 10 October ### UK & Ireland Complaint reporting must contain the number of users who are vulnerable, including the following information: | Data point | Explanation | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Total number of users tagged as vulnerable | Where a user is identified as vulnerable per our training, this should be recorded in the platform CRM system to ensure that the user continually receives the additional support that they need for as long as it is needed. | | Total number of users flagged as vulnerable broken down by categorisation of vulnerability | The user’s specific vulnerability should be recorded under one of these four categories (Health, Life Events, Resilience, and Capability) to allow Adyen to better understand the types of vulnerability Adyen and the platform need to account for when building products and supporting their customers. | | Outcomes of any user requests for specific additional support | If a user requests specific support such as having information presented in a different way to accommodate their needs, or for more time to make a decision, this request should be documented and the outcome recorded. The outcome should cover the actions taken by the platform to accommodate the user’s needs, and details of any relevant follow-up requests from the user. | Reports must be provided in accordance with the same deadlines outlined for quarterly complaints reporting and sent to complaintreports\@adyen.com. Only the total figures for vulnerable users are required. In addition, the platform is required to share with Adyen annually any specific patterns of vulnerability they have identified within their customer base that the platform believes may require Adyen’s attention or further action. ## See also * [Overview of compliance guidelines](/business-accounts/compliance-guidelines) * [Customer service and support](/business-accounts/compliance-guidelines/customer-service-support) * [Customer complaints](/business-accounts/compliance-guidelines/customer-complaints) * [Keeping records](/business-accounts/compliance-guidelines/keeping-records) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/user-interface.md Section: Business accounts Title: User application and interface Description: Learn about the compliance requirements for your user interface and application. --- title: "User application and interface" description: "Learn about the compliance requirements for your user interface and application." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/user-interface" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/user-interface.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/user-interface" last_modified: "2023-12-12T12:09:00+01:00" language: "en" --- # User application and interface Learn about the compliance requirements for your user interface and application. [View source](/business-accounts/compliance-guidelines/user-interface.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. Platforms must provide a user interface that includes the following: * **Product Request:** Let the user request any of the financial services that the platform has agreed with Adyen to provide. * **KYC:** Provide required KYC information to Adyen as required under Adyen’s customer due diligence procedures. * **Agreements and Terms:** Present all required agreements and user terms including bank disclosures and fees, as detailed in [Adyen’s Customer Disclosure and Consent Procedure](#customer-disclosure-and-consent-procedure). If the platform is using [hosted onboarding](/platforms/onboard-users#hosted-onboarding), KYC fields, agreements, and terms of service will be hosted by Adyen. If the platform is using Adyen’s components in the UI, certain requirements may be embedded into the components provided by Adyen. * **User consent:** Ensure that the user reads and accepts the required legal agreements, using language detailed in [Adyen’s Customer Disclosure and Consent Procedure](#customer-disclosure-and-consent-procedure): *“I have read and I accept these terms and confirm that I am a legal representative authorized to accept these terms on behalf of the company. I have taken notice of the privacy statement (www\.adyen.com/privacy-policy) and I consent to my (personal) data being used for the purposes described therein."* * **Terms and Conditions availability:** Provide ongoing access to all the agreements that have been accepted by the user. * **Account Access:** Provide the user, free of charge, with ongoing access to their Balance or Bank Account, Capital, or Issuing product to view transactions, fees and other account information, as provided by Adyen to the platformthrough API as detailed below. * **Preselected Options:** The user interface must not include pre-selected options to indicate that the user has confirmed that they have read or understood the provided information concerning financial services. * **Financial Service Provider:** The user interface may not present the platform as a bank and should include a disclosure indicating Adyen as the financial services provider. * (Ireland Only): For all products, the following wording in the interface must be used: *“We work with Adyen N.V. to offer financial services. Adyen N.V., trading as Adyen, is authorised by De Nederlandsche Bank in the Netherlands and is regulated by the Central Bank of Ireland for consumer protection rules."* ### Product-specific requirements | | | | ------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Service** | **Terms** | | Adyen for Platforms | AfP Terms and Conditions | | Bank Accounts | * Adyen Business Bank Account Agreement - User Terms (Regional versions, if applicable) * Adyen’s Privacy Statement | | Card Issuing | - Account Holder Terms (EU/US) - Adyen’s Privacy Statement | | Capital | * Adyen Capital User Terms * Adyen’s Privacy Statement | ### User interface requirements | | | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Service** | **Interface requirements** | | Adyen for Platforms | * Balance overview (showing the total amount of funds paid into the user’s account) * Transaction history (showing the date of the transaction, total value of the transaction, fees and unique payment ID). | | Business Accounts | - Balance overview - Individual transaction information - Sender and/or receiver reference - IBAN (EU) Bank account number (US) - BIC (EU) - (EU only): Platforms need to provide users in the EU with a [Depositor Information Sheet](/business-accounts/compliance-financial-products/user-interface#depositor-info-sheet) both before offering business accounts and thereafter annually. This information need to be provided as a PDF using the same language shown in the Depositor Information Sheet. - User consent: Ensure that the user interface contains a confirmation for the user to confirm they have read and accepted the terms of the Depositor Information Sheet, using the following language: “*I have read and I accept these terms and confirm that I am a legal representative authorized to accept these terms on behalf of the company. I have taken notice of the [privacy statement](https://www.adyen.com/privacy-policy) and I consent to my (personal) data being used for the purposes described therein.*" - (EU and UK only): Adyen is required to perform a service called verification of payee (EU) and confirmation of payee (UK) for payments made using an Adyen bank account. The verification/confirmation is usually performed by calling Adyen’s API built for this purpose. The platform’s user interface must display a notice to the user and the notice is four-fold as follows: * Match: A notice confirming that the account holder's name and IBAN match the information provided. * Partial Match: A notice indicating the name partially matches, which includes the correct recipient name for the sub-merchant to review. * No Match: A notice stating the names do not match, providing the sub-merchant with the option to cancel, edit, or continue with the transfer or adding the payee. * Service Not Supported: A warning that the verification service is not supported for the specific account, with the option to cancel, edit, or continue with the transfer or adding the payee. - (UK only) BACS Direct Debits: Platforms that wish to offer Business Accounts that are enabled for BACS Direct Debits must ensure that their user interfaces facilitate the following: **Mandate management** * Clearly disclose that only paperless/electronic mandate creation is supported. * Embed the following functionalities for mandate management in the user interface: * Account holders can view all of their mandates, along with the date the mandate was created and the name/reference of the payee. * Account holders receive a notification when a new mandate has been created (sent before the first payment is collected) containing the following details: * Payee details (sort code, account number, name). * payer (i.e., account holder) details (sort code, account number, name). * Account holders can cancel mandates at any time and cancellations must be effective immediately and confirmed to the Account holder. To enable this, the platform must integrate with our mandate cancellation API. Platforms are required to call the API immediately after the cancellation, so Adyen can notify the payee. * Account holders can amend mandates at any time, and amendments must also be effective immediately. **Transaction overview** * Provide in the user interface a clear visibility of the transactions that have been debited from the account, with a reference to the mandate to which each payment relates. **Refund** * Allow the account holder to request a refund at any time. Account holders are entitled to a refund where there is an error in the direct debit payment. This can be done via a dedicated button in the user interface, or through customer support channels. * The platform is required to provide Adyen with the details of the refund claim on the same business day the claim is made. The following details of the transaction must be provided: * Amount * Crediting date * Payee details (sort code, account number, name) * Payer details (sort code, account number, name) * Reason for refund - (US only): FDIC language must be presented the first time the Adyen business bank account is introduced in the UI. - (US only): Regulation GG - Unlawful Internet Gambling Enforcement Act Certification: users requesting business bank accounts must be asked the following prior to the acceptance of the User Terms: * *Is the legal entity opening the business bank account engaged in internet gambling? \[Yes/No]* * Any \[Yes] response should not be able to proceed to open a business bank account. | | Card Issuing | * Account balance information/ Issued card balance information * Account Transaction history/ Issued card Transaction histor * (For Charge Cards): Card balance repayment method; * Applicable fees, interest, and APR * Card transaction dispute functionality; * (US only): Equal Credit Opportunity Act disclosures must be presented with Capital Offers and Charge Card Applications * (US only): The platform must notify users when their request for a Loan or Charge Card has been declined by Adyen (Lender of Record). The platform must use a method that allows for retained documentation of the notification (e.g., UI message, email, or verbal communication documented in a system of record with the date and time). | | Capital Interface | - Capital Contract Type - Capital Balance and term, if applicable - Capital Fee (for Canada, must be shown as annual interest rate) - Capital Repayment Amount and repayment percentage; if applicable, the monthly threshold amount - If applicable, serving Adyen’s offered alternative ways of paying off the financing - (Ireland only): The following statements must be displayed to the user in the Capital interface before the user becomes bound by the Capital contract: * "*As a borrower in a credit agreement, you may have rights and duties under the Credit Reporting Act 2013 (available [here](https://www.irishstatutebook.ie/eli/2013/act/45/enacted/en/html))*". * "*NOTICE: Under the Credit Reporting Act 2013 lenders are required to provide personal and credit information for credit applications and credit agreements of €500 and above to the Central Credit Register. This information will be held on the Central Credit Register and may be used by other lenders when making decisions on your credit applications and credit agreements.*". Note, this notice must be displayed in bold, in a text box and in font size at least equal to that used for other information.) - (Ireland only): The following information must be shown to the user in the Capital user interface before the user becomes bound by the Capital contract: * Capital Balance (the total amount lent) * The length of time for which the loan offer is valid. - (Ireland only): Before the user is bound by the Capital contract, the Capital interface must prompt the user to provide their consent with a tick box to the following statement: "*I understand the features of Capital and I wish to proceed.*" | ** ### Customer disclosure and consent procedure This document outlines the Customer Disclosures and Consent Procedure of Adyen. It describes when and under what conditions Adyen makes disclosures and gains consent from its customers. This document is reviewed on an annual basis. This procedure encompasses disclosures and consents which Adyen presents to its customers; 1. As part of Adyen's customer due diligence (CDD) process. This refers to the due diligence which Adyen performs on all customers as a result of Know Your Customer (KYC) obligations during onboarding or periodic review. 2. As a result of regulatory obligations in the US which mandate that c certain disclosures and/or consent, reflected in the relevant agreement(s), must be detailed within a procedure. This document does not encompass other legal disclosures and consents that Adyen may require as part of the agreements. #### Legal Background Adyen enters a contractual agreement with every user directly, or indirectly (through a platform). This agreement outlines the terms of use for Adyen’s products and services. In addition to the terms of use, there is additional information that must be disclosed and/or requires consent to/from customers, due to local and/or global regulatory obligations, outside of these agreements. This procedure differentiates between Disclosures and Consents. * Disclosure: refers to mandatory information that must be disclosed to the customer, meaning that they must be made explicitly aware of that information prior - or during - the customer due diligence process; * Consent: refers to provisions that the customer must explicitly consent to or certify. Consent must be freely given, informed and specific. #### Applicability This procedure applies to all entities with whom Adyen enters into a business relationship with or on whose behalf Adyen performs a transaction, or provides embedded finance solutions (hereinafter: ‘customer’). Consent can only be given to Adyen by natural persons type: Authorized Signatory. The identification and verification requirements of authorized signatories is described in Adyen’s Natural Person Screening Procedure. The disclosures and consents presented to customers are based on the service line being utilized. Identification and verification requirements on service lines are described in Adyen’s Service Line Screening Procedure. When a term is not defined in this procedure, please refer to the definitions stated in Adyen’s Global AMLCFT and Sanctions Policy and related documents. #### Methodology Adyen discloses all disclosures and obtains all consents remotely through Adyen’s Onboarding forms and/or API’s, all evidence of consents obtained must be retained. ## See also * [Overview of compliance guidelines](/business-accounts/compliance-financial-products) * [Keeping records](/business-accounts/compliance-financial-products/keeping-records) --- # Source: https://docs.adyen.com/business-accounts/compliance-guidelines/vulnerable-users.md Section: Business accounts Title: Vulnerable users (UK and Ireland only) Description: Learn how to support potential users in vulnerable circumstances. --- title: "Vulnerable users (UK and Ireland only)" description: "Learn how to support potential users in vulnerable circumstances." url: "https://docs.adyen.com/business-accounts/compliance-guidelines/vulnerable-users" source_url: "https://docs.adyen.com/business-accounts/compliance-guidelines/vulnerable-users.md" canonical: "https://docs.adyen.com/business-accounts/compliance-guidelines/vulnerable-users" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Vulnerable users (UK and Ireland only) Learn how to support potential users in vulnerable circumstances. [View source](/business-accounts/compliance-guidelines/vulnerable-users.md) This document assists Adyen partners in identifying and assisting the platform’s users who may be in vulnerable circumstances. Adyen recognizes that, due to personal circumstances, certain users may have or acquire traits of vulnerability throughout their lifetime. As a result, such users may require additional assistance to fully engage with the offered financial services and to ensure their needs are being met. In some countries where Adyen offers its financial services, Adyen is obliged by regulation to identify and assist vulnerable customers. To ensure these regulatory requirements are fulfilled, Adyen requires Platforms to adhere to certain processes concerning vulnerable customers, which are outlined in Adyen’s compliance guidelines. This instruction document is an important component of Adyen’s compliance guidelines. It provides practical, step-by-step guidance on how Platform staff should identify vulnerable customers and the procedures they should follow to ensure vulnerable customers receive the necessary assistance. Platforms are required to provide the following instructions to all members of staff who interact directly with users. This includes: * Customer Support Staff * Sales and Marketing Staff who communicate directly with users for sales/marketing purposes. * Managers responsible for overseeing staff who interact directly with users. Platforms must ensure all in-scope staff members read and fully understand these instructions. Staff should be encouraged to raise any queries. If there is any unclarity, Platforms should **seek clarification from Adyen**. Agents should be encouraged to properly support the customer and be given all the additional time needed. Your organisation should also flag any support available for agents when they have been dealing with users who are in distress, as these situations can be stressful. ## Identifying vulnerable users Adyen applies the following definition for vulnerable users: *“Users who, due to their personal circumstances, are especially susceptible to harm, particularly when a firm is not acting with appropriate levels of care.”* While all users are at risk of becoming vulnerable, the risk is increased by characteristics related to **four key drivers**: | Driver | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | Health | Physical or mental health conditions that impact a customer's ability to manage their affairs. | | Life Events | Significant life changes such as bereavement, job loss, or relationship breakdown that can affect resilience and decision-making. | | Resilience | Low ability to withstand financial or emotional shocks (for example., tight margins, limited financial reserves). | | Capability | Low levels of financial literacy, confidence in managing money, or other relevant skills such as digital literacy. | ### Vulnerability in a B2B Context Vulnerability is less likely in the B2B context than in retail financial services, but it can manifest for certain segments of Adyen's indirect customer base, particularly sole proprietors. Indicative examples of merchants who may be prone to vulnerability include: * Sole proprietors operating with tight margins and limited financial reserves who are susceptible to economic shocks. * Small e-commerce businesses experiencing a sudden increase in fraudulent transactions and lacking the resources to manage chargebacks. * Sole proprietors whose health conditions impact their ability to manage business finances effectively. * A business with an owner who has suddenly become incapacitated, leaving no one with the knowledge to manage online payments. * A business struggling with cash flow, making it difficult to pay suppliers. * Elderly sole traders or those with lower digital literacy who may struggle to navigate digital financial tools and processes. Vulnerability can be temporary. Merchants that do not exhibit signs of vulnerability one day may in fact experience it in the future, and vice versa. It is therefore important to routinely be on the lookout for signs of vulnerability. ## Instructions for staff ### Step 1: Initial Interaction Greeting and Introduction: Begin every customer interaction with a warm and empathetic greeting. Introduce yourself and let the customer know you are here to help. ### Step 2: Identifying Vulnerability Indicators of Vulnerability: Pay close attention to the customer's tone, language, and emotional cues. Be alert for any of the following: * Individual Factors: * Passing mentions of illness, disability, or impairment. * Reference to contact with the health or social care sector, or receipt of specific benefits. * Use of English as an additional language. * Behavioural Cues: * Sounding flustered, anxious, or under duress. * Displaying frustration or anger. * Asking unrelated questions, forgetfulness, or struggling to concentrate/understand detail. * Difficulty regulating emotional responses (being upset, tearful) or difficulty trusting the service/individual. * Confusion (for example., not knowing where a debt has come from). * Wider Circumstances: * Mention of life events (time in hospital, bereavement, income shocks). * Struggling with the cost of living (mentions of higher bills, struggling to pay household bills). * Signs of an unstable housing situation or abuse, including economic abuse. * Unexplained spending (which could indicate problem gambling or undeclared debt). * Organizational Actions: * Complaints about things your or another organization may have done (for example, changing communication methods). * Mention of failures to deal with a third party/carer, accept a different payment method, or explain key information clearly. * Example Statements: Statements that could indicate vulnerable circumstances include: * “My circumstances are bad, can you help?” * “I’m not very well at the moment and am finding it difficult.” * “I’m really struggling today, I’m so down.” * “I don’t understand you.” For identifying customers with potential mental capacity limitations, the **BRUCE** method can help identify difficulties with decision-making or limited ability to understand, remember, or "weigh up" information. | Acronym | Focus Area | Question to Consider | | ------- | ------------------ | ------------------------------------------------------------------ | | B | Behaviour and talk | Is there a limitation in the customer’s behaviour and speech? | | R | Remembering | Is the customer experiencing problems with their memory or recall? | | U | Understanding | Does the customer understand the information they are being given? | | C | Confusion | Is the customer confused about the situation or options? | | E | Evaluating | Can the customer “weigh up” the different options open to them? | ### Step 3: Providing Support Use the **TEXAS** method to respond to a customer who has provided information indicating they need additional support. | Acronym | Action | Example Script | | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | T | Thank | “Thanks for telling me about your situation, as it will help us take this into account.” | | E | Explain | “Let me explain how we’d like to use that information, just so you know.” | | X | Explicit Consent | “Are you happy to give me permission to note down and save the information you’ve shared with me today?” | | A | Ask | “How does your situation make it difficult to manage your finances?” "How does it affect your ability to communicate with us?" | | S | Signpost or Refer | Internally refer to a specialist team, or signpost to external help. | Use the **IDEA** method when more information is needed about a customer’s situation to take effective action. | Acronym | Action | Example Script | | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I | Impact | Ask about the impact of the circumstances on the customer’s financial situation (what does it stop them doing or make more difficult?). For example, “What has the impact been on your personal and financial situation?” | | D | Duration | Ask about the duration of the circumstances to help determine the time needed to consider options. For example, “So when did this first start to happen?” | | E | Experience | Understand the customer’s experience of the vulnerability (one-off or recurring?). Take fluctuating situations (including medication effects) into account. For example, “To help me understand your situation better, can you tell me whether this has happened before?” | | A | Assistance | Establish what, if any, assistance the customer has received. This helps determine if you need to refer them for additional support from an external agency. | If necessary, politely ask the customer for clarification about a condition or illness they mention. For example, “I’m really sorry, but I don’t know very much about (name of condition), could you tell me a little more about it?” #### Tailor your support * Customize your approach to meet the customer's specific needs. * Provide clear and concise explanations and solutions. Use plain language and avoid jargon. For complex topics, break them down into sub-topics and pause for questions. * Ask the customer if the current channel (chat, phone, etc.) is their preferred communications channel. * Ask the customer for feedback at appropriate times (for example., when proposing a resolution or next step) to ensure alignment and understanding. #### Offer Additional Assistance/Signposting * If the customer needs extra help, offer additional resources or escalate the issue to a supervisor if necessary. * Ensure that the customer feels supported throughout the process. * External Signposting Categories (Non-exhaustive list; identify an appropriate organisation in the relevant country/territory): * Debt advice services * Mental health support services * Bereavement counselling services * Domestic abuse helpline * Disability support services * Financial literacy/capability groups * Legal aid services * Housing advice services. ### Step 4: Documenting the Interaction A general principle is that customers should only be required to share information about their vulnerability once. The details must be recorded so other staff members who interact with the customer can also meet their needs. The specific vulnerability indicator(s) identified or shared should be recorded using the tags below. A record must be attached to the customer’s file. Take detailed notes about the customer’s situation, the support provided, and any follow-up actions. Make sure that you only record the facts shared with you by the user and do not include any proposed diagnoses or names of any specific conditions unless the customer has explicitly told you that they have that condition. Please also ensure that the notes are recorded in such a way that you would be comfortable with the customer or a third party reading that about themselves. | Tag | Examples of conditions or experiences | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Health/Ability | Physical or mental health conditions that impact a customer's ability to manage their affairs. These may include: significant illness, health issues, or disability. | | Life events | Significant life changes such as: bereavement, job loss, or relationship breakdown. | | Resilience | Low ability to withstand financial or emotional shocks such as being in debt or living paycheck to paycheck. | | Capability | Low levels of financial literacy, confidence in managing money, or other relevant skills, such as digital literacy. | The following are examples of best practices for user interactions with staff. | Example | Vulnerable circumstances tag | Follow-up/support | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer explained that they struggled to understand complex financial information and needed additional support in working through the terms and conditions. | Capability | Agent offered to spend time explaining terms and conditions (or any other aspect unclear to customer) in further detail. Agent added a note to the customer’s file that additional care may be needed to ensure the customer understands all relevant financial information. | | Customer appeared to have difficulty in understanding/retaining relevant financial information. | Capability | Agent offered to spend time explaining terms and conditions (or any other aspect unclear to customer) in further detail. Agent added a note to the customer’s file that additional care may be needed to ensure the customer understands all relevant financial information. | | Customer shared that they suffer from hearing loss and requested that we only communicate with them via email and do not call them. | Health/Ability | Agent added a note to the customer’s file that all communications are to occur in writing and not via call. | | Customer stated that they had recently suffered from a broken down boiler and they needed extra time to pay their fees. | Life events / Resilience | Agent offered to speak with the finance team and check if additional time to pay can be given. | | Customer shared that their finances are tight following a relationship ending and they needed extra time to pay. | Life events / Resilience | Agent offered to speak with the finance team and check if additional time to pay can be given. | The following are examples of unacceptable documentation for user interactions. * Customer did not speak very good English. * Customer had problems concentrating so may have ADHD. * Customer had difficulties understanding/remembering so may have dementia. Consult with your internal privacy or legal teams to ensure that your method of recording is compliant with your company's obligations under domestic privacy legislation such as GDPR. ### Step 5: Follow-Up If necessary, schedule a follow-up call or email to ensure the customer's issue has been resolved. Confirm that the customer is satisfied with the resolution. We recommend that you periodically review your interactions and feedback to continuously improve the handling of vulnerable users. ## See also * [Reporting on vulnerable customer information](/business-accounts/compliance-guidelines/reporting-to-adyen#periodic-reporting) --- # Source: https://docs.adyen.com/business-accounts/consent.md Section: Business accounts Title: Manage consent Description: Learn how to manege user consent with our dedicated API endpoints. --- title: "Manage consent" description: "Learn how to manege user consent with our dedicated API endpoints." url: "https://docs.adyen.com/business-accounts/consent" source_url: "https://docs.adyen.com/business-accounts/consent.md" canonical: "https://docs.adyen.com/business-accounts/consent" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Manage consent Learn how to manege user consent with our dedicated API endpoints. [View source](/business-accounts/consent.md) After an account holder gives their consent, the third-party provider can check if it is still valid and see what they consented to. If an account holder wants to withdraw their consent, the third party provider can make a call to revoke that consent. This page explains how you, as a third-party provider, use the `/consents` endpoint to: * Check if an account holder's consent is still valid and how a third party provider can use the consent. * Revoke consent on the account holder's behalf. ## Requirements | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Setup steps** | Before you begin, you must:- Complete the [Adyen onboarding steps](/business-accounts/open-banking#onboard-with-adyen). - Complete the [get account holder consent](/business-accounts/oauth-flow) steps.. | ## Check if the account holder granted consent To get the status of a previously granted consent: 1. Make a GET `/consents/{consent_id}/status` request, where `consent_id` is a unique identifier for a specific consent. This is the `consent_id` you saved in the [create a consent](/business-accounts/oauth-flow#create-a-consent) step. In the headers, include a UUID for the `X-Request-ID` and the `access_token` you saved in the [get and access token](/business-accounts/oauth-flow#get-an-access-token) step. **Get consent status** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/consent/v1/consents/{consent-id}/status' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. In the response, check the `consentStatus`. This value indicates your current stage in the consent process. See the `consentStatus` for all possible values. | Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `consentStatus` | Status of consent. Possible values:- **received**: The consent data have been received. The request will need to be repeated to check if its status updates to "valid" for use. - **rejected**: The consent data have been rejected. This is a final status. - **valid**: The consent is accepted and valid. - **revokedByPsu**: The consent has been revoked by the account holder. - **expired**: The consent expired. - **terminatedByTpp**: The third-party provider has terminated the consent. | | `psuMessage` | Details regarding the account holder's consent. | **Response** ```json { "consentStatus": "valid", "psuMessage": "The consent is accepted and valid for GET account data calls and others as specified in the consent object." } ``` ## Check the authorization status of an account holders consent To get information about consent authorization and to determine where your account holder is in the authentication flow, for accessing account information, or to initiate payments: 1. Make a GET `/consents/{consentId}/authorisations/{authorization-id-consent}` request, where `consent_id` is a unique identifier for a specific consent and `authorization-id-consent` is a unique identifier for a specific consent authorization. * Note that this `authorization-id-consent` can be found in the [create a consent](/business-accounts/oauth-flow#create-a-consent) response. This is the last set of characters at the end of the`scaStatus` link. **Get authorization details** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/consent/v1/consents/{consent-id}/authorisations/{authorization-id-consent}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. The response contains the authorization status, use this to determine what part of the authentication flow your account holder is currently in. See `scaStatus` for all possible values. | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `scaStatus` | Status of authorization. Possible values:- **scaMethodSelected**: The account holder/third-party provider has selected the related Strong Customer Authentication (SCA) routine. - **started**: The addressed SCA routine has been started. - **finalised**: The SCA routine has been finalized successfully (including a potential confirmation command). This is a final status of the authorization resource. - **failed**: The SCA routine failed. This is a final status of the authorization resource. | **Response** ```json { "scaStatus": "finalised" } ``` ## Check consent details of an account holder To retrieve the details of a previously granted consent, such as the consent status, expiration date, scope, and other related information: 1. Make a GET `/consents/{consent_id}` request, where `consent_id` is a unique identifier for a specific consent. **Get consent details** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/consent/v1/consents/{consent-id}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. Check the response for details about account access, validity period, consent status, and links to available resources. **Response** ```json { "access": { "accounts": [ { "iban": "NL57INGB4654188101" } ], "balances": [ { "iban": "NL57INGB4654188101" } ], "transactions": [ { "iban": "NL57INGB4654188101" } ] }, "recurringIndicator": true, "validUntil": "2023-10-12", "frequencyPerDay": 10, "lastActionDate": "2023-07-14", "consentStatus": "valid", "_links": { "account": { "href": "aisp/v1/accounts" } } } ``` ## Delete a consent Revoking consent withdraws the account holder's authorization to access account information or initiate payments. To revoke a previously granted consent: 1. Make a DELETE `/consents/{consent_id}` request, where `consent_id` is a unique identifier for a specific consent. **Delete a consent** ```bash curl --request DELETE 'https://openbanking-psd2-test.adyen.com/obeu/consent/v1/consents/{consent-id}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Bearer {access-token}' ``` 2. If the deactivation was successful, you'll get an **HTTP 200 OK** response. The `revokedByPsu` status will appear in future calls when you [check if the account holder granted consent](#check-if-the-account-holder-granted-consent). ## Next steps [AISP interface](/business-accounts/aisp) [Learn how to consume our dedicated AISP endpoints.](/business-accounts/aisp) [PISP interface](/business-accounts/pisp) [Learn how to consume our dedicated PISP endpoints.](/business-accounts/pisp) [PIISP interface](/business-accounts/piisp) [Learn how to consume our dedicated PIISP endpoints.](/business-accounts/piisp) --- # Source: https://docs.adyen.com/business-accounts/create-business-accounts.md Section: Business accounts Title: Create business accounts Description: Create and manage business accounts for your users. --- title: "Create business accounts" description: "Create and manage business accounts for your users." url: "https://docs.adyen.com/business-accounts/create-business-accounts" source_url: "https://docs.adyen.com/business-accounts/create-business-accounts.md" canonical: "https://docs.adyen.com/business-accounts/create-business-accounts" last_modified: "2024-01-04T17:37:00+01:00" language: "en" --- # Create business accounts Create and manage business accounts for your users. [View source](/business-accounts/create-business-accounts.md) When you create an Adyen business account for your users, you generate a business account number linked to their balance account. Your users can share their business account number with third parties so they can receive business-related payments or fund transfers. ## Requirements Before you can create business accounts for your users, check if you meet the [requirements for business accounts](/business-accounts#requirements). Additionally, make sure that your users have: * [Legal entities](/business-accounts/manage-legal-entities) for both your user and all entities associated with the user. For example, the ultimate beneficial owners (UBOs) for an organization. * Business lines, which contain information about your user's line of business. You need to create two business lines, one for your user to receive payments and one for business accounts. * An [account holder](/business-accounts/manage-account-holders) and a [balance account](/business-accounts/manage-balance-accounts). * Completed the [verification checks for business accounts](/business-accounts/verification-requirements) and have the **issueBankAccount** [capability](/business-accounts/verification-overview/capabilities) allowed and enabled. ## Create a payment instrument After the **issueBankAccount** capability has been allowed and enabled on the account holder of your user, you can proceed with creating a payment instrument for them. Payment instruments—such as business accounts—are resources that account holders can use externally to transact with their balance account. Creating a business account payment instrument generates a business account number, such as an IBAN. To create a business account payment instrument, make a POST [/paymentInstruments](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments) call specifying: | Parameter name | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [balanceAccountId](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#request-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID returned when you created the balance account. All financial transactions, such as receiving and sending funds, will be processed in this balance account. | | [issuingCountryCode](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__reqParam_issuingCountryCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The two-letter country code where the business account is issued from. We currently support **NL** and **US**. The currency of the specified country must match the currency of the balance account. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **bankAccount**. | | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#request-description) | | Your description for the business account, which you can use to store useful information for your staff. | | [reference](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__reqParam_reference) | | Your reference for the business account, which you can map to your internal systems. | A balance account can only have one business account number. The API returns an error if a business account number already exists. ### Tab: IBAN Here is how you create an IBAN for a business account issued in the Netherlands. **Create an IBAN** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "bankAccount", "description": "{hint:Your human-readable description for the business account}S.Hopper - Account in NL{/hint}", "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "NL" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) PaymentInstrumentInfo paymentInstrumentInfo = new PaymentInstrumentInfo() .balanceAccountId("BA00000000000000000000001") .description("S.Hopper - Account in NL") .type(PaymentInstrumentInfo.TypeEnum.BANKACCOUNT) .issuingCountryCode("NL"); // Send the request PaymentInstrumentsApi service = new PaymentInstrumentsApi(client); PaymentInstrument response = service.createPaymentInstrument(paymentInstrumentInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $paymentInstrumentInfo = new PaymentInstrumentInfo(); $paymentInstrumentInfo ->setBalanceAccountId("BA00000000000000000000001") ->setDescription("S.Hopper - Account in NL") ->setType("bankAccount") ->setIssuingCountryCode("NL"); // Send the request $service = new PaymentInstrumentsApi($client); $response = $service->createPaymentInstrument($paymentInstrumentInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PaymentInstrumentInfo paymentInstrumentInfo = new PaymentInstrumentInfo { BalanceAccountId = "BA00000000000000000000001", Description = "S.Hopper - Account in NL", Type = PaymentInstrumentInfo.TypeEnum.BankAccount, IssuingCountryCode = "NL" }; // Send the request var service = new PaymentInstrumentsService(client); var response = service.CreatePaymentInstrument(paymentInstrumentInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentInstrumentInfo = { type: "bankAccount", description: "S.Hopper - Account in NL", balanceAccountId: "BA00000000000000000000001", issuingCountryCode: "NL" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.PaymentInstrumentsApi.createPaymentInstrument(paymentInstrumentInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) paymentInstrumentInfo := balancePlatform.PaymentInstrumentInfo{ BalanceAccountId: "BA00000000000000000000001", Description: common.PtrString("S.Hopper - Account in NL"), Type: "bankAccount", IssuingCountryCode: "NL", } // Send the request service := client.BalancePlatform() req := service.PaymentInstrumentsApi.CreatePaymentInstrumentInput().PaymentInstrumentInfo(paymentInstrumentInfo) res, httpRes, err := service.PaymentInstrumentsApi.CreatePaymentInstrument(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "bankAccount", "description": "S.Hopper - Account in NL", "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "NL" } # Send the request result = adyen.balancePlatform.payment_instruments_api.create_payment_instrument(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'bankAccount', :description => 'S.Hopper - Account in NL', :balanceAccountId => 'BA00000000000000000000001', :issuingCountryCode => 'NL' } # Send the request result = adyen.balancePlatform.payment_instruments_api.create_payment_instrument(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentInstrumentInfo: Types.balancePlatform.PaymentInstrumentInfo = { balanceAccountId: "BA00000000000000000000001", description: "S.Hopper - Account in NL", type: Types.balancePlatform.PaymentInstrumentInfo.TypeEnum.BankAccount, issuingCountryCode: "NL" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.PaymentInstrumentsApi.createPaymentInstrument(paymentInstrumentInfo); ``` The response returns the **paymentInstrument** resource, identified by its unique `id`. You also receive the `iban` which the account holder can use when sending funds to their business account. **Response** ```json { "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "NL", "status": "Active", "type": "bankAccount", "bankAccount": { "iban": "NL20ADYB2017000035" }, "id": "PI322LJ223222B5DJS7CD9LWL" } ``` ### Tab: US account number Here is how you create an account number for a business account issued in the US. **Create a US account number** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "bankAccount", "description": "{hint:Your human-readable description for the business account}S.Hopper - Account in the US{/hint}", "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "US" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) PaymentInstrumentInfo paymentInstrumentInfo = new PaymentInstrumentInfo() .balanceAccountId("BA00000000000000000000001") .description("S.Hopper - Account in the US") .type(PaymentInstrumentInfo.TypeEnum.BANKACCOUNT) .issuingCountryCode("US"); // Send the request PaymentInstrumentsApi service = new PaymentInstrumentsApi(client); PaymentInstrument response = service.createPaymentInstrument(paymentInstrumentInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $paymentInstrumentInfo = new PaymentInstrumentInfo(); $paymentInstrumentInfo ->setBalanceAccountId("BA00000000000000000000001") ->setDescription("S.Hopper - Account in the US") ->setType("bankAccount") ->setIssuingCountryCode("US"); // Send the request $service = new PaymentInstrumentsApi($client); $response = $service->createPaymentInstrument($paymentInstrumentInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PaymentInstrumentInfo paymentInstrumentInfo = new PaymentInstrumentInfo { BalanceAccountId = "BA00000000000000000000001", Description = "S.Hopper - Account in the US", Type = PaymentInstrumentInfo.TypeEnum.BankAccount, IssuingCountryCode = "US" }; // Send the request var service = new PaymentInstrumentsService(client); var response = service.CreatePaymentInstrument(paymentInstrumentInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentInstrumentInfo = { type: "bankAccount", description: "S.Hopper - Account in the US", balanceAccountId: "BA00000000000000000000001", issuingCountryCode: "US" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.PaymentInstrumentsApi.createPaymentInstrument(paymentInstrumentInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) paymentInstrumentInfo := balancePlatform.PaymentInstrumentInfo{ BalanceAccountId: "BA00000000000000000000001", Description: common.PtrString("S.Hopper - Account in the US"), Type: "bankAccount", IssuingCountryCode: "US", } // Send the request service := client.BalancePlatform() req := service.PaymentInstrumentsApi.CreatePaymentInstrumentInput().PaymentInstrumentInfo(paymentInstrumentInfo) res, httpRes, err := service.PaymentInstrumentsApi.CreatePaymentInstrument(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "bankAccount", "description": "S.Hopper - Account in the US", "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "US" } # Send the request result = adyen.balancePlatform.payment_instruments_api.create_payment_instrument(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'bankAccount', :description => 'S.Hopper - Account in the US', :balanceAccountId => 'BA00000000000000000000001', :issuingCountryCode => 'US' } # Send the request result = adyen.balancePlatform.payment_instruments_api.create_payment_instrument(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const paymentInstrumentInfo: Types.balancePlatform.PaymentInstrumentInfo = { balanceAccountId: "BA00000000000000000000001", description: "S.Hopper - Account in the US", type: Types.balancePlatform.PaymentInstrumentInfo.TypeEnum.BankAccount, issuingCountryCode: "US" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.PaymentInstrumentsApi.createPaymentInstrument(paymentInstrumentInfo); ``` The response returns the **paymentInstrument** resource, identified by its unique `id`. You also receive the `bankAccount` details that the account holder can use when sending funds to their business account. **Response** ```json { "balanceAccountId": "BA00000000000000000000001", "issuingCountryCode": "US", "status": "Active", "type": "bankAccount", "bankAccount": { "accountNumber": "333720756", "routingNumber": "21000021", "accountType": "checking" }, "id": "PI322LJ223222B5DJS7CD9LWL" } ``` ## Get payment instruments To find the existing business account number related to a specified balance account, make a GET [/balanceAccounts/{id}/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/paymentInstruments) request and specify the balance account `id` in the path. --- # Source: https://docs.adyen.com/business-accounts/get-started.md Section: Business accounts Title: Get started Description: An overview of the steps from signing up to going live with business accounts. --- title: "Get started" description: "An overview of the steps from signing up to going live with business accounts." url: "https://docs.adyen.com/business-accounts/get-started" source_url: "https://docs.adyen.com/business-accounts/get-started.md" canonical: "https://docs.adyen.com/business-accounts/get-started" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Get started An overview of the steps from signing up to going live with business accounts. [View source](/business-accounts/get-started.md) With your Adyen for Platforms integration, you can offer your users an Adyen business account. This page provides an overview of how to get started. ## Requirements Before you begin, take into account the following requirements, and preparations: | Requirement | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration. | | **Setup steps** | Complete the following setup steps:- Make sure that creating business accounts has been enabled for your balance platform. To confirm this, ask your Adyen contact. - [Implement Adyen's Authentication SDK](/business-accounts/implement-sca) to comply with the PSD2 regulations for online transactions. | ## How it works Here is the process to start offering Adyen business accounts to your users: 1. [Complete your Adyen for Platforms integration](#1-complete-your-adyen-for-platforms-integration) 2. [Get in touch with us](#2-get-in-touch-with-us) 3. [Scope and design your implementation](#design-implementation) 4. [Build your integration](#4-build-your-integration) 5. [Test your integration](#5-test-your-integration) 6. [Configure your live account](#6-configure-your-live-account) ## Complete your Adyen for Platforms integration Make sure that you completed all the steps in the integration checklist for your [platform](/platforms/integration-checklist) or [marketplace](/marketplaces/integration-checklist) integration. ## Get in touch with us [Contact us](https://www.adyen.com/contact/sales) to register your interest for business accounts. We will help you determine whether our current capabilities are a good fit for your use case. ## Scope and design your implementation Your Adyen contact will work with you to design your implementation. During this phase you will determine how to: * [Comply with financial regulations](/business-accounts/compliance-guidelines) related to business accounts. * Configure the required [capabilities](/business-accounts/verification-overview/capabilities) to allow your users to use business accounts. * [Onboard your users](/business-accounts/onboard-users) and [share the Terms of Service](/business-accounts/onboard-users/terms-of-service) with them. * [Create business accounts for your users](/business-accounts/create-business-accounts). These accounts can be used to send funds to or receive funds from third parties. * [Authenticate your account holders](/business-accounts/implement-sca). * [Send](/business-accounts/send-funds) and [receive](/business-accounts/receive-funds) funds and [track transfers](/business-accounts/third-party-transfer-webhooks). ## Build your integration When you have your test account and credentials, you can start building your Adyen for Platforms integration. Refer to our [integration checklist](/business-accounts/integration-checklist), [Postman collections](https://github.com/Adyen/adyen-postman), [GitHub repo and libraries](https://github.com/Adyen) for help with the implementation process. ## Test your integration After you integrate with our APIs, you are responsible for testing what you built in our test environment. We recommend that you test your integration again after you [configure your live account](#6-configure-your-live-account). ## Configure your live account The setup and configuration of your test account is *not* replicated to your live account. You need to replicate your test account setup in the live environment. After you configure your account on the live environment, test your integration on the live environment as well. Follow our [go-live checklist](/business-accounts/integration-checklist#go-live) to make sure your integration is ready. ## See also * [Account structures and resources](/business-accounts/account-structure-resources) * [Integration checklist](/business-accounts/integration-checklist) * [Manage access for your team](/business-accounts/manage-access) --- # Source: https://docs.adyen.com/business-accounts/how-sca-works.md Section: Business accounts Title: How Strong Customer Authentication (SCA) works with Adyen's APIs Description: Learn how to to perform SCA when making requests to Adyen's APIs. --- title: "How Strong Customer Authentication (SCA) works with Adyen's APIs" description: "Learn how to to perform SCA when making requests to Adyen's APIs." url: "https://docs.adyen.com/business-accounts/how-sca-works" source_url: "https://docs.adyen.com/business-accounts/how-sca-works.md" canonical: "https://docs.adyen.com/business-accounts/how-sca-works" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # How Strong Customer Authentication (SCA) works with Adyen's APIs Learn how to to perform SCA when making requests to Adyen's APIs. [View source](/business-accounts/how-sca-works.md) The purpose of this page is to provide an overview of the SCA process and *not* to provide examples for specific use cases. Some procedures involving business accounts require you to perform Strong Customer Authentication (SCA). For example: * Making funds transfers to third-party bank accounts. * Consulting the transaction history of a business account. * Creating transfer limits. When you make API requests for this procedure, you must also perform SCA. After verifying the identity of your user, the Authentication SDK produces an output that you must include in your API request. Adyen validates this information before sending back a successful response. This page explains how the SCA process works when using Adyen's Authentication SDK. ## Requirements Before you begin, make sure that you fulfill the following requirements: | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model) integration that includes business accounts. | | **API credentials** | To make API requests, you need an [API credential for webservices](/business-accounts/manage-access?tab=balance_platform_configuration_0_1#manage-api-credentials). The [roles](/business-accounts/manage-access?tab=balance_platform_configuration_0_1#frequently-used-roles) that you need depend on the specific API request that you want to make. | | **Setup steps** | Make sure that you have installed the Authentication SDK. | ## How it works After your user starts a procedure that requires SCA, your application initiates the SCA flow. Your user must successfully complete the SCA flow to the API requests required for the procedure. The following diagram shows the flow for performing SCA challenges to validate API requests. [![](/user/pages/reuse/pfs-business-accounts/auth-sdk/how-sca-works/sca-flow.svg)](/user/pages/reuse/pfs-business-accounts/auth-sdk/how-sca-works/sca-flow.svg) As shown in the preceding diagram, the flow for performing SCA on your user is as follows: 1. The Authentication SDK checks if the device is eligible for SCA. 1. Your application initializes the Authentication SDK. 2. The Authentication SDK calls a method that checks if the device is eligible for SCA. 3. If the check is successful, the Authentication SDK passes the `sdkOutput` to your server. 2. Your server makes an API request to initiate the procedure. 1. Your server makes an API request to Adyen including the `sdkOutput` from the previous step in the header. 2. If the request is successful, Adyen returns an **HTTP 401** response that includes an `sdkInput`. 3. Your server passes the `sdkInput` to the Authentication SDK. 3. The Authentication SDK initiates the SCA verification process for your user. 1. The Authentication SDK calls a method to prompt an SCA challenge in your application. 2. Your user completes the challenge. 3. The Authentication SDK validates the solution of the challenge. 4. If the challenge is completed successfully, the Authentication SDK passes a new `sdkOutput` to your server. 4. Your server makes an API request to finalize the procedure. 1. Your server makes an API request to Adyen including the `sdkOutput` from the previous step in the header. 2. If the request is successful, Adyen returns an **HTTP 2xx** response. The exact HTTP status code depends on the endpoint. The following sections explain more details about the steps in the flow. ## Check SCA eligibility Before initiating a procedure that requires SCA, you must check that the device is eligible for SCA. The following tabs explain how to check for SCA eligibility using the Authentication SDK for Kotlin, Swift, or JavaScript. This functionality requires additional configuration from Adyen. To enable it, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Tab: Android (Kotlin) To check if the Android device is eligible for SCA: 1. Initiate the `AdyenAuthentication` class in your Activity or Fragment. **Initiate authentication** ```kotlin private lateinit var adyenAuthentication: AdyenAuthentication override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) adyenAuthentication = AdyenAuthentication(this) } ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```kotlin lifecycleScope.launch { val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability() if (availabilityResult is AvailabilityResult.Available) { availabilityResult.sdkOutput } } ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: iOS (Swift) To check if the iOS device is eligible for SCA: 1. Initialize the `AuthenticationService` class. **Initialize authentication service** ```swift let configuration = AuthenticationService.Configuration( localizedRegistrationReason: registrationReason, localizedAuthenticationReason: authenticationReason, appleTeamIdendtifier: appleTeamIdentifier ) let authenticationService = AuthenticationService(configuration: configuration) ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```swift let sdkOutput = try authenticationService.checkSupport() /// send the sdkOutput to your backend ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: Web (JavaScript) To check if the web browser on your web-enabled device is eligible for SCA: 1. Import the node package in your application. `RelyingPartyName` is the name the user will be presented with when creating or validating a `WebAuthn` operation. We recommend that the value of the `RelyingPartyName` be the merchant name or the URL domain. **Import web sdk and initiate authentication** ```javascript import ScaWebauthn from '@adyen/bpscaweb'; const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'merchant', }); const sdkOutput = await scaWebauthn.checkAvailability().catch((error) => /* SCA_UNAVAILABLE error*/); ``` If the user's browser supports SCA, the function returns `sdkOutput` to exchange in requests to the server. If SCA is not supported, the method throws an `SCA_UNAVAILABLE` error. 2. Pass the `sdkOutput` to your server. You will use the `sdkOutput` when [initiating a procedure](#initiate-procedure). ## Initiate the procedure To initiate a procedure that requires SCA: 1. Make an API request to the endpoint that you need. In the header, specify the following parameter: | Parameter | Type | Required | Description | | ------------------ | ------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Include the following values: - `SCA realm`: Specifies the type of procedure that you want to do. Example values: **Transfer**, **Transaction**, **TransferLimit**. - `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [checked the SCA eligibility](#check-sca) of the device. | The following example shows the `WWW-Authenticate` header using the `SCA realm` **Transfers**. **Header of a transfer request that requires SCA** ```bash 'WWW-Authenticate: SCA realm="Transfer" auth-param1="eyJpZCI6ICJ1c2VyMTIzIiwgInRva2VuIjog..."' ``` 2. Verify that you receive an **HTTP 401** response that includes the `WWW-Authenticate` parameter in the header. The value of this parameter also includes: * `SCA realm`: This must be the same value as the one in the request header. * `auth-param1`: This is a new base64-encoded blob of data. 3. Pass the new `auth-param1` value to the SDK as `sdkInput`. ## Authenticate your user To register the device with the Authentication SDK: 1. Authenticate the user by performing [two-factor authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication) (2FA). 2. Trigger the SDK to start the device registration and pass `sdkInput` you received when you [initiated the procedure](#initiate-procedure). ### Tab: Android (Kotlin) **Register device with SCA SDK** ```kotlin lifecycleScope.launch { val registrationResult: AuthenticationResult = adyenAuthentication.register("sdkInput") when (registrationResult) { is AuthenticationResult.RegistrationSuccessful -> { registrationResult.sdkOutput } is AuthenticationResult.Canceled -> { // cardholder canceled the flow } is AuthenticationResult.Error -> { // Unexpected error registrationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error registrationResult.authenticationError } } } ``` ### Tab: iOS (Swift) **Register device with SCA SDK** ```swift let sdkOutput = try await authenticationService.register(withBase64URLString: sdkInput) /// send the sdkOutput to the backend ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) **Register device with SCA SDK** ```javascript const sdkOutput = await scaWebauthn.register(sdkInput); ``` After a successful registration, the SDK generates a Base64-encoded `sdkOutput` data blob. 3. Pass `sdkOutput` to your server. ## Finalize the procedure To finalize a procedure after SCA was completed: 1. Make an API request to the endpoint that you need. In the header, specify the following parameter: | Parameter | Type | Required | Description | | ------------------ | ------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Include the following values: - `SCA realm`: Specifies the type of procedure that you want to do. Use the same value that you used when you [initiated the procedure](#initiate-procedure). - `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [authenticated your user](#authenticate-user) of the device. | 2. Verify that you receive an **HTTP 2xx** response. This means that the request was successful.\ The HTTP status and the content of the response depend on the endpoint. ## Next steps [required](/business-accounts/register-sca-devices) [Register an SCA device](/business-accounts/register-sca-devices) [Find out how to use our Authentication SDK to register an iOS or Android device, or other web-enabled device for SCA purposes.](/business-accounts/register-sca-devices) [Manage SCA devices](/business-accounts/manage-sca-devices) [Learn how to manage registered SCA devices.](/business-accounts/manage-sca-devices) --- # Source: https://docs.adyen.com/business-accounts/implement-sca.md Section: Business accounts Title: Implement Strong Customer Authentication (SCA) Description: Learn how to manage Strong Customer Authentication (SCA) for business account users. --- title: "Implement Strong Customer Authentication (SCA)" description: "Learn how to manage Strong Customer Authentication (SCA) for business account users." url: "https://docs.adyen.com/business-accounts/implement-sca" source_url: "https://docs.adyen.com/business-accounts/implement-sca.md" canonical: "https://docs.adyen.com/business-accounts/implement-sca" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # Implement Strong Customer Authentication (SCA) Learn how to manage Strong Customer Authentication (SCA) for business account users. [View source](/business-accounts/implement-sca.md) To use Adyen's business accounts in the European Economic Area (EEA) or UK, your business must comply with the [Payment Services Directive 2 (PSD2)](https://www.adyen.com/knowledge-hub/psd2). This directive regulates secure payments and account access to reduce fraud. For some procedures involving business accounts, PSD2 requires you to verify the identity of your user. Some examples of such procedures are: * Making funds transfers to third-party bank accounts. * Consulting the transaction history of a business account. * Creating transfer limits. PSD2 requires you to use Strong Customer Authentication (SCA). This means that, during authentication, the user is required to provide two out of three factors: * **Knowledge**: something that only the user knows, such as a password. * **Possession**: something that only the user possesses, such as a personal mobile or web-enabled device. * **Inherence**: something that is unique to the user, such as biological and behavioral biometrics. To help you comply with PSD2, we provide a client-side Authentication SDK that combines the possession factor with either the knowledge or the inherence factor. The SDK helps you configure a two-factor authentication feature that requires a secondary verification method through a separate communication channel, such as a native mobile phone app or a web-enabled device. ## How to use the Authentication SDK To use Adyen's Authentication SDK: 1. [Install the Authentication SDK](/business-accounts/install-auth-sdk) and add it to your iOS and Android project, or web application. 2. Use the Authentication SDK to [register your user's native mobile, or other web-enabled device](/business-accounts/register-sca-devices) for SCA. 3. Use the Authentication SDK to authenticate your users each time they want to: * [Transfer funds](/business-accounts/sca-for-funds-transfers) to or from their business account. * [Check their transaction history](/business-accounts/sca-for-transaction-history). ## Next steps Install Adyen's Authentication SDK to implement SCA in your application. [required](/business-accounts/install-auth-sdk) [Install the Authentication SDK for mobile devices](/business-accounts/install-auth-sdk) [This only applies to the European Economic Area (EEA).](/business-accounts/install-auth-sdk) [How Strong Customer Authentication (SCA) works with Adyen's APIs](/business-accounts/how-sca-works) [Learn how to to perform SCA when making requests to Adyen's APIs.](/business-accounts/how-sca-works) --- # Source: https://docs.adyen.com/business-accounts/install-auth-sdk.md Section: Business accounts Title: Install the Authentication SDK Description: Learn how to install Adyen's Authentication SDK for iOS and Android devices. --- title: "Install the Authentication SDK" description: "Learn how to install Adyen's Authentication SDK for iOS and Android devices." url: "https://docs.adyen.com/business-accounts/install-auth-sdk" source_url: "https://docs.adyen.com/business-accounts/install-auth-sdk.md" canonical: "https://docs.adyen.com/business-accounts/install-auth-sdk" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # Install the Authentication SDK Learn how to install Adyen's Authentication SDK for iOS and Android devices. [View source](/business-accounts/install-auth-sdk.md) To help you comply with PSD2, we provide a client-side Authentication SDK that combines the possession factor with either the knowledge or the inherence factor. The SDK helps you configure a two-factor authentication feature that requires a secondary verification method through a separate communication channel, such as a mobile phone or other web-enabled device. With Adyen's Authentication SDK, you can: * Check if the user's device is eligible for Strong Customer Authentication (SCA). * Register your user's device to create device binding. * Authenticate your user's subsequent actions. The Authentication SDK integration also enables you to implement out-of-band authentication for [Adyen-issued cards](/issuing). ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------- | | **Integration type** | This feature is supported with an [Adyen for Platforms](/platforms) integration. | ### Client-side requirements We provide the client-side Authentication SDK in the following languages: * **Kotlin** or **Java** for native Android applications * **Swift** for native iOS applications * **JavaScript** for other web applications Before you start implementing the SDK, make sure that your system follows the requirements: | ### Tab: Android (Kotlin) * Your application targets minimum Android API level 21 or later. * The authentication feature works on devices running on Android API level 26 and later. * The authentication feature requires [Google Play Services](https://developers.google.com/android/guides/setup) on the cardholder's device. ### Tab: iOS (Swift) * Your application targets iOS 14 or later. * Your developer environment runs Xcode 13.2 or later. * Your developer environment runs Swift 5.5 or later (pre-installed with Xcode 13.2). * To use the LIVE environment, your application must be a [TestFlight](https://testflight.apple.com/) or App Store release build. Do **not** use debug builds from Xcode. ### Tab: Web (JavaScript) * Make sure that the web browser on your user's device supports SCA. ## Installation The following tabs explain how to install the Authentication SDK using Kotlin, Swift, or JavaScript. ### Tab: Android (Kotlin) 1. To install the Authentication SDK, add the following line to your `build.gradle` file. ```kotlin implementation "com.adyen.authentication:android-authentication:0.3.0" ``` ### Tab: iOS (Swift) To install the Authentication SDK, use one of the following package managers: * [Swift Package Manager](https://swift.org/package-manager/) * [Carthage](https://github.com/Carthage/Carthage) * [CocoaPods](http://cocoapods.org/) The following subsections list the installation steps that correspond to each package manager. ### Swift Package Manager 1. Follow the [Apple's Adding Package Dependencies to Your App](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) guide on how to add a Swift Package dependency. 2. Use `https://github.com/Adyen/adyen-authentication-ios` for the repository URL. 3. Specify the minimum version of **1.0.0**. ### Carthage 1. Add `github adyen/adyen-authentication-ios` to your Cartfile. 2. Run `carthage update`. 3. Link the framework with your target as described in [Carthage Readme](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application). ### CocoaPods 1. Add `pod 'AdyenAuthentication'` to your Podfile. 2. Run `pod install`. ### Tab: Web (JavaScript) 1. To install the Authentication SDK library for use in your front-end application, install the node package. ```bash npm install @adyen/bpscaweb ``` ## Next steps Register and manage your user's devices for strong customer authentication. [How Strong Customer Authentication (SCA) works with Adyen's APIs](/business-accounts/how-sca-works) [Learn how to to perform SCA when making requests to Adyen's APIs.](/business-accounts/how-sca-works) [required](/business-accounts/register-sca-devices) [Register an SCA device](/business-accounts/register-sca-devices) [Find out how to use our Authentication SDK to register an iOS or Android device, or other web-enabled device for SCA purposes.](/business-accounts/register-sca-devices) [Manage SCA devices](/business-accounts/manage-sca-devices) [Learn how to manage registered SCA devices.](/business-accounts/manage-sca-devices) --- # Source: https://docs.adyen.com/business-accounts/integration-checklist.md Section: Business accounts Title: Integration and go-live checklist Description: Checklist for building and taking your Adyen for Platforms integration live with business accounts. --- title: "Integration and go-live checklist" description: "Checklist for building and taking your Adyen for Platforms integration live with business accounts." url: "https://docs.adyen.com/business-accounts/integration-checklist" source_url: "https://docs.adyen.com/business-accounts/integration-checklist.md" canonical: "https://docs.adyen.com/business-accounts/integration-checklist" last_modified: "2023-03-06T15:13:00+01:00" language: "en" --- # Integration and go-live checklist Checklist for building and taking your Adyen for Platforms integration live with business accounts. [View source](/business-accounts/integration-checklist.md) ##### Adyen APIs Postman collections ![](/user/pages/reuse/pfs-general/link-to-postman-collections/postman-icon.svg?decoding=auto\&fetchpriority=auto) Fork our [Postman collections](https://www.postman.com/adyendev/workspace/adyen-apis/overview) in your private workspace to start testing API calls with your own credentials. On this page you can learn about the steps required to enable the use of business accounts for your users. Before you start building your integration, make sure that you have [designed your implementation](/business-accounts/get-started#design-implementation) with your Adyen implementation manager. The integration steps are the following: * [Review your account structure](#review-your-account-structure) * [Complete the integration checklist for Adyen for Platforms](#complete-the-integration-checklist-for-adyen-for-platforms) * [Test your API keys](#test-your-api-keys) * [Set up webhooks](#set-up-webhooks) * [Implement business account features](#implement-business-account-features) * [Go live](#go-live) ## Review your account structure Before you start using business accounts, you must be familiar with the Adyen account structure. Every Adyen for Platforms integration with business accounts must have at least the following resource types: * **Company account**: represents your core business entity and holds your merchant accounts. * **Merchant account**: the account where we process payments for your users. You can have multiple merchant accounts. * **Balance platform**: the accounting system in which you manage your users and funds. * **Account holder**: specifies what your user can do in your platform, for example, receive fund transfers to their balance account and payouts to their verified transfer instrument (bank account). * **Balance account**: holds the funds of your user or your platform. All financial activities in your platform, such as paying out to a bank account, happen through balance accounts. * **Legal entity**: contains information about your user, for example, the legal name, address, and tax information of the organization. Adyen uses this information to perform verification checks required by payment industry regulations. * **Transfer instrument**: your user's verified bank account where they can receive payouts. * **Business line**: contains information about your user's line of business, including their industry and source of funds. * **Payment instrument** (business account): an externally-facing resource for interacting with funds on the associated balance account. Creating a payment instrument generates an account number. Each balance account can have only one payment instrument of type **bankAccount**. For details on the different account structures and example use cases, see [Account structures](/business-accounts/account-structure-resources). ## Complete the integration checklist for Adyen for Platforms Before integrating business accounts, you must complete the integration steps for either the [marketplace](/marketplaces/integration-checklist) or [platform](/platforms/integration-checklist) model of Adyen for Platforms. ## Test your API keys To make API requests related to business accounts, you can use the same API credentials that you generated for your [marketplace](/marketplaces/integration-checklist/#generate-and-test-your-api-keys) or [platform](/platforms/integration-checklist/#generate-and-test-your-api-keys). If needed, you can [generate your API credentials](/business-accounts/manage-access#manage-api-credentials) and assign roles to them in your [Customer Area](https://ca-test.adyen.com/). Make sure that you have the following API credentials and roles. | API | Credential | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) | **ws\@BalancePlatform.****\[YourBalancePlatform]** Use this API credential to send funds to or receive funds from third parties, set rules to automatically approve or decline outgoimg transfers, and create resources such as account holders, balance accounts, and business accounts. | | [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) | **ws*\[123456]@Scope.Company*\[YourCompanyAccount]** Use this API credential to create and manage legal entities that contain the information required for verification checks. | ## Set up webhooks Webhooks are a crucial part of your integration. Adyen sends webhooks to communicate events in your balance platform, such as if your user needs to provide additional information for onboarding, or when funds are debited or credited from their business accounts. 1. [Set up webhook endpoints](/development-resources/webhooks/#expose-an-endpoint-on-your-server) on your server and build the logic for acknowledging webhooks. 2. [Configure webhooks](/development-resources/webhooks/#set-up-webhooks-in-your-customer-area) in your Customer Area. 3. [Secure webhooks](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures/) with HMAC signing. ## Implement business account features In addition to setting up your marketplace or platform, business accounts require you to take additional actions: * Make sure that your users pass the [additional verification checks required for business accounts](/business-accounts/verification-requirements). * (Optional) [Implement Adyen's authentication SDK](/business-accounts/implement-sca) to authenticate your user's transactions and reduce the chance of fraud. * Learn how to make requests to [send funds to](/business-accounts/send-funds) or [receive funds from](/business-accounts/receive-funds) third parties using your Adyen business accounts. * Learn how to [initiate internal direct debits](/business-accounts/transfer-funds-internally) between the balance accounts in your balance platform. * (Optional) Integrate with the [Adyen Open Banking Platform](/business-accounts/open-banking). ## Go live To take your business accounts integration live: 1. **Replicate your test account setup in your live account**\ The business account setup from your test account for Adyen for Platforms is *not* automatically replicated in your live account. 2. **Update your code base** 3. **Switch to live API credentials**\ Get your live API credentials from your Adyen contact. Use these credentials in your live account. 4. **Switch from test to live endpoints**\ Change the endpoints from `test` to `live`. For example, `https://balanceplatform-api-test.adyen.com/` to\ `https://balanceplatform-api-live.adyen.com/`. 5. **Run end-to-end tests** * Live API credentials: make your first live API requests to make sure that your live API credentials are working. * [Business accounts](/business-accounts/create-business-accounts): confirm that you can create business accounts with the **issueBankAccount** [capability](/business-accounts/verification-overview/capabilities#business-account-capabilities) * Third-party transfers: confirm that you can [send funds to](/business-accounts/send-funds) and [receive funds from](/business-accounts/receive-funds) third parties with the **sendToThirdParty** and **receiveFromThirdParty** [capabilities](/business-accounts/verification-overview/capabilities#business-account-capabilities). * [Webhooks](/development-resources/webhooks): confirm that you can receive and accept webhooks in the live environment. --- # Source: https://docs.adyen.com/business-accounts/kyc-verification-codes.md Section: Business accounts Title: Verification codes Description: Verification errors and remediation codes in webhooks or API responses --- title: "Verification codes" description: "Verification errors and remediation codes in webhooks or API responses" url: "https://docs.adyen.com/business-accounts/kyc-verification-codes" source_url: "https://docs.adyen.com/business-accounts/kyc-verification-codes.md" canonical: "https://docs.adyen.com/business-accounts/kyc-verification-codes" last_modified: "2021-01-19T09:45:00+01:00" language: "en" --- # Verification codes Verification errors and remediation codes in webhooks or API responses [View source](/business-accounts/kyc-verification-codes.md) When a verification error occurs, Adyen uses specific verification codes. These codes provide information such as which checks failed and what your users can do to fix the errors. This page provides an overview of the codes and their structure. * **Remediating action codes**: Provides possible solutions to fix a verification error. Whenever possible, Adyen sends a remediating action for every error. * **General error codes**: Provides a broad description of the cause of the verification error. * **Specific suberror codes**: Provides a more granular and specific cause of the verification error. Suberrors are linked to the general error codes. Use the suberror codes to build your verification error handling flows or test different verification scenarios. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen Issuing](/issuing) integration. | | **[API credentials](/development-resources/api-credentials/)** | To view the verification codes using API requests, you must have an [API web service user credential](/business-accounts/manage-access/#manage-api-credentials) for the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). | | **[Customer Area roles](/account/user-roles)** | To view the verification codes using the Customer Area, you must have the**Manage account holder capabilities** [user role](/account/user-roles#platforms). | ### How to view the verification codes Check the verification codes in your Customer Area, or through API responses or webhooks. ### Tab: Customer Area To view capabilities of an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab. You can view the capabilities that are enabled, allowed and their verification status. ### Tab: APIs and webhooks To check the verification codes, you can: * Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}) request. * Or keep track of the [balancePlatform.accountHolder.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.created) and [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks. The verification codes are in the [`problems` array](#example-problems-array). ## Recommendations for API-only onboarding When using [API-only onboarding](/business-accounts/onboard-users), we recommend that you build your error handling flows using the codes that best fit your use cases and available development resources. We try to provide you with the most accurate feedback. This requires you to build your implementation so that it can handle all possible verification codes. Using all the codes allows you to resolve issues for your users by providing them with more information about errors and what they need to do next. ## Problems array example When a verification error occurs, you get information from the [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) array in an API response or a webhook. This array contains the following. * [entity](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}) object: The ID of the legal entity that has a verification error. * [verificationErrors](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors) array: Contains the details of the errors. Each item contains: * [type](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors-type): The type of error. Possible values are **invalidInput** and **dataMissing**. * [code](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors-code): The general error code. * [message](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors-message): The general error message. * [remediatingActions](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors-remediatingActions): This object is sent when there is a common remediating action in the suberrors. This contains a `code` and `message`. * [subErrors](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__resParam_capabilities-problems-verificationErrors-subErrors) array. Each entry contains a `type`, `code`, `message`, and a `remediatingActions` array. **Problems array example** ```json { ... "problems": [ { "entity": { "id": "LE00000000000000000000001", "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" } ] } ], "verificationStatus": "invalid" ... } ``` ## Next steps Build your error handling flows using the codes below. [Remediating action codes](/business-accounts/kyc-verification-codes/remediating-actions) [Possible solutions to resolve KYC errors.](/business-accounts/kyc-verification-codes/remediating-actions) [General error codes](/business-accounts/kyc-verification-codes/general-verification-errors) [General error codes for different check types.](/business-accounts/kyc-verification-codes/general-verification-errors) [Specific sub-error codes](/business-accounts/kyc-verification-codes/sub-errors) [More granular error codes for different check types.](/business-accounts/kyc-verification-codes/sub-errors) --- # Source: https://docs.adyen.com/business-accounts/kyc-verification-codes/general-verification-errors.md Section: Business accounts Title: General error codes --- title: "General error codes" url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/general-verification-errors" source_url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/general-verification-errors.md" canonical: "https://docs.adyen.com/business-accounts/kyc-verification-codes/general-verification-errors" last_modified: "2023-02-28T10:50:00+01:00" language: "en" --- # General error codes [View source](/business-accounts/kyc-verification-codes/general-verification-errors.md) You can use the general error codes to broadly identify the cause of an error. Adyen sends the general error codes and messages in the `verificationErrors` array. This array also usually contains corresponding [suberrors](/business-accounts/kyc-verification-codes/sub-errors). ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen Issuing](/issuing) integration, there are no additional requirements, limitations, or preparations. ## Types of error codes The range of error codes are divided into the types of check. * **1\_1x**: [General issues](#general-errors) * **1\_3x**-**1\_4x**: [Issues with the individual check](#individual-check) * **1\_5x**: [Issues with the organization check](#organization-check) * **1\_6x**: [Issues with the legal arrangement check](#legal-check) * **1\_7x**: [Issues with the bank account check](#bank-check) * **1\_8x**: [Issues with the proof of signatory check](#proof-of-signatory-check) * **1\_9x**: [Issues with the business line check](#bl-check) * **2\_8x**: [Issues with missing data](#missing-data) * **2\_9x**: [Issues with missing contracts](#missing-contracts) * **3\_1x**: [Issues with data review](#data-review) ## General issues | General error code | Message | Possible suberrors | | | ------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | - | | []()1\_10 | Information couldn't be verified | [1\_1002](/business-accounts/kyc-verification-codes/sub-errors#1_1002) | | | []()1\_11 | Document didn't meet requirements | [1\_1003](/business-accounts/kyc-verification-codes/sub-errors#1_1003) | | | []()1\_12 | Legal entity declined | [1\_1000](/business-accounts/kyc-verification-codes/sub-errors#1_1000) | | | []()1\_13 | Verification couldn't be completed | [1\_1001](/business-accounts/kyc-verification-codes/sub-errors#1_1001) | | | []()1\_14 | Capability not allowed for type individual | | | | []()1\_15 | Capability not allowed due to legal entity's or associated individual's country | | | | []()1\_16 | Capability not allowed for entity type | | | ## Individual identity check | General error code | Message | Possible suberrors | | | ------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_30 | Individual details couldn't be verified | [1\_3000](/business-accounts/kyc-verification-codes/sub-errors#1_3000), [1\_3001](/business-accounts/kyc-verification-codes/sub-errors#1_3001), [1\_3002](/business-accounts/kyc-verification-codes/sub-errors#1_3002), [1\_3003](/business-accounts/kyc-verification-codes/sub-errors#1_3003), [1\_3004](/business-accounts/kyc-verification-codes/sub-errors#1_3004), [1\_3005](/business-accounts/kyc-verification-codes/sub-errors#1_3005), [1\_3006](/business-accounts/kyc-verification-codes/sub-errors#1_3006), [1\_3007](/business-accounts/kyc-verification-codes/sub-errors#1_3007), [1\_3057](/business-accounts/kyc-verification-codes/sub-errors#1_3057), [1\_3058](/business-accounts/kyc-verification-codes/sub-errors#1_3058), [1\_3062](/business-accounts/kyc-verification-codes/sub-errors#1_3062) | | | []()1\_31 | ID document is needed | [1\_3052](/business-accounts/kyc-verification-codes/sub-errors#1_3052) | | | []()1\_32 | ID document couldn't be processed | [1\_3012](/business-accounts/kyc-verification-codes/sub-errors#1_3012) | | | []()1\_33 | ID document didn't meet requirements | [1\_3009](/business-accounts/kyc-verification-codes/sub-errors#1_3009), [1\_3013](/business-accounts/kyc-verification-codes/sub-errors#1_3013), [1\_3015](/business-accounts/kyc-verification-codes/sub-errors#1_3015), [1\_3019](/business-accounts/kyc-verification-codes/sub-errors#1_3019), [1\_3020](/business-accounts/kyc-verification-codes/sub-errors#1_3020), [1\_3024](/business-accounts/kyc-verification-codes/sub-errors#1_3024), [1\_3026](/business-accounts/kyc-verification-codes/sub-errors#1_3026), [1\_3027](/business-accounts/kyc-verification-codes/sub-errors#1_3027), [1\_3029](/business-accounts/kyc-verification-codes/sub-errors#1_3029), [1\_3030](/business-accounts/kyc-verification-codes/sub-errors#1_3030), [1\_3031](/business-accounts/kyc-verification-codes/sub-errors#1_3031), [1\_3066](/business-accounts/kyc-verification-codes/sub-errors#1_3066), [1\_3067](/business-accounts/kyc-verification-codes/sub-errors#1_3067) | | | []()1\_34 | Image of the ID document didn't meet requirements | [1\_3008](/business-accounts/kyc-verification-codes/sub-errors#1_3008), [1\_3010](/business-accounts/kyc-verification-codes/sub-errors#1_3010), [1\_3011](/business-accounts/kyc-verification-codes/sub-errors#1_3011), [1\_3014](/business-accounts/kyc-verification-codes/sub-errors#1_3014), [1\_3036](/business-accounts/kyc-verification-codes/sub-errors#1_3036), [1\_3016](/business-accounts/kyc-verification-codes/sub-errors#1_3016), [1\_3017](/business-accounts/kyc-verification-codes/sub-errors#1_3017), [1\_3018](/business-accounts/kyc-verification-codes/sub-errors#1_3018), [1\_3021](/business-accounts/kyc-verification-codes/sub-errors#1_3021), [1\_3022](/business-accounts/kyc-verification-codes/sub-errors#1_3022), [1\_3023](/business-accounts/kyc-verification-codes/sub-errors#1_3023) | | | []()1\_35 | Individual details didn't match the ID document | [1\_3032](/business-accounts/kyc-verification-codes/sub-errors#1_3032), [1\_3033](/business-accounts/kyc-verification-codes/sub-errors#1_3033), [1\_3034](/business-accounts/kyc-verification-codes/sub-errors#1_3034), [1\_3035](/business-accounts/kyc-verification-codes/sub-errors#1_3035), [1\_3025](/business-accounts/kyc-verification-codes/sub-errors#1_3025), [1\_3028](/business-accounts/kyc-verification-codes/sub-errors#1_3028), [1\_3065](/business-accounts/kyc-verification-codes/sub-errors#1_3065) | | | []()1\_36 | Proof of residency didn't meet requirements | [1\_3040](/business-accounts/kyc-verification-codes/sub-errors#1_3040), [1\_3041](/business-accounts/kyc-verification-codes/sub-errors#1_3041), [1\_3042](/business-accounts/kyc-verification-codes/sub-errors#1_3042), [1\_3043](/business-accounts/kyc-verification-codes/sub-errors#1_3043), [1\_3044](/business-accounts/kyc-verification-codes/sub-errors#1_3044) | | | []()1\_37 | Image of the proof of residency didn't meet the requirements | [1\_3045](/business-accounts/kyc-verification-codes/sub-errors#1_3045) | | | []()1\_38 | Individual details didn't match the proof of residency | [1\_3037](/business-accounts/kyc-verification-codes/sub-errors#1_3037), [1\_3038](/business-accounts/kyc-verification-codes/sub-errors#1_3038), [1\_3039](/business-accounts/kyc-verification-codes/sub-errors#1_3039), [1\_3046](/business-accounts/kyc-verification-codes/sub-errors#1_3046) | | | []()1\_39 | Proof of national ID number didn't meet requirements | [1\_3047](/business-accounts/kyc-verification-codes/sub-errors#1_3047) | | | []()1\_40 | Image of the proof of national ID number didn't meet the requirements | [1\_3051](/business-accounts/kyc-verification-codes/sub-errors#1_3051) | | | []()1\_41 | Individual details didn't match the proof of national ID number | [1\_3048](/business-accounts/kyc-verification-codes/sub-errors#1_3048), [1\_3049](/business-accounts/kyc-verification-codes/sub-errors#1_3049), [1\_3050](/business-accounts/kyc-verification-codes/sub-errors#1_3050) | | | []()1\_42 | Individual details didn't meet the format requirements | [1\_3053](/business-accounts/kyc-verification-codes/sub-errors#1_3053), [1\_3054](/business-accounts/kyc-verification-codes/sub-errors#1_3054), [1\_3055](/business-accounts/kyc-verification-codes/sub-errors#1_3055) | | | []()1\_43 | Image of the proof of the individual tax ID didn't meet the requirements | [1\_3056](/business-accounts/kyc-verification-codes/sub-errors#1_3056) | | | []()1\_44 | Proof of the individual tax ID didn't meet requirements | [1\_3059](/business-accounts/kyc-verification-codes/sub-errors#1_3059) | | | []()1\_45 | Individual details didn't match the proof of the individual tax ID | [1\_3060](/business-accounts/kyc-verification-codes/sub-errors#1_3060), [1\_3061](/business-accounts/kyc-verification-codes/sub-errors#1_3061), [1\_3063](/business-accounts/kyc-verification-codes/sub-errors#1_3063) | | | []()1\_46 | Identity couldn't be verified | [1\_3077](/business-accounts/kyc-verification-codes/sub-errors#1_3077) | | | []()1\_47 | Image of the live selfie didn't meet requirements | [1\_3078](/business-accounts/kyc-verification-codes/sub-errors#1_3078), [1\_3079](/business-accounts/kyc-verification-codes/sub-errors#1_3079), [1\_3080](/business-accounts/kyc-verification-codes/sub-errors#1_3080) | | | []()1\_48 | Biometric verification couldn't be performed | [1\_3075](/business-accounts/kyc-verification-codes/sub-errors#1_3075), [1\_3076](/business-accounts/kyc-verification-codes/sub-errors#1_3076) | | ## Organization check | General error code | Message | Possible suberrors | | ------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | []()1\_50 | Organization details couldn't be verified | [1\_5000](/business-accounts/kyc-verification-codes/sub-errors#1_5000), [1\_5001](/business-accounts/kyc-verification-codes/sub-errors#1_5001), [1\_5002](/business-accounts/kyc-verification-codes/sub-errors#1_5002), [1\_5003](/business-accounts/kyc-verification-codes/sub-errors#1_5003), [1\_5004](/business-accounts/kyc-verification-codes/sub-errors#1_5004), [1\_5005](/business-accounts/kyc-verification-codes/sub-errors#1_5005), [1\_5006](/business-accounts/kyc-verification-codes/sub-errors#1_5006), [1\_5007](/business-accounts/kyc-verification-codes/sub-errors#1_5007), [1\_5008](/business-accounts/kyc-verification-codes/sub-errors#1_5008), [1\_5009](/business-accounts/kyc-verification-codes/sub-errors#1_5009), [1\_5010](/business-accounts/kyc-verification-codes/sub-errors#1_5010), [1\_5011](/business-accounts/kyc-verification-codes/sub-errors#1_5011), [1\_5012](/business-accounts/kyc-verification-codes/sub-errors#1_5012), [1\_5013](/business-accounts/kyc-verification-codes/sub-errors#1_5013), [1\_5014](/business-accounts/kyc-verification-codes/sub-errors#1_5014), [1\_5015](/business-accounts/kyc-verification-codes/sub-errors#1_5015), [1\_5016](/business-accounts/kyc-verification-codes/sub-errors#1_5016), [1\_5017](/business-accounts/kyc-verification-codes/sub-errors#1_5017), [1\_5018](/business-accounts/kyc-verification-codes/sub-errors#1_5018), [1\_5019](/business-accounts/kyc-verification-codes/sub-errors#1_5019), [1\_5020](/business-accounts/kyc-verification-codes/sub-errors#1_5020), [1\_5025](/business-accounts/kyc-verification-codes/sub-errors#1_5025), [1\_5026](/business-accounts/kyc-verification-codes/sub-errors#1_5026), [1\_5033](/business-accounts/kyc-verification-codes/sub-errors#1_5033), [1\_5036](/business-accounts/kyc-verification-codes/sub-errors#1_5036), [1\_5042](/business-accounts/kyc-verification-codes/sub-errors#1_5042), [1\_5054](/business-accounts/kyc-verification-codes/sub-errors#1_5042), [1\_5055](/business-accounts/kyc-verification-codes/sub-errors#1_5055), [1\_5093](/business-accounts/kyc-verification-codes/sub-errors#1_5093), [1\_5094](/business-accounts/kyc-verification-codes/sub-errors#1_5094), [1\_8000](/business-accounts/kyc-verification-codes/sub-errors#1_8000) | | | | | | []()1\_51 | Organization details didn't match the document | [1\_5023](/business-accounts/kyc-verification-codes/sub-errors#1_5023), [1\_5027](/business-accounts/kyc-verification-codes/sub-errors#1_5027), [1\_5028](/business-accounts/kyc-verification-codes/sub-errors#1_5028), [1\_5029](/business-accounts/kyc-verification-codes/sub-errors#1_5029), [1\_5030](/business-accounts/kyc-verification-codes/sub-errors#1_5030), [1\_5031](/business-accounts/kyc-verification-codes/sub-errors#1_5031), [1\_5032](/business-accounts/kyc-verification-codes/sub-errors#1_5032), [1\_5037](/business-accounts/kyc-verification-codes/sub-errors#1_5037), [1\_5041](/business-accounts/kyc-verification-codes/sub-errors#1_5041), [1\_5043](/business-accounts/kyc-verification-codes/sub-errors#1_5043), [1\_5044](/business-accounts/kyc-verification-codes/sub-errors#1_5044), [1\_5045](/business-accounts/kyc-verification-codes/sub-errors#1_5045), [1\_5061](/business-accounts/kyc-verification-codes/sub-errors#1_5061), [1\_5062](/business-accounts/kyc-verification-codes/sub-errors#1_5062), [1\_5063](/business-accounts/kyc-verification-codes/sub-errors#1_5063), [1\_5064](/business-accounts/kyc-verification-codes/sub-errors#1_5064), [1\_5065](/business-accounts/kyc-verification-codes/sub-errors#1_5065), [1\_5066](/business-accounts/kyc-verification-codes/sub-errors#1_5066), [1\_5067](/business-accounts/kyc-verification-codes/sub-errors#1_5067), [1\_8001](/business-accounts/kyc-verification-codes/sub-errors#1_8001) | | []()1\_52 | Registration document didn't meet requirements | [1\_5021](/business-accounts/kyc-verification-codes/sub-errors#1_5021), [1\_5022](/business-accounts/kyc-verification-codes/sub-errors#1_5022), [1\_5024](/business-accounts/kyc-verification-codes/sub-errors#1_5024), [1\_5035](/business-accounts/kyc-verification-codes/sub-errors#1_5035) | | []()1\_53 | Tax document didn't meet requirements | [1\_5038](/business-accounts/kyc-verification-codes/sub-errors#1_5038), [1\_5039](/business-accounts/kyc-verification-codes/sub-errors#1_5039), [1\_5040](/business-accounts/kyc-verification-codes/sub-errors#1_5040) | | []()1\_54 | Proof of address didn't meet requirements | [1\_5034](/business-accounts/kyc-verification-codes/sub-errors#1_5034) | | []()1\_55 | Proof of ownership is needed | [1\_5048](/business-accounts/kyc-verification-codes/sub-errors#1_5048) | | []()1\_56 | Organization ownership couldn't be verified | [1\_5046](/business-accounts/kyc-verification-codes/sub-errors#1_5046), [1\_5047](/business-accounts/kyc-verification-codes/sub-errors#1_5047) | | []()1\_57 | Submitted affiliation document didn't meet the requirements | [1\_5049](/business-accounts/kyc-verification-codes/sub-errors#1_5049), [1\_5051](/business-accounts/kyc-verification-codes/sub-errors#1_5051), [1\_5052](/business-accounts/kyc-verification-codes/sub-errors#1_5052) | | []()1\_58 | VAT document didn't meet requirements | [1\_5056](/business-accounts/kyc-verification-codes/sub-errors#1_5056), [1\_5057](/business-accounts/kyc-verification-codes/sub-errors#1_5057), [1\_5058](/business-accounts/kyc-verification-codes/sub-errors#1_5058), [1\_5059](/business-accounts/kyc-verification-codes/sub-errors#1_5059), [1\_5060](/business-accounts/kyc-verification-codes/sub-errors#1_5060) | | | | | ## Legal arrangement check The actual error message will correspond to the specific type of legal arrangement. For example, "`Sole proprietorship` details couldn't be verified." | General error code | Message | Possible suberrors | | ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | []()1\_60 | Legal arrangement details couldn't be verified | [1\_6000](/business-accounts/kyc-verification-codes/sub-errors#1_6000), [1\_6001](/business-accounts/kyc-verification-codes/sub-errors#1_6001), [1\_6002](/business-accounts/kyc-verification-codes/sub-errors#1_6002), [1\_6004](/business-accounts/kyc-verification-codes/sub-errors#1_6004), [1\_6005](/business-accounts/kyc-verification-codes/sub-errors#1_6005) | | []()1\_61 | Constitutional document didn't meet requirements | [1\_6006](/business-accounts/kyc-verification-codes/sub-errors#1_6006), [1\_6009](/business-accounts/kyc-verification-codes/sub-errors#1_6009), [1\_6010](/business-accounts/kyc-verification-codes/sub-errors#1_6010), [1\_6017](/business-accounts/kyc-verification-codes/sub-errors#1_6017) | | []()1\_62 | Legal arrangement details didn't match the constitutional document | [1\_6007](/business-accounts/kyc-verification-codes/sub-errors#1_6007), [1\_6008](/business-accounts/kyc-verification-codes/sub-errors#1_6008), [1\_6011](/business-accounts/kyc-verification-codes/sub-errors#1_6011) | | []()1\_63 | Legal arrangement's affiliated member's details didn't match the constitutional document | [1\_6034](/business-accounts/kyc-verification-codes/sub-errors#1_6034), [1\_6035](/business-accounts/kyc-verification-codes/sub-errors#1_6035), [1\_6036](/business-accounts/kyc-verification-codes/sub-errors#1_6036), [1\_6037](/business-accounts/kyc-verification-codes/sub-errors#1_6037), [1\_6038](/business-accounts/kyc-verification-codes/sub-errors#1_6038) | ## Bank account check | General error code | Message | Possible suberrors | | | ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_70 | Bank account couldn't be verified | [1\_7000](/business-accounts/kyc-verification-codes/sub-errors#1_7000), [1\_7003](/business-accounts/kyc-verification-codes/sub-errors#1_7003) | | | []()1\_71 | Bank account details couldn't be verified | [1\_7001](/business-accounts/kyc-verification-codes/sub-errors#1_7001), [1\_7002](/business-accounts/kyc-verification-codes/sub-errors#1_7002), [1\_7004](/business-accounts/kyc-verification-codes/sub-errors#1_7004), [1\_7015](/business-accounts/kyc-verification-codes/sub-errors#1_7015), [1\_7017](/business-accounts/kyc-verification-codes/sub-errors#1_7017), [1\_7020](/business-accounts/kyc-verification-codes/sub-errors#1_7020), [1\_7007](/business-accounts/kyc-verification-codes/sub-errors#1_7007) | | | []()1\_72 | Verification could not be completed | [1\_1001](/business-accounts/kyc-verification-codes/sub-errors#1_1001) | | | []()1\_73 | Bank account access could not be authenticated | | | | []()1\_74 | Bank statement is needed | [1\_7008](/business-accounts/kyc-verification-codes/sub-errors#1_7008) | | | []()1\_75 | Bank statement didn't meet requirements | [1\_7009](/business-accounts/kyc-verification-codes/sub-errors#1_7009), [1\_7010](/business-accounts/kyc-verification-codes/sub-errors#1_7010), [1\_7012](/business-accounts/kyc-verification-codes/sub-errors#1_7012), [1\_7013](/business-accounts/kyc-verification-codes/sub-errors#1_7013), [1\_7014](/business-accounts/kyc-verification-codes/sub-errors#1_7014), [1\_7018](/business-accounts/kyc-verification-codes/sub-errors#1_7018), [1\_7019](/business-accounts/kyc-verification-codes/sub-errors#1_7019), [1\_7021](/business-accounts/kyc-verification-codes/sub-errors#1_7021), [1\_7022](/business-accounts/kyc-verification-codes/sub-errors#1_7022) | | | []()1\_76 | Bank details didn't match the bank document | [1\_7011](/business-accounts/kyc-verification-codes/sub-errors#1_7011), [1\_7016](/business-accounts/kyc-verification-codes/sub-errors#1_7016) | | | []()1\_77 | The entity is in pending status | | | ## Proof of signatory check | General error code | Message | Possible suberrors | | ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1\_80 | Proof of signatory missing | | | 1\_81 | Signatory details didn't match proof of signatory | [1\_8002](/business-accounts/kyc-verification-codes/sub-errors#1_8002) | | 1\_82 | Proof of signatory didn't meet requirements | [1\_8003](/business-accounts/kyc-verification-codes/sub-errors#1_8003), [1\_8004](/business-accounts/kyc-verification-codes/sub-errors#1_8004), [1\_8005](/business-accounts/kyc-verification-codes/sub-errors#1_8005), [1\_8006](/business-accounts/kyc-verification-codes/sub-errors#1_8006) | | 1\_83 | Signatory details couldn't be verified | [1\_8007](/business-accounts/kyc-verification-codes/sub-errors#1_8007), [1\_8008](/business-accounts/kyc-verification-codes/sub-errors#1_8008) | | 1\_84 | Proof of director document missing | | | 1\_85 | Proof of director document didn't meet the requirements | [1\_8013](/business-accounts/kyc-verification-codes/sub-errors#1_8013), [1\_8014](/business-accounts/kyc-verification-codes/sub-errors#1_8014), [1\_8015](/business-accounts/kyc-verification-codes/sub-errors#1_8008) | | 1\_86 | Director details didn't match with proof of director document | [1\_8011](/business-accounts/kyc-verification-codes/sub-errors#1_8011), [1\_8012](/business-accounts/kyc-verification-codes/sub-errors#1_8012) | | 1\_87 | Director details couldn't be verified | | ## Business line check | General error code | Message | Possible suberrors | | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_90 | Industry couldn't be verified | [1\_9000](/business-accounts/kyc-verification-codes/sub-errors#1_9000), [1\_9001](/business-accounts/kyc-verification-codes/sub-errors#1_9001), [1\_9002](/business-accounts/kyc-verification-codes/sub-errors#1_9002), [1\_9003](/business-accounts/kyc-verification-codes/sub-errors#1_9003) | | | []()1\_91 | Proof of industry didn't meet requirements | [1\_9004](/business-accounts/kyc-verification-codes/sub-errors#1_9004), [1\_9005](/business-accounts/kyc-verification-codes/sub-errors#1_9005), [1\_9006](/business-accounts/kyc-verification-codes/sub-errors#1_9006), [1\_9007](/business-accounts/kyc-verification-codes/sub-errors#1_9007), [1\_9008](/business-accounts/kyc-verification-codes/sub-errors#1_9008) | | | []()1\_92 | No web address available to perform verification | [1\_9002](/business-accounts/kyc-verification-codes/sub-errors#1_9002) | | | []()1\_93 | Source of funds details couldn’t be verified | [1\_9009](/business-accounts/kyc-verification-codes/sub-errors#1_9009) | | | []()1\_94 | Proof of funds document didn't meet requirements | [1\_9010](/business-accounts/kyc-verification-codes/sub-errors#1_9010), [1\_9011](/business-accounts/kyc-verification-codes/sub-errors#1_9011), [1\_9012](/business-accounts/kyc-verification-codes/sub-errors#1_9012) | | ## Missing data | General error code | Message | Remediating action code | | ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | []()2\_8009 | `individual.firstName` was missing | [2\_102](/business-accounts/kyc-verification-codes/remediating-actions#2_102) | | []()2\_8011 | `individual.lastName` was missing | [2\_103](/business-accounts/kyc-verification-codes/remediating-actions#2_103) | | []()2\_8017 | `individual.residentialAddress.country` was missing | [2\_104](/business-accounts/kyc-verification-codes/remediating-actions#2_104) | | []()2\_8018 | `individual.residentialAddress.stateOrProvince` was missing | [2\_105](/business-accounts/kyc-verification-codes/remediating-actions#2_105) | | []()2\_8019 | `individual.residentialAddress.street` was missing | [2\_106](/business-accounts/kyc-verification-codes/remediating-actions#2_106) | | []()2\_8020 | `individual.residentialAddress.city` was missing | [2\_107](/business-accounts/kyc-verification-codes/remediating-actions#2_107) | | []()2\_8021 | `individual.residentialAddress.postalCode` was missing | [2\_108](/business-accounts/kyc-verification-codes/remediating-actions#2_108) | | []()2\_8022 | `individual.residentialAddress.street2` was missing | [2\_109](/business-accounts/kyc-verification-codes/remediating-actions#2_109) | | []()2\_8025 | `individual.nationality` was missing | [2\_110](/business-accounts/kyc-verification-codes/remediating-actions#2_110) | | []()2\_8028 | `individual.birthData.dateOfBirth` was missing | [2\_112](/business-accounts/kyc-verification-codes/remediating-actions#2_112) | | []()2\_8030 | `bankAccount.iban` was missing | [2\_113](/business-accounts/kyc-verification-codes/remediating-actions#2_113) | | []()2\_8032 | `bankAccount.accountNumber` was missing | [2\_114](/business-accounts/kyc-verification-codes/remediating-actions#2_114) | | []()2\_8036 | `bankAccount` was missing | [2\_115](/business-accounts/kyc-verification-codes/remediating-actions#2_115) | | []()2\_8037 | `bankStatement` was missing | [1\_703](/business-accounts/kyc-verification-codes/remediating-actions#1_703) | | []()2\_8038 | `bankAccount.branchCode` was missing | [2\_116](/business-accounts/kyc-verification-codes/remediating-actions#2_116) | | []()2\_8043 | `organization.registrationNumber` was missing | [2\_117](/business-accounts/kyc-verification-codes/remediating-actions#2_117) | | []()2\_8044 | `soleProprietorship.registrationNumber` was missing | [2\_189](/business-accounts/kyc-verification-codes/remediating-actions#2_189) | | []()2\_8045 | `organization.taxId` was missing | [2\_118](/business-accounts/kyc-verification-codes/remediating-actions#2_118) | | []()2\_8052 | `documents.attachment` was missing | [2\_119](/business-accounts/kyc-verification-codes/remediating-actions#2_119) | | []()2\_8058 | `individual.name` was missing | [2\_120](/business-accounts/kyc-verification-codes/remediating-actions#2_120) | | []()2\_8059 | `individual.birthData` was missing | [2\_121](/business-accounts/kyc-verification-codes/remediating-actions#2_121) | | []()2\_8060 | `individual.identificationData` was missing | [2\_101](/business-accounts/kyc-verification-codes/remediating-actions#2_101) | | []()2\_8062 | `individual.residentialAddress` was missing | [2\_122](/business-accounts/kyc-verification-codes/remediating-actions#2_122) | | []()2\_8064 | `UBO through ownership` was missing | [2\_123](/business-accounts/kyc-verification-codes/remediating-actions#2_123) | | []()2\_8067 | `Signatory` was missing | [2\_124](/business-accounts/kyc-verification-codes/remediating-actions#2_124) | | []()2\_8069 | `organization.type` was missing | [2\_125](/business-accounts/kyc-verification-codes/remediating-actions#2_125) | | []()2\_8071 | `Identity document` was missing | [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | []()2\_8076 | `Drivers license` was missing | [2\_127](/business-accounts/kyc-verification-codes/remediating-actions#2_127) | | []()2\_8077 | `Front image of drivers license` was missing. | [2\_128](/business-accounts/kyc-verification-codes/remediating-actions#2_128) | | []()2\_8078 | `Back image of drivers license` was missing | [2\_129](/business-accounts/kyc-verification-codes/remediating-actions#2_129) | | []()2\_8079 | `Identity card` was missing | [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | []()2\_8080 | `Back image of identity card` was missing | [2\_131](/business-accounts/kyc-verification-codes/remediating-actions#2_131) | | []()2\_8081 | `Front image of identity card` was missing. | [2\_130](/business-accounts/kyc-verification-codes/remediating-actions#2_130) | | []()2\_8082 | `individual.identificationData.number` was missing | [2\_101](/business-accounts/kyc-verification-codes/remediating-actions#2_101) | | []()2\_8085 | `organization.legalName` was missing | [2\_132](/business-accounts/kyc-verification-codes/remediating-actions#2_132) | | []()2\_8086 | `organization.doingBusinessAs` was missing | [2\_133](/business-accounts/kyc-verification-codes/remediating-actions#2_133) | | []()2\_8087 | `Legal representative` was missing. | [2\_221](/business-accounts/kyc-verification-codes/remediating-actions#2_221) | | []()2\_8100 | `VAT document` was missing | [2\_134](/business-accounts/kyc-verification-codes/remediating-actions#2_134) | | []()2\_8107 | `Proof of residency` was missing | [1\_304](/business-accounts/kyc-verification-codes/remediating-actions#1_304) | | []()2\_8108 | `Continuous payout entity` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8109 | `Full affiliation proof` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8129 | `Name` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8131 | `Type` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8138 | `Passport` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8139 | `Proof of national ID number` was missing | [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | []()2\_8140 | `Proof of address` was missing | [1\_505](/business-accounts/kyc-verification-codes/remediating-actions#1_505) | | []()2\_8141 | `Registration document` was missing | [2\_137](/business-accounts/kyc-verification-codes/remediating-actions#2_137) | | []()2\_8142 | `email` was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8148 | `individual.identificationData.type` was missing | [2\_139](/business-accounts/kyc-verification-codes/remediating-actions#2_139) | | []()2\_8149 | `individual.email` was missing | [2\_152](/business-accounts/kyc-verification-codes/remediating-actions#2_152) | | []()2\_8150 | `phone.number` was missing | [2\_153](/business-accounts/kyc-verification-codes/remediating-actions#2_153) | | []()2\_8151 | `phone.type` was missing | [2\_154](/business-accounts/kyc-verification-codes/remediating-actions#2_154) | | []()2\_8152 | `phone.countryCode` was missing | [2\_155](/business-accounts/kyc-verification-codes/remediating-actions#2_155) | | []()2\_8153 | `entityAssociation.jobTitle` was missing | [2\_156](/business-accounts/kyc-verification-codes/remediating-actions#2_156) | | []()2\_8154 | `bankAccount.accountType` was missing | [2\_140](/business-accounts/kyc-verification-codes/remediating-actions#2_140) | | []()2\_8155 | `bankAccount.bankBicSwift` was missing | [2\_141](/business-accounts/kyc-verification-codes/remediating-actions#2_141) | | []()2\_8156 | `bankAccount.bankCity` was missing | [2\_142](/business-accounts/kyc-verification-codes/remediating-actions#2_142) | | []()2\_8157 | `bankAccount.bankCode` was missing | [2\_143](/business-accounts/kyc-verification-codes/remediating-actions#2_143) | | []()2\_8158 | `bankAccount.bankName` was missing | [2\_144](/business-accounts/kyc-verification-codes/remediating-actions#2_144) | | []()2\_8159 | `bankAccount.checkCode` was missing. | [2\_145](/business-accounts/kyc-verification-codes/remediating-actions#2_145) | | []()2\_8161 | `bankAccount.currencyCode` was missing | [2\_147](/business-accounts/kyc-verification-codes/remediating-actions#2_147) | | []()2\_8162 | `proofOfOrganizationTaxInfo` was missing | [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | []()2\_8163 | `sourceOfFunds` was missing | [2\_159](/business-accounts/kyc-verification-codes/remediating-actions#2_159) | | []()2\_8164 | `businessLine.sourceOfFunds.type` was missing | [2\_160](/business-accounts/kyc-verification-codes/remediating-actions#2_160) | | []()2\_8165 | `businessLine.sourceOfFunds.dateOfFundsReceived` was missing | [2\_161](/business-accounts/kyc-verification-codes/remediating-actions#2_161) | | []()2\_8166 | `businessLine.sourceOfFunds.dateOfSourceEvent` was missing | [2\_162](/business-accounts/kyc-verification-codes/remediating-actions#2_162) | | []()2\_8167 | `businessLine.sourceOfFunds.purpose` was missing | [2\_163](/business-accounts/kyc-verification-codes/remediating-actions#2_163) | | []()2\_8168 | `businessLine.sourceOfFunds.adyenProcessedFunds` was missing | [2\_164](/business-accounts/kyc-verification-codes/remediating-actions#2_164) | | []()2\_8169 | `businessLine.sourceOfFunds.cryptocurrencyExchange` was missing | [2\_165](/business-accounts/kyc-verification-codes/remediating-actions#2_165) | | []()2\_8170 | `businessLine.sourceOfFunds.description` was missing | [2\_166](/business-accounts/kyc-verification-codes/remediating-actions#2_166) | | []()2\_8171 | `businessLine.sourceOfFunds.relationship` was missing | [2\_167](/business-accounts/kyc-verification-codes/remediating-actions#2_167) | | []()2\_8173 | `businessLine.sourceOfFunds.amount` was missing | [2\_169](/business-accounts/kyc-verification-codes/remediating-actions#2_169) | | []()2\_8174 | `taxInformation` was missing | [2\_170](/business-accounts/kyc-verification-codes/remediating-actions#2_170) | | []()2\_8175 | `taxInformation.number` was missing | [2\_170](/business-accounts/kyc-verification-codes/remediating-actions#2_170) | | []()2\_8176 | `taxInformation.type` was missing | [2\_171](/business-accounts/kyc-verification-codes/remediating-actions#2_171) | | []()2\_8177 | `taxInformation.country` was missing | [2\_172](/business-accounts/kyc-verification-codes/remediating-actions#2_172) | | []()2\_8178 | `proofOfIndividualTaxId` was missing | [2\_173](/business-accounts/kyc-verification-codes/remediating-actions#2_173) | | []()2\_8179 | `vatNumber` was missing | [2\_174](/business-accounts/kyc-verification-codes/remediating-actions#2_174) | | []()2\_8180 | `vatDocument` was missing | [2\_175](/business-accounts/kyc-verification-codes/remediating-actions#2_175) | | []()2\_8181 | `industryCode` was missing | [2\_176](/business-accounts/kyc-verification-codes/remediating-actions#2_176) | | []()2\_8182 | `channel` was missing | [2\_177](/business-accounts/kyc-verification-codes/remediating-actions#2_177) | | []()2\_8183 | `webAddress` was missing | [2\_178](/business-accounts/kyc-verification-codes/remediating-actions#2_178) | | []()2\_8184 | `taxReportingClassification` was missing | [2\_179](/business-accounts/kyc-verification-codes/remediating-actions#2_179) | | []()2\_8185 | `taxReportingClassification.type` was missing | [2\_180](/business-accounts/kyc-verification-codes/remediating-actions#2_180) | | []()2\_8186 | `taxReportingClassification.businessType` was missing | [2\_181](/business-accounts/kyc-verification-codes/remediating-actions#2_181) | | []()2\_8187 | `taxReportingClassification.mainSourceOfIncome` was missing | [2\_182](/business-accounts/kyc-verification-codes/remediating-actions#2_182) | | []()2\_8188 | `taxReportingClassification.financialInstitutionNumber` was missing | [2\_183](/business-accounts/kyc-verification-codes/remediating-actions#2_183) | | []()2\_8189 | `UBO through control` was missing | [2\_151](/business-accounts/kyc-verification-codes/remediating-actions#2_151) | | []()2\_8190 | `businessLine` was missing | [2\_136](/business-accounts/kyc-verification-codes/remediating-actions#2_136) | | []()2\_8191 | `businessLine` was missing | [2\_136](/business-accounts/kyc-verification-codes/remediating-actions#2_136) | | []()2\_8192 | `constitutional document` to perform verification was missing | [2\_184](/business-accounts/kyc-verification-codes/remediating-actions#2_184) | | []()2\_8193 | `director` was missing | [2\_185](/business-accounts/kyc-verification-codes/remediating-actions#2_185) | | []()2\_8194 | `settlor` was missing | [2\_186](/business-accounts/kyc-verification-codes/remediating-actions#2_186) | | []()2\_8195 | `definedBeneficiary` was missing | [2\_187](/business-accounts/kyc-verification-codes/remediating-actions#2_187) | | []()2\_8196 | `proofOfOwnership` document to perform verification was missing | [2\_188](/business-accounts/kyc-verification-codes/remediating-actions#2_188) | | []()2\_8197 | `secondaryPartner` was missing | [2\_190](/business-accounts/kyc-verification-codes/remediating-actions#2_190) | | []()2\_8198 | Proof of industry to perform verification was missing | [1\_900](/business-accounts/kyc-verification-codes/remediating-actions#1_900) | | []()2\_8199 | `organization.dateOfIncorporation` was missing | [2\_191](/business-accounts/kyc-verification-codes/remediating-actions#2_191) | | []()2\_8200 | `soleProprietorship.dateOfIncorporation` was missing | [2\_192](/business-accounts/kyc-verification-codes/remediating-actions#2_192) | | []()2\_8201 | `undefinedBeneficiary` was missing | [2\_193](/business-accounts/kyc-verification-codes/remediating-actions#2_193) | | []()2\_8202 | `organization.registeredAddress.postalCode` was missing | [2\_194](/business-accounts/kyc-verification-codes/remediating-actions#2_194) | | []()2\_8203 | `organization.economicSector` was missing | [2\_905](/business-accounts/kyc-verification-codes/remediating-actions#2_905) | | []()2\_8204 | `organization.globalLegalEntityIdentifier` was missing | [2\_909](/business-accounts/kyc-verification-codes/remediating-actions#2_909) | | []()2\_8205 | `organization.stockData` was missing | [2\_903](/business-accounts/kyc-verification-codes/remediating-actions#2_903) | | []()2\_8206 | `organization.stockData.marketIdentifier` was missing | [2\_148](/business-accounts/kyc-verification-codes/remediating-actions#2_148) | | []()2\_8207 | `organization.stockData.stockNumber` was missing | [2\_149](/business-accounts/kyc-verification-codes/remediating-actions#2_149) | | []()2\_8208 | `organization.stockData.tickerSymbol` was missing | [2\_150](/business-accounts/kyc-verification-codes/remediating-actions#2_150) | | []()2\_8209 | Proof of signatory was missing | [1\_800](/business-accounts/kyc-verification-codes/remediating-actions#1_800) | | []()2\_8210 | Live selfie was missing | [2\_215](/business-accounts/kyc-verification-codes/remediating-actions#2_215) | | []()2\_8211 | `organization.registeredAddress.country` was missing | [2\_196](/business-accounts/kyc-verification-codes/remediating-actions#2_196) | | []()2\_8212 | `organization.principalPlaceOfBusiness.country` was missing | [2\_195](/business-accounts/kyc-verification-codes/remediating-actions#2_195) | | []()2\_8213 | `organization.registeredAddress.stateOrProvince` was missing | [2\_198](/business-accounts/kyc-verification-codes/remediating-actions#2_198) | | []()2\_8214 | `organization.principalPlaceOfBusiness.stateOrProvince` was missing | [2\_197](/business-accounts/kyc-verification-codes/remediating-actions#2_197) | | []()2\_8215 | `organization.registeredAddress.street` was missing | [2\_206](/business-accounts/kyc-verification-codes/remediating-actions#2_206) | | []()2\_8216 | `organization.principalPlaceOfBusiness.street` was missing | [2\_199](/business-accounts/kyc-verification-codes/remediating-actions#2_199) | | []()2\_8217 | `organization.registeredAddress.city` was missing | [2\_208](/business-accounts/kyc-verification-codes/remediating-actions#2_208) | | []()2\_8218 | `organization.principalPlaceOfBusiness.city` was missing | [2\_207](/business-accounts/kyc-verification-codes/remediating-actions#2_207) | | []()2\_8219 | `organization.principalPlaceOfBusiness.postalCode` was missing | [2\_209](/business-accounts/kyc-verification-codes/remediating-actions#2_209) | | []()2\_8220 | `organization.registeredAddress.street2` was missing | [2\_210](/business-accounts/kyc-verification-codes/remediating-actions#2_210) | | []()2\_8221 | `organization.principalPlaceOfBusiness.street2` was missing | [2\_211](/business-accounts/kyc-verification-codes/remediating-actions#2_211) | | []()2\_8222 | `trust.description` was missing | [2\_212](/business-accounts/kyc-verification-codes/remediating-actions#2_212) | | []()2\_8223 | `taxInformation` from the `registeredAddress.country` was missing | [2\_213](/business-accounts/kyc-verification-codes/remediating-actions#2_213) | | []()2\_8224 | Proof of funding or wealth source was missing | [2\_214](/business-accounts/kyc-verification-codes/remediating-actions#2_214) | | []()2\_8225 | Institutional sector was missing | [2\_910](/business-accounts/kyc-verification-codes/remediating-actions#2_910) | | []()2\_8226 | Legal form was missing | [2\_906](/business-accounts/kyc-verification-codes/remediating-actions#2_906) | | []()2\_8227 | Status of legal proceedings was missing | [2\_907](/business-accounts/kyc-verification-codes/remediating-actions#2_907) | | []()2\_8228 | Date of initiation of legal proceedings was missing | [2\_908](/business-accounts/kyc-verification-codes/remediating-actions#2_908) | | []()2\_8229 | Head office indicator was missing | [2\_911](/business-accounts/kyc-verification-codes/remediating-actions#2_911) | | []()2\_8230 | CNAE Number was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8231 | `businessLine` was missing | [2\_136](/business-accounts/kyc-verification-codes/remediating-actions#2_136) | | []()2\_8232 | E-invoicing code was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8233 | `Proof of relationship` was missing | [2\_222](/business-accounts/kyc-verification-codes/remediating-actions#2_222) | | []()2\_8234 | `organization.countryOfGoverningLaw` was missing | [2\_223](/business-accounts/kyc-verification-codes/remediating-actions#2_223) | | []()2\_8235 | Legal Form Description was missing | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | []()2\_8236 | Proof of director was missing. | [1\_803](/business-accounts/kyc-verification-codes/remediating-actions#1_803) | | []()2\_8237 | `taxInformation` or `legalArrangement` was missing | [2\_224](/business-accounts/kyc-verification-codes/remediating-actions#2_224) | | []()2\_8238 | Financial report was missing | [2\_225](/business-accounts/kyc-verification-codes/remediating-actions#2_225) | | []()2\_8239 | Number of employees was missing | [2\_226](/business-accounts/kyc-verification-codes/remediating-actions#2_226) | | []()2\_8240 | Balance sheet total was missing | [2\_227](/business-accounts/kyc-verification-codes/remediating-actions#2_227) | | []()2\_8241 | Annual turnover was missing | [2\_228](/business-accounts/kyc-verification-codes/remediating-actions#2_228) | | []()2\_8242 | `businessLine.sourceOfFunds.annualTurnover` was missing. | [2\_229](/business-accounts/kyc-verification-codes/remediating-actions#2_229) | | []()2\_8243 | `businessLine.sourceOfFunds.originatorLegalEntityId` was missing. | [2\_230](/business-accounts/kyc-verification-codes/remediating-actions#2_230) | | []()2\_8244 | `businessLine.sourceOfFunds.financiers` was missing. | [2\_231](/business-accounts/kyc-verification-codes/remediating-actions#2_231) | | []()2\_8245 | `businessLine.sourceOfFunds.website` was missing. | [2\_232](/business-accounts/kyc-verification-codes/remediating-actions#2_232) | | []()2\_8246 | `legalArrangement.doingBusinessAs` was missing. | [2\_233](/business-accounts/kyc-verification-codes/remediating-actions#2_233) | | []()2\_8247 | `organization.support.email` was missing. | [2\_234](/business-accounts/kyc-verification-codes/remediating-actions#2_234) | | []()2\_8248 | `individual.support.email was missing` was missing. | [2\_235](/business-accounts/kyc-verification-codes/remediating-actions#2_235) | | []()2\_8249 | `organization.support.phone.number` was missing. | [2\_236](/business-accounts/kyc-verification-codes/remediating-actions#2_236) | | []()2\_8250 | `individual.support.phone.number` was missing. | [2\_237](/business-accounts/kyc-verification-codes/remediating-actions#2_237) | | []()2\_8251 | Financial report currency was missing. | [2\_228](/business-accounts/kyc-verification-codes/remediating-actions#2_228) | | []()2\_8252 | Proof of identity verification report was missing. | [2\_239](/business-accounts/kyc-verification-codes/remediating-actions#2_239) | | []()2\_8253 | Additional due diligence was missing. | [2\_240](/business-accounts/kyc-verification-codes/remediating-actions#2_240) | | []()2\_8254 | Business line and activity verification was missing. | [2\_241](/business-accounts/kyc-verification-codes/remediating-actions#2_241) | | []()2\_8255 | Credit underwriting document was missing. | [2\_242](/business-accounts/kyc-verification-codes/remediating-actions#2_242) | ## Missing contracts | General error code | Message | Remediating action code | | ------------------ | --------------------------------------- | ----------------------------------------------------------------------------- | | []()2\_901 | PCI forms are not signed | [2\_901](/business-accounts/kyc-verification-codes/remediating-actions#2_901) | | []()2\_902 | Terms Of Service forms are not accepted | [2\_902](/business-accounts/kyc-verification-codes/remediating-actions#2_902) | | []()2\_904 | Integration is not fully implemented | [2\_904](/business-accounts/kyc-verification-codes/remediating-actions#2_904) | ### Data review errors | General error code | Message | Remediating action code | | ------------------ | -------------------------- | ----------------------------------------------------------------------------- | | []()3\_10 | Review of data is required | [3\_100](/business-accounts/kyc-verification-codes/remediating-actions#3_100) | ## General verification errors array example **Example problems array** ```json { ... "problems": [ { "entity": { "id": "LE00000000000000000000001", "type": "LegalEntity" }, "verificationErrors": [ { "code": "1_30", "message": "Individual details couldn't be verified", "{hint:Sent when there is a common remediating action}remediatingActions{/hint}": [ { "code": "1_300", "message": "Update individual details" } ], "subErrors": [...] } ] } ] } ``` --- # Source: https://docs.adyen.com/business-accounts/kyc-verification-codes/remediating-actions.md Section: Business accounts Title: Remediating action codes --- title: "Remediating action codes" url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/remediating-actions" source_url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/remediating-actions.md" canonical: "https://docs.adyen.com/business-accounts/kyc-verification-codes/remediating-actions" last_modified: "2021-01-19T09:45:00+01:00" language: "en" --- # Remediating action codes [View source](/business-accounts/kyc-verification-codes/remediating-actions.md) Remediating actions provide instructions to resolve an error. There can be multiple remediating actions to resolve an error. Whenever possible, Adyen sends remediation codes and messages within the following: * `verificationErrors` array. The remediating actions are only sent in this array when there are common actions for the `subErrors`. * `subErrors` array. ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen Issuing](/issuing) integration, there are no additional requirements, limitations, or preparations. ## Types of error codes The range of remediation codes are divided into the types of issues. * **1\_1xx**: [Remediation for general issues](#general-codes) * **1\_3xx**: [Remediation for individual check issues](#individual-checks) * **1\_5xx**: [Remediation for organization check issues](#organization-checks) * **1\_6xx**: [Remediation for legal arrangement issues](#legal-checks) * **1\_7xx**: [Remediation for bank account check issues](#bank-checks) * **1\_8xx**: [Remediation for proof of signatory checks](#proof-of-signatory) * **1\_9xx**: [Remediation for business line check issues](#bl-checks) * **2\_1xx** - **2\_2xx**: [Remediation for missing data issues](#missing-data) * **2\_9xx**: [Remediation for contract issues](#missing-contracts) * **3\_1xx**: [Remediating for data review issues](#data-review) ## General remediation codes | Remediating action code | Message | | | ----------------------- | --------------------------- | - | | []()1\_100 | No remediation possible | | | []()1\_101 | Contact Support | | | []()1\_102 | Upload a different document | | ## Individual checks | Remediating action code | Message | | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_300 | Update individual details | | | []()1\_301 | Upload an ID document | | | []()1\_302 | Upload a different ID document | | | []()1\_303 | Upload a different image of the ID document | | | []()1\_304 | Upload proof of residency | | | []()1\_305 | Upload a different proof of residency | | | []()1\_306 | Upload a different image of the proof of residency | | | []()1\_307 | Upload a proof of national ID number | | | []()1\_308 | Upload a different proof of national ID number | | | []()1\_309 | Upload a different image of the proof of national ID number | | | []()1\_310 | Update the name (Katakana) with only full-width Katakana characters and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_311 | Update the name (Kanji) with only full-width Katakana, Kanji or Latin characters, and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_312 | Update the residency street in full-width Kanji and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_313 | Upload a different image of the proof of the individual tax ID | | | []()1\_314 | Upload a proof of the individual tax ID | | | []()1\_315 | Upload a different proof of the individual tax ID | | | []()1\_316 | Update the national Id number to a 9 digit SSN | | | []()1\_317 | Upload a different live selfie | | | []()1\_318 | Upload a different photo ID document | | | []()1\_319 | Update individual details | | | []()1\_320 | Upload proof of residency | | | []()1\_321 | Update the residential address | | ## Organization checks | Remediating action code | Message | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | | []()1\_500 | Update organization details | | | []()1\_501 | Upload a registration document | | | []()1\_502 | Upload a different registration document | | | []()1\_503 | Upload a `proofOfOrganizationTaxInfo` | | | []()1\_504 | Upload a different `proofOfOrganizationTaxInfo` | | | []()1\_505 | Upload a proof of address | | | []()1\_506 | Upload a different proof of address | | | []()1\_507 | Update organization ownership details | | | []()1\_508 | Upload a proof of ownership | | | []()1\_510 | Ensure signing person has the rights to represent the organization or is a listed professional member (lawyer, accountant) in your country of business and upload the right document | | | []()1\_511 | Upload a document that proves the payout entity is 100% affiliated with the legal entity | | | []()1\_512 | Upload a VAT document | | | []()1\_513 | Upload a different VAT document | | | []()1\_514 | Update the organization name (Katakana) with only full-width Katakana characters and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_515 | Update the organization name (Kanji) with only full-width Katakana, Kanji or Latin characters, and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_516 | Update the registered street in full-width Kanji and remove any invalid characters such as spaces, restricted or special characters | | | []()1\_518 | Update organization `legalName` | | | []()1\_519 | Update source of funds | | | []()1\_520 | Upload a proof of source of funds | | | []()1\_521 | Upload a different proof of source of funds | | | []()1\_522 | Add a director | | | []()1\_523 | Update organization details | | | []()1\_524 | Make sure the registered business address is correct, and that the principal place of business address is a physical, non-PO box address | | | []()1\_525 | Add the physical address of the principal place of business | | ## Legal arrangement checks The actual error message will correspond to the specific type of legal arrangement. For example, "Update `sole proprietership` details." | Remediating action code | Message | | | ----------------------- | ------------------------------------------------------ | - | | []()1\_600 | Update legal arrangement details | | | []()1\_601 | Upload a constitutional document | | | []()1\_602 | Upload a different constitutional document | | | []()1\_603 | Update legal arrangement's affiliated member's details | | ## Bank account checks | Remediating action code | Message | | ----------------------- | -------------------------------- | | []()1\_700 | Update bank account details | | []()1\_701 | Use different bank account | | []()1\_703 | Upload a bank statement | | []()1\_704 | Upload a different bank document | | []()1\_705 | Upload an official bank document | ## Proof of signatory checks | Remediating action code | Message | | ----------------------- | --------------------------------------------------- | | []()1\_800 | Upload a proof of signatory | | []()1\_801 | Upload a different proof of signatory | | []()1\_802 | Update signatory details | | []()1\_803 | Upload a proof of director document to legal entity | | []()1\_804 | Upload a different proof of director document | | []()1\_805 | Update director details | ## Business lines checks | Remediating action code | Message | | ----------------------- | ---------------------------------------------------------------------------------- | | []()1\_900 | Upload a proof of industry | | []()1\_901 | Update industry | | []()1\_902 | Update the web address with a website or application that represents your business | | []()1\_903 | Upload a different proof of industry | | []()1\_904 | Upload a different image of the proof of industry | | []()1\_905 | Add `webData.webAddress` to business line | ## Missing data The following remediation codes may be returned when the error type is **dataMissing**. | Remediating action code | Message | | ----------------------- | ----------------------------------------------------------------------------------- | | []()2\_101 | Add `individual.identificationData` to legal entity | | []()2\_102 | Add `individual.name.firstName` to legal entity | | []()2\_103 | Add `individual.name.lastName` to legal entity | | []()2\_104 | Add `individual.residentialAddress.country` to legal entity | | []()2\_105 | Add `individual.residentialAddress.stateOrProvince` to legal entity | | []()2\_106 | Add `individual.residentialAddress.street` to legal entity | | []()2\_107 | Add `individual.residentialAddress.city` to legal entity | | []()2\_108 | Add `individual.residentialAddress.postalCode` to legal entity | | []()2\_109 | Add `individual.residentialAddress.street2` to legal entity | | []()2\_110 | Add `individual.nationality` to legal entity | | []()2\_112 | Add `individual.birthData.dateOfBirth` to legal entity | | []()2\_113 | Add `bankAccount.iban` to bank account | | []()2\_114 | Add `bankAccount.accountNumber` to bank account | | []()2\_115 | Add bank account | | []()2\_116 | Add `bankAccount.branchCode` to bank account | | []()2\_117 | Add `organization.registrationNumber` to legal entity | | []()2\_118 | Add `organization.taxId` to legal entity | | []()2\_119 | Add `attachments` to document | | []()2\_120 | Add `individual.name` to legal entity | | []()2\_121 | Add `individual.birthData` to legal entity | | []()2\_122 | Add `individual.residentialAddress` to legal entity | | []()2\_123 | Add `organization.entityAssociations` of type `uboThroughOwnership` to legal entity | | []()2\_124 | Add `organization.entityAssociations` of type `signatory` to legal entity | | []()2\_125 | Add `organization.type` to legal entity | | []()2\_126 | Upload a document | | []()2\_127 | Upload a drivers license | | []()2\_128 | Upload the front of a drivers license | | []()2\_129 | Upload the back of a drivers license | | []()2\_130 | Upload the front of an identity card | | []()2\_131 | Upload the back of an identity card | | []()2\_132 | Add `organization.legalName` to legal entity | | []()2\_133 | Add `organization.doingBusinessAs` to legal entity | | []()2\_134 | Upload a VAT document | | []()2\_135 | Add `bankAccount.sortCode` to bank account | | []()2\_136 | Add business line | | []()2\_137 | Upload a proof of registration | | []()2\_138 | Add `individual.identificationData.number` to legal entity | | []()2\_139 | Add `individual.identificationData.type` to legal entity | | []()2\_140 | Add `bankAccount.accountType` to bank account | | []()2\_141 | Add `bankAccount.bankBicSwift` to bank account | | []()2\_142 | Add `bankAccount.bankCity` to bank account | | []()2\_143 | Add `bankAccount.bankCode` to bank account | | []()2\_144 | Add `bankAccount.bankName` to bank account | | []()2\_145 | Add `bankAccount.checkCode` to bank account | | []()2\_146 | Add `bankAccount.bankCountry` to bank account | | []()2\_147 | Add `bankAccount.currencyCode` to bank account | | []()2\_148 | Add `organization.stockData.marketIdentifier` to legal entity | | []()2\_149 | Add `organization.stockData.stockNumber` to legal entity | | []()2\_150 | Add `organization.stockData.tickerSymbol` to legal entity | | []()2\_151 | Add `organization.entityAssociations` of type `uboThroughControl` to legal entity | | []()2\_152 | Add `individual.email` to legal entity | | []()2\_153 | Add `phone.number` to legal entity | | []()2\_154 | Add `phone.type` to legal entity | | []()2\_155 | Add `phone.countryCode` to legal entity | | []()2\_156 | Add `entityAssociation.jobTitle` to legal entity | | []()2\_157 | Upload a passport | | []()2\_158 | Add `organization.vatNumber` to legal entity | | []()2\_159 | Add source of funds to business line | | []()2\_160 | Add `businessLine.sourceOfFunds.type` to business line | | []()2\_161 | Add `businessLine.sourceOfFunds.dateOfFundsReceived` to business line | | []()2\_162 | Add `businessLine.sourceOfFunds.dateOfSourceEvent` to business line | | []()2\_163 | Add `businessLine.sourceOfFunds.purpose` to business line | | []()2\_164 | Add `businessLine.sourceOfFunds.adyenProcessedFunds` to business line | | []()2\_165 | Add `businessLine.sourceOfFunds.cryptocurrencyExchange` to business line | | []()2\_166 | Add `businessLine.sourceOfFunds.description` to business line | | []()2\_167 | Add `businessLine.sourceOfFunds.relationship` to business line | | []()2\_169 | Add `businessLine.sourceOfFunds.amount` to business line | | []()2\_170 | Add tax information to legal entity | | []()2\_171 | Add `taxInformation.number` to legal entity | | []()2\_172 | Add `taxInformation.type` to legal entity | | []()2\_173 | Add `taxInformation.country` to legal entity | | []()2\_174 | Add `proofOfIndividualTaxId` to legal entity | | []()2\_175 | Add `vatDocument` to legal entity | | []()2\_176 | Add `industryCode` to business line | | []()2\_177 | Add `channel` to business line | | []()2\_178 | Add `webAddress` to business line | | []()2\_179 | Add `taxReportingClassification` to legal entity | | []()2\_180 | Add `taxReportingClassification.type` to legal entity | | []()2\_181 | Add `taxReportingClassification.businessType` to legal entity | | []()2\_182 | Add `taxReportingClassification.mainSourceOfIncome` to legal entity | | []()2\_183 | Add `taxReportingClassification.financialInstitutionNumber` to legal entity | | []()2\_184 | Add constitutional document for verification to legal entity | | []()2\_185 | Add `organization.entityAssociations` of type `director` to legal entity | | []()2\_186 | Add `trust.entityAssociations` of type `settlor` to legal entity | | []()2\_187 | Add `trust.entityAssociations` of type `definedBeneficiary` to legal entity | | []()2\_188 | Add `proofOfOwnership` document document for verification to legal entity | | []()2\_189 | Add `soleProprietorship.registrationNumber` to legal entity | | []()2\_190 | Add `partnership.entityAssociations` of type `secondaryPartner` to legal entity | | []()2\_191 | Add `organization.dateOfIncorporation` to legal entity | | []()2\_192 | Add `soleProprietorship.dateOfIncorporation` to legal entity | | []()2\_193 | Add `trust.entityAssociations` of type `undefinedBeneficiary` to legal entity | | []()2\_194 | Add `organization.registeredAddress.postalCode` to legal entity | | []()2\_195 | Add `organization.principalPlaceOfBusiness.country` to legal entity | | []()2\_196 | Add `organization.registeredAddress.country` to legal entity | | []()2\_197 | Add `organization.principalPlaceOfBusiness.stateOrProvince` to legal entity | | []()2\_198 | Add `organization.registeredAddress.stateOrProvince` to legal entity | | []()2\_198 | Add `organization.principalPlaceOfBusiness.street` to legal entity | | []()2\_206 | Add `organization.registeredAddress.street` to legal entity | | []()2\_207 | Add `organization.principalPlaceOfBusiness.city` to legal entity | | []()2\_208 | Add `organization.registeredAddress.city` to legal entity | | []()2\_209 | Add `organization.principalPlaceOfBusiness.postalCode` to legal entity | | []()2\_210 | Add `organization.registeredAddress.street2` to legal entity | | []()2\_211 | Add `organization.principalPlaceOfBusiness.street2` to legal entity | | []()2\_212 | Add `trust.description` to legal entity | | []()2\_213 | Add `taxInformation` from the `registeredAddress.country` to legal entity | | []()2\_214 | Upload a proof of funding or wealth source | | []()2\_215 | Upload a live selfie | | []()2\_216 | Update Legal Entity Type | | []()2\_217 | Add tax information to legal entity | | []()2\_218 | Add `taxInformation.number` to legal entity | | []()2\_219 | Add `taxInformation.type` to legal entity | | []()2\_220 | Add `taxInformation.country` to legal entity | | []()2\_221 | Add `individual.entityAssociations` of type `legalRepresentative` to legal entity | | []()2\_222 | Upload a proof of relationship to individual | | []()2\_223 | Add `organization.countryOfGoverningLaw` to legal entity | | []()2\_224 | Add `taxInformation` or `legalArrangement` to legal entity | | []()2\_225 | Add financial report to legal entity | | []()2\_226 | Provide number of employees for legal entity | | []()2\_227 | Provide balance sheet total for legal entity | | []()2\_228 | Provide annual turnover for legal entity | | []()2\_229 | Add `businessLine.sourceOfFunds.annualTurnover` to business line | | []()2\_230 | Add `businessLine.sourceOfFunds.originatorLegalEntityId` to business line | | []()2\_231 | Add `businessLine.sourceOfFunds.financiers` to business line | | []()2\_232 | Add `businessLine.sourceOfFunds.website` to business line | | []()2\_233 | Add `legalArrangement.doingBusinessAs` to legal entity | | []()2\_234 | Add `organization.support.email` to legal entity | | []()2\_235 | Add `individual.support.email` to legal entity | | []()2\_236 | Add `organization.support.phone.number` to legal entity | | []()2\_237 | Add `individual.support.phone.number` to legal entity | ## Missing contracts | Remediating action code | Message | | ----------------------- | --------------------------------------------- | | []()2\_901 | Sign PCI | | []()2\_902 | Accept TOS | | []()2\_903 | Add `organization.stockData` to legal entity. | | []()2\_904 | Contact support | ### Data review | Remediating action code | Message | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | []()3\_100 | Use the [/legalEntities/{id}/confirmDataReview](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/confirmDataReview) to indicate that the data is confirmed | ## Remediating actions array example **Example remediating actions array** ```json { ... "problems":[ { ... "verificationErrors":[ { "code":"1_30", "message":"Individual details couldn't be verified", "{hint:Sent when there is a common remediating action}remediatingActions{/hint}":[ { "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" } ] } ] ... } ``` --- # Source: https://docs.adyen.com/business-accounts/kyc-verification-codes/sub-errors.md Section: Business accounts Title: Suberror codes --- title: "Suberror codes" url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/sub-errors" source_url: "https://docs.adyen.com/business-accounts/kyc-verification-codes/sub-errors.md" canonical: "https://docs.adyen.com/business-accounts/kyc-verification-codes/sub-errors" last_modified: "2023-02-28T10:52:00+01:00" language: "en" --- # Suberror codes [View source](/business-accounts/kyc-verification-codes/sub-errors.md) Suberrors are more granular error codes that you can use to provide the specific cause of a verification error. Adyen sends the general error codes and messages in the `subErrors` array. When applicable, an entry contains [remediating actions](/business-accounts/kyc-verification-codes/remediating-actions) that you can use to resolve the KYC error. ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen Issuing](/issuing) integration, there are no additional requirements, limitations, or preparations. ## Types of error codes The range of error codes are divided into the types of check. * **1\_1xxx**: [General issues](#general-issues) * **1\_3xxx**: [Issues with the individual check](#individual-check) * **1\_5xxx**: [Issues with the organization check](#organization-check) * **1\_6xxx**: [Issues with the legal arrangement check](#legal-check) * **1\_7xxx**: [Issues with the bank account check](#bank-check) * **1\_8xxx**: [Issues with the proof of signatory check](#proof-of-signatory-check) * **1\_9xxx**: [Issues with the business line check](#bl-check) ## General issues | Suberror code | Message | Remediating action codes | | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | | []()1\_1000 | Verification failed. Legal entity declined | [1\_101](/business-accounts/kyc-verification-codes/remediating-actions#1_101) | | | []()1\_1001 | There were some technical issues in the verification process | [1\_101](/business-accounts/kyc-verification-codes/remediating-actions#1_101) | | | []()1\_1002 | There are more questions about the submitted information | [1\_101](/business-accounts/kyc-verification-codes/remediating-actions#1_101) | | | []()1\_1003 | The document contained sensitive data | [1\_102](/business-accounts/kyc-verification-codes/remediating-actions#1_102) | | | []()1\_1004 | Required information is missing | [1\_102](/business-accounts/kyc-verification-codes/remediating-actions#1_102), [1\_101](/business-accounts/kyc-verification-codes/remediating-actions#1_101) | | ## Individual identity check | Suberror code | Message | Remediating action codes | | | ------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_3000 | The user couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | | []()1\_3001 | The name and date of birth couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | | []()1\_3002 | The name and national ID number couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | | []()1\_3003 | The name and residence state couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3004 | The name and residence country couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | | []()1\_3005 | The national ID number was entered incorrectly | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | | []()1\_3006 | The name didn't match the national ID number | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | | []()1\_3007 | An incorrect national ID number was entered | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | | []()1\_3008 | The ID document image was incomplete | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3009 | The photo on the ID document couldn't be recognized | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3010 | The ID document image was incomplete or too blurry | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3011 | The ID document image was in black and white | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3012 | The image couldn't be recognized as a supported ID document | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3013 | The ID document wasn't a supported document type | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3014 | The ID document image didn't contain the MRZ code | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3015 | The ID document was expired | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3016 | The ID document image was of too low quality | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3017 | The ID document image was a scan | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3018 | The ID document image was too blurry | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3019 | The ID document was expired | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3020 | The ID document wasn't a supported document type | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3021 | The ID document MRZ code is unreadable | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3022 | The ID document image only showed one side of the ID document | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3023 | The ID document image only showed parts of the ID document | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3024 | The ID document wasn't valid | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3025 | The state didn't match the one on the ID document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_304](/business-accounts/kyc-verification-codes/remediating-actions#1_304), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3026 | The ID document didn't show an issuing state | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_304](/business-accounts/kyc-verification-codes/remediating-actions#1_304) | | | []()1\_3027 | The ID document wasn't valid | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3028 | The ID number didn't match the one on the document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3029 | The ID document didn't show a document number | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_307](/business-accounts/kyc-verification-codes/remediating-actions#1_307) | | | []()1\_3030 | The ID document wasn't valid | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3031 | The ID document wasn't valid | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3032 | The first name didn't match the one on the ID document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3033 | The last name didn't match the one on the ID document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3034 | The date of birth didn't match the one on the ID document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3035 | The country didn't match the one on the ID document | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_304](/business-accounts/kyc-verification-codes/remediating-actions#1_304), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3036 | The ID document image was too low quality | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303) | | | []()1\_3037 | The last name didn't match the one on the proof of residential address | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3038 | The first name didn't match the one on the proof of residential address | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3039 | The date of birth didn't match the one on the proof of residential address | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3040 | The proof of residential address didn't show the date it was issued | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3041 | The proof of residential address didn't show a name | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3042 | The proof of residential address didn't show an issuing country | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3043 | The proof of residential address wasn't a supported document type | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3044 | The proof of residential address was too old | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3045 | The proof of residential address image was of too low quality | [1\_306](/business-accounts/kyc-verification-codes/remediating-actions#1_306) | | | []()1\_3046 | The address on the proof of residential address was a PO box | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3047 | The proof of national ID number wasn't a supported document type | [1\_308](/business-accounts/kyc-verification-codes/remediating-actions#1_308) | | | []()1\_3048 | The last name didn't match the one on the proof of national ID number | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_308](/business-accounts/kyc-verification-codes/remediating-actions#1_308) | | | []()1\_3049 | The first name didn't match the one on the proof of national ID number | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_308](/business-accounts/kyc-verification-codes/remediating-actions#1_308) | | | []()1\_3050 | The date of birth didn't match the one on the proof of national ID number | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_308](/business-accounts/kyc-verification-codes/remediating-actions#1_308) | | | []()1\_3051 | The proof of national ID number image was of too low quality | [1\_309](/business-accounts/kyc-verification-codes/remediating-actions#1_309) | | | []()1\_3052 | An ID document is needed to verify the individual | [1\_301](/business-accounts/kyc-verification-codes/remediating-actions#1_301) | | | []()1\_3053 | The name (Katakana) couldn't be verified due to invalid characters | [1\_310](/business-accounts/kyc-verification-codes/remediating-actions#1_310) | | | []()1\_3054 | The name (Kanji) couldn't be verified due to invalid characters | [1\_311](/business-accounts/kyc-verification-codes/remediating-actions#1_311) | | | []()1\_3055 | The residency address couldn't be verified due to invalid characters. | [1\_312](/business-accounts/kyc-verification-codes/remediating-actions#1_312) | | | []()1\_3056 | The proof of the individual tax ID image was of too low quality | [1\_313](/business-accounts/kyc-verification-codes/remediating-actions#1_313) | | | []()1\_3057 | The name didn't match the individual tax ID | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3058 | The individual tax ID was entered incorrectly | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3059 | The proof of the individual tax ID wasn't a supported document type | [1\_315](/business-accounts/kyc-verification-codes/remediating-actions#1_315) | | | []()1\_3060 | The last name didn't match the one on the proof of the individual tax ID | [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314), [1\_315](/business-accounts/kyc-verification-codes/remediating-actions#1_315) | | | []()1\_3061 | The first name didn't match the one on the proof of the individual tax ID | [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314), [1\_315](/business-accounts/kyc-verification-codes/remediating-actions#1_315) | | | []()1\_3062 | The name and 4 digit SSN couldn't be verified | [1\_316](/business-accounts/kyc-verification-codes/remediating-actions#1_316) | | | []()1\_3063 | The date of birth didn't match the one on the proof of the individual tax ID | [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314), [1\_315](/business-accounts/kyc-verification-codes/remediating-actions#1_315) | | | []()1\_3064 | The name and individual tax ID couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3065 | The submitted individual tax ID does not match the tax id number of the document | [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3066 | The submitted identity document does not display a tax ID number | [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3067 | The tax ID number could not be verified as the identity document is not valid | [1\_303](/business-accounts/kyc-verification-codes/remediating-actions#1_303), [1\_314](/business-accounts/kyc-verification-codes/remediating-actions#1_314) | | | []()1\_3068 | The name and postal code of the residency address couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_319](/business-accounts/kyc-verification-codes/remediating-actions#1_319), [1\_320](/business-accounts/kyc-verification-codes/remediating-actions#1_320) | | | []()1\_3069 | The postal code didn't match the one on the proof of national ID number | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_319](/business-accounts/kyc-verification-codes/remediating-actions#1_319), [1\_320](/business-accounts/kyc-verification-codes/remediating-actions#1_320) | | | []()1\_3070 | The postal code didn't match the one on the proof of residential address | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3071 | The proof of residential address didn't show the postal code | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_3072 | The name and nationality couldn't be verified | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_319](/business-accounts/kyc-verification-codes/remediating-actions#1_319) | | | []()1\_3073 | The ID document didn't show the nationality | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3074 | No face detected in either the ID document or selfie | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_317](/business-accounts/kyc-verification-codes/remediating-actions#1_317) | | | []()1\_3075 | No face detected in live selfie | [1\_317](/business-accounts/kyc-verification-codes/remediating-actions#1_317) | | | []()1\_3076 | No face detected in ID document | [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3077 | There is no face match between the ID document and selfie | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302), [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3078 | Photo was not taken by the individual | [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3079 | Photo of the individual was taken involuntarily | [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3080 | Selfie was not taken in real time | [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3081 | Image couldn't be processed due to unsupported file format or document type | [1\_318](/business-accounts/kyc-verification-codes/remediating-actions#1_318) | | | []()1\_3082 | The individual does not meet the minimum age requirement | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | | []()1\_3083 | The name or residential address couldn't be verified | [1\_319](/business-accounts/kyc-verification-codes/remediating-actions#1_319), [1\_320](/business-accounts/kyc-verification-codes/remediating-actions#1_320) | | | []()1\_3084 | The name or residential address does not match the proof of residential address | [1\_319](/business-accounts/kyc-verification-codes/remediating-actions#1_319), [1\_320](/business-accounts/kyc-verification-codes/remediating-actions#1_320) | | | []()1\_3085 | No face detected in either the ID document or motion capture | [1\_321](/business-accounts/kyc-verification-codes/remediating-actions#1_321) | | | []()1\_3086 | There is no face match between the ID document and motion capture | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3087 | The required motion capture actions were not completed correctly | [1\_302](/business-accounts/kyc-verification-codes/remediating-actions#1_302) | | | []()1\_3088 | The residential address is a P.O. Box | [1\_300](/business-accounts/kyc-verification-codes/remediating-actions#1_300), [1\_321](/business-accounts/kyc-verification-codes/remediating-actions#1_321) | | ## Organization check | Suberror code | Message | Remediating action codes | | | ------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | []()1\_5000 | The legal business name couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503), [1\_800](/business-accounts/kyc-verification-codes/remediating-actions#1_800) | | | []()1\_5001 | The tax ID number couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5002 | The state couldn't be verified | [1\_505](/business-accounts/kyc-verification-codes/remediating-actions#1_505), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5003 | The legal name didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_505](/business-accounts/kyc-verification-codes/remediating-actions#1_505), [1\_800](/business-accounts/kyc-verification-codes/remediating-actions#1_800) | | | []()1\_5004 | The legal name didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5005 | The legal name didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5006 | The country didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5007 | The registration number didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5008 | The tax ID didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5009 | The registration number was provided as tax ID | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5010 | The company details couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5011 | The trade name (doing business as) was entered | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5012 | The submitted company type didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5013 | The company was not found in the database | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5014 | The registration number couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5015 | The registration number didn't match the legal business name | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5016 | The tax ID number couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5017 | The tax ID number didn't match the legal business name | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5018 | The business address couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5019 | The trade name (doing business as) was entered | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5020 | Registration document is missing | [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501) | | | []()1\_5021 | The registration document was too low quality. | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502) | | | []()1\_5022 | The registration document was too old | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502) | | | []()1\_5023 | The submitted company type didn't match the one on the registration document | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502) | | | []()1\_5024 | The registration document did not show the company type | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5025 | The address on the company registration document was a residential address | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5026 | The address on the company registration document was a PO box | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5027 | The business address didn't match the one on the company registration document | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5028 | The registration number didn't match the one on the company registration document | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5029 | The legal business name didn't match the one on the company registration document | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5030 | The country didn't match the one on the company registration document | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5031 | The company registration document didn't show a legal business name | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502) | | | []()1\_5032 | The company registration document didn't show a registration number | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502) | | | []()1\_5033 | The state didn't match the one on the company registration document | [1\_505](/business-accounts/kyc-verification-codes/remediating-actions#1_505), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5034 | The company registration document wasn't a supported document type | [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5035 | The company registration document is not supported. | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5036 | Tax document is missing | [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5037 | The country didn't match the one on the tax document. | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5038 | The tax document wasn't a supported document type. | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5039 | The tax document was too low quality | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5040 | The tax document was too old. | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5041 | The legal name didn't match the one on the tax document | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5042 | The tax ID number didn't match the legal business name | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503) | | | []()1\_5043 | The tax document didn't show a tax ID number | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5044 | The tax document didn't show a legal business name | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5045 | The state didn't match the one on the proof of address | [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5046 | Ownership data seems incorrect | [1\_508](/business-accounts/kyc-verification-codes/remediating-actions#1_508), [1\_507](/business-accounts/kyc-verification-codes/remediating-actions#1_507) | | | []()1\_5047 | Ownership data seems to be missing | [1\_508](/business-accounts/kyc-verification-codes/remediating-actions#1_508), [1\_507](/business-accounts/kyc-verification-codes/remediating-actions#1_507) | | | []()1\_5048 | Provide official ownership documentation | [1\_508](/business-accounts/kyc-verification-codes/remediating-actions#1_508) | | | []()1\_5049 | The affiliation document was not sufficient to prove the 100% affiliation | [1\_511](/business-accounts/kyc-verification-codes/remediating-actions#1_511) | | | []()1\_5050 | The affiliation document was not official | [1\_509](/business-accounts/kyc-verification-codes/remediating-actions#1_509) | | | []()1\_5051 | Signing person on the affiliation document could not be verified | [1\_510](/business-accounts/kyc-verification-codes/remediating-actions#1_510) | | | []()1\_5052 | The affiliation document verifies the payout entity is not 100% affiliated with the company. Setup cannot be continued | [1\_100](/business-accounts/kyc-verification-codes/remediating-actions#1_100) | | | []()1\_5053 | The affiliation document was not issued within the last 6 months | [1\_509](/business-accounts/kyc-verification-codes/remediating-actions#1_509) | | | []()1\_5054 | The VAT number couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5055 | VAT document is missing | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5056 | The VAT document was too low quality | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5057 | The VAT document wasn't a supported document type | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5058 | The VAT document was too old | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5059 | The VAT document didn't show a legal name | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5060 | The VAT document didn't show a VAT number | [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5061 | The country didn't match the one on the VAT document | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5062 | The legal name didn't match the one on the VAT document | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5063 | The organization VAT details couldn't be verified | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5064 | The VAT number didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5065 | The registration number was provided as VAT number | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5066 | The trade name (doing business as) was entered instead of the legal name | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_513](/business-accounts/kyc-verification-codes/remediating-actions#1_513) | | | []()1\_5067 | The legal name didn't match the one on the VAT registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_512](/business-accounts/kyc-verification-codes/remediating-actions#1_512) | | | []()1\_5071 | The registered city didn't match the one on the proof of address | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5072 | The registered city didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5073 | Proof of address is missing | [1\_505](/business-accounts/kyc-verification-codes/remediating-actions#1_505) | | | []()1\_5074 | The proof of address didn't show a business legal name | [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5075 | The proof of address didn't show the registered city | [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5076 | The organization tax ID document didn't show a business legal name | [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5077 | The organization tax ID number didn't match the legal business name | [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5078 | The legal name couldn't be verified | [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5079 | The submitted organization tax ID number does not exist | [1\_503](/business-accounts/kyc-verification-codes/remediating-actions#1_503), [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500) | | | []()1\_5080 | The postal code of the registered address does not match legal name | [1\_517](/business-accounts/kyc-verification-codes/remediating-actions#1_517) | | | []()1\_5081 | The postal code didn't match the one on the proof of address | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5082 | The postal code the didn't match the one on the registry | [1\_500](/business-accounts/kyc-verification-codes/remediating-actions#1_500), [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5083 | The proof of address didn't show postal code | [1\_506](/business-accounts/kyc-verification-codes/remediating-actions#1_506) | | | []()1\_5084 | The date of incorporation couldn't be verified | [1\_501](/business-accounts/kyc-verification-codes/remediating-actions#1_501), [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_523](/business-accounts/kyc-verification-codes/remediating-actions#1_523) | | | []()1\_5085 | The registration document didn't show the Date of Incorporation | [1\_502](/business-accounts/kyc-verification-codes/remediating-actions#1_502), [1\_504](/business-accounts/kyc-verification-codes/remediating-actions#1_504) | | | []()1\_5086 | ISIN number couldn't be verified | [2\_200](/business-accounts/kyc-verification-codes/remediating-actions#2_200) | | | []()1\_5087 | Ticker symbol number couldn't be verified | [2\_201](/business-accounts/kyc-verification-codes/remediating-actions#2_201) | | | []()1\_5088 | Market identifier code couldn't be verified | [2\_202](/business-accounts/kyc-verification-codes/remediating-actions#2_202) | | | []()1\_5089 | ISIN number didn't match the legal name | [2\_203](/business-accounts/kyc-verification-codes/remediating-actions#2_203) | | | []()1\_5090 | Ticker symbol didn't match the legal name | [2\_204](/business-accounts/kyc-verification-codes/remediating-actions#2_204) | | | []()1\_5091 | Market identifier code didn't match the legal name | [2\_205](/business-accounts/kyc-verification-codes/remediating-actions#2_205) | | | []()1\_5092 | Residential address not shown on the document | [1\_305](/business-accounts/kyc-verification-codes/remediating-actions#1_305) | | | []()1\_5093 | The residential address is a P.O. Box | [1\_524](/business-accounts/kyc-verification-codes/remediating-actions#1_524) | | | []()1\_5094 | The principal place of business was missing | [1\_321](/business-accounts/kyc-verification-codes/remediating-actions#1_321) | | ## Legal arrangement check The actual error message will correspond to the specific type of legal arrangement. For example, "The `sole proprietorship's` name couldn't be verified." | Suberror code | Message | Remediating action codes | | | ------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | | []()1\_6000 | The legal arrangement's name couldn't be verified. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6001 | The legal arrangement's name didn't match the registration number. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6002 | The legal arrangement's registration number couldn't be verified. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6003 | The provided information is not associated with a legal arrangement. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6004 | The country of governing law couldn't be verified. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6005 | Constitutional document is missing. | [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6006 | The constitutional document was too old. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6007 | The legal arrangement's name didn't match the one on the constitutional document. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6008 | Country of governing law didn't match the constitutional document. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6009 | The constitutional document didn't show the legal arrangement's name. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6010 | The constitutional document didn't show a registration number. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6011 | The constitutional document didn't show a legal arrangement. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6012 | The legal arrangement's state didn't match the one on the constitutional document. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6013 | The registered state couldn't be verified. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6014 | The submitted registered state didn't match the one on the registry. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600), [1\_601](/business-accounts/kyc-verification-codes/remediating-actions#1_601) | | | []()1\_6015 | The constitutional document contained sensitive data. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6016 | The constitutional document is not supported. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6017 | The constitutional document doesn't belong to the legal arrangement. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6018 | The legal arrangement was not found in the database. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6019 | The constitutional document didn't show the date of issue. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6020 | The constitutional document didn't show a stamp/signature. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6021 | The image quality of the constitutional document was too low. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6022 | The legal arrangement registration number didn't match the one on the registry. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6023 | The legal arrangement name didn't match the one on the registry. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6024 | The trade name (doing business as) was entered instead of the legal arrangement name. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6025 | The legal arrangement name is incorrect. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6026 | The legal arrangement registration number did not match the one on the constitutional document. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6027 | The legal arrangement is registered as a different entity type. | [1\_600](/business-accounts/kyc-verification-codes/remediating-actions#1_600) | | | []()1\_6028 | The constitutional document is not associated with a legal arrangement. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6029 | The constitutional document didn't show the Secondary Trustee details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6030 | The constitutional document didn't show the Settlor(s) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6031 | The constitutional document didn't show the Protector(s) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6032 | The constitutional document didn't show the Defined Beneficiary(ies) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6033 | The constitutional document didn't show the Undefined Beneficiary(ies) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6034 | The Secondary Trustee details didn't match the ones on the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6035 | The Settlor(s) details didn't match the one(s) on the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6036 | The Protector(s) details didn't match the one(s) on the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6037 | The Defined Beneficiary(ies) details didn't match the one(s) on the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6038 | The Undefined Beneficiary(ies) details didn't match the one(s) on the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6039 | The Secondary Trustee is missing. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6040 | The Protector(s) is/are missing. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6041 | The Secondary Trustee(s) is a natural person but an Organization is mentioned instead. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6042 | The Secondary Trustee(s) is an Organization but a natural person is mentioned instead. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6044 | The constitutional document didn't show the Secondary Partner(s) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6045 | The constitutional document didn't show the UBO(s) details. | [1\_602](/business-accounts/kyc-verification-codes/remediating-actions#1_602) | | | []()1\_6046 | The Secondary Partner(s) details didn't match the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6047 | The UBO(s) details didn't match the constitutional document. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6048 | The Secondary Partner(s) is a natural person but an Organization is mentioned instead. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | | []()1\_6049 | The Secondary Partner(s) is an Organization but a natural person is mentioned instead. | [1\_603](/business-accounts/kyc-verification-codes/remediating-actions#1_603) | | ## Bank account check | Suberror code | Message | Remediating action codes | | ------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | []()1\_7000 | The bank account couldn't be verified | [1\_703](/business-accounts/kyc-verification-codes/remediating-actions#1_703), [1\_701](/business-accounts/kyc-verification-codes/remediating-actions#1_701) | | []()1\_7001 | The routing number wasn't valid | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7002 | The bank account number wasn't valid | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7003 | The bank account couldn't be verified | [1\_703](/business-accounts/kyc-verification-codes/remediating-actions#1_703), [1\_701](/business-accounts/kyc-verification-codes/remediating-actions#1_701) | | []()1\_7004 | The bank account entered was invalid | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7007 | The verification code wasn't entered | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7008 | There is no bank document to verify | [1\_705](/business-accounts/kyc-verification-codes/remediating-actions#1_705) | | []()1\_7009 | The bank document didn't show a bank account number | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7010 | The bank document didn't show the account owner name | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7011 | The bank account number didn't match the one on the bank document | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700), [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7012 | The bank account owner name appearing in the document does not match the verified legal name | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7013 | The bank document was too low quality | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7014 | The bank document wasn't a supported document type | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7015 | The bank account country didn't match the one on the bank document | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7016 | The branch code didn't match the one on the bank document | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700), [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7017 | The bank account currency didn't match the one on the bank document | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7018 | The bank document wasn't officially issued by the bank | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7019 | The bank document wasn't issued in the past 12 months | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7020 | The bank name didn't match the one on the bank document | [1\_700](/business-accounts/kyc-verification-codes/remediating-actions#1_700) | | []()1\_7021 | The bank document didn't show an official bank logo | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | | []()1\_7022 | The bank document didn't show an official bank stamp | [1\_704](/business-accounts/kyc-verification-codes/remediating-actions#1_704) | ## Proof of signatory check | Suberror code | Message | Remediating action codes | | ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | []()1\_8000 | Proof of signatory was missing organization `legalName` | [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8001 | Organization `legalName` did not match proof of signatory | [1\_518](/business-accounts/kyc-verification-codes/remediating-actions#1_518), [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8002 | Signatory name was not found in proof of signatory | [1\_802](/business-accounts/kyc-verification-codes/remediating-actions#1_802) | | []()1\_8003 | Proof of signatory image was of too low quality | [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8004 | Proof of signatory was too old | [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8005 | Proof of signatory didn't show the date it was issued | [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8006 | Proof of signatory provided is not supported | [1\_801](/business-accounts/kyc-verification-codes/remediating-actions#1_801) | | []()1\_8007 | The signatory couldn't be verified | [1\_800](/business-accounts/kyc-verification-codes/remediating-actions#1_800), [1\_802](/business-accounts/kyc-verification-codes/remediating-actions#1_802) | | []()1\_8008 | The signatory name didn't match the one on the registry | [1\_800](/business-accounts/kyc-verification-codes/remediating-actions#1_800), [1\_802](/business-accounts/kyc-verification-codes/remediating-actions#1_802) | | []()1\_8009 | Organization legal name is missing from the proof of director document | [1\_518](/business-accounts/kyc-verification-codes/remediating-actions#1_518), [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804) | | []()1\_8010 | Organization legal name is different with the one presented in the document | [1\_518](/business-accounts/kyc-verification-codes/remediating-actions#1_518), [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804) | | []()1\_8011 | Director name is missing from the proof of director document | [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804), [1\_805](/business-accounts/kyc-verification-codes/remediating-actions#1_805) | | []()1\_8012 | Director name is different with the one presented in the document | [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804), [1\_805](/business-accounts/kyc-verification-codes/remediating-actions#1_805) | | []()1\_8013 | Provided proof of director document is not supported | [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804) | | []()1\_8014 | Proof of director document was too old | [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804) | | []()1\_8015 | Proof of director image was of too low quality | [1\_804](/business-accounts/kyc-verification-codes/remediating-actions#1_804) | ## Business lines check | Suberror code | Message | Remediating action codes | | ------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | []()1\_9000 | The industry didn't match the website content | [1\_900](/business-accounts/kyc-verification-codes/remediating-actions#1_900), [1\_901](/business-accounts/kyc-verification-codes/remediating-actions#1_901), [1\_902](/business-accounts/kyc-verification-codes/remediating-actions#1_902) | | []()1\_9001 | The website didn't seem to be owned by the business | [1\_902](/business-accounts/kyc-verification-codes/remediating-actions#1_902) | | []()1\_9002 | Proof of industry is missing | [1\_900](/business-accounts/kyc-verification-codes/remediating-actions#1_900) | | []()1\_9003 | The industry didn't match the one on the proof of industry | [1\_901](/business-accounts/kyc-verification-codes/remediating-actions#1_901), [1\_903](/business-accounts/kyc-verification-codes/remediating-actions#1_903) | | []()1\_9004 | The proof of industry was too low quality | [1\_904](/business-accounts/kyc-verification-codes/remediating-actions#1_904) | | []()1\_9005 | The proof of industry wasn't a supported document type | [1\_903](/business-accounts/kyc-verification-codes/remediating-actions#1_903) | | []()1\_9006 | The proof of industry was too old | [1\_903](/business-accounts/kyc-verification-codes/remediating-actions#1_903) | | []()1\_9007 | The proof of industry didn't show a legal business name | [1\_903](/business-accounts/kyc-verification-codes/remediating-actions#1_903) | | []()1\_9008 | The proof of industry didn't show an industry | [1\_903](/business-accounts/kyc-verification-codes/remediating-actions#1_903) | | []()1\_9009 | Proof of funds didn’t match funding source type | [1\_519](/business-accounts/kyc-verification-codes/remediating-actions#1_519), [1\_521](/business-accounts/kyc-verification-codes/remediating-actions#1_521) | | []()1\_9010 | The legal business name didn't match the one shown on the proof of funds document | [1\_521](/business-accounts/kyc-verification-codes/remediating-actions#1_521) | | []()1\_9011 | The proof of funds document was too old | [1\_521](/business-accounts/kyc-verification-codes/remediating-actions#1_521) | | []()1\_9012 | The legal business name was not found in the proof of funds document | [1\_521](/business-accounts/kyc-verification-codes/remediating-actions#1_521) | ## Suberrors array example **Example problems array** ```json { ... "problems": [ { ... "verificationErrors": [ { "code": "1_30", "message": "Individual details couldn't be verified", "{hint:Sent when there is a common remediating action}remediatingActions{/hint}": [ { "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" } ] } ], ... } ``` --- # Source: https://docs.adyen.com/business-accounts/manage-access.md Section: Business accounts Title: Manage access for your team Description: Learn how to manage your integration in your Customer Area. --- title: "Manage access for your team" description: "Learn how to manage your integration in your Customer Area." url: "https://docs.adyen.com/business-accounts/manage-access" source_url: "https://docs.adyen.com/business-accounts/manage-access.md" canonical: "https://docs.adyen.com/business-accounts/manage-access" last_modified: "2023-07-20T12:03:00+02:00" language: "en" --- # Manage access for your team Learn how to manage your integration in your Customer Area. [View source](/business-accounts/manage-access.md) When you first sign up for Adyen, we automatically create an admin user account for your balance platform. After we create your admin user, you receive an email to verify the account. When you complete the verification, your admin user becomes active. ## Customer Area The Customer Area is an online dashboard that helps you manage your balance platform integration. In your [Customer Area](https://ca-test.adyen.com/), you can: * Manage your Adyen [resources](/business-accounts/account-structure-resources), such as your company account, merchant account, account holders, balance accounts, and business accounts. * Manage all third-party and internal [transfers](/business-accounts/view-transfers-details) in your balance platform. * Manage access for members of your team. * Manage your [API credentials](/development-resources/api-credentials) for your balance platform, and your business accounts. * Configure [webhooks](/development-resources/webhooks) to get updates on changes in your balance platform. ## Manage users Your [Customer Area](https://ca-test.adyen.com/) includes an admin user who has access to all the permissions required to manage your integration. These permissions also enable you to create more user accounts for your team. User accounts allow members of your team to access your Customer Area. With your admin user account, you can provide each user with a specific set of permissions to perform certain actions. You control your user's permissions by assigning roles to them. All users with an Adyen account must set up [Multifactor Authentication (MFA)](/account/multifactor-authentication/) or [Single Sign-On](/account/single-sign-on) in the Customer Area. To view information about business accounts in the Customer Area, your users need the following roles: | Role | The user can... | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Balance platform base role** | View all transfers, account holders, balance accounts, and business accounts. | | **View payment instrument PII** | View the IBAN of an Adyen issued bank account, if it belongs to a sole proprietorship. To use this role, the user must also have the **Balance platform base role**. | For more information about how you can manage access for members of your team, see [Manage users](/account/users). ## Manage API credentials To make requests to Adyen's APIs, you must have the appropriate API credentials. When your balance platform account is set up, it includes: * An API credential for web services. * An API credential for legal entity management. For more information on how to manage these credentials, see [API credentials for Balance Platform](/platforms/manage-access/api-credentials-web-service/). A credential for web services has web service (ws) roles assigned to it. These roles specify what API requests a user can perform with this credential. ### Frequently used roles The following tabs show the most frequently used web service roles that are available in your [Customer Area](https://ca-test.adyen.com/). ### Tab: Balance platform configuration The following table shows roles that you use to make requests for general configuration of your Balance Platform. | Web service role | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Balance Platform BCL role | You can create, update, and delete resources in your balance platform. For example: account holders, payment instruments, or transaction rules. | | Balance Platform BCL PCI role | You can unmask and view PANs and CVVs/CVCs in the response of a POST [/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments) request.To use this role, you must also have the Balance Platform BCL role enabled. | | Bank SCA Webservice Role | You can manage devices used for Strong Customer Authentication (SCA). | ### Tab: Transfers The following table shows roles that you use to make requests related to fund transfers. | Web service role | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Bank Transfer Initiation Webservice role | You can initiate transfers.This is only available for Transfers API [v1](https://docs.adyen.com/api-explorer/transfers/1/overview). | | TransferService Webservice Initiate role | You can initiate transfers. | | TransferService Webservice Retrieve role | You can view initiated transfers. | --- # Source: https://docs.adyen.com/business-accounts/manage-account-holders.md Section: Business accounts Title: Manage account holders Description: Learn how to manage account holders on your platform. --- title: "Manage account holders" description: "Learn how to manage account holders on your platform." url: "https://docs.adyen.com/business-accounts/manage-account-holders" source_url: "https://docs.adyen.com/business-accounts/manage-account-holders.md" canonical: "https://docs.adyen.com/business-accounts/manage-account-holders" last_modified: "2023-03-28T10:48:00+02:00" language: "en" --- # Manage account holders Learn how to manage account holders on your platform. [View source](/business-accounts/manage-account-holders.md) Account holders are the main API resource that represent users of your balance platform integration. It contains the legal entities and balance accounts of the user. The object also contains information about the user's [capabilities](/business-accounts/verification-overview/capabilities). To manage account holders, use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). This page contains instructions for common account holder operations. These operations are part of a larger process which includes [verification](/business-accounts/verification-overview) and [onboarding steps](/business-accounts/onboard-users). Account holders cannot be deleted. You can temporarily [suspend them](#suspend-account-holder) to disable payout capabilities, or [close them permanently](#permanent-deactivation). ## Create an account holder You can create account holders using the Configuration API. To create an account holder, you need to [create a legal entity](/business-accounts/manage-legal-entities#create-legal-entity) first. 1. Make a POST [/accountHolders](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/accountHolders) request using a [legal entity ID](/business-accounts/manage-legal-entities#create-legal-entity). For sole proprietorships, this is the individual legal entity ID of the owner. **Create an account holder** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "New Seller", "reference": "S.Eller-001", "legalEntityId": "LE00000000000000000000001" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AccountHolderInfo accountHolderInfo = new AccountHolderInfo() .reference("S.Eller-001") .legalEntityId("LE00000000000000000000001") .description("New Seller"); // Send the request AccountHoldersApi service = new AccountHoldersApi(client); AccountHolder response = service.createAccountHolder(accountHolderInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $accountHolderInfo = new AccountHolderInfo(); $accountHolderInfo ->setReference("S.Eller-001") ->setLegalEntityId("LE00000000000000000000001") ->setDescription("New Seller"); // Send the request $service = new AccountHoldersApi($client); $response = $service->createAccountHolder($accountHolderInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AccountHolderInfo accountHolderInfo = new AccountHolderInfo { Reference = "S.Eller-001", LegalEntityId = "LE00000000000000000000001", Description = "New Seller" }; // Send the request var service = new AccountHoldersService(client); var response = service.CreateAccountHolder(accountHolderInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderInfo = { description: "New Seller", reference: "S.Eller-001", legalEntityId: "LE00000000000000000000001" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.createAccountHolder(accountHolderInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) accountHolderInfo := balancePlatform.AccountHolderInfo{ Reference: common.PtrString("S.Eller-001"), LegalEntityId: "LE00000000000000000000001", Description: common.PtrString("New Seller"), } // Send the request service := client.BalancePlatform() req := service.AccountHoldersApi.CreateAccountHolderInput().AccountHolderInfo(accountHolderInfo) res, httpRes, err := service.AccountHoldersApi.CreateAccountHolder(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "description": "New Seller", "reference": "S.Eller-001", "legalEntityId": "LE00000000000000000000001" } # Send the request result = adyen.balancePlatform.account_holders_api.create_account_holder(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :description => 'New Seller', :reference => 'S.Eller-001', :legalEntityId => 'LE00000000000000000000001' } # Send the request result = adyen.balancePlatform.account_holders_api.create_account_holder(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderInfo: Types.balancePlatform.AccountHolderInfo = { reference: "S.Eller-001", legalEntityId: "LE00000000000000000000001", description: "New Seller" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.createAccountHolder(accountHolderInfo); ``` 2. In the response, note the unique `id` of the new `accountHolder` resource as well as a capabilities object with the default [capabilities](/business-accounts/verification-overview/capabilities/). Save the response because you need it to: * Match the incoming webhooks using the `id`. * [Create a balance account for the account holder](/business-accounts/manage-balance-accounts#create-a-balance-account). * [Update the account holder](#update-account-holder). **POST /accountHolders response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "description": "New Seller", "legalEntityId": "LE00000000000000000000001", "reference": "S.Eller-001", "capabilities": { "receiveFromPlatformPayments": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "receiveFromBalanceAccount": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "sendToBalanceAccount": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "sendToTransferInstrument": { "enabled": true, "requested": true, "allowed": false, "requestedSettings": { "interval": "daily", "maxAmount": { "currency": "EUR", "value": 0 } }, "verificationStatus": "pending" } }, "id": "AH00000000000000000000001", "status": "active" } ``` 3. Listen to [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks. After Adyen has verified the new account holder, webhooks inform your integration of the resulting verification statuses of the account holder's capabilities. Webhooks contain the updated capability object with [verification codes](/business-accounts/kyc-verification-codes). ## View account holders To view [account holder](/business-accounts/account-structure-resources) details, you can either use your [Customer Area](https://ca-test.adyen.com/) or make an API request. The following tabs explain both methods. ### Tab: Customer Area To view the account holders in your [Customer Area](https://ca-test.adyen.com/): 1. Go to **Accounts & balances** > **Account holders**. 2. In the **Account holders** table, select an **Account holder ID** to open the **Account holder details** page. The **Account holder details** page shows information such as: * The status of the account holder * Their balance accounts and available balances * Their associated legal entities * The ID and type of their uploaded documents * Their capabilities and [verification deadlines](/business-accounts/verification-overview/#verification-deadlines) ### Filter and search On the **Account holders** page, you can find specific account holders by using the filter and search features. Set a filter by using the buttons on the filter bar, located on top of the account holder table. For example, you can filter account holders based on their [capabilities](/business-accounts/verification-overview/capabilities) and the capability statuses. Also, you can search for an account holder by using their ID, reference, name or email. To search for an account holder: 1. On the **Account holders** page, select **Search**. 2. On the dropdown menu, select **Account holder**. 3. In the text field, enter account holder's data, such as: * **Account holder details**: ID or reference * **Main legal entity details**: ID, name, or email\ If the main legal entity is an individual, you need the `View account holders PII` role to search for the legal entity's name or email. The search window now shows any corresponding account holders. ### Liable account holder The [liable account holder](/business-accounts/account-structure-resources) is the account holder related to your company's legal entity. To view the details of the liable account holder, on the **Account holders** page, select **View liable account holder**. ### Tab: API 1. Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) with the account holder's `id` as a path parameter. **Get an account holder** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request AccountHoldersApi service = new AccountHoldersApi(client); AccountHolder response = service.getAccountHolder("id", null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Send the request $service = new AccountHoldersApi($client); $response = $service->getAccountHolder('id'); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new AccountHoldersService(client); var response = service.GetAccountHolder("id"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.getAccountHolder("id"); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.BalancePlatform() req := service.AccountHoldersApi.GetAccountHolderInput("id") res, httpRes, err := service.AccountHoldersApi.GetAccountHolder(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Send the request result = adyen.balancePlatform.account_holders_api.get_account_holder(id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Send the request result = adyen.balancePlatform.account_holders_api.get_account_holder('id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.getAccountHolder("id"); ``` 2. Receive the details about the account holder including their [capabilities](/business-accounts/verification-overview/capabilities) in the API response. **Get account holder response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "description": "Liable account holder used for international payments and payouts", "legalEntityId": "LE00000000000000000000001", "reference": "S.Eller-001", "capabilities": { "receiveFromPlatformPayments": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "receiveFromBalanceAccount": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "sendToBalanceAccount": { "enabled": true, "requested": true, "allowed": false, "verificationStatus": "pending" }, "sendToTransferInstrument": { "enabled": true, "requested": true, "allowed": false, "transferInstruments": [ { "enabled": true, "requested": true, "allowed": false, "id": "SE322KH223222F5GXZFNM3BGP", "verificationStatus": "pending" } ], "verificationStatus": "pending" } }, "id": "AH00000000000000000000001", "status": "active" } ``` With the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/2/overview), you can also: * GET [/balancePlatforms/{id}/accountHolders](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/accountHolders): Get a list of the account holders in your balance platform. This endpoint returns a paginated list of account holders. * GET [/accountHolders/{id}/balanceAccounts](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)/balanceAccounts): Get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts. ## Update an account holder After you create an account holder resource, you may need to update it at a later time. For example, when an account holder with multiple balance accounts wants to change their primary balance account. To update an account holder: 1. Make a PATCH [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)) request. The example below shows how you can change the primary balance account of an account holder by sending the `primaryBalanceAccount` field. **Change the primary balance account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "primaryBalanceAccount":"BA00000000000000000000002" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest() .primaryBalanceAccount("BA00000000000000000000002"); // Send the request AccountHoldersApi service = new AccountHoldersApi(client); AccountHolder response = service.updateAccountHolder("id", accountHolderUpdateRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $accountHolderUpdateRequest = new AccountHolderUpdateRequest(); $accountHolderUpdateRequest ->setPrimaryBalanceAccount("BA00000000000000000000002"); // Send the request $service = new AccountHoldersApi($client); $response = $service->updateAccountHolder('id', $accountHolderUpdateRequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest { PrimaryBalanceAccount = "BA00000000000000000000002" }; // Send the request var service = new AccountHoldersService(client); var response = service.UpdateAccountHolder("id", accountHolderUpdateRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderUpdateRequest = { primaryBalanceAccount: "BA00000000000000000000002" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) accountHolderUpdateRequest := balancePlatform.AccountHolderUpdateRequest{ PrimaryBalanceAccount: common.PtrString("BA00000000000000000000002"), } // Send the request service := client.BalancePlatform() req := service.AccountHoldersApi.UpdateAccountHolderInput("id").AccountHolderUpdateRequest(accountHolderUpdateRequest) res, httpRes, err := service.AccountHoldersApi.UpdateAccountHolder(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "primaryBalanceAccount": "BA00000000000000000000002" } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :primaryBalanceAccount => 'BA00000000000000000000002' } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderUpdateRequest: Types.balancePlatform.AccountHolderUpdateRequest = { primaryBalanceAccount: "BA00000000000000000000002" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` 2. Receive the response with the updated account holder object. **Update account holder response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "description": "Content", "legalEntityId": "LE00000000000000000000001", "id": "AH00000000000000000000001", "primaryBalanceAccount": "BA00000000000000000000002", "status": "active" } ``` ## Deactivate account holders When an account holder discontinues their business, you can permanently close them and their balance accounts from your balance platform. In some scenarios, you might also want to close a balance account but keep the account holder active. For example, an account holder that has separate balance accounts for their businesses might want to only close one of their businesses. To close balance accounts and account holders: 1. Check if they have [zero balance](/business-accounts/manage-balance-accounts#view-balance-accounts) in their balance accounts. You can only close empty balance accounts, so if there are funds left, [transfer](/platforms/internal-fund-transfers/on-demand-fund-transfers/) any remaining balance. 2. Close balance accounts by [updating each balance account](/business-accounts/manage-balance-accounts#update-balance-account) and setting the `status` to **Closed**. Start with those that are not the primary balance account. You can only close a primary balance account if the account holder's other balance accounts are already closed. 3. Finally, permanently close the account holder by [updating the account holder](#update-account-holder) and setting the `status` to **Closed**. ## View capabilities You can view an account holder's capabilities and their verification status in your [Customer Area](https://ca-test.adyen.com/) or by making a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request. The following tabs explain both methods. ### Tab: Customer Area To view capabilities of an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab. You can view the capabilities that are enabled, allowed and their verification status. ### Tab: API To view the capabilities of an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request. 2. In the [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities) object of the response, note the following parameters and values that are listed for each capability: * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Boolean that indicates whether the capability is allowed. The possible values are **true** or **false**. * [enabled](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-enabled): Boolean that indicates whether the user can use the capability. The possible values are **true** or **false**. * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): The status of the checks. The possible values are **invalid**, **pending**, **rejected**, or **valid**. * [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) array: When this array is not empty, this means that there are errors that you need to address. Refer to [verification error codes](/business-accounts/kyc-verification-codes) for a list of verification errors. ## Request a capability Some capabilities are automatically requested when you [create an account holder](/business-accounts/onboard-users). However, your account holders may need additional capabilities. For example, if you want to allow your users to send and receive funds from third parties. In these cases, you must request the additional capabilities. The following tabs show how to request a capability. ### Tab: Customer Area To complete the following steps, you must have the **Manage account holder capabilities** [user role](/account/user-roles#platforms). To request a capability for an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab and select **+ Request new capability**. 3. From the dropdown menu, select a capability and, if applicable, its level. 4. Select **Submit**. 5. On the confirmation window, select **Submit request**. The capability request is sent to Adyen for approval. ### Tab: API To request a capability for an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a PATCH [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)) request, specifying the key-value pairs for each capability in the [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)#responses-200-capabilities) object. Set the [requested](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)#request-capabilities-requested) parameter to **true**. Here is an example of how to request the `receivePayment` capability for an existing user. If you are requesting multiple capabilities, add another set of key-value pairs. **Request a capability** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "capabilities" : { "receivePayments" : { "requested" : true } } }' ``` #### Java ```java // Adyen Java API Library v34.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AccountHolderCapability accountHolderCapability = new AccountHolderCapability() .requested(true); AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest() .capabilities(new HashMap(Map.of( "receivePayments", accountHolderCapability ))); // Send the request AccountHoldersApi service = new AccountHoldersApi(client); AccountHolder response = service.updateAccountHolder("id", accountHolderUpdateRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $accountHolderCapability = new AccountHolderCapability(); $accountHolderCapability ->setRequested(true); $accountHolderUpdateRequest = new AccountHolderUpdateRequest(); $accountHolderUpdateRequest ->setCapabilities( array( "receivePayments" => $accountHolderCapability ) ); // Send the request $service = new AccountHoldersApi($client); $response = $service->updateAccountHolder('id', $accountHolderUpdateRequest); ``` #### C\# ```cs // Adyen .net API Library v14.4.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AccountHolderCapability accountHolderCapability = new AccountHolderCapability { Requested = true, RequestedLevel = AccountHolderCapability.RequestedLevelEnum.Medium }; AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest { Capabilities = new Dictionary { { "withdrawFromAtm", accountHolderCapability } } }; // Make the API call var service = new AccountHoldersService(client); var response = service.UpdateAccountHolder("id", accountHolderUpdateRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v16.2.0 // Require the parts of the module you want to use const { Client, BalancePlatformAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const accountHolderUpdateRequest = { capabilities: { withdrawFromAtm: { requested: true, requestedLevel: "medium" } } } // Make the API call const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` #### Go ```go // Adyen Go API Library v18.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v18/src/common" "github.com/adyen/adyen-go-api-library/v18/src/adyen" "github.com/adyen/adyen-go-api-library/v18/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) accountHolderCapability := balancePlatform.AccountHolderCapability{ Requested: common.PtrBool(true), } accountHolderUpdateRequest := balancePlatform.AccountHolderUpdateRequest{ Capabilities: &map[string]balancePlatform.AccountHolderCapability{ "receivePayments": accountHolderCapability, }, } // Send the request service := client.BalancePlatform() req := service.AccountHoldersApi.UpdateAccountHolderInput("id").AccountHolderUpdateRequest(accountHolderUpdateRequest) res, httpRes, err := service.AccountHoldersApi.UpdateAccountHolder(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.4.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "capabilities": { "receivePayments": { "requested": True } } } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.2 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :capabilities => { :receivePayments => { :requested => true } } } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v25.0.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderCapability: Types.balancePlatform.AccountHolderCapability = { requested: true }; const accountHolderUpdateRequest: Types.balancePlatform.AccountHolderUpdateRequest = { capabilities: { "receivePayments": accountHolderCapability } }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` 2. In the response, note the following parameters and their respective values for the capability: * `requested`: **true** * `allowed`: **false** * `verification status`: **pending** **Response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "id": "AH00000000000000000000001", "legalEntityId": "LE00000000000000000000001", "description": "S.Hopper", "capabilities": { "sendToThirdParty": { "requested": true, "allowed": false, "verificationStatus": "pending" } } } ``` ## Enable or disable a capability To allow or prevent an account holder from using a capability, update the capability in your [Customer Area](https://ca-test.adyen.com/) or make an API request. The following tabs explain both methods. ### Tab: Customer Area To complete the following steps, you must have the **Manage account holder capabilities** [user role](/account/user-roles#platforms). To enable or disable a capability for an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab and select **Edit**. 3. In the **Enabled** column: * Select the corresponding checkbox to *enable* the capability. * Clear the corresponding checkbox to *disable* the capability. 4. Select **Save**. 5. On the confirmation window, select **Save changes**. ### Tab: API To enable or disable a capability for an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a PATCH [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)) request specifying the following parameter for a capability: * [enabled](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-enabled): Set this to **true** or **false** to enable or disable the capability, respectively. Here is an example of how to disable a capability for an account holder. If you are requesting multiple capabilities, add another set of key-value pairs. **Disable a capability** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "capabilities": { "sendToThirdParty": { "enabled": false } } }' ``` #### Java ```java // Adyen Java API Library v34.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AccountHolderCapability accountHolderCapability = new AccountHolderCapability() .enabled(false); AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest() .capabilities(new HashMap(Map.of( "sendToThirdParty", accountHolderCapability ))); // Send the request AccountHoldersApi service = new AccountHoldersApi(client); AccountHolder response = service.updateAccountHolder("id", accountHolderUpdateRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $accountHolderCapability = new AccountHolderCapability(); $accountHolderCapability ->setEnabled(false); $accountHolderUpdateRequest = new AccountHolderUpdateRequest(); $accountHolderUpdateRequest ->setCapabilities( array( "sendToThirdParty" => $accountHolderCapability ) ); // Send the request $service = new AccountHoldersApi($client); $response = $service->updateAccountHolder('id', $accountHolderUpdateRequest); ``` #### C\# ```cs // Adyen .net API Library v29.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AccountHolderCapability accountHolderCapability = new AccountHolderCapability { Enabled = false }; AccountHolderUpdateRequest accountHolderUpdateRequest = new AccountHolderUpdateRequest { Capabilities = new Dictionary { { "sendToThirdParty", accountHolderCapability } } }; // Send the request var service = new AccountHoldersService(client); var response = service.UpdateAccountHolder("id", accountHolderUpdateRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v25.0.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderUpdateRequest = { capabilities: { sendToThirdParty: { enabled: false } } } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` #### Go ```go // Adyen Go API Library v18.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v18/src/common" "github.com/adyen/adyen-go-api-library/v18/src/adyen" "github.com/adyen/adyen-go-api-library/v18/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) accountHolderCapability := balancePlatform.AccountHolderCapability{ Enabled: common.PtrBool(false), } accountHolderUpdateRequest := balancePlatform.AccountHolderUpdateRequest{ Capabilities: &map[string]balancePlatform.AccountHolderCapability{ "sendToThirdParty": accountHolderCapability, }, } // Send the request service := client.BalancePlatform() req := service.AccountHoldersApi.UpdateAccountHolderInput("id").AccountHolderUpdateRequest(accountHolderUpdateRequest) res, httpRes, err := service.AccountHoldersApi.UpdateAccountHolder(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.4.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "capabilities": { "sendToThirdParty": { "enabled": False } } } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.2 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :capabilities => { :sendToThirdParty => { :enabled => false } } } # Send the request result = adyen.balancePlatform.account_holders_api.update_account_holder(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v25.0.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const accountHolderCapability: Types.balancePlatform.AccountHolderCapability = { enabled: false }; const accountHolderUpdateRequest: Types.balancePlatform.AccountHolderUpdateRequest = { capabilities: { "sendToThirdParty": accountHolderCapability } }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.AccountHoldersApi.updateAccountHolder("id", accountHolderUpdateRequest); ``` 2. In the response, note the following parameters and their respective values for each capability: * `enabled`: **false** * `allowed`: **true** * `verification status`: **valid** **Response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "id": "AH32272223222B5D3755J3C3C", "legalEntityId": "LE00000000000000000000001", "description": "S.Hopper", "capabilities": { "sendToThirdParty": { "enabled": false, "allowed": true, "verificationStatus": "valid" } } } ``` ## Manage KYC The [Know Your Customer](/business-accounts/onboard-users/) (KYC) checks are part of the verification process that Adyen performs to make sure that account holders have provided accurate information about their businesses. In your [Customer Area](https://ca-test.adyen.com/), you can access a KYC summary and a detailed timeline of the entire verification process. You can also view and download any documents that account holders have uploaded. ### View KYC summary and timeline You can view information about the [verification process](/business-accounts/verification-overview) for account holders in your balance platform. This includes an overview of the current verification status for associated legal entities and a timeline of KYC-related events. You can use this information to help your users troubleshoot issues they experience during the onboarding process. To view KYC summary and timeline information in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select **KYC timeline**. The **KYC summary** section shows the current status of the KYC checks separated by the type of check, for example **Identity**. If there are multiple legal entities linked to the account holder, the type of each legal entity is specified, for example **Individual**. ** ### Possible KYC verification statuses for a legal entity | Verification status | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Awaiting data** | The KYC information for the legal entity has not yet been submitted. | | **In review** | The KYC information for the legal entity is being reviewed by Adyen. | | **Verified** | The KYC verification checks for the legal entity have passed. | | **Unsuccessful** | The KYC verification checks for the legal entity have failed. For example, because of an invalid document or ID number. Review the **KYC Timeline** for more information about the verification errors and recommended remediating actions. To be verified, all the errors must be resolved. | | **Rejected** | The legal entity has been rejected by Adyen. For example, because the organization is in a sanctions list. This status is final and any errors cannot be resolved by updating data or uploading documents. | To view more detailed information about the order of the KYC checks and events that affected the verification process, look at the **KYC timeline**. You can filter events by the type of check, legal entity ID, and legal entity name. The timeline also includes any [verification errors and the corresponding remediating action codes](/business-accounts/kyc-verification-codes). ### View KYC documents To access the **KYC documents** tab, you must have the **View KYC documents** and **Download KYC documents** [roles](/account/user-roles#platforms). Consider the privacy implications before granting these roles to any user. Based on your role, you may view only or view and download the documents that account holders have uploaded during their onboarding process for verification checks. In your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select **KYC documents**. You can use this information to help your users resolve [verification errors](/business-accounts/kyc-verification-codes) they experience during the onboarding process, such as expired documents or a mismatch between the legal and organization names. Apply filters by document type, file name, and associated legal entity ID to get the information you need. --- # Source: https://docs.adyen.com/business-accounts/manage-balance-accounts.md Section: Business accounts Title: Manage balance accounts Description: View and manage the balance accounts in your balance platform. --- title: "Manage balance accounts" description: "View and manage the balance accounts in your balance platform." url: "https://docs.adyen.com/business-accounts/manage-balance-accounts" source_url: "https://docs.adyen.com/business-accounts/manage-balance-accounts.md" canonical: "https://docs.adyen.com/business-accounts/manage-balance-accounts" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Manage balance accounts View and manage the balance accounts in your balance platform. [View source](/business-accounts/manage-balance-accounts.md) A [balance account](/business-accounts/account-structure-resources/) is an API resource that contains information about the funds held by your user. To manage the balance accounts use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). This page contains instructions for common balance account operations. These operations are part of a larger process which includes [verification](/business-accounts/verification-overview) and [onboarding steps](/business-accounts/onboard-users). ## Create a balance account You can create balance accounts manually using the Configuration API. To create a balance account: 1. Make a POST [/balanceAccounts](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts) request using the account holder ID you want to attach the balance account to. **Create a balance account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "accountHolderId": "AH00000000000000000000001", "description": "AccountHolder Primary Balance Account" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) BalanceAccountInfo balanceAccountInfo = new BalanceAccountInfo() .accountHolderId("AH00000000000000000000001") .description("AccountHolder Primary Balance Account"); // Send the request BalanceAccountsApi service = new BalanceAccountsApi(client); BalanceAccount response = service.createBalanceAccount(balanceAccountInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $balanceAccountInfo = new BalanceAccountInfo(); $balanceAccountInfo ->setAccountHolderId("AH00000000000000000000001") ->setDescription("AccountHolder Primary Balance Account"); // Send the request $service = new BalanceAccountsApi($client); $response = $service->createBalanceAccount($balanceAccountInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) BalanceAccountInfo balanceAccountInfo = new BalanceAccountInfo { AccountHolderId = "AH00000000000000000000001", Description = "AccountHolder Primary Balance Account" }; // Send the request var service = new BalanceAccountsService(client); var response = service.CreateBalanceAccount(balanceAccountInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const balanceAccountInfo = { accountHolderId: "AH00000000000000000000001", description: "AccountHolder Primary Balance Account" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createBalanceAccount(balanceAccountInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) balanceAccountInfo := balancePlatform.BalanceAccountInfo{ AccountHolderId: "AH00000000000000000000001", Description: common.PtrString("AccountHolder Primary Balance Account"), } // Send the request service := client.BalancePlatform() req := service.BalanceAccountsApi.CreateBalanceAccountInput().BalanceAccountInfo(balanceAccountInfo) res, httpRes, err := service.BalanceAccountsApi.CreateBalanceAccount(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "accountHolderId": "AH00000000000000000000001", "description": "AccountHolder Primary Balance Account" } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_balance_account(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :accountHolderId => 'AH00000000000000000000001', :description => 'AccountHolder Primary Balance Account' } # Send the request result = adyen.balancePlatform.balance_accounts_api.create_balance_account(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const balanceAccountInfo: Types.balancePlatform.BalanceAccountInfo = { accountHolderId: "AH00000000000000000000001", description: "AccountHolder Primary Balance Account" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.createBalanceAccount(balanceAccountInfo); ``` 2. In the response, note the `id`. You need this ID to: * [View a balance account](#view-balance-accounts) * [Update a balance account](#update-balance-account) * [Close a balance account](#close-a-balance-account) **Create balance account response** ```json { "accountHolderId": "AH00000000000000000000001", "defaultCurrencyCode": "EUR", "description": "Main Account", "reference": "Referee", "timeZone": "Europe/Amsterdam", "balances": [ { "available": 0, "balance": 0, "currency": "EUR", "pending": 0, "reserved": 0 } ], "id": "BA00000000000000000000001", "status": "active" } ``` ## View balance accounts To view the balance accounts and the available balances of your account holder, you can either use your [Customer Area](https://ca-test.adyen.com/) or make an API request. ### Tab: Customer Area To view balance accounts in your [Customer Area](https://ca-test.adyen.com/): 1. Select **Accounts & balances** > **Balance accounts**. 2. In the **Balance platform** dropdown, select the balance platform. You can view balance accounts from one balance platform at a time. 3. Select a **Balance account ID** to view more details, such as the available balances. Alternatively, enter a balance account ID in the **Search** menu to find a balance account. ### Tab: API To get balance accounts, use the following endpoints: * GET [/accountHolders/{id}/balanceAccounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}/balanceAccounts): get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts. * GET [/balanceAccounts/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)): get the details of a balance account, including a list of [balances](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__resParam_balances) associated with the balance account. * GET [/balanceAccounts/{id}/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/paymentInstruments): get a list of the payment instruments (cards) associated with the balance account. ## Update a balance account To update a balance account, make a PATCH [/balanceAccounts/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/patch/balanceAccounts/{id}) request. The following example shows how to update the description of a balance account. **Change the description of a balance account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "description":"Balance account for new business" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) BalanceAccountUpdateRequest balanceAccountUpdateRequest = new BalanceAccountUpdateRequest() .description("Balance account for new business"); // Send the request BalanceAccountsApi service = new BalanceAccountsApi(client); BalanceAccount response = service.updateBalanceAccount("id", balanceAccountUpdateRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $balanceAccountUpdateRequest = new BalanceAccountUpdateRequest(); $balanceAccountUpdateRequest ->setDescription("Balance account for new business"); // Send the request $service = new BalanceAccountsApi($client); $response = $service->updateBalanceAccount('id', $balanceAccountUpdateRequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) BalanceAccountUpdateRequest balanceAccountUpdateRequest = new BalanceAccountUpdateRequest { Description = "Balance account for new business" }; // Send the request var service = new BalanceAccountsService(client); var response = service.UpdateBalanceAccount("id", balanceAccountUpdateRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const balanceAccountUpdateRequest = { description: "Balance account for new business" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.updateBalanceAccount("id", balanceAccountUpdateRequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) balanceAccountUpdateRequest := balancePlatform.BalanceAccountUpdateRequest{ Description: common.PtrString("Balance account for new business"), } // Send the request service := client.BalancePlatform() req := service.BalanceAccountsApi.UpdateBalanceAccountInput("id").BalanceAccountUpdateRequest(balanceAccountUpdateRequest) res, httpRes, err := service.BalanceAccountsApi.UpdateBalanceAccount(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "description": "Balance account for new business" } # Send the request result = adyen.balancePlatform.balance_accounts_api.update_balance_account(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :description => 'Balance account for new business' } # Send the request result = adyen.balancePlatform.balance_accounts_api.update_balance_account(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const balanceAccountUpdateRequest: Types.balancePlatform.BalanceAccountUpdateRequest = { description: "Balance account for new business" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.BalanceAccountsApi.updateBalanceAccount("id", balanceAccountUpdateRequest); ``` ## Close a balance account In some scenarios, you might want to close an account holder's balance account. For example, an account holder that has separate balance accounts for their businesses might want to close one of their businesses. To permanently close a balance account: 1. Check if they have [zero balance](#view-balance-accounts) in their balance accounts. You can only close empty balance accounts, so if there are funds left, [transfer](/platforms/internal-fund-transfers/on-demand-fund-transfers/) any remaining balance. 2. Close balance accounts by [updating each balance account](#update-balance-account) and setting the `status` to **Closed**. If an account holder discontinues their contractual relationship with your platform, you can also [permanently deactivate the account holder](/business-accounts/manage-account-holders#permanent-deactivation). --- # Source: https://docs.adyen.com/business-accounts/manage-legal-entities.md Section: Business accounts Title: Manage legal entities Description: Create, view, and manage your users' legal entity resources. --- title: "Manage legal entities" description: "Create, view, and manage your users' legal entity resources." url: "https://docs.adyen.com/business-accounts/manage-legal-entities" source_url: "https://docs.adyen.com/business-accounts/manage-legal-entities.md" canonical: "https://docs.adyen.com/business-accounts/manage-legal-entities" last_modified: "2024-01-04T17:37:00+01:00" language: "en" --- # Manage legal entities Create, view, and manage your users' legal entity resources. [View source](/business-accounts/manage-legal-entities.md) A legal entity is an API resource that describes an individual or an organization on your Balance Platform. It contains information about your user, for example, the legal name, address, and tax information of the individual or organization. Adyen uses this information to perform [verification checks](/business-accounts/verification-overview) as required by payment industry regulations. The legal entity resource also contains the associations that the legal entity has with other entities on your platform. For example, most organizations need a signatory. To manage legal entities, use the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/3/overview). This page contains instructions for common legal entity operations. These operations are part of a larger process which includes [verification](/business-accounts/verification-overview) and [onboarding steps](/business-accounts/onboard-users). ## Create a legal entity Creating a legal entity is the first step in moving users though the onboarding and verification process. Adyen uses the details you include when you create the legal entity to [verify the account holder](/business-accounts/verification-overview) that is linked to the legal entity. The minimum required information for creating a legal entity depends on the location and entity type that you are onboarding. To create a legal entity: 1. Make a POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) request using the [individual](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-individual) or [organization](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization) details. The following example shows how to create an organization in the United States. **Create legal entity request** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "organization", "organization": { "legalName": "Explorer Company based in US", "registrationNumber": "101002749", "type": "privateCompany", "registeredAddress": { "city": "New York", "country": "US", "postalCode": "10003", "stateOrProvince": "NY", "street": "71 5th Avenue", "street2": "11th floor" } } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) Address address = new Address() .country("US") .stateOrProvince("NY") .city("New York") .street("71 5th Avenue") .postalCode("10003") .street2("11th floor"); Organization organization = new Organization() .legalName("Explorer Company based in US") .registeredAddress(address) .registrationNumber("101002749") .type(Organization.TypeEnum.PRIVATECOMPANY); LegalEntityInfoRequiredType legalEntityInfoRequiredType = new LegalEntityInfoRequiredType() .organization(organization) .type(LegalEntityInfoRequiredType.TypeEnum.ORGANIZATION); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.createLegalEntity(legalEntityInfoRequiredType, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $address = new Address(); $address ->setCountry("US") ->setStateOrProvince("NY") ->setCity("New York") ->setStreet("71 5th Avenue") ->setPostalCode("10003") ->setStreet2("11th floor"); $organization = new Organization(); $organization ->setLegalName("Explorer Company based in US") ->setRegisteredAddress($address) ->setRegistrationNumber("101002749") ->setType("privateCompany"); $legalEntityInfoRequiredType = new LegalEntityInfoRequiredType(); $legalEntityInfoRequiredType ->setOrganization($organization) ->setType("organization"); // Send the request $service = new LegalEntitiesApi($client); $response = $service->createLegalEntity($legalEntityInfoRequiredType); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Address address = new Address { Country = "US", StateOrProvince = "NY", City = "New York", Street = "71 5th Avenue", PostalCode = "10003", Street2 = "11th floor" }; Organization organization = new Organization { LegalName = "Explorer Company based in US", RegisteredAddress = address, RegistrationNumber = "101002749", Type = Organization.TypeEnum.PrivateCompany }; LegalEntityInfoRequiredType legalEntityInfoRequiredType = new LegalEntityInfoRequiredType { Organization = organization, Type = LegalEntityInfoRequiredType.TypeEnum.Organization }; // Send the request var service = new LegalEntitiesService(client); var response = service.CreateLegalEntity(legalEntityInfoRequiredType); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const legalEntityInfoRequiredType = { type: "organization", organization: { legalName: "Explorer Company based in US", registrationNumber: "101002749", type: "privateCompany", registeredAddress: { city: "New York", country: "US", postalCode: "10003", stateOrProvince: "NY", street: "71 5th Avenue", street2: "11th floor" } } } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.createLegalEntity(legalEntityInfoRequiredType); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) address := legalEntityManagement.Address{ Country: "US", StateOrProvince: common.PtrString("NY"), City: common.PtrString("New York"), Street: common.PtrString("71 5th Avenue"), PostalCode: common.PtrString("10003"), Street2: common.PtrString("11th floor"), } organization := legalEntityManagement.Organization{ LegalName: "Explorer Company based in US", RegisteredAddress: address, RegistrationNumber: common.PtrString("101002749"), Type: common.PtrString("privateCompany"), } legalEntityInfoRequiredType := legalEntityManagement.LegalEntityInfoRequiredType{ Organization: &organization, Type: "organization", } // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.CreateLegalEntityInput().LegalEntityInfoRequiredType(legalEntityInfoRequiredType) res, httpRes, err := service.LegalEntitiesApi.CreateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "organization", "organization": { "legalName": "Explorer Company based in US", "registrationNumber": "101002749", "type": "privateCompany", "registeredAddress": { "city": "New York", "country": "US", "postalCode": "10003", "stateOrProvince": "NY", "street": "71 5th Avenue", "street2": "11th floor" } } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.create_legal_entity(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'organization', :organization => { :legalName => 'Explorer Company based in US', :registrationNumber => '101002749', :type => 'privateCompany', :registeredAddress => { :city => 'New York', :country => 'US', :postalCode => '10003', :stateOrProvince => 'NY', :street => '71 5th Avenue', :street2 => '11th floor' } } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.create_legal_entity(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const address: Types.legalEntityManagement.Address = { country: "US", stateOrProvince: "NY", city: "New York", street: "71 5th Avenue", postalCode: "10003", street2: "11th floor" }; const organization: Types.legalEntityManagement.Organization = { legalName: "Explorer Company based in US", registeredAddress: address, registrationNumber: "101002749", type: Types.legalEntityManagement.Organization.TypeEnum.PrivateCompany }; const legalEntityInfoRequiredType: Types.legalEntityManagement.LegalEntityInfoRequiredType = { organization: organization, type: Types.legalEntityManagement.LegalEntityInfoRequiredType.TypeEnum.Organization }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.createLegalEntity(legalEntityInfoRequiredType); ``` 2. The response contains a generated legal entity `id`. Save this response because you need the ID to: * [Create an account holder](/business-accounts/manage-account-holders#create-an-account-holder) * [View a legal entity](#view-legal-entity-details) * [Update a legal entity](#update-a-legal-entity) **Create legal entity response** ```json { "organization": { "legalName": "Explorer Company based in US", "registeredAddress": { "city": "New York", "country": "US", "postalCode": "10003", "stateOrProvince": "NY", "street": "71 5th Avenue", "street2": "11th floor" }, "registrationNumber": "101002749", "type": "privateCompany" }, "type": "organization", // Generated legal entity ID "id": "LE00000000000000000000001" } ``` ## View legal entity details After creating a legal entity, you can view the resource at any time using the [Customer Area](https://ca-test.adyen.com/), the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview), or hosted onboarding. ### Tab: Customer Area To view the legal entity details of an account holder in your [Customer Area](https://ca-test.adyen.com/), you can [search for the account holder](/business-accounts/manage-account-holders?tab=ah-customer-area_2#get-account-holders) associated to the legal entity. As an alternative: 1. Select **Accounts & balances** > **Account holders**. 2. In the account holder table, select an **Account holder ID**. 3. In the **Account holder details** page, select **Overview** > **Legal entity**. The legal entity details of the main legal entity are shown. You can view bank account information for the main legal entity under **Transfer instruments**. If the legal entity is an organization, the page also shows details about the associated legal entities under **Entity associations**. If the legal entity is an individual or a sole proprietorship, their personally identifiable information (PII) is redacted. Personally identifiable information includes their: * Name * Address (except for the country/region) * Date of birth * Email address * Phone number * IBAN or bank account number To view this information in its unredacted state, you must have the **View account holders PII data** [user role](/account/user-roles#platforms). ### Tab: API To view legal entity details with the API: 1. Make a GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request using the main [legal entity ID](#create-legal-entity) as a path parameter. **View legal entity details** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X GET \ ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.getLegalEntity("id", null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Send the request $service = new LegalEntitiesApi($client); $response = $service->getLegalEntity('id'); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new LegalEntitiesService(client); var response = service.GetLegalEntity("id"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.getLegalEntity("id"); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.GetLegalEntityInput("id") res, httpRes, err := service.LegalEntitiesApi.GetLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Send the request result = adyen.legalEntityManagement.legal_entities_api.get_legal_entity(id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Send the request result = adyen.legalEntityManagement.legal_entities_api.get_legal_entity('id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.getLegalEntity("id"); ``` 2. Adyen returns the **legal entity details** of the requested legal entity ID in the `individual` or `organization` object. **View legal entity response** ```json { "entityAssociations": [ { "associatorId": "LE00000000000000000000001", "entityType": "soleProprietorship", "legalEntityId": "LE00000000000000000000002", "type": "soleProprietorship" } ], "individual": { "email": "s.eller@example.com", "birthData": { "dateOfBirth": "1990-06-21" }, "name": { "firstName": "Shelly", "lastName": "Eller" }, "residentialAddress": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "street": "Simon Carmiggeltstraat 6 - 50" } }, "type": "individual", "id": "LE00000000000000000000001" } ``` 3. To view the details of the [associated entities](https://docs.adyen.com/api-explorer/legalentity/3/post/legalEntities#request-entityAssociations), make another GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) using the `legalEntityId` returned in each element of the `entityAssociations` array. ## Update a legal entity When the details of your account holders change, you need to update the legal entity. For example, a business can change address or ownership. You can update a legal entity using the Customer Area or the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). ### Tab: Customer Area Before you begin, make sure you have the following [role](/account/user-roles/): * **Manage account holders and legal entities** To update the legal entity details of an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Select the merchant account linked to your balance platform. 2. Select **Accounts & balances** > **Account holders**. 3. In the account holder table, select an **Account holder ID**. 4. Under **Quick actions**, select **Go to Onboarding**.\ This opens a new browser tab for Hosted onboarding. 5. Edit the details and select **Submit**. ### Tab: API To update a legal entity using the API, make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request with the new details. Only parameters passed in the request body are updated. **Update legal entity details** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "organization": { "legalName": "New Company Name", "registrationNumber": "101002750", "type": "privateCompany", "registeredAddress": { "city": "New York", "country": "US", "postalCode": "10003", "stateOrProvince": "NY", "street": "73 5th Avenue", "street2": "12th floor" } } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) Address address = new Address() .country("US") .stateOrProvince("NY") .city("New York") .street("73 5th Avenue") .postalCode("10003") .street2("12th floor"); Organization organization = new Organization() .legalName("New Company Name") .registeredAddress(address) .registrationNumber("101002750") .type(Organization.TypeEnum.PRIVATECOMPANY); LegalEntityInfo legalEntityInfo = new LegalEntityInfo() .organization(organization); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.updateLegalEntity("id", legalEntityInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $address = new Address(); $address ->setCountry("US") ->setStateOrProvince("NY") ->setCity("New York") ->setStreet("73 5th Avenue") ->setPostalCode("10003") ->setStreet2("12th floor"); $organization = new Organization(); $organization ->setLegalName("New Company Name") ->setRegisteredAddress($address) ->setRegistrationNumber("101002750") ->setType("privateCompany"); $legalEntityInfo = new LegalEntityInfo(); $legalEntityInfo ->setOrganization($organization); // Send the request $service = new LegalEntitiesApi($client); $response = $service->updateLegalEntity('id', $legalEntityInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Address address = new Address { Country = "US", StateOrProvince = "NY", City = "New York", Street = "73 5th Avenue", PostalCode = "10003", Street2 = "12th floor" }; Organization organization = new Organization { LegalName = "New Company Name", RegisteredAddress = address, RegistrationNumber = "101002750", Type = Organization.TypeEnum.PrivateCompany }; LegalEntityInfo legalEntityInfo = new LegalEntityInfo { Organization = organization }; // Send the request var service = new LegalEntitiesService(client); var response = service.UpdateLegalEntity("id", legalEntityInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const legalEntityInfo = { organization: { legalName: "New Company Name", registrationNumber: "101002750", type: "privateCompany", registeredAddress: { city: "New York", country: "US", postalCode: "10003", stateOrProvince: "NY", street: "73 5th Avenue", street2: "12th floor" } } } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) address := legalEntityManagement.Address{ Country: "US", StateOrProvince: common.PtrString("NY"), City: common.PtrString("New York"), Street: common.PtrString("73 5th Avenue"), PostalCode: common.PtrString("10003"), Street2: common.PtrString("12th floor"), } organization := legalEntityManagement.Organization{ LegalName: "New Company Name", RegisteredAddress: address, RegistrationNumber: common.PtrString("101002750"), Type: common.PtrString("privateCompany"), } legalEntityInfo := legalEntityManagement.LegalEntityInfo{ Organization: &organization, } // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.UpdateLegalEntityInput("id").LegalEntityInfo(legalEntityInfo) res, httpRes, err := service.LegalEntitiesApi.UpdateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "organization": { "legalName": "New Company Name", "registrationNumber": "101002750", "type": "privateCompany", "registeredAddress": { "city": "New York", "country": "US", "postalCode": "10003", "stateOrProvince": "NY", "street": "73 5th Avenue", "street2": "12th floor" } } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :organization => { :legalName => 'New Company Name', :registrationNumber => '101002750', :type => 'privateCompany', :registeredAddress => { :city => 'New York', :country => 'US', :postalCode => '10003', :stateOrProvince => 'NY', :street => '73 5th Avenue', :street2 => '12th floor' } } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const address: Types.legalEntityManagement.Address = { country: "US", stateOrProvince: "NY", city: "New York", street: "73 5th Avenue", postalCode: "10003", street2: "12th floor" }; const organization: Types.legalEntityManagement.Organization = { legalName: "New Company Name", registeredAddress: address, registrationNumber: "101002750", type: Types.legalEntityManagement.Organization.TypeEnum.PrivateCompany }; const legalEntityInfo: Types.legalEntityManagement.LegalEntityInfo = { organization: organization }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` Verification checks will be run again when legal entity details are updated. ### Change legal entity type Users sometimes sign up with an incorrect legal entity type. To change the legal entity type to the correct one, you can make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request to update the legal entity type and then provide additional required information. All verification checks are run again after the legal entity type is changed. You can only change the type of the main legal entity. If the type of an associated legal entity is incorrect, you need to create a new legal entity. #### Retained information When you change the legal entity type, the following information is retained: * The legal entity id * Transfer instruments * Bank statement details * Proof of industry * Processed amounts * Business lines When changing between an individual and an organization legal entity, the following information is migrated: * The `country` is migrated from the individual `residentialAddress` to the organization `registeredAddress`. * The individual `name` is migrated to the organization `legalName`. When changing between an organization and an individual legal entity, the following information is migrated: * The `country` is migrated from the organization `registeredAddress` to the individual `residentialAddress`. * The organization `legalName` is migrated to the individual `name`. #### Make an API request You can only directly change a legal entity type from: * individual to organization * organization to individual The example below shows how you can change a legal entity from an individual to an organization. Provide the new `type` in your PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request: **Change legal entity type** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "type": "organization" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo() .type(LegalEntityInfo.TypeEnum.ORGANIZATION); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.updateLegalEntity("id", legalEntityInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $legalEntityInfo = new LegalEntityInfo(); $legalEntityInfo ->setType("organization"); // Send the request $service = new LegalEntitiesApi($client); $response = $service->updateLegalEntity('id', $legalEntityInfo); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo { Type = LegalEntityInfo.TypeEnum.Organization }; // Send the request var service = new LegalEntitiesService(client); var response = service.UpdateLegalEntity("id", legalEntityInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const legalEntityInfo = { type: "organization" } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) legalEntityInfo := legalEntityManagement.LegalEntityInfo{ Type: common.PtrString("organization"), } // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.UpdateLegalEntityInput("id").LegalEntityInfo(legalEntityInfo) res, httpRes, err := service.LegalEntitiesApi.UpdateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "organization" } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'organization' } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const legalEntityInfo: Types.legalEntityManagement.LegalEntityInfo = { type: Types.legalEntityManagement.LegalEntityInfo.TypeEnum.Organization }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` The response contains the updated legal entity with some of the data migrated to the new type. To update additional information, for example, the complete address, make another PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request. **Response** ```json { "organization": { "legalName": "Simone Hopper", "registeredAddress": { "country": "US" } }, "type": "organization", "id": "LE00000000000000000000001" } ``` To change the legal entity type from an organization to a sole proprietorship: 1. Change the legal entity type from organization to individual following the flow above. 2. Make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request and associate a sole proprietorship to the individual legal entity. --- # Source: https://docs.adyen.com/business-accounts/manage-sca-devices.md Section: Business accounts Title: Manage devices registered for SCA Description: View or deregister mobile devices used for Strong Customer Authentication (SCA). --- title: "Manage devices registered for SCA" description: "View or deregister mobile devices used for Strong Customer Authentication (SCA)." url: "https://docs.adyen.com/business-accounts/manage-sca-devices" source_url: "https://docs.adyen.com/business-accounts/manage-sca-devices.md" canonical: "https://docs.adyen.com/business-accounts/manage-sca-devices" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # Manage devices registered for SCA View or deregister mobile devices used for Strong Customer Authentication (SCA). [View source](/business-accounts/manage-sca-devices.md) After you registered devices for Strong Customer Authentication (SCA), you can use our API to: * [Get a list of registered devices](#get-registered-devices) * [Associate payment instruments to a registered device](#associate-business-accounts-to-a-registered-device) * [Deregister a device from a specific business account](#deregister-device) ## Requirements Ensure that your [API credential](/business-accounts/manage-access#manage-api-credentials) has the following role: * **Bank SCA Webservice Role** ## Get a list of registered devices After the device is registered, you use the API to get information about the SCA device connected to a specific business account such as the device ID, the name of the device, and the type of the device. This information can be helpful for building user interfaces or for checking the payment instrument's devices before [associating more](#associate-business-accounts-to-a-registered-device). To get a paginated list of the SCA devices registered for a specific business account: 1. Make a GET [/registeredDevices](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices) request. You can limit the amount of returned data by including the following query parameters: | Query parameter | Required | Description | | | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | - | | [paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#query-paymentInstrumentId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Limits the returned list to SCA devices registered for this business account. | | | [pageSize](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#query-pageSize) | | The number of items on a page. Default: 20. Maximum: 100. | | | [pageNumber](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#query-pageNumber) | | The index of the page to retrieve. The index of the first page is 0 (zero). Default: 0. | | The following example shows a GET [/registeredDevices](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices) request for the `paymentInstrumentId` **PI00000000000000000000001**. **Example GET /registeredDevices request** #### curl ```bash curl --request GET 'https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices?paymentInstrumentId=PI00000000000000000000001' \ --header 'X-API-Key:ADYEN_BALANCE_PLATFORM_API_KEY' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("", Environment.TEST); // Create the request object(s) RegisterSCARequest registerSCARequest = new RegisterSCARequest(); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); RegisterSCAResponse response = service.initiateRegistrationOfScaDevice(registerSCARequest, null); ``` #### PHP ```php setXApiKey(""); $client->setEnvironment(Environment::TEST); // Create the request object(s) $registerSCARequest = new RegisterSCARequest(); $registerSCARequest; // Send the request $service = new ManageScaDevicesApi($client); $response = $service->initiateRegistrationOfScaDevice($registerSCARequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) RegisterSCARequest registerSCARequest = new RegisterSCARequest }; // Send the request var service = new ManageScaDevicesService(client); var response = service.InitiateRegistrationOfScaDevice(registerSCARequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "", environment: "TEST" }); // Create the request object(s) const registerSCARequest = { } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateRegistrationOfScaDevice(registerSCARequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "", Environment: common.TestEnv, }) // Create the request object(s) registerSCARequest := balancePlatform.RegisterSCARequest, } // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.InitiateRegistrationOfScaDeviceInput().RegisterSCARequest(registerSCARequest) res, httpRes, err := service.ManageScaDevicesApi.InitiateRegistrationOfScaDevice(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_registration_of_sca_device(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = '' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_registration_of_sca_device(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "", environment: "TEST" }); // Create the request object(s) const registerSCARequest: Types.balancePlatform.RegisterSCARequest = }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateRegistrationOfScaDevice(registerSCARequest); ``` 2. In the response, note the following parameters: | Response parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [data](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#responses-200-data) | An array that contains a list of registered SCA devices and their corresponding details. | | [data.id](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#responses-200-data-id) | The unique identifier of the registered SCA device. | | [data.name](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#responses-200-data-name) | The name of the SCA device. You can show this name to your user to help them identify the device. | | [data.paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#responses-200-data-paymentInstrumentId) | The unique identifier of the business account for which the SCA device is registered. | | [data.type](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices#responses-200-data-type) | **ios**, **android**, **browser** | **Example GET /registeredDevices response** ```json { "data": [ { "id": "BSDR00000000000000000000000001", "name": "android_1709902088787", "paymentInstrumentId": "PI00000000000000000000001", "type": "android" } ], "itemsTotal": 1, "link": { "first": { "href": "https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices?pageNumber=0&paymentInstrumentId=PI00000000000000000000001" }, "last": { "href": "https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices?pageNumber=0&paymentInstrumentId=PI00000000000000000000001" }, "self": { "href": "https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices?pageNumber=0&paymentInstrumentId=PI00000000000000000000001" } }, "pagesTotal": 1 } ``` ## Associate business accounts to a registered device After you [register a device](/business-accounts/register-sca-devices/), you can connect additional payment instruments to the device using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). This enables a single device to handle authentication for multiple payment instruments. You can associate up to five payment instruments to a device per [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) API request. Each payment instrument can only be linked to one device. To add payment instruments to a registered device: 1. From your server, initiate the association by making a POST [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) request with the user's device ID as a path parameter. In the request body, specify up to five payment instrument IDs in the [ids](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations#request-ids) array. **Initiate the association** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/{deviceId}/associations \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "ids": [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], "type": "PaymentInstrument" }' ``` #### Java ```java // Adyen Java API Library v35.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AssociationInitiateRequest associationInitiateRequest = new AssociationInitiateRequest() .ids(Arrays.asList("PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005")) .type(AssociationInitiateRequest.TypeEnum.PAYMENTINSTRUMENT); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); AssociationInitiateResponse response = service.initiateAssociationBetweenScaDeviceAndResource("deviceId", associationInitiateRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $associationInitiateRequest = new AssociationInitiateRequest(); $associationInitiateRequest ->setIds(array("PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005")) ->setType("PaymentInstrument"); // Send the request $service = new ManageScaDevicesApi($client); $response = $service->initiateAssociationBetweenScaDeviceAndResource('deviceId', $associationInitiateRequest); ``` #### C\# ```cs // Adyen .net API Library v31.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AssociationInitiateRequest associationInitiateRequest = new AssociationInitiateRequest { Ids = { "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" }, Type = AssociationInitiateRequest.TypeEnum.PaymentInstrument }; // Send the request var service = new ManageScaDevicesService(client); var response = service.InitiateAssociationBetweenScaDeviceAndResource("deviceId", associationInitiateRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v26.0.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const associationInitiateRequest = { ids: [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], type: "PaymentInstrument" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateAssociationBetweenScaDeviceAndResource("deviceId", associationInitiateRequest); ``` #### Go ```go // Adyen Go API Library v20.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v20/src/common" "github.com/adyen/adyen-go-api-library/v20/src/adyen" "github.com/adyen/adyen-go-api-library/v20/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) associationInitiateRequest := balancePlatform.AssociationInitiateRequest{ Ids: []string{ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005", }, Type: "PaymentInstrument", } // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.InitiateAssociationBetweenScaDeviceAndResourceInput("deviceId").AssociationInitiateRequest(associationInitiateRequest) res, httpRes, err := service.ManageScaDevicesApi.InitiateAssociationBetweenScaDeviceAndResource(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.4.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "ids": [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], "type": "PaymentInstrument" } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_association_between_sca_device_and_resource(request=json_request, deviceId="deviceId") ``` #### Ruby ```rb # Adyen Ruby API Library v10.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :ids => [ 'PI00000000000000000000001', 'PI00000000000000000000002', 'PI00000000000000000000003', 'PI00000000000000000000004', 'PI00000000000000000000005' ], :type => 'PaymentInstrument' } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_association_between_sca_device_and_resource(request_body, 'deviceId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v26.0.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const associationInitiateRequest: Types.balancePlatform.AssociationInitiateRequest = { ids: ["PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005"], type: Types.balancePlatform.AssociationInitiateRequest.TypeEnum.PaymentInstrument }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateAssociationBetweenScaDeviceAndResource("deviceId", associationInitiateRequest); ``` The response contains a Base64-encoded string, which our [Authentication SDKs](/business-accounts/install-auth-sdk/#installation) uses to authenticate the requested association. You do not need to decode or validate this string. **POST /association response** ```json { "sdkInput": "eyJtZXNzYWdlIjogIkFuIGV4YW1wbGUgZW5jb2RlZCBtZXNzYWdlLiBUaGlzIGlzIHdoYXQgeW91IG1pZ2h0IGdldCBvdXQgb2YgdGhlIGF1dGhlbnRpY2F0aW9uIFNESy4gSG93ZXZlciwgeW91IHdvdWxkIG5vdCBuZWVkIHRvIGRlY29kZSBpdCAtLSBqdXN0IGtlZXAgaXQgZW5jb2RlZCwgb2theT8ifQ==" } ``` 2. Pass the resulting `sdkInput` to your client. 3. On your client, initialize the SDK and call the `authenticate()` method using the `sdkInput` from your server as an argument. The `authenticate()` method prompts the user to respond to a challenge, for example, Touch ID, Face ID, or the device password. ### Tab: Android (Kotlin) ```kotlin lifecycleScope.launch { if (adyenAuthentication.hasCredential("sdkInput")) { // Authenticate existing credential val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput") when (authenticationResult) { is AuthenticationResult.AuthenticationSuccessful -> { authenticationResult.sdkOutput } is AuthenticationResult.Canceled -> { // User cancelled the authentication flow } is AuthenticationResult.Error -> { // Unexpected error authenticationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error authenticationResult.authenticationError } } } else { // None of the existing credentials exist in this device } } ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. ### Tab: iOS (Swift) ```swift delegatedAuthenticationSession.authenticate(withBase64URLString: sdkInput) { [weak self] result in switch result { case let .success(sdkOutput): /// send the sdkOutput to the backend case let .failure(error): /// authentication failed } } ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) ```javascript import ScaWebauthn from '@adyen/bpscaweb'; // Initialize the scaWebauthn instance const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'YOUR_MERCHANT_NAME', }); // Launch the authentication flow const authenticationResult = await scaWebauthn.authenticate(sdkInput) .catch((error) => { // Example: NotAllowedError: The operation either timed out or was not allowed. // See https://webidl.spec.whatwg.org/#idl-DOMException-error-names for possible webauthn errors. }); ``` The `authenticate()` function returns a Base64-encoded string that contains data about the user authentication and challenge. You can check that the authentication result is not empty to verify that the authentication was successful. You do not need to decode or validate this string. **Authentication result** ```javascript console.log(authenticationResult) // eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0= ``` 4. Pass the authentication result to your server. 5. On your server, finalize the association by making a PATCH [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(deviceId\)/associations) request using the device ID as a path parameter. In the request body, specify the following: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | [ids](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations#request-ids) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array of the payment instrument IDs that you want to associate. These IDs must be the same that you sent in the POST request in step 1. | | [strongCustomerAuthentication.sdkOutput](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(deviceId\)/associations#request-strongCustomerAuthentication-sdkOutput) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The data returned from the client-side `authenticate()` method. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(deviceId\)/associations#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of resource that you are associating with the SCA device. Possible value: **PaymentInstrument** | **Finalize the assocation** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/{deviceId}/associations \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "ids": [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], "strongCustomerAuthentication": { "sdkOutput": "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=" }, "type": "PaymentInstrument" }' ``` #### Java ```java // Adyen Java API Library v35.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) AssociationDelegatedAuthenticationData associationDelegatedAuthenticationData = new AssociationDelegatedAuthenticationData() .sdkOutput("eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0="); AssociationFinaliseRequest associationFinaliseRequest = new AssociationFinaliseRequest() .strongCustomerAuthentication(associationDelegatedAuthenticationData) .ids(Arrays.asList("PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005")) .type(AssociationFinaliseRequest.TypeEnum.PAYMENTINSTRUMENT); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); AssociationFinaliseResponse response = service.completeAssociationBetweenScaDeviceAndResource("deviceId", associationFinaliseRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $associationDelegatedAuthenticationData = new AssociationDelegatedAuthenticationData(); $associationDelegatedAuthenticationData ->setSdkOutput("eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0="); $associationFinaliseRequest = new AssociationFinaliseRequest(); $associationFinaliseRequest ->setStrongCustomerAuthentication($associationDelegatedAuthenticationData) ->setIds(array("PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005")) ->setType("PaymentInstrument"); // Send the request $service = new ManageScaDevicesApi($client); $response = $service->completeAssociationBetweenScaDeviceAndResource('deviceId', $associationFinaliseRequest); ``` #### C\# ```cs // Adyen .net API Library v31.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AssociationDelegatedAuthenticationData associationDelegatedAuthenticationData = new AssociationDelegatedAuthenticationData { SdkOutput = "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=" }; AssociationFinaliseRequest associationFinaliseRequest = new AssociationFinaliseRequest { StrongCustomerAuthentication = associationDelegatedAuthenticationData, Ids = { "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" }, Type = AssociationFinaliseRequest.TypeEnum.PaymentInstrument }; // Send the request var service = new ManageScaDevicesService(client); var response = service.CompleteAssociationBetweenScaDeviceAndResource("deviceId", associationFinaliseRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v26.0.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const associationFinaliseRequest = { ids: [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], strongCustomerAuthentication: { sdkOutput: "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=" }, type: "PaymentInstrument" } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.completeAssociationBetweenScaDeviceAndResource("deviceId", associationFinaliseRequest); ``` #### Go ```go // Adyen Go API Library v20.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v20/src/common" "github.com/adyen/adyen-go-api-library/v20/src/adyen" "github.com/adyen/adyen-go-api-library/v20/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) associationDelegatedAuthenticationData := balancePlatform.AssociationDelegatedAuthenticationData{ SdkOutput: "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=", } associationFinaliseRequest := balancePlatform.AssociationFinaliseRequest{ StrongCustomerAuthentication: associationDelegatedAuthenticationData, Ids: []string{ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005", }, Type: "PaymentInstrument", } // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.CompleteAssociationBetweenScaDeviceAndResourceInput("deviceId").AssociationFinaliseRequest(associationFinaliseRequest) res, httpRes, err := service.ManageScaDevicesApi.CompleteAssociationBetweenScaDeviceAndResource(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.4.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "ids": [ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ], "strongCustomerAuthentication": { "sdkOutput": "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=" }, "type": "PaymentInstrument" } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.complete_association_between_sca_device_and_resource(request=json_request, deviceId="deviceId") ``` #### Ruby ```rb # Adyen Ruby API Library v10.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :ids => [ 'PI00000000000000000000001', 'PI00000000000000000000002', 'PI00000000000000000000003', 'PI00000000000000000000004', 'PI00000000000000000000005' ], :strongCustomerAuthentication => { :sdkOutput => 'eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=' }, :type => 'PaymentInstrument' } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.complete_association_between_sca_device_and_resource(request_body, 'deviceId') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v26.0.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const associationDelegatedAuthenticationData: Types.balancePlatform.AssociationDelegatedAuthenticationData = { sdkOutput: "eyJtZXNzYWdlIjogIlRoaXMgaXMgd2hhdCB5b3UgbWlnaHQgZ2V0IGFzIGEgcmVzdWx0IGZvciB0aGUgYXV0aGVudGljYXRlKCkgbWV0aG9kLiBJdCB3aWxsIGhhdmUgbG90cyBvZiBkaWZmZXJlbnQgaW5mb3JtYWl0b24gaW4gaXQsIGJ1dCB0aGVyZSBpcyBubyByZWFzb24gZm9yIHlvdSB0byBkZWNvZGUgaXQgb3IgaW5zcGVjdCBpdC4gV2Ugd2lsbCBoYW5kbGUgdGhhdCBmb3IgeW91ISBTbywgZmVlbCBmcmVlIHRvIGRlY29kZSBpdC4gSG93ZXZlciwgZG8gbm90IHJlLWVuY29kZSBpdCBhbmQgZXhwZWN0IHRoZSBzYW1lIHJlc3VsdC4gVGhlIFNESyBlbmNvZGVzIHRoZSBibG9iIGluIGEgc3BlY2lmaWMgd2F5LCBhbmQgaWYgeW91IGRlY29kZSBpdCBhbmQgcmUtZW5jb2RlIGl0LCB5b3UgbWlnaHQgaW50cm9kdWNlIHByb2JsZW1zLiBTbywganVzdCBsZWF2ZSBpdCBlbmNvZGVkIG9rYXk/In0=" }; const associationFinaliseRequest: Types.balancePlatform.AssociationFinaliseRequest = { strongCustomerAuthentication: associationDelegatedAuthenticationData, ids: ["PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005"], type: Types.balancePlatform.AssociationFinaliseRequest.TypeEnum.PaymentInstrument }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.completeAssociationBetweenScaDeviceAndResource("deviceId", associationFinaliseRequest); ``` If the association is successful, the API responds with a list of payment instrument IDs. To verify the association, [get a list of registered devices](#get-registered-devices) for each of the payment instruments. **PATCH /association response** ```json { "deviceId":"BSDR4294N223223N5M6J9T2BP46HVK", "type":"PaymentInstrument", "ids":[ "PI00000000000000000000001", "PI00000000000000000000002", "PI00000000000000000000003", "PI00000000000000000000004", "PI00000000000000000000005" ] } ``` ## Troubleshooting device association The following examples show some common issues you may encounter during the association process. ** ### Device limit reached **POST /associations response** ```json { "type": "https://docs.adyen.com/errors/unprocessable-entity", "errorCode": "00_422", "title": "Unprocessable entity", "detail": "Device limit reached, please delete a device and try again", "requestId": "5ffa18b720392054047e8b33cc271d98", "status": 422 } ``` The "Device limit reached, please delete a device and try again" error detail means that one or more of the payment instrument IDs in the POST [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) call is already linked to a device. #### Solution To avoid this error, all payment instrument IDs passed in the POST [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) call need to be deregistered. 1. [Get a list of registered devices](#get-registered-devices). 2. If the payment instrument has a device in its `data` array, [deregister the device](#deregister-device). After you have deregistered all of the payment instruments, retry the POST [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) request. ** ### Challenge not found **PATCH /associations response** ```json { "type": "https://docs.adyen.com/errors/unprocessable-entity", "errorCode": "00_422", "title": "Unprocessable entity", "detail": "Challenge not found", "requestId": "de2c4f16b79a883ad1989122bad98d15", "status": 422 } ``` The 422 "Challenge not found" error usually occurs when the client device ID for the challenge does not match the device ID in the PATCH [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(deviceId\)/associations) request. When a client authenticates using the Adyen SCA library, the library produces an `sdkOuput` that is specific to the client device. If you send an sdkOutput that does not correspond to the device that you want to associate, then you get a "Challenge not found" error. #### Solution Ensure that the device ID used in the initial POST [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices/\(deviceId\)/associations) request matches the one used in the PATCH [/registeredDevices/{deviceId}/associations](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(deviceId\)/associations) request. As long as the IDs match between the POST and the PATCH, the "Challenge not found" error will be prevented. ** ### NotAllowedError: The operation either timed out or was not allowed. The client-side `authenticate()` method failed because the user canceled the challenge. This is similar to other client-side errors that can occur. These are standard errors for [WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API). Go to [Web IDL standard](https://webidl.spec.whatwg.org/#idl-DOMException-error-names) for a list of possible exception error names. #### Solution To avoid this error, tell your user before the authentication process begins that they are about to be asked to authenticate. To handle this error, return the user to the previous step and ask them to retry. You can reuse the same `sdkInput` when you retry `authenticate()` in the same session. ## Deregister a device from a business account You can deregister an SCA device from a business account by making a DELETE  [/registeredDevices/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/registeredDevices/\(id\)) request. You can do this when, for example: * Your user will no longer use a registered device. * A registered device has been compromised. If the SCA device is associated with multiple business accounts, you must make a request for each business account. To deregister an SCA device from a business account: 1. [Get the ID of the device](#get-registered-devices) that you want to deregister. 2. Make a DELETE  [/registeredDevices/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/registeredDevices/\(id\)) request and include the following parameters: | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/registeredDevices/\(id\)#path-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the SCA device that you want to deregister. | | [paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/registeredDevices/\(id\)#query-paymentInstrumentId) | Query | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the business account from which you want to deregister the device. | The following example shows a request to deregister an SCA device with `id` **BSDR00000000000000000000000001** from the `paymentInstrumentId` **PI00000000000000000000001**. **Example DELETE /registeredDevices/{id} request** #### curl ```bash curl --request DELETE 'https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/BSDR00000000000000000000000001?paymentInstrumentId=PI00000000000000000000001' \ --header 'X-API-Key;' ``` #### Java ```java // Adyen Java API Library v26.2.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); service.deleteRegistrationOfScaDevice("id", "String", null); ``` #### PHP ```php // Adyen PHP API Library v18.2.0 use Adyen\Client; use Adyen\Environment; use Adyen\Service\BalancePlatform\ManageScaDevicesApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('paymentInstrumentId' => 'string'); // Send the request $service = new ManageScaDevicesApi($client); $service->deleteRegistrationOfScaDevice('id', $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v16.1.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new ManageScaDevicesService(client); service.DeleteRegistrationOfScaDevice("id", paymentInstrumentId: "string"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use const { Client, BalancePlatformAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); balancePlatformAPI.ManageScaDevicesApi.deleteRegistrationOfScaDevice("id", "string"); ``` #### Go ```go // Adyen Go API Library v10.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.DeleteRegistrationOfScaDeviceInput("id") req = req.PaymentInstrumentId("string") service.ManageScaDevicesApi.DeleteRegistrationOfScaDevice(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.5.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. query_parameters = { "paymentInstrumentId" : "string" } # Send the request adyen.balancePlatform.manage_sca_devices_api.delete_registration_of_sca_device(id="id", query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v9.5.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :paymentInstrumentId => 'string' } # Send the request adyen.balancePlatform.manage_sca_devices_api.delete_registration_of_sca_device('id', query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); balancePlatformAPI.ManageScaDevicesApi.deleteRegistrationOfScaDevice("id", "string"); ``` 3. Verify that you receive a **204** HTTP response with no content. This indicates that the request succeeded. --- # Source: https://docs.adyen.com/business-accounts/oauth-flow.md Section: Business accounts Title: Get account holder consent Description: Learn how to get an access and refresh token. --- title: "Get account holder consent" description: "Learn how to get an access and refresh token." url: "https://docs.adyen.com/business-accounts/oauth-flow" source_url: "https://docs.adyen.com/business-accounts/oauth-flow.md" canonical: "https://docs.adyen.com/business-accounts/oauth-flow" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Get account holder consent Learn how to get an access and refresh token. [View source](/business-accounts/oauth-flow.md) Adyen uses [OAuth 2.0](https://oauth.net/2/), an open standard for authorization, to allow third-party applications to get an account holder's explicit consent to access their account data. This page explains how to get an account holder's consent to access their Adyen business account information. ## Requirements | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Setup steps** | Before you begin, you must complete the [Adyen onboarding steps](/business-accounts/open-banking#onboard-with-adyen). | ## How it works Here is how the OAuth flow works with Adyen open banking: * In your client app, the account holder selects to give access to their payment data with Adyen. * Your client app [redirects the account holder](#redirect-account-holder-for-authentication) to Adyen's authentication interface so they can authenticate and give their consent to access their account data. Depending on the consent they give, you can check their account details, view the balance on their account, or initiate a payment. * Adyen generates an authorization code and returns it to your client app through the redirect URL. * Your server uses the authorization code to [get an access token](#get-an-access-token). The access token is needed for two things: * To authenticate open banking requests to Adyen for this account holder. * To get the account holder's consent ID, which is needed to get their account details. * Your server uses the access token to [create a consent](#create-a-consent) and get a `consentId`. After you get the access token and the `consentId`, you can make requests to Adyen open banking APIs to retrieve the account holder's Adyen business account details. ## Implement Adyen connect button In your app or on your website, implement a **Connect with Adyen** button. This button sends a GET `/bankoauth/authorize` request to your server, which redirects the account holder to an Adyen dialog for authentication and consent. Use the URL from the next step to get the account holder's consent. ## Redirect account holder for authentication To redirect the account holder so they can authenticate and give consent: 1. Make a GET `/bankoauth/authorize` request with the following query parameters: Note that this request does not require any type of authorization. | Parameter | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Identifies the client (your app) making the request. This should match the QWAC certificate’s organization identifier. | | `response_type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the response type expected from the authorization server. Set to **code**. | | `redirect_uri` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the URI to which the authorization server redirects the user after authentication and consent. | | `scope` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Defines the requested permissions or access levels that the client is seeking. It specifies the scope of the resources or actions the client intends to access on behalf of the user. Multiple scopes can be requested, separated by spaces. Possible values: **bank.aisp:read**, **bank.pisp:write**, and **bank.cof:read**. | | `code_challenge_method` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **S256**. | | `code_challenge` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | SHA256 hash of the `code_verifier` to be provided when [getting the access token](#get-an-access-token) in the next step. The code\_verifier is a random string generated by the third-party provider. | | `state` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A string generated by the client, which is included in the request and returned by the authorization server. It helps maintain the integrity of the authorization flow by preventing CSRF attacks. | By including these parameters, the authorization server can properly authenticate the account holder. Here is an example of a GET request: **Get authentication instructions for the account holder** ```bash curl 'https://balanceplatform-test.adyen.com/bankoauth/authorize?client_id={CLIENT_ID}&code_challenge_method=S256&code_challenge={CODE_CHALLENGE}&response_type=code&redirect_uri={REDIRECT_URI}&state={STATE}&scope={SCOPE}' ``` 2. Embed the HTML code that you receive in the response into your app or website so the account holder can authenticate with their Adyen business account. 3. After the account holder has authenticated, get the `code` that is sent back to your client's `redirect_uri`. You need this code in the next step, to get an access token. This redirect will include the following query parameters in the URL. | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | The authorization code used to [exchange for an access token](#get-an-access-token). The `code` is short-lived and expires in five minutes. | | `state` | The same value as in the initial redirect URL. | An example of a redirect URL may look like this: **Redirect URL with authorization code** ```bash https://{redirect_uri}?code={code}&state={state} ``` ## Get an access token To exchange the authorization code from the previous step for an access token: 1. From the server, make a POST `/token` request with the following parameters in the request body: | Parameter | Required | Description | | --------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `grant_type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **authorization\_code**. | | `code` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The authorization code provided in the redirect URL. | | `code_verifier` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The code verifier. | | `redirect_uri` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The redirect URI for your client. | **Authentication type**: use `client_id` and `client_secret` for basic authentication. **Get access token** ```bash curl 'https://oauth-test.adyen.com/v1/token' \ --header 'Authorization: Basic {BASE64(client_id:client_secret)}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code={CODE}' \ --data-urlencode 'code_verifier={CODE_VERIFIER}' \ --data-urlencode 'redirect_uri={REDIRECT_URI}' ``` 2. From the response, save the `access_token` and the `refresh_token`. You need the `access_token` in the next step, to get a `consentId`. The response contains the following fields: | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `token_type` | The token type: **bearer**. | | `expires_in` | The expiry of the access token, in seconds. By default, 24 hours. | | `access_token` | The access token which can be used to access the open banking APIs. | | `scope` | The scope for the `access_token`. Multiple scopes are possible, separated by spaces. | | `refresh_token` | The OAuth refresh token that you can use to get new access tokens with the same scope. The refresh token expires as soon as it is used, providing a new access token and a new refresh token. A refresh token is one-time-use. | **Response** ```json { "token_type": "bearer", "expires_in": 86400, "access_token": "oa_tzNbAuwtPQEogej95u5RH7sbYQ6ugQ2PQ5tp4IkuOqgI0iM", "scope": "bank.aisp:read bank.pisp:write", "accounts": [ "NL57INGB4654188101" ], "refresh_token": "oa_6sL3R9KDN8zzC5XQ2WhtKr1AxXy0gvikcPo9i1CO6APU0PK" } ``` If you lose the refresh token, there is no way to recover the granted access. You will need to [redirect the account holder for authentication](#redirect-account-holder-for-authentication) again. ## Create a consent To create a new consent use the access token to get a `consentId`. This `consentId` is needed to get the account details for the account holder. This consent needs to be approved by the account holder to continue. 1. Make a POST `/consents` request with the following parameters in the request body. The request header includes the `TPP-Signature-Certificate: QSEALCertificate`, which is the full eIDAS certificate encoded in Base64 format. | Parameter | Required | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `access` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of access requested. Set `allPsd2` to **allAccounts**. This means you are requesting access to all of the user's accounts with Adyen. | | `recurringIndicator` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Indicates that the consent is being requested for recurring access to the user's account information or payment initiation. | | `validUntil` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the consent's validity end date in YYYY-MM-DD (ISO format). Maximum 90-day duration and 10 uses per day. Consent expires after this date. | | `frequencyPerDay` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Indicates the maximum number of times per day that you are allowed to access the user's account information or initiate payments. | | `combinedServiceIndicator` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Indicates whether you are requesting access to the user's account information or payment initiation services individually or as a combined service. | **Create a new consent** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/consent/v1/consents' \ --header 'X-Request-ID: {your-request-id}' \ --header 'TPP-Signature-Certificate: QSEALCertificate' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {access-token}' \ --data '{ "access" : { "allPsd2": "allAccounts" }, "recurringIndicator": true, "validUntil": "2025-12-31", "frequencyPerDay": 10, "combinedServiceIndicator": false }' ``` 2. The response contains the `consentStatus`, `consentId`, and links to requested resources. From the response, save the `consentId`, you need this for the Adyen open banking requests to get the account details for this account holder. You can continue to poll the endpoint until you receive an updated `consentStatus`. * If you want to get information about consent authorization and to determine where your account holder is in the authentication flow, you will need the `authorization-id-consent`. This is the last set of characters at the end of the`scaStatus` link below. Save this `authorization-id-consent` to use in the [get authorization information](/business-accounts/consent#check-the-authorization-status-of-an-account-holders-consent). **Response** ```json { "consentStatus": "received", "consentId": "09289d2e-83ae-4a61-8452-ac23cf0055de", "_links": { "self": { "href": "consent/v1/consents/09289d2e-83ae-4a61-8452-ac23cf0055de" }, "status": { "href": "consent/v1/consents/09289d2e-83ae-4a61-8452-ac23cf0055de/status" }, "scaStatus": { "href": "consent/v1/consents/09289d2e-83ae-4a61-8452-ac23cf0055de/authorisations/OBAU4222Z223222P5J6FP7BDG34LW3" } } } ``` ## Refresh an access token Because the access token is short-lived, a new access token has to be requested regularly to continue using open banking APIs. To find your original refresh token, see the response from [get an access token](#get-an-access-token). To refresh an access token: 1. Make a POST request to the `/token` endpoint. Provide the following parameters in the request body: | Parameter | Required | Description | | --------------- | ------------------------------------------------------------------------------------------- | -------------------------- | | `grant_type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **refresh\_token**. | | `refresh_token` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The refresh token. | **Authentication type**: use `client_id` and `client_secret` for basic authentication. **Refresh access token** ```bash curl --request POST 'https://oauth-test.adyen.com/v1/token' \ --header 'Authorization: Basic {BASE64(client_id:client_secret)}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'refresh_token={REFRESH_TOKEN}' ``` 2. From the response, save the new `access_token` and `refresh_token`. The response contains the following fields: | Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token_type` | The token type: **bearer**. | | `expires_in` | The expiry of the access token, in seconds. By default, 24 hours. | | `access_token` | The access token which can be used to access the open banking APIs. | | `refresh_token` | The OAuth refresh token that you can use to get new access tokens with the same scope. The refresh token has an unlimited validity but it expires with a short grace period when the refresh token is used to renew the access token. A refresh token is one-time-use. | ```json { "token_type": "bearer", "expires_in": 86400, "access_token": "oa_Elnme5TE0FH0v8qXEAQ56ME0Zxp0s1ETtGizd07mEY0MTh1", "refresh_token": "oa_T7ZKiG5HsdTBAstDksw4WslQhbQQr0CwfSom90NkSV9w8zB" } ``` ## Next steps [required](/business-accounts/consent) [Consent interface](/business-accounts/consent) [Learn how to manage user consents with our dedicated endpoints.](/business-accounts/consent) [AISP interface](/business-accounts/aisp) [Learn how to consume our dedicated AISP endpoints.](/business-accounts/aisp) [PISP interface](/business-accounts/pisp) [Learn how to consume our dedicated PISP endpoints.](/business-accounts/pisp) [PIISP interface](/business-accounts/piisp) [Learn how to consume our dedicated PIISP endpoints.](/business-accounts/piisp) --- # Source: https://docs.adyen.com/business-accounts/onboard-users.md Section: Business accounts Title: Onboard and verify users Description: Learn to move your users through the onboarding and verification process. --- title: "Onboard and verify users" description: "Learn to move your users through the onboarding and verification process." url: "https://docs.adyen.com/business-accounts/onboard-users" source_url: "https://docs.adyen.com/business-accounts/onboard-users.md" canonical: "https://docs.adyen.com/business-accounts/onboard-users" last_modified: "2024-03-04T17:27:00+01:00" language: "en" --- # Onboard and verify users Learn to move your users through the onboarding and verification process. [View source](/business-accounts/onboard-users.md) Your users' legal entity type and operating country determine the [required verification information](/business-accounts/verification-requirements) you need to collect from your users. You must build your own UI to collect this information and submit it to Adyen using our APIs. After Adyen receives the information, the [verification process](/business-accounts/verification-overview) starts automatically. ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) integration, there are no additional requirements, limitations, or preparations. ## API-only onboarding With API-only onboarding, you need to build your own UI where you collect data from your users. You then need to submit the collected data to Adyen by making requests to the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) and the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). You can onboard users operating in any of the [countries and regions where business accounts are supported](/business-accounts#supported-countriesregions). ### Onboarding v4 requirements The following requirements apply if you want to offer business accounts to your users. #### Source of funds Only applicable for [business accounts](/business-accounts/) and [card issuing](/issuing). Adyen is required to verify the source of funds (SOF) used to fund an account. This requirement is applicable for both [card issuing](/issuing) and [business accounts](/business-accounts/). Depending on the type of funds, we may request additional documents as proof. We strongly recommend that you have these documents available before starting in order to speed up this process. To submit this information to Adyen, make a POST [/businessLines](https://docs.adyen.com/api-explorer/legalentity/4/post/businessLines) request, specifying the `service` as either: * **banking** for business accounts * **issuing** for card issuing If the source of funds was processed through Adyen, set the `sourceOfFunds.adyenProcessedFunds` to **true**. If the source of funds was not processed through Adyen, set the `sourceOfFunds.adyenProcessedFunds` to **false**. You must then include the `sourceOfFunds.type` and `sourceOfFunds.description`. The description must state the origin of the source of funds. The following table shows the accepted funding sources and the required documents for each type, if requested. If the type of accepted document has a listed date requirement, the document must meet this requirement. | Type of Source of Funds | `businessLines.sourceOfFunds.type` API value | Documents must show | Examples of accepted documents | | ----------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Business earnings processed through Adyen | Set `businessLines.adyenProcessedFunds` to **true** | N/A | No supporting document is required | | Previous business earnings | **business** | * Name of company * Amounts earned * Description of business activity | - Latest accounts (issued within the last financial year) - Annual Statements (within 12 months) - Latest tax filing (issued within the last year) - Letter from accountant (signed and dated within 12 months) - Recent Invoices (last 3 months) | | (Previous) employment | **employment** | * Your business name * Date document was issued * Bank logo/name (for bank statement) * Employer’s name (for payslips) | - Last 3 months of bank statements - Last 3 months of payslips | | Cryptocurrency | **cryptocurrencyIncome** | * Your business name * Date document was issued (no older than 12 months) * Name of Crypto-exchange * Name of coin | - Proof of ownership of wallet - Statement of transaction history (showing crypto) - Latest tax report (showing crypto) (no older than 12 months) | | Investments (dividends) | **dividendIncome** | * Your business name * The date your business received the money * The amount received * The type of investments * Names of the parties involved | - Contract specifying dividends - Latest tax returns of the company (no older than 12 months) - Investment certificate - Broker statement (issued within 3 months) | | Loans | **loans** | * Your business name * Amount you borrowed * The date you received the money * Name of the lender * Address of the lender * Purpose of the loan | - Loan agreement - Loan statement (no older than 12 months) | | Subsidies / Grants | **financialAid** | * Amount of Subsidy / Grant * Providers(s) of Subsidy / Grant * Time Period | - Confirmation of Subsidy / Grant - Subsidy Receipt | | Third Party Funding (capital investments) | **thirdPartyFunding** | * Your business name * The date your business received the money * The amount received * Names of the parties involved * Addresses of the parties involved * Signatures of the parties involved * Payment purpose | - Investor contracts - Investor memoranda - Notarized statements (no older than 12 months) - Partnership agreement | | Property Sale | **assetSale** | * Date money was received * Amount you received * Address (if applicable) * Description of property | - Proof of ownership (notarized) - Signed letter from the solicitor / estate agent (no older than 12 months) - Copy of contract of sale - Tax declaration (no older than 12 months) - Title deed (notarized) | | Rental Income | **rentalIncome** | * Amount received * Address * Name of parties to the agreement | - Rental Agreement - Proof of Ownership | | Donations / Gifts | **donations** | * Amount received * Date of transfer * Full name of donor | - Original or certified copy of grant | | Royalty Income | **royaltyIncome** | * Description of (intellectual) property * Amount received | - Royalty agreement - Tax declaration (no older than 12 months) | | Gambling / Lottery | **gamblingWinnings** | * Amount won * Date of winning * Location / Site | - Proof of Winnings - Win Report - Win/Loss Statement (issued within 3 months) - Tax declaration that shows winnings (issued within 12 months) | | Inheritance | **inheritance** | * Name of person who made the will * Amount received / Value of estate * Date received * Name of benefactor | - Certificate of inheritance - A grant of probate - Letter from solicitor / notary (no older than 12 months) - Signed copy of the will | | Pension | **pensionIncome** | * Amount to be received * Legal Name of recipient | - Pension slip (no older than 12 months) - Letter from previous employer - Pension statement form (no older than 12 months) | | Insurance / Settlement | **insuranceSettlement** | * Amount of settlement * Legal name of recipient * Date received | - Court order - Letter from lawyer / solicitor - Letter from insurer | #### Requirements for specific countries/regions In the European Union, organizations must provide either their annual turnover or their annual balance sheet. In your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request, specify `organization.financialReports.annualTurnover` or `organization.financialReports.balanceSheetTotal`. In the United Kingdom, organizations must provide their number of employees, and either their annual turnover or annual balance sheet. In your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request, specify `organization.financialReports.employeeCount` and either `organization.financialReports.annualTurnover` or `organization.financialReports.balanceSheetTotal`. ## Onboarding steps After you complete all the steps in the integration checklist for your platform or marketplace integration, you must provide [additional verification information](/business-accounts/verification-requirements) so that your users can use business accounts. If you are creating a new account holder for which you want to request business accounts, you must first follow the onboarding steps for your [platform](/platforms/onboard-users/onboarding-steps) or [marketplace](/marketplaces/onboard-users/onboarding-steps) integration. In addition, you can use API-only onboarding to provide us with the additional information required for business accounts. If you already have an existing, verified account holder, and want to request business accounts for them, you only need to provide the additional information required for business accounts using API-only onboarding. ## Next steps [Verification process](/business-accounts/verification-overview) [Learn how Adyen verifies the users in your balance platform.](/business-accounts/verification-overview) [Determine verification requirements](/business-accounts/verification-requirements) [Learn what verification information you must collect from your users before offering them business accounts.](/business-accounts/verification-requirements) --- # Source: https://docs.adyen.com/business-accounts/onboard-users/terms-of-service.md Section: Business accounts Title: Terms of Service Description: Get your users to accept Adyen's Terms of Service --- title: "Terms of Service" description: "Get your users to accept Adyen's Terms of Service" url: "https://docs.adyen.com/business-accounts/onboard-users/terms-of-service" source_url: "https://docs.adyen.com/business-accounts/onboard-users/terms-of-service.md" canonical: "https://docs.adyen.com/business-accounts/onboard-users/terms-of-service" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Terms of Service Get your users to accept Adyen's Terms of Service [View source](/business-accounts/onboard-users/terms-of-service.md) Your users must accept Adyen's Terms of Service before they can perform particular actions in your balance platform. You must generate a Terms of Service document, show the document to your users, and ask them to accept it. The Terms of Service document must be accepted by an individual legal entity that represents a physical person. For organizations, the document must be accepted by an authorized signatory of the organization. * A business account holder accepts the document on their own behalf. * The owner of a restaurant accepts the document on behalf of the legal entity that represents the business. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | **Integration type** | You must have an Adyen for Platforms integration. | | | **API credentials** | You must have API credentials for the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) (for example, **ws\[123456]@Scope.Company\[YourCompanyAccount]**) | | | **Webhooks** | Ensure that your server can receive and accept [standard webhooks](/development-resources/webhooks). Subscribe to the following webhooks:- [Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview) | | | **Setup steps** | Before you begin, make sure:- Make sure you created legal entities for: * The user that has a contractual relationship with your balance platform. * The individual legal entity who will accept the document. | | ## How it works To generate the Terms of Service and have them accepted by your users, follow these steps: 1. Listen to the webhook to [confirm Terms of Service requirements](#get-updates). 2. Make an API request to [get the types of Terms of Service required](#get-required). 3. Make an API request to [generate the Terms of Service documents](#get-document). 4. [Present the Terms of Service document](#present-document) to your user. 5. Make an API request to [confirm that your user has accepted the Terms of Service](#accept-tos). 6. Optionally, make an API request to [see the Terms of Service information for a specific legal entity](#tos-for-le). ## 1. Confirm Terms of Service requirements When you create an account holder, certain [capabilities](/business-accounts/verification-overview/capabilities) are requested for them. To check whether your user must accept the Terms of Service, listen to [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks. If your user is required to accept Adyen's Terms of Service, it is indicated in the `verificationErrors` array. **balancePlatform.accountHolder.updated webhook - with verification errors array** ```json { "data":{ "accountHolder":{ "capabilities":{ "sendToTransferInstrument":{ "allowed":"false", "enabled":"true", "problems":[ { "entity":{ "id":"LE00000000000000000000001", "type":"LegalEntity" }, "verificationErrors":[ { "code":"2_902", "message":"Terms Of Service forms are not accepted.", "remediatingActions":[ { "code":"2_902", "message":"Accept TOS" } ], "type":"invalidInput" } ] } ], "requested":"true", "verificationStatus":"invalid" } }, "description":"Test Account holder", "reference":"YOUR_INTERNAL_IDENTIFIER", "id":"AH00000000000000000000001", "legalEntityId":"LE00000000000000000000001", "status":"Active" }, "balancePlatform":"YOUR_BALANCE_PLATFORM" }, "environment":"test", "type":"balancePlatform.accountHolder.updated" } ``` ## 2. Get the types of Terms of Service required If your user is required to accept Adyen's Terms of Service, you must determine which types of documents they need to accept. Make a GET [/legalEntities/{id}/termsOfServiceStatus](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)/termsOfServiceStatus) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. Note that your user may need to accept more than one Terms of Service document. In your test environment, only the document type `adyenForPlatformsAdvanced` is returned regardless of your actual integration. This is since all accounts use the same default configuration. In your live environment, the actual Terms of Service document types are returned. **Response** ```json { "termsOfServiceTypes": [ "adyenForPlatformsAdvanced", "adyenCapital", "adyenAccount" ] } ``` ## 3. Generate the Terms of Service documents To generate the Terms of Service documents, make a POST [/legalEntities/{id}/termsOfService](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of document based on the services and capabilities requested by the user and your platform integration. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-language) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The language used for the Terms of Service document, specified by the two letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Possible value: **en** for English or **fr** for French. Note that French is only available for some integration types in certain countries/regions. Reach out to your Adyen contact for more information. | | [termsOfServiceDocumentFormat](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-termsOfServiceDocumentFormat) | | The requested format for the Terms of Service document. Default value: **JSON**. Possible values: **JSON**, **PDF**, or **TXT**. | **Generate the Terms of Service document** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfService \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -d '{ "type": "adyenForPlatformsAdvanced", "language": "en" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) GetTermsOfServiceDocumentRequest getTermsOfServiceDocumentRequest = new GetTermsOfServiceDocumentRequest() .language("en") .type(GetTermsOfServiceDocumentRequest.TypeEnum.ADYENFORPLATFORMSADVANCED); // Send the request TermsOfServiceApi service = new TermsOfServiceApi(client); GetTermsOfServiceDocumentResponse response = service.getTermsOfServiceDocument("id", getTermsOfServiceDocumentRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $getTermsOfServiceDocumentRequest = new GetTermsOfServiceDocumentRequest(); $getTermsOfServiceDocumentRequest ->setLanguage("en") ->setType("adyenForPlatformsAdvanced"); // Send the request $service = new TermsOfServiceApi($client); $response = $service->getTermsOfServiceDocument('id', $getTermsOfServiceDocumentRequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) GetTermsOfServiceDocumentRequest getTermsOfServiceDocumentRequest = new GetTermsOfServiceDocumentRequest { Language = "en", Type = GetTermsOfServiceDocumentRequest.TypeEnum.AdyenForPlatformsAdvanced }; // Send the request var service = new TermsOfServiceService(client); var response = service.GetTermsOfServiceDocument("id", getTermsOfServiceDocumentRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const getTermsOfServiceDocumentRequest = { type: "adyenForPlatformsAdvanced", language: "en" } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceDocument("id", getTermsOfServiceDocumentRequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) getTermsOfServiceDocumentRequest := legalEntityManagement.GetTermsOfServiceDocumentRequest{ Language: "en", Type: "adyenForPlatformsAdvanced", } // Send the request service := client.LegalEntityManagement() req := service.TermsOfServiceApi.GetTermsOfServiceDocumentInput("id").GetTermsOfServiceDocumentRequest(getTermsOfServiceDocumentRequest) res, httpRes, err := service.TermsOfServiceApi.GetTermsOfServiceDocument(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "adyenForPlatformsAdvanced", "language": "en" } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_document(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'adyenForPlatformsAdvanced', :language => 'en' } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_document(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const getTermsOfServiceDocumentRequest: Types.legalEntityManagement.GetTermsOfServiceDocumentRequest = { language: "en", type: Types.legalEntityManagement.GetTermsOfServiceDocumentRequest.TypeEnum.AdyenForPlatformsAdvanced }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceDocument("id", getTermsOfServiceDocumentRequest); ``` The response returns the following information: | Parameter | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-document) | The generated document in the Base64-encoded format. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-id) | The unique identifier of the organization legal entity. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-language) | The language of the document. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | | [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-termsOfServiceDocumentId) | The unique identifier of the document. | | [termsOfServiceDocumentFormat](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-termsOfServiceDocumentFormat) | The requested format for the Terms of Service document. Default value: **JSON**. Possible values: **JSON**, **PDF**, or **TXT**. | **Response** ```json { "id": "LE00000000000000000000001", "type": "adyenForPlatformsAdvanced", "language": "en", "document": "termsOfServiceDocumentResponse" , "termsOfServiceDocumentId": "abc123", "termsOfServiceDocumentFormat": "JSON" } ``` The response returns the [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-document) and its unique [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId). Your user may need to accept more than one Terms of Service document depending on your integration. In this case, every required [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-document) and [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId) is returned in the response. You will need to present the document to your user in the [next step](#present-document). Use the document ID when you confirm your user has [accepted the Terms of Service](#accept-tos). ## 4. Present the Terms of Service document to your user You need to ask your user to review and accept the Terms of Service document. The process to do this depends on the format of the document. ### Tab: Format: JSON To present the document to your user, you can use the Adyen Document Viewer to render the document in your website. Before passing the document to the Adyen Document Viewer, you need to decode it. ```js const documentViewer = new AdyenDocumentViewer('#test'); const document = JSON.parse(decodeURIComponent(escape(window.atob(termsOfServiceDocumentResponse.document)))); documentViewer.render(document); ``` ### Tab: Format: PDF or TXT In the response from the previous step, take the Base64-encoded data from the [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-document). Decode it and present it to your user in your UI. ## 5. Accept the Terms of Service To confirm that your user has accepted the Terms of Service, make a PATCH [/legalEntities/{id}/termsOfService/termsOfServicedocumentid](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)/termsOfService/\(termsofservicedocumentid\)) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity and the [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId) of the document in the path. For sole proprietorships, include the legal entity ID of the owner in the path. For organizations, include the legal entity ID of the organization in the path. In the body of the request, specify the following: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#request-acceptedBy) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The individual legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the user accepting the Terms of Service. For sole proprietorships, this is the individual legal entity ID of the owner. For organizations, this is the legal entity ID of an authorized signatory for the organization. | | [ipAddress](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#request-ipAddress) | | The IP address of the user. | This request populates the Terms of Service document with the data of the main legal entity. For sole proprietorships, this is the information for the individual legal entity of the owner. For organizations, this means the document contains both the data for the organization and the individual legal entity of the authorized signatory who accepted the document. **Accept Terms of Service document** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfService/abc123 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "acceptedBy" : "LE00000000000000000000002", "ipAddress" : "127.0.0.1" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) AcceptTermsOfServiceRequest acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest() .ipAddress("127.0.0.1") .acceptedBy("LE00000000000000000000002"); // Send the request TermsOfServiceApi service = new TermsOfServiceApi(client); AcceptTermsOfServiceResponse response = service.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest(); $acceptTermsOfServiceRequest ->setIpAddress("127.0.0.1") ->setAcceptedBy("LE00000000000000000000002"); // Send the request $service = new TermsOfServiceApi($client); $response = $service->acceptTermsOfService('id', 'termsofservicedocumentid', $acceptTermsOfServiceRequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AcceptTermsOfServiceRequest acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest { IpAddress = "127.0.0.1", AcceptedBy = "LE00000000000000000000002" }; // Send the request var service = new TermsOfServiceService(client); var response = service.AcceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const acceptTermsOfServiceRequest = { acceptedBy: "LE00000000000000000000002", ipAddress: "127.0.0.1" } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) acceptTermsOfServiceRequest := legalEntityManagement.AcceptTermsOfServiceRequest{ IpAddress: common.PtrString("127.0.0.1"), AcceptedBy: "LE00000000000000000000002", } // Send the request service := client.LegalEntityManagement() req := service.TermsOfServiceApi.AcceptTermsOfServiceInput("id","termsofservicedocumentid").AcceptTermsOfServiceRequest(acceptTermsOfServiceRequest) res, httpRes, err := service.TermsOfServiceApi.AcceptTermsOfService(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "acceptedBy": "LE00000000000000000000002", "ipAddress": "127.0.0.1" } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.accept_terms_of_service(request=json_request, id="id", termsofservicedocumentid="termsofservicedocumentid") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :acceptedBy => 'LE00000000000000000000002', :ipAddress => '127.0.0.1' } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.accept_terms_of_service(request_body, 'id', 'termsofservicedocumentid') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const acceptTermsOfServiceRequest: Types.legalEntityManagement.AcceptTermsOfServiceRequest = { ipAddress: "127.0.0.1", acceptedBy: "LE00000000000000000000002" }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` The response returns the following information. | Parameter | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-acceptedBy) | The individual legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the user who accepted the terms of service. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-id) | The unique identifier of the accepted document. | | [ipAddress](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-ipAddress) | The IP address of the user. Only if provided in the request. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-language) | The language of the document. | | [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-termsOfServiceDocumentId) | The unique identifier of the document. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | **Terms of Service document accepted** ```json { "acceptedBy": "LE00000000000000000000002", "id": "TOSA000AB00000000B2AAAB2BA0AA0", "ipAddress": "127.0.0.1", "language": "en", "termsOfServiceDocumentId": "abc123", "type": "adyenForPlatformsAdvanced" } ``` ## 6. (Optional): Get the Terms of Service information for a legal entity To see the Terms of Service information for a legal entity, make a GET [/legalEntities/{id}/termsOfServiceAcceptanceInfos](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)/termsOfServiceAcceptanceInfos) request with the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. **Get Terms of Service information for a legal entity** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfServiceAcceptanceInfos \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -X GET \ ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Send the request TermsOfServiceApi service = new TermsOfServiceApi(client); GetTermsOfServiceAcceptanceInfosResponse response = service.getTermsOfServiceInformationForLegalEntity("id", null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Send the request $service = new TermsOfServiceApi($client); $response = $service->getTermsOfServiceInformationForLegalEntity('id'); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TermsOfServiceService(client); var response = service.GetTermsOfServiceInformationForLegalEntity("id"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceInformationForLegalEntity("id"); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.LegalEntityManagement() req := service.TermsOfServiceApi.GetTermsOfServiceInformationForLegalEntityInput("id") res, httpRes, err := service.TermsOfServiceApi.GetTermsOfServiceInformationForLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_information_for_legal_entity(id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_information_for_legal_entity('id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceInformationForLegalEntity("id"); ``` The response returns information about the Terms of Service document linked to the legal entity. | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [createdAt](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-createdAt) | The date the document was created. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-id) | The unique identifier of the accepted document. | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-acceptedBy) | The [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the individual who accepted the terms of service. | | [acceptedFor](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-acceptedFor) | The [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | **Response** ```json { "data": [ { "acceptedBy": "LE00000000000000000000002", "acceptedFor": "LE00000000000000000000001", "createdAt": "2022-12-05T13:36:58.212253Z", "id": "TOSA000AB00000000B2AAAB2BA0AA0", "type": "adyenForPlatformsAdvanced" } ] } ``` --- # Source: https://docs.adyen.com/business-accounts/open-banking.md Section: Business accounts Title: Open banking Description: Learn how to integrate with the Adyen Open Banking platform. --- title: "Open banking" description: "Learn how to integrate with the Adyen Open Banking platform." url: "https://docs.adyen.com/business-accounts/open-banking" source_url: "https://docs.adyen.com/business-accounts/open-banking.md" canonical: "https://docs.adyen.com/business-accounts/open-banking" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Open banking Learn how to integrate with the Adyen Open Banking platform. [View source](/business-accounts/open-banking.md) Open banking is a regulatory initiative that was introduced in Europe in 2018 through the Revised Payment Services Directive ([PSD2](https://www.adyen.com/knowledge-hub/psd2). It requires financial institutions, such as Adyen, to provide secure access to their customers' data and allow third-party providers to initiate payments on behalf of the customer with the customer's explicit consent. Adyen provides secure open banking APIs that let third-party service providers interact with Adyen business accounts and get the account holders' consent for those interactions. This documentation is for third-party providers and explains how they can interact with Adyen business accounts to: * Retrieve account information * Initiate payments * Confirm funds This is not [Pay by Bank (Europe)](/payment-methods/pay-by-bank-europe) or [Pay by Bank (US)](/payment-methods/pay-by-bank-us) , which is a specific payment method within Checkout. ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Limitations** | This documentation is for the EU region only. For UK documentation, see the [Open Banking documentation](https://openbankinguk.github.io/read-write-api-site3/v4.0/profiles/read-write-data-api-profile.html). Also, see a list of [supported countries and regions](#supported-countries-and-regions). | | **Setup steps** | If you are a third-party service provider seeking access to Adyen's open banking interfaces, you must:- Be licensed by a national regulatory authority. - Have a Qualified Website Authentication Certificate (QWAC). This can be obtained from [Qualified Trusted Service Providers](https://webgate.ec.europa.eu/tl-browser/#/) (QTSP). - Complete the [Adyen onboarding steps](#onboard-with-adyen). | ## Adyen open banking APIs Adyen's open banking interface provides a secure and reliable way for third-party providers to access Adyen's APIs and interact with the data of Adyen business accounts. This involves the use of APIs that allow third-party providers to access and use financial data from financial institutions. Typically, the Adyen open banking flow has three participants: * **Adyen business account holder**: This is an account holder that has a business account with Adyen, often referred to as the *payment service user* in the open banking industry. * **A third-party provider**: * An **account information service provider (AISP)**: a third-party provider that requests information about Adyen business accounts. * A **payment initiation service provider (PISP)**: a third-party provider that initiates payments from Adyen business accounts. * A **payment instrument issuer service provider (PIISP)**: a third-party provider that requests information about the available funds in Adyen business accounts. * **Account servicing payment service provider**: Adyen, as the financial institution that manages the business accounts of the account holders. Adyen provides third-party providers with the following regulatory APIs: * **Open Banking API for the EU**: Follows the [NextGenPSD2](https://www.berlin-group.org/nextgenpsd2-downloads) standard created by [The Berlin Group](https://www.berlin-group.org). * **Open Banking API for the UK**: Follows the [Open Banking API specifications](https://standards.openbanking.org.uk/api-specifications) created by [Open Banking Limited](https://www.openbanking.org.uk/about-us). ### Base URL and API structure The table below describes the structure of each API request URL. | Description | Value | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Test base URL** | `https://openbanking-psd2-test.adyen.com` | | **Live base live URL** | `https://openbanking-psd2-live.adyen.com` | | **Region identifier** | * `obeu` for EU APIs. * `obuk` for UK APIs. | | **Third-party providers** | - `/asip` for account information service providers for EU APIs. - `/pisp` for payment initiation service providers. - `/piis` for payment instrument issuer service providers. | | **API version** | The version of the API. Currently, `/v1` is supported. | | **Endpoint** | The specific resource you are accessing (for example, `/accounts`). | **Example URL**\ `https://openbanking-psd2-live.adyen.com/obeu/pisp/v1/accounts` ## How it works The typical open banking flow with Adyen is as follows: 1. An account holder requests a service from a third-party provider. The third-party provider can only ask for those scopes agreed to by the account holder. 2. The third-party provider requests the account holder to: 1. Authenticate themselves with Adyen. 2. Provide consent to Adyen to allow the third-party provider to perform the requested service. 3. If the previous step is successful, Adyen allows the third-party provider to use the open banking API. 4. Adyen sends the requested information through the open banking API. ## Onboard with Adyen To integrate with the Adyen's open banking interface, third-party providers need to register and obtain the necessary credentials to access the APIs. They also need to ensure that their systems comply with the relevant security and data protection requirements. Third-party service provider must be licensed by a national regulatory authority and have a Qualified Website Authentication Certificate (QWAC). This can be obtained from [Qualified Trusted Service Providers](https://webgate.ec.europa.eu/tl-browser/#/) (QTSP). 1. To onboard with Adyen as a third-party provider, gather the required information: * **QWAC certificate**: PEM-formatted QWAC certificate file. Add the certificate as an attachment. * **Redirect URL**: This URL used to redirect successful authentications with the authorization code. * **Third-party provider website**: Your website URL. * **Scopes**: The scopes to be enabled for your OAuth client. The available scopes are: * **AISP** * **PISP** * **PIISP** 2. Send an email to . Adyen reviews your information and sends you the **client ID** and **client secret** used in the [OAuth flow](/business-accounts/oauth-flow) to get access token. ## Supported countries and regions The table shows the supported countries and regions, and availability. This documentation is for the EU region only. For UK documentation, see the [Open Banking documentation](https://openbankinguk.github.io/read-write-api-site3/v4.0/profiles/read-write-data-api-profile.html). | Countries/regions | Account information | Payment | Funds check | | ----------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | EU | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | UK | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Next steps [required](/business-accounts/oauth-flow) [Authentication](/business-accounts/oauth-flow) [Implement OAuth 2.0 to enable secure communication with Adyen.](/business-accounts/oauth-flow) [required](/business-accounts/consent) [Consent interface](/business-accounts/consent) [Learn how to manage user consents with our dedicated endpoints.](/business-accounts/consent) [AISP interface](/business-accounts/aisp) [Learn how to consume our dedicated AISP endpoints.](/business-accounts/aisp) [PISP interface](/business-accounts/pisp) [Learn how to consume our dedicated PISP endpoints.](/business-accounts/pisp) [PIISP interface](/business-accounts/piisp) [Learn how to consume our dedicated PIISP endpoints.](/business-accounts/piisp) --- # Source: https://docs.adyen.com/business-accounts/piisp.md Section: Business accounts Title: Confirm funds availability Description: Learn how to consume our dedicated PIISP endpoints. --- title: "Confirm funds availability" description: "Learn how to consume our dedicated PIISP endpoints." url: "https://docs.adyen.com/business-accounts/piisp" source_url: "https://docs.adyen.com/business-accounts/piisp.md" canonical: "https://docs.adyen.com/business-accounts/piisp" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Confirm funds availability Learn how to consume our dedicated PIISP endpoints. [View source](/business-accounts/piisp.md) As part of the open banking framework for Payment Initiation Service Providers (PIISPs), Adyen provides an endpoint to confirm available funds on behalf of account holders who have given their consent. This page explains how you, as a third-party PIISP, use the `/funds-confirmations` endpoint to: * [Confirm funds](#confirm-funds) ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Setup steps** | Before you begin, you must:- Complete the [Adyen onboarding steps](/business-accounts/open-banking#onboard-with-adyen). - Have your [access token](/business-accounts/oauth-flow#get-an-access-token) for the Adyen business account. | ## Confirm funds To ensure that the account holder has sufficient funds to cover the payment amount: 1. Make a POST `/funds-confirmations` request with the following parameters in the request body. The request header includes, for example, an IPv4 address like 82.199.87.148, or an IPv6 address like 2001:db8:1:1:1:1:1:1. | Parameter | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `instructedAmount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency and the amount of the payment. | | `account` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The account number for which the funds availability needs to be checked. | The following request checks if the IBAN has **EUR 10.50** available. **Confirm available funds** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/piis/v1/funds-confirmations' \ --header 'X-Request-ID: {your-request-id}' \ --header 'IPv4: 82.199.87.148' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {access_token}' \ --data '{ "instructedAmount": { "currency": "EUR", "amount": "10.50" }, "account": { "iban": "NL91ABNA0417164300" } }' ``` 2. The response contains `fundsAvailable` that indicates whether the instructed amount is available. A value of `false` indicates insufficient funds for the specified amount. **Response** ```json { "fundsAvailable": true } ``` ## See also * [Get account holder information](/business-accounts/aisp) * [Initiate payments](/business-accounts/pisp) --- # Source: https://docs.adyen.com/business-accounts/pisp.md Section: Business accounts Title: Initiate payments on behalf of account holders Description: Learn how to consume our dedicated PISP endpoints. --- title: "Initiate payments on behalf of account holders" description: "Learn how to consume our dedicated PISP endpoints." url: "https://docs.adyen.com/business-accounts/pisp" source_url: "https://docs.adyen.com/business-accounts/pisp.md" canonical: "https://docs.adyen.com/business-accounts/pisp" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Initiate payments on behalf of account holders Learn how to consume our dedicated PISP endpoints. [View source](/business-accounts/pisp.md) As part of the open banking framework for Payment Initiation Service Providers (PISPs), Adyen provides endpoints to initiate payment transactions on behalf of account holders who have given their consent. This page explains how you, as a third-party PISP, use the `/payments` endpoint to: * [Initiate a payment](#initiate-a-payment) * [Get the status of a payment](#payment-status) * [Get the status of a payment authorization](#authorization-status) ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Not applicable; this documentation is intended for third-party providers. | | **Setup steps** | Before you begin, you must:- Complete the [Adyen onboarding steps](/business-accounts/open-banking#onboard-with-adyen). - Have your [access token](/business-accounts/oauth-flow#get-an-access-token) for the Adyen business account. | ## Initiate a payment To initiate a single payment on behalf of your account holder: 1. Make a POST `/payments/target-2-payments` request with the following parameters in the request body. The request header includes, for example, an IPv4 address like 19.68.26.143, or an IPv6 address like 2001:db8:1:1:1:1:1:1. | Parameter | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `instructedAmount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency and the amount of the payment. | | `creditorAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The account number of the creditor—the person or entity who will receive the payment. | | `debtorAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The account number of the debtor. | | `creditorName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the creditor. | | `creditorAddress` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The address of the creditor. | Here is an example of a request to initiate a payment of **EUR 0.50** to Railway Company. **Initiate a single payment** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/pisp/v1/payments/target-2-payments' \ --header 'X-Request-ID: {your-request-id}' \ --header 'IPv4: 19.68.26.143' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {access_token}' \ --data '{ "instructedAmount": { "currency": "EUR", "amount": "0.50" }, "creditorAccount": { "iban": "NL57INGB4654188101" }, "debtorAccount": { "iban": "NL91ABNA0417164300" }, "creditorName": "Railway Company", "creditorAddress": { "streetName": "Railstraat", "buildingNumber": "1", "townName": "Amsterdam", "postCode": "2023 AB", "country": "NL" } }' ``` 2. The response contains the details of the initiated payment, including the `transactionStatus` and the `paymentId`. The response contains the following fields: | Parameter | Description | | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | `transactionStatus` | Current status of the payment. Possible values:- **ACCP**: Accepted customer profile. - **ACFC**: Accepted funds checked. - **ACCC**: Accepted settlement completed on the creditor's account. - **ACSC**: Accepted settlement completed on the debtor's account. - **ACSP**: Accepted settlement in process. - **ACTC**: Accepted technical validation. - **ACWC**: Accepted with change. - **ACWP**: Accepted without posting. - **CANC**: Payment initiation has been cancelled before execution. - **RCVD**: Payment initiation has been received. - **RJCT**: Payment initiation or individual transaction included in the payment initiation has been rejected. - **PDNG**: Payment initiation or individual transaction included in the payment initiation is pending. - **PART**: Partially accepted. - **PATC**: Partially accepted technical. | | | `paymentId` | A list of characters that represents the ID of a specific payment. | | **Response** ```json { "transactionStatus": "PDNG", "paymentId": "1WPF9J5ZKOIZH8MG", "_links": { "self": { "href": "/payments/target-2-payments/1WPF9J5ZKOIZH8MG" }, "status": { "href": "/payments/target-2-payments/1WPF9J5ZKOIZH8MG/status" }, "scaStatus": { "href": "/payments/target-2-payments/1WPF9J5ZKOIZH8MG/authorisations/OBAU4222Z223222P5J6FPG9DG4654T" } } } ``` ## Get payment status To get the status of the payment: 1. Make a GET `/payments/target-2-payments/{paymentId}` request. Use this endpoint to check if the payment has been confirmed. The `paymentId` is found in the response of the [Initiate a payment](#initiate-a-payment) step. Keep polling the endpoint for status updates (recommended every 5 seconds). **Get payment status** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/pisp/v1/payments/target-2-payments/{paymentId}' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Bearer {access_token}' ``` 2. The response contains the `transactionStatus` which describes the current state of the payment. The response may look like this: **Response** ```json { "transactionStatus": "RCVD", "paymentId": "1WPF9J5ZKOIZH8MG", "instructedAmount": { "currency": "EUR", "amount": "-0.50" } } ``` ## Get authorization status To get information about the payment authorization details and determine where your account holder is in the in authorization flow to initiate payments. 1. Make a GET `/payments/target-2-payments/{paymentId}/authorisations/{authorizationId}` request, where `paymentId` represents a unique identifier for a payment transaction and `authorizationId` is a unique identifier for a specific payment authorization. **Get authorization status** ```bash curl 'https://openbanking-psd2-test.adyen.com/obeu/pisp/v1/payments/target-2-payments/1WPF9J5Z16P8M825/authorisations/OBAU4222Z223222P5HWJDLHD766H93' \ --header 'X-Request-ID: {your-request-id}' \ --header 'Authorization: Basic {access_token}' ``` 2. The response contains the authorization status. See the `scaStatus` for all possible values. | Parameter | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scaStatus` | Status of authorization. Possible values:- **scaMethodSelected**: The account holder/third-party provider has selected the related SCA routine. - **started**: The addressed SCA routine has been started. - **finalised**: The SCA routine has been finalized successfully (including a potential confirmation command). This is a final status of the authorization resource. - **failed**: The SCA routine failed. This is a final status of the authorization resource. | **Response** ```json { "scaStatus": "finalised" } ``` ## See also * [Get account holder information](/business-accounts/aisp) * [Confirm funds](/business-accounts/piisp) --- # Source: https://docs.adyen.com/business-accounts/receive-funds.md Section: Business accounts Title: Receive funds from third parties Description: Learn how to receive funds from third parties using an Adyen business account. --- title: "Receive funds from third parties" description: "Learn how to receive funds from third parties using an Adyen business account." url: "https://docs.adyen.com/business-accounts/receive-funds" source_url: "https://docs.adyen.com/business-accounts/receive-funds.md" canonical: "https://docs.adyen.com/business-accounts/receive-funds" last_modified: "2022-02-28T17:18:00+01:00" language: "en" --- # Receive funds from third parties Learn how to receive funds from third parties using an Adyen business account. [View source](/business-accounts/receive-funds.md) With an Adyen business account, your users can: * Receive business-related payments from third parties. These funds are directly credited in their business account and made available in their balance accounts. * Make business-related payments by accepting incoming direct debit requests from third parties, for example, to pay for subscriptions. Their business accounts are debited. ## Requirements Ensure that your users have the **receiveFromThirdParty** capability allowed and enabled. ## Supported currencies, locations, and priorities You can specify how fast you want the funds to arrive to your user's account by setting a priority in the request or schedule. A with a higher priority incurs higher fees. You can set the following priorities for bank transfers: * **Regular**: Recommended for standard, low-value transactions to a recipient in the same region. * **Instant**: Transfers funds instantly within the United States, Australia, the United Kingdom, and the [Single Euro Payments Area (SEPA)](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en). * **Fast**: Processes faster than Regular and incurs higher fees. Suitable for high-priority, low-value transfers in the same region. * **Wire**: The fastest option, with the highest fees. Recommended for high-priority, high-value transfers in the same region. * **Cross-border**: Recommended for high-value transfers to recipients in other regions or countries. When using Cross-border priority, delays and additional fees may occur due to intermediary banks. As a result, the beneficiary may receive a lower amount than the instructed value. * **Internal**: Transfers between Adyen-issued accounts, such as balance accounts or business accounts. The following tables show the priorities available for each currency and location. ### Tab: Receive USD | Priority of incoming transfer | Available for US business accounts | Available for EU business account | Available for UK business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Instant | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Fast | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Wire | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Cross border | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Tab: Receive EUR | Priority of incoming transfer | Available for USD business accounts | Available for EUR business account | Available for GBP business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Instant | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Fast | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Wire | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Cross border | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Tab: Receive GBP | Priority of incoming transfer | Available for USD business accounts | Available for EUR business accounts | Available for GBP business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Instant | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Fast | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Wire | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Cross border | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Account information for third parties The following tabs show the account information that you must share with third parties so you can receive funds from them. ### Tab: Account in the US | Items | References | | --------------------------------------------------------------------------------- | ------------ | | Account number format (sample) | `1322347452` | | Routing number (Adyen-specific code that is used to move funds locally in the US) | `121045274` | | Adyen US BIC (BIC is used for SWIFT/cross-border transactions) | `ADYBUS62` | ### Tab: Account in the Netherlands | Items | References | | -------------------------------------------------------------- | ------------------------ | | IBAN format (sample) | `NL12 ADYB 0123 4567 89` | | Adyen US BIC (BIC is used for SWIFT/cross-border transactions) | `ADYBNL2A` | ### Tab: Account in the UK | Items | References | | ------------------------------------------------------------------------------- | ----------------------------- | | Account number format (sample) | `20004111` | | IBAN format (sample) | `GB37 ADYB 0429 5720 0041 11` | | UK sort code (Adyen-specific code that is used to move funds locally in the UK) | `121045274` | | Adyen UK BIC (BIC is used for SWIFT/cross-border transactions) | `ADYBGB22` | ## Receiving funds An external party (sender) can send funds to your user's Adyen business account. They must use the business account number which was returned in the API [response](/business-accounts/create-business-accounts#create-business-account-response) when you created the business account. Your users must have the **receiveFromThirdParty** capability allowed and enabled before they can receive funds on their Adyen business account from external parties. When a business account receives funds from an external party, Adyen informs your server through [incoming bank transfer webhooks](/business-accounts/third-party-transfer-webhooks#receiving-funds). ## Receiving direct debit requests An external party can collect payments from your user's Adyen business account through direct debit. We currently support external direct debits in the Single Euro Payments Area (SEPA). SEPA is the standardized infrastructure for bank-to-bank transactions within the European Union. If your user wants to accept incoming SEPA direct debit requests on their Adyen business account, you need to: * Inform your user of their rights: * They have eight weeks to dispute a SEPA direct debit transaction, without providing a reason. * They have thirteen months to dispute an unauthorised or incorrect SEPA direct debit transaction when they provide evidence. * Ask your Adyen contact to enable receiving SEPA direct debits for your user. ## Next steps Keep track of Adyen business account transactions using webhooks or by making an API request. [required](/business-accounts/third-party-transfer-webhooks) [Get updates through webhooks](/business-accounts/third-party-transfer-webhooks) [Find out which webhooks Adyen sends for incoming and outgoing transactions.](/business-accounts/third-party-transfer-webhooks) [Use an API to get updates](/business-accounts/transactions) [Send API requests to query bank transactions.](/business-accounts/transactions) --- # Source: https://docs.adyen.com/business-accounts/register-sca-devices.md Section: Business accounts Title: Register a device for SCA Description: Learn how to use our Authentication SDK to register an iOS or Android device for SCA purposes. --- title: "Register a device for SCA" description: "Learn how to use our Authentication SDK to register an iOS or Android device for SCA purposes." url: "https://docs.adyen.com/business-accounts/register-sca-devices" source_url: "https://docs.adyen.com/business-accounts/register-sca-devices.md" canonical: "https://docs.adyen.com/business-accounts/register-sca-devices" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # Register a device for SCA Learn how to use our Authentication SDK to register an iOS or Android device for SCA purposes. [View source](/business-accounts/register-sca-devices.md) To enable Strong Customer Authentication (SCA) for your users, you must register their device as an SCA device. The registration associates your user's device with their business account. You can register devices for SCA using Adyen's Authentication SDK. To do so: 1. [Check SCA eligibility](#check-sca). 2. [Initiate the device registration](#initiate-registration) from your server. 3. [Register the device](#register-device). 4. [Finalize the registration](#finalize-registration) from your server. The following sections explain how to perform all the steps to register a user's device for SCA. ## Requirements * Make sure that the operating system or web browser on your user's device supports SCA. * Make sure that you have [installed the Authentication SDK](/business-accounts/install-auth-sdk). * Make sure that your [API credential](/business-accounts/manage-access#manage-api-credentials) has the following role: * **Bank SCA Webservice Role** ## Check SCA eligibility This functionality requires additional configuration from Adyen. To enable it, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Tab: Android (Kotlin) To check if the Android device is eligible for SCA: 1. Initiate the `AdyenAuthentication` class in your Activity or Fragment. **Initiate authentication** ```kotlin private lateinit var adyenAuthentication: AdyenAuthentication override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) adyenAuthentication = AdyenAuthentication(this) } ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```kotlin lifecycleScope.launch { val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability() if (availabilityResult is AvailabilityResult.Available) { availabilityResult.sdkOutput } } ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: iOS (Swift) To check if the iOS device is eligible for SCA: 1. Initialize the `AuthenticationService` class. **Initialize authentication service** ```swift let configuration = AuthenticationService.Configuration( localizedRegistrationReason: registrationReason, localizedAuthenticationReason: authenticationReason, appleTeamIdendtifier: appleTeamIdentifier ) let authenticationService = AuthenticationService(configuration: configuration) ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```swift let sdkOutput = try authenticationService.checkSupport() /// send the sdkOutput to your backend ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: Web (JavaScript) To check if the web browser on your web-enabled device is eligible for SCA: 1. Import the node package in your application. `RelyingPartyName` is the name the user will be presented with when creating or validating a `WebAuthn` operation. We recommend that the value of the `RelyingPartyName` be the merchant name or the URL domain. **Import web sdk and initiate authentication** ```javascript import ScaWebauthn from '@adyen/bpscaweb'; const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'merchant', }); const sdkOutput = await scaWebauthn.checkAvailability().catch((error) => /* SCA_UNAVAILABLE error*/); ``` If the user's browser supports SCA, the function returns `sdkOutput` to exchange in requests to the server. If SCA is not supported, the method throws an `SCA_UNAVAILABLE` error. 2. Pass the `sdkOutput` to your server. You will use the `sdkOutput` when [initiating the registration](#initiate-registration). ## Initiate device registration Registering the device is a one-off procedure for each device. If your user has multiple devices, you need to register each of their devices separately. After a device is registered, you can associate more payment instruments with it. To learn how to associate multiple payment instruments with a registered device, go to [Manage registered devices](/business-accounts/manage-sca-devices/). To start the device registration, make a POST [/registeredDevices](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices) request from your server. In the request, specify the following: | Request parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices#request-paymentInstrumentId) | yes | The unique identifier of the business account you want to register the device for. | | [name](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices#request-name) | no | The name of the SCA device that you are registering. You can use it to help your users identify the device. If you do not specify a `name`, Adyen automatically generates one. | | [strongCustomerAuthentication.sdkOutput](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices#request-strongCustomerAuthentication-sdkOutput) | yes | Base64-encoded blob of data created in the [previous step](#check-sca). | **Initiate device registration** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "paymentInstrumentId": "PI00000000000000000000001", "strongCustomerAuthentication" : { "sdkOutput": "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..." } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) DelegatedAuthenticationData delegatedAuthenticationData = new DelegatedAuthenticationData() .sdkOutput("eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..."); RegisterSCARequest registerSCARequest = new RegisterSCARequest() .strongCustomerAuthentication(delegatedAuthenticationData) .paymentInstrumentId("PI00000000000000000000001"); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); RegisterSCAResponse response = service.initiateRegistrationOfScaDevice(registerSCARequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $delegatedAuthenticationData = new DelegatedAuthenticationData(); $delegatedAuthenticationData ->setSdkOutput("eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..."); $registerSCARequest = new RegisterSCARequest(); $registerSCARequest ->setStrongCustomerAuthentication($delegatedAuthenticationData) ->setPaymentInstrumentId("PI00000000000000000000001"); // Send the request $service = new ManageScaDevicesApi($client); $response = $service->initiateRegistrationOfScaDevice($registerSCARequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) DelegatedAuthenticationData delegatedAuthenticationData = new DelegatedAuthenticationData { SdkOutput = "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..." }; RegisterSCARequest registerSCARequest = new RegisterSCARequest { StrongCustomerAuthentication = delegatedAuthenticationData, PaymentInstrumentId = "PI00000000000000000000001" }; // Send the request var service = new ManageScaDevicesService(client); var response = service.InitiateRegistrationOfScaDevice(registerSCARequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const registerSCARequest = { paymentInstrumentId: "PI00000000000000000000001", strongCustomerAuthentication: { sdkOutput: "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..." } } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateRegistrationOfScaDevice(registerSCARequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) delegatedAuthenticationData := balancePlatform.DelegatedAuthenticationData{ SdkOutput: "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV...", } registerSCARequest := balancePlatform.RegisterSCARequest{ StrongCustomerAuthentication: delegatedAuthenticationData, PaymentInstrumentId: "PI00000000000000000000001", } // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.InitiateRegistrationOfScaDeviceInput().RegisterSCARequest(registerSCARequest) res, httpRes, err := service.ManageScaDevicesApi.InitiateRegistrationOfScaDevice(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "paymentInstrumentId": "PI00000000000000000000001", "strongCustomerAuthentication": { "sdkOutput": "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..." } } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_registration_of_sca_device(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :paymentInstrumentId => 'PI00000000000000000000001', :strongCustomerAuthentication => { :sdkOutput => 'eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV...' } } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.initiate_registration_of_sca_device(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const delegatedAuthenticationData: Types.balancePlatform.DelegatedAuthenticationData = { sdkOutput: "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..." }; const registerSCARequest: Types.balancePlatform.RegisterSCARequest = { strongCustomerAuthentication: delegatedAuthenticationData, paymentInstrumentId: "PI00000000000000000000001" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.initiateRegistrationOfScaDevice(registerSCARequest); ``` The response returns: * [sdkInput](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices#responses-200-sdkInput): pass the value to the SDK when [registering the device](#register-device). * [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/registeredDevices#responses-200-id): the device ID needed when [finalizing the registration](#finalize-registration). This ID begins either with `BSDR` or `RD`. We suggest that you create and store a mapping between the registered device `id` and the human-readable account holder name. For example, **BSDR00000000000000000000001** is "Cardholder's iPhone". You can use this pair later to show the details, for example, when [deregistering the device](/business-accounts/manage-sca-devices#deregister-device) if the user doesn't specify a device name during registration. **Initiate device registration response** ```json { "id": "BSDR00000000000000000000001", "paymentInstrumentId": "PI00000000000000000000001", "sdkInput": "eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNlQzFvVjBGSGRVaDNaVXc1UVE9PSJ9", "success": true } ``` ## Register the device To register the device with the Authentication SDK: 1. Authenticate the user by performing [two-factor authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication) (2FA). 2. Trigger the SDK to start the device registration and pass `sdkInput` from [step 2](#initiate-registration). ### Tab: Android (Kotlin) **Register device with SCA SDK** ```kotlin lifecycleScope.launch { val registrationResult: AuthenticationResult = adyenAuthentication.register("sdkInput") when (registrationResult) { is AuthenticationResult.RegistrationSuccessful -> { registrationResult.sdkOutput } is AuthenticationResult.Canceled -> { // cardholder canceled the flow } is AuthenticationResult.Error -> { // Unexpected error registrationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error registrationResult.authenticationError } } } ``` After the successful registration, the SDK generates a Base64-encoded `sdkOutput` data blob. ### Tab: iOS (Swift) **Register device with SCA SDK** ```swift let sdkOutput = try await authenticationService.register(withBase64URLString: sdkInput) /// send the sdkOutput to the backend ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) **Register device with SCA SDK** ```javascript const sdkOutput = await scaWebauthn.register(sdkInput); ``` After the successful registration, the SDK generates a Base64-encoded `sdkOutput` data blob. 3. Pass `sdkOutput` to your server. ## Finalize registration To finalize the device registration: 1. Make a PATCH [/registeredDevices/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(id\)) request from your server. Specify the following parameters: | Parameter | Parameter type | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(id\)#path-id) | Path | The unique identifier of the SCA device. You obtain this `id` after you [initiate the device registration](#initiate-registration). | | [paymentInstrumentId](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(id\)#request-paymentInstrumentId) | Body | The unique identifier of the business account you want to register the device for. | | [strongCustomerAuthentication.sdkOutput](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/registeredDevices/\(id\)#request-strongCustomerAuthentication-sdkOutput) | Body | Base64-encoded blob of data created in the previous step. | **Finalize device registration** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/{id} \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "paymentInstrumentId": "PI00000000000000000000001", "strongCustomerAuthentication" : { "sdkOutput": "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..." } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) DelegatedAuthenticationData delegatedAuthenticationData = new DelegatedAuthenticationData() .sdkOutput("eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..."); RegisterSCARequest registerSCARequest = new RegisterSCARequest() .strongCustomerAuthentication(delegatedAuthenticationData) .paymentInstrumentId("PI00000000000000000000001"); // Send the request ManageScaDevicesApi service = new ManageScaDevicesApi(client); RegisterSCAFinalResponse response = service.completeRegistrationOfScaDevice("id", registerSCARequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $delegatedAuthenticationData = new DelegatedAuthenticationData(); $delegatedAuthenticationData ->setSdkOutput("eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..."); $registerSCARequest = new RegisterSCARequest(); $registerSCARequest ->setStrongCustomerAuthentication($delegatedAuthenticationData) ->setPaymentInstrumentId("PI00000000000000000000001"); // Send the request $service = new ManageScaDevicesApi($client); $response = $service->completeRegistrationOfScaDevice('id', $registerSCARequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) DelegatedAuthenticationData delegatedAuthenticationData = new DelegatedAuthenticationData { SdkOutput = "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..." }; RegisterSCARequest registerSCARequest = new RegisterSCARequest { StrongCustomerAuthentication = delegatedAuthenticationData, PaymentInstrumentId = "PI00000000000000000000001" }; // Send the request var service = new ManageScaDevicesService(client); var response = service.CompleteRegistrationOfScaDevice("id", registerSCARequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const registerSCARequest = { paymentInstrumentId: "PI00000000000000000000001", strongCustomerAuthentication: { sdkOutput: "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..." } } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.completeRegistrationOfScaDevice("id", registerSCARequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) delegatedAuthenticationData := balancePlatform.DelegatedAuthenticationData{ SdkOutput: "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF...", } registerSCARequest := balancePlatform.RegisterSCARequest{ StrongCustomerAuthentication: delegatedAuthenticationData, PaymentInstrumentId: "PI00000000000000000000001", } // Send the request service := client.BalancePlatform() req := service.ManageScaDevicesApi.CompleteRegistrationOfScaDeviceInput("id").RegisterSCARequest(registerSCARequest) res, httpRes, err := service.ManageScaDevicesApi.CompleteRegistrationOfScaDevice(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "paymentInstrumentId": "PI00000000000000000000001", "strongCustomerAuthentication": { "sdkOutput": "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..." } } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.complete_registration_of_sca_device(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :paymentInstrumentId => 'PI00000000000000000000001', :strongCustomerAuthentication => { :sdkOutput => 'eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF...' } } # Send the request result = adyen.balancePlatform.manage_sca_devices_api.complete_registration_of_sca_device(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const delegatedAuthenticationData: Types.balancePlatform.DelegatedAuthenticationData = { sdkOutput: "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..." }; const registerSCARequest: Types.balancePlatform.RegisterSCARequest = { strongCustomerAuthentication: delegatedAuthenticationData, paymentInstrumentId: "PI00000000000000000000001" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.ManageScaDevicesApi.completeRegistrationOfScaDevice("id", registerSCARequest); ``` 2. Verify that the response contains `success` **true**. The registration is now complete and the device ID is connected to the payment instrument. An element for the device ID is added to the `data` array of GET [/registeredDevices](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/registeredDevices). The user can start authenticating themselves for future operations related to the payment instrument ID used during registration. You cannot register a device more than once. However, now that the device is registered, you can connect more payment instruments to the device [using the device association API](/business-accounts/manage-sca-devices/#associate-business-accounts-to-a-registered-device). ## Next steps Authenticate your users before authorizing operations. [required](/business-accounts/manage-sca-devices) [Manage devices](/business-accounts/manage-sca-devices) [Use our APIs to get registration details, connect payment instruments to devices, and delete registrations.](/business-accounts/manage-sca-devices) [required](/business-accounts/sca-for-funds-transfers) [Authenticate users when making a transfer](/business-accounts/sca-for-funds-transfers) [Use our Authentication SDK to authenticate your users before they transfer funds.](/business-accounts/sca-for-funds-transfers) [required](/business-accounts/sca-for-transaction-history) [Authenticate users when getting their transaction history](/business-accounts/sca-for-transaction-history) [Use our Authentication SDK to authenticate your users before showing them their transaction history.](/business-accounts/sca-for-transaction-history) --- # Source: https://docs.adyen.com/business-accounts/sca-for-funds-transfers.md Section: Business accounts Title: SCA for funds transfers Description: Learn how to use our Authentication SDK to authenticate your users when they make transfers. --- title: "SCA for funds transfers" description: "Learn how to use our Authentication SDK to authenticate your users when they make transfers." url: "https://docs.adyen.com/business-accounts/sca-for-funds-transfers" source_url: "https://docs.adyen.com/business-accounts/sca-for-funds-transfers.md" canonical: "https://docs.adyen.com/business-accounts/sca-for-funds-transfers" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # SCA for funds transfers Learn how to use our Authentication SDK to authenticate your users when they make transfers. [View source](/business-accounts/sca-for-funds-transfers.md) Each time a user in the European Economic Area (EEA) wants to transfer funds, you must authenticate them using SCA. To do so: 1. [Check SCA eligibility](#initiate-authentication). 2. [Initiate the transfer](#initiate-transfer) using the `sdkOutput` that you got when you checked the device for SCA eligibility. 3. [Authenticate your user](#authenticate-user) with the Authentication SDK. 4. [Finalize the transfer](#finalize-transfer) using the `sdkOutput` from the authentication step. ## Requirements * Make sure that you have [installed the Authentication SDK](/business-accounts/install-auth-sdk).\ Make sure that you have [registered a device](/business-accounts/register-sca-devices) for your user. * Make sure that your [API credential](/business-accounts/manage-access#manage-api-credentials) has the following role: * **TransferService Webservice Initiate role** ## Check SCA eligibility Before initiating a transfer, you must check for SCA eligibility and initiate the process to authenticate your users. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript. ### Tab: Android (Kotlin) To check if the Android device is eligible for SCA: 1. Initiate the `AdyenAuthentication` class in your Activity or Fragment. **Initiate authentication** ```kotlin private lateinit var adyenAuthentication: AdyenAuthentication override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) adyenAuthentication = AdyenAuthentication(this) } ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```kotlin lifecycleScope.launch { val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability() if (availabilityResult is AvailabilityResult.Available) { availabilityResult.sdkOutput } } ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: iOS (Swift) To check if the iOS device is eligible for SCA: 1. Initialize the `AuthenticationService` class. **Initialize authentication service** ```swift let configuration = AuthenticationService.Configuration( localizedRegistrationReason: registrationReason, localizedAuthenticationReason: authenticationReason, appleTeamIdendtifier: appleTeamIdentifier ) let authenticationService = AuthenticationService(configuration: configuration) ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```swift let sdkOutput = try authenticationService.checkSupport() /// send the sdkOutput to your backend ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: Web (JavaScript) To check if the web browser on your web-enabled device is eligible for SCA: 1. Import the node package in your application. `RelyingPartyName` is the name the user will be presented with when creating or validating a `WebAuthn` operation. We recommend that the value of the `RelyingPartyName` be the merchant name or the URL domain. **Import web sdk and initiate authentication** ```javascript import ScaWebauthn from '@adyen/bpscaweb'; const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'merchant', }); const sdkOutput = await scaWebauthn.checkAvailability().catch((error) => /* SCA_UNAVAILABLE error*/); ``` If the user's browser supports SCA, the function returns `sdkOutput` to exchange in requests to the server. If SCA is not supported, the method throws an `SCA_UNAVAILABLE` error. 2. Pass the `sdkOutput` to your server. You will use the `sdkOutput` when [initiating the transfer](#initiate-transfer). ## Initiate transfer The steps to initiate a transfer depend on whether you want to: * Authenticate the user when initiating a transfer request. * Authenticate the reviewer when approving a transfer request. Because a reviewer can approve multiple transfers at the same time, performing SCA during approval allows you to satisfy the authentication requirements for multiple transfers with a single SCA process. The following tabs explain both methods for initiating a transfer that requires SCA. ### Tab: Authenticate during initiation To initiate a funds transfer for your user and trigger SCA, do the following: 1. Make a POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request, specifying the following parameters: | Parameter | Type | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **Transfer**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [initiate authentication](#initiate-authentication). | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-amount) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The amount of the transfer. | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-balanceAccountId) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the source balance account. | | [category](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-category) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **bank**. | | [counterparty.bankAccount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains information about the target bank account. | | [description](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-description) | Body | | A human-readable description for the transfer. | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-reference) | Body | | A reference of the transfer, only used internally within your balance platform. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-referenceForBeneficiary) | Body | | A reference that is sent to the recipient. | **Initiate funds transfer and trigger SCA** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="Transfer" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification() .fullName("A. Klaassen"); IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL91ABNA0417164300") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(ibanAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(1000L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") .amount(amount) .referenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") .description("YOUR_DESCRIPTION_FOR_THE_TRANSFER") .counterparty(counterpartyInfoV3) .category(TransferInfo.CategoryEnum.BANK); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL91ABNA0417164300") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") ->setAmount($amount) ->setReferenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") ->setDescription("YOUR_DESCRIPTION_FOR_THE_TRANSFER") ->setCounterparty($counterpartyInfoV3) ->setCategory("bank"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification { FullName = "A. Klaassen" }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL91ABNA0417164300", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", Amount = amount, ReferenceForBeneficiary = "YOUR_REFERENCE_SENT_TO_BENEFICIARY", Description = "YOUR_DESCRIPTION_FOR_THE_TRANSFER", Counterparty = counterpartyInfoV3, Category = TransferInfo.CategoryEnum.Bank }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const transferInfo = { amount: { currency: "EUR", value: 1000 }, balanceAccountId: "BA00000000000000000000001", category: "bank", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen" }, accountIdentification: { type: "iban", iban: "NL91ABNA0417164300" } } } } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) partyIdentification3 := transfers.PartyIdentification{ FullName: common.PtrString("A. Klaassen"), } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL91ABNA0417164300", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 1000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER"), Amount: amount, ReferenceForBeneficiary: common.PtrString("YOUR_REFERENCE_SENT_TO_BENEFICIARY"), Description: common.PtrString("YOUR_DESCRIPTION_FOR_THE_TRANSFER"), Counterparty: counterpartyInfoV3, Category: "bank", } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :balanceAccountId => 'BA00000000000000000000001', :category => 'bank', :description => 'YOUR_DESCRIPTION_FOR_THE_TRANSFER', :reference => 'YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER', :referenceForBeneficiary => 'YOUR_REFERENCE_SENT_TO_BENEFICIARY', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen' }, :accountIdentification => { :type => 'iban', :iban => 'NL91ABNA0417164300' } } } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const partyIdentification3: Types.transfers.PartyIdentification = { fullName: "A. Klaassen" }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL91ABNA0417164300", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 1000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", amount: amount, referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", counterparty: counterpartyInfoV3, category: Types.transfers.TransferInfo.CategoryEnum.Bank }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` 2. Verify that the response header contains the following fields: * `status`: **401** * `auth-param1`: Base64-encoded blob of data. You will need `auth-param1` when you [authenticate your user](#authenticate-user). **Response header** ```json "WWW-Authenticate: SCA realm="Transfer" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."" ``` 3. Verify that the response body contains the following fields: * `amount`: An object containing the amount and currency of the funds that will be transferred. * `counterparty`: An object containing information about the counterparty that will receive the funds. You must show this data to your user when you [authenticate your user](#authenticate-user). **Response for initiating a fund transfer** ```json { "type": "https://docs.adyen.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "response": { "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, }, "errorCode": "00_401" } ``` 4. Pass `auth-param1` to the SDK as `sdkInput`. ### Tab: Authenticate during approval To initiate a funds transfer for your user and trigger SCA during approval, do the following: 1. Make a POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request, specifying the following parameters: | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-amount) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The amount of the transfer. | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-balanceAccountId) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the source balance account. | | [category](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-category) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **bank**. | | [counterparty.bankAccount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains information about the target bank account. | | [description](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-description) | Body | | A human-readable description for the transfer. | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-reference) | Body | | A reference of the transfer, only used internally within your balance platform. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-referenceForBeneficiary) | Body | | A reference that is sent to the recipient. | | [review.numberOfApprovalsRequired](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review-numberOfApprovalsRequired) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the number of approvals required to process the transfer. | | [review.scaOnApproval](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review-scaOnApproval) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **true**. | **Initiate funds transfer** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "review": { "numberOfApprovalsRequired": 1, "scaOnApproval": true } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("YOUR_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification() .fullName("A. Klaassen"); IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL91ABNA0417164300") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(ibanAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(1000L); TransferRequestReview transferRequestReview = new TransferRequestReview() .numberOfApprovalsRequired(1) .scaOnApproval(true); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") .amount(amount) .referenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") .review(transferRequestReview) .description("YOUR_DESCRIPTION_FOR_THE_TRANSFER") .counterparty(counterpartyInfoV3) .category(TransferInfo.CategoryEnum.BANK); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("YOUR_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL91ABNA0417164300") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $transferRequestReview = new TransferRequestReview(); $transferRequestReview ->setNumberOfApprovalsRequired(1) ->setScaOnApproval(true); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") ->setAmount($amount) ->setReferenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") ->setReview($transferRequestReview) ->setDescription("YOUR_DESCRIPTION_FOR_THE_TRANSFER") ->setCounterparty($counterpartyInfoV3) ->setCategory("bank"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "YOUR_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification { FullName = "A. Klaassen" }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL91ABNA0417164300", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; TransferRequestReview transferRequestReview = new TransferRequestReview { NumberOfApprovalsRequired = 1, ScaOnApproval = true }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", Amount = amount, ReferenceForBeneficiary = "YOUR_REFERENCE_SENT_TO_BENEFICIARY", Review = transferRequestReview, Description = "YOUR_DESCRIPTION_FOR_THE_TRANSFER", Counterparty = counterpartyInfoV3, Category = TransferInfo.CategoryEnum.Bank }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "YOUR_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const transferInfo = { amount: { currency: "EUR", value: 1000 }, balanceAccountId: "BA00000000000000000000001", category: "bank", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen" }, accountIdentification: { type: "iban", iban: "NL91ABNA0417164300" } } }, review: { numberOfApprovalsRequired: 1, scaOnApproval: true } } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "YOUR_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) partyIdentification3 := transfers.PartyIdentification{ FullName: common.PtrString("A. Klaassen"), } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL91ABNA0417164300", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 1000, } transferRequestReview := transfers.TransferRequestReview{ NumberOfApprovalsRequired: common.PtrInt32(1), ScaOnApproval: common.PtrBool(true), } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER"), Amount: amount, ReferenceForBeneficiary: common.PtrString("YOUR_REFERENCE_SENT_TO_BENEFICIARY"), Review: &transferRequestReview, Description: common.PtrString("YOUR_DESCRIPTION_FOR_THE_TRANSFER"), Counterparty: counterpartyInfoV3, Category: "bank", } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "YOUR_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "review": { "numberOfApprovalsRequired": 1, "scaOnApproval": True } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'YOUR_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :balanceAccountId => 'BA00000000000000000000001', :category => 'bank', :description => 'YOUR_DESCRIPTION_FOR_THE_TRANSFER', :reference => 'YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER', :referenceForBeneficiary => 'YOUR_REFERENCE_SENT_TO_BENEFICIARY', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen' }, :accountIdentification => { :type => 'iban', :iban => 'NL91ABNA0417164300' } } }, :review => { :numberOfApprovalsRequired => 1, :scaOnApproval => true } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "YOUR_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const partyIdentification3: Types.transfers.PartyIdentification = { fullName: "A. Klaassen" }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL91ABNA0417164300", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 1000 }; const transferRequestReview: Types.transfers.TransferRequestReview = { numberOfApprovalsRequired: 1, scaOnApproval: true }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", amount: amount, referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", review: transferRequestReview, description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", counterparty: counterpartyInfoV3, category: Types.transfers.TransferInfo.CategoryEnum.Bank }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` 2. Verify that you receive an **HTTP 2XX** response that includes the following parameters: * `amount`: You must show this data to your user during [authentication](#authenticate-user). * `counterparty`: You must show this data to your user during authentication. * `id`: You must include the transfer ID in the POST `/transfers/approve` request. 3. Make a POST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) request, specifying the following parameters: | **Parameter name** | **Type** | **Required** | **Description** | | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **ApproveTransfers**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [initiate the SCA authentication process](#initiate-authentication). | | [transferIds](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve#request-transferIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array containing the unique identifiers of the transfers that you decide to approve. You can include the IDs of all transfers that have: — `status`: **received** — `reason`: **pendingApproval** | **Approve funds transfer and trigger SCA** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/approve \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest() .transferIds(Arrays.asList("APUFHASUFD4AS", "407ASFPUHASFA")); // Send the request TransfersApi service = new TransfersApi(client); service.approveInitiatedTransfers(approveTransfersRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $approveTransfersRequest = new ApproveTransfersRequest(); $approveTransfersRequest ->setTransferIds(array("APUFHASUFD4AS", "407ASFPUHASFA")); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $service->approveInitiatedTransfers($approveTransfersRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest { TransferIds = { "APUFHASUFD4AS", "407ASFPUHASFA" } }; // Send the request var service = new TransfersService(client); service.ApproveInitiatedTransfers(approveTransfersRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest = { transferIds: [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) approveTransfersRequest := transfers.ApproveTransfersRequest{ TransferIds: []string{ "APUFHASUFD4AS", "407ASFPUHASFA", }, } // Send the request service := client.Transfers() req := service.TransfersApi.ApproveInitiatedTransfersInput().IdempotencyKey("UUID").ApproveTransfersRequest(approveTransfersRequest) service.TransfersApi.ApproveInitiatedTransfers(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :transferIds => [ 'APUFHASUFD4AS', '407ASFPUHASFA' ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest: Types.transfers.ApproveTransfersRequest = { transferIds: ["APUFHASUFD4AS", "407ASFPUHASFA"] }; // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` 4. Verify that the response header contains the following fields: * `status`: **401** * `auth-param1`: Base64-encoded blob of data. You will need `auth-param1` when you [authenticate your user](#authenticate-user). **Response header** ```json "WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."" ``` **Response for initiating the approval of a fund transfer** ```json { "type": "https://docs.adyen.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "response": { "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] }, "errorCode": "00_401" } ``` 5. Pass `auth-param1` to the SDK as `sdkInput`. ## Authenticate user After [initiating a transfer](#initiate-transfer) request, you have 10 minutes to complete the authentication process and [finalize the transfer request](#finalize-transfer). When authenticating your user, PSD2 requires you to show to your user the amount and the counterparty (payee) of the transfer that the user is authenticating for. To comply with these regulations, we recommend that you implement a push notification and use the `amount` and `counterparty` fields from: * The response to the POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request you used to create the transfer. * The response to a GET [/transfers/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)) request. To authenticate your user with the Authentication SDK: 1. Trigger the SDK to start user authentication and pass the `auth-param1` value from [the previous step](#initiate-authentication) as `sdkInput`. ### Tab: Android (Kotlin) **Authenticate with SCA SDK** ```kotlin lifecycleScope.launch { if (adyenAuthentication.hasCredential("sdkInput")) { // Authenticate existing credential val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput") when (authenticationResult) { is AuthenticationResult.AuthenticationSuccessful -> { authenticationResult.sdkOutput } is AuthenticationResult.Canceled -> { // User cancelled the authentication flow } is AuthenticationResult.Error -> { // Unexpected error authenticationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error authenticationResult.authenticationError } } } else { // None of the existing credentials exist in this device } } ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. ### Tab: iOS (Swift) **Authenticate with SCA SDK** ```swift delegatedAuthenticationSession.authenticate(withBase64URLString: sdkInput) { [weak self] result in switch result { case let .success(sdkOutput): /// send the sdkOutput to the backend case let .failure(error): /// authentication failed } } ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) **Authenticate with SCA SDK** ```javascript const sdkOutput = await scaWebauthn.authenticate(sdkInput); ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. 2. Pass `sdkOutput` to your server. ## Finalize transfer The steps to initiate a transfer depend on whether you: * Authenticated the user when initiating a transfer request. * Authenticated the reviewer when approving a transfer request. The following tabs explain both methods for finalizing a transfer after completing SCA. ### Tab: Authenticated during initiation To finalize the transfer: 1. Make a POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request, specifying the following parameters: The values of the body parameters must match the ones previously submitted to the `/transfers` endpoint [when initiating the transfer](#initiate-transfer). | Parameter | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#header-WWW_Authenticate) | Header | `SCA realm`: **Transfer**. `auth-param1`: Base64-encoded value of **sdkOutput** you get from the Authentication SDK when you [authenticate the user](#authenticate-user). | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-amount) | Body | The amount of the transfer. | | [category](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-category) | Body | Set to **bank**. | | [description](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-description) | Body | A human-readable description for the transfer. | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-balanceAccountId) | Body | The unique identifier of the source balance account. | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-reference) | Body | A reference of the transfer, only used internally within your balance platform. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-referenceForBeneficiary) | Body | A reference that is sent to the recipient. | | [counterparty.balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-balanceAccountId) | Body | The unique identifier of the target balance account. | **Finalize funds transfer** #### curl ```bash curl 'https://balanceplatform-api-test.adyen.com/btl/v4/transfers' \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="Transfer" auth-param1="CeCcEEJf2UPC7pB0K7AtEgLZX7cTvnqNznJF...' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "internal", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification() .fullName("A. Klaassen"); IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL91ABNA0417164300") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(ibanAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(1000L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") .amount(amount) .referenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") .description("YOUR_DESCRIPTION_FOR_THE_TRANSFER") .counterparty(counterpartyInfoV3) .category(TransferInfo.CategoryEnum.INTERNAL); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL91ABNA0417164300") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(1000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") ->setAmount($amount) ->setReferenceForBeneficiary("YOUR_REFERENCE_SENT_TO_BENEFICIARY") ->setDescription("YOUR_DESCRIPTION_FOR_THE_TRANSFER") ->setCounterparty($counterpartyInfoV3) ->setCategory("internal"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification { FullName = "A. Klaassen" }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL91ABNA0417164300", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 1000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", Amount = amount, ReferenceForBeneficiary = "YOUR_REFERENCE_SENT_TO_BENEFICIARY", Description = "YOUR_DESCRIPTION_FOR_THE_TRANSFER", Counterparty = counterpartyInfoV3, Category = TransferInfo.CategoryEnum.Internal }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const transferInfo = { amount: { currency: "EUR", value: 1000 }, balanceAccountId: "BA00000000000000000000001", category: "internal", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen" }, accountIdentification: { type: "iban", iban: "NL91ABNA0417164300" } } } } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) partyIdentification3 := transfers.PartyIdentification{ FullName: common.PtrString("A. Klaassen"), } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL91ABNA0417164300", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 1000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER"), Amount: amount, ReferenceForBeneficiary: common.PtrString("YOUR_REFERENCE_SENT_TO_BENEFICIARY"), Description: common.PtrString("YOUR_DESCRIPTION_FOR_THE_TRANSFER"), Counterparty: counterpartyInfoV3, Category: "internal", } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "internal", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 1000 }, :balanceAccountId => 'BA00000000000000000000001', :category => 'internal', :description => 'YOUR_DESCRIPTION_FOR_THE_TRANSFER', :reference => 'YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER', :referenceForBeneficiary => 'YOUR_REFERENCE_SENT_TO_BENEFICIARY', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen' }, :accountIdentification => { :type => 'iban', :iban => 'NL91ABNA0417164300' } } } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const partyIdentification3: Types.transfers.PartyIdentification = { fullName: "A. Klaassen" }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL91ABNA0417164300", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 1000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", amount: amount, referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_BENEFICIARY", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", counterparty: counterpartyInfoV3, category: Types.transfers.TransferInfo.CategoryEnum.Internal }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` 2. Verify that the response header contains `status` **authorised**. This means that the authentication and transfer request were successful.\ The following example shows a response for a successful funds transfer. **Finalize funds transfer response** ```json { "id": "1W1UG35U8A9J5ZLG", "amount": { "currency": "EUR", "value": 1000 }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY", "direction": "outgoing", "reason": "pending", "status": "received" } ``` ### Tab: Authenticated during approval To finalize the transfer: 1. Make a POST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) request, specifying the following parameters: The values of the body parameters must match the ones previously submitted to the `/transfers/approve` endpoint [when initiating the transfer](#initiate-transfer). | **Parameter name** | **Type** | **Required** | **Description** | | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **ApproveTransfers**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [authenticate the user](#authenticate-user). | | [transferIds](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve#request-transferIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array containing the unique identifiers of the transfers that you decide to approve. | **Finalize approval of funds transfers** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/approve \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="CeCcEEJf2UPC7pB0K7AtEgLZX7cTvnqNznJF..."' \ -X POST \ -d '{ "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest() .transferIds(Arrays.asList("APUFHASUFD4AS", "407ASFPUHASFA")); // Send the request TransfersApi service = new TransfersApi(client); service.approveInitiatedTransfers(approveTransfersRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $approveTransfersRequest = new ApproveTransfersRequest(); $approveTransfersRequest ->setTransferIds(array("APUFHASUFD4AS", "407ASFPUHASFA")); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $service->approveInitiatedTransfers($approveTransfersRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest { TransferIds = { "APUFHASUFD4AS", "407ASFPUHASFA" } }; // Send the request var service = new TransfersService(client); service.ApproveInitiatedTransfers(approveTransfersRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest = { transferIds: [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) approveTransfersRequest := transfers.ApproveTransfersRequest{ TransferIds: []string{ "APUFHASUFD4AS", "407ASFPUHASFA", }, } // Send the request service := client.Transfers() req := service.TransfersApi.ApproveInitiatedTransfersInput().IdempotencyKey("UUID").ApproveTransfersRequest(approveTransfersRequest) service.TransfersApi.ApproveInitiatedTransfers(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :transferIds => [ 'APUFHASUFD4AS', '407ASFPUHASFA' ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest: Types.transfers.ApproveTransfersRequest = { transferIds: ["APUFHASUFD4AS", "407ASFPUHASFA"] }; // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` 2. Verify that you receive an **HTTP 200 OK** response with a header that contains `status` **authorised**. 3. Verify that you receive a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with `status` **authorised**. This means that the authentication and transfer approval were successful. --- # Source: https://docs.adyen.com/business-accounts/sca-for-transaction-history.md Section: Business accounts Title: SCA for transaction history Description: Learn how to use our Authentication SDK to authenticate your users when they request their transaction history. --- title: "SCA for transaction history" description: "Learn how to use our Authentication SDK to authenticate your users when they request their transaction history." url: "https://docs.adyen.com/business-accounts/sca-for-transaction-history" source_url: "https://docs.adyen.com/business-accounts/sca-for-transaction-history.md" canonical: "https://docs.adyen.com/business-accounts/sca-for-transaction-history" last_modified: "2022-11-30T17:52:00+01:00" language: "en" --- # SCA for transaction history Learn how to use our Authentication SDK to authenticate your users when they request their transaction history. [View source](/business-accounts/sca-for-transaction-history.md) Each time a user in the European Economic Area (EEA) wants to check their transaction history, you must authenticate them using SCA. This process ensures that sensitive financial data is only accessible to authorized users, fulfilling PSD2 regulatory requirements for secure data retrieval.\ \ Use the Authentication SDK to integrate this verification flow directly into your transaction history request. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | This feature is supported with an [Adyen for Platforms](/platforms) or a [Classic integration](/point-of-sale/classic-library-deprecation). | | **[API credentials](/development-resources/api-credentials/)** | You must have an [API key](/development-resources/api-credentials/#generate-api-key) (recommended) or [basic authentication username and password](/development-resources/api-credentials/#basic-authentication) to access this API. Ensure that you have asked your Adyen contact to assign the following role to your API credential: - **TransferService Webservice Retrieve role** | | **Setup steps** | Before you begin:- Make sure that you have [installed the Authentication SDK](/business-accounts/install-auth-sdk). - Make sure that you have [registered a device](/business-accounts/register-sca-devices) for your user. | ## How it works To retrieve transaction history, verify device eligibility, trigger a secure challenge via the SDK, and retrieve the data, perform the following: 1. [Check SCA eligibility](#initiate-authentication) 2. [Initiate a request for your user's transaction history](#initiate-request-transactions) using the `sdkOutput` that you got when you checked the device for SCA eligibility. 3. [Authenticate your user](#authenticate-user) with the Authentication SDK. 4. [Get the transaction history](#get-transactions) using the `sdkOutput` from the authentication step. ## Check SCA eligibility Before requesting the transaction history, you must check for SCA eligibility and initiate the process to authenticate your users. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript. ### Tab: Android (Kotlin) To initiate authentication on an Android device: To check if the Android device is eligible for SCA: 1. Initiate the `AdyenAuthentication` class in your Activity or Fragment. **Initiate authentication** ```kotlin private lateinit var adyenAuthentication: AdyenAuthentication override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) adyenAuthentication = AdyenAuthentication(this) } ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```kotlin lifecycleScope.launch { val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability() if (availabilityResult is AvailabilityResult.Available) { availabilityResult.sdkOutput } } ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: iOS (Swift) To initiate authentication on an iOS device: To check if the iOS device is eligible for SCA: 1. Initialize the `AuthenticationService` class. **Initialize authentication service** ```swift let configuration = AuthenticationService.Configuration( localizedRegistrationReason: registrationReason, localizedAuthenticationReason: authenticationReason, appleTeamIdendtifier: appleTeamIdentifier ) let authenticationService = AuthenticationService(configuration: configuration) ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```swift let sdkOutput = try authenticationService.checkSupport() /// send the sdkOutput to your backend ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: Web (JavaScript) To initiate authentication on a web browser on your web-enabled device: To check if the web browser on your web-enabled device is eligible for SCA: 1. Import the node package in your application. `RelyingPartyName` is the name the user will be presented with when creating or validating a `WebAuthn` operation. We recommend that the value of the `RelyingPartyName` be the merchant name or the URL domain. **Import web sdk and initiate authentication** ```javascript import ScaWebauthn from '@adyen/bpscaweb'; const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'merchant', }); const sdkOutput = await scaWebauthn.checkAvailability().catch((error) => /* SCA_UNAVAILABLE error*/); ``` If the user's browser supports SCA, the function returns `sdkOutput` to exchange in requests to the server. If SCA is not supported, the method throws an `SCA_UNAVAILABLE` error. 2. Pass the `sdkOutput` to your server. You will use the `sdkOutput` when [initiating a request for transaction history](#initiate-request-transactions). ## Initiate a request for the transaction history To request the transaction history for the specified balance account: 1. Make a GET [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) request, specifying the following parameter in the header: | Request header | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | `SCA realm`: **Transaction**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [initiate authentication](#initiate-authentication).. | Provide the following query parameters: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Unique identifier of the balance account to get the transaction history for. | | [createdSince](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-createdSince) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Only include transactions that have been created on or after this point in time. The value must be in ISO 8601 format. For example, **2022-05-30T15:07:40Z**. | | [createdUntil](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-createdUntil) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Only include transactions that have been created on or before this point in time. The value must be in ISO 8601 format. For example, **2022-05-31T15:07:40Z**. | **Request transaction history** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transactions?balanceAccountId=BA00000000000000000000002&createdSince=2022-05-30T15:07:40Z&createdUntil=2022-05-31T15:07:40Z \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="Transaction" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X GET \ -d '{ }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request TransactionsApi service = new TransactionsApi(client); TransactionSearchResponse response = service.getAllTransactions("String", "String", "String", "String", "String", LocalDateTime.parse("2025-01-01T15:00:00");, LocalDateTime.parse("2025-01-01T15:00:00");, 1, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('balancePlatform' => 'string', 'paymentInstrumentId' => 'string', 'accountHolderId' => 'string', 'balanceAccountId' => 'string', 'cursor' => 'string', 'createdSince' => 'date-time', 'createdUntil' => 'date-time', 'limit' => 'integer'); // Send the request $service = new TransactionsApi($client); $response = $service->getAllTransactions($requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TransactionsService(client); var response = service.GetAllTransactions(balancePlatform: "string", paymentInstrumentId: "string", accountHolderId: "string", balanceAccountId: "string", cursor: "string", createdSince: DateTime.Parse("2025-01-01T15:00:00"), createdUntil: DateTime.Parse("2025-01-01T15:00:00"), limit: 1); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Transfers() req := service.TransactionsApi.GetAllTransactionsInput() req = req.BalancePlatform("string").PaymentInstrumentId("string").AccountHolderId("string").BalanceAccountId("string").Cursor("string").CreatedSince(DateTime.Parse("2025-01-01T15:00:00")).CreatedUntil(DateTime.Parse("2025-01-01T15:00:00")).Limit(1) res, httpRes, err := service.TransactionsApi.GetAllTransactions(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. query_parameters = { "balancePlatform" : "string", "paymentInstrumentId" : "string", "accountHolderId" : "string", "balanceAccountId" : "string", "cursor" : "string", "createdSince" : "date-time", "createdUntil" : "date-time", "limit" : "integer" } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :balancePlatform => 'string', :paymentInstrumentId => 'string', :accountHolderId => 'string', :balanceAccountId => 'string', :cursor => 'string', :createdSince => 'date-time', :createdUntil => 'date-time', :limit => 'integer' } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` 2. In the response, note the following field in the header: * `auth-param1`: Base64-encoded blob of data. You will need `auth-param1` when [authenticating your user using the SDK](#authenticate-user). **Response** ```json { "type": "https://docs.adyen.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "errorCode": "00_401" } ``` 3. Pass `auth-param1` to the SDK as `sdkInput`. ## Authenticate your user After [initiating the request](#initiate-request-transactions), you have 10 minutes to complete the authentication process and [finalize the request](#get-transactions). To authenticate your user with the Authentication SDK: 1. Trigger the SDK and pass the `auth-param1` value from the previous step as `sdkInput`. ### Tab: Android (Kotlin) **Authenticate with SCA SDK** ```kotlin lifecycleScope.launch { if (adyenAuthentication.hasCredential("sdkInput")) { // Authenticate existing credential val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput") when (authenticationResult) { is AuthenticationResult.AuthenticationSuccessful -> { authenticationResult.sdkOutput } is AuthenticationResult.Canceled -> { // User cancelled the authentication flow } is AuthenticationResult.Error -> { // Unexpected error authenticationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error authenticationResult.authenticationError } } } else { // None of the existing credentials exist in this device } } ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. ### Tab: iOS (Swift) **Authenticate with SCA SDK** ```swift delegatedAuthenticationSession.authenticate(withBase64URLString: sdkInput) { [weak self] result in switch result { case let .success(sdkOutput): /// send the sdkOutput to the backend case let .failure(error): /// authentication failed } } ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) **Authenticate with SCA SDK** ```javascript const sdkOutput = await scaWebauthn.authenticate(sdkInput); ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. 2. Pass `sdkOutput` to your server. ## Get the transaction history To finalize the request to get the transaction history: 1. Make a GET [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) request, specifying the following parameter in the request header. | Request header | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | `SCA realm`: **Transaction**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [initiate authentication](#initiate-authentication). | **Get user transaction history** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transactions?balanceAccountId=BA00000000000000000000002&createdSince=2022-05-30T15:07:40Z&createdUntil=2022-05-31T15:07:40Z \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="Transaction" auth-param1="CeCcEEJf2UPC7pB0K7AtEgLZX7cTvnqNznJF..."' \ -X GET \ -d '{ }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request TransactionsApi service = new TransactionsApi(client); TransactionSearchResponse response = service.getAllTransactions("String", "String", "String", "String", "String", LocalDateTime.parse("2025-01-01T15:00:00");, LocalDateTime.parse("2025-01-01T15:00:00");, 1, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('balancePlatform' => 'string', 'paymentInstrumentId' => 'string', 'accountHolderId' => 'string', 'balanceAccountId' => 'string', 'cursor' => 'string', 'createdSince' => 'date-time', 'createdUntil' => 'date-time', 'limit' => 'integer'); // Send the request $service = new TransactionsApi($client); $response = $service->getAllTransactions($requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TransactionsService(client); var response = service.GetAllTransactions(balancePlatform: "string", paymentInstrumentId: "string", accountHolderId: "string", balanceAccountId: "string", cursor: "string", createdSince: DateTime.Parse("2025-01-01T15:00:00"), createdUntil: DateTime.Parse("2025-01-01T15:00:00"), limit: 1); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Transfers() req := service.TransactionsApi.GetAllTransactionsInput() req = req.BalancePlatform("string").PaymentInstrumentId("string").AccountHolderId("string").BalanceAccountId("string").Cursor("string").CreatedSince(DateTime.Parse("2025-01-01T15:00:00")).CreatedUntil(DateTime.Parse("2025-01-01T15:00:00")).Limit(1) res, httpRes, err := service.TransactionsApi.GetAllTransactions(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. query_parameters = { "balancePlatform" : "string", "paymentInstrumentId" : "string", "accountHolderId" : "string", "balanceAccountId" : "string", "cursor" : "string", "createdSince" : "date-time", "createdUntil" : "date-time", "limit" : "integer" } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :balancePlatform => 'string', :paymentInstrumentId => 'string', :accountHolderId => 'string', :balanceAccountId => 'string', :cursor => 'string', :createdSince => 'date-time', :createdUntil => 'date-time', :limit => 'integer' } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` 2. Use the content of the [data](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#responses-200-data) array to present the transaction information to your user. **Response** ```json { "data": [ { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-10T14:51:20+02:00", "id": "EVJN42272224222B5JB8BRC84N686ZEUR", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": -1000 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-10T14:51:33+02:00", "status": "booked", "transfer": { "id": "3JNC3O5ZVFLLGV4B", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-10T14:51:20+02:00" }, { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-10T15:34:31+02:00", "id": "EVJN4227C224222B5JB8G3Q89N2NB6EUR", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": 123 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-10T15:34:40+02:00", "status": "booked", "transfer": { "id": "48POO45ZVG11166J", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-10T15:34:31+02:00" } ], "_links": { "next": { "href": "https://balanceplatform-api-test.adyen.com/btl/v4/transactions?balancePlatform=YOUR_BALANCE_PLATFORM&createdUntil=2023-08-20T13%3A07%3A40Z&createdSince=2023-08-10T10%3A50%3A40Z&cursor=S2B-c0p1N0tdN0l6RGhYK1YpM0lgOTUyMDlLXElyKE9LMCtyaFEuMj1NMHgidCsrJi1ZNnhqXCtqVi5JPGpRK1F2fCFqWzU33JTojSVNJc1J1VXhncS10QDd6JX9FQFl5Zn0uNyUvSXJNQTo" } } } ``` ## See also * [How SCA works](/business-accounts/how-sca-works) --- # Source: https://docs.adyen.com/business-accounts/send-funds.md Section: Business accounts Title: Send funds to third parties Description: Learn how to send funds to third parties using an Adyen business account. --- title: "Send funds to third parties" description: "Learn how to send funds to third parties using an Adyen business account." url: "https://docs.adyen.com/business-accounts/send-funds" source_url: "https://docs.adyen.com/business-accounts/send-funds.md" canonical: "https://docs.adyen.com/business-accounts/send-funds" last_modified: "2022-02-28T17:18:00+01:00" language: "en" --- # Send funds to third parties Learn how to send funds to third parties using an Adyen business account. [View source](/business-accounts/send-funds.md) With an Adyen business account, your users can make business-related payments by transferring funds to third-party bank accounts, for example, to pay out their suppliers. Third-party accounts are *not owned* by your user and therefore *not connected* to their legal entity as a [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments). When your user makes a payment to a third-party bank account, their business accounts are debited, and the business account number is shown in the bank statement of the recipient. Adyen informs your server of this transfer through [outgoing bank transfer webhooks](/business-accounts/third-party-transfer-webhooks/#sending-funds). We are working on making it possible to collect payments from third-party bank accounts through direct debit. In this case, the Adyen business account is credited. ## Supported currencies, locations, and priorities You can specify how fast you want the funds to arrive to your user's account by setting a priority in the request or schedule. A with a higher priority incurs higher fees. You can set the following priorities for bank transfers: * **Regular**: Recommended for standard, low-value transactions to a recipient in the same region. * **Instant**: Transfers funds instantly within the United States, Australia, the United Kingdom, and the [Single Euro Payments Area (SEPA)](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en). * **Fast**: Processes faster than Regular and incurs higher fees. Suitable for high-priority, low-value transfers in the same region. * **Wire**: The fastest option, with the highest fees. Recommended for high-priority, high-value transfers in the same region. * **Cross-border**: Recommended for high-value transfers to recipients in other regions or countries. When using Cross-border priority, delays and additional fees may occur due to intermediary banks. As a result, the beneficiary may receive a lower amount than the instructed value. * **Internal**: Transfers between Adyen-issued accounts, such as balance accounts or business accounts. The following tables show the priorities available for each currency and location. ### Tab: Send USD | Priority of outgoing transfer | Available for US business accounts | Available for EU business account | Available for UK business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Instant | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Fast | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Wire | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Cross border | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Tab: Send EUR | Priority of outgoing transfer | Available for US business accounts | Available for EU business accounts | Available for UK business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Instant | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Fast | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Wire | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Cross border | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Tab: Send GBP | Priority of outgoing transfer | Available for US business accounts | Available for EU business accounts | Available for UK business accounts | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Regular | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Instant | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Fast | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Wire | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Cross border | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Internal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ## Transfer cut-off times There are specific times during a business day, called **cut-off times**, when Adyen stops processing bank transfers for settlement within the settlement delay. Bank transfers initiated before the cut-off time are typically processed within the specified **settlement delay**, while those initiated after the cut-off time will be processed the next day within the specified settlement delay. Adhering to cut-off times can help you maintain consistency and predictability of your financial activities. ### Example cut-off times ### Tab: SEPA recipient Suppose you need to make a bank to a recipient in the SEPA. Depending on when you initiate the , the funds will be available the same business day or the next business day. 1. You initiate the with a **wire** priority at **16:20 CET** (10 minutes before the 16:30 CET cut-off time). Adyen processes this , and the recipient will receive the funds the same business day. 2. You initiate the with a **wire** priority at **17:00 CET** (30 minutes after the 16:30 CET cut-off time). Because it is past the cut-off time, Adyen will process this on the following business day. The funds will be available in the recipient's account on the next business day (one business day from the date of the initiation). ### Tab: US recipient Suppose you need to make a bank to a US recipient. Depending on when you initiate the , the funds will be available the next business day or the day after the next business day. 1. You initiate the with a **regular** priority at **01:30 AM ET** (15 minutes before the 01:45 AM ET cut-off time). Adyen processes this , and the recipient will receive the funds on the same business day. 2. You initiate the with a **regular** priority at **02:30 AM ET** (45 minutes after the 01:45 AM ET cut-off time). Because it is past the cut-off time, Adyen will process this at the end of the business day. The funds will be available in the recipient's account on the next business day. For example, a initiated at 02:30 AM ET on a Tuesday will have the funds available in the beneficiary's bank account at approximately 09:00 AM ET on Wednesday. ** #### Cut-off times by location, currency, and priority | Country/region | Currency | Priority | Cut-off time | Local timezone | Settlement delay | Min amount | Max amount | | --------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ------------ | -------------- | ---------------- | ---------- | ---------------- | | Australia | AUD | Wire | 15:00 | AEDT | Same day | 0.01 | 999,999,999.99 | | Australia | AUD | Regular | 17:15 | AEDT | Same day | 0.01 | 999,999,999.99 | | Australia | AUD | Fast | 23:15 | AEDT | Same day | 0.01 | 5,000,000.00 | | Bulgaria | BGN | Wire | 10:45 | CET | Same day | 1.00 | 999,999,999.99 | | Bulgaria | BGN | Regular | 10:45 | CET | Same day | 1.00 | 99,999.99 | | Canada | CAD | Regular | 17:45 | ET | Same day | 1.00 | 999,999.99 | | Canada | USD | Regular | 02:00 | ET | Same day | 1.00 | 999,999.99 | | Czechia | CZK | Wire | 12:00 | CET | Same day | 0.01 | 999,999,999.99 | | Czechia | CZK | Regular | 12:00 | CET | Same day | 0.01 | 999,999,999.99 | | Denmark | DKK | Wire | 14:45 | CET | Same day | 1.00 | 999,999,999.99 | | Denmark | DKK | Regular | 10:15 | CET | Same day | 1.00 | 39,999,999.99 | | Hong Kong | HKD | Wire | 14:45 | HKT | Same day | 1.00 | 999,999,999.99 | | Hong Kong | USD | Wire | 14:45 | HKT | Same day | 1.00 | 999,999,999.99 | | Hong Kong | HKD | Regular | 15:45 | HKT | Same day | 1.00 | 999,999,999.99 | | Hungary | HUF | Regular | 13:00 | CET | Same day | 1.00 | 999,999,999.99 | | New Zealand | NZD | Wire | 15:30 | NZST | Same day | 0.01 | 999,999,999.99 | | New Zealand | NZD | Regular | 18:30 | NZST | Same day | 0.01 | 999,999,999.99 | | Norway | NOK | Wire | 14:00 | CET | Same day | 1.00 | 999,999,999.99 | | Norway | NOK | Regular | 14:00 | CET | Same day | 1.00 | 10,000,000.00 | | Poland | PLN | Wire | 10:50 | CET | Same day | 0.01 | 999,999,999.99 | | Poland | PLN | Regular | 10:30 | CET | Same day | 0.01 | 999,999,999.99 | | Romania | RON | Wire | 10:15 | CET | Same day | 0.50 | 999,999,999.99 | | Romania | RON | Regular | 10:15 | CET | Same day | 0.50 | 50,000.00 | | [SEPA](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en) | EUR | Wire | 16:55 | CET | Same day | 0.01 | 999,999,999.99 | | [SEPA](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en) | EUR | Regular | 15:45 | CET | Same day | 0.01 | 999,999,999.99 | | [SEPA](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en) | EUR | Instant | 24/7 | CET | Same day | 0.01 | 100,000.00 | | Singapore | SGD | Wire | 16:45 | SGT | Same day | 1.00 | 999,999,999.99 | | Singapore | SGD | Regular | 18:15 | SGT | Next day | 1.00 | 90,000,000.00 | | Singapore | SGD | Fast | 23:45 | SGT | Same day | 1.00 | 200,000.00 | | Sweden | SEK | Wire | 15:30 | CET | Same day | 1.00 | 999,999,999.99 | | Sweden | SEK | Regular | 12:00 | CET | Same day | 1.00 | 999,999,999.99 | | Switzerland | CHF | Wire | 15:45 | CET | Same day | 0.01 | 999,999,999.99 | | Switzerland | CHF | Regular | 11:45 | CET | Same day | 0.01 | 100,000,000.00 | | United Kingdom | GBP | Wire | 15:15 | GMT | Same day | 0.01 | 999,999,999.99 | | United Kingdom | GBP | Regular | 19:30 | GMT | T+2 | 0.01 | 20,000,000.00 | | United Kingdom | GBP | Fast | 21:00 | GMT | Same day | 0.01 | 1,000,000.00 | | United States | USD | Wire | 18:30 | ET | Same day | 0.01 | 9,999,999,999.99 | | United States | USD | Regular | 01:45 | ET | Same day | 0.01 | 99,999,999.99 | | United States | USD | Fast | 16:15 | ET | Same day | 0.01 | 1,000,000.00 | | United States | USD | Instant | 24/7 | ET | Same day | 0.01 | 1,000,000.00 | ## Bank account identification types and supported priorities When transferring funds to a third-party bank account, you need to provide the `accountIdentification.type` in your API request. The type also determines the required bank account details. 1. To determine the `accountIdentification.type` value, you must have: * The location of the recipient bank account. * The currency of the funds you are transferring. 2. Find the combination in the table below and select the `type` to see the required fields. This combination also identifies if you are doing a local or cross-border transfer. Cross-border transfers must be sent as wire transfers, and you must include the address of the bank account owner. []() The following table show the limits for the length and the characters you can use in the descriptions based on the country/region, currency and priority. ## Supported countries, currencies, and priorities See the following overview of supported countries, currencies, priorities, and bank account formats for bank details. Depending on the country or region, users can provide their bank details using the default bank account format or a custom value. ### Tab: Europe | Country/region of counterparty | Currency | Supported priority | Transfer description limits | Bank account formats | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Single Euro Payments Area (SEPA) countries](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en) | EUR | regular instant wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Czech Republic | CZK | regular | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) Custom [czLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-CZLocalAccountIdentification) | | Denmark | DKK | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [dkLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-DKLocalAccountIdentification) Custom [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Hungary | HUF | regular | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) Custom [huLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-HULocalAccountIdentification) | | Norway | NOK | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [noLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-NOLocalAccountIdentification) Custom [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Poland | PLN | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [plLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-PLLocalAccountIdentification) Custom [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Romania | RON | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Sweden | SEK | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [seLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-SELocalAccountIdentification) Custom [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | Switzerland | CHF | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | | United Kingdom | GBP | regular instant fast wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [ukLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-UKLocalAccountIdentification) Custom [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) | ### Tab: North America | Country/region of counterparty | Currency | Supported priority | Transfer description limits | Bank account formats | | ------------------------------ | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Canada | CAD, USD | regular | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [caLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-CALocalAccountIdentification) Custom [usLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-USLocalAccountIdentification) | | United States | USD | regular fast instant wire | Maximum 140 characters. Allowed characters for **regular** and **fast** priority: `[a-z][A-Z][0-9]& $ % # @ ~ = + - _ ' " ! ?` Allowed characters for **instant** and **wire** priority: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [usLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-USLocalAccountIdentification) | ### Tab: Asia Pacific | Country/region of counterparty | Currency | Supported priority | Transfer description limits | Bank account formats | | ------------------------------ | -------- | ------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Australia | AUD | regular fast wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [auLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-AULocalAccountIdentification) | | Hong Kong | HKD, USD | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [hkLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-HKLocalAccountIdentification) | | New Zealand | NZD | regular wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [nzLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-NZLocalAccountIdentification) | | Singapore | SGD | regular fast wire | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9]/ - ? : ( ) . , ' + Space` | Default [sgLocal](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-SGLocalAccountIdentification) | ### Tab: Cross-border | Country/region of counterparty | Currency | Supported priority | Transfer description limits | Type and other requirements | | -------------------------------------------------------------------------------- | ------------- | ------------------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Countries/regions where IBAN is required | EUR, GBP, USD | crossBorder | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9] . , – ( ) / = ' + : ? ! ” % & * < > ; Space` | - Type: [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) - [address](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountHolder-address) of the bank account owner | | Countries/regions where IBAN is optional (for example, Poland or Czech Republic) | EUR, GBP, USD | crossBorder | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9] . , – ( ) / = ' + : ? ! ” % & * < > ; Space` | - Type: [iban](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-IbanAccountIdentification) or [numberAndBic](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-NumberAndBicAccountIdentification) - [address](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountHolder-address) of the bank account owner | | Other countries/regions not listed above | EUR, GBP, USD | crossBorder | Maximum 140 characters. Allowed characters: `[a-z][A-Z][0-9] . , – ( ) / = ' + : ? ! ” % & * < > ; Space` | - Type: [numberAndBic](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountIdentification-NumberAndBicAccountIdentification) - [address](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountHolder-address) of the bank account owner | ## Next steps Keep track of Adyen business account transactions using webhooks or by making an API request. [required](/business-accounts/third-party-transfer-webhooks) [Get updates through webhooks](/business-accounts/third-party-transfer-webhooks) [Find out which webhooks Adyen sends for incoming and outgoing transactions.](/business-accounts/third-party-transfer-webhooks) [Use an API to get updates](/business-accounts/transactions) [Send API requests to query bank transactions.](/business-accounts/transactions) --- # Source: https://docs.adyen.com/business-accounts/send-funds-ideal-integration.md Section: Business accounts Title: Account-to-account (A2A) payments with iDEAL Description: Learn how to integrate A2A payment flow through Adyen. --- title: "Account-to-account (A2A) payments with iDEAL" description: "Learn how to integrate A2A payment flow through Adyen." url: "https://docs.adyen.com/business-accounts/send-funds-ideal-integration" source_url: "https://docs.adyen.com/business-accounts/send-funds-ideal-integration.md" canonical: "https://docs.adyen.com/business-accounts/send-funds-ideal-integration" last_modified: "2025-08-22T17:52:00+02:00" language: "en" --- # Account-to-account (A2A) payments with iDEAL Learn how to integrate A2A payment flow through Adyen. [View source](/business-accounts/send-funds-ideal-integration.md) Adyen supports making account-to-account (A2A) payments in the Netherlands through [iDEAL](https://ideal.nl/en). This feature allows your users to make online payments using their Adyen business account. This page explains how to: * Enable Account-to-Account (A2A) payments directly from Adyen business accounts. * Retrieve payment details using the `/payments/details` endpoint. * Confirm payments using the `/payments/confirm` endpoint * Cancel payments using the `/payments/cancel` endpoint. ## Requirements | Requirement | Description | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have the Adyen for Platforms integration that supports business accounts. | | **[API credentials](/development-resources/api-credentials/)** | The API user making the request must have the following role assigned:- **Role for A2A Issuer payments - API** | | **Limitations** | Some limitations are:- This documentation is only for platforms or marketplaces operating in the Netherlands. - Payments are exclusively facilitated via the iDEAL network. | | **Setup steps** | You must:- Have an Adyen business account. - [Implement Strong Customer Authentication (SCA)](/business-accounts/implement-sca/). - Integrate one of two ways: redirect or QR code. The QR code method requires your app to have a built-in QR reader that sends the raw QR information directly to the endpoint. - Ensure your platform's user interface and experience (UI/UX) follows iDEAL's UX and regulatory standards in the [Payment screen requirements](#payment-screen-requirements) section. - Provide the specific URLs for the [required redirect URLs](#configure-required-redirect-urls) to Adyen contact. - Provide your Adyen contact with a platform logo between (34–48) x 34 px. | ## iDEAL for A2A payments After you have integrated iDEAL for A2A payments, business account users can select iDEAL as a payment method during checkout. The payment flow redirects users to your platform, where they select their Adyen business account, complete a Strong Customer Authentication (SCA) process, and then authorize the payment. For platforms, this means faster payments, fewer dependencies on external banks, and a smoother user experience. ### How users complete SCA using your platform To complete the checkout process, your user must use your platform to complete SCA. How your user completes SCA depends on the device that they are using: ### Redirection Users are redirected from the checkout to your platform's app or website to authorize the payment. The user flow is as follows: #### Mobile (App-to-app) 1. The user starts the checkout on their mobile device, the mobile browser displays a "Select your bank" screen. 2. The user must select **Adyen** from the list, followed by selecting your platform. 3. The mobile browser opens your platform's app. 4. The user authorizes the payment within your app and is then automatically redirected back to the checkout in their mobile browser. #### Desktop computer 1. The user starts the checkout on their desktop computer, the desktop browser displays a "Select your bank" screen. 2. The user selects **Adyen** from the list of banks on their desktop browser, followed by selecting your platform. 3. The desktop browser opens your platform's web login page. 4. The user authorizes the payment on the web page and is then automatically redirected back to the checkout in their desktop browser. ### QR scan Users scan an iDEAL QR code on their desktop to authorize the payment via your mobile app. The user flow is as follows: #### Desktop computer 1. The user scans the iDEAL QR code displayed in the desktop browser using the QR reader within their mobile app. 2. This transfers the authorization session from the desktop computer to the mobile device. 3. After authorizing the payment, your mobile app must only show a success or confirmation screen. 4. Do not redirect the user from the mobile app to the checkout page. The desktop browser automatically detects the completed payment and handles the redirection to the checkout page. ## How it works The typical iDEAL integration flow with Adyen is as follows: 1. **Checkout**: The user initiates an iDEAL payment at the checkout page. 2. **Select bank**: The user is presented with an iDEAL screen where they can choose to scan a QR code or select a bank. If they choose to select a bank, they must select **Adyen** from the list of banks. 3. **Select platform**: The user is redirected to a platform selection page, located at the `payment_redirect_url` you provided in the [configure required redirect URLs](#configure-required-redirect-urls) step. From there, they must choose your platform from a list of all supported options. To automate this process, you can have users scan a QR code from your app. 4. **Log in**: The user must authenticate themselves on your platform. 5. **Show details**: The user is shown the details of the payment, prompted to authorize the transaction, and potentially select a source balance account (if multiple exist). 6. **Authorize**: The user authorizes the payment using Strong Customer Authentication (SCA). 7. **Result**: Upon successful payment or cancellation, the user is redirected back to the platform's page. The specific URL for this final redirection is returned by the `/payments/confirm` endpoint for success cases and the `/payments/cancel` endpoint for cancellations. The platform then displays the payment outcome, such as "Payment successful" to the user. The following tabs show example images of the screens that the user sees at each step of the flow. ### Tab: Checkout [![initial checkout](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-checkout.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-checkout.png) ### Tab: Select bank [![select bank](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-select-bank.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-select-bank.png) ### Tab: Select platform [![select platform](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-select-platform.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-select-platform.png) ### Tab: Log in [![login to platform](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-login-platform.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-login-platform.png) ### Tab: Show details [![show details of payment](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-show-details-payment.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-show-details-payment.png) ### Tab: Authorize [![authorize payment](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-authorize-payment.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-authorize-payment.png) ### Tab: Result [![payment result](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-payment-result.png)](/user/pages/reuse/pfs-business-accounts/ideal-integration-issuing/ideal-payment-result.png) ### Integration steps Follow these steps to implement an iDEAL integration: 1. [Configure required redirect URLs](#configure-required-redirect-urls) 2. [Retrieve payment information](#retrieve-payment-information) 3. [Check SCA eligibility](#check-sca-eligibility) 4. [Initiate SCA payment confirmation](#initiate-sca-payment-confirmation) 5. [Authenticate user](#authenticate-user) 6. [Complete SCA payment confirmation](#complete-sca-payment-confirmation) 7. [Cancel a payment](#cancel-a-payment) 8. [iDEAL profile endpoints](#ideal-profile-endpoints) ## Configure required redirect URLs To enable redirection for A2A payment and authentication to your platform, you must configure redirect URLs on your platform. 1. Configure the following redirect URLs on your platform: * `payment_redirect_url`: This is where Adyen sends users after they select your platform from Adyen's platform selection page. This URL should be configured to: * Require the user to log in with their credentials. * Accept a `payload` query parameter, which is then used in the `/payments/details` endpoint. * Redirect the user to a payment page that displays the transaction details for authorization. * `authenticate_redirect_url`: Adyen will use this URL to redirect the user to your platform if iDEAL requests user authentication. For details, see the [iDEAL profile authenticate endpoint](#authenticate) section. 2. Provide the specific URLs for these endpoints to Adyen as part of your integration setup. Both redirect URLs must support HTTPS and be capable of handling query parameters containing transaction context. ## Retrieve payment information Retrieve the iDEAL transaction information before authorization begins. This is done in two situations: after the user scans the payment QR code, or after they are redirected to your `payment_redirect_url` and have logged in. 1. From your server, make a POST `/payments/details` request specifying the following parameters: | Parameter | Location | Required | Applies to | Description | | --------- | -------- | ------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `method` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | All | The payment method this payment is from. Set to `ideal`. | | `source` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `method: ideal` | The source that was used to obtain the payload. Possible values include `redirect` or `qr`. | | `payload` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `method: ideal` | The payment payload is an identifier for the payment. It's generated by iDEAL and provided in two ways: as the content of a QR code or as a query parameter during a redirect. | The following example shows a request for retrieving transaction information. **Retrieve transaction information** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/payments/details' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ADYEN-API-KEY' \ --data '{ "method": "ideal", "source": "redirect", "payload": "https://ext.tx.ideal.nl/2/A7AFBMA3QHGB5HFNU7SAGEBYFYI?sig=BGBCQEIAE3ECSXSQQMPPFFSG3YNHOS2WOHG7IP67A3LNOGIRN2JIPD455NABCCAGZZSV5OJMARVPO3TIDDU63USPSKU7VRKOKA6VQK2BTXOGJRAY5QM" }' ``` 2. In the response, note the `token` and other transaction details. You will need this `token` in the [confirm a payment](#initiate-sca-payment-confirmation) or [cancel a payment](#cancel-a-payment) step. The response also contains the specific details of the transaction. See the details in the following fields: | Parameter | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token` | A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent `/payments/confirm` or `/payments/cancel` endpoint requests. | | `value` | The numerical value of the amount. | | `currency` | Currency of a monetary amount. | | `counterparty` | An object containing information about the counterparty that will receive the funds. | | `counterparty.accountHolder` | Details about the account holder who will receive the funds. | | `fullName` | The full name of the `counterparty`'s account holder. | | `type` | The type of account identification. | | `iban` | The IBAN of the bank account. | | `description` | A description of the transaction. | | `expiresAt` | The timestamp when the transaction token expires. | **Response** ```json { "token": "eyJ0b2tlbiI6InNvbWVUb2tlbiJ9", "details": { "amount": { "value": 10, "currency": "EUR" }, "counterparty": { "accountHolder": { "fullName": "The Dutch CookieShop Company N.V." }, "accountIdentification": { "type": "iban", "iban": "NL44RABO0123456789" } }, "description": "26d1f6ca-a55a-4923-b189-e9558b4fb7cd", "expiresAt": "2026-04-17T15:36:22.77Z" } } ``` If you encounter any errors, see [error codes and messages](#error-codes-and-messages). ## Check SCA eligibility Before confirming the payment, first check device eligibility. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript. ### Tab: Android (Kotlin) To check if the Android device is eligible for SCA: 1. Initiate the `AdyenAuthentication` class in your Activity or Fragment. **Initiate authentication** ```kotlin private lateinit var adyenAuthentication: AdyenAuthentication override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) adyenAuthentication = AdyenAuthentication(this) } ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```kotlin lifecycleScope.launch { val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability() if (availabilityResult is AvailabilityResult.Available) { availabilityResult.sdkOutput } } ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: iOS (Swift) To check if the iOS device is eligible for SCA: 1. Initialize the `AuthenticationService` class. **Initialize authentication service** ```swift let configuration = AuthenticationService.Configuration( localizedRegistrationReason: registrationReason, localizedAuthenticationReason: authenticationReason, appleTeamIdendtifier: appleTeamIdentifier ) let authenticationService = AuthenticationService(configuration: configuration) ``` 2. Check if SCA is available on the device. **Check SCA eligibility** ```swift let sdkOutput = try authenticationService.checkSupport() /// send the sdkOutput to your backend ``` The function returns an `sdkOutput`. 3. Pass the `sdkOutput` to your server. ### Tab: Web (JavaScript) To check if the web browser on your web-enabled device is eligible for SCA: 1. Import the node package in your application. `RelyingPartyName` is the name the user will be presented with when creating or validating a `WebAuthn` operation. We recommend that the value of the `RelyingPartyName` be the merchant name or the URL domain. **Import web sdk and initiate authentication** ```javascript import ScaWebauthn from '@adyen/bpscaweb'; const scaWebauthn = ScaWebauthn.create({ relyingPartyName: 'merchant', }); const sdkOutput = await scaWebauthn.checkAvailability().catch((error) => /* SCA_UNAVAILABLE error*/); ``` If the user's browser supports SCA, the function returns `sdkOutput` to exchange in requests to the server. If SCA is not supported, the method throws an `SCA_UNAVAILABLE` error. 2. Pass the `sdkOutput` to your server. You will use the `sdkOutput` when [confirming the payment](#initiate-sca-payment-confirmation). ## Initiate SCA payment confirmation Confirm a payment using the `token` that you obtained when you [retrieved the payment information](#retrieve-payment-information). The operation is secured by Strong Customer Authentication (SCA). You must complete the second `/payments/confirm` request within 10 minutes of the initial request in order to complete authentication. 1. Make an initial POST `/payments/confirm` request specifying the following parameters: | Parameter | Location | Required | Description | | ------------------ | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **A2APayment**. `auth-param1`: Value of **sdkOutput** from the [Check SCA eligibility](#check-sca-eligibility) step. | | `token` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent `/payments/confirm` or `/payments/cancel` endpoint requests. | | `balanceAccountId` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Balance account ID of the account where the funds should be substracted. For example, `BA00000000000000000000000`. | **Confirm a payment - initial request** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/payments/confirm' \ --header 'WWW-Authenticate: SCA realm="A2APayment" auth-param1="eyJkZXZpY2UiOiJpT1MiLCJAdHlwZSI6ImNvbS5hZHllbi53ZWJhdXRobi5lbnRpdGllcy5BdXRoZW50aWNhdGlvbkFwcERhdGEifQ=="' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ADYEN-API-KEY' \ --data '{ "token":"BQABAQA2th6I0RbAQLWVNC9Q2bycAGxVf11/HT9pDXPpvVX1QwjYdvOAGLUj4lE0b9LEXLYUJ14zRzr+ETknWhWZ1Y7RF3L6ckElVX+CmQ8mYI9cJ7ADvqiLDMV2daxtmsAeT7BjV7GwX1rwGPsY6FXeEI9MH6PI6nSklPbbsA8adF8Y1EUJqeXWMqWDW+ddqDylfWF8uy5zQPBsRsU64zsP+COeWxJEpYSodPIGTSbpACi8+81Xx5sTBROpnNrslnQBlUEFk9hlnCc3XE5ZMTEyor3XVzjfgjsKEHN9PzewMo7dC+loHL5FEk0r5iYZJoPwT47+Vsj8FFLAA//ywhuDjT8GDMfFb3X5pwXSMPtsEgAAnEnm+6Y/LClpYZ/CBNW1JE1h6LWYvUn+V3zueak/Qwk0EcJWDo5kC0QSRhaP+LeRgWwOMCpVGx6hD/tfa4EM3Q4uwoo7+4jiuw7BdPkvFyljYtV6UJqbZguCmYMSJQ09hXVvc8L3gz+PvL3xP6berp8oiKMmC5NjzfQdbdLA9u/0pyOIbmkx9LGr3wVRgZqsfx9Bp3H/mqZOA4JdrKEL8iA/yamOWxlYdwj0SpDZWPjvJoyBPxIIq3YgLuAHSBwU0lHgPEyXHJUrh6SCVA==", "balanceAccountId": "BA32272223222K5JF79DL53KQ" }' ``` 2. The API returns a `HTTP 401 - Unauthorized response` with the message "User needs to perform SCA." The response headers include the following parameters: | Parameter | Description | | ------------------ | ---------------------------------------------------------------------------------- | | `WWW-Authenticate` | The header containing the SCA challenge. | | `auth-param1` | An attribute within the `WWW-Authenticate` header that holds the `sdkInput` value. | | `sdkInput` | The SCA challenge that you must pass to the user's device for authentication. | Here is an example of the response header: **Response header** ```json "WWW-Authenticate: SCA realm="A2APayment" auth-param1="eyJ2YWx1ZSI6InNvbWUgb3BhcXVlIGpzb24gd2l0aCB0aGUgU0NBIGNoYWxsZW5nZSJ9"" ``` 3. Pass `auth-param1` to the SDK as `sdkInput`. ## Authenticate user To authenticate your user with the Authentication SDK: 1. Trigger the SDK to start user authentication and pass the `auth-param1` value from [the previous step](#initiate-sca-payment-confirmation) as `sdkInput`. ### Tab: Android (Kotlin) **Authenticate with SCA SDK** ```kotlin lifecycleScope.launch { if (adyenAuthentication.hasCredential("sdkInput")) { // Authenticate existing credential val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput") when (authenticationResult) { is AuthenticationResult.AuthenticationSuccessful -> { authenticationResult.sdkOutput } is AuthenticationResult.Canceled -> { // User cancelled the authentication flow } is AuthenticationResult.Error -> { // Unexpected error authenticationResult.errorMessage } is AuthenticationResult.AuthenticationError -> { // FIDO API Error authenticationResult.authenticationError } } } else { // None of the existing credentials exist in this device } } ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. ### Tab: iOS (Swift) **Authenticate with SCA SDK** ```swift delegatedAuthenticationSession.authenticate(withBase64URLString: sdkInput) { [weak self] result in switch result { case let .success(sdkOutput): /// send the sdkOutput to the backend case let .failure(error): /// authentication failed } } ``` The SDK uses the [Apple DeviceCheck framework](https://developer.apple.com/documentation/devicecheck) to generate a Base64-encoded `sdkOutput` data blob. To do this, the SDK authenticates the user using Touch ID, Face ID, or the device passcode. To enable Face ID support, add `NSFaceIDUsageDescription` to `Info.plist`. ### Tab: Web (JavaScript) **Authenticate with SCA SDK** ```javascript const sdkOutput = await scaWebauthn.authenticate(sdkInput); ``` If successful, the SDK generates a Base64-encoded `sdkOutput` data blob. 2. Pass `sdkOutput` to your server. You will use the sdkOutput when [completing the payment confirmation](#complete-sca-payment-confirmation). ## Complete SCA payment confirmation After completing the SCA challenge, you can finalize the payment by sending a POST request to the `/payments/confirm` endpoint. This request submits the `sdkOutput` from the solved challenge confirming the transaction. 1. Make a second POST `/payments/confirm` request specifying the following parameters: | Parameter | Location | Required | Description | | ------------------ | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WWW-Authenticate` | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **A2APayment**. `auth-param1`: Value of **sdkOutput** from the [Authenticate user](#authenticate-user) step. | | `token` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent `/payments/confirm` or `/payments/cancel` endpoint requests. | | `balanceAccountId` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Balance account ID of the account where the funds should be substracted. For example, `BA00000000000000000000000`. | **Confirm a payment - final request** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/payments/confirm' \ --header 'WWW-Authenticate: SCA realm="A2APayment" auth-param1="eyJhc3NlcnRpb25PYmplY3QiOiJ2Mmx6YVdkdVlYUjFjbVZZUnpCRkFpQnJsWTlqUHBraWI3OG1hd2RRUDdKei9oSlI4QWVCYnVsQzBHNExTcStrTGdJaEFNWEF5anVlbDJPQ1JQZ1lybktZbklwZS9STkJ3dFRTV2dXOGd0c0I5S1pIY1dGMWRHaGxiblJwWTJGMGIzSkVZWFJoV0NVZ1cwOTd6b2lidDNTK3VVcm5iWHZROW82VlhFOWR0amdVTVpCMUtkZDFJVVVBQUFBQS93PT0iLCJjcmVkZW50aWFsSWQiOiJUZGwyOEZaY3lhblBuRVJHRkFmSytUcGJoc2tWSnh6YzFDZys3Tzd2aDRBPSIsInJwSWQiOiJCMk5ZU1M1OTMyLmNvbS5hZHllbi5BZHllbjNEUzJEZW1vIiwicHNwUmVmZXJlbmNlIjoiQlNDUjQyOTY4MjIzMjIzUDVNVDdCNTM1TTM0RlBUX18wMC0yM2ViYTgzN2Y5ZDM2OGE3OWU4ODBmM2JlNGQxNTAzZC00YWI1MWE0ZGNmYjc0NzM1LTAxIiwidHJhY2luZyI6IjAwLTIzZWJhODM3ZjlkMzY4YTc5ZTg4MGYzYmU0ZDE1MDNkLTRhYjUxYTRkY2ZiNzQ3MzUtMDEiLCJkZXZpY2UiOiJpT1MifQ=="' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ADYEN-API-KEY' \ --data '{ "token":"BQABAQA2th6I0RbAQLWVNC9Q2bycAGxVf11/HT9pDXPpvVX1QwjYdvOAGLUj4lE0b9LEXLYUJ14zRzr+ETknWhWZ1Y7RF3L6ckElVX+CmQ8mYI9cJ7ADvqiLDMV2daxtmsAeT7BjV7GwX1rwGPsY6FXeEI9MH6PI6nSklPbbsA8adF8Y1EUJqeXWMqWDW+ddqDylfWF8uy5zQPBsRsU64zsP+COeWxJEpYSodPIGTSbpACi8+81Xx5sTBROpnNrslnQBlUEFk9hlnCc3XE5ZMTEyor3XVzjfgjsKEHN9PzewMo7dC+loHL5FEk0r5iYZJoPwT47+Vsj8FFLAA//ywhuDjT8GDMfFb3X5pwXSMPtsEgAAnEnm+6Y/LClpYZ/CBNW1JE1h6LWYvUn+V3zueak/Qwk0EcJWDo5kC0QSRhaP+LeRgWwOMCpVGx6hD/tfa4EM3Q4uwoo7+4jiuw7BdPkvFyljYtV6UJqbZguCmYMSJQ09hXVvc8L3gz+PvL3xP6berp8oiKMmC5NjzfQdbdLA9u/0pyOIbmkx9LGr3wVRgZqsfx9Bp3H/mqZOA4JdrKEL8iA/yamOWxlYdwj0SpDZWPjvJoyBPxIIq3YgLuAHSBwU0lHgPEyXHJUrh6SCVA==", "balanceAccountId": "BA32272223222K5JF79DL53KQ" }' ``` 2. Verify that the response contains a `success` object indicating the transaction was successful, which contains the related links. See the details in the following fields: | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `links` | An object containing one or more links related to the next steps in the payment flow. | | `success` | An object containing the URL that the user should be redirected to in order to complete the "success" path of the payment confirmation. | | `href` | The URL string to which the user should be redirected. | **Response** ```json { "links": { "success": { "href": "https://checkoutshopper-test.adyen.com/checkoutshopper/checkoutPaymentReturn?gpid=GPEB06E7D8AC9D9AB5&pspEchoData=ZLLRBHX6KWMWSD75%3A821204%3Aj7igk8cQHA5rQ1fetWe8Yyn0%2BOc%3D" } } } ``` For QR code flows initiated on a desktop computer, do not redirect the user from the mobile app back to the platform. The desktop browser automatically detects the completed payment and handles the redirection to the checkout page. If you encounter any errors, see [error codes and messages](#error-codes-and-messages). ## Cancel a payment Use the `/payments/cancel` endpoint to cancel a pending payment that has not yet expired or been confirmed. A payment is considered canceled when the `redirectUrl` in the API response is opened. 1. Make a POST `/payments/cancel` request specifying the following parameters: | Parameter | Location | Required | Description | | --------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token` | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A unique, short-lived identifier for a pending transaction. Its validity period depends on the payment provider; for iDEAL, it's typically around 15 minutes. It is used to reference the specific payment in subsequent `/payments/confirm` or `/payments/cancel` endpoint requests. | **Cancel a payment** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/payments/cancel' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ADYEN-API-KEY' \ --data '{ "token":"BQABAQA2th6I0RbAQLWVNC9Q2bycAGxVf11/HT9pDXPpvVX1QwjYdvOAGLUj4lE0b9LEXLYUJ14zRzr+ETknWhWZ1Y7RF3L6ckElVX+CmQ8mYI9cJ7ADvqiLDMV2daxtmsAeT7BjV7GwX1rwGPsY6FXeEI9MH6PI6nSklPbbsA8adF8Y1EUJqeXWMqWDW+ddqDylfWF8uy5zQPBsRsU64zsP+COeWxJEpYSodPIGTSbpACi8+81Xx5sTBROpnNrslnQBlUEFk9hlnCc3XE5ZMTEyor3XVzjfgjsKEHN9PzewMo7dC+loHL5FEk0r5iYZJoPwT47+Vsj8FFLAA//ywhuDjT8GDMfFb3X5pwXSMPtsEgAAnEnm+6Y/LClpYZ/CBNW1JE1h6LWYvUn+V3zueak/Qwk0EcJWDo5kC0QSRhaP+LeRgWwOMCpVGx6hD/tfa4EM3Q4uwoo7+4jiuw7BdPkvFyljYtV6UJqbZguCmYMSJQ09hXVvc8L3gz+PvL3xP6berp8oiKMmC5NjzfQdbdLA9u/0pyOIbmkx9LGr3wVRgZqsfx9Bp3H/mqZOA4JdrKEL8iA/yamOWxlYdwj0SpDZWPjvJoyBPxIIq3YgLuAHSBwU0lHgPEyXHJUrh6SCVA==" }' ``` 2. The response for a successful cancellation contains a `links` object. This object has a `cancel` field, which includes a `href` property that specifies a redirect URL. See the details in the following fields: | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `links` | An object containing one or more links related to the next steps in the payment flow. | | `cancel` | An object containing the URL that the user should be redirected to in order to complete the "cancel" path of the payment. | | `href` | The URL string to which the user should be redirected. | **Response** ```json { "links": { "cancel": { "href": "https://ext.pay.ideal.nl/transactions/HTTPS%3A%2F%2FEXT.TX.IDEAL.NL%2F2%2FA2JXWE33UOOXZXPMJBMV46AR7U4/cancellation-and-merchant-redirection?sig=BGBCAEIDYUXOMFC3ETVAYBKLQYCELNFFXJXYP5HI6CR7VNFEKDPYH6K7XMQBCA3WTS2IIH5UT7C5BQDIMLDO4CANJ2YY3VEE422LUFUNIQRGLDGZU" } } } ``` If you encounter any errors, see [error codes and messages](#error-codes-and-messages). ## Payment screen requirements All screens related to the iDEAL flow (payment, profile, and authentication) must comply with iDEAL's UX and regulatory standards. To comply with these standards, your screens must display the following: * **iDEAL/WERO logo**: show the iDEAL logo clearly on all screens to indicate the transaction is using iDEAL as the payment method. * **Amount and currency**: the full payment amount and currency. * **Payee (recipient)**: clearly identify who is recieving the payment. * **Payment description**: include a brief, user-friendly description of the transaction. * **Account switch option**: let users switch balance accounts if needed. * **Confirmation screen with result**: For example, in case of success, display a confirmation screen should display with all the transaction details again. These details must include the selected bank account (in IBAN format), the iDEAL payment method, amount and currency, and description. ### Design Adyen requires early access to the wireframes for the iDEAL flow screens within your app or web application. Share these with your Adyen contact as soon as they are available and before you go live, so that they can be validated and you can be informed of any necessary changes early in your development process. ## iDEAL profile endpoints As an optional feature, you can allow users to create and manage their iDEAL profiles. This lets them securely store payment and delivery information, enabling them to make future payments with a single click. These endpoints are not required for standard iDEAL payment processing but provide a way to interact with the profile management features, offering a faster and more convenient checkout experience for your users. For more details, see the [iDEAL Profile FAQ](https://ideal.nl/en/products/faq-ideal-profiel). ### Create an iDEAL profile To create a new iDEAL profile: 1. Make a POST `/ideal/profile/register` request specifying the following parameters: | Parameter | Required | Description | | ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `accountHolderId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier for an account holder. | | `paymentInstrumentIds` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The IDs for the payment instruments to be associated with the iDEAL profile. | **Create a new profile** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/ideal/profile/register' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data '{ "accountHolderId": "AH00000000000000000000001", "paymentInstrumentIds": ["PI00000000000000000000001", "PI00000000000000000000002"] }' ``` 2. The response includes a `redirectUrl` object with `href` property. This `href` specifies a redirect URL. See the details in the following fields: | Parameter | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirectUrl` | A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response. | | `href` | The URL string to which the user should be redirected. | **Response** ```json { "redirectUrl": { "href": "https://ext.profile.ideal.nl/session/eyJraWQiOiJpcHIxIiwidHlwIjoiSldUIiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJQUk9GSUxFOnpEU0JyMmlxVjVjekxyb3BuaUNZVDRUVVRaeVpGM21vIiwic3ViX2luZm8iOiJBRFlCTkwyQSIsImV4cCI6MTc1NTg1OTEzOCwicmVzb3VyY2UiOiJQQUdFOlBST0ZJTEVfUkVHSVNUUkFUSU9OX1BBR0VfVjIiLCJqdGkiOiJjODBhYTA3MS0zMzMwLTRkNTctYWNmMy0xNjkxMDk0ZTE1MjMifQ.XYL8uGHe6yRVL1AMxzH-BhecY3W2nuJZa6-bnc-WjQ8So8PCMm7NQ2_cWGvLa8hkiEiT66Nq_pRKpZL-aJgAiA" } } ``` 3. Select the `href` URL and follow the steps to create your iDEAL profile. ### Generate a profile management URL The iDEAL profile management page allows your users to edit their iDEAL profile. For example, they can manage personal details, linked accounts, and delivery addresses, or view trusted webshops. They can also use this page to delete their profile entirely. To generate a URL for your user's iDEAL profile management page: 1. Make a POST `/ideal/profile/auth-link` request specifying the following parameters: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- | | `accountHolderId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier for an account holder. | **Generate a profile management URL** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/ideal/profile/auth-link' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data '{ "accountHolderId": "AH00000000000000000000001" }' ``` 2. The response includes a `redirectUrl` object with `href` property. This `href` specifies a redirect URL. See the details in the following fields: | Parameter | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirectUrl` | A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response. | | `href` | The URL string to which the user should be redirected. | **Response** ```json { "redirectUrl": { "href": "https://ext.profile.ideal.nl/session/eyJraWQiOiJpcHIxIiwidHlwIjoiSldUIiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJQUk9GSUxFOkI2NDR6Z0RzalU5bWNaWmdwaE53Y3JLeXRmMDh5aVZHIiwic3ViX2luZm8iOiJBRFlCTkwyQSIsImV4cCI6MTc1NTg1ODk0NSwicmVzb3VyY2UiOiJQQUdFOlBST0ZJTEVfTUFOQUdFTUVOVF9QQUdFIiwianRpIjoiOWQyYmM4YTItZmZjMS00NzkyLTljNTQtNmEzNGQ1NzAyNGU2In0.b6jvGX0IXtMMe3Vjn3cCVSkikTKeZzEBsaG-7_ZG9xqvFANS4_IulZ57vR-6Lvd1fZ8PCTHOw1-ZH2gtsmHfZQ" } } ``` ### Authenticate To generate a URL after a user has been authenticated, typically via Multi-Factor Authentication (MFA) use the `/ideal/profile/authenticate` endpoint. This is used for actions such as changing profile details or to unmask sensitive payment information. 1. Make a POST `/ideal/profile/authenticate` request specifying the following parameters: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accountHolderId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier for an account holder. | | `payload` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A payload initiated by iDEAL to complete the authentication process. It's generated by iDEAL and provided in two ways: as the content of a QR code or as a query parameter during a redirect. | **Create a new profile** ```bash curl --location --request POST 'https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1/ideal/profile/authenticate' \ --header 'Content-Type: application/json' \ --header 'x-api-key: {ADYEN_API_KEY}' \ --data '{ "accountHolderId": "AH00000000000000000000001", "payload": "https://AU.IDEAL.NL/2/RECOGNIZE_PROFILE_BY_CIT/I45ECVKSKI4TANRUIRCFIMSXGFJFOORVJNFEMQ2VIRATUMJXGU2DQOJYGY4TS?sig=BGBDAEIIAUVQ5SYITU4JVDF3URUJ6AQSHXYDDBRLEP3EN5DFNK3TPDHFA75XQEIIAYMT7AZMHUDZKRNQS4OMSRCJ5NOCX4JG2GFN5U44AIC6EADUOEDFA" }' ``` 2. The response includes a `redirectUrl` object with `href` property. This `href` specifies a redirect URL. See the details in the following fields: | Parameter | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `redirectUrl` | A short-lived URL that redirects the user to the iDEAL profile registration page. You must redirect the user to this URL within 5 seconds of receiving the response. | | `href` | The URL string to which the user should be redirected. | **Response** ```json { "redirectUrl": { "href": "https://ext.profile.ideal.nl/auth/session/eyJraWQiOiJpcGEtZXh0IiwidHlwIjoiSldUIiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJTRVNTSU9OX1BBR0U6Tk9ORSIsImV4cCI6MTc1NTg1OTE0OCwicmVzb3VyY2UiOiJBVVRIX1JFUVVFU1Q6SFRUUFM6Ly9BVS5JREVBTC5OTC8yL1JFQ09HTklaRV9QUk9GSUxFX0JZX0NJVC9JNDVFNE1aWkpSRlVFVVNOSlU0VlVTMlFHNU5GTU9TWUpWS1RBVFNMS0kyVFVNSlhHVTJUUU5KWkdNM1RHIiwianRpIjoiODY0MDEwOWEtOGEyMS00OWEwLWE0YTUtZTlmNmJiMDdjYzdhIiwiYXV0aG9yaXRpZXMiOlsiU0VUVVBfUFJPRklMRV9BVVRIX0NPT0tJRSJdfQ.dM8DM1RUaa0o9rdvOyBLi2S1y1-nDOXlUdGUgIbPH0AJUrMI9Lnc4Cmz1_30NcwN0cJzlWyX5l_ni3NmFrLBfg" } } ``` ## Error codes and messages These are the common error codes. See the descriptions below for details. #### A2A payment errors | Error code | HTTP status | Description | | ---------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1069_003` | 400 Bad Request | The received token is invalid, malformed, or expired. | | `1069_010` | 400 Bad Request | The received payload is invalid, malformed, or expired. | | `1069_004` | 422 Unprocessable Entity | Payment has expired and is no longer available. | | `1069_005` | 422 Unprocessable Entity | The payment has been locked by another request and can no longer be processed. This may happen if the payment has already been confirmed, canceled, or is currently being processed by another simultaneous request. | | `1069_006` | 422 Unprocessable Entity | An unprocessable error occurred related to iDEAL. | | `1069_002` | 500 Internal Server Error | An unexpected error occurred related to iDEAL. | | `1069_001` | 500 Internal Server Error | A generic server-side error occurred. | #### iDEAL profile errors | Error code | HTTP status | Description | | ---------- | ------------------------ | ---------------------------------------------------------------- | | `1069_007` | 422 Unprocessable Entity | The provided account already has a registered iDEAL profile. | | `1069_008` | 422 Unprocessable Entity | The provided account does not have a registered iDEAL profile. | | `1069_009` | 422 Unprocessable Entity | The authenticate payload has expired and is no longer available. | ## See also * [Track transactions](/business-accounts/transactions) --- # Source: https://docs.adyen.com/business-accounts/send-funds/approve-cancel-transfers.md Section: Business accounts Title: Approve or cancel transfers Description: Allow members of your team to approve or cancel transfers before Adyen processes them. --- title: "Approve or cancel transfers" description: "Allow members of your team to approve or cancel transfers before Adyen processes them." url: "https://docs.adyen.com/business-accounts/send-funds/approve-cancel-transfers" source_url: "https://docs.adyen.com/business-accounts/send-funds/approve-cancel-transfers.md" canonical: "https://docs.adyen.com/business-accounts/send-funds/approve-cancel-transfers" last_modified: "2020-09-11T17:20:00+02:00" language: "en" --- # Approve or cancel transfers Allow members of your team to approve or cancel transfers before Adyen processes them. [View source](/business-accounts/send-funds/approve-cancel-transfers.md) To decrease the risk of unintentional or malicious transfers in your balance platform, you can trigger additional reviews for transfers. Additional reviews require a member of your team to verify a transfer before Adyen processes it. You decide which members of your team are allowed to review transfers by assigning them the [required API role](#requirements) in your [Customer Area](https://ca-test.adyen.com/). To complete the review, the reviewer must either approve or cancel the transfer. If the transfer is approved, then Adyen continues processing the transfer. ## Requirements Before you begin, take into account the following requirements. | Requirement | Description | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | **[API credential roles](/business-accounts/manage-access/api-credentials-web-service)** | Make sure that your web service API key has the following role:- **TransferService Approval role** | | **[Webhooks](/development-resources/webhooks/configure-and-manage)** | Subscribe to the following webhook:- [**Transfer Webhooks**](/platforms/webhook-types/#transfer-webhooks) | ## How it works The following diagram shows the approval flow for a transfer when you trigger an additional review. ![](/user/pages/reuse/pfs-transfers/approve-cancel-transfers/approval-flow/approval-flow-diagram.svg?decoding=auto\&fetchpriority=auto) As shown in the previous diagram, the approval flow is the following: 1. You [trigger an additional review](/business-accounts/send-funds/make-transfer-request#trigger-additional-reviews) by including the [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review) object in a POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request. 2. The transfer request is pending approval until a member of your team completes the review. 3. Depending on the decision of the reviewer, one of the following happens: * If the reviewer approves the transfer, then the transfer is authorized and Adyen continues processing the request. * If the reviewer cancels the transfer, then the transfer fails and Adyen can no longer processes the request. * If the reviewer takes no action within 30 days after initiating the transfer request, then the transfer fails and Adyen can no longer processes the request. A reviewer can approve or cancel multiple transfers at the same time. The following sections explain how make API requests to approve or cancel transfers. ## Approve transfers To approve initiated transfers, make a POST  [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) request, specifying the following parameter: | **Parameter name** | **Type** | **Required** | **Description** | | -------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [transferIds](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve#request-transferIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array containing the unique identifiers of the transfers that you decide to approve. You can include one or more `transferIds` in the request, up to a maximum of 500. | The following code sample shows how to make a POST `/transfers/approve` request with two `transferIds`. **Approve transfers** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/approve \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest() .transferIds(Arrays.asList("APUFHASUFD4AS", "407ASFPUHASFA")); // Send the request TransfersApi service = new TransfersApi(client); service.approveInitiatedTransfers(approveTransfersRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $approveTransfersRequest = new ApproveTransfersRequest(); $approveTransfersRequest ->setTransferIds(array("APUFHASUFD4AS", "407ASFPUHASFA")); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $service->approveInitiatedTransfers($approveTransfersRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) ApproveTransfersRequest approveTransfersRequest = new ApproveTransfersRequest { TransferIds = { "APUFHASUFD4AS", "407ASFPUHASFA" } }; // Send the request var service = new TransfersService(client); service.ApproveInitiatedTransfers(approveTransfersRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest = { transferIds: [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) approveTransfersRequest := transfers.ApproveTransfersRequest{ TransferIds: []string{ "APUFHASUFD4AS", "407ASFPUHASFA", }, } // Send the request service := client.Transfers() req := service.TransfersApi.ApproveInitiatedTransfersInput().IdempotencyKey("UUID").ApproveTransfersRequest(approveTransfersRequest) service.TransfersApi.ApproveInitiatedTransfers(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :transferIds => [ 'APUFHASUFD4AS', '407ASFPUHASFA' ] } # Send the request adyen.transfers.transfers_api.approve_initiated_transfers(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const approveTransfersRequest: Types.transfers.ApproveTransfersRequest = { transferIds: ["APUFHASUFD4AS", "407ASFPUHASFA"] }; // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.approveInitiatedTransfers(approveTransfersRequest, { idempotencyKey: "UUID" }); ``` If the request is successful, you receive an **HTTP 200 OK** response. ### Strong Customer Authentication (SCA) for approving transfers If a transfer requires [SCA](/business-accounts/sca-for-funds-transfers), you must do one of the following: * Authenticate the user when initiating a transfer request. * Authenticate the reviewer when approving a transfer request. Because a reviewer can approve multiple transfers at the same time, performing SCA during approval allows you to satisfy the authentication requirements for multiple transfers with a single SCA process. To [trigger SCA during approval](/business-accounts/send-funds/make-transfer-request#trigger-additional-reviews), you must set [scaOnApproval](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review-scaOnApproval) to **true** in the POST  [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request. ## Cancel transfers To cancel an initiated transfer, make a POST  [/transfers/cancel](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/cancel) request, specifying the following parameter: | **Parameter name** | **Type** | **Required** | **Description** | | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [transferIds](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/cancel#request-transferIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array containing the unique identifiers of the transfers that you decide to cancel. You can include one or more `transferIds` in the request, up to a maximum of 500. | The following code sample shows how to make a POST `/transfers/cancel` request with two `transferIds`. **Cancel transfers** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/cancel \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) CancelTransfersRequest cancelTransfersRequest = new CancelTransfersRequest() .transferIds(Arrays.asList("APUFHASUFD4AS", "407ASFPUHASFA")); // Send the request TransfersApi service = new TransfersApi(client); service.cancelInitiatedTransfers(cancelTransfersRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $cancelTransfersRequest = new CancelTransfersRequest(); $cancelTransfersRequest ->setTransferIds(array("APUFHASUFD4AS", "407ASFPUHASFA")); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $service->cancelInitiatedTransfers($cancelTransfersRequest, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) CancelTransfersRequest cancelTransfersRequest = new CancelTransfersRequest { TransferIds = { "APUFHASUFD4AS", "407ASFPUHASFA" } }; // Send the request var service = new TransfersService(client); service.CancelInitiatedTransfers(cancelTransfersRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const cancelTransfersRequest = { transferIds: [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.cancelInitiatedTransfers(cancelTransfersRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) cancelTransfersRequest := transfers.CancelTransfersRequest{ TransferIds: []string{ "APUFHASUFD4AS", "407ASFPUHASFA", }, } // Send the request service := client.Transfers() req := service.TransfersApi.CancelInitiatedTransfersInput().IdempotencyKey("UUID").CancelTransfersRequest(cancelTransfersRequest) service.TransfersApi.CancelInitiatedTransfers(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "transferIds": [ "APUFHASUFD4AS", "407ASFPUHASFA" ] } # Send the request adyen.transfers.transfers_api.cancel_initiated_transfers(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :transferIds => [ 'APUFHASUFD4AS', '407ASFPUHASFA' ] } # Send the request adyen.transfers.transfers_api.cancel_initiated_transfers(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const cancelTransfersRequest: Types.transfers.CancelTransfersRequest = { transferIds: ["APUFHASUFD4AS", "407ASFPUHASFA"] }; // Send the request const transfersAPI = new TransfersAPI(client); transfersAPI.TransfersApi.cancelInitiatedTransfers(cancelTransfersRequest, { idempotencyKey: "UUID" }); ``` If the request is successful, you receive an **HTTP 200 OK** response. ## Get status updates on transfer reviews For every transfer request, Adyen sends multiple [webhooks](/business-accounts/third-party-transfer-webhooks) to your server. Webhooks inform you about any status change in the transfers, including the approval status. During the approval flow, you receive webhooks for the following events: * The transfer is initiated and requires an additional review. * The transfer is canceled. * The transfer expires after 30 days because the review was not completed. Adyen uses two types of webhooks to inform you about the approval status of a transfer: * [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created), which informs your server that a transfer was initiated in your balance platform. * [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated), which informs your server of changes in the status of the transfer. The following tabs explain how you can identify updates related to the approval status of a transfer. ### Tab: Additional review required Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook to inform your server that a transfer was initiated in your balance platform. You can identify if the transfer requires approval by noting the following values: | Parameter | Description | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------ | | [status](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-status) | Specifies the status of the transfer. | **received** | | [reason](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-reason) | Provides more information about the status of the transfer. | **pending** | | [review.numberOfApprovalsRequired](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-review-numberOfApprovalsRequired) | Specifies the number of approvals required to continue processing the transfer. | **1** | The following example shows a webhook that you would receive when an initiated transfer requires approval. **Webhook for an initiated transfer that requires review** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": -10000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bankTransfer" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" } ], "id": "6JKRLZ8LOT47J7RY", "reason": "pending", "reference": "Your user reference for the transfer", "review": { "numberOfApprovalsRequired": 1 }, "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 1, "status": "received", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ### Tab: Transfer approved Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook to inform your server that a pending transfer was approved. You can identify an approved transfer by noting the following values: | Parameter | Description | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------- | | [status](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-status) | Specifies the status of the transfer. | **authorised** | | [reason](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-reason) | Provides more information about the status of the transfer. | **approved** | | [review.numberOfApprovalsRequired](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-review-numberOfApprovalsRequired) | Specifies the number of approvals required to continue processing the transfer. | **1** | The following example shows a webhook that you would receive for an approved transfer. **Webhook for an approved transfer** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 0, "reserved": -10000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bankTransfer" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" } ], "id": "6JKRLZ8LOT47J7RY", "reason": "approved", "review": { "numberOfApprovalsRequired": 1 }, "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 2, "status": "authorised", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Transfer canceled Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook to inform your server that a pending transfer was canceled. You can identify a canceled transfer by noting the following values: | Parameter | Description | Value | | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------- | | [status](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-status) | Specifies the status of the transfer. | **cancelled** | | [reason](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-reason) | Provides more information about the status of the transfer. | **unknown** | The following example shows a webhook that you would receive for a canceled transfer. **Webhook for a canceled transfer** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": -10000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bankTransfer" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000 } ], "reason": "unknown", "status": "cancelled", "type": "accounting" } ], "id": "6JKRLZ8LOT47J7RY", "reason": "unknown", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 2, "status": "cancelled", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ## See also * [Trigger additional reviews for bank transfers](/business-accounts/send-funds/make-transfer-request#trigger-additional-reviews) * [Perform SCA during approval](/business-accounts/sca-for-funds-transfers?tab=initiate-sca-approval_2#initiate-transfer) --- # Source: https://docs.adyen.com/business-accounts/send-funds/make-transfer-request.md Section: Business accounts Title: Make a transfer request Description: Learn how to send funds to third parties using an Adyen business account. --- title: "Make a transfer request" description: "Learn how to send funds to third parties using an Adyen business account." url: "https://docs.adyen.com/business-accounts/send-funds/make-transfer-request" source_url: "https://docs.adyen.com/business-accounts/send-funds/make-transfer-request.md" canonical: "https://docs.adyen.com/business-accounts/send-funds/make-transfer-request" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Make a transfer request Learn how to send funds to third parties using an Adyen business account. [View source](/business-accounts/send-funds/make-transfer-request.md) When sending funds to third-party bank accounts, the required bank account details depend on the [bank identification type](/business-accounts/send-funds#bank-account-identification-types). There are also additional required fields if you are doing a [cross-border transfer](/business-accounts/send-funds#cross-border). Additionally, you can [validate the third-party bank account](#validate-a-third-party-bank-account) before sending funds to avoid failed transfers due to incorrect details. ## Requirements | Requirement | Description | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Adyen business accounts | | **API credential roles** | Make sure that your API credential has the [roles](/business-accounts/manage-access#manage-api-credentials) to use the [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview). | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- **[Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview)** - **[Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview)** | | **[Capabilities](/business-accounts/verification-overview/capabilities/#business-account-capabilities)** | Make sure that the user has the following capability allowed and enabled:- **sendToThirdParty** | | **Limitations** | Currently, Adyen only supports sending funds to third-party bank accounts. In the future, you will be able to send to third-party wallets and cards. | | **Setup steps** | * Reach out to your Adyen contact to: * Make sure you have the roles and capabilities necessary to send funds to a third-party bank account. * Enable transfers for the source balance account. * (Recommended) Get transfer routes before transferring to a new counterparty. * (Recommended) Validate the counterparty's bank account. | ## Get transfer routes Prior to submitting a transfer request, we recommend that you [calculate the available transfer routes](/business-accounts/send-funds/transfer-routes). This will enable you to design a configuration that optimally aligns with your use case. Furthermore, it minimizes the risk of transfer failures by proactively identifying supported routes and highlighting any necessary parameters. ## Validate a third-party bank account Before sending funds to a third-party bank account, you can validate this bank account to avoid failed transfers due to incorrect details. To validate a third-party bank account, make a POST `/validateBankAccountIdentification` request specifying the following information, depending on the [bank account identification type](/business-accounts/send-funds#bank-account-identification-types): | Parameter | Description | | ----------------------- | ------------------------------------------------------------------ | | `accountIdentification` | Object containing the details of the bank account to be validated. | ### Tab: IBAN **Validate a third-party IBAN** ```json { "accountIdentification": { "type": "iban", "iban": "1001001234" } } ``` ### Tab: US bank account **Validate a US third-party bank account** ```json { "accountIdentification": { "type": "usLocal", "accountNumber": "12345JHDhjkf67890", "routingNumber": "121000cxhgjhzxg248" } } ``` ### Tab: AU bank account **Validate an AU third-party bank account** ```json { "accountIdentification": { "type": "auLocal", "accountNumber": "17520016", "bsbCode": "237001" } } ``` If the bank account details are valid, you'll get an **HTTP 200 OK** response. You can proceed with transferring funds to this account. In case the bank account validation fails, you'll get the details in the response. Use this information to build your own logic for handling invalid bank account details. ### Tab: IBAN **Invalid IBAN details** ```json { "type": "https://docs.adyen.com/errors/validation", "title": "Invalid bank account identification details provided", "status": 422, "invalidFields": [ { "name": "iban", "message": "Invalid IBAN." } ], "errorCode": "33_01" } ``` ### Tab: US bank account **Invalid US bank account details** ```json { "type": "https://docs.adyen.com/errors/validation", "title": "Invalid bank account identification details provided", "status": 422, "invalidFields": [ { "name": "accountNumber", "message": "Invalid account number." }, { "name": "routingNumber", "message": "Invalid routing number." } ], "errorCode": "33_01" } ``` ### Tab: AU bank account **Invalid AU bank account details** ```json { "type": "https://docs.adyen.com/errors/validation", "title": "Invalid bank account identification details provided", "status": 422, "invalidFields": [ { "name": "bsbCode", "message": "Invalid BSB code." } ], "errorCode": "33_01" } ``` ## Make a transfer To start a transfer to a third party bank account, make a POST [/transfers](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers) request specifying: | Parameter name | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-amount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The amount and the currency of the transfer. | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID of the [balance account](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts) from which funds are deducted. | | [category](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-category) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **bank**. | | [bankAccount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains details about the bank account and its owner.- The `accountHolder.fullName` is always required. For [cross-border transfers](/business-accounts/send-funds#cross-border), the `accountHolder.address` object is also required. - The `accountIdentification` is required. The fields that you need to send in this object are determined by the `accountIdentification.type`. See [bank account identification types](/business-accounts/send-funds#bank-account-identification-types). | | [priority](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-priority) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [priority](/business-accounts/send-funds#supported-currencies-locations-and-priorities) of the bank transfer, which affects the speed of the transfer and the fees you have to pay. | | [description](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-description) | | Your description for the transfer. See [Bank account identification types](/business-accounts/send-funds#bank-account-identification-types) for allowed characters. | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-reference) | | Your reference for the transfer. This is only used within your balance platform and not sent to the recipient. If you do not provide this in the request, Adyen generates a unique reference. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-referenceForBeneficiary) | | Your reference for the transfer that Adyen sends to the recipient. | Select a tab below for examples. ### Tab: Local funds transfer to IBAN bank account Here is an example of a local funds transfer of EUR funds to an IBAN bank account. When providing the details of the bank account, set the `accountIdentification.type` to **iban**. For possible values for local transfers, see [Bank account identification types](/business-accounts/send-funds#bank-account-identification-types). **Local funds transfer to an IBAN bank account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 150000 }, "category": "bank", "priority": "regular", "balanceAccountId": "BA00000000000000000000001", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION" }' ``` #### Java ```java // Adyen Java API Library v26.2.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification() .fullName("A. Klaassen"); IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL91ABNA0417164300") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(ibanAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(150000L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_INTERNAL_REFERENCE") .amount(amount) .referenceForBeneficiary("YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY") .counterparty(counterpartyInfoV3) .description("YOUR_DESCRIPTION") .category(TransferInfo.CategoryEnum.BANK) .priority(TransferInfo.PriorityEnum.REGULAR); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, null); ``` #### PHP ```php // Adyen PHP API Library v18.2.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\Transfers\Amount; use Adyen\Model\Transfers\CounterpartyInfoV3; use Adyen\Model\Transfers\PartyIdentification; use Adyen\Model\Transfers\TransferInfoAccountIdentification; use Adyen\Model\Transfers\BankAccountV3; use Adyen\Service\Transfers\TransfersApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL91ABNA0417164300") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(150000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_INTERNAL_REFERENCE") ->setAmount($amount) ->setReferenceForBeneficiary("YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY") ->setCounterparty($counterpartyInfoV3) ->setDescription("YOUR_DESCRIPTION") ->setCategory("bank") ->setPriority("regular"); // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo); ``` #### C\# ```cs // Adyen .net API Library v16.1.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification { FullName = "A. Klaassen" }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL91ABNA0417164300", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 150000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_INTERNAL_REFERENCE", Amount = amount, ReferenceForBeneficiary = "YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY", Counterparty = counterpartyInfoV3, Description = "YOUR_DESCRIPTION", Category = TransferInfo.CategoryEnum.Bank, Priority = TransferInfo.PriorityEnum.Regular }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use const { Client, TransfersAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const transferInfo = { amount: { currency: "EUR", value: 150000 }, category: "bank", priority: "regular", balanceAccountId: "BA00000000000000000000001", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen" }, accountIdentification: { type: "iban", iban: "NL91ABNA0417164300" } } }, referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY", reference: "YOUR_INTERNAL_REFERENCE", description: "YOUR_DESCRIPTION" } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` #### Go ```go // Adyen Go API Library v10.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) partyIdentification3 := transfers.PartyIdentification{ FullName: "A. Klaassen", } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL91ABNA0417164300", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 150000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_INTERNAL_REFERENCE"), Amount: amount, ReferenceForBeneficiary: common.PtrString("YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY"), Counterparty: counterpartyInfoV3, Description: common.PtrString("YOUR_DESCRIPTION"), Category: "bank", Priority: common.PtrString("regular"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.5.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "EUR", "value": 150000 }, "category": "bank", "priority": "regular", "balanceAccountId": "BA00000000000000000000001", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION" } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v9.5.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'EUR', :value => 150000 }, :category => 'bank', :priority => 'regular', :balanceAccountId => 'BA00000000000000000000001', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen' }, :accountIdentification => { :type => 'iban', :iban => 'NL91ABNA0417164300' } } }, :referenceForBeneficiary => 'YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY', :reference => 'YOUR_INTERNAL_REFERENCE', :description => 'YOUR_DESCRIPTION' } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use import { Client, TransfersAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const partyIdentification3: Types.transfers.PartyIdentification = { fullName: "A. Klaassen" }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL91ABNA0417164300", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 150000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_INTERNAL_REFERENCE", amount: amount, referenceForBeneficiary: "YOUR_REFERENCE_SENT_TO_THE_BENEFICIARY", counterparty: counterpartyInfoV3, description: "YOUR_DESCRIPTION", category: Types.transfers.TransferInfo.CategoryEnum.Bank, priority: Types.transfers.TransferInfo.PriorityEnum.Regular }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` ### Tab: Local funds transfer to a US bank account Here is an example of a local funds transfer of USD funds to a US bank account. To provide the details of the bank account, the `accountIdentification.type` is set to **usLocal**. For possible values for local transfers, see [Bank account identification types](/business-accounts/send-funds#bank-account-identification-types). **Local funds transfer to a US bank account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 10000, "currency": "USD" }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "usLocal", "accountNumber": "123456789", "routingNumber": "011000138" } } }, "priority": "regular", "referenceForBeneficiary": "Your-reference-sent-to-the-beneficiary", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER" }' ``` #### Java ```java // Adyen Java API Library v26.2.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification() .fullName("A. Klaassen"); USLocalAccountIdentification uSLocalAccountIdentification = new USLocalAccountIdentification() .routingNumber("011000138") .type(USLocalAccountIdentification.TypeEnum.USLOCAL) .accountNumber("123456789"); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(uSLocalAccountIdentification)); Amount amount = new Amount() .currency("USD") .value(10000L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_INTERNAL_REFERENCE") .amount(amount) .referenceForBeneficiary("Your-reference-sent-to-the-beneficiary") .counterparty(counterpartyInfoV3) .description("YOUR_DESCRIPTION_FOR_THE_TRANSFER") .category(TransferInfo.CategoryEnum.BANK) .priority(TransferInfo.PriorityEnum.REGULAR); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, null); ``` #### PHP ```php // Adyen PHP API Library v18.2.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\Transfers\Amount; use Adyen\Model\Transfers\CounterpartyInfoV3; use Adyen\Model\Transfers\PartyIdentification; use Adyen\Model\Transfers\TransferInfoAccountIdentification; use Adyen\Model\Transfers\BankAccountV3; use Adyen\Service\Transfers\TransfersApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setRoutingNumber("011000138") ->setType("usLocal") ->setAccountNumber("123456789"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("USD") ->setValue(10000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_INTERNAL_REFERENCE") ->setAmount($amount) ->setReferenceForBeneficiary("Your-reference-sent-to-the-beneficiary") ->setCounterparty($counterpartyInfoV3) ->setDescription("YOUR_DESCRIPTION_FOR_THE_TRANSFER") ->setCategory("bank") ->setPriority("regular"); // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo); ``` #### C\# ```cs // Adyen .net API Library v16.1.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) PartyIdentification partyIdentification3 = new PartyIdentification { FullName = "A. Klaassen" }; USLocalAccountIdentification uSLocalAccountIdentification = new USLocalAccountIdentification { RoutingNumber = "011000138", Type = USLocalAccountIdentification.TypeEnum.UsLocal, AccountNumber = "123456789" }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(uSLocalAccountIdentification) }; Amount amount = new Amount { Currency = "USD", Value = 10000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_INTERNAL_REFERENCE", Amount = amount, ReferenceForBeneficiary = "Your-reference-sent-to-the-beneficiary", Counterparty = counterpartyInfoV3, Description = "YOUR_DESCRIPTION_FOR_THE_TRANSFER", Category = TransferInfo.CategoryEnum.Bank, Priority = TransferInfo.PriorityEnum.Regular }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use const { Client, TransfersAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const transferInfo = { amount: { value: 10000, currency: "USD" }, balanceAccountId: "BA00000000000000000000001", category: "bank", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen" }, accountIdentification: { type: "usLocal", accountNumber: "123456789", routingNumber: "011000138" } } }, priority: "regular", referenceForBeneficiary: "Your-reference-sent-to-the-beneficiary", reference: "YOUR_INTERNAL_REFERENCE", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER" } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` #### Go ```go // Adyen Go API Library v10.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) partyIdentification3 := transfers.PartyIdentification{ FullName: "A. Klaassen", } uSLocalAccountIdentification := transfers.USLocalAccountIdentification{ RoutingNumber: "011000138", Type: "usLocal", AccountNumber: "123456789", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.USLocalAccountIdentificationAsTransferInfoAccountIdentification(&uSLocalAccountIdentification), } amount := transfers.Amount{ Currency: "USD", Value: 10000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_INTERNAL_REFERENCE"), Amount: amount, ReferenceForBeneficiary: common.PtrString("Your-reference-sent-to-the-beneficiary"), Counterparty: counterpartyInfoV3, Description: common.PtrString("YOUR_DESCRIPTION_FOR_THE_TRANSFER"), Category: "bank", Priority: common.PtrString("regular"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.5.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "value": 10000, "currency": "USD" }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "usLocal", "accountNumber": "123456789", "routingNumber": "011000138" } } }, "priority": "regular", "referenceForBeneficiary": "Your-reference-sent-to-the-beneficiary", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER" } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v9.5.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :value => 10000, :currency => 'USD' }, :balanceAccountId => 'BA00000000000000000000001', :category => 'bank', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen' }, :accountIdentification => { :type => 'usLocal', :accountNumber => '123456789', :routingNumber => '011000138' } } }, :priority => 'regular', :referenceForBeneficiary => 'Your-reference-sent-to-the-beneficiary', :reference => 'YOUR_INTERNAL_REFERENCE', :description => 'YOUR_DESCRIPTION_FOR_THE_TRANSFER' } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use import { Client, TransfersAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const partyIdentification3: Types.transfers.PartyIdentification = { fullName: "A. Klaassen" }; const uSLocalAccountIdentification: Types.transfers.USLocalAccountIdentification = { routingNumber: "011000138", type: Types.transfers.USLocalAccountIdentification.TypeEnum.UsLocal, accountNumber: "123456789" }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: uSLocalAccountIdentification }; const amount: Types.transfers.Amount = { currency: "USD", value: 10000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_INTERNAL_REFERENCE", amount: amount, referenceForBeneficiary: "Your-reference-sent-to-the-beneficiary", counterparty: counterpartyInfoV3, description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", category: Types.transfers.TransferInfo.CategoryEnum.Bank, priority: Types.transfers.TransferInfo.PriorityEnum.Regular }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` ### Tab: Cross-border transfer Here is an example of a cross-border wire transfer of EUR funds to a bank account in the US. To provide the details of the bank account, the `accountIdentification.type` is set to **numberAndBic**. For possible values for cross-border transfers, see [Bank account identification types](/business-accounts/send-funds#bank-account-identification-types). **Cross-border wire transfer to a US bank account** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 150000, "currency": "EUR" }, "balanceAccountId": "BA00000000000000000000002", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "San Francisco", "country": "US", "postalCode": "94678", "stateOrProvince": "CA", "street": "Brannan Street", "street2": "274" } }, "accountIdentification": { "type": "numberAndBic", "accountNumber": "123456789", "bic": "BOFAUS3NXXX" } } }, "priority": "wire", "referenceForBeneficiary": "Your-reference-sent-to-the-beneficiary", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER" }' ``` #### Java ```java // Adyen Java API Library v26.2.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) Address address3 = new Address() .country("US") .stateOrProvince("CA") .city("San Francisco") .postalCode("94678"); PartyIdentification partyIdentification3 = new PartyIdentification() .address(address3) .fullName("A. Klaassen"); NumberAndBicAccountIdentification numberAndBicAccountIdentification = new NumberAndBicAccountIdentification() .type(NumberAndBicAccountIdentification.TypeEnum.NUMBERANDBIC) .accountNumber("123456789") .bic("BOFAUS3NXXX"); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(numberAndBicAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(150000L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000002") .reference("YOUR_INTERNAL_REFERENCE") .amount(amount) .referenceForBeneficiary("Your-reference-sent-to-the-beneficiary") .counterparty(counterpartyInfoV3) .description("YOUR_DESCRIPTION_FOR_THE_TRANSFER") .category(TransferInfo.CategoryEnum.BANK) .priority(TransferInfo.PriorityEnum.WIRE); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, null); ``` #### PHP ```php // Adyen PHP API Library v18.2.0 use Adyen\Client; use Adyen\Environment; use Adyen\Model\Transfers\Amount; use Adyen\Model\Transfers\CounterpartyInfoV3; use Adyen\Model\Transfers\Address; use Adyen\Model\Transfers\PartyIdentification; use Adyen\Model\Transfers\TransferInfoAccountIdentification; use Adyen\Model\Transfers\BankAccountV3; use Adyen\Service\Transfers\TransfersApi; $client = new Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $address3 = new Address(); $address3 ->setCountry("US") ->setStateOrProvince("CA") ->setCity("San Francisco") ->setPostalCode("94678"); $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setAddress($address3) ->setFullName("A. Klaassen"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setType("numberAndBic") ->setAccountNumber("123456789") ->setBic("BOFAUS3NXXX"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(150000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000002") ->setReference("YOUR_INTERNAL_REFERENCE") ->setAmount($amount) ->setReferenceForBeneficiary("Your-reference-sent-to-the-beneficiary") ->setCounterparty($counterpartyInfoV3) ->setDescription("YOUR_DESCRIPTION_FOR_THE_TRANSFER") ->setCategory("bank") ->setPriority("wire"); // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo); ``` #### C\# ```cs // Adyen .net API Library v16.1.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Address address3 = new Address { Country = "US", StateOrProvince = "CA", City = "San Francisco", PostalCode = "94678" }; PartyIdentification partyIdentification3 = new PartyIdentification { Address = address3, FullName = "A. Klaassen" }; NumberAndBicAccountIdentification numberAndBicAccountIdentification = new NumberAndBicAccountIdentification { Type = NumberAndBicAccountIdentification.TypeEnum.NumberAndBic, AccountNumber = "123456789", Bic = "BOFAUS3NXXX" }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(numberAndBicAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 150000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000002", Reference = "YOUR_INTERNAL_REFERENCE", Amount = amount, ReferenceForBeneficiary = "Your-reference-sent-to-the-beneficiary", Counterparty = counterpartyInfoV3, Description = "YOUR_DESCRIPTION_FOR_THE_TRANSFER", Category = TransferInfo.CategoryEnum.Bank, Priority = TransferInfo.PriorityEnum.Wire }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use const { Client, TransfersAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const transferInfo = { amount: { value: 150000, currency: "EUR" }, balanceAccountId: "BA00000000000000000000002", category: "bank", counterparty: { bankAccount: { accountHolder: { fullName: "A. Klaassen", address: { city: "San Francisco", country: "US", postalCode: "94678", stateOrProvince: "CA", street: "Brannan Street", street2: "274" } }, accountIdentification: { type: "numberAndBic", accountNumber: "123456789", bic: "BOFAUS3NXXX" } } }, priority: "wire", referenceForBeneficiary: "Your-reference-sent-to-the-beneficiary", reference: "YOUR_INTERNAL_REFERENCE", description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER" } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` #### Go ```go // Adyen Go API Library v10.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) address3 := transfers.Address{ Country: "US", StateOrProvince: common.PtrString("CA"), City: common.PtrString("San Francisco"), PostalCode: common.PtrString("94678"), } partyIdentification3 := transfers.PartyIdentification{ Address: &address3, FullName: "A. Klaassen", } numberAndBicAccountIdentification := transfers.NumberAndBicAccountIdentification{ Type: "numberAndBic", AccountNumber: "123456789", Bic: "BOFAUS3NXXX", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.NumberAndBicAccountIdentificationAsTransferInfoAccountIdentification(&numberAndBicAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 150000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000002"), Reference: common.PtrString("YOUR_INTERNAL_REFERENCE"), Amount: amount, ReferenceForBeneficiary: common.PtrString("Your-reference-sent-to-the-beneficiary"), Counterparty: counterpartyInfoV3, Description: common.PtrString("YOUR_DESCRIPTION_FOR_THE_TRANSFER"), Category: "bank", Priority: common.PtrString("wire"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.5.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "value": 150000, "currency": "EUR" }, "balanceAccountId": "BA00000000000000000000002", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "San Francisco", "country": "US", "postalCode": "94678", "stateOrProvince": "CA", "street": "Brannan Street", "street2": "274" } }, "accountIdentification": { "type": "numberAndBic", "accountNumber": "123456789", "bic": "BOFAUS3NXXX" } } }, "priority": "wire", "referenceForBeneficiary": "Your-reference-sent-to-the-beneficiary", "reference": "YOUR_INTERNAL_REFERENCE", "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER" } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v9.5.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :value => 150000, :currency => 'EUR' }, :balanceAccountId => 'BA00000000000000000000002', :category => 'bank', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'A. Klaassen', :address => { :city => 'San Francisco', :country => 'US', :postalCode => '94678', :stateOrProvince => 'CA', :street => 'Brannan Street', :street2 => '274' } }, :accountIdentification => { :type => 'numberAndBic', :accountNumber => '123456789', :bic => 'BOFAUS3NXXX' } } }, :priority => 'wire', :referenceForBeneficiary => 'Your-reference-sent-to-the-beneficiary', :reference => 'YOUR_INTERNAL_REFERENCE', :description => 'YOUR_DESCRIPTION_FOR_THE_TRANSFER' } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v17.2.0 // Require the parts of the module you want to use import { Client, TransfersAPI, Types } from "@adyen/api-library"; // Initialize the client object const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Create the request object(s) const address3: Types.transfers.Address = { country: "US", stateOrProvince: "CA", city: "San Francisco", postalCode: "94678" }; const partyIdentification3: Types.transfers.PartyIdentification = { address: address3, fullName: "A. Klaassen" }; const numberAndBicAccountIdentification: Types.transfers.NumberAndBicAccountIdentification = { type: Types.transfers.NumberAndBicAccountIdentification.TypeEnum.NumberAndBic, accountNumber: "123456789", bic: "BOFAUS3NXXX" }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: numberAndBicAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 150000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000002", reference: "YOUR_INTERNAL_REFERENCE", amount: amount, referenceForBeneficiary: "Your-reference-sent-to-the-beneficiary", counterparty: counterpartyInfoV3, description: "YOUR_DESCRIPTION_FOR_THE_TRANSFER", category: Types.transfers.TransferInfo.CategoryEnum.Bank, priority: Types.transfers.TransferInfo.PriorityEnum.Wire }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo); ``` If the transfer request is successful, you receive an **HTTP 200 OK** response containing an `id` of the transfer request. Adyen informs your server of the status of the transfer through [outgoing bank transfer webhooks](/business-accounts/third-party-transfer-webhooks/#sending-funds). ** ### Trigger additional reviews To better control money movement in your balance platform, you can trigger additional reviews for s. Additional reviews require a member of your team to verify a before Adyen processes it. 1. You can trigger an additional review by including the [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review) object in the POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request. In the object, specify the following parameter: | Parameter name | Required | Description | | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [review.numberOfApprovalsRequired](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review-numberOfApprovalsRequired) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the number of approvals required to process the . Possible values: **1**. Currently, it is possible to request only one additional review per . | | The following code sample shows how to include the `review` object. **Trigger an additional review** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 60000, "currency": "EUR" }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "Adyen N.V.", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL33ADYX1000001544" } } }, "description": "Your-description-for-the-transfer", "priority": "fast", "reference": "YOUR_INTERNAL_REFERENCE", "referenceForBeneficiary": "Your-reference-for-the-beneficiary", "review": { "numberOfApprovalsRequired": 1 } }' ``` #### Java ```java // Adyen Java API Library v29.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("YOUR_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) Address address3 = new Address() .country("NL") .stateOrProvince("NH") .city("Amsterdam") .postalCode("1011DJ") .line1("Simon Carmiggeltstraat 6-50"); PartyIdentification partyIdentification3 = new PartyIdentification() .address(address3) .fullName("Adyen N.V."); IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL33ADYX1000001544") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccountV3 bankAccountV33 = new BankAccountV3() .accountHolder(partyIdentification3) .accountIdentification(new TransferInfoAccountIdentification(ibanAccountIdentification)); Amount amount = new Amount() .currency("EUR") .value(60000L); TransferRequestReview transferRequestReview = new TransferRequestReview() .numberOfApprovalsRequired(1); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .bankAccount(bankAccountV33); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000000001") .reference("YOUR_INTERNAL_REFERENCE") .amount(amount) .referenceForBeneficiary("Your-reference-for-the-beneficiary") .review(transferRequestReview) .counterparty(counterpartyInfoV3) .description("Your-description-for-the-transfer") .category(TransferInfo.CategoryEnum.BANK) .priority(TransferInfo.PriorityEnum.FAST); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("YOUR_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $address3 = new Address(); $address3 ->setCountry("NL") ->setStateOrProvince("NH") ->setCity("Amsterdam") ->setPostalCode("1011DJ") ->setLine1("Simon Carmiggeltstraat 6-50"); $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setAddress($address3) ->setFullName("Adyen N.V."); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL33ADYX1000001544") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(60000); $transferRequestReview = new TransferRequestReview(); $transferRequestReview ->setNumberOfApprovalsRequired(1); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("YOUR_INTERNAL_REFERENCE") ->setAmount($amount) ->setReferenceForBeneficiary("Your-reference-for-the-beneficiary") ->setReview($transferRequestReview) ->setCounterparty($counterpartyInfoV3) ->setDescription("Your-description-for-the-transfer") ->setCategory("bank") ->setPriority("fast"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v22.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "YOUR_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Address address3 = new Address { Country = "NL", StateOrProvince = "NH", City = "Amsterdam", PostalCode = "1011DJ", Line1 = "Simon Carmiggeltstraat 6-50" }; PartyIdentification partyIdentification3 = new PartyIdentification { Address = address3, FullName = "Adyen N.V." }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL33ADYX1000001544", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 60000 }; TransferRequestReview transferRequestReview = new TransferRequestReview { NumberOfApprovalsRequired = 1 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "YOUR_INTERNAL_REFERENCE", Amount = amount, ReferenceForBeneficiary = "Your-reference-for-the-beneficiary", Review = transferRequestReview, Counterparty = counterpartyInfoV3, Description = "Your-description-for-the-transfer", Category = TransferInfo.CategoryEnum.Bank, Priority = TransferInfo.PriorityEnum.Fast }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v21.0.0 // Require the parts of the module you want to use const { Client, TransfersAPI } = require('@adyen/api-library'); // Initialize the client object const client = new Client({apiKey: "YOUR_BALANCE_PLATFORM_API_KEY", environment: "TEST"}); // Create the request object(s) const transferInfo = { amount: { value: 60000, currency: "EUR" }, balanceAccountId: "BA00000000000000000000001", category: "bank", counterparty: { bankAccount: { accountHolder: { fullName: "Adyen N.V.", address: { city: "Amsterdam", country: "NL", postalCode: "1011DJ", stateOrProvince: "NH", line1: "Simon Carmiggeltstraat 6-50" } }, accountIdentification: { type: "iban", iban: "NL33ADYX1000001544" } } }, description: "Your-description-for-the-transfer", priority: "fast", reference: "YOUR_INTERNAL_REFERENCE", referenceForBeneficiary: "Your-reference-for-the-beneficiary", review: { numberOfApprovalsRequired: 1 } } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v14.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v9/src/common" "github.com/adyen/adyen-go-api-library/v9/src/adyen" "github.com/adyen/adyen-go-api-library/v9/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "YOUR_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) address3 := transfers.Address{ Country: "NL", StateOrProvince: common.PtrString("NH"), City: common.PtrString("Amsterdam"), PostalCode: common.PtrString("1011DJ"), Line1: common.PtrString("Simon Carmiggeltstraat 6-50"), } partyIdentification3 := transfers.PartyIdentification{ Address: &address3, FullName: common.PtrString("Adyen N.V."), } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL33ADYX1000001544", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 60000, } transferRequestReview := transfers.TransferRequestReview{ NumberOfApprovalsRequired: common.PtrInt32(1), } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("YOUR_INTERNAL_REFERENCE"), Amount: amount, ReferenceForBeneficiary: common.PtrString("Your-reference-for-the-beneficiary"), Review: &transferRequestReview, Counterparty: counterpartyInfoV3, Description: common.PtrString("Your-description-for-the-transfer"), Category: "bank", Priority: common.PtrString("fast"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v12.8.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "YOUR_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "value": 60000, "currency": "EUR" }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "Adyen N.V.", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL33ADYX1000001544" } } }, "description": "Your-description-for-the-transfer", "priority": "fast", "reference": "YOUR_INTERNAL_REFERENCE", "referenceForBeneficiary": "Your-reference-for-the-beneficiary", "review": { "numberOfApprovalsRequired": 1 } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v9.9.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'YOUR_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :value => 60000, :currency => 'EUR' }, :balanceAccountId => 'BA00000000000000000000001', :category => 'bank', :counterparty => { :bankAccount => { :accountHolder => { :fullName => 'Adyen N.V.', :address => { :city => 'Amsterdam', :country => 'NL', :postalCode => '1011DJ', :stateOrProvince => 'NH', :line1 => 'Simon Carmiggeltstraat 6-50' } }, :accountIdentification => { :type => 'iban', :iban => 'NL33ADYX1000001544' } } }, :description => 'Your-description-for-the-transfer', :priority => 'fast', :reference => 'YOUR_INTERNAL_REFERENCE', :referenceForBeneficiary => 'Your-reference-for-the-beneficiary', :review => { :numberOfApprovalsRequired => 1 } } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "YOUR_BALANCE_PLATFORM_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const address3: Types.transfers.Address = { country: "NL", stateOrProvince: "NH", city: "Amsterdam", postalCode: "1011DJ", line1: "Simon Carmiggeltstraat 6-50" }; const partyIdentification3: Types.transfers.PartyIdentification = { address: address3, fullName: "Adyen N.V." }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL33ADYX1000001544", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 60000 }; const transferRequestReview: Types.transfers.TransferRequestReview = { numberOfApprovalsRequired: 1 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "YOUR_INTERNAL_REFERENCE", amount: amount, referenceForBeneficiary: "Your-reference-for-the-beneficiary", review: transferRequestReview, counterparty: counterpartyInfoV3, description: "Your-description-for-the-transfer", category: Types.transfers.TransferInfo.CategoryEnum.Bank, priority: Types.transfers.TransferInfo.PriorityEnum.Fast }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` 2. If the request is successful, you receive an **HTTP 2XX** response containing details, including the following parameters: | Parameter name | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | [review.numberOfApprovalsRequired](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#responses-202-review-numberOfApprovalsRequired) | Shows the number of approvals required to process the . | After triggering the review, a member of your team must [approve](/business-accounts/send-funds/approve-cancel-transfers) the before Adyen continues processing it. --- # Source: https://docs.adyen.com/business-accounts/send-funds/transfer-routes.md Section: Business accounts Title: Transfer routes Description: Learn how to get the optimal routes for your payouts. --- title: "Transfer routes" description: "Learn how to get the optimal routes for your payouts." url: "https://docs.adyen.com/business-accounts/send-funds/transfer-routes" source_url: "https://docs.adyen.com/business-accounts/send-funds/transfer-routes.md" canonical: "https://docs.adyen.com/business-accounts/send-funds/transfer-routes" last_modified: "2023-03-13T23:32:00+01:00" language: "en" --- # Transfer routes Learn how to get the optimal routes for your payouts. [View source](/business-accounts/send-funds/transfer-routes.md) Sending funds to third-party bank accounts can have additional requirements or limitations. For example, some banks only support specific transfer priorities, or limit the amount of funds that you can send. These requirements or limitations are set by the third-party bank or its regulating entities. To prevent transfer failures due to such limitations, we recommend that you calculate the available transfer routes before sending funds to a new recipient. ## Requirements Before you begin, consider the following requirements: | Requirement | Description | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model) integration that supports business accounts. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Your API credential for the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) must have the following role:- **Balance Platform BCL role** | ## Calculate transfer routes You can make calculate all available transfer routes for either a specific location or a set of counterparty bank details. The following tabs explain both of these methods. ### Tab: Calculate routes by country/region To calculate transfer routes for a specific country/region: 1. Make a POST [/transferRoutes/calculate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate) request. Provide the following parameters in the request body: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | [balancePlatform](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-balancePlatform) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of your balance platform. | | [currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-currency) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character ISO currency code of the transfer. | | [category](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-category) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of transfer. Set to **bank**. | | [country](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-country) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The two-character ISO country code of the counterparty. For example, **US** or **NL**. | | [priorities](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-priorities) | | An array that contains the priorities that you want to calculate transfer routes for. For example: **regular**, **fast**, **wire**. | The following example shows how to make a request to calculate transfer routes for a counterparty in the Netherlands. **Example request—Calculate the available transfer routes by country/region** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transferRoutes/calculate \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "balancePlatform": "YOUR_BALANCE_PLATFORM", "currency": "USD", "category": "bank", "country": "NL", "priorities": [ "regular", "crossBorder", "wire" ] }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) TransferRouteRequest transferRouteRequest = new TransferRouteRequest() .country("NL") .priorities(Arrays.asList(TransferRouteRequest.PrioritiesEnum.REGULAR, TransferRouteRequest.PrioritiesEnum.CROSSBORDER, TransferRouteRequest.PrioritiesEnum.WIRE)) .currency("USD") .category(TransferRouteRequest.CategoryEnum.BANK) .balancePlatform("YOUR_BALANCE_PLATFORM"); // Send the request TransferRoutesApi service = new TransferRoutesApi(client); TransferRouteResponse response = service.calculateTransferRoutes(transferRouteRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $transferRouteRequest = new TransferRouteRequest(); $transferRouteRequest ->setCountry("NL") ->setPriorities(array("regular", "crossBorder", "wire")) ->setCurrency("USD") ->setCategory("bank") ->setBalancePlatform("YOUR_BALANCE_PLATFORM"); // Send the request $service = new TransferRoutesApi($client); $response = $service->calculateTransferRoutes($transferRouteRequest); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) TransferRouteRequest transferRouteRequest = new TransferRouteRequest { Country = "NL", Priorities = { TransferRouteRequest.PrioritiesEnum.Regular, TransferRouteRequest.PrioritiesEnum.CrossBorder, TransferRouteRequest.PrioritiesEnum.Wire }, Currency = "USD", Category = TransferRouteRequest.CategoryEnum.Bank, BalancePlatform = "YOUR_BALANCE_PLATFORM" }; // Send the request var service = new TransferRoutesService(client); var response = service.CalculateTransferRoutes(transferRouteRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.1 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const transferRouteRequest = { balancePlatform: "YOUR_BALANCE_PLATFORM", currency: "USD", category: "bank", country: "NL", priorities: [ "regular", "crossBorder", "wire" ] } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.TransferRoutesApi.calculateTransferRoutes(transferRouteRequest); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) transferRouteRequest := balancePlatform.TransferRouteRequest{ Country: common.PtrString("NL"), Priorities: []string{ "regular", "crossBorder", "wire", }, Currency: "USD", Category: "bank", BalancePlatform: "YOUR_BALANCE_PLATFORM", } // Send the request service := client.BalancePlatform() req := service.TransferRoutesApi.CalculateTransferRoutesInput().TransferRouteRequest(transferRouteRequest) res, httpRes, err := service.TransferRoutesApi.CalculateTransferRoutes(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "balancePlatform": "YOUR_BALANCE_PLATFORM", "currency": "USD", "category": "bank", "country": "NL", "priorities": [ "regular", "crossBorder", "wire" ] } # Send the request result = adyen.balancePlatform.transfer_routes_api.calculate_transfer_routes(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :balancePlatform => 'YOUR_BALANCE_PLATFORM', :currency => 'USD', :category => 'bank', :country => 'NL', :priorities => [ 'regular', 'crossBorder', 'wire' ] } # Send the request result = adyen.balancePlatform.transfer_routes_api.calculate_transfer_routes(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const transferRouteRequest: Types.balancePlatform.TransferRouteRequest = { country: "NL", priorities: [ Types.balancePlatform.TransferRouteRequest.PrioritiesEnum.Regular, Types.balancePlatform.TransferRouteRequest.PrioritiesEnum.CrossBorder, Types.balancePlatform.TransferRouteRequest.PrioritiesEnum.Wire ], currency: "USD", category: Types.balancePlatform.TransferRouteRequest.CategoryEnum.Bank, balancePlatform: "YOUR_BALANCE_PLATFORM" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.TransferRoutesApi.calculateTransferRoutes(transferRouteRequest); ``` 2. In the response, note the `transferRoutes` object, which includes all transfer routes supported in a country/region. Each transfer route specifies: * The supported currency. * The supported priority. * Any additional requirements you must fulfill when using the transfer route. **Example response—Transfer routes by country/region** ```json { "transferRoutes": [ { "currency": "USD", "priority": "regular", "requirements": [] }, { "currency": "USD", "priority": "crossBorder", "requirements": [ { "description": "Amount of transfer must be at least 100, and no greater than 99999999999", "max": 99999999999, "min": 100, "type": "amountMinMaxRequirement" }, { "description": "Country, street and city is required.", "requiredAddressFields": [ "STREET", "CITY" ], "type": "addressRequirement" }, { "description": "Bank account identification type must be iban or numberAndBic", "bankAccountIdentificationTypes": [ "iban", "numberAndBic" ], "type": "bankAccountIdentificationTypeRequirement" }, { "issuingCountryCode": "NL", "paymentInstrumentType": "BankAccount", "type": "paymentInstrumentRequirement" } ] }, { "currency": "USD", "priority": "wire", "requirements": [] } ] } ``` ### Tab: Calculate transfer routes by counterparty To calculate transfer routes for a specific counterparty: 1. Make a POST [/transferRoutes/calculate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate) request. Provide the following parameters in the request body: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | [balancePlatform](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-balancePlatform) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of your balance platform. | | [currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-currency) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character ISO currency code of the transfer. | | [category](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-category) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of transfer. Set to **bank**. | | [counterparty](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-counterparty) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object that contains information about the recipient of the funds transfer. The counterparty can be a third-party bank account or a transfer instrument. | | [priorities](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-priorities) | | An array that contains the priorities that you want to calculate transfer routes for. For example: **regular**, **fast**, **wire**. | | [balanceAccountId](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transferRoutes/calculate#request-balanceAccountId) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the source balance account. Required if `counterparty` contains a **transferInstrumentId**. | The following example shows how to make a request to calculate transfer routes for a specific counterparty. **Example request—Calculate transfer routes by counterparty** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transferRoutes/calculate \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "balancePlatform": "YOUR_BALANCE_PLATFORM", "currency": "EUR", "category": "bank", "priorities": [ "instant", "wire" ], "counterparty": { "bankAccount": { "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.balanceplatform.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.balancePlatform.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification() .iban("NL91ABNA0417164300") .type(IbanAccountIdentification.TypeEnum.IBAN); BankAccount bankAccount = new BankAccount() .accountIdentification(new TransferRouteRequestAccountIdentification(ibanAccountIdentification)); Counterparty counterparty = new Counterparty() .bankAccount(bankAccount); TransferRouteRequest transferRouteRequest = new TransferRouteRequest() .priorities(Arrays.asList(TransferRouteRequest.PrioritiesEnum.INSTANT, TransferRouteRequest.PrioritiesEnum.WIRE)) .counterparty(counterparty) .currency("EUR") .category(TransferRouteRequest.CategoryEnum.BANK) .balancePlatform("YOUR_BALANCE_PLATFORM"); // Send the request TransferRoutesApi service = new TransferRoutesApi(client); TransferRouteResponse response = service.calculateTransferRoutes(transferRouteRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $transferRouteRequestAccountIdentification = new TransferRouteRequestAccountIdentification(); $transferRouteRequestAccountIdentification ->setIban("NL91ABNA0417164300") ->setType("iban"); $bankAccount = new BankAccount(); $bankAccount ->setAccountIdentification($transferRouteRequestAccountIdentification); $counterparty = new Counterparty(); $counterparty ->setBankAccount($bankAccount); $transferRouteRequest = new TransferRouteRequest(); $transferRouteRequest ->setPriorities(array("instant", "wire")) ->setCounterparty($counterparty) ->setCurrency("EUR") ->setCategory("bank") ->setBalancePlatform("YOUR_BALANCE_PLATFORM"); // Send the request $service = new TransferRoutesApi($client); $response = $service->calculateTransferRoutes($transferRouteRequest); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.BalancePlatform; using Adyen.Service.BalancePlatform; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL91ABNA0417164300", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccount bankAccount = new BankAccount { AccountIdentification = new TransferRouteRequestAccountIdentification(ibanAccountIdentification) }; Counterparty counterparty = new Counterparty { BankAccount = bankAccount }; TransferRouteRequest transferRouteRequest = new TransferRouteRequest { Priorities = { TransferRouteRequest.PrioritiesEnum.Instant, TransferRouteRequest.PrioritiesEnum.Wire }, Counterparty = counterparty, Currency = "EUR", Category = TransferRouteRequest.CategoryEnum.Bank, BalancePlatform = "YOUR_BALANCE_PLATFORM" }; // Send the request var service = new TransferRoutesService(client); var response = service.CalculateTransferRoutes(transferRouteRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.1 const { Client, BalancePlatformAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const transferRouteRequest = { balancePlatform: "YOUR_BALANCE_PLATFORM", currency: "EUR", category: "bank", priorities: [ "instant", "wire" ], counterparty: { bankAccount: { accountIdentification: { type: "iban", iban: "NL91ABNA0417164300" } } } } // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.TransferRoutesApi.calculateTransferRoutes(transferRouteRequest); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/balancePlatform" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) ibanAccountIdentification := balancePlatform.IbanAccountIdentification{ Iban: "NL91ABNA0417164300", Type: "iban", } bankAccount := balancePlatform.BankAccount{ AccountIdentification: balancePlatform.IbanAccountIdentificationAsTransferRouteRequestAccountIdentification(&ibanAccountIdentification), } counterparty := balancePlatform.Counterparty{ BankAccount: &bankAccount, } transferRouteRequest := balancePlatform.TransferRouteRequest{ Priorities: []string{ "instant", "wire", }, Counterparty: &counterparty, Currency: "EUR", Category: "bank", BalancePlatform: "YOUR_BALANCE_PLATFORM", } // Send the request service := client.BalancePlatform() req := service.TransferRoutesApi.CalculateTransferRoutesInput().TransferRouteRequest(transferRouteRequest) res, httpRes, err := service.TransferRoutesApi.CalculateTransferRoutes(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "balancePlatform": "YOUR_BALANCE_PLATFORM", "currency": "EUR", "category": "bank", "priorities": [ "instant", "wire" ], "counterparty": { "bankAccount": { "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } } } # Send the request result = adyen.balancePlatform.transfer_routes_api.calculate_transfer_routes(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.1.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :balancePlatform => 'YOUR_BALANCE_PLATFORM', :currency => 'EUR', :category => 'bank', :priorities => [ 'instant', 'wire' ], :counterparty => { :bankAccount => { :accountIdentification => { :type => 'iban', :iban => 'NL91ABNA0417164300' } } } } # Send the request result = adyen.balancePlatform.transfer_routes_api.calculate_transfer_routes(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.1 import { Client, BalancePlatformAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const ibanAccountIdentification: Types.balancePlatform.IbanAccountIdentification = { iban: "NL91ABNA0417164300", type: Types.balancePlatform.IbanAccountIdentification.TypeEnum.Iban }; const bankAccount: Types.balancePlatform.BankAccount = { accountIdentification: ibanAccountIdentification }; const counterparty: Types.balancePlatform.Counterparty = { bankAccount: bankAccount }; const transferRouteRequest: Types.balancePlatform.TransferRouteRequest = { priorities: [ Types.balancePlatform.TransferRouteRequest.PrioritiesEnum.Instant, Types.balancePlatform.TransferRouteRequest.PrioritiesEnum.Wire ], counterparty: counterparty, currency: "EUR", category: Types.balancePlatform.TransferRouteRequest.CategoryEnum.Bank, balancePlatform: "YOUR_BALANCE_PLATFORM" }; // Send the request const balancePlatformAPI = new BalancePlatformAPI(client); const response = balancePlatformAPI.TransferRoutesApi.calculateTransferRoutes(transferRouteRequest); ``` 2. In the response, note the `transferRoutes` object, which includes all transfer routes supported by a counterparty. Each transfer route specifies: * The country of the counterparty. * The supported currency. * The supported priority. * Any additional requirements you must fulfill when using the transfer route. **Example response—Transfer routes by counterparty** ```json { "transferRoutes": [ { "country": "NL", "currency": "EUR", "priority": "instant", "requirements": [ { "description": "Amount of transfer must be at least 1, and no greater than 9999999", "max": 9999999, "min": 1, "type": "amountMinMaxRequirement" }, { "description": "Bank account identification type must be iban", "bankAccountIdentificationTypes": [ "iban" ], "type": "bankAccountIdentificationTypeRequirement" }, { "issuingCountryCode": "NL", "paymentInstrumentType": "BankAccount", "type": "paymentInstrumentRequirement" } ] }, { "country": "NL", "currency": "EUR", "priority": "wire", "requirements": [ { "description": "Amount of transfer must be at least 1, and no greater than 99999999999", "max": 99999999999, "min": 1, "type": "amountMinMaxRequirement" }, { "issuingCountryCode": "NL", "paymentInstrumentType": "BankAccount", "type": "paymentInstrumentRequirement" }, { "description": "Bank account identification type must be iban", "bankAccountIdentificationTypes": [ "iban" ], "type": "bankAccountIdentificationTypeRequirement" } ] } ] } ``` ## Next steps [required](/business-accounts/send-funds) [Send funds](/business-accounts/send-funds) [Learn how your users can send funds using their Adyen business account.](/business-accounts/send-funds) --- # Source: https://docs.adyen.com/business-accounts/send-funds/verify-counterparty.md Section: Business accounts Title: Verify counterparty name Description: Learn how to verify the counterparty name registered to a third-party bank account for outgoing transfers. --- title: "Verify counterparty name" description: "Learn how to verify the counterparty name registered to a third-party bank account for outgoing transfers." url: "https://docs.adyen.com/business-accounts/send-funds/verify-counterparty" source_url: "https://docs.adyen.com/business-accounts/send-funds/verify-counterparty.md" canonical: "https://docs.adyen.com/business-accounts/send-funds/verify-counterparty" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Verify counterparty name Learn how to verify the counterparty name registered to a third-party bank account for outgoing transfers. [View source](/business-accounts/send-funds/verify-counterparty.md) Adyen's verification of counterparty name service allows business account holders to check the intended recipient before making a payment to domestic bank accounts registered in the EU or UK regions. The service performs verification lookups with account name-checking services operated by the following regulators: * European Payment Council * UK Payment System Regulator These services were designed to help reduce misdirected payments and provide greater assurance that payments are being sent, and collected from, the intended account holder for EU/UK domestic payments. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Adyen [business accounts](/business-accounts) | | **[API credential roles](/development-resources/api-credentials/roles/)** | To [verify a counterparty name](#verify-a-counterparty-name), make sure that your Balance Platform API key has the following role(s)- **CounterpartyNameVerification Webservice Initiate** | | **Setup steps** | Before you begin:- Reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable the API credential role for your API key. | ## How it works At a high level, your user does the following within your client interface: 1. The business account holder logs in to their account on your platform. 2. You provide an interface for the business account holder to verify a counterparty when providing transfer instructions.\ OR\ You provide an interface for the business account holder to add a counterparty to an address book of known parties to which they want to make future transfers. 3. The user enters information for a transfer request to one of the following. * A bank account located in the EU region: * IBAN account number * name on the account * A bank account located in the UK: * bank account number * sort code * type of bank account (personal or business) * name on the account 4. Your platform makes a call to the `POST /verifyCounterpartyName` endpoint. Adyen makes a check with the counterparty's bank to determine if there is a name match, and responds with a `response` value:\ Some `response` examples: * **nameMatch** * **nameMatchNotSupported** * **noNameMatch** * **partialNameMatch** If the `response` is a partial name match, Adyen returns the name on the account in the response. To safeguard against name-guessing, for all other `response` values, Adyen does not return a name in the response. 5. Based on the `response`, you present some options to your user, and prompt them to confirm if they want to continue, or to cancel, the transfer.\ If there is a name match, your client could also prompt the business account holder to add that name to their address book of parties to make future transfers. 6. If the user confirms they want to continue with the transfer, make the transfer request using the `POST /transfers` endpoint. ## Verify a counterparty name Select the location of the bank account information you want to verify from the following tabs: ### Tab: Checking EU-based accounts To verify the name of a counterparty for a transfer to a domestic EU bank account, make a `POST /verifyCounterpartyName` request, providing the following parameters: | Parameter name | Required | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `counterparty.bankAccount.accountHolder.fullName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The full name of the entity that owns the bank account. | | `counterparty.bankAccount.accountIdentification` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | object | An object containing information about the account holder's bank account you want to verify. | | `counterparty.bankAccount.accountIdentification.iban` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The IBAN in the following format, without separators or whitespace: **^\[A-Z]{2}\[0-9]{2}\[A-Z0-9]{1,30}$** Maximum character count: 34 characters | | `counterparty.bankAccount.accountIdentification.type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | String | Possible values: **iban** | | `reference` | | string | Your reference to identify the party or counterparty involved with the transfer. For example, your client's counterparty ID. | | `balanceAccountId` | | string | The unique identifier of the source balance account. Adyen does not verify this value. | **Verify a counterparty for a transfer request to an account registered in the EU** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/verifyCounterpartyName \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_API_KEY' \ -X POST \ -d '{ "counterparty": { "bankAccount": { "accountHolder": { "fullName": "Alexander Jeffries" }, "accountIdentification": { "type": "iban", "iban": "DE87123456781234567890" } } }, "balanceAccountId": "BA0000000000000001", "reference": "account-check-7T67G5428398G" }' ``` ### Tab: Checking UK-based accounts To verify the name of a counterparty for a transfer to a domestic UK bank account, make a `POST /verifyCounterpartyName` request, providing the following parameters: | Parameter name | Required | Type | Description | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | `counterparty.bankAccount.accountHolder.fullName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The full name of the entity that owns the bank account. | | `counterparty.bankAccount.accountIdentification` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | object | An object containing information about the account holder's bank account you want to verify. | | `counterparty.bankAccount.accountIdentification.accountNumber` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The eight-digit bank account number, without separators or whitespace. | | `counterparty.bankAccount.accountIdentification.sortCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The six-digit sort code, without separators or whitespace. | | `counterparty.bankAccount.accountIdentification.type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | Possible values: **ukLocal** | | `counterparty.bankAccount.accountIdentification.accountType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | string | The type of bank account. Possible values:- **personal** - **business** | | `reference` | | string | Your reference to identify the party or counterparty involved with the transfer. For example, your client's counterparty ID. | | `balanceAccountId` | | string | The unique identifier of the source balance account. Adyen does not verify this value. | **Verify a counterparty for a transfer request to an account registered in the UK** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/verifyCounterpartyName \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_API_KEY' \ -X POST \ -d '{ "counterparty": { "bankAccount": { "accountHolder": { "fullName": "Alexander Jeffries" }, "accountIdentification": { "type": "ukLocal", "accountNumber": "12345678", "sortCode": "011000", "accountType": "personal" } } }, "balanceAccountId": "BA0000000000000001", "reference": "account-check-7T67G5428398G" }' ``` The response contains the results of the counterparty name verification lookup. This example shows a verification result where the counterparty name matched the name on the bank account. ```json { "creationDate": "2025-09-05T14:28:17.521224712+02:00[Europe/Amsterdam]", "id": "CV8239-83092-749823-47078", "reference": "account-check-7T67G5428398G", "balanceAccountId": "BA0000000000000001", "counterpartyVerification": { "response": "nameMatch", "responseDescription": "Correct name match" } } ``` This example response shows a verification result where the counterparty name partially matched the name on the bank account. ```json { "creationDate": "2025-09-05T14:28:17.521224712+02:00[Europe/Amsterdam]", "id": "CV8239-83092-749823-47078", "reference": "account-check-7T67G5428398G", "balanceAccountId": "BA0000000000000001", "counterpartyVerification": { "name": "Alexander Jeffriesy", "response": "partialNameMatch", "responseDescription": "Partial name match" } } ``` Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return. A successful response contains the following parameters: | Parameter name | type | description | | ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `creationDate` | string | The creation date of the verification request. Example: **2025-09-05T14:28:17.521224712+02:00\[Europe/Amsterdam]** | | `id` | string | The ID of the counterparty name verification request. | | `reference` | string | Your unique reference to identify the party or counterparty involved with the verification request. For example, your system's unique ID assigned to the party or counterparty. | | `balanceAccountId` | string | The unique identifier of the balance account requesting verification of a counterparty name for a transfer. | | `counterpartyVerification` | object | The object containing the results of the counterparty name verification lookup. | | `counterpartyVerification.name` | string | The name of the entity that owns the bank account. The name is only returned when the response is **partialNameMatch** (EU or UK), **partialNameMatchBusiness** (UK only), or **partialNameMatchPersonal** (UK only). | | `counterpartyVerification.response` | enum | The response returned by the counterparty name verification lookup. Possible values in the EU region:- **nameMatch** - **nameMatchNotSupported** - **noNameMatch** - **partialNameMatch**Possible values in the UK:- **accountNotFound** - **accountSwitched** - **accountVerificationNotSupported** - **financialInstitutionNotFound** - **nameMatch** - **nameMatchBusiness** - **nameMatchNotSupported** - **nameMatchOptOut** - **nameMatchPersonal** - **noNameMatch** - **partialNameMatch** - **partialNameMatchBusiness** - **partialNameMatchPersonal** | | `counterpartyVerification.responseDescription` | string | A human-readable description mapped to the value of the `response` parameter. Do not use this description to inform your client logic. | ## Guidance for developing your client interface When consuming the response to the counterparty name verification request, consider the following when presenting notes, warnings, and call-to-action links and/or buttons when developing your client interface. | response | responseDescription | Name returned? | Suggested messaging | Additional expectation | | ----------------------------------------------------------- | ------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **accountNotFound** UK account checks only | Account not found | No | Account not found. | Warning message with the following options. **When adding name to a contact list:**- Cancel - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **accountSwitched** UK account checks only | Account switched | No | Account switched. | Warning message with the following options. **When adding name to a contact list:**- Cancel - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **accountVerificationNotSupported** UK accounts checks only | Incorrect bank code | No | Unable to check details. | Warning message with the following options. **When adding name to a contact list:**- Cancel - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **financialInstitutionNotFound** UK account checks only | Financial institution not found | No | Financial institution not found. | Warning message with the following options. **When adding name to a contact list:**- Cancel - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **nameMatch** EU or UK account checks | Correct name match | No | The account name is a match. | Check with the user before continuing, with the following options. **When adding name to a contact list:**- Add name**When making a payment request:**- Continue with payment | | **nameMatchBusiness** UK account checks only | Name match, but the account type is business instead of personal | No | Account name is a match, but the account type is business instead of personal. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **nameMatchNotSupported** EU or UK account checks | Name match not supported | No | Unable to confirm name. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **nameMatchOptOut** UK account checks only | Opted out from account name verification | No | Unable to check name. | Warning message with the following options. **When adding name to a contact list:**- Add name - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **nameMatchPersonal** UK account checks only | Name match, but the account type is personal instead of business | No | Account name is a match, but the account type is personal instead of business. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **noNameMatch** EU or UK account checks | No name match | No | The name you gave us is not the same as the name held on the account. | Warning message with the following options. **When adding name to a contact list:**- Edit details - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **partialNameMatch** EU or UK account checks | Partial name match | Yes | The name you gave us is not the same as the name held on the account. It's a close match, the name is *returned name*. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **partialNameMatchBusiness** UK account checks only | Partial name match, but the account type is business instead of personal | Yes | The name you gave us is not the same as the name held on the account. It's a close match, the name is *returned name*. Additionally, the account type is business instead of personal. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment | | **partialNameMatchPersonal** UK account checks only | Partial name match, but the account type is personal instead of business | Yes | The name you gave us is not the same as the name held on the account. It's a close match, the name is *returned name*. Additionally, the account type is personal instead of business. | Warning message with the following options. **When adding name to a contact list:**- Add name - Edit details - Cancel**When making a payment request:**- Cancel payment - Edit payment details - Continue with payment \setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $address3 = new Address(); $address3 ->setCountry("NL") ->setCity("Amsterdam") ->setLine1("Simon Carmiggeltstraat 6-50"); $partyIdentification3 = new PartyIdentification(); $partyIdentification3 ->setAddress($address3) ->setFullName("A. Klaassen") ->setType("unknown"); $transferInfoAccountIdentification = new TransferInfoAccountIdentification(); $transferInfoAccountIdentification ->setIban("NL20ADYB2017000035") ->setType("iban"); $bankAccountV33 = new BankAccountV3(); $bankAccountV33 ->setAccountHolder($partyIdentification3) ->setAccountIdentification($transferInfoAccountIdentification); $amount = new Amount(); $amount ->setCurrency("EUR") ->setValue(10000); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBankAccount($bankAccountV33); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000000001") ->setReference("The reference for the transfer") ->setAmount($amount) ->setReferenceForBeneficiary("The-reference-sent-to-the-beneficiary") ->setCounterparty($counterpartyInfoV3) ->setDescription("The description for the transfer") ->setCategory("bank") ->setPriority("regular"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v29.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Address address3 = new Address { Country = "NL", City = "Amsterdam", Line1 = "Simon Carmiggeltstraat 6-50" }; PartyIdentification partyIdentification3 = new PartyIdentification { Address = address3, FullName = "A. Klaassen", Type = PartyIdentification.TypeEnum.Unknown }; IbanAccountIdentification ibanAccountIdentification = new IbanAccountIdentification { Iban = "NL20ADYB2017000035", Type = IbanAccountIdentification.TypeEnum.Iban }; BankAccountV3 bankAccountV33 = new BankAccountV3 { AccountHolder = partyIdentification3, AccountIdentification = new TransferInfoAccountIdentification(ibanAccountIdentification) }; Amount amount = new Amount { Currency = "EUR", Value = 10000 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BankAccount = bankAccountV33 }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000000001", Reference = "The reference for the transfer", Amount = amount, ReferenceForBeneficiary = "The-reference-sent-to-the-beneficiary", Counterparty = counterpartyInfoV3, Description = "The description for the transfer", Category = TransferInfo.CategoryEnum.Bank, Priority = TransferInfo.PriorityEnum.Regular }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v24.0.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const transferInfo = { amount: { value: 10000, currency: "EUR" }, balanceAccountId: "BA00000000000000000000001", category: "bank", counterparty: { bankAccount: { accountHolder: { type: "unknown", fullName: "A. Klaassen", address: { city: "Amsterdam", line1: "Simon Carmiggeltstraat 6-50", country: "NL" } }, accountIdentification: { type: "iban", iban: "NL20ADYB2017000035" } } }, description: "The description for the transfer", priority: "regular", referenceForBeneficiary: "The-reference-sent-to-the-beneficiary", reference: "The reference for the transfer" } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v18.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v18/src/common" "github.com/adyen/adyen-go-api-library/v18/src/adyen" "github.com/adyen/adyen-go-api-library/v18/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) address3 := transfers.Address{ Country: "NL", City: common.PtrString("Amsterdam"), Line1: common.PtrString("Simon Carmiggeltstraat 6-50"), } partyIdentification3 := transfers.PartyIdentification{ Address: &address3, FullName: common.PtrString("A. Klaassen"), Type: common.PtrString("unknown"), } ibanAccountIdentification := transfers.IbanAccountIdentification{ Iban: "NL20ADYB2017000035", Type: "iban", } bankAccountV33 := transfers.BankAccountV3{ AccountHolder: partyIdentification3, AccountIdentification: transfers.IbanAccountIdentificationAsTransferInfoAccountIdentification(&ibanAccountIdentification), } amount := transfers.Amount{ Currency: "EUR", Value: 10000, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BankAccount: &bankAccountV33, } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), Reference: common.PtrString("The reference for the transfer"), Amount: amount, ReferenceForBeneficiary: common.PtrString("The-reference-sent-to-the-beneficiary"), Counterparty: counterpartyInfoV3, Description: common.PtrString("The description for the transfer"), Category: "bank", Priority: common.PtrString("regular"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "value": 10000, "currency": "EUR" }, "balanceAccountId": "BA00000000000000000000001", "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "type": "unknown", "fullName": "A. Klaassen", "address": { "city": "Amsterdam", "line1": "Simon Carmiggeltstraat 6-50", "country": "NL" } }, "accountIdentification": { "type": "iban", "iban": "NL20ADYB2017000035" } } }, "description": "The description for the transfer", "priority": "regular", "referenceForBeneficiary": "The-reference-sent-to-the-beneficiary", "reference": "The reference for the transfer" } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.2 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :value => 10000, :currency => 'EUR' }, :balanceAccountId => 'BA00000000000000000000001', :category => 'bank', :counterparty => { :bankAccount => { :accountHolder => { :type => 'unknown', :fullName => 'A. Klaassen', :address => { :city => 'Amsterdam', :line1 => 'Simon Carmiggeltstraat 6-50', :country => 'NL' } }, :accountIdentification => { :type => 'iban', :iban => 'NL20ADYB2017000035' } } }, :description => 'The description for the transfer', :priority => 'regular', :referenceForBeneficiary => 'The-reference-sent-to-the-beneficiary', :reference => 'The reference for the transfer' } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v24.0.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const address3: Types.transfers.Address = { country: "NL", city: "Amsterdam", line1: "Simon Carmiggeltstraat 6-50" }; const partyIdentification3: Types.transfers.PartyIdentification = { address: address3, fullName: "A. Klaassen", type: Types.transfers.PartyIdentification.TypeEnum.Unknown }; const ibanAccountIdentification: Types.transfers.IbanAccountIdentification = { iban: "NL20ADYB2017000035", type: Types.transfers.IbanAccountIdentification.TypeEnum.Iban }; const bankAccountV33: Types.transfers.BankAccountV3 = { accountHolder: partyIdentification3, accountIdentification: ibanAccountIdentification }; const amount: Types.transfers.Amount = { currency: "EUR", value: 10000 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { bankAccount: bankAccountV33 }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000000001", reference: "The reference for the transfer", amount: amount, referenceForBeneficiary: "The-reference-sent-to-the-beneficiary", counterparty: counterpartyInfoV3, description: "The description for the transfer", category: Types.transfers.TransferInfo.CategoryEnum.Bank, priority: Types.transfers.TransferInfo.PriorityEnum.Regular }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` The funds sent from the Adyen business account are deducted from the associated balance account. The transfer and the changes in the status of the transfer trigger webhooks that include the following information: | Parameter | Description | | ------------------------- | ------------------------------------------------------------ | | `accountHolder` | The user that initiated the transfer. | | `balanceAccount` | The balance account of the user that initiated the transfer. | | `category` | **bank** | | `description` | The description your user included in the transfer request. | | `reference` | The reference your user included in the transfer request. | | `referenceForBeneficiary` | Your user's message for the beneficiary. | | `type` | **bankTransfer** | The following sections contain the webhooks that Adyen sends when you transfer EUR 100.00 to a third-party bank account. ** ### Outgoing bank transfer initiated When your user initiates a transfer to a Mastercard or Visa card, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook to inform your server that an outgoing transfer request has been created. The webhook provides information about the transfer, such as: * The `amount` of the payout * The `reference` for the payout * The `referenceForBeneficiary` * Your user's `balanceAccount` from which the funds will be deducted * Details of the `accountHolder` linked to your user's balance account. * Details of the `counterparty` in the transfer, which is your user's transfer instrument. * The `bookingDate` when the payout was requested. * The `id` of the corresponding transfer. ** ### Outgoing bank transfer authorized When the transfer request is authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event to inform your server that the transfer amount has been reserved on the account. This webhook includes the `status` **authorised**. **Transfer authorised** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "EUR", "received": 0, "reserved": -10000 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bankTransfer" }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" } ], "id": "6JKRLZ8LOT47J7RY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 2, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "authorised", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer booked When the funds are deducted from your user's balance account, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event with: * `direction`: **outgoing** * `status`: **booked** * `counterparty`: details of the external transfer instrument. * `events.transactionId`: ID of the transaction This status is not final. The transfer may still [fail](#outgoing-bank-transfer-failed) if, for example, the transfer is rejected by the external banking system. **Transfer booked** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" } ], "id": "6JKRLZ8LOT47J7RY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 3, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "booked", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer pending After the funds are deducted from your user's balance account, the transfer is automatically analyzed to ensure that it complies with Adyen's policies. If a transfer is flagged, Adyen reviews the transfer. In order to speed up the screening process and reduce the amount of manual effort needed, we recommend that you provide as much information as possible in the transfer request. For example, include all counterparty details in the [accountHolder](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-bankAccount-accountHolder) object. In this case, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event with a `tracking` event type, specifying the following `trackingData` details: * `status`: **pending** * `type`: **internalReview** **Transfer pending** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" }, "fullName": "A. Klaassen", "type": "unknown" }, "accountIdentification": { "iban": "NL91ABNA0417164300", "type": "iban" } } }, "creationDate": "2024-04-22T12:55:18+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2024-04-22T12:55:18+02:00" }, { "id": "6JKRLZ8LOT47J7RY", "trackingData": { "status": "pending", "type": "internalReview" }, "type": "tracking", "updateDate": "2024-04-22T12:55:30+02:00" } ], "id": "34IXDC62P0FE4RHI", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 4, "status": "booked", "tracking": { "status": "pending", "type": "internalReview" }, "transactionRulesResult": { "allHardBlockRulesPassed": true, "score": 0 }, "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` After Adyen reviews the transfer details, we send a webhook to notify you of the outcome. ### Tab: Review passed If the transfer passed the review: * For transfers with `priority` **instant**, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook to confirm that the funds have been credited in the counterparty account. The webhook includes a `tracking` event with the tracking `status` **credited**. For more information, see an example of the [payout credited webhook](#payout-credited). * For transfers with any other priority, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the `tracking` event, specifying the `estimatedArrivalTime`. This field indicates the date and time when the funds will be credited in the counterparty bank account. For more information, see an example of the [payout tracking webhook](#payout-tracking). This status is not final. The transfer may still [fail](#outgoing-bank-transfer-failed), for example if the transfer is rejected by the external banking system. ### Tab: Review failed If the transfer fails Adyen's review process, we send a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with a `tracking` event, specifying the following `trackingData`: * `reason`: **refusedForRegulatoryReasons** * `status`: **failed** * `type`: **internalReview** If this is the case, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). **Transfer failed review** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 1000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" }, "fullName": "A. Klaassen", "type": "unknown" }, "accountIdentification": { "iban": "NL91ABNA0417164300", "type": "iban" } } }, "creationDate": "2024-04-22T12:55:18+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 1000, "reserved": -1000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2024-04-22T12:55:20+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -1000, "currency": "EUR", "received": 0, "reserved": 1000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2024-04-22T12:55:18+02:00" }, { "id": "6JKRLZ8LOT47J7RY", "trackingData": { "status": "pending", "type": "internalReview" }, "type": "tracking", "updateDate": "2024-04-22T12:55:29+02:00" }, { "id": "6JKRLZ8LOT47J7RY", "trackingData": { "reason": "refusedForRegulatoryReasons", "status": "failed", "type": "internalReview" }, "type": "tracking", "updateDate": "2024-04-22T12:57:28+02:00" } ], "id": "34IXDC62P0FE4RHI", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 5, "status": "booked", "tracking": { "reason": "refusedForRegulatoryReasons", "status": "failed", "type": "internalReview" }, "transactionRulesResult": { "allHardBlockRulesPassed": true, "score": 0 }, "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer failed The transfer can fail if it is rejected by an external banking system and any automatic retries are unsuccessful. For instant bank transfers with end-to-end confirmation from the counterparty's bank, this is the status when the counterparty's bank rejects the transfer. When a transfer fails, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with: * `status`: **failed** * The `transactionId` * The `reason` for the failure. For more information, see [Return reason codes](#return-reason-codes). **Transfer failed** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 0, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000004", "mutations": [ { "balance": 10000, "currency": "EUR", "received": 0 } ], "reason": "counterpartyAccountNotFound", "status": "failed", "transactionId": "EVJN42271114222B5JB8BRC76N686ZHBG", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" } ], "id": "6JKRLZ8LOT47J7RY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 4, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "failed", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer tracking When the transfer is completed, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event with a `tracking` event type, specifying the `estimatedArrivalTime`. This is the estimated time when the funds will be credited in the counterparty bank account. The estimated time is based on the official clearing system regulations that outline credit fund availability requirements. If the beneficiary bank does not adhere to the official regulations, the actual time of arrival can deviate from the estimate. Estimated Time of Arrival is currently available for all local payouts. It is *not* available for instant or cross-border payouts. This only applies to transfers with: * `priority` **regular** * `priority` **fast** * `priority` **wire** **Estimated time of arrival** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" }, { "estimatedArrivalTime": "2023-03-02T07:00:00+00:00", "id": "EVJN00000000000000000000000004", "trackingData": { "estimatedArrivalTime": "2023-03-02T07:00:00+00:00", "type": "estimation" }, "type": "tracking", "updateDate": "2023-03-01T17:59:34+01:00" } ], "id": "3JTRKZ5VXL07G5UY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 4, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "booked", "tracking": { "estimatedArrivalTime": "2023-03-02T07:00:00+00:00", "type": "estimation" }, "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer credited If a transfer with `priority` **instant** is completed, then Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event to confirm that the funds have been credited. The webhook includes a `tracking` event type with the tracking `status` **credited**. **Transfer credited** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "instant", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" }, { "id": "EVJN00000000000000000000000004", "status": "credited", "type": "tracking", "updateDate": "2023-03-01T12:58:25+01:00" } ], "id": "3JTRKZ5VXL07G5UY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 4, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "booked", "tracking": { "status": "credited", "type": "confirmation" }, "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** ### Outgoing bank transfer returned If the transfer is returned by the counterparty's bank, then Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event with: * `status`: **returned** * The `transactionId` * The `reason` for not accepting the transfer. For more information, see [Reason codes](#return-reason-codes). **Transfer returned** ```json { "data": { "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 10000 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001", "reference": "Your reference for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 0, "currency": "EUR", "received": 0, "reserved": 0 } ], "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen", "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" } }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "creationDate": "2023-02-28T13:30:05+02:00", "description": "Your user description for the transfer", "direction": "outgoing", "events": [ { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -10000 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 10000, "reserved": -10000 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -10000, "currency": "EUR", "received": 0, "reserved": 10000 } ], "status": "booked", "transactionId": "EVJN42272224222B5JB8BRC84N686ZEUR", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" }, { "bookingDate": "2023-02-28T13:30:18+02:00", "id": "EVJN00000000000000000000000004", "mutations": [ { "balance": 10000, "currency": "EUR", "received": 0 } ], "reason": "counterpartyAccountNotFound", "status": "returned", "transactionId": "EVJN42271114222B5JB8BRC76N686ZHBG", "type": "accounting", "valueDate": "2023-03-01T12:58:25+01:00" } ], "id": "6JKRLZ8LOT47J7RY", "paymentInstrument": { "description": "Your user IBAN linked to the payment instrument", "id": "PI32272223226J5K6KR474CVJ" }, "reason": "approved", "reference": "Your user reference for the transfer", "referenceForBeneficiary": "Your user reference for the beneficiary", "sequenceNumber": 4, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "status": "returned", "type": "bankTransfer" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ### Return reason Adyen includes a `reason` in the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook event to keep you informed about why the transfer was returned. The [return reason codes](#return-reason-codes) are based on the response Adyen receives from the user's bank. Some reasons indicate temporary issues that can be resolved when you retry the transfer. Others signify a permanent problem with the user's bank account details and require new bank details before you retry. Adyen blocks subsequent transfer attempts when a reason code indicates a permanent issue. When a transfer instrument is blocked, new transfer requests made with the user's bank account fail with a 422, "[Transfers to counterparty bank account is blocked.](/platforms/custom-payouts/on-demand-payouts#transfers-to-counterparty-bank-account-is-blocked)" error. Refer to the [reason codes](#return-reason-codes) table below for a list of reason codes we recommend to retry. ### Reason codes The following table describes the reasons why a transfer may be rejected or returned by the counterparty's bank. | Reason code | Description | Remediating action | | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | `amountLimitExceeded` | The counterparty's bank or the payment system rejected this transfer because the value is too high. | Retry the transfer with a lower amount or with a different route. | | | `counterpartyBankUnavailable` | The counterparty's bank is unavailable for real-time processing. | Retry the transfer later or with a different route. | | | `counterpartyAccountNotFound` | The counterparty's bank is unable to locate the account with the provided details. | Check the bank account details provided in the transfer and retry. | | | `counterpartyAccountClosed` | The counterparty's bank reported that the account exists, but it is closed. | Check the bank account details provided in the transfer and retry. | | | `counterpartyAccountBlocked` | The counterparty's bank reported that the account is blocked or suspended. | Check the bank account details provided in the transfer and retry. | | | `counterpartyAddressRequired` | The counterparty's bank requires the account holder's address to credit this transfer to the account. | Retry the transfer with full street address. | | | `counterpartyBankTimedOut` | The counterparty's bank timed out while trying to process this request in real-time. | Retry the transfer later or with a different route. | | | `declinedByTransactionRule` | Adyen declined the transfer because it did not comply with one or more [transaction rules](/business-accounts/transaction-rules/) set by you or Adyen. | Check the transaction rules that are blocking the transfer to confirm if this outcome is expected. If this is not the expected outcome, try updating your transaction rules. | | | `refusedByCounterpartyBank` | The counterparty's bank refused the transfer without providing any further information regarding the underlying reason. | Check the bank account details provided in the transfer and/or contact the counterparty's bank. | | | `unknown` | No specific reason is known by Adyen for the failure, or the reported reason does not correspond to any of the codes above. | Check the bank account details provided in the transfer and retry. If problem persists, further manual investigation might be needed. | | ## See also * [Receive funds](/business-accounts/receive-funds) * [Send funds](/business-accounts/send-funds) * [SEPA direct debit](/business-accounts/receive-funds#receive-direct-debit) * [Transaction rules](/business-accounts/transaction-rules) --- # Source: https://docs.adyen.com/business-accounts/transaction-rules.md Section: Business accounts Title: Use transaction rules Description: Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes. --- title: "Use transaction rules" description: "Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes." url: "https://docs.adyen.com/business-accounts/transaction-rules" source_url: "https://docs.adyen.com/business-accounts/transaction-rules.md" canonical: "https://docs.adyen.com/business-accounts/transaction-rules" last_modified: "2022-04-04T12:45:00+02:00" language: "en" --- # Use transaction rules Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes. [View source](/business-accounts/transaction-rules.md) **Limited availability**\ Transaction rules for business accounts are currently in pilot phase. Some of the processes and documentation may change as the feature evolves. If you are interested in piloting transaction rules or have any feedback, reach out to your Adyen contact. *** When your users send funds to third party bank accounts, you can protect your balance platform from risk by evaluating and declining suspicious transfer requests. You can use transaction rules to configure a logic that automatically declines an outgoing transfer that does not meet your business' requirements. We recommend that you use transaction rules to make decisions based on request data and static conditions: for example, a fixed list of banks that your user must not pay out funds to. ## Transaction rule creation When creating transaction rules, you must determine the following: 1. **Criteria**: The [criteria](#criteria) that determine when a transfer is evaluated with the rule. For example, if the transfer occurs in a specific time interval or if it applies to a specific resource in your balance platform. To define the rule criteria, you must consider the following: | Criterion | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Request type | Defines the `type` of transfer request to which you want to apply the rule. For transfers to third parties, set this to **bankTransfer**. | | [Rule type](#rule-types) | Defines what data the rule must use to analyze the transfer and check whether it meets the conditions. The rule either uses only the data of the current transfer being analyzed, or uses accumulated data from previous transfers. | | [Time interval](#time-intervals) | Defines the time period in which a transfer must meet the rule conditions. | | [Entity](#entity) | Defines the balance platform resource to which the rule applies. | 2. **Conditions**: The [conditions](#conditions) that a transfer must meet for the rule's outcome to be applied. For example, if it contains certain request data. 3. **Outcome**: The outcome to apply when the transfer is evaluated and meets the conditions of the rule, such as to decline the transfer. This is called a hard-block outcome. ## How it works 1. You create a transaction rule by defining the criteria, conditions, and outcome. 2. Your user makes an outgoing transfer to a third-party bank account. 3. If the transfer meets the criteria of the transaction rule, Adyen evaluates the transfer using the rule. 4. If the transfer meets the conditions defined in the transaction rule, Adyen applies the outcome of the rule. ## Criteria ### Rule types The rule type defines what data the rule uses to analyze and decide the outcome of a transfer request. Adyen can use the data of the current transfer, or use accumulated data from previous transfers. The following rule types are available: * Blocklist: decline a transfer if it meets the specified [conditions](#conditions). For example, block all transactions where the counterparty is **Bank 123**. * Velocity: decline a transfer if a set amount of accumulated previous transfers have met the specified [conditions](#conditions). Adyen only considers previous transfers within a specified [time interval](#time-intervals). You can only [accumulate transfers](#accumulate-data) at the balance account level. ### Time intervals The time interval defines the period when the rule conditions and outcome apply. When using a **velocity** [rule type](#rule-types) which looks at accumulated data, the time interval also determines when the accumulated count or value is reset. The interval also determines when counters are reset if the rule is accumulating data. The following types of time intervals are available: | Type of time interval | Description | Example | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Per transaction** | The rule only uses data from the current transfer to make a decision. The outcome also applies only to the current transfer request. | You can set a rule that allows a user to transfer a maximum of EUR 5000 per transfer request. | | **Fixed interval** | The rule uses data from transfers made within the specified time interval, such as the ongoing day, week, or month. The outcome applies to the current transfer and all following transfers until the end of the interval. | You can set a rule that allows a user to transfer a maximum of EUR 1000 from their account in a day. In this case, Adyen accumulates the data of all the outgoing transfers from that account within the current day. If the user exceeds the EUR 1000 limit, all subsequent transfer request are declined until the next day. | | **Rolling interval** | The rule uses conditions that are applied and counters are reset based on a start time, timezone, and duration that you define. The outcome applies to the current transfer and all following transfers until the end of the interval. | You can set a rule that allows a user to transfer a maximum of EUR 5000 from their account within a week. You can specify a schedule for that week that starts every Monday, for a duration of seven days. If the user exceeds the EUR 5000 limit, all subsequent transfer requests are declined until the start of the next week. | | **Sliding interval** | The rule uses data from transfers that occurred within a specified time interval previous to the current transfer. For example, Adyen can check transfers made in the previous minutes, hours, or days. The outcome applies to the current transfer and all following transfer requests until the specified interval ends. | You can set a rule that allows a user to make a maximum of five transfer requests within an hour. If the user makes five transfer requests in less than an hour, all subsequent transfers are declined until the next hour. | ### Entity to which the rule applies Each transaction rule must be applied to only one resource. You can apply a transaction rule to any of the following resources: * A balance account (business account): the rule applies to a business account. * An account holder: the rule applies to all business accounts linked to an account holder. * A balance platform: the rule applies to all business accounts and account holders on your balance platform. If multiple rules apply to an account, Adyen prioritizes the rules according to the [hierarchy of transaction rules](#hierarchy-for-transaction-rules). #### Aggregating total amount or number of transactions If you choose the [velocity rule type](#rule-types), the transfer data is always accumulated and aggregated at the balance account level, in the time interval you specified. For example, you can set a maximum total amount for the aggregated total of all transfers linked to a balance account in the past 24 hours. When aggregating amounts, we convert all transfer amounts to the default currency of the account holder or balance platform. ## Conditions Conditions define the data that a transfer must contain for the outcome to be applied. Transaction rules check whether the transfer meets all of the conditions before accepting or declining the transfer. We refer to these conditions as *rule restrictions*. A rule restrictions consists of the following: * `value`: one or more types of transfer data that a transfer must or must not contain, such as the country code, the merchant category code, or the start time and end time. * `operation`: the operation type, which determines how a transfer's data must be evaluated against the values specified in the `value` array. For example: * The transfer's merchant category code can *Match any* of the codes you specify in `value`. * The transfer's country code *Does not match* any of the country codes you specify in `value`. * The total amount of the transfer *Equals*, is *greater than or equal to*, or is *less than* the total amount you specify in `value`. | Rule restriction name | Available values | Available operation types | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `counterpartyAccounts` | - `type`: iban, numberAndBic, auLocal, czLocal, noLocal, plLocal, huLocal, seLocal, sgLocal, ukLocal, usLocal, brLocal, dkLocal, caLocal, nzLocal, hkLocal. | anyMatch, noneMatch | Evaluates whether the counterparty's bank account type in the transfer request matches the account types specified in `counterpartyAccount.value`. | | `counterpartyBank` | * `country`: two-character ISO 3166-1 alpha-2 country code. * `identification`: the bank identification code. * `identificationType`: iban, routingNumber, sortCode, bic. | anyMatch, noneMatch | Evaluates whether the bank account details of the counterparty in the transfer request match the details specified in `counterpartyBank.value`. | | `counterpartyCountries` | Two-character ISO 3166-1 alpha-2 country code. | anyMatch, noneMatch | Evaluates whether the counterparty's country in the transfer request matches any of the countries specified in `counterpartyCountries.value` | | `counterpartyNames` | Array of allowed counterparty names. | anyMatch, noneMatch | Evaluates whether the counterparty's name in the transfer request matches any of the counterparty names specified in `counterpartyNames.value` | | `descriptions` | Array of allowed transfer descriptions. | anyMatch, noneMatch | Evaluates whether the transfer's `description` matches any of the descriptions specified in `descriptions.value`. | | `matchingTransactions` | An integer indicating the total number of allowed transactions. | equals, notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan | Evaluates the total number of transfers against the number specified in `matchingTransactions.value`. | | `percentageOfAvailableBalance` | An integer between 0 and 100 | notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan | Evaluates the amount of the transfer as a percentage of the available balance in the balance account, and compares it to the percentage specified in `percentageOfAvailableBalance.value`. | | `platformActions` | intraBank, instant, fast, regular, crossBorder | anyMatch, noneMatch | Evaluates whether the priority of a transfer matches any of the priorities specified in `platformActions.value` | | `sameAmountRestriction` | true, false | equals | Can only be used together with `matchingTransactions`. Evaluates whether the number of transfer requests with the same amount exceeds the number specified in `matchingTransactions.value` | | `sameCounterpartyRestriction` | true, false | equals | Can only be used together with `matchingTransactions`. Evaluates whether the number of transfer requests with the same counterparty exceeds the number specified in `matchingTransactions.value` | | `sourceAccountTypes` | businessAccount | anyMatch, noneMatch | Evaluates whether the type of the source account in the transfer matches any of the account types specified in `sourceAccountTypes.value`. | | `totalAmount` | - `currency`: The three-character ISO currency code. - `value`: total allowed amount, in minor units. | notEquals, greaterThanOrEqualTo, greaterThan, lessThanOrEqualTo, lessThan | Evaluates the total amount of all transfers against the amount specified in `totalAmount.value`. | ## Outcome The outcome determines what Adyen does when a transaction meets the conditions of a rule. Currently, you can only select a **hardBlock** outcome type. This means that a transaction is declined when it meets the conditions of a rule ## Hierarchy for transaction rules You can create a rule with one or more conditions, and apply one or more rules to an entity. When your user makes a transfer, Adyen evaluates all of the applicable rules. ### Multiple conditions If you have multiple conditions within one rule, Adyen applies the outcome if the transfer meets all the conditions within the rule. ### Multiple rules If you have multiple rules tied to an entity, Adyen evaluates all the rules. If the transaction meets the condition of at least one rule with a **hardBlock** outcome type, we decline the transaction. You can create transaction rules that override other transaction rules in specific circumstances, such as for a specific balance platform resource. For more information, see [Override a transaction rule](/business-accounts/transaction-rules/create-and-manage#override-an-existing-transaction-rule). ## Get updates when a rule is triggered To get updated about payouts that are declined because they triggered one or more transaction rules, you can use either webhook notifications or the Customer Area: * Subscribe to the [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview). The [transactionRulesResult](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-transactionRulesResult) object contains the details of all the transactions rules that the payout triggered. The [reason](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-reason) field returns **declinedByTransactionRule**. * In your [Customer Area](https://ca-test.adyen.com/), go to **Transactions** > **Transfers**, and click on a declined transfer. You can see all the transactions rules that the transfer triggered. ## Next steps [required](/business-accounts/transaction-rules/create-and-manage/) [Create transaction rules](/business-accounts/transaction-rules/create-and-manage/) [Send an API request to create transaction rules.](/business-accounts/transaction-rules/create-and-manage/) --- # Source: https://docs.adyen.com/business-accounts/transaction-rules/create-and-manage.md Section: Business accounts Title: Create and manage rules Description: Use transaction rules to automatically approve or decline an outgoing transfer from business accounts. --- title: "Create and manage rules" description: "Use transaction rules to automatically approve or decline an outgoing transfer from business accounts." url: "https://docs.adyen.com/business-accounts/transaction-rules/create-and-manage" source_url: "https://docs.adyen.com/business-accounts/transaction-rules/create-and-manage.md" canonical: "https://docs.adyen.com/business-accounts/transaction-rules/create-and-manage" last_modified: "2021-05-31T18:10:00+02:00" language: "en" --- # Create and manage rules Use transaction rules to automatically approve or decline an outgoing transfer from business accounts. [View source](/business-accounts/transaction-rules/create-and-manage.md) After you determine your business' requirements for evaluating and declining suspicious payout requests, you can use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) to create and manage transaction rules that automatically evaluate every external payout. This page explains how to: * [Create a transaction rule](#create-a-transaction-rule) * [View existing transaction rules](#view-transaction-rules) * [Override existing transaction rules](#override-an-existing-transaction-rule) * [Update a transaction rule](#update-a-transaction-rule) ## Requirements | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Adyen Payouts | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have access to the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) with following role:- **Bank Manage TransactionRules role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- [**Transfer webhooks**](/payouts/payout-service/pay-out-to-bank-accounts/payout-webhooks/) - [**Transaction webhooks**](/payouts/payout-service/transfer-transactions/transaction-webhooks/) | | **Limitations** | Transaction rules are not supported for [internal transfers](/payouts/payout-service/internal-fund-transfers/). | | **Setup steps** | Before you begin:- Make sure you are familiar with [how transaction rules work](/business-accounts/transaction-rules) | ## Create a transaction rule When you have defined your business logic and requirements, turn your requirements into a transaction rule. 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/transactionRules) request, specifying the following parameters: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [aggregationLevel](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-aggregationLevel) | | The [level at which the data is accumulated](/business-accounts/transaction-rules#accumulate-data) when selecting the velocity rule type. You can only set this to **balanceAccount**. | | [description](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-description) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your description for the rule. Maximum length: 300 characters. This reference is displayed in the [Customer Area](https://ca-test.adyen.com/). | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object that contains the ID and type of resource to which you want to apply the rule. | | [interval](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-interval) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The time period or duration when you want to apply the rule. | | [outcomeType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-outcomeType) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The outcome that is applied if the transfer meets the conditions of the rule. Set this to **hardBlock**. | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-reference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the rule. Maximum length: 150 characters. This description is displayed in the [Customer Area](https://ca-test.adyen.com/). | | [requestType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-requestType) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of transfer to which you want to apply the rule. Set this to **bankTransfer**. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An object that contains a combination of values and operations that a must meet in order to be accepted or declined. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-type) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of rule that determines what data to analyze.- **blockList**: decline a transfer if it meets specific conditions. - **velocity**: decline a transaction if a set amount of accumulated previous transactions have met the specified conditions. Adyen only considers previous transactions within a specified time interval and aggregation level. | | [startDate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-startDate) | | Specifies a date and time in the future when the rule must be evaluated. For example, **2022-02-25T07:00:00+01:00**. When you specify a start date, the rule is created with a `status` set to **active**. | | [endDate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-endDate) | | Specifies a date and time in the future when the rule evaluation must stop. For example, **2022-12-18T10:15:30+01:00**. If not provided, the rule is evaluated until the `status` is set to **inactive**. | | [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-status) | | Set to **active** if you want to start evaluating the rule. When you set the status to active, we automatically set the `startDate` to the current time. | Let's take the following requirement for example: * Set a hard-block limit for a daily maximum outgoing transfer amount of EUR 500K. Here is an example of how to create a transaction rule for the requirement above. **Create transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Daily limit for outgoing bank transfers{/hint}", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 50000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "businessAccount" ] } }, "status": "active", "type": "velocity" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. If your users tries to transfer more than EUR 500K over a day, those transfers will be blocked. **Response** ```json { "description": "Daily limit for outgoing bank transfers", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 50000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "businessAccount" ] } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "id": "TR00000000000000000000001" } ``` ## View transaction rules To view the transaction rules you have created, use the following API requests: | Purpose | Endpoint | Path parameter | | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | - | | Get the details of a specific rule | GET [/transactionRules/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/transactionRules/{transactionRuleId}) | Specify the `id` of the transaction rule in the path. | | | Get a list of all transaction rules configured on a balance account | GET  [/balanceAccounts/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/balanceAccounts/\(id\)/transactionRules) | Specify the `id` of the balance account in the path. | | | Get a list of all transaction rules configured for an account holder | GET  [/accountHolders/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/accountHolders/\(id\)/transactionRules) | Specify the `id` of the account holder in the path. | | | Get a list of all transaction rules configured on your balance platform | GET  [/balancePlatforms/{id}/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/2/get/balancePlatforms/\(id\)/transactionRules) | Specify the `id` of the balance platform in the path. | | ## Override an existing transaction rule When you have multiple transaction rules, Adyen applies these rules based on the existing [rule hierarchy](/business-accounts/transaction-rules#hierarchy-for-transaction-rules). To override this hierarchy for a specific resource or entity, you can create a new rule for that entity that overrides an existing rule with a higher hierarchical ranking. To create a transaction rule that overrides an existing rule for a specific entity: 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules) request. In addition to other parameters required to [create a rule](#create-a-transaction-rule), specify the following: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains the ID and [type](/issuing/authorisation/transaction-rules#entity) of entity for which you want to override a rule. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The new rule restrictions you want to apply to the entity. | | `overridesRule` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID of the transaction rule you want to override for the entity. | In the [previous example](#create-transaction-rule-request-outgoing-transfers), we created a transaction rule that sets a maximum daily limit of EUR 500K for all balance accounts. Now, let's override this rule to allow a higher limit of EUR 800K for just one balance account. **Override a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Allow higher daily outgoing transfer limit of EUR 800K for BA00000000000000000000001{/hint}", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "businessAccount" ] } }, "status": "active", "type": "velocity", "overridesRule": "TR00000000000000000000001" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. **Response** ```json { "description": "Allow higher daily outgoing transfer limit of EUR 800K for BA00000000000000000000001", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } }, "sourceAccountTypes": { "operation": "anyMatch", "value": [ "businessAccount" ] } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "overridesRule": "TR00000000000000000000001", "id": "TR00000000000000000000002" } ``` ### Skip a transaction rule You can override a rule by skipping it entirely for specific entities. This means that the rule no longer applies to that entity. To skip a transaction rule for an entity: 1. Make a POST [/transactionRules](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules) request. In addition to other parameters required to [create a rule](#create-a-transaction-rule), specify the following: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [entityKey](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-entityKey) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains the ID and type of entity for which you want to skip a rule. | | [ruleRestrictions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-ruleRestrictions) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Leave this empty. | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/transactionRules#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The rule type. Set this to **bypass**. | | `overridesRule` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The ID of the transaction rule you want to skip for the entity. | In the [previous example](#create-transaction-rule-request-payouts), we created a transaction rule that sets a maximum daily limit of EUR 500K for all balance accounts. Now, let's skip this rule for just one balance account, so that it has no maximum daily transfer limit. **Skip a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "description": "{hint:Human-readable rule description}Skip outgoing transfer limit for BA00000000000000000000001{/hint}", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "reference": "{hint:Your unique identifier for this resource}YOUR_REFERENCE{/hint}", "requestType": "bankTransfer", "ruleRestrictions": {}, "status": "active", "type": "bypass", "overridesRule": "TR00000000000000000000001" }' ``` 2. Note the response, which contains the new **transactionRule** resource, identified by its unique `id`. **Response** ```json { "description": "Skip outgoing transfer limit of EUR 500K for BA00000000000000000000001", "entityKey": { "entityReference": "BA00000000000000000000001", "entityType": "balanceAccount" }, "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": {}, "status": "active", "type": "bypass", "overridesRule": "TR00000000000000000000001", "id": "TR00000000000000000000002" } ``` ## Update a transaction rule To update a transaction rule: 1. Make a PATCH [/transactionRules/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/patch/transactionRules/{transactionRuleId}) request, specifying the `id` in the path. In the request body, specify the parameters and rule restrictions you want to update. You can activate or deactivate a transaction rule by updating the value for `status`: | Possible value | Description | | -------------- | ------------------------------- | | **active** | Activate the transaction rule | | **inactive** | Deactivate the transaction rule | In the [previous example](#create-transaction-rule-request-outgoing-transfers), we created a transaction rule that sets a maximum daily outgoing transfer limit of EUR 500,000 for all balance accounts in your balance platform. Now, let's update the transaction rule to increase the daily limit to EUR 800,000. **Update a transaction rule** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules/TR00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } } }' ``` 2. The response returns the updated transaction rule. **Response** ```json { "description": "Daily limit for bank transfers", "entityKey": { "entityReference": "YOUR_BALANCE_PLATFORM", "entityType": "balancePlatform" }, "interval": { "type": "daily" }, "outcomeType": "hardBlock", "reference": "YOUR_REFERENCE", "requestType": "bankTransfer", "ruleRestrictions": { "totalAmount": { "operation": "greaterThan", "value": { "currency": "EUR", "value": 80000000 } } }, "startDate": "2023-09-20T00:00:00+01:00", "status": "active", "type": "velocity", "id": "TR00000000000000000000001" } ``` ## See also * [Track transactions](/business-accounts/transactions) * [Use transfer limits](/business-accounts/use-transfer-limits) --- # Source: https://docs.adyen.com/business-accounts/transactions.md Section: Business accounts Title: Track transactions related to third-party transfers Description: Use our API to get updates about transactions with third-party bank accounts. --- title: "Track transactions related to third-party transfers" description: "Use our API to get updates about transactions with third-party bank accounts." url: "https://docs.adyen.com/business-accounts/transactions" source_url: "https://docs.adyen.com/business-accounts/transactions.md" canonical: "https://docs.adyen.com/business-accounts/transactions" last_modified: "2023-09-07T13:26:00+02:00" language: "en" --- # Track transactions related to third-party transfers Use our API to get updates about transactions with third-party bank accounts. [View source](/business-accounts/transactions.md) You can use the [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) to query the [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) endpoint and get transaction details on demand. You can query transactions for your whole balance platform, a particular account holder, or balance account. ## Requirements | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model/), [Issuing](/issuing/account-structure-resources/issuing-enterprise/), or [Payouts](/payouts/payout-service/) integration. | | **API credentials** | You must have the credentials and the following roles for the [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview). Ensure that you have asked your Adyen contact to assign the following role to your API credential::- **TransferService Webservice Retrieve role** role - Transfers must also be enabled for the source balance account. | ## Use cases By leveraging this API, you can monitor and manage both internal and external transfers efficiently, ensuring accurate record keeping. Examples of these types of transfers are: * A payment from a purchase in your balance platform. * A payout to one of your users. With the Transactions API, you can query the transactions for your whole balance platform, a particular account holder, or balance account. ## Get a list of transactions To get a list of transactions, related to a balance account, account holder, or balance platform: 1. Make a GET  [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) request with the following query parameters. | Parameter | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [balancePlatform](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-balancePlatform), [accountHolderId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-accountHolderId), or [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You must include at least one of the following in your request:- [balancePlatform](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-balancePlatform): The unique identifier of the balance platform. - [accountHolderId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-accountHolderId): The unique identifier of the account holder. - [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-balanceAccountId): The unique identifier of the balance account. | | [createdSince](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-createdSince) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transactions created after this date and time are included in the response. The value must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, **2021-05-30T15:07:40Z**. | | [createdUntil](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-createdUntil) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transactions created before this date and time are included in the response. The value must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, **2021-05-30T15:07:40Z**. | | [limit](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-limit) | | The number of items returned per page. | | [sortOrder](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-sortOrder) | | The transactions sorting order. | | [cursor](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-cursor) | | The cursor returned in the `links` of the previous response. | | [paymentInstrumentId](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions#query-paymentInstrumentId) | | The unique identifier of the payment instrument. | **Example GET /transactions request** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transactions?accountHolderId=AH00000000000000000000001&createdUntil=2021-10-05&limit=4&accountHolder&createdSince=2015-10-01 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request TransactionsApi service = new TransactionsApi(client); TransactionSearchResponse response = service.getAllTransactions("String", "String", "String", "String", "String", LocalDateTime.parse("2025-01-01T15:00:00");, LocalDateTime.parse("2025-01-01T15:00:00");, 1, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('balancePlatform' => 'string', 'paymentInstrumentId' => 'string', 'accountHolderId' => 'string', 'balanceAccountId' => 'string', 'cursor' => 'string', 'createdSince' => 'date-time', 'createdUntil' => 'date-time', 'limit' => 'integer'); // Send the request $service = new TransactionsApi($client); $response = $service->getAllTransactions($requestOptions); ``` #### C\# ```cs // Adyen .net API Library v27.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TransactionsService(client); var response = service.GetAllTransactions(balancePlatform: "string", paymentInstrumentId: "string", accountHolderId: "string", balanceAccountId: "string", cursor: "string", createdSince: DateTime.Parse("2025-01-01T15:00:00"), createdUntil: DateTime.Parse("2025-01-01T15:00:00"), limit: 1); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` #### Go ```go // Adyen Go API Library v16.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v16/src/common" "github.com/adyen/adyen-go-api-library/v16/src/adyen" "github.com/adyen/adyen-go-api-library/v16/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Transfers() req := service.TransactionsApi.GetAllTransactionsInput() req = req.BalancePlatform("string").PaymentInstrumentId("string").AccountHolderId("string").BalanceAccountId("string").Cursor("string").CreatedSince(DateTime.Parse("2025-01-01T15:00:00")).CreatedUntil(DateTime.Parse("2025-01-01T15:00:00")).Limit(1) res, httpRes, err := service.TransactionsApi.GetAllTransactions(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. query_parameters = { "balancePlatform" : "string", "paymentInstrumentId" : "string", "accountHolderId" : "string", "balanceAccountId" : "string", "cursor" : "string", "createdSince" : "date-time", "createdUntil" : "date-time", "limit" : "integer" } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :balancePlatform => 'string', :paymentInstrumentId => 'string', :accountHolderId => 'string', :balanceAccountId => 'string', :cursor => 'string', :createdSince => 'date-time', :createdUntil => 'date-time', :limit => 'integer' } # Send the request result = adyen.transfers.transactions_api.get_all_transactions(query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransactionsApi.getAllTransactions("string", "string", "string", "string", "string", Date.now(), Date.now(), 1); ``` 2. The response includes: * `data`: an array containing all the transactions that match the query parameters. * `_links`: an object containing links to the next or previous page when applicable. To page through the results, add the `cursor` value as a query parameter in your next request. **Example GET /transactions response** ```json { "data": [ { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-10T14:51:20+02:00", "description": "Your description for the payout", "id": "EVJN42272224222B5JB8BRC84N686ZEUR", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": -1000 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-10T14:51:33+02:00", "status": "booked", "transfer": { "categoryData": { "priority": "regular", "type": "bank" }, "id": "3JNC3O5ZVFLLGV4B", "reference": "Your internal reference for the transfer" }, "referenceForBeneficiary": "Your reference sent to the beneficiary", "valueDate": "2023-08-10T14:51:20+02:00" }, { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-10T15:34:31+02:00", "description": "Your description for the transfer", "id": "EVJN4227C224222B5JB8G3Q89N2NB6EUR", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": 123 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-10T15:34:40+02:00", "status": "booked", "transfer": { "id": "48POO45ZVG11166J", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-10T15:34:31+02:00" }, { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-11T13:45:46+02:00", "description":"Your description for the transfer", "id": "EVJN4227C224222B5JBD3XHF8P3L8GUSD", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": -10000 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-11T13:45:57+02:00", "status": "booked", "transfer": { "categoryData": { "priority": "internal", "type": "internalTransfer" }, "id": "48RTTW5ZVT8KU9DV", "reference": "The sender's reference for the transfer" }, "valueDate": "2023-08-11T13:45:46+02:00" }, { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-08-11T13:45:51+02:00", "description": "The sender's description for the transfer", "id": "EVJN42272224222B5JBD3XJGHF4J26USD", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": 1000 }, "balanceAccount": { "description": "Your description for the account holder", "id": "BA00000000000000000000001" }, "bookingDate": "2023-08-11T13:45:58+02:00", "status": "booked", "transfer": { "id": "48TYZO5ZVT8M1K47", "reference": "The sender's reference for the transfer" }, "valueDate": "2023-08-11T13:45:51+02:00" } ], "_links": { "next": { "href": "https://balanceplatform-api-test.adyen.com/btl/v4/transactions?balancePlatform=TestBalancePlatform&createdUntil=2023-08-20T13%3A07%3A40Z&createdSince=2023-08-10T10%3A50%3A40Z&cursor=S2B-c0p1N0tdN0l6RGhYK1YpM0lgOTUyMDlLXElyKE9LMCtyaFEuMj1NMHgidCsrJi1ZNnhqXCtqVi5JPGpRK1F2fCFqWzU33JTojSVNJc1J1VXhncS10QDd6JX9FQFl5Zn0uNyUvSXJNQTo" } } } ``` If you only want to get details of a specific transaction, include the `transactionId` in your GET  [/transactions/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/\(id\)) request. ## Identify incoming and outgoing funds Refer to the following fields and objects of the API response to find out if a transaction is outgoing or incoming. | Field | Incoming funds | Outgoing funds | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-amount) | Has a positive [value](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-amount-value), meaning funds are added to the balance account. | Has a negative [value](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-amount-value), meaning funds are deducted from the balance account. | | [/data.transfer.reference](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-transfer-reference) | The reference from the sender, if they sent any. | The reference that you sent in the `/transfers` request. | | [status](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-status) | The status of the transaction. It can be: - **pending**: The funds have not been added yet to the balance account. Check the [valueDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-valueDate) to know when the funds will be available. - **booked**: The funds have been added to the balance account. | The status of the transaction. It can be: - **pending**: The funds are reserved to be deducted from the balance account. Check the [valueDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-valueDate) to know when the funds will be deducted. - **booked**: The funds have been deducted from the balance account. | Both incoming and outgoing transactions can be a result of [external](#external-transactions) or [internal](#internal-transactions) transfers. The following subsections show example responses for external and internal transactions ### External transactions These transactions result from external transfers. For example: * An [outgoing transfer](/business-accounts/send-funds) that your user makes to pay their suppliers. * An [incoming transfer](/business-accounts/receive-funds) that your user receives from a business-related transaction. ### Tab: Example of an outgoing external transaction After making a successful GET  [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) or GET  [/transactions/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/\(id\)) request, you get the following information: **Outgoing external transaction** ```json { "id": "EVJN00000000000000000000000002EUR", "amount": { "value": -10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "priority": "regular", "type": "bank" }, "id": "48TYZO5ZVURJ2FCW", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:19:39+02:00", "creationDate": "2023-08-11T16:19:35+02:00", "description": "Your description of the transfer", "referenceForBeneficiary": "Your reference for the beneficiary of the transfer", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" } ``` ### Tab: Example of an incoming external transaction After making a successful GET  [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) or GET  [/transactions/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/\(id\)) request, you get the following information: **Incoming external transaction** ```json { "id": "EVJN00000000000000000000000001EUR", "amount": { "value": 10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "modificationMerchantReference": "MRef#000001", "modificationPspReference": "PPKFQ89R6QRXGN82", "paymentMerchantReference": "Payment reference", "platformPaymentType": "BalanceAccount", "pspPaymentReference": "CWBC43ZX2VTFWR82", "type": "platformPayment" }, "id": "3JW8PC5ZVV06067J", "reference": "automatically-generated-reference" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:43:46+02:00", "creationDate": "2023-08-11T16:43:46+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" } ``` ### Internal transactions These transactions result from internal transfers. For example: * [Internal transfers](/platforms/internal-fund-transfers) between balance accounts. * [Internal direct debits](/business-accounts/transfer-funds-internally). ### Tab: Example of an outgoing internal transaction After making a successful GET  [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) or GET  [/transactions/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/\(id\)) request, you get the following information: **Outgoing internal transaction** ```json { "id": "EVJN00000000000000000000000002EUR", "amount": { "value": -10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "type": "internal" }, "id": "48TYZO5ZVURJ2FCW", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:19:39+02:00", "creationDate": "2023-08-11T16:19:35+02:00", "description": "Your description of the transfer", "referenceForBeneficiary": "Your reference for the beneficiary", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" } ``` ### Tab: Example of an incoming internal transaction After making a successful GET  [/transactions](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions) or GET  [/transactions/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/\(id\)) request, you get the following information: **Incoming internal transaction** ```json { "id": "EVJN00000000000000000000000001EUR", "amount": { "value": 10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "type": "internal" }, "id": "3JW8PC5ZVV06067J", "reference": "An internal reference for the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:43:46+02:00", "creationDate": "2023-08-11T16:43:46+02:00", "description": "The sender's description of the transfer", "referenceForBeneficiary": "The sender's reference for the beneficiary", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" } ``` ## Booking and value dates For every transaction returned in the API response, you receive two date fields: the [bookingDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-bookingDate) and the [valueDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-valueDate). These fields indicate when the funds are recorded and when they are deducted from your balance account. For example, when you transfer funds from an Adyen business account after bank cutoff times, the funds are reserved but are not yet deducted. In this scenario, the dates will be: * [bookingDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-bookingDate): The date when the funds are recorded as reserved or pending in the balance account. * [valueDate](https://docs.adyen.com/api-explorer/transfers/latest/get/transactions/#responses-200-data-valueDate): The date when the funds are deducted from or made available in the balance account. Funds are always deducted at the booked stage for outgoing transfers. --- # Source: https://docs.adyen.com/business-accounts/transactions/transaction-webhooks.md Section: Business accounts Title: Transaction webhooks Description: Find out which webhooks Adyen sends for transfers involving third-party bank accounts. --- title: "Transaction webhooks" description: "Find out which webhooks Adyen sends for transfers involving third-party bank accounts." url: "https://docs.adyen.com/business-accounts/transactions/transaction-webhooks" source_url: "https://docs.adyen.com/business-accounts/transactions/transaction-webhooks.md" canonical: "https://docs.adyen.com/business-accounts/transactions/transaction-webhooks" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Transaction webhooks Find out which webhooks Adyen sends for transfers involving third-party bank accounts. [View source](/business-accounts/transactions/transaction-webhooks.md) When a funds transfer takes place between one of your user's balance accounts and a counterparty bank account, balance account, or card, Adyen sends a transaction webhook to your server. This webhook informs your server that Adyen has deducted funds from or credited funds to your balance account. [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) can be used in combination with [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) to stay fully up to date about the status of your transfers. While a transfer webhook is sent for every status change, transaction webhooks are only sent when the funds from the transfer are credited or debited from the balance account. ## Requirements | Requirement | Description | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model/), [Issuing](/issuing/account-structure-resources/issuing-enterprise/), or [Payouts](/payouts/payout-service/) integration. | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- [Standard webhooks](/development-resources/webhooks/webhook-types#webhook-structure) - [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) (optional) - [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) | | **Setup steps** | Before you begin:- Make sure that your server can [receive and accept webhooks](/development-resources/webhooks/configure-and-manage). | ## Types of transaction webhooks The values returned in the transaction webhook can vary depending on the following factors: * Whether you are **sending funds from (outgoing)**, or **receiving funds to (incoming)**, the balance account. * Whether the transfer is **internal** or **external**. ## Sending funds (outgoing) Adyen sends webhooks for: * [Outgoing external transactions](#outgoing-external-transactions): transactions that result from [transfers to third-party bank accounts](/business-accounts/send-funds). * [Outgoing internal transactions](#outgoing-internal-transactions) (incoming internal direct debit): transactions that result from [sending funds from a balance account to another](/business-accounts/transfer-funds-internally). ### Outgoing external transactions 1. You send a POST [/transfers](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers) requesting a EUR 100.00 transfer to a third-party bank account. ** #### Outgoing external transfer request **Outgoing external transfer request** ```json { "amount": { "currency": "EUR", "value": 150000 }, "category": "bank", "priority": "regular", "balanceAccountId": "BA00000000000000000000001", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "referenceForBeneficiary": "Your reference sent to the beneficiary", "reference": "Your internal reference", "description": "Your description of the transfer" } ``` 2. After the transfer is [**booked** ](/business-accounts/third-party-transfer-webhooks/#outgoing-bank-transfer-booked), Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook with the following information: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | [accountHolder](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-accountHolder) | An object containing information about the account holder that owns the source balance account. | | [amount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-amount) | An object containing the value and currency of the transaction. | | [balanceAccount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-balanceAccount) | The balance account that sends the funds. | | [id](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-id) | The unique identifier of the transaction event. | | [transfer](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer) | An object containing information about the related transfer. | ** #### Outgoing external transaction webhook **Outgoing external transaction created** ```json { "data": { "id": "EVJN00000000000000000000000001EUR", "amount": { "value": -10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "priority": "regular", "type": "bank" }, "id": "3JNC3O5ZVFLLGV4B", "reference": "Your internal reference of the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:31:02+02:00", "creationDate": "2023-08-11T16:19:35+02:00", "description": "Your description of the transfer", "referenceForBeneficiary": "Your reference sent to the beneficiary", "accountHolder": { "id": "AH00000000000000000000001", "reference": "Your reference for the account holder", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "paymentInstrument": { "id": "PI00000000000000000000001", "description": "Your description of the payment instrument" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "environment": "test", "type": "balancePlatform.transaction.created" } ``` ### Outgoing internal transactions 1. You send a POST [/transfers](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers) requesting a EUR 100.00 transfer between two balance accounts in your platform. ** #### Outgoing internal transfer request **Internal direct debit request** ```json { "amount": { "currency": "EUR", "value": "10000" }, "balanceAccountId": "BA00000000000000000000001", "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000000002" }, "description": "Your description for the transfer", "reference": "Your internal reference for the transfer", "referenceForBeneficiary": "Your reference for the beneficiary of the transfer", "type": "internalDirectDebit" } ``` 2. After the transfer is [**booked** ](/business-accounts/third-party-transfer-webhooks/#outgoing-bank-transfer-booked), Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook with the following information: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | [accountHolder](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-accountHolder) | An object containing information about the account holder that owns the source balance account. | | [amount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-amount) | An object containing the value and currency of the transaction. | | [balanceAccount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-balanceAccount) | The balance account that receives the direct debit request and from which the funds are debited. | | [id](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-id) | The unique identifier of the transaction event. | | [transfer](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer) | An object containing information about the related transfer. | ** #### Outgoing internal transaction webhook **Outgoing internal transaction created** ```json { "data": { "id": "EVJN00000000000000000000000001EUR", "amount": { "value": -10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "type": "internal" }, "id": "48TYZO5ZVURJ2FCW", "reference": "Your internal reference for the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:19:38+02:00", "creationDate": "2023-08-11T16:19:35+02:00", "description": "Your description for the transfer", "referenceForBeneficiary": "Your reference for the beneficiary of the transfer", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder", "reference": "Your reference of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" } ``` ## Receiving funds (incoming) Adyen sends webhooks for: * [Incoming external transactions](#incoming-external-transactions): transactions that result from [receiving funds from a third-party bank account](/business-accounts/receive-funds). * [Incoming internal transactions](#incoming-internal-transactions): transactions that result from a balance account [receiving funds from another balance account](/business-accounts/transfer-funds-internally). ### Incoming external transactions After an incoming third-party transfer is [**booked** ](/business-accounts/third-party-transfer-webhooks/#incoming-bank-transfer-booked)into your user's account, Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook with the following information: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | [accountHolder](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-accountHolder) | An object containing information about the account holder that owns the target balance account. | | [amount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-amount) | An object containing the value and currency of the transaction. | | [balanceAccount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-balanceAccount) | The balance account that receives the funds. | | [id](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-id) | The unique identifier of the transaction event. | | [transfer](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer) | An object containing information about the related transfer. | ** #### Incoming external transaction webhook **Incoming external transaction created** ```json { "data": { "id": "EVJN00000000000000000000000001EUR", "amount": { "value": 10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "priority": "regular", "type": "bank" }, "id": "3JW8PC5ZVV06067J", "reference": "automatically-generated-reference" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:43:46+02:00", "creationDate": "2023-08-11T16:43:46+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description of the balance account" }, "paymentInstrument": { "id": "PI00000000000000000000001", "description": "Your description of the payment instrument" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "environment": "test", "type": "balancePlatform.transaction.created" } ``` ### Incoming internal transactions After an incoming internal transfer is [**booked** ](/business-accounts/transfer-funds-internally#3-internal-direct-debit-booked)to your user's account, Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook with the following information: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | [accountHolder](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-accountHolder) | An object containing information about the account holder that owns the target balance account. | | [amount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-amount) | An object containing the value and currency of the transaction. | | [balanceAccount](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-balanceAccount) | The balance account that sends the direct debit request and to which the funds are credited. | | [id](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-id) | The unique identifier of the transaction event. | | [transfer](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer) | An object containing information about the related transfer. | ** #### Incoming internal transaction webhook **Incoming internal transaction created** ```json { "data": { "id": "EVJN00000000000000000000000002EUR", "amount": { "value": 10000, "currency": "EUR" }, "status": "booked", "transfer": { "categoryData": { "type": "internal" }, "id": "3JW8PC5ZVV06067J", "reference": "The sender's reference of the transfer" }, "valueDate": "2023-08-11T16:19:35+02:00", "bookingDate": "2023-08-11T16:43:46+02:00", "creationDate": "2023-08-11T16:43:46+02:00", "description": "The sender's description of the transfer", "referenceForBeneficiary": "The sender's reference for the beneficiary", "accountHolder": { "id": "AH00000000000000000000001", "reference": "Your reference of the account holder", "description": "Your description of the account holder" }, "balanceAccount": { "id": "BA00000000000000000000002", "description": "Your description of the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" } ``` ## See also * [Third-party transfer webhooks](/business-accounts/third-party-transfer-webhooks) --- # Source: https://docs.adyen.com/business-accounts/transfer-funds-internally.md Section: Business accounts Title: Transfer funds internally Description: Initiate internal direct debits between your users' balance accounts. --- title: "Transfer funds internally" description: "Initiate internal direct debits between your users' balance accounts." url: "https://docs.adyen.com/business-accounts/transfer-funds-internally" source_url: "https://docs.adyen.com/business-accounts/transfer-funds-internally.md" canonical: "https://docs.adyen.com/business-accounts/transfer-funds-internally" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Transfer funds internally Initiate internal direct debits between your users' balance accounts. [View source](/business-accounts/transfer-funds-internally.md) An **internal direct debit** moves funds between balance accounts within your balance platform. For example, to collect monthly or subscription fees from your users without triggering strong customer authentication (SCA) or payment fees, you can initiate an internal debit, where your liable balance account sends a debit request to your user's balance account. As a balance platform, you can also initiate internal direct debits between the balance accounts of two different users. ## Before you begin * Make sure that your server can [receive and accept webhooks](/development-resources/webhooks), and that you subscribed to the **Transfer webhooks** in your [Customer Area](https://ca-test.adyen.com/). * Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable transfers for the balance account that debits funds. * Make sure that your account holders have the following [capabilities](/business-accounts/verification-overview/capabilities): * The account holder of the balance account that initiates the direct debit must have the **sendToBalanceAccount** capability. * The account holder of the balance account that received the request must have the **receiveFromBalanceAccount** capability. ## Initiate an internal direct debit To initiate an internal direct debit, make a POST [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers) request. In the body of the request, include the following fields: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-amount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object containing the currency and value of the transfer. | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the source balance account: the balance account that initiates the direct debit. | | [counterparty.balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-counterparty-balanceAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the target balance account: the balance account that receives the debit request. | | [category](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-category) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **internal**. | | [type](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-type) | | Set to **internalDirectDebit** to debit the funds from the counterparty balance account. | | [description](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-description) | | Your description of the transfer. You can use this to identify the transfer in the webhooks that you receive. | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-reference) | | Your unique reference for the transfer. You can use this to identify the transfer in the webhooks that you receive. | | [referenceForBeneficiary](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-referenceForBeneficiary) | | Text to inform the recipient about the push or pull transfer. This reference is also included in all webhooks. Supported characters: a-z, A-Z, 0-9. | The following example shows how to pull **USD 25** from your user's balance account to your liable balance account. **Initiate internal direct debit** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "USD", "value": 2500 }, "balanceAccountId": "BA00000000000000000LIABLE", "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "category" : "internal", "type": "internalDirectDebit", "referenceForBeneficiary": "Your-reference-sent-to-the-counterparty", "description": "YOUR_DESCRIPTION_OF_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Create the request object(s) Amount amount = new Amount() .currency("USD") .value(2500L); CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3() .balanceAccountId("BA00000000000000000000001"); TransferInfo transferInfo = new TransferInfo() .balanceAccountId("BA00000000000000000LIABLE") .reference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") .amount(amount) .referenceForBeneficiary("Your-reference-sent-to-the-counterparty") .counterparty(counterpartyInfoV3) .description("YOUR_DESCRIPTION_OF_THE_TRANSFER") .category(TransferInfo.CategoryEnum.INTERNAL) .type(TransferInfo.TypeEnum.INTERNALDIRECTDEBIT); // Send the request TransfersApi service = new TransfersApi(client); Transfer response = service.transferFunds(transferInfo, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $amount = new Amount(); $amount ->setCurrency("USD") ->setValue(2500); $counterpartyInfoV3 = new CounterpartyInfoV3(); $counterpartyInfoV3 ->setBalanceAccountId("BA00000000000000000000001"); $transferInfo = new TransferInfo(); $transferInfo ->setBalanceAccountId("BA00000000000000000LIABLE") ->setReference("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER") ->setAmount($amount) ->setReferenceForBeneficiary("Your-reference-sent-to-the-counterparty") ->setCounterparty($counterpartyInfoV3) ->setDescription("YOUR_DESCRIPTION_OF_THE_TRANSFER") ->setCategory("internal") ->setType("internalDirectDebit"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new TransfersApi($client); $response = $service->transferFunds($transferInfo, $requestOptions); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) Amount amount = new Amount { Currency = "USD", Value = 2500 }; CounterpartyInfoV3 counterpartyInfoV3 = new CounterpartyInfoV3 { BalanceAccountId = "BA00000000000000000000001" }; TransferInfo transferInfo = new TransferInfo { BalanceAccountId = "BA00000000000000000LIABLE", Reference = "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", Amount = amount, ReferenceForBeneficiary = "Your-reference-sent-to-the-counterparty", Counterparty = counterpartyInfoV3, Description = "YOUR_DESCRIPTION_OF_THE_TRANSFER", Category = TransferInfo.CategoryEnum.Internal, Type = TransferInfo.TypeEnum.InternalDirectDebit }; // Send the request var service = new TransfersService(client); var response = service.TransferFunds(transferInfo, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const transferInfo = { amount: { currency: "USD", value: 2500 }, balanceAccountId: "BA00000000000000000LIABLE", counterparty: { balanceAccountId: "BA00000000000000000000001" }, category: "internal", type: "internalDirectDebit", referenceForBeneficiary: "Your-reference-sent-to-the-counterparty", description: "YOUR_DESCRIPTION_OF_THE_TRANSFER", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER" } // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) amount := transfers.Amount{ Currency: "USD", Value: 2500, } counterpartyInfoV3 := transfers.CounterpartyInfoV3{ BalanceAccountId: common.PtrString("BA00000000000000000000001"), } transferInfo := transfers.TransferInfo{ BalanceAccountId: common.PtrString("BA00000000000000000LIABLE"), Reference: common.PtrString("YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER"), Amount: amount, ReferenceForBeneficiary: common.PtrString("Your-reference-sent-to-the-counterparty"), Counterparty: counterpartyInfoV3, Description: common.PtrString("YOUR_DESCRIPTION_OF_THE_TRANSFER"), Category: "internal", Type: common.PtrString("internalDirectDebit"), } // Send the request service := client.Transfers() req := service.TransfersApi.TransferFundsInput().IdempotencyKey("UUID").TransferInfo(transferInfo) res, httpRes, err := service.TransfersApi.TransferFunds(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "amount": { "currency": "USD", "value": 2500 }, "balanceAccountId": "BA00000000000000000LIABLE", "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "category": "internal", "type": "internalDirectDebit", "referenceForBeneficiary": "Your-reference-sent-to-the-counterparty", "description": "YOUR_DESCRIPTION_OF_THE_TRANSFER", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER" } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :amount => { :currency => 'USD', :value => 2500 }, :balanceAccountId => 'BA00000000000000000LIABLE', :counterparty => { :balanceAccountId => 'BA00000000000000000000001' }, :category => 'internal', :type => 'internalDirectDebit', :referenceForBeneficiary => 'Your-reference-sent-to-the-counterparty', :description => 'YOUR_DESCRIPTION_OF_THE_TRANSFER', :reference => 'YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER' } # Send the request result = adyen.transfers.transfers_api.transfer_funds(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Create the request object(s) const amount: Types.transfers.Amount = { currency: "USD", value: 2500 }; const counterpartyInfoV3: Types.transfers.CounterpartyInfoV3 = { balanceAccountId: "BA00000000000000000000001" }; const transferInfo: Types.transfers.TransferInfo = { balanceAccountId: "BA00000000000000000LIABLE", reference: "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", amount: amount, referenceForBeneficiary: "Your-reference-sent-to-the-counterparty", counterparty: counterpartyInfoV3, description: "YOUR_DESCRIPTION_OF_THE_TRANSFER", category: Types.transfers.TransferInfo.CategoryEnum.Internal, type: Types.transfers.TransferInfo.TypeEnum.InternalDirectDebit }; // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.transferFunds(transferInfo, { idempotencyKey: "UUID" }); ``` In the response, note the following: * `id`: the unique ID of the transfer. * `status`: the result of the transfer. * `reason`: an explanation of the status. Check this field if the status is not **authorised**.\ For example, the reason for a **refused** status can be **notEnoughBalance**. **Internal direct debit initiated** ```json { "creationDate": "2024-08-08T13:52:08+02:00", "id": "48NJIB9TWQJ6L7U7", "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000LIABLE", "reference": "Your reference for your liable account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000LIABLE", "reference": "Your reference for your liable balance account" }, "category" : "internal", "categoryData": { "type": "internalDirectDebit" }, "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "description": "YOUR_DESCRIPTION_OF_THE_TRANSFER", "direction": "outgoing", "reason": "approved", "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER", "referenceForBeneficiary": "Your-reference-sent-to-the-counterparty", "status": "authorised", "type": "internalDirectDebit" } ``` ## Get status updates For every internal transfer request, Adyen sends multiple webhooks to your server: a series of webhooks for the balance account where the transfer is an outgoing request, and a series of webhooks for the balance account where the transfer is an incoming request. Using these webhooks, you can track the status of the transfer: **received**, then **authorised**, and finally **booked**. The webhooks also inform you if the transfer failed. You can also [view the transfer details in your Customer Area](/business-accounts/view-transfers-details). Each transfer of funds between balance accounts appears in the Customer Area as two transfer entries: one for the balance account that is credited, and one for the balance account that is debited. When you initiate an internal direct debit is triggered between balance accounts in your balance platform, Adyen sends two kinds of webhooks: * [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created), that informs your server that funds will be transferred between the balance accounts. * [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated), that informs your server of changes in the status of the fund transfer. For each event you receive two sets of webhooks: * Webhooks for the source balance account, where you initiate the direct debit an outgoing request. * Webhooks for the target balance account, that received the direct debit as an incoming request. You can identify transfer webhooks triggered by internal direct debit requests by the following values: | Parameter | Description | Value | | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- | | [category](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-category) | The category of the transfer. | **internal** | | [direction](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-direction) | The direction of the transfer request. | **outgoing** for the source balance account **incoming** for the target balance account | | [type](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-type) | The type of internal transfer. | **internalDirectDebit** | For an internal direct debit, you receive webhooks for the following events: * The transfer is [initiated](#internal-direct-debit-initiated). * The transfer is [authorized](#internal-direct-debit-authorized). This indicates that the funds are reserved. * The transfer is [booked](#internal-direct-debit-booked). Expand the sections below to see the webhooks you would receive for the [example direct debit request above](#initiate-an-internal-direct-debit). ** #### 1. Internal direct debit initiated When you initiate an internal direct debit, we send you a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with `status` **received**, to inform your server that funds will be transferred between balance accounts in your balance platform. ### Tab: Source balance account For the source balance account, the webhook indicates that funds will be credited to that account: * `direction`: **outgoing** * `balances.received`: a positive amount **Outgoing transfer request received** ```json { "data": { "id": "4VXNYX62NIZEZH8S", "type": "internalDirectDebit", "accountHolder": { "description": "Your description of your liable account holder", "id": "AH00000000000000000LIABLE", "reference": "Your reference your liable account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description of your liable balance account", "id": "BA00000000000000000LIABLE" }, "balances": [ { "currency": "USD", "received": 2500 } ], "balancePlatform": "YOUR_BALANCE_PLATFORM", "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "creationDate": "2024-08-28T13:30:05+02:00", "description": "Your description of the transfer", "direction": "outgoing", "events": [ { "id": "MOCJ00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": 2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request", "sequenceNumber": 1, "status": "received" }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ### Tab: Target balance account For the target balance account, the webhook indicates that funds will be debited from that account: * `direction`: **incoming** * `balances.received`: a negative amount **Incoming transfer request received** ```json { "data": { "id": "3K6U5F62NIZJSIVI", "type": "internalDirectDebit", "accountHolder": { "description": "Your description for the account holder of the target balance account", "id": "AH00000000000000000000002", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for the target balance account", "id": "BA00000000000000000000001" }, "balances": [ { "currency": "USD", "received": -2500 } ], "balancePlatform": "YOUR_BALANCE_PLATFORM", "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000LIABLE" }, "creationDate": "2024-08-28T13:30:05+02:00", "direction": "incoming", "description": "Your description of the transfer", "events": [ { "id": "KESG00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": -2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request", "status": "received", "sequenceNumber": 1 }, "environment": "test", "type": "balancePlatform.transfer.created" } ``` ** #### 2. Internal direct debit authorized When the scheduled or on-demand internal pull transfer is authorized, Adyen sends [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhooks with `status` **authorised**, to inform your server that the funds have been reserved on the source and target balance accounts. ### Tab: Source balance account For the source balance account, the webhook indicates that the transfer amount has been reserved to be credited: * `direction`: **outgoing** * `balances.reserved`: a positive amount **Outgoing transfer authorized** ```json { "data": { "id": "4VXNYX62NIZEZH8S", "type": "internalDirectDebit", "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000LIABLE", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000LIABLE" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": 0, "reserved": 2500 } ], "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "creationDate": "2024-08-28T13:30:05+02:00", "description": "Your description of the transfer", "direction": "outgoing", "events": [ { "id": "MOCJ00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": 2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "MOCJ00000000000000000000000002", "type": "accounting", "status": "authorised", "mutations": [ { "currency": "USD", "received": -2500, "reserved": 2500, } ], "bookingDate": "2024-08-28T13:30:18+02:00" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request", "sequenceNumber": 2, "status": "authorised" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Target balance account For the target balance account, the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook indicates that the transfer amount has been reserved to be debited: * `direction`: **incoming** * `balances.reserved`: a negative amount **Incoming transfer authorized** ```json { "data": { "id": "3K6U5F62NIZJSIVI", "type": "internalDirectDebit", "accountHolder": { "description": "Your description for the account holder of the target balance account", "id": "AH00000000000000000000002", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for the target balance account", "id": "BA00000000000000000000001" }, "balanceAccountId": "BA00000000000000000000001", "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "currency": "USD", "received": 0, "reserved": -2500 } ], "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000LIABLE" }, "creationDate": "2024-08-28T13:30:05+02:00", "description": "Your description of the transfer", "direction": "incoming", "events": [ { "id": "KESG00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": -2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "KESG00000000000000000000000002", "type": "accounting", "status": "authorised", "mutations": [ { "currency": "USD", "received": 2500, "reserved": -2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request", "sequenceNumber": 2, "status": "authorised" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ** #### 3. Internal direct debit booked When the scheduled or on-demand internal pull transfer is booked, Adyen sends [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhooks with `status` **booked**, to inform your server that the funds have been pulled from the target balance account to the source balance account. ### Tab: Source balance account For the source balance account, the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook indicates that the transfer amount has been credited: * `direction`: **outgoing** * `balances.balance`: a positive amount **Outgoing transfer booked** ```json { "data": { "id": "4VXNYX62NIZEZH8S", "type": "internalDirectDebit", "accountHolder": { "description": "Your description for your liable account holder", "id": "AH00000000000000000LIABLE", "reference": "Your reference for your liable account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for your liable balance account", "id": "BA00000000000000000LIABLE" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": 2500, "currency": "USD", "received": 0, "reserved": 0 } ], "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "creationDate": "2024-08-28T13:30:05+02:00", "description": "Your description of the transfer", "direction": "outgoing", "events": [ { "id": "MOCJ00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": 2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "MOCJ00000000000000000000000002", "type": "accounting", "status": "authorised", "mutations": [ { "currency": "USD", "received": -2500, "reserved": 2500, } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "MOCJ00000000000000000000000003", "type": "accounting", "status": "booked", "mutations": [ { "balance": 2500, "currency": "USD", "received": 0, "reserved": -2500, } ], "bookingDate": "2024-08-28T13:30:18+02:00", "transactionId": "EVJN4294X224223D5KKNV5MBWJ53HFUSD" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request", "sequenceNumber": 3, "status": "booked", }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Target balance account For the target balance account, the [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook indicates that the transfer amount has been debited: * `direction`: **incoming** * `balances.balance`: a negative amount **Incoming transfer booked** ```json { "data": { "id": "3K6U5F62NIZJSIVI", "type": "internalDirectDebit", "accountHolder": { "description": "Your description for the account holder of the target balance account", "id": "AH00000000000000000000002", "reference": "Your reference for the account holder" }, "amount": { "currency": "USD", "value": 2500 }, "balanceAccount": { "description": "Your description for the target balance account", "id": "BA00000000000000000000001" }, "balancePlatform": "YOUR_BALANCE_PLATFORM", "balances": [ { "balance": -2500, "currency": "USD", "received": 0, "reserved": 0 } ], "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000LIABLE" }, "creationDate": "2024-08-28T13:30:05+02:00", "description": "Your description of the transfer", "direction": "incoming", "events": [ { "id": "KESG00000000000000000000000001", "type": "accounting", "status": "received", "mutations": [ { "currency": "USD", "received": -2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "KESG00000000000000000000000002", "type": "accounting", "status": "authorised", "mutations": [ { "currency": "USD", "received": 2500, "reserved": -2500 } ], "bookingDate": "2024-08-28T13:30:18+02:00" }, { "id": "KESG00000000000000000000000003", "type": "accounting", "status": "booked", "mutations": [ { "balance": -2500, "currency": "USD", "received": 0, "reserved": 2500 } ], "valueDate": "2024-08-28T13:30:18+02:00", "bookingDate": "2024-08-28T13:30:18+02:00", "transactionId": "EVJN42CL8224223D5KKNTXP54453VSUSD" } ], "reason": "approved", "reference": "Your reference for the transfer", "referenceForBeneficiary": "Your-reference-for-the-recipient-of-the-transfer-request" "sequenceNumber": 3, "status": "booked" }, "environment": "test", "type": "balancePlatform.transfer.updated" } ``` --- # Source: https://docs.adyen.com/business-accounts/use-transfer-limits.md Section: Business accounts Title: Use transfer limits Description: Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes. --- title: "Use transfer limits" description: "Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes." url: "https://docs.adyen.com/business-accounts/use-transfer-limits" source_url: "https://docs.adyen.com/business-accounts/use-transfer-limits.md" canonical: "https://docs.adyen.com/business-accounts/use-transfer-limits" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Use transfer limits Evaluate outgoing transfer requests from business accounts with predefined conditions and outcomes. [View source](/business-accounts/use-transfer-limits.md) Transfer limits create conditional logic that automatically approves or declines a transfer based on its amount. You can configure transfer limits for your users, to regulate outgoing fund transfers from their balance accounts. When setting up a transfer limit, you configure the following settings: * [Transfer limit validity](#transfer-limit-validity): the period in which the transfer limit is valid. * [Transfer limit conditions](#transfer-limit-conditions): the type of transfers to which the limit applies (instant or non-instant transfers, and scope of the limit (per-transaction limit or daily limit). According to regulations in the EU, you must always provide your users with the option to configure transfer limits on their outgoing, instant transfers. Your users can choose whether to use this feature. ## How it works You can configure transfer limits on two levels: * **Balance platform level**: the transfer limit applies to all balance accounts in your balance platform. This is the default transfer limit that applies when no transfer limit is configured at the balance account level. * **Balance account level**: the transfer limit applies to a specific balance account in your balance platform. This overrides any default transfer limits you configured for your balance platform. To set transfer limits at the balance account level, the balance account must be linked to an Adyen business account. When you configure a limit for your user at this level, your user must authenticate their identity using [SCA](/business-accounts/use-transfer-limits/balance-accounts#strong-customer-authentication-sca-for-transfer-limits). After a transfer limit is successfully created for your balance platform or your user's balance account, it works as follows: 1. On the start date of the transfer limit, the status of the transfer limit becomes **active**. 2. You make an outgoing transfer request to send funds to an external bank account within the timeframe that the transfer limit is active. 3. Adyen checks if the amount of the transfer exceeds the transfer limit you set. If it does, the transfer fails. 4. On the end date of the transfer limit, the status of the transfer limit becomes **inactive**, and it is no longer used to regulate outgoing transfers. ## Transfer limit validity When you create a transfer limit, you can specify a start and end date. The transfer limit is only valid for the time period between its start and end date. Note that: * If you do not specify a start date, we default to the date and time at which you send the request. * If you do not specify an end date, the transfer limit stays valid until it is overridden. ## Transfer limit status Throughout its lifecycle, a transfer limit can have four statuses: * **pendingSCA**: your user's identity needs to be authenticated using SCA before the transfer limit is processed. * **scheduled**: the transfer limit has been created, but the start date has not arrived yet. * **active**: the transfer limit has been created, and applies to all transfers within its scope. * **inactive**: the end date for the transfer limit has passed. ## Transfer limit conditions Transfer limit conditions determine which transfers a transfer limit applies to. Conditions consist of: * `scope`: determines whether the transfer limit applies to each individual transfer, or to the total amount of all transfers made in a day. * `transferType`: determines whether the transfer limit only applies to transfers with an **instant** priority, or to all transfers. You can create multiple transfer limits with different combinations of `scope` and `transferType`. At any given moment, there can only be one **scheduled** or **pendingSCA** transfer limit with the same combination of `scope` and `transferType`. To create another **scheduled** or **pending** transfer limit with the same combination, you must first [delete the existing one](/business-accounts/use-transfer-limits/balance-accounts#delete-a-transfer-limit). After a transfer limit becomes **active**, you can create a new **scheduled** or **pending** transfer limit with the same combination of `scope` and `transferType`. The new transfer limit you create then overrides the previous one when it becomes **active**. #### For example: 1. You create a transfer limit (TRLI\_1) with the following details: * Amount: EUR 100.00 * Scope: **perDay** * Transfer type: **instant**\ The start date for the transfer limit is in the future, so it has a **scheduled** status. 2. You want to schedule a new transfer limit (TRLI\_2) with the following details * Amount: EUR 200.00 * Scope: **perDay** * Transfer type: **instant** Because TRLI\_1 and TRLI\_1 have the same scope and transfer type, you cannot schedule TRLI\_2 while TRLI\_1 has a **scheduled** status. To schedule TRLI\_2, you must do either of the following: * Delete TRLI\_1 * Wait until TRLI\_1 becomes **active**. In this case, when TRLI\_2 eventually becomes active, it will override TRLI\_1. ## Get updates when a limit is triggered To get updated about transfers that are declined because they triggered a transfer limit, you can use either webhook notifications or the Customer Area: * Subscribe to the [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview). The webhook returns the following fields: * [transactionRulesResult](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-transactionRulesResult): Contains the details of the transfer limit that was triggered: * [reason](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-reason): Returns **declinedByTransactionRule**. * [reference](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-reference): Returns your reference for the transfer limit. * [description](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-description): Returns the description for the transfer limit in the format **Enforce transfer limit with code: {transferLimitId}** * In your [Customer Area](https://ca-test.adyen.com/), go to **Transactions** > **Transfers**, and click on a declined transfer. You can see the details of the transfer limit that the transfer triggered. ## Next steps Learn how to set transfer limits. [Transfer limits for balance accounts](/business-accounts/use-transfer-limits/balance-accounts) [Set a limit on outgoing transfers from your users' balance accounts.](/business-accounts/use-transfer-limits/balance-accounts) [Transfer limits for your balance platform](/business-accounts/use-transfer-limits/balance-platform) [Set a limit on outgoing transfers from your balance platform.](/business-accounts/use-transfer-limits/balance-platform) --- # Source: https://docs.adyen.com/business-accounts/use-transfer-limits/balance-accounts.md Section: Business accounts Title: Create and manage transfer limits for balance accounts Description: Set a limit on outgoing transfers from your users' balance accounts. --- title: "Create and manage transfer limits for balance accounts" description: "Set a limit on outgoing transfers from your users' balance accounts." url: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-accounts" source_url: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-accounts.md" canonical: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-accounts" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Create and manage transfer limits for balance accounts Set a limit on outgoing transfers from your users' balance accounts. [View source](/business-accounts/use-transfer-limits/balance-accounts.md) Transfer limits create conditional logic that automatically approves or declines a transfer based on its amount. When a transfer limit is configured for a balance account in your platform, it regulates the amount of funds that can be transferred externally from that balance account. To set transfer limits at the balance account level, the balance account must be linked to a payment instrument with `type` **bankAccount** (Adyen business account). ## Requirements Before you begin, make sure that you complete the following requirements: | Requirement | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Adyen for Platforms integration with business accounts. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have access to the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) with the following role:- **Balance platform base role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- [**Transfer webhooks**](/payouts/payout-service/pay-out-to-bank-accounts/payout-webhooks/) - [**Transaction webhooks**](/payouts/payout-service/transfer-transactions/transaction-webhooks/) | | **Limitations** | Transfer limits are not supported for [internal transfers](/business-accounts/transfer-funds-internally), or [incoming external transfers](/business-accounts/receive-funds). | | **Setup steps** | Before you begin, make sure that:- You are familiar with [how transfer limits work](/business-accounts/use-transfer-limits). - Your user has an [Adyen business account](/business-accounts/create-business-accounts) linked to their balance account. - You have [installed the Authentication SDK](/business-accounts/install-auth-sdk/), and [registered your users' devices for SCA](/business-accounts/register-sca-devices/). | ## Strong Customer Authentication (SCA) for transfer limits In certain regions, you are required by law to enable your users to configure transfer limits for their outgoing transfers. When creating or updating a transfer limit, your user must complete Strong Customer Authentication (SCA). [Strong Customer Authentication (SCA)](/business-accounts/implement-sca/) uses multi-factor authentication to verify your user's identity. When creating a transfer limit for your user's balance account, your user is required by law to authenticate their identity using their registered SCA device. You do not need to perform SCA when creating a transfer limit at the balance platform level. When configuring transfer limits, there are two ways to authenticate your users' identities using SCA: 1. **SCA on initiation, for each transfer limit your user creates**\ When you send a request to create a transfer limit, you must include SCA details in the request header. Your user is immediately prompted to authenticate their identity using their registered SCA device. 2. **SCA on approval, for one or more pending transfer limits**\ You send one or more requests to create transfer limits for your user without including SCA details in the request headers. These transfer limits end up in a pending state, because your user has not yet authenticated their identity. Then, you make a new request to approve all pending transfer limits, with SCA details in the request header. Your user is then prompted to authenticate their identity for all the pending transfer limit requests using their registered SCA device. ### Exemptions to SCA In some cases, your user's identity does not need to be authenticated when creating a transfer limit because of an SCA exemption. When you or your user has an SCA exemption, you must specify this in your request, along with the type of exemption that applies for that transfer limit. There are five types of SCA exemptions: * **lowerLimit**: this exemption applies when the transfer limit created by your user is lower than the transfer limit that already exists for that balance account. Because the new transfer limit has a lower risk than the previous transfer limit, there is no need for SCA. * **notRegulated**: this exemption applies when you want to use transfer limits in countries, regions, or industries where it is not mandated by law to use SCA. * **setByPlatform**: this exemption applies when *you* set a transfer limit for one of your user's balance accounts or for your entire balance platform. Because *you* are configuring the transfer limit for your users, there is no need to verify their identity using SCA. * **initialLimit**: this exemption applies when there is no transfer limit configured on the balance account, and no default transfer limit configured on the balance platform. Because having a transfer limit has a lower risk than having no transfer limit, there is no need for SCA. * **alreadyPerformed**: this exemption applies when you are already confident about your user's identity and do not need to verify this using SCA. For example, if your user already performed SCA when logging into your app, they do not need to verify their identity again when setting a transfer limit. ## How it works The flow to create a transfer limit depends on whether you trigger SCA on initiation for each request, on approval for one or more requests, or if you are exempt from SCA. ### Tab: SCA triggered on initiation 1. You create a transfer limit by making a POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) request. In your request, you must consider the scope and type of the transfer, and include SCA details in the header. You must also specify the time period in which the transfer limit is valid. 2. Your user is prompted to authenticate their identity using their registered SCA device. 3. After a successful authentication, the transfer limit is created with a **scheduled** status. 4. On the start date of the transfer limit, the status of the transfer limit becomes **active**. 5. While it is **active**, the transfer limit regulates the amount of funds being transferred externally from the balance account. 6. On the end date of the transfer limit, the status of the transfer limit becomes **inactive**. ### Tab: SCA triggered on approval 1. You create one or more transfer limits by making POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) requests. In your requests, you must consider the scope and type of the transfer. You must also specify the time period in which the transfer limit is valid. Do not include the SCA parameter in the header. 2. The transfer limits are created with a **pendingSCA** status. 3. To allow your user to authenticate their identity for all pending requests at once, make a POST [/balanceAccounts/{id}/transferLimits/approve](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve) request. Include SCA details in the header and transfer limit IDs of the transfer limits in the body. 4. Your user is prompted to authenticate their identity using their registered SCA device. 5. After a successful authentication, the transfer limit reaches a **scheduled** status. 6. On the start date of the transfer limit, the status of the transfer limit becomes **active**. 7. While it is **active**, the transfer limit regulates the amount of funds being transferred externally from the balance account. 8. On the end date of the transfer limit, the status of the transfer limit becomes **inactive**. ### Tab: Exemption from SCA 1. You create a transfer limit by making a POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) request. In your request, you must consider the scope and type of the transfer, and specify the reason for your exemption from SCA. You must also specify the time period in which the transfer limit is valid. 2. The transfer limit is created with a **scheduled** status. 3. On the start date of the transfer limit, the status of the transfer limit becomes **active**. 4. While it is **active**, the transfer limit regulates the amount of funds being transferred externally from the balance account. 5. On the end date of the transfer limit, the status of the transfer limit becomes **inactive**. ## Create transfer limits Before you create a transfer limit, you must determine: * The limit conditions (scope and transfer type), which define to which transfers the limit applies. * The start and end date, which define the time period in which the limit is active. * Whether to perform SCA on initiation or approval. Depending on how you decide to perform SCA, follow the steps in the tabs below: ### Tab: SCA on initiation When creating new transfer limits, you can choose to perform SCA immediately for each transfer limit request that you create. To do this: ** #### 1. Check SCA eligibility Before creating a transfer limit, you must check for SCA eligibility and initiate the process to authenticate your users. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript. ** #### 2. Make a request to create a transfer limit 1. Make a POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) request. Include the following parameters: | Parameter | Type | Required | Description | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **TransferLimit**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [checked SCA eligibility](#1-check-sca-eligibility). | | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | | [amount.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-value) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value, in minor units, for the transfer limit. This is the maximum amount allowed per transfer or per day based on the `scope` of the limit. | | | [amount.currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-currency) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency in which you want to set the limit. | | | [startsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-startsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes active. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify a start date, or set this to **null**, we default to the date and time of the request. If you specify a date in the future, we will schedule a transfer limit. You cannot schedule more than one limit in the future. | | | [endsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-endsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes inactive. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify an end date, the limit stays active until you override it with a new limit. | | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scope) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-reference) | Body | | Your reference for the transfer limit. | | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-transferType) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | | [scaInformation.scaOnApproval](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scaInformation-scaOnApproval) | Body | | Indicates whether to initiate Strong Customer Authentication (SCA) later, during approval, or immediately after you submit this request. Set this to **false** (default). | | Here is an example request to create a transfer limit. **Create a transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="TransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "amount": { "value": 10000 "currency: "EUR" }, "startsAt": "2025-08-14T00:00:00+01:00", "endsAt": "2026-08-14T00:00:00+01:00", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "transferType": "all", "scaInformation: { "scaOnApproval": false } } ``` 2. Verify that the response header contains the following fields: * `status`: **401** * `auth-param1`: Base64-encoded blob of data. You will need `auth-param1` when you [authenticate your user](#2-authenticate-your-user). **Response header** ```json "WWW-Authenticate: SCA realm="TransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."" ``` ** #### 3. Authenticate your user After [creating a transfer limit request](#2-make-a-request-to-create-a-transfer-limit), you have 10 minutes to complete the authentication process and [finalize the transfer limit](#4-finalize-the-transfer-limit). To authenticate your user with the Authentication SDK: 1. Trigger the SDK to start user authentication and pass the `auth-param1` value from [the previous step](#2-make-a-request-to-create-a-transfer-limit) as `sdkInput`. 2. Pass `sdkOutput` to your server. ** #### 4. Finalize the transfer limit To finalize the transfer limit: 1. Make a POST `/balanceAccounts/{id}/transferLimits` request. Include the following parameters: The values of the body parameters must match the ones previously submitted to the `/balanceAccounts/{id}/transferLimits` endpoint [when creating a transfer limit request](#2-make-a-request-to-create-a-transfer-limit). | Parameter | Type | Required | Description | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [WWW-Authenticate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **TransferLimit**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [authenticated your user](#3-authenticate-your-user). | | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | | [amount.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-value) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value, in minor units, for the transfer limit. This is the maximum amount allowed per transfer or per day based on the `scope` of the limit. | | | [amount.currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-currency) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency in which you want to set the limit. | | | [startsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-startsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes active. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify a start date, or set this to **null**, we default to the date and time of the request. If you specify a date in the future, we will schedule a transfer limit. You cannot schedule more than one limit in the future. | | | [endsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-endsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes inactive. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify an end date, the limit stays active until you override it with a new limit. | | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scope) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-reference) | Body | | Your reference for the transfer limit. | | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-transferType) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | | [scaInformation.scaOnApproval](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scaInformation-scaOnApproval) | Body | | Indicates whether to initiate Strong Customer Authentication (SCA) later, during approval, or immediately after you submit this request. Set this to **false** (default). | | Here is an example request to finalize the transfer limit. **Finalize the transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="TransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "amount": { "value": 10000 "currency: "EUR" }, "startsAt": "2025-08-14T00:00:00+01:00", "endsAt": "2026-08-14T00:00:00+01:00", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "transferType": "all", "scaInformation: { "scaOnApproval": false } } ``` 2. Verify that your response contains a `HTTP 200 - Success` response code. Take note of the transfer limit `id` and `limitStatus` that is returned in the response. The `limitStatus` must be either **active** or **scheduled** depending on the start date of the limit. **Response** ```json [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "status": "performed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ] ``` ### Tab: SCA on approval When creating one or more new transfer limits, you can choose to perform SCA on approval. This way, you user only needs to authenticate one time to approve all pending requests. To do this: ** #### 1. Check SCA eligibility Before creating a transfer limit, you must check for SCA eligibility and initiate the process to authenticate your users. The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript. ** #### 2. Make a request to create a transfer limit 1. Make a POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) request. Include the following parameters: | Parameter | Type | Required | Description | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | | [amount.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-value) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value, in minor units, for the transfer limit. This is the maximum amount allowed per transfer or per day based on the `scope` of the limit. | | | [amount.currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-currency) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency in which you want to set the limit. | | | [startsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-startsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes active. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify a start date, or set this to **null**, we default to the date and time of the request. If you specify a date in the future, we will schedule a transfer limit. You cannot schedule more than one limit in the future. | | | [endsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-endsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes inactive. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify an end date, the limit stays active until you override it with a new limit. | | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scope) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-reference) | Body | | Your reference for the transfer limit. | | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-transferType) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | | [scaInformation.scaOnApproval](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scaInformation-scaOnApproval) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Indicates whether to initiate Strong Customer Authentication (SCA) later, during approval, or immediately after you submit this request. Set this to **true**. If you do not specify this parameter, we default to **false**, which means that your user needs to perform SCA for each transfer limit request. | | Here is an example request to create a transfer limit. **Create a transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 10000 "currency: "EUR" }, "startsAt": "2025-08-14T00:00:00+01:00", "endsAt": "2026-08-14T00:00:00+01:00", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "transferType": "all", "scaInformation: { "scaOnApproval": true } } ``` 2. Verify that your response has a `HTTP 200- Success` response code. Take note of the transfer limit `id` and `limitStatus` that is returned in the response. The `limitStatus` must be **pendingSCA**. **Response** ```json [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "status": "pending" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "pendingSCA", "transferType": "all" } ] ``` ** #### 3. Make a request to approve pending requests 1. Make a POST [/balanceAccounts/{id}/transferLimits/approve](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve) request so that your user can authenticate the pending requests using SCA. Specify the following parameters: | Parameter | Type | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#path-WWW_Authenticate) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | [WWW\_Authenticate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **ApproveTransferLimit**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [checked for SCA eligibility](#1-check-sca-eligibility). | | [transferLimitIds](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#request-transferLimitIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A list that includes the `id` of all the pending transfer limits you want to approve. | **Initiate SCA to approve pending transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="ApproveTransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "transferLimitIds": ["TL00000000000000000000001", "TL00000000000000000000002"] } ``` 2. Verify that the response header contains the following fields: * `status`: **401** * `auth-param1`: Base64-encoded blob of data. You will need `auth-param1` when you [authenticate your user](#authenticate-user). **Response header** ```json "WWW-Authenticate: SCA realm="ApproveTransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."" ``` 3. Pass `auth-param1` to the SDK as `sdkInput`. ** #### 4. Authenticate your user After [creating a transfer limit approval request](#2-make-a-request-to-create-a-transfer-limit), you have 10 minutes to complete the authentication process and [finalize the transfer limit](#4-finalize-the-transfer-limit). To authenticate your user with the Authentication SDK: 1. Trigger the SDK to start user authentication and pass the `auth-param1` value from [the previous step](#3-make-a-request-to-approve-pending-requests) as `sdkInput`. 2. Pass `sdkOutput` to your server. ** #### 5. Finalize the transfer limit To finalize the transfer limit: 1. Make a POST [/balanceAccounts/{id}/transferLimits/approve](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve) request. Include the following parameters: The values of the body parameters must match the ones previously submitted to the `/balanceAccounts/{id}/transferLimits/approve` endpoint [when creating a transfer limit approval request](#3-make-a-request-to-approve-pending-requests). | Parameter | Type | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#path-WWW_Authenticate) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | [WWW\_Authenticate](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#header-WWW_Authenticate) | Header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SCA realm`: **ApproveTransferLimit**. `auth-param1`: Base64-encoded value of **sdkOutput** you get when you [initiate the SCA authentication process](/business-accounts/sca-for-funds-transfers/#initiate-authentication). | | [transferLimitIds](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits/approve#request-transferLimitIds) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A list that includes the `id` of all the pending transfer limits you want to approve. | **Finalize pending transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -H 'WWW-Authenticate: SCA realm="ApproveTransferLimit" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \ -X POST \ -d '{ "transferLimitIds": ["TL00000000000000000000001", "TL00000000000000000000002"] } ``` 2. Verify that your response contains a `HTTP 200 - Success` response code. Take note of the `limitStatus` that is returned in the response. The `limitStatus` must be either **active** or **scheduled** depending on the start date of the limit. **Response** ```json [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "status": "performed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ] ``` ### Tab: Exemption from SCA To create a new transfer limit when your user has an exemption from SCA: 1. Make a POST [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits) request. Include the following parameters: | Parameter | Type | Required | Description | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the balance account for which you want to set a transfer limit. | | | [amount.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-value) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value, in minor units, for the transfer limit. This is the maximum amount allowed per transfer or per day based on the `scope` of the limit. | | | [amount.currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-amount-currency) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency in which you want to set the limit. | | | [startsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-startsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes active. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify a start date, or set this to **null**, we default to the date and time of the request. If you specify a date in the future, we will schedule a transfer limit. You cannot schedule more than one limit in the future. | | | [endsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-endsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes inactive. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify an end date, the limit stays active until you override it with a new limit. | | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scope) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-reference) | Body | | Your reference for the transfer limit. | | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-transferType) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | | [scaInformation.exemption](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-scaInformation-exemption) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of exemption for Strong Customer Authentication (SCA). Possible values:- **lowerLimit**: the newly created limit is lower than the existing limit. - **notRegulated**: the limit is created in a country, region, or industry where it is not mandated by law to use SCA. - **setByPlatform**: you set a limit for one of your user's balance accounts. - **initialLimit**: there are no existing transfer limits set on the balance account or balance platform. - **alreadyPerformed**: you are confident about your user's identity and do not need to verify this using SCA. | | | | | | | | Here is an example request to create a transfer limit. **Create a transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 10000 "currency: "EUR" }, "startsAt": "2025-08-14T00:00:00+01:00", "endsAt": "2026-08-14T00:00:00+01:00", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "transferType": "all", "scaInformation: { "exemption": "initialLimit" } } ``` 2. Take note of the `id` and `status` that is returned in the response. The `status` must be either **active** or **scheduled** depending on the start date of the limit. **Response** ```json [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ] ``` ## View transfer limits After you configure transfer limits for your users' balance accounts, you can make GET requests to view the details of these limits. ### View all transfer limits To view all transfer limits configured at the balance account level: 1. Make a GET [/balanceAccounts/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits) request. To filter out transfer limits based on their characteristics, include any of the following query parameters in your request: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits#request-scope) | | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits#request-transferType) | | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits#query-status) | | The status of the transfer limit. Possible values:- **active**: the limit is currently active. - **inactive**: the limit is currently inactive - **pendingSCA**: the limit is pending until your user performs SCA. - **scheduled**: the limit is scheduled to become active at a future date. | For example, you want to view all transfer limits configured on your balance account that meet the following requirements: * `scope`: **perDay** * `transferType`: **instant** * `status`: **active** **Filter transfer limits on a balance account** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d scope=perDay \ -d transferType=instant \ -d status=active ``` 2. Take note of the array in the response that returns all all the transfer limits on your balance platform that meet the queried requirements. **Response** ```json { "transferLimits": [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perDay", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "instant" }, { "amount": { "value": 20000, "currency": "EUR" }, "id": "TRLI00000000000000000000000002", "endsAt": "2026-08-13T23:00:00Z", "scope": "perDay", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "instant" } ] } ``` ### View all current limits You can set transfer limits at the balance account level, and at the balance platform level. Transfer limits that you set for your balance account override transfer limits that are set for your balance platform when they concern the same combination of `scope` and `transferType`. If you do not set a transfer limit at the balance platform level for a particular combination of `scope` and `transferType`, then the balance platform limit applies to the balance account instead. At any given moment, the following limits apply to a balance account: * All the limits configured at balance account level * The limits configured at balance platform level that are not overridden by limits at balance account level To view all transfer limits that apply to your user's balance account at any given moment: 1. Make a GET [/balanceAccounts/{id}/transferLimits/current](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/current) request. If needed, you can use any of the following query parameters to filter out transfer limits based on their characteristics: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/current#query-scope) | | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance account. - **perDay**: you set a maximum total amount for all transfers made from the balance account in a day. | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/current#query-transferType) | | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | Here is an example request to view all current transfer limits that apply to **instant** transfers on balance account **BA00000000000000000000001** with a **perDay** scope. **View all active transfer limits on the balance account** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d scope=perDay \ -d transferType=instant ``` 2. Take note of the array in the response that returns all active transfer limits on the balance account with a **perDay** scope. **Response** ```json { "transferLimits": [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perDay", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "instant" } ] } ``` ### View a specific transfer limit To view a specific transfer limit: 1. Make a GET [/balanceAccounts/{id}/transferLimits/{transferLimitId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)) request. Specify the following parameters in the path: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)#path-id) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your balance account. | | [transferLimitId](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)#path-transferLimitId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the transfer limit you want to view. | Here is an example request to view a specific transfer limit: **View specific transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits/{transferLimitId} \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. Take note of the response, which returns the details of the transfer limit. **Response** ```json { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ``` ## Delete a transfer limit You can only delete **pending** or **scheduled** transfer limits. After a transfer limit becomes **active**, it cannot be deleted. If you no longer want to apply an **active** limit to your balance account, you must override it by creating a new transfer limit. To delete a **pending** or **scheduled** transfer limit, make a DELETE [/balanceAccounts/{id}/transferLimits/{transferLimitId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)) request. Specify the following parameters in the path: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)#path-id) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your balance account. | | [transferLimitId](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balanceAccounts/\(id\)/transferLimits/\(transferLimitId\)#path-transferLimitId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the transfer limit you want to delete. | Here is an example request to delete a specific transfer limit: **Delete specific transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001/transferLimits/{transferLimitId} \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X DELETE ``` If the transfer limit is successfully deleted, you receive a `HTTP 204 - No Content` response. --- # Source: https://docs.adyen.com/business-accounts/use-transfer-limits/balance-platform.md Section: Business accounts Title: Create and manage transfer limits for your balance platform Description: Set a limit on outgoing transfers from your balance platform. --- title: "Create and manage transfer limits for your balance platform" description: "Set a limit on outgoing transfers from your balance platform." url: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-platform" source_url: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-platform.md" canonical: "https://docs.adyen.com/business-accounts/use-transfer-limits/balance-platform" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Create and manage transfer limits for your balance platform Set a limit on outgoing transfers from your balance platform. [View source](/business-accounts/use-transfer-limits/balance-platform.md) Transfer limits create conditional logic that automatically approves or declines a transfer based on its amount. When a transfer limit is configured for your balance platform, it regulates the amount of funds that can be transferred externally from all the balance accounts in your platform. ## Requirements Before you begin, make sure that you complete the following requirements: | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | Adyen for Platforms integration with business accounts. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have access to the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) with the following role:- **Balance platform base role** | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the following webhook(s):- [**Transfer webhooks**](/payouts/payout-service/pay-out-to-bank-accounts/payout-webhooks/) - [**Transaction webhooks**](/payouts/payout-service/transfer-transactions/transaction-webhooks/) | | **Limitations** | Transfer limits are not supported for [internal transfers](/business-accounts/transfer-funds-internally), or [incoming external transfers](/business-accounts/receive-funds). | | **Setup steps** | Before you begin:- Make sure you are familiar with [how transfer limits work](/business-accounts/use-transfer-limits). | ## How it works 1. You create a transfer limit by making a POST [/balancePlatforms/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits) request. In your request, you must consider the scope and type of the transfer, and specify the time period in which the transfer limit is valid. 2. The transfer limit is created with a **scheduled** status. 3. On the start date of the transfer limit, the status of the transfer limit becomes **active**. 4. While it is **active**, the transfer limit regulates the amount of funds being transferred externally from the balance account. 5. When the end date of the transfer limit passes, it reaches an **inactive** state. ## Create transfer limits To create a new transfer limit: 1. Make a POST [/balancePlatforms/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits) request. Include the following parameters: | Parameter | Type | Required | Description | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/\(id\)/transferLimits#request-id) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your balance platform. | | | [amount.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-amount-value) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The value, in minor units, for the transfer limit. This is the maximum amount allowed per transfer or per day based on the `scope` of the limit. | | | [amount.currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-amount-currency) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency in which you want to set the limit. | | | [startsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-startsAt) | Body | | The date, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes active. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify a start date, or set this to **null**, we default to the date and time of the request. If you specify a date in the future, we will schedule a transfer limit. You cannot schedule more than one limit in the future. | | | [endsAt](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-endsAt) | Body | | The date and time, in [ISO date and time format](https://en.wikipedia.org/wiki/ISO_8601), when the transfer limit becomes inactive. Format: **YYYY-MM-DDThh:mm:ss.sssTZD** If you do not specify an end date, the limit stays active until you override it with a new limit. | | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-scope) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance platform. - **perDay**: you set a maximum total amount for all transfers made from the balance platform in a day. | | | [reference](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-reference) | Body | | Your reference for the transfer limit. | | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-transferType) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | | [scaInformation.exemption](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(id\)/transferLimits#request-scaInformation-exemption) | Body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of exemption for Strong Customer Authentication (SCA). Set this to **setByPlatform**. | | | | | | | | Here is an example request to create a transfer limit. **Create a transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms/YOUR_BALANCE_PLATFORM/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 10000 "currency: "EUR" }, "startsAt": "2025-08-14T00:00:00+01:00", "endsAt": "2026-08-14T00:00:00+01:00", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "transferType": "all", "scaInformation: { "exemption": "setByPlatform" } } ``` 2. Take note of the `transferLimitId` and `status` that is returned in the response. The `status` must be either **active** or **scheduled** depending on the start date of the limit. **Response** ```json [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "setByPlatform", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ] ``` ## View transfer limits After you configure transfer limits for your balance platform, you can make GET requests to view the details of these limits. ### View all transfer limits To view all transfer limits configured for your balance platform: 1. Make a GET [/balancePlatforms/{id}/transferLimits](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits) request. To filter out transfer limits based on their characteristics, include any of the following query parameters in your request: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [scope](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits#request-scope) | | The scope on which the transfer limit applies. Possible values:- **perTransaction**: you set a maximum amount for each transfer made from the balance platform. - **perDay**: you set a maximum total amount for all transfers made from the balance platform in a day. | | [transferType](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits#request-transferType) | | The type of transfer to which the limit applies. Possible values:- **instant**: the limit applies to transfers with an **instant** priority. - **all**: the limit applies to all transfers, regardless of priority. | | [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits#query-status) | | The status of the transfer limit. Possible values:- **active**: the limit is currently active. - **inactive**: the limit is currently inactive - **scheduled**: the limit is scheduled to become active at a future date. | For example, you want to view all transfer limits configured on your balance platform that meet the following requirements: * `scope`: **perDay** * `transferType`: **instant** * `status`: **active** **Filter transfer limits on balance platform** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms/YOUR_BALANCE_PLATFORM/transferLimits \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d scope=perDay \ -d transferType=instant \ -d status=active \ ``` 2. Take note of the array in the response that returns all the transfer limits on your balance platform that meet the queried requirements. **Response** ```json { "transfer": [ { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perDay", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "instant" }, { "amount": { "value": 20000, "currency": "EUR" }, "id": "TRLI00000000000000000000000002", "endsAt": "2026-08-13T23:00:00Z", "scope": "perDay", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "instant" } ] } ``` ### View a specific transfer limit To view a specific transfer limit: 1. Make a GET [/balancePlatforms/{id}/transferLimits/{transferLimitId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)) request. Specify the following parameters in the path: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)#path-id) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your balance platform. | | [transferLimitId](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)#path-transferLimitId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the transfer limit you want to view. | Here is an example request to view a specific transfer limit: **View specific transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms/YOUR_BALANCE_PLATFORM/transferLimits/{transferLimitId} \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. Take note of the response, which returns the details of the transfer limit. **Response** ```json { "amount": { "value": 10000, "currency": "EUR" }, "id": "TRLI00000000000000000000000001", "endsAt": "2026-08-13T23:00:00Z", "scope": "perTransaction", "reference": "Your reference for the transfer limit", "scaInformation": { "exemption": "initialLimit", "status": "notPerformed" }, "startsAt": "2025-08-13T23:00:00Z", "limitStatus": "active", "transferType": "all" } ``` ## Delete a transfer limit You can only delete **pending** or **scheduled** transfer limits. After a transfer limit becomes **active**, it cannot be deleted. If you no longer want to apply an **active** limit to your balance platform, you must override it by creating a new transfer limit. To delete a **pending** or **scheduled** transfer limit, make a DELETE [/balancePlatforms/{id}/transferLimits/{transferLimitId}](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)) request. Specify the following parameters in the path: | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)#path-id) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your balance platform. | | [transferLimitId](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balancePlatforms/\(id\)/transferLimits/\(transferLimitId\)#path-transferLimitId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the transfer limit you want to delete. | Here is an example request to delete a specific transfer limit: **Delete specific transfer limit** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms/YOUR_BALANCE_PLATFORM/transferLimits/TRLI00000000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X DELETE ``` If the transfer limit is successfully deleted, you receive a `HTTP 204 - No Content` response. --- # Source: https://docs.adyen.com/business-accounts/verification-overview.md Section: Business accounts Title: Verification process Description: Learn how Adyen verifies the users in your platform. --- title: "Verification process" description: "Learn how Adyen verifies the users in your platform." url: "https://docs.adyen.com/business-accounts/verification-overview" source_url: "https://docs.adyen.com/business-accounts/verification-overview.md" canonical: "https://docs.adyen.com/business-accounts/verification-overview" last_modified: "2023-12-29T17:35:00+01:00" language: "en" --- # Verification process Learn how Adyen verifies the users in your platform. [View source](/business-accounts/verification-overview.md) As required by payment industry regulations, Adyen must verify the users in your balance platform before you can process payments, pay out their funds, and offer business accounts to them. These verification checks are also called *Know Your Customer* (KYC) checks. During this process, Adyen verifies that your users provide accurate information about their businesses. Based on the results of the verification checks, Adyen decides if a user can perform any action on your balance platform. These actions are known as [*capabilities* ](/business-accounts/verification-overview/capabilities). To see whether a user can use a specific capability on your balance platform, check the [capability settings](/business-accounts/verification-overview/capabilities#capability-settings). On this page, we describe: * [When Adyen verifies users](#when-the-verification-process-happens) * [How the verification process works](#verification-workflow) ## When does Adyen verify users Adyen verifies users before allowing them to use capabilities on your balance platform. The following events all trigger verification checks. ** ### Requesting capabilities for your user In the [design phase](/business-accounts/get-started#design-implementation), you set up [business account capabilities](/business-accounts/verification-overview/capabilities) for your balance platform. These capabilities are requested every time you onboard a new user and create an account holder for them. Adyen verifies the user and if they successfully complete the verification checks, they are allowed to use the capabilities. If a user needs a specific capability that is not requested by default, you must [request the additional capability](/business-accounts/manage-account-holders#request-capability). In some cases, this requires more verification. ** ### When users change their data When users change their data after they are already allowed to use capabilities, Adyen verifies them again. If the updated data fails verification checks, Adyen may set a verification deadline by which the user needs to resolve the issues. The user is allowed to continue using the capabilities while the verification deadline is active. If the user does not resolve the verification issues in a timely manner, their capabilities will be disallowed. Note that [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) are only triggered for capability-related changes to the account holder. Data changes to the legal entity of the account holder do not trigger webhooks. ** ### Periodic data reviews required by Adyen Adyen occasionally requires your users to [review and confirm](/business-accounts/verification-overview#when-adyen-requires-data-reviews) that their data is up-to-date. You also can choose to [proactively request the data review](/business-accounts/verification-overview/data-review-process#proactive-review) for your user. After a data review is triggered, Adyen immediately runs verification checks on the existing data of the user. This data includes information about their legal entity/legal arrangement and all entities associated with it, such as their ultimate beneficial owners (UBOs) and signatories. Adyen sets a verification deadline by which the user must confirm their data and update it (if needed). If there are no verification errors, the user must only review and confirm their data. If there are any errors from the verification checks, the user must also resolve them and confirm the data. If you proactively request the data review, Adyen still provides a verification deadline during which the user can continue using their capabilities that were allowed. If the user updates their data, Adyen verifies the updated data again. While the deadline is active, the user can continue using their capabilities that were allowed prior to the review request. If the user does not confirm the data and resolve any verification errors, their capabilities will be disallowed. The review is only considered finalized when the user has both confirmed the data **and** resolved all verification errors. ### Verification deadlines Verification deadlines are only available in v3 and v4 of the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). For the events mentioned above that require additional verification checks, Adyen may set a deadline to give users extra time to resolve any verification issues before certain capabilities are disallowed. This allows users to correct any missing or incorrect information to complete verification checks or fulfill their contractual obligations, such as [accept Terms of Service](/business-accounts/onboard-users/terms-of-service). The verification deadline is the final date by which all required information and documents must be submitted and verified by Adyen. Users are allowed to continue using the capabilities while the deadline is active. The specific verification deadline varies depending on the capabilities involved. The following table outlines the standard verification deadlines for each capability. | Verification deadline | Capability API name | Capability display name in the Customer Area | | --------------------- | --------------------- | -------------------------------------------- | | **30-day period** | issueBankAccount | Issue bank accounts | | | sendToThirdParty | Send funds to third-party bank accounts | | **60-day period** | receiveFromThirdParty | Receive funds from third-party bank accounts | Verification deadlines may be adjusted based on ongoing account monitoring and subsequent verification checks. In accordance with our internal due diligence processes, designed to ensure platform security and comply with regulatory obligations, a standard deadline could be shortened or removed in specific situations. Users are allowed to continue using the capabilities while the deadline is active. To see the verification deadlines, you can either: * [View the details of the account holder](/business-accounts/manage-account-holders?tab=ah-customer-area_1#get-account-holders) in your Customer Area. * Make a GET [/accountHolders/id](https://docs.adyen.com/api-explorer/balanceplatform/2/get/accountHolders/_id_) request. **API response - With verification deadline** ```json { "balancePlatform":"YOUR_BALANCE_PLATFORM", "capabilities":{ "sendToThirdParty":{ "allowed":"true", "enabled":"true", "requested":"true", "verificationStatus":"invalid" } }, "description":"Test Account holder", "id":"AH00000000000000000000001", "legalEntityId":"LE00000000000000000000001", "reference":"YOUR_INTERNAL_IDENTIFIER", "status":"active", "verificationDeadlines":[ { "expiresAt":"2022-05-01T00:00:00Z", "capabilities":[ "sendToThirdParty" ] }, { "expiresAt":"2022-06-01T00:00:00Z", "capabilities":[ "receiveFromPlatformPayments", "receivePayments" ] } ], "verificationErrors":[ { "entity":{ "id":"LE00000000000000000000001", "type":"LegalEntity" }, "code":"1_14", "message":"Capability not allowed for type individual", "remediatingActions":[], "type":"invalidInput", "capabilities":[ "sendToThirdParty", "receivePayments" ] } ] } ``` The diagrams in the next section show the process and the corresponding capability verification statuses and capability settings. ## How the verification process works In the following diagrams, you can see the process for events that trigger verification checks and the relationship between [capability verification statuses](/business-accounts/verification-overview/capabilities#verification-status-of-a-capability) and [capability settings](/business-accounts/verification-overview/capabilities#capability-settings). ### Tab: You request capabilities for users [![](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/request-capabilities.svg)](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/request-capabilities.svg) The illustrated verification process is as follows: 1. You create an account holder or request new capabilities for your user. 2. Adyen asynchronously checks if there are verification requirements that your user must fulfill.\ When there are several verification checks in progress, the user may receive verification errors while the overall status of the capability remains `pending`. Before reaching out to your Adyen contact, we recommend waiting until all checks are completed and the status becomes `invalid`. 3. If the verification fails, user can fix the issues by providing new or updated data.\ If the verification is successful, the user is allowed to use the capability. Adyen sends all verification-related updates through webhooks. If Adyen has found reasons to not allow the capability, the capability verification status is set as `rejected` and the capability will not be allowed. ### Tab: Users change data If the user changes their data after they are already allowed to use capabilities, Adyen verifies them again. If the verification fails, Adyen might also set a deadline for updating the data. [![](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/data-updated.svg)](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/data-updated.svg) The illustrated verification process is as follows: 1. Your user changes their data. They are still allowed to use the capability while Adyen verifies the updated data. 2. Adyen asynchronously checks if there are verification requirements that your user must fulfill resulting from the change in data.\ When there are several verification checks in progress, the user may receive verification errors while the overall status of the capability remains `pending`. Before reaching out to your Adyen contact, we recommend waiting until all checks are completed and the status becomes `invalid`. 3. If the verification fails, the user must provide the new or updated information within a deadline.\ If the verification is successful, the user is allowed to use continue using the capability and the deadline is cleared. Adyen sends all verification-related updates through webhooks. If the user does not provide new or updated information within the deadline, or if the new data fails the KYC checks, the capabilities are disallowed. ### Tab: Adyen requires data review Adyen occasionally requires your users to [review and confirm](/business-accounts/verification-overview#when-adyen-requires-data-reviews) that their data is up-to-date. You also can choose to [proactively request the data review](/business-accounts/verification-overview/data-review-process#proactive-review) for your user. After a data review is triggered, Adyen immediately runs verification checks on the existing data of the user. This data includes information about their legal entity/legal arrangement and all entities associated with it, such as their ultimate beneficial owners (UBOs) and signatories. Adyen sets a verification deadline by which the user must confirm their data and update it (if needed). If there are no verification errors, the user must only review and confirm their data. If there are any errors from the verification checks, the user must also resolve them and confirm the data. If you proactively request the data review, Adyen still provides a verification deadline during which the user can continue using their capabilities that were allowed. If the user updates their data, Adyen verifies the updated data again. While the deadline is active, the user can continue using their capabilities that were allowed prior to the review request. If the user does not confirm the data and resolve any verification errors, their capabilities will be disallowed. The review is only considered finalized when the user has both confirmed the data **and** resolved all verification errors. [![](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/review-required.svg)](/user/pages/reuse/pfs-verification/verification-overview/verification-workflow/review-required.svg) The illustrated verification process is as follows: 1. Adyen informs you through a webhook when a data review is required or you [proactively request the data review for your user](/business-accounts/verification-overview/data-review-process#proactive-review). The webhook also includes a verification deadline. The user is still allowed to use their capabilities while the deadline is in place. 2. The user needs to confirm their data is up-to-date, or update their data if needed and then confirm it, within the verification deadline. 3. Adyen asynchronously checks the data and sends all verification-related updates through webhooks. If the verification is successful, they can continue using their capabilities and the deadline is lifted. 4. If the user does not confirm they reviewed the data within the deadline or the new data fails the verification checks, the capabilities are disallowed. ## Next steps Find out which information your users need to provide. [User capabilities](/business-accounts/verification-overview/capabilities) [Learn what capabilities your users can have in your platform](/business-accounts/verification-overview/capabilities) [required](/business-accounts/onboard-users) [Onboard your users](/business-accounts/onboard-users) [Learn to move your users through the verification process](/business-accounts/onboard-users) --- # Source: https://docs.adyen.com/business-accounts/verification-overview/capabilities.md Section: Business accounts Title: User capabilities Description: Learn what capabilities your users can have in your platform --- title: "User capabilities" description: "Learn what capabilities your users can have in your platform" url: "https://docs.adyen.com/business-accounts/verification-overview/capabilities" source_url: "https://docs.adyen.com/business-accounts/verification-overview/capabilities.md" canonical: "https://docs.adyen.com/business-accounts/verification-overview/capabilities" last_modified: "2024-02-20T15:43:00+01:00" language: "en" --- # User capabilities Learn what capabilities your users can have in your platform [View source](/business-accounts/verification-overview/capabilities.md) Every account holder has a list of capabilities that determine what they can do on your balance platform. You can edit a [capability's settings](#capability-settings) to change which actions the account holder has permission to do, for example, receive payments, send funds to a bank account, or [use certain financial products](#financial-product-capabilities). In most cases, Adyen configures default capabilities for your business during the [design phase](/business-accounts/get-started#design-implementation). These capabilities are automatically requested for your users when you create account holders for them. If a user needs a specific capability that is not part of their default configuration, you must [request the additional capability](/business-accounts/manage-account-holders#request-capability). It is possible that requesting additional capabilities prompts additional [KYC checks](/business-accounts/verification-overview) on your users. ## Business account capabilities Adyen business accounts requires your user's account holders to have the following capabilities: | Capability name | Display name in the Customer Area | Description | | ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **issueBankAccount** | Issue bank accounts | Allow users to have an Adyen business bank account. | | **receiveFromThirdParty** | Receive funds from third-party bank accounts | Allows users to receive funds from third-party bank accounts. This capability is enabled by default when they have an **issueBankAccount** capability. | | **sendToThirdParty** | Send funds to third-party bank accounts | Allows users to send funds to third-party bank accounts. This capability is enabled by default when they have an **issueBankAccount** capability. | ## General capabilities In addition to the business account capabilities, your users also need [other capabilities](/platforms/verification-overview/capabilities#capabilities) that allow them to perform actions in your balance platform. Some of these capabilities are requested automatically for new account holders, or you have to request them separately when needed. ## Verification status of a capability Verification status of a capability indicates whether a user has passed [KYC checks](/business-accounts/verification-overview) and meets requirements to use a specific capability. To get updates about the verification status of a capability, you can: * Listen to [balancePlatform.accountHolder.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.created) and [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks * Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}) request Here are the possible values for the capability verification status. | Status | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending`[]() | The `pending` status indicates that the verification is in progress. At this verification phase, a capability requested for the first time is set to [`requested` ](#requested): **true** and [`allowed` ](#allowed): **false**. If the capability has already been allowed, but some [user data has changed](/business-accounts/verification-overview#when-users-change-their-data) and needs to be verified, you may see that the capability verification status is `pending` and the capability is [`allowed` ](#allowed): **true**. This means that the user is still allowed to use capability while Adyen performs the checks. | | `valid`[]() | The `valid` status indicates that the verification is successfully completed and that the user meets the requirements to use a capability. With this verification status, the user can use the capability. Adyen sets the capability to [`allowed` ](#allowed): **true**. | | `invalid`[]() | The `invalid` status indicates that the verification failed, for example due to incorrect information or missing documents. In this case, the webhook or the API response contains the [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) object, including the `verificationErrors`, `subErrors`, and `remediatingActions` arrays returned on the linked legal entity. If there are [verification errors](/business-accounts/kyc-verification-codes), you must resolve them. With this verification status, Adyen sets the capability to [`allowed` ](#allowed): **false**. This means the user is not permitted to use the capability until all verification errors are resolved and the verification process is completed successfully. If any [user data changes or is missing](/business-accounts/verification-overview#when-users-change-their-data) after the previous verification has been completed successfully, Adyen reverts the capability verification status to `invalid`. In such a scenario, the user must provide the necessary information within a specific deadline. During this period, the user can continue using the capability, and its setting remains as [`allowed` ](#allowed): **true**. | | `rejected`[]() | The `rejected` status indicates that Adyen completed verification, but the user does not meet the requirements to use a capability based on the submitted information. This status is final and any errors cannot be resolved by updating data or uploading documents. With this verification status, Adyen prohibits the user from performing the action and sets the capability to [`allowed` ](#allowed): **false**. | ## Capability settings The settings of a capability determine if it is available to a user and they can use it. To get updates about the capability settings, you can: * Listen to [balancePlatform.accountHolder.created](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.created) and [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks * Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}) request. The API response contains the [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/_id_#responses-200-capabilities) object that shows whether the capability is `requested`, `allowed`, and `enabled`. Below are the explanations for each setting. | Setting | Possible values | Description | | --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`requested`]() | **true**, **false** | true: the capability has been requested. Default capabilities are requested automatically when you create an account holder. You can also request additional capabilities by including this setting in your API request. false: the capability has not been requested yet. | | [`allowed`]() | **true**, **false** | true: the verification is successful and the user is permitted to use the capability. The capability can only be used when it is both allowed and enabled. In some scenarios, such as when a user changes their information, the capability is set to true while the verification status is pending or invalid . The user must provide updated information within the given deadline. During the deadline, the user can still use the capability while Adyen verifies the data. false: the verification is pending , invalid , or rejected . The user is not permitted to use the capability. | | [`enabled`]() | **true**, **false** | This setting allows you to [manage your users’ access to capabilities](/business-accounts/manage-account-holders/?tab=ah-customer-area_2#deactivate-capability). Changing this setting does not trigger verification checks or prevent a capability from being requested. Note that this capability can only be used if it is both enabled and allowed. Set to **true** to offer the capability to the user. Set to **false** to prevent them from using the capability. | --- # Source: https://docs.adyen.com/business-accounts/verification-overview/data-review-process.md Section: Business accounts Title: Periodic data reviews Description: Learn how Adyen may request your user to verify that their data is up-to-date. --- title: "Periodic data reviews" description: "Learn how Adyen may request your user to verify that their data is up-to-date." url: "https://docs.adyen.com/business-accounts/verification-overview/data-review-process" source_url: "https://docs.adyen.com/business-accounts/verification-overview/data-review-process.md" canonical: "https://docs.adyen.com/business-accounts/verification-overview/data-review-process" last_modified: "2023-11-21T14:17:00+01:00" language: "en" --- # Periodic data reviews Learn how Adyen may request your user to verify that their data is up-to-date. [View source](/business-accounts/verification-overview/data-review-process.md) Adyen occasionally requires your users to review and confirm that their data is up-to-date. You also can choose to [proactively request the data review](#proactive-review) for your user. You may want to do this if your user does not engage with your platform on a regular basis. After a data review is triggered, Adyen immediately runs verification checks on the existing data of the user. This data includes information about their legal entity/legal arrangement and all entities associated with it, such as their ultimate beneficial owners (UBOs) and signatories. Adyen informs you through webhooks the review requirements for the user: ### Tab: User has verification errors The user must update their data (if needed), resolve the verification errors and then confirm the data. If the user data is updated, Adyen verifies their data again. ### Tab: No verification errors If there are no verification errors, the user must only review and confirm their data. In both scenarios, Adyen provides a verification deadline in the [webhook](#review-required). While the deadline is active, the user can continue using their capabilities that were allowed prior to the review request. If the user does not confirm the data and resolve any verification errors, their capabilities will be disallowed. The review is only considered finalized when the user has confirmed the data **and** resolved all verification errors. ## Step 1: Get updates when a review is required Adyen informs you if a user data review is required through a [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook. The webhook contains the following information: | Field | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus) | Set to `invalid` | | [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed) | Remains set to `true` | | [verificationErrors](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-capabilities-problems-verificationErrors) | Contains the verification error **3\_10** and message "Review of data is required". | | [verificationDeadlines](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-verificationDeadlines) | The date when the capability will be disallowed if the verification error is not resolved. | | [remediatingActions](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-capabilities-problems-verificationErrors-remediatingActions) | Contains the remediating action **3\_100** and message "Use `/legalEntities/{id}/confirmDataReview` to indicate that the data is confirmed". | Note that the webhook contains the capabilities that will be disallowed if the user does not confirm that they have reviewed and updated their data. **accountHolder.updated webhook - Data review required** ```json { "data": { "balancePlatform": "YourBalancePlatform", "id": "AH00000000000000000000001", "accountHolder": { "description": "Liable account holder used for international payments and payouts", "legalEntityId": "LE00000000000000000000001", "reference": "YOUR_INTERNAL_IDENTIFIER", "capabilities": { "sendToBalanceAccount": { "enabled": true, "requested": true, "allowed": true, "problems": [ { "entity": { "id": "LE00000000000000000000002", "type": "LegalEntity" }, "verificationErrors": [ { "code": "3_10", "message": "Review of data is required", "remediatingActions": [ { "code": "3_100", "message": "Use /legalEntities/{id}/confirmDataReview to indicate that the data is confirmed" } ], "type": "dataReview" } ] } ], "verificationStatus": "invalid" } }, "id": "AH00000000000000000000001", "status": "active", "verificationDeadlines": [ { "capabilities": [ "sendToBalanceAccount" ], "expiresAt": "2024-12-07T21:34:06+01:00" } ] } }, "environment": "test", "type": "balancePlatform.accountHolder.updated" } ``` ## Step 2 (optional): Proactively request a data review for your user This feature is only available if you are using onboarding v3 or v4. To streamline the process, we recommend that you request the data review during a time when your user is active in your platform. Note that we may also require a data review outside of the scheduled period if there is a significant change to the user's information or risk level. If you request a data review when the user is not eligible, for example when: * their next scheduled review date is more than a year away or * the user was onboarded or had their last review within in the past six months, we ensure the review is not activated and communicate the reason in an [error message](#troubleshooting). 1. To request the data review, make a POST `/legalEntities/{id}/requestPeriodicReview` request with the legal entity ID of the user in the path. 2. If the request is successful, you receive a **204** response. Adyen then informs you that a user data review is required through a [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook. The webhook contains the following information: | Field | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus) | Set to `invalid` | | [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed) | Remains set to `true` | | [verificationErrors](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-capabilities-problems-verificationErrors) | Contains the verification error **3\_10** and message "Review of data is required". | | [verificationDeadlines](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-verificationDeadlines) | The date when the capability will be disallowed if the verification error is not resolved. | | [remediatingActions](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-capabilities-problems-verificationErrors-remediatingActions) | Contains the remediating action **3\_100** and message "Use `/legalEntities/{id}/confirmDataReview` to indicate that the data is confirmed". | Note that the webhook contains the capabilities that will be disallowed if the user does not confirm that they have reviewed and updated their data. **accountHolder.updated webhook - Data review required** ```json { "data": { "balancePlatform": "YourBalancePlatform", "id": "AH00000000000000000000001", "accountHolder": { "description": "Liable account holder used for international payments and payouts", "legalEntityId": "LE00000000000000000000001", "reference": "YOUR_INTERNAL_IDENTIFIER", "capabilities": { "sendToBalanceAccount": { "enabled": true, "requested": true, "allowed": true, "problems": [ { "entity": { "id": "LE00000000000000000000002", "type": "LegalEntity" }, "verificationErrors": [ { "code": "3_10", "message": "Review of data is required", "remediatingActions": [ { "code": "3_100", "message": "Use /legalEntities/{id}/confirmDataReview to indicate that the data is confirmed" } ], "type": "dataReview" } ] } ], "verificationStatus": "invalid" } }, "id": "AH00000000000000000000001", "status": "active", "verificationDeadlines": [ { "capabilities": [ "sendToBalanceAccount" ], "expiresAt": "2024-12-07T21:34:06+01:00" } ] } }, "environment": "test", "type": "balancePlatform.accountHolder.updated" } ``` ### Troubleshooting * If you attempt to request a review more than one year prior to the user's next scheduled review, you will receive the error code **422** and message **A periodic review can only be requested when the next scheduled deadline is within one year**. * If you attempt to request a review and the endpoint is not available for any other reason, you will receive the error code **422** and message **Unable to request periodic review for this legal entity**. * If you attempt to request a review less than 180 days from the date of the previous review, you will receive the error code **422** and message **A periodic review cannot be started yet as a review was completed recently**. ## Step 3: Ask your users to review their data within the deadline Inform your user that they need to review their data and to provide updated information if needed. Follow the steps below depending on your type of integration. ### Tab: Hosted onboarding 1. Make a GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)) request with the legal entity ID of the user in the path. Review any user information that you submitted to Adyen through API requests. For example, information about the user's legal entities. 2. If needed, make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request to update any user information. 3. Then, create a hosted onboarding link. When the user is redirected to the link, they are presented with a summary page where they can confirm or update their data. ![](/user/pages/reuse/pfs-verification/verification-overview/data-review/hosted-onboarding-review.png) 4. After the user completes their review, they need to select the checkbox and then select **Submit review** to confirm that their data is now up-to-date. This resolves the verification error related to the data review. ![](/user/pages/reuse/pfs-verification/verification-overview/data-review/submit-data-review.png) ### Tab: API-only onboarding 1. Present your user's information in your UI. To do this, first make a GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)) request with the legal entity ID of the user in the path. You also need to make a GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)) request for all the user's associated entities, such as their UBOs and signatories. 2. Make API requests to get information for the user's supporting entities. For example: * GET [/transferInstruments/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/get/transferInstruments/\(id\)) for their transfer instruments. * GET [/legalEntities/{id}/businessLines](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)/businessLines) for their business lines. * GET [/merchants/{merchantId}/stores](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/stores) for their stores. 3. Ask your user to review and confirm if their data is up-to-date. If their data needs to be be updated, make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request with the updated information in the body of the request. 4. When the user confirms that their data is now up-to-date, make a POST [/legalEntities/{id}/confirmDataReview](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/confirmDataReview) request. The response returns the time when the data review was confirmed in the [dataReviewedAt](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/confirmDataReview#responses-200-dataReviewedAt) field. This resolves the verification error related to the data review. **confirmDataReview response** ```json { "dataReviewedAt":"2023-07-13T15:19:02Z" } ``` ## Step 4: Get the verification results Once the review has been submitted, Adyen verifies the user’s data and informs you of the results through the [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook. To resolve any verification errors, follow the steps based on your integration type: [API-only onboarding](/business-accounts/onboard-users) or [Hosted onboarding](/business-accounts/onboard-users). After the user has reviewed their data and the verification is valid, there is no further action needed. ### Verification valid When the checks are completed successfully, Adyen sends a [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook with: * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): Set to **valid**. * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Set to **true**. **balancePlatform.accountHolder.updated webhook - verification completed** ```json { "data":{ "accountHolder":{ "capabilities":{ "sendToTransferInstrument":{ "allowed":"true", "enabled":"true", "requested":"true", "verificationStatus":"valid" } }, "description":"Test Account holder", "id":"AH00000000000000000000001", "legalEntityId":"LE00000000000000000000001", "reference":"YOUR_INTERNAL_IDENTIFIER", "status":"active" }, "balancePlatform":"YOUR_BALANCE_PLATFORM" }, "environment":"test", "type":"balancePlatform.accountHolder.updated" } ``` ### Verification invalid When there are problems with the verification, Adyen sends a [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook. The webhook contains the following information: * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): Set to **invalid**. * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Set to **false** or **true** with the [verificationDeadlines](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated#request-data-accountHolder-verificationDeadlines) array showing when the capability will be disallowed if the verification error is not resolved. * [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems): Contains `verificationErrors`, `subErrors`, and `remediatingActions` arrays returned on the linked legal entity. If there are verification errors, you must resolve them. To see any [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) also returned on the transfer instrument resource, reach out to your Adyen contact to enable the feature. For example, if your users have multiple transfer instruments, this can help them more easily see the errors and on which transfer instrument they need to be resolved. **balancePlatform.accountHolder.updated webhook - with verification errors array** ```json { "data":{ "accountHolder":{ "capabilities":{ "sendToTransferInstrument":{ "allowed":"false", "enabled":"true", "problems":[ { "entity":{ "id":"LE00000000000000000000001", "type":"LegalEntity" }, "verificationErrors":[ { "code":"2_8037", "message":"bankStatement was missing.", "remediatingActions":[ { "code":"1_703", "message":"Upload a bank statement" } ], "type":"dataMissing" } ] } ], "requested":"true", "verificationStatus":"invalid" } }, "description":"Test Account holder", "reference":"YOUR_INTERNAL_IDENTIFIER", "id":"AH00000000000000000000001", "legalEntityId":"LE00000000000000000000001", "status":"Active" }, "balancePlatform":"YOUR_BALANCE_PLATFORM" }, "environment":"test", "type":"balancePlatform.accountHolder.updated" } ``` ## Test the data review flow In this scenario, you force Adyen to send a verification error relating to one of your users (a legal entity). This verification error is due to an outstanding data review required by Adyen. The account holder for the legal entity must already have capabilities allowed to be able test the flow. ### Step 1: Make an API request Using the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview), make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/#/legalentity/latest/patch/legalEntities/{id}) request. Include the [x-requested-verification-code](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#header-x_requested_verification_code) `3_10` in the header of your request. ### Step 2: Check verification results To confirm that the legal entity has an outstanding data review required, you can: * Listen to the [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhook or * Make a GET [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)) request for the specified legal entity or * Make a POST [/checkVerificationErrors](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/checkVerificationErrors) request for the specified legal entity. These all contain the verification error **3\_10** and message "Review of data is required". ### Step 3: Resolve the verification error Make a POST [/legalEntities/{id}/confirmDataReview](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/confirmDataReview) request with the specified legal entity ID in the path. The response returns the time when the data review was confirmed in the [dataReviewedAt](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/confirmDataReview#responses-200-dataReviewedAt) field. You can confirm the verification error was resolved by listening to webhooks or making a GET API request. ## See also * [Onboard users](/business-accounts/onboard-users) --- # Source: https://docs.adyen.com/business-accounts/verification-requirements.md Section: Business accounts Title: Determine the verification requirements Description: Learn what verification information you must collect from your users --- title: "Determine the verification requirements" description: "Learn what verification information you must collect from your users" url: "https://docs.adyen.com/business-accounts/verification-requirements" source_url: "https://docs.adyen.com/business-accounts/verification-requirements.md" canonical: "https://docs.adyen.com/business-accounts/verification-requirements" last_modified: "2023-11-06T16:56:00+01:00" language: "en" --- # Determine the verification requirements Learn what verification information you must collect from your users [View source](/business-accounts/verification-requirements.md) Verification requirements vary based on the additional financial products that you offer to your users. In some cases, additional financial products, such as business accounts, require more verification checks. To use business accounts, your users must provide additional information for these verification checks. After the checks are completed successfully, you can assign to your user the [capabilities related to business accounts](/business-accounts/verification-overview/capabilities#business-account-capabilities). This page explains the verification requirements and the data that you need to collect from your users. ## Required verification data In addition to the minimum required information based on the [country/region](/platforms/verification-requirements/#country-of-operation) and [legal entity type](/platforms/verification-requirements/#legal-entity-type), you must also collect the following: * [Industry](/business-accounts/verification-requirements/reference-additional-products/#list-industry-codes) in which the user is registered based on their local chamber of commerce * URL of the user's website if they have an online presence * The user's [source of funds](/business-accounts/verification-requirements/reference-additional-products#list-source-of-funds) * For organizations, their [Foreign Account Tax Compliance Act (FATCA)/Common Reporting Standard (CRS) classification](/business-accounts/verification-requirements/reference-additional-products#list-fatca-crs), which includes their business type and their main source of income. * Tax residence country and [ID number](/business-accounts/verification-requirements/data-formats-per-country). This is required for both organizations and the individuals associated with the organization, or the sole proprietorship owner. * The user's source of wealth. Adyen determines if your user needs to provide data about their source of wealth and/or of the owners or controllers of the organization. If the source of wealth is required, Adyen will inform you. * A [live selfie photo](/business-accounts/verification-requirements/document-requirements/#live-selfie-photo) and a [photo id](/business-accounts/verification-requirements/document-requirements/#photo-id-requirements). These are required for each signatory of an organization legal entity, or an individual legal entity owning a sole proprietorship. Adyen uses these documents to perform verification for your platform’s safety, and to help prevent onboarding of individuals attempting impersonation fraud. ## Additional requirements for US business accounts To create business accounts for your users in the US, you must include the following requirements in your onboarding flow. Adyen will check your onboarding flow to ensure that it meets the guidelines. Business accounts are not available for governmental organizations in the US, including SOEs. | Requirement | Overview | Copy | Timing | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Patriot Act / Customer Identification Program (CIP) disclosure | The disclosure and the reason for collecting the information must be shown to the account holder. | **Important Information You Need to Know About Opening an Account.** *To help the government fight the funding of terrorism and money laundering activities, Federal law requires financial institutions to obtain, verify, and record information that identifies each person (individual or entity) who opens an account and certain individuals who are associated with an account. When you open an account, we will ask for your name, address, taxpayer identification number and other information that will allow us to identify you. What this means: When you open an account, we will ask for your name, address, taxpayer identification number and other information that will allow us to identify you.* | Must be shown before any personal information is collected from the user. For example, as the first part of your onboarding form. | | Adyen Business Account Terms of Service | Every account holder must accept Adyen's [Terms of Service](/business-accounts/onboard-users/terms-of-service) before the business account can be opened. A copy of the Terms of Service needs to be provided alongside the acceptance. See copy guidelines. | *I have read and I accept these terms and confirm that I am a legal representative authorized to accept these terms on behalf of the company. I have taken notice of the privacy statement (www\.adyen.com/privacy-policy) and I consent to my (personal) data being used for the purposes described therein.* | | | Regulation GG - Unlawful Internet Gambling Enforcement Act - Certification | Every account holder must be certified under the Regulation GG - Unlawful Internet Gambling Enforcement Act before the business account can be opened. A copy of Adyen's [Terms of Service](/business-accounts/onboard-users/terms-of-service) needs to be provided alongside the acceptance. See copy. | *Is the legal entity opening the business account engaged in internet gambling? \[Yes/No]* | This certification must be performed when the Adyen Terms of Service are accepted. | ## Next steps [required](/business-accounts/onboard-users) [Onboard users](/business-accounts/onboard-users) [Learn to move your users through the verification process](/business-accounts/onboard-users) --- # Source: https://docs.adyen.com/business-accounts/verification-requirements/data-formats-per-country.md Section: Business accounts Title: Data formats per country/region Description: Find out the accepted identification, registration, and tax ID numbers for each supported country/region. --- title: "Data formats per country/region" description: "Find out the accepted identification, registration, and tax ID numbers for each supported country/region." url: "https://docs.adyen.com/business-accounts/verification-requirements/data-formats-per-country" source_url: "https://docs.adyen.com/business-accounts/verification-requirements/data-formats-per-country.md" canonical: "https://docs.adyen.com/business-accounts/verification-requirements/data-formats-per-country" last_modified: "2024-03-25T21:41:00+01:00" language: "en" --- # Data formats per country/region Find out the accepted identification, registration, and tax ID numbers for each supported country/region. [View source](/business-accounts/verification-requirements/data-formats-per-country.md) This page lists the accepted formats and examples of data that you can collect from legal entities based on the country or region they are operating in. Adyen automatically verifies most of the information. However, in some cases, the automatic verification might fail because the data cannot be verified or it is incorrect. In these cases Adyen asks legal entities to [provide additional documents](/business-accounts/verification-requirements/document-requirements). Special characters that serve as separators, such as spaces, dashes `-`, forward slashes `/`, and dots `.`, are optional when providing values in API requests. ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen issuing](/issuing) integration, there are no additional requirements, limitations, or preparations. ## Belgium | Data for | Type | Description | Format | Example | | | | -------------------- | ------------------- | ------------------------------------------------------------------ | ------------------------ | ---------------- | - | - | | Addresses | Postal code | Postal code | 4 digits | 8500 | | | | Bank accounts | IBAN | For EUR bank accounts | 16 characters | BE59978867432226 | | | | Individuals | Tax ID | Numéro National | 11 digits | 99999999999 | | | | Organizations | Registration number | Enterprise Number Numéro d'Entreprise Ondernemingsnummer | 10 digits | 1234567890 | | | | | VAT number | Numéro de TVA BTW identificatienummer | BE + registration number | BE1234567890 | | | | | Tax ID | Business nummer, Numéro d'entreprise, Belgische ondernemingsnummer | 10 digits | 0123321123 | | | | Sole proprietorships | Registration number | Eenmanszaak or entreprise individuelle | 10 digits | 2345678901 | | | ## France | Data for | Type | Description | Format | Example | | | -------------------- | ---------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------- | --------------------------- | - | | Addresses | Postal code | Postal code | 5 digits | 75008 | | | Bank accounts | IBAN | For EUR bank accounts | 27 characters | FR6410096000403534259742Y90 | | | Individuals | Tax ID | Numéro SPI | 13 digits Optional characters: spaces | 30 23 217 600 053 | | | Organizations | Registration number | SIRET number | 14 digits Optional character: `-` | 542051180-00066 | | | | Alternative registration number for nonprofits | RNA number | `W`+ 9 digits `W`+ 1 digit +1 character + 7 digits | W123456789 W1A2345678 | | | | VAT number | Numéro d'identification à la taxe sur la valeur ajoutée | `FR` + 11 digits | FR12345678901 | | | | | Numéro de TVA intracommunautaire | `FR` + 2 digits + SIREN number (9 digits) | FR12999999999 | | | Sole proprietorships | Registration number | SIRET number | 14 digits Optional character: `-` | 542051180-00066 | | ## Germany | Data for | Type | Description | Format | Example | | | -------------------- | ------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | ---------------------- | - | | Addresses | Postal code | Postal code | 5 digits | 04571 | | | Bank accounts | IBAN | For EUR bank accounts | 22 characters | DE89370400440532013000 | | | Individuals | Tax ID | Persönliche Identifikatiosnummer (IdNr) | 11 digits | 26954371827 | | | Organizations | Registration number | Handelsregisternummer | 2-3 letters + 1-6 digits + 0-5 letters Optional: `-` + 1 letter + 4 numbers | HRB 100484 | | | | VAT number | Umsatzsteuer-Identifikationsnummer (USt-IdNr.) | `DE` + 9 digits Optional character: space | DE 115235681 | | | | Tax ID | Steuernummer | 10 or 11 digits Remove `/` before sending | 14310260208 | | | Sole proprietorships | Registration number | Handelsregisternummer | 2-3 letters + 1-6 digits + 0-5 letters Optional: `-` + 1 letter + 4 numbers | HRB 400387 | | ## Netherlands | Data for | Type | Description | Format | Example | | | -------------------- | ------------------- | --------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- | - | | Addresses | Postal code | Postal code | 4 digits + 2 letters Optional character: space | 1011 AA or 1011AA | | | Bank accounts | IBAN | For EUR bank accounts | 18 characters | NL57INGB4654188101 | | | Individuals | Tax ID | BSN | 9 digits | 999999999 | | | Organizations | Registration number | Kamer van Koophandel nummer (KvK) | 8 digits | 34179503 | | | | VAT number | Btw-nummer | `NL`+ 9 digits + `B` + `2` digits | NL123456789B01 or NL123456789B02 (for companies with VAT groups) | | | | Tax ID | Rechtspersonen en Samenwerkingsverbanden Informatienummer(RSIN) | 9 digits | 811786523 | | | Sole proprietorships | Registration number | Eenmanszaak | 8 digits | 25779503 | | ## Spain | Data for | Type | Description | Format | Example | | | ---------------------------------- | --------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | - | | Addresses | Postal code | Postal code | 5 digits | 48180 | | | Bank accounts | IBAN | For EUR bank accounts | 24 characters | ES2100490000000000000000 | | | Individuals | Identification number | Documento Nacional de Identidad (DNI) | 9–10 characters, with 8 numbers and 1-2 letters | 99999999L (Spanish residents) L9999999L (Non-resident Spaniards without DNI) K9999999L (Resident Spaniards under 14 without DNI) | | | | | Foreign Card Number (NIE, non-residents) | `X`,`Y`, or `Z` + 7 digits + 1 letter `M` + 7 digits + 1 letter | X9999999L (Foreigners with NIE) M9999999L (Foreigners without NIE) | | | | Tax ID | Documento Nacional de Identidad (DNI) | 9–10 characters, with 8 numbers and 1-2 letters | 99999999L (Spanish residents) L9999999L (Non-resident Spaniards without DNI) K9999999L (Resident Spaniards under 14 without DNI) | | | | | Foreign Card Number (NIE, non-residents) | `X`,`Y`, or `Z` + 7 digits + 1 letter `M` + 7 digits + 1 letter | X9999999L (Foreigners with NIE) M9999999L (Foreigners without NIE) | | | Organizations/sole proprietorships | Registration number | Número de Identificación Fiscal (NIF) | 1 letter + 8 alphanumeric characters | A39000013 | | | | VAT number | Número de Identificación a efectos de IVA (Impuesto sobre el Valor Añadido) | `ES`+ 9 characters | ESX12345678 or ES12345678X or ESX1234567X | | ## United Kingdom | Data for | Type | Description | Format | Example | | | ---------------------------------- | ---------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------- | - | | Addresses | Postal code | Postal code | 5-7 characters Optional character: space | EC1A 1BB, M1 1AE, or B33 8TH | | | Bank accounts | IBAN | For EUR or GBP bank accounts | 22 characters | GB63HBUK40119910000003 | | | | Sort code | For GBP bank accounts | 6 digits | 401199 | | | | Account number | For GBP bank accounts | 8 digits | 10000003 | | | Individuals | Tax ID | Unique taxpayer reference (UTR) | 10 digits | 3194027616 | | | | | National Insurance Number (NINO) | 9 characters: 2 letters + 6 digits + `A`, `B`, `C`, or `D` | AA123456C | | | Organizations/sole proprietorships | Registration number | Company number | 8 characters | 04366849 | | | | Alternative registration number for nonprofits | Charity number | 6-8 digits or 6-7 digits with 2-character prefix or 6 digits with suffix `-0` | 1234567 / SC012345 / 123456-0 | | | | VAT number | VAT registration number | `GB` + 9-12 digits | GB123456789 / GB1234567890 / GB12345678901 / GB123456789012 | | | | Tax ID | Unique taxpayer reference (UTR) | 10 digits | 1234567890 | | | Partnerships | Registration number | Unique taxpayer reference (UTR) | 10 digits | 1234567890 | | | | | VAT registration number | `GB` + 9-12 digits | GB123456789 / GB1234567890 / GB12345678901 / GB123456789012 | | ## United States | Data for | Type | Description | Format | Example | | -------------------- | ---------------------- | ------------------------------------ | --------------------------------------- | --------------------------------- | | Addresses | Postal code | Postal code | 5 or 9 digits Optional character: `-` | 11111 or 11111-1111 | | | State | State | Two-letter state code | NY | | Bank accounts | Routing number | For USD bank accounts | 9 digits | 121000248 | | | Account number | For USD bank accounts | 3-17 digits | 10220001111 | | Individuals | Identification number | Social Security Number (SSN) | Full 9 or last 4 digits | 923456789 or 6789 | | | | Driver's license number | 7–15 characters, depending on the state | Example for New York: 123 456 789 | | Organizations | Tax information number | Employer Identification Number (EIN) | 9 digits | 101002749 | | Sole proprietorships | Tax information number | Employer Identification Number (EIN) | 9 digits | 123456789 | --- # Source: https://docs.adyen.com/business-accounts/verification-requirements/document-requirements.md Section: Business accounts Title: Requirements for document uploads Description: Check the size, file format, and information required when uploading documents. --- title: "Requirements for document uploads" description: "Check the size, file format, and information required when uploading documents." url: "https://docs.adyen.com/business-accounts/verification-requirements/document-requirements" source_url: "https://docs.adyen.com/business-accounts/verification-requirements/document-requirements.md" canonical: "https://docs.adyen.com/business-accounts/verification-requirements/document-requirements" last_modified: "2023-11-29T13:31:00+01:00" language: "en" --- # Requirements for document uploads Check the size, file format, and information required when uploading documents. [View source](/business-accounts/verification-requirements/document-requirements.md) Adyen tries to verify your users based on the information that you provide. However, in some cases, the automatic verification might fail. This can be due to incorrect data or when the data cannot be verified. In these cases, Adyen may ask your user to provide additional documents, such as a passport or a bank statement. This page lists the requirements for different types of documents. ## Requirements If you have an [Adyen for Platforms](/adyen-for-platforms-model/) or [Adyen issuing](/issuing) integration, there are no additional requirements, limitations, or preparations. ## Document types for legal entities or bank accounts The following are the types of documents that Adyen may require from your user. When uploading documents, make sure that the document meets the specific requirements for individuals, organizations, sole proprietorships, or bank accounts. **Individual (includes UBOs, signatories, and sole proprietors)** [Live selfie photo](#live-selfie-photo)\ [Photo IDs](#photo-id-requirements)\ [Proof of national ID number](#national-id-proof)\ [Proof of residential address](#residential-address-proof)\ [Proof of individual tax ID](#proof-of-individual-tax-id)\ [Proof of industry](#industry-proof)\ [Proof of source of funds](#funds-proof)\ [Proof of source of wealth](#wealth-proof) **Organization** [Registration document](#registration-document)\ [Proof of address](#address-proof)\ [Proof of director](#director-proof)\ [Proof of industry](#industry-proof)\ [Proof of ownership](#ownership-proof)\ [Proof of tax information](#organization-tax-document)\ [Proof of signatory](#signatory-proof)\ [Proof of source of funds](#funds-proof)\ [Proof of source of wealth](#wealth-proof)\ [VAT document](#vat-document) **Sole proprietorship** [Constitutional document](#constitutional-doc)\ [Proof of address](#address-proof) **Bank account** [Bank statement](#bank-statement-requirements) ## Bank statement If the automatic verification of a bank account fails, Adyen may ask for a proof of bank account. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **bankStatement** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The proof of bank account can be any of the following: * Bank statements * Deposit tickets or deposit forms * Screenshots of their online banking environment * Official letters issued by a bank * Cheques Location-specific documents: * Relevé d'Identité Bancaire (RIB): bank document in France * TAMIEYTHPIO: bank document in Greece * Singaporian bank passbooks: bank document in Singapore Do not upload photos of bank-issued cards, such as credit or debit cards. These contain sensitive information. ### Requirements for all documents The document must show: * The account holder name. This must match your legal entity name. * The account number or IBAN needs to be visible. * The date of issuance needs to be visible and needs to be dated less than 12 months ago. This requirement applies to all types of documents except for RIBs, cheques, online banking environment or TAMIEYTHPIO. Some RIBs and online banking environments contain a date of issuance. The date of issuance for these must also be less than 12 months ago. * The country/region where the bank account is located. For EU bank statements, Adyen infers the country/region from the IBAN. * An indicator that the document was issued by a bank, such as the bank logo or the bank name in its bank-specific font. If the bank account is issued under the trading (doing business as) name, it may be necessary to provide a supporting document in order to establish a connection between the legal entity and the trading name. We do not accept: * Photos of bank-issued cards, such as credit or debit cards. * Edited or personalized documents. * Documents issued more than 12 months ago. * Documents where required data points are missing. * Documents with cut-off, blurry, or low-quality images. * Documents issued by third party software platforms or programs. #### Requirements for specific document types Direct deposit tickets and forms: * Must contain a bank logo or bank letterhead. * Can only be accepted with a stamp or signature from the bank. Cheques: * The name of the account holder, account number, and name of the financial institution or logo need to be printed (not handwritten). * Security features need to be visible for cheques in US and CA. * The account number and routing number need to be fully visible. * We can only accept electronic cheques issued by banks in CA. * We cannot accept any cheques issued by banks in AU. Letters from bank or bank account agreements: * Must contain a bank logo or a bank letterhead. * All letters must have a stamp or signature from the bank. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ![Visual examples of the bank statements described in this section](/user/pages/reuse/pfs-verification/verification-requirements/bank-document-infographic/bank-document.svg?decoding=auto\&fetchpriority=auto) ## Constitutional document Adyen tries to automatically verify the sole proprietorship. In case automatic verification fails, Adyen may ask for a constitutional document. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **constitutionalDocument** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The constitutional document must be: * Issued within the last 12 months, or it must contain a signature and a state of affairs with a date not older than 12 months. * The following are examples of documents accepted for sole proprietorships: * Doing business as (DBA) filing (also known as articles of incorporation, Fictitious- or Trading name filing) * Tax filing. Below are examples of accepted constitutional documents in particular locations. | Country/region | Local name for constitutional document | Example/English translation (if applicable) | | ----------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | **Europe** | | | | Belgium | Extrait de BCE/KBO/ZDU | Extract from Crossroads Bank For Enterprises | | France | Extrait K-bis, Avis de Situation au Répertoire Sirene, URSSAF/INSEE | Extract from the commercial register, Situation report, URSSAF/INSEE Extract | | Germany | Gewerbe Anmeldung (GewA 1 or 2), Gewerbeschein, Bescheinigung über... | Trade registration, trade licence, Taxpayer registration certificate | | Netherlands | Uittreksel Handelsregister | Extract from the Chamber of Commerce | | Spain | Communicación de Tarjeta Acreditativa del NIF, Certificación de... | | | United Kingdom | UTR Confirmation Letter, Tax return | | | **North America** | | | | United States | SS-4 confirmation letter, Schedule C, EIN Confirmation Letter (CP 575) | | The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 30 MB * Size for other formats: minimum 100 KB, maximum 30 MB ## Live selfie photo Only applicable when using [onboarding v4](/platforms/onboard-users/onboarding-versions/onboarding-v4). This requirement applies to: * each signatory of an organization legal entity * an individual legal entity owning a sole proprietorship To enhance your platform’s safety and to help prevent onboarding of individuals attempting impersonation fraud, Adyen has a partnership with Onfido, an identity verification company, to verify users through the evaluation of a live selfie photo against a [photo ID document](#photo-id-requirements). When requesting business accounts, users need to provide a live selfie photo, along with a photo ID document. These documents are used for biometric verification. If the verification for an individual's identification fails, Adyen may ask for a new live selfie photo (or a [photo ID](#photo-id-requirements)). When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **liveSelfie** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. ### Collection requirements for live selfie photos **Display Onfido and Adyen terms** Take the following steps to satisfy Onfido’s requirements for privacy notices and consent: 1. Explain to your end users that your partner (Adyen) uses a third party, Onfido, to process their identity check. For example: > "To proceed with onboarding, we require that you provide a live selfie photo of yourself, and a photo of your ID. >We use technology developed by Adyen and Onfido to perform the verification of the photo data you provide. For information on how Adyen uses your data, see [Adyen's privacy statement](https://www.adyen.com/policies-and-disclaimer/privacy-policy)." 2. Present your users with Onfido consent language before asking them to proceed with the check powered by Onfido. For example: > "I have read, understand, and accept the [Onfido Facial Scan Policy and Release](https://www.entrust.com/legal-compliance/data-privacy/facial-scan-policy-and-release), [Onfido Privacy Policy](https://www.entrust.com/sites/default/files/documentation/licensingandagreements/product-privacy-notice-identity-verification-services.pdf), and [Onfido Terms of Service](https://www.entrust.com/legal-compliance/terms-conditions/idv/terms-of-service)." You may change the phrasing of your consent statement to be consistent with your user experience, as long as you obtain confirmation that the end user has read, understood, and accepted Onfido's policies and terms of service. For example: > "By continuing to use this service, you confirm that you have read, understand, and accept the [Onfido Facial Scan Policy and Release](https://www.entrust.com/legal-compliance/data-privacy/facial-scan-policy-and-release), [Onfido Privacy Policy](https://www.entrust.com/sites/default/files/documentation/licensingandagreements/product-privacy-notice-identity-verification-services.pdf), and [Onfido Terms of Service](https://www.entrust.com/legal-compliance/terms-conditions/idv/terms-of-service)." or > "By checking "accept", you confirm you have read, understand, and accept the [Onfido Facial Scan Policy and Release](https://www.entrust.com/legal-compliance/data-privacy/facial-scan-policy-and-release), [Onfido Privacy Policy](https://www.entrust.com/sites/default/files/documentation/licensingandagreements/product-privacy-notice-identity-verification-services.pdf), and [Onfido Terms of Service](https://www.entrust.com/legal-compliance/terms-conditions/idv/terms-of-service)." 3. Ensure that you provide URL links to the Onfido and Adyen policies within your application. | Policy name | URL to policy | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Adyen Privacy Statement | | | Onfido Facial Scan Policy and Release | | | Onfido Privacy Policy | | | Onfido Terms of Service | | **Collect a live selfie from your users** To make optimal use of this safety feature, we recommend your users take a live selfie photo directly within your onboarding flow, instead of allowing them to upload a photo taken separately from their phone or camera. If the only possible way to implement this feature in your onboarding flow is through a photo upload mechanism, the live selfie photo must be uploaded within 24 hours from when the photo was taken. **Live selfie photo requirements** To determine sufficient quality of the live selfie photo your user provides, consider the following: * **The live selfie photo is a first-hand capture**: it should be a direct photo of the person, and not be taken by another party. * **Angle of the photo**: the live selfie photo should be taken in such a way that captures the face from a similar angle as the portrait on the supplied [photo ID](#photo-id-requirements). * **Distance from the camera**: the distance of the person’s face from the camera has to be appropriate to both capture the shoulders and full face in the photo, and to see sufficient facial features and details. * **Focus and clarity**: The live selfie photo must be in-focus, and cannot be blurry. * **The live selfie photo is not altered**: There can be no alteration of the live selfie photo of any kind. * **Lighting**: The live selfie photo, and the space where the photo is taken, must be well-lit. Facial features must not be obscured by shadows. * **Objects cannot block facial features**: There should be no objects in the photo that hide any facial features.\ This includes (but is not limited to) the following: * Sunglasses * Headwear * On-ear or over-ear headphones and headsets * Other accessories * Clothing * Fingers blocking the camera\ \ **Exceptions**: * Eyeglasses with no tints * Religious clothing, headwear or accessories can be present in the selfie, only if they are also present on the identity document. * Medical equipment that cannot be reasonably removed can be present in the selfie. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Photo IDs If the automatic verification for an individual's identification number fails, Adyen may ask for a photo ID. The name in the photo ID must match the name sent to Adyen during onboarding. If the names are different—for example, your user provided their married name to register but their passport has their maiden name—the photo ID check will fail. The first and last name provided when creating the legal entity must match the photo ID exactly. If the individual only has one name, they must use this name for both the first and last name fields when creating the legal entity. The following are the accepted photo ID documents, along with the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) that you must set in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. You must include both the front and back of the identity card or driver's license in the same `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. | Photo ID | `type` | Notes | | ---------------- | ------------------ | ------------------------------------------------------------------------------------- | | Passport | **passport** | Must be the data page (picture, MRZ, and details) | | Identity card | **identityCard** | Must be a government-issued identity card. Front and back, each side in its own file. | | Driver's license | **driversLicense** | Front and back, each side in its own file. | The photo ID must: * Be non-expired. * Have the [machine-readable zone](https://en.wikipedia.org/wiki/Machine-readable_passport) visible (if available). * Be a physical photo ID document, not digital. * If there is an available field for a signature in the document, it must be signed. The uploaded document must: * Have separate files for front and back of the ID document (only when providing an ID card or driver's license). * Be a full color and straightened image. The corners and edges of the ID must be fully visible. * Be a photo or a scan of the physical photo ID document. We do not accept: * Digital IDs. * Secondary copies of IDs. These include screenshots of photos, a photo pasted onto another document, a photo of a screen, or a photo of a printout. * Low-quality images. The uploaded document can be a maximum of 15 pages. #### Additional information for specific countries/regions | Country | Notes | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | France | The validity of French national ID cards issued between 2 January 2004 and 31 December 2013 has been extended for 5 years beyond the original expiration date. The original period of validity of these cards was set at 10 years. Following the extension, they are now valid for 15 years from the year of issue. Note that f the card holder was under the age of 18 when the ID was issued, this extension does not apply. The extension does not apply to any other document types. | | Poland | Polish driving licenses do not show an expiration date. Any licenses issued before 2013/19/01 are valid until 2033. They must be exchanged for a new license prior to this date. | | Ukraine | Ukrainian passports are considered valid for 5 years from the original submission date for the extension of its validity period. A signed and stamped passport page must be included. | The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ![Visual examples of the photo IDs described in this section](/user/pages/reuse/pfs-verification/verification-requirements/photo-id-infographic/id-document.svg?decoding=auto\&fetchpriority=auto) ## Proof of address Adyen uses the data to automatically verify your user's address. In case automatic verification fails, Adyen may ask for a proof of address. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfAddress** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The proof of address must be: * Issued by a reliable, independent source such as the local commercial register of the country/region where the business is registered in. * Issued within the last 12 months, or it must contain a signature and a state of affairs with a date not older than 12 months. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of individual tax ID If the automatic verification for an individual's tax ID fails, Adyen may ask the individual to upload a tax identification document. Set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfIndividualTaxId** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. | Country/region | Tax Document requirements | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Belgium (BE) | Official document containing Numéro National and name of individual. | | France (FR) | Official document containing Simplification des Procédures d'Imposition / numéro fiscal de référence / numero SPI and the name of individual. The number can be found on the pre-printed income tax declaration form or on income tax/property tax notices. | | Germany (DE) | Official document containing Persönliche Identifikatiosnummer (IdNr) and name of individual. | | Netherlands (NL) | Official document containing Burgerservicenummer (BSN) and name of individual. | | Spain (ES) | Official document containing Documento Nacional de Identidad (DNI) or Foreign Card Number (NIE), and name of individual. | | United Kingdom (GB) | Official document containing Unique Taxpayer Reference (UTR) number or National Insurance Number (NINO), and name of individual. | | United States (US) | Official document containing Social Security Number (SSN), Employer Identification Number (EIN), or Individual Taxpayer Identification Number (ITIN), and name of individual. | ## Proof of industry If the automatic verification of an industry fails, Adyen may ask for a proof of industry. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfIndustry** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. A proof of industry can be a VAT document, a proof of tax information, or a registration document that includes a local or a global industry code. For example, **SBI** in the Netherlands, **NACE** in the European Union, or **SIC** in the United Kingdom. For the document requirements, see: * [Proof of tax information](#organization-tax-document) for organizations * [VAT document](#vat-document) for organizations * [Registration document](#registration-document) for organizations * [Proof of tax individual tax ID](#proof-of-individual-tax-id) for individuals ## Proof of national ID number If the automatic verification of a national ID number fails, Adyen may ask for a proof of the national ID number. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfNationalIdNumber** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The proof of national ID number must: * Have the name of the individual. * Have the national ID number. * Be issued by a reliable, independent source such as a government agency, public authority, or judicial authority. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of organization tax information In case automatic verification for tax ID fails, Adyen may ask for a proof of tax information. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfOrganizationTaxInfo** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The tax ID document needs to * Be issued by a public authority, government agency or judicial authority. * State the legal entity name and the tax ID number. * State the country/region where the business is registered. * Contain an issuance date within the last 12 months, or be signed and dated by a legal representative within the last 12 months. Note the following: * The “doing business as” / “trading as” name cannot be accepted as the legal name of your company. Please make sure to fill in the correct legal entity name. * For some countries/regions, the VAT number is not the same as the tax ID number. Please check [local names for tax ID numbers](/business-accounts/verification-requirements/data-formats-per-country/). The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of ownership If the automatic verification of an ultimate beneficial owner (UBO) through ownership fails, Adyen may ask for proof of ownership. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfOwnership** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. To verify this information, Adyen requires a visual diagram of the ownership and control structure of the legal entity. The diagram must show the associated legal entities and ultimate beneficial owners (UBOs) of the legal entity. The ownership and control chart must include: * The full ownership and control structure of all legal entities and UBOs under review, including all intermediate companies. * The official legal entity name, legal structure, and registered country/region for every entity on the chart. * The ownership and control relationship between the entities, including ownership percentages. * Indication of how the criteria for identifying UBOs are fulfilled, for example an individual owning 25% of the total shares of a company. * A signature confirming the content of the organizational chart, the name and job title of the signing person, and the date of the signature (not older than 6 months from the current date). ![](/user/pages/reuse/pfs-verification/verification-requirements/doc-proof-of-ownership/ownership-and-control-chart.svg?decoding=auto\&fetchpriority=auto) If the person signing the organizational chart is one of the following, you do not need to send any additional documents: * An internal person who is a qualified professional such as a lawyer, accountant or auditor, and whose qualification can be verified through the official website of their professional body. The professional body must be located in the registered country/region of the organization or in the same country/region as another entity in the ownership and control chart. * An external person or a professional body, certified by a consultancy firm, notary, lawyer, auditor, or other comparable official legal service provider from the registered country/region of the legal entity or entities under review. []()\ **External official documents**\ If the internal person signing the ownership and control chart does not meet the above criteria, you must send official documents that support the submitted ownership and control information. Examples of official documents include: * Securities register * Shareholder register * Ultimate Beneficial Owner register * Articles of incorporation * Annual reports * Annual returns * Certificate of Corporate Status * Shareholder Agreements * Assignment Agreements * Partnership Agreements * Board of directors' meeting records of decisions * Registration document * Certificate of incumbency The official document must: * State the information about the UBOs associated with the legal entity under review, including all intermediate entities involved in the ownership structure * Not be older than 6 months from the current date * Be an external document If your legal entity is located in the Netherlands, Adyen may ask for a UBO extract. This can be downloaded from the [KvK website](https://www.kvk.nl/en/ordering-products/kvk-ubo-register-extract/). The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of residential address If the automatic verification of a residential address fails, Adyen may ask for a proof of the residential address. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfResidency** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The following sources can be used as proof of residence documentation. These documents must not be older than the period specified below. | Cannot be older than... | Type of document | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 3 months | * Bank statement * Utility Bill (gas, water, electric, cable TV (no satellite TV companies), internet (landline)) * Taxation Document * Extract from Municipal Personal Records Database * Salary slip (containing the company letterhead) * Contract of Employment (containing the company letterhead) * Government-issued correspondence (receipt of benefits such as pension, unemployment benefits, housing benefits, or healthcare) | | 12 months | - Mortgage statement - Certificate of voter registration | The proof of residency must: * Have the name of the individual. * Have the full residence address, residence country/region, and residence state (when applicable). * Have a date within the last 3 or 12 months depending on the document type. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ![Visual examples of the residential address documents described in this section](/user/pages/reuse/pfs-verification/verification-requirements/doc-proof-of-residential-address-infographic/residency-document.svg?decoding=auto\&fetchpriority=auto) ## Proof of signatory If the automatic verification of your user's proof of signatory fails, Adyen may ask the user to upload supporting documentation as proof of the signatory's authority. When uploading a proof of signatory document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfSignatory** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. Adyen accepts the following documents to prove the signatory’s authority: * trade registry document * internal company document **Trade registry document**\ If you are supplying a local trade registry extract, the document must contain the following: * The name of the person acting as the authorized signatory * The name of the company the authorized signatory represents * A date of issuance not older than 12 months, *or* the document has been signed and dated by a legal representative within the past 12 months Trade registry documents have different names within each country/region where Adyen offers business accounts, listed in the following table: | Country/region | Document name | | ------------------- | --------------------------------------------- | | France (FR) | Extrait K-Bis | | United Kingdom (UK) | Confirmation Statement | | Germany (DE) | Handelsregisterauszug Handelsregisterausdruck | | Netherlands (NL) | Uittreksel Handelsregister | **Internal company document**\ If you are supplying an internal company document as proof of signatory, the document must contain the following: * State of affairs confirming that the authorized signatory has authority to sign of behalf of the company * The name of the person acting as the authorized signatory * The name of the company the authorized signatory represents * A date of issuance not older than 12 months * The document has been signed and dated by a legal representative within the past 12 months * The name, job title, and signature of the signing person Accepted internal company documents:\ Board of Directors meeting minutes (FR, UK, DE, NL). The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of source of funds If the automatic verification of your user's [source of funds](/business-accounts/verification-requirements/reference-additional-products#list-source-of-funds) fails, Adyen may ask for proof of their source of funds. This information must identify the main source of the funds or assets that are deposited to an Adyen business account. To submit the data, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfFundingOrWealthSource** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. | Source of funds type | Description | Supporting Documents | | ------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Business (profits generated from commercial activities) | A description of the industry and business model of the business | A copy of (audited) latest accounts | | | | A copy of annual statements | | | | A letter from a regulated accountant giving details of company profits over the last 2 years | The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of source of wealth Adyen may contact you for proof of your user's source of wealth. This information must show the total amount of wealth and the main sources of that wealth, with a particular emphasis on the sources that generated the majority of the wealth. To submit the data, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfFundingOrWealthSource** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. ** ### Required information for sources of wealth | Source of wealth type | Description | Supporting Documents | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Business (profits generated from commercial activities) | a description of the industry and business model of the business | a copy of (audited) latest accounts | | | | a copy of annual statements | | | | a letter from a regulated accountant giving details of company profits over the last 2 years | | (Savings from) Employment (salary, wages, bonuses, pension, etc.) | your role | the pay slips (last three months) | | | your annual salary (most recent year) | the salary section of your contract | | | your employer's name | confirmation from employer of total income | | | your employer's address | bank statements that clearly show receipt of the most recent 3 months’ regular salary payments from the stated employer | | | the nature of employer's business | a tax document (most recent) | | | the dates you were employed | ibid. | | Donations/Gifts | the date of the donation/gift | Letter from donor confirming details of gift and acknowledging the source of the donated funds | | | the date you received the money | Based on the SOW specified, the donor might need to provide supporting documentation as per the provisions of this table | | | the amount you received | ibid. | | | the ground (reason) for the donation | ibid. | | | the name, date of birth (if natural person) and address of originator (benefactor) | ibid. | | | the relationship between you and the funder (benefactor) | ibid. | | | the source of donated funds | ibid. | | Inheritance | the date you received the money | a grant of probate (with a copy of the will) which must include the value of the estate | | | the amount you received | a tax document | | | the name, date of birth and address of the originator (benefactor) | a bank statement showing you received the money | | | the relationship between you and the funder (benefactor) | a solicitor’s letter | | Rental Income (for example property rentals) | the amount you receive (yearly) | proof of property ownership | | | the address of the property | a tax document | | | | the rental agreement | | Capital market income (for example capital gains, or dividend payments) | the amount you receive (yearly) | a tax document | | | a description of the capital held | an investment holdings/savings certificate, contract note or statement | | | the time of investment held (in months) | a confirmation from the relevant investment company (company letterhead) | | | | a (signed) letter detailing funds from a regulated accountant | | Royalty Income (for example patents, copyrighted works, natural resources) | the amount you receive (yearly) | a tax document | | | a description of the royalties held | ibid. | | | the time of royalties held (in months) | ibid. | | Crypto currency income (for example, trading, standing profits, mining) | the amount you receive (yearly) | a tax document | | | a description of the type of crypto held | a standardized statement from digital asset exchange | | | the exchange on/from which the amount is received | a proof of balance at crypto exchange(s) | | | the total time that the crypto has been held (in months) | a signed message on crypto wallet | | Asset sale (for example real estate, vehicles or other assets) | the date of the sale | the sale contract signed (countersigned) | | | the date you receive the money | a (signed) letter from a solicitor, auditor or regulated accountant | | | the amount you received | a bank statement showing the received amount | | | the type of asset (real estate, vehicle, company, etc) | a title deed | | | the time of asset held (in months) | a tax document | | | the address (if real estate) | ibid. | | Loans | the date of the loan | the loan agreement | | | the date you received the money | a recent loan statement | | | the amount you received | ibid. | | | the name, date of birth (if natural person) and address of the lender | ibid. | | | the purpose of the loan | ibid. | | | the duration of the loan | ibid. | | Lottery/Betting/Casino winnings | the date you received the winnings | a tax document | | | the amount you received | a bank statement showing you received the money | | | the name, address and website (if online) of the originator (lottery/casino) | a proof of winnings from lottery/casino (company letterhead) | | Other | the date you received the money | a (signed) letter from a solicitor, auditor or accountant | | | the amount you received | a written confirmation from the payer | | | the name, date of birth (if natural person) and address of the originator | a bank statement showing you received the money | | | the ground (reason) for receiving the money | ibid. | The examples of supporting documents listed above are illustrative. A document is acceptable if it provides the information listed in the description for the source of wealth type. Reach out to your Adyen contact to confirm other types of documents that can be used for verification. The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Proof of relationship If you are onboarding a minor user, Adyen may ask the minor to upload a document showing the the relationship between them and their legal representative. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **proofOfRelationship** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. Examples of acceptable official documents include: * Birth certificate * Adoption certificate * Legal guardianship certificate The official document must: * State information about the legal representative associated with minor * State the relationship between the legal representative and minor * Be an external document The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ## Registration document Adyen uses the name and registration number to automatically verify your user. In case automatic verification fails, Adyen may ask for a registration document. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **registrationDocument** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The registration document must be: * Be issued by a public authority, government agency or judicial authority. The registration document is typically issued when a business is registered at the local commercial register. * State the legal entity name and registration number. * Contain an issuance date within the last 12 months, or be signed and dated by a legal representative within the last 12 months. Note the following: * The “doing business as” / “trading as” name cannot be accepted as the legal name of your company. Please make sure to fill in the correct legal entity name. * For some countries/regions, the VAT number is not the same as the tax ID number. The following list of examples for registration documents is not exhaustive. Different documents may be accepted if they meet the above requirements. For more information about the required formats for registration numbers, see [here](/business-accounts/verification-requirements/data-formats-per-country). | Country | ISO-2 code | Issued by | Local name for registration number | Local name for registration document | English translation (if applicable) | | | ------------------------ | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | - | | Australia | AU | Australian Securities & Investments Commission (ASIC) | Australia Business Number (ABN) or Australia Company Number (ACN) | Record of Registration for Business Name | N/A | | | Austria | AT | Firmenbuch | Firmenbuchnummer | Firmenbuchauszug | Extract from the Commercial Register | | | Belgium | BE | Banque-Carrefour des entreprises (BCE) | Company number or Numéro d'Entreprise | Certificat D'Inscription | Certificate of Registration | | | Bulgaria | BG | ТРРЮЛНЦ - Търговски регистър | ЕИК | Удостоверение от агенция по вписванията | Certificate of Registration | | | Canada | CA | Canada Revenue Agency Business | Business Number (BN) | Certificate of Registration | Certificate of Registration | | | Croatia | HR | Sudski registar - Ministarstvo pravosuđa | Matični broj subjekta (MBS) | Izvadak Iz Sudskog Registra | Extract from Court Register | | | Cyprus | CY | Τμήμα Εφόρου Εταιρειών | Αριθμός Εγγραφής | Πιστοποιητικό Σύστασης | Certificate of Incorporation | | | Czech Republic | CZ | Obchodní rejstřík | Identifikační číslo (IČO) | Výpis z Obchodního rejstříku | Extract from the Commercial Register | | | Denmark | DK | Erhvervsstyrelsen | CVR-nummer | Virksomhedsrapport | Company extract | | | Estonia | EE | Tartu Maakohtu | Registrikood | Registrikaart | Extract from the Commercial Register | | | Finland | FI | Kaupparekisteri | Y-TUNNUS | "Kaupparekisteriote | Extract from the Commercial Register | | | France | FR | Greffes des tribunaux de commerce | SIRET/SIREN | L'extrait Kbis | Certificate of Incorporation (Kbis) | | | Germany | DE | Handelsregister | Handelsregisternummer | Aktuellen/Chronologischer Handelsregisterauszug | Extract from the Commercial Register | | | Greece | GR | Γενικό Εμπορικό Μητρώο | GEMI number or ΑΡΙΘΜΟΣ Γ.Ε.ΜΗ (Γενικού Εμπορικού Μητρώου) | Ανακοίνωση Καταχώρισης στο Γενικό Εμπορικό Μητρώο | Notice of Registration in the General Commercial Register | | | Hungary | HU | Cégbíróság | Cégjegyzékszám | Cégkivonat | Company extract | | | Ireland | IR | Companies Registration Office | Company number | Extract from the commercial register | N/A | | | Italy | IT | "Agenzia delle Entrate" | Codice fiscale or CCIAA number | Certificato Di Attribuzione Del Codice Fiscale | Certificate of Allocation of Tax Code | | | Latvia | LV | Latvijas Republikas Uzņēmumu reģistrs | Reģistrācijas numurs | Izzina | Certificate of Incorporation | | | Liechtenstein | LI | Handelsregister | Unternehmensnummer | Handelsregister-Auszug | Extract from the Commercial Register | | | Lithuania | LT | Registrų centras | Įmonės kodas | Juridinių Asmenų Registro Išrašus | Extract from the Registry of Legal Entities | | | Luxembourg | LU | Registre de commerce et des sociétés | RCS number, Registernummer, or Numéro RCS | Extrait de Registre de Commerce | Extract from the Registry of Commerce and Companies | | | Malta | MT | Malta Business Registry | Company registration number | Certificate of Incorporation | N/A | | | Netherlands | NL | Kamer van Koophandel (KvK) | Kamer van Koophandel nummer (KvK) | Uittreksel Handelsregister/Uittreksel van KVK | Extract from the Chamber of Commerce | | | Norway | NO | Brønnøysundregistrene | Organisasjonsnummer | Registerutskrift | Company extract | | | Poland | PO | National Court Register (NCR) | Numer Krajowy Rejestr Sądowy (KRS)/ REGON numer | Informacja Odpowiadająca Odpisowi Aktualnemu z Rejestru Przedsiębiorców | Company extract | | | Portugal | PT | Registo Comercial | Número de Identificação de Pessoa Colectiva (NIPC) | Certidão permanente de registo comercial | Permanent Certificate of Registration | | | Romania | RO | Oficiul Național al Registrului Comerțului | Numar de ordine in registrul comertului | Certificatul de înregistrare | Registration Certificate | | | Singapore | SG | Accounting and Corporate Regulatory Authority (ACRA) | Unique Entity Number (UEN) | Certificate Confirming Incorporation of Company | N/A | | | Slovakia | SK | Obchodný register | Identifikačné číslo (IČO) | Výpis z Obchodného registra | Extract from the Commercial Register | | | Slovenia | SI | Agencija Republike Slovenije za javnopravne evidence in storitve – AJPES | Matična številka | Izpisek iz Poslovnega registra Slovenije - AJPES | Extract from the Commercial Register | | | Spain | SP | Registro Mercantil Central (RMC) | Número de Identificación Fiscal (NIF) | Certificado tributario de la Agencia Tributaria | Tax Certificate | | | Sweden | SE | Bolagsverket | Organisationsnummer | Registreringsbevis | Company extract | | | Switzerland | CH | Handelsregister | Unternehmens-Identifikationsnummer (UID), Numéro d'identification des entreprises (IDE), Numero d'identificazione delle imprese (IDI), or CH-number | Handelsregisterauszug | Extract from the Commercial Register | | | United Kingdom | GB | Companies House | Company Number | Certificate of Incorporation | N/A | | | United States of America | US | Internal Revenue Service (IRS) | Employer Identification Number (EIN) | SS-4 Confirmation Letter | N/A | | The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ![Visual examples of the registration documents described in this section](/user/pages/reuse/pfs-verification/verification-requirements/doc-registration-infographic/company-document.svg?decoding=auto\&fetchpriority=auto) ## VAT document In case automatic verification for VAT number fails, Adyen may ask for a VAT document. When uploading this document, set the [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) to **vatDocument** in your `POST` [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request. The VAT document must: * Be issued by a public authority, government agency or judicial authority. * State the legal entity name and the VAT number. * State the country of where the business is registered. * Contain an issuance date within the last 12 months, or be signed and dated by a legal representative within the last 12 months. Note the following: * The “doing business as” / “trading as” name cannot be accepted as the legal name of your company. Please make sure to fill in the correct legal entity name. * For some countries/regions, the VAT number is not the same as the tax ID number. Please check [local names for VAT numbers](/business-accounts/verification-requirements/data-formats-per-country/). The uploaded document must meet the following file format and size requirements: * Formats: JPEG, JPG, PNG, or PDF (maximum 1 file) * Size for PDFs: minimum 1 KB, maximum 15 MB * Size for other formats: minimum 100 KB, maximum 15 MB ![Visual examples of the VAT documents described in this section](/user/pages/reuse/pfs-verification/verification-requirements/doc-vat-infographic/vat-document.svg?decoding=auto\&fetchpriority=auto) --- # Source: https://docs.adyen.com/business-accounts/verification-requirements/reference-additional-products.md Section: Business accounts Title: Reference for additional capabilities Description: Learn what additional information is required to offer business accounts to your users. --- title: "Reference for additional capabilities" description: "Learn what additional information is required to offer business accounts to your users." url: "https://docs.adyen.com/business-accounts/verification-requirements/reference-additional-products" source_url: "https://docs.adyen.com/business-accounts/verification-requirements/reference-additional-products.md" canonical: "https://docs.adyen.com/business-accounts/verification-requirements/reference-additional-products" last_modified: "2023-12-06T13:50:00+01:00" language: "en" --- # Reference for additional capabilities Learn what additional information is required to offer business accounts to your users. [View source](/business-accounts/verification-requirements/reference-additional-products.md) Find out which values you can use for the [FATCA/CRS](#list-fatca-crs), [industry codes](#list-industry-codes), and [source of funds](#list-source-of-funds). ## FATCA/CRS Under [FATCA]() and [CRS legislation](https://www.oecd-ilibrary.org/taxation/standard-for-automatic-exchange-of-financial-account-information-in-tax-matters-second-edition_9789264267992-en), Adyen NV as a licensed Dutch Financial Institution is legally required to both: * Identify its financial account holders. * Report details of reportable financial account holders to the relevant tax authorities. To open a financial account with Adyen, you must provide additional information about yourself or your entity. To determine if your account is reportable under FATCA or CRS, Adyen requires a self-certified FATCA/CRS qualification. After you complete the self-certification, no further action is required unless your information changes. FATCA/CRS self-certification is **not required** for US-based legal entities applying for US business bank accounts. #### Decision tree **Complete the self-certification process** Follow these steps to confirm your status **Is your business a privately owned company with the majority (50%) of the income coming from operational activities from the business itself?** * **Self-certify as Active NF(F)E** Based on your answers, Adyen classifies your business as a non-financial business who receives the majority of its income through active income. Self-certify as `nonFinancialActive` and submit this information in your API request. For more information, please visit our [website](https://help.adyen.com/en_US/knowledge/compliance/regulations/what-are-fatca-and-crs-and-do-they-affect-me) * **Choose your self-certification status** * Non-financial active: `nonFinancialActive` or * Non-financial passive: `nonFinancialPassive` Submit this information in your API request. * **Contact Adyen** If you are unsure about your classification status, contact Adyen for more information. * **Is your business one of the following?** * Publicly listed entity * Subsidiary of a publicly listed entity * Governmental entity * International organization If yes, self-certify as `nonFinancialNonReportable`. Please submit the information in your API request. * **Global intermediary identification number** Look up your [Global Intermediary Identification Number](https://apps.irs.gov/app/fatcaFfiList/flu.jsf) (GIIN) that is assigned to you by the Internal Revenue Service (IRS). Self-certify as `financialNonReportable`. Submit this and your GIIN in your API request. * **What is the main source of income (>50 %) of your business?** | Source of income | Business classification | | ------------------------------------------- | ------------------------------------- | | Operational activity from the business | Self-certify as `nonFinancialActive` | | Real estate sales | Self-certify as `nonFinancialActive` | | Investments, stocks, interest, or royalties | Self-certify as `nonFinancialPassive` | | Income from property rental | Self-certify as `nonFinancialPassive` | * **Self-certification** You should self-certify as either: * `nonFinancialPassive`or * `nonFinancialActive` Submit this information in your API request. For more information, please visit our website: www\.adyen.com/fatca-crs If you do not agree with this classification, reach out to your contact for more information. ## Industry codes list As a financial institution, Adyen has a legal obligation to collect information about the line of business from your users. This is done by capturing *industry codes*. You are required to provide industry codes for your users when requesting business accounts. These codes can represent the industry in which the user is registered based on their local registry (for example, chamber of commerce or secretary of state). To submit this information to Adyen, make a POST [/businessLines](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines) request. Select the industry code that most accurately represents the business activity of the user. For some industries, Adyen requires approval before onboarding users. In this case, contact your Adyen Account Manager, Implementation Manager, or [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) for further guidance. After collecting industry codes, Adyen also makes this data available for you, in case you want to gain insights on your balance platform users. Industry codes have been mapped to merchant category codes (MCCs) and adapted based on our internal regulations. We only accept the following values listed below for industry codes. To offer business accounts to users in *any new industries* that were not part of the previous approval process, you must contact your Adyen Account Manager or our Support Team. ### Tab: Approval needed | Industry code | Description | | ------------- | --------------------------------------------------------------------------------------- | | 3121A | Alcoholic beverage manufacturing | | 324 | Petroleum and coal products manufacturing | | 3254 | Pharmaceutical and medicine manufacturing | | 3259 | Other chemical product and preparation manufacturing | | 339A | Jewelry, precious stone, precious metal and silverware manufacturing[ 1](#fn1) | | 339C | Medical equipment and supplies manufacturing | | 42311 | Automobile and other motor vehicle merchant wholesalers[ 1](#fn1) | | 42312 | Motor vehicle supplies and new parts merchant wholesalers | | 42313 | Tire and tube merchant wholesalers[ 1](#fn1) | | 42314 | Motor vehicle parts (used) merchant wholesalers | | 42345 | Medical, dental, and hospital equipment and supplies merchant wholesalers | | 42394 | Jewelry, watch, precious stone, and precious metal merchant wholesalers[ 1](#fn1) | | 4242 | Drugs and druggists' sundries merchant wholesalers | | 4246 | Chemical and allied products merchant wholesalers | | 4247 | Petroleum and petroleum products merchant wholesalers | | 4248 | Beer, wine, and distilled alcoholic beverage merchant wholesalers | | 44111 | New car dealers[ 1](#fn1) | | 4411B | Used cars - reputable dealers | | 44132 | Tire dealers[ 1](#fn1) | | 4461A | Nutraceutical stores (non-food) | | 44611 | Pharmacies and drug stores | | 44619A | Food (Health) supplement stores (nutraceuticals, food) - regulated[ 2](#fn2) | | 446191 | Food (Health) supplement stores (nutraceuticals, food) - non-regulated | | 44831 | Jewelry stores[ 1](#fn1) | | 4453 | Beer, wine, and liquor stores | | 452A | Buying and shopping services and clubs | | 4539B | Stamp and coin stores | | 4539D | Auction houses | | 45392 | Art dealers[ 1](#fn1) | | 45431 | Fuel dealers | | 487 | Scenic and sightseeing transportation[ 5](#fn5) | | 52231 | Mortgage and non-mortgage loan brokers | | 524114 | Direct health and medical insurance carriers | | 52412 | Direct insurance (except life, health, and medical) carriers | | 52413 | Reinsurance carriers | | 5242 | Agencies, brokerages, and other insurance related activities | | 5311 | Lessors of real estate | | 5312 | Offices of real estate agents and brokers | | 5313 | Activities related to real estate | | 5417A | Ancestry research | | 56145 | Credit bureaus | | 5615 | Travel arrangement and reservation services | | 6211 | Office of physicians | | 6212 | Office of dentists | | 62131 | Office of chiropractors | | 62132 | Offices of optometrists | | 62133 | Offices of mental health practitioners | | 62134 | Offices of physical, occupational and speech therapists, and audiologists | | 62139 | Offices of all other health practitioners | | 6215 | Medical and diagnostic laboratories | | 6216 | Home health care services | | 621A | Commercial private health and e-doctor services | | 622 | Hospitals | | 623 | Nursing and residential care facilities | | 711A | Ticketing agencies | | 7211A | Timeshares | | 7224 | Drinking places (alcoholic beverages) | | 8129C | Pseudo science services (astrology, psychokinesis, clairvoyance, fortune telling, etc.) | | 81394 | Political organizations | | 921 | Executive, legislative, and other general government support | | 922A | Fines and penalties of any kind | | 92219 | Other justice, public order, and safety activities | | 92B | Other public administrations | []()1Only when average transaction value (ATV) is EUR 2000 or less. []()2Includes CBD, kava kava, baby formula, and baby food. []()5American Express is not supported for this industry code. ### Tab: No approval needed | Industry code | Description | | ------------- | ----------------------------------------------------------------------------------------------------------- | | 11 | Agriculture, forestry, fishing, and hunting | | 2211 | Electric power generation, transmission, and distribution | | 2212 | Natural gas distribution | | 2213 | Water, sewage, and other systems | | 23 | Construction & installation | | 311 | Food manufacturing | | 3121B | Non-alcoholic beverage manufacturing | | 313 | Textile mills | | 314 | Textile product mills | | 315 | Apparel manufacturing | | 316 | Leather and allied product manufacturing | | 321 | Wood product manufacturing | | 322 | Paper manufacturing | | 323 | Printing and related support activities | | 3255 | Paint, coating, and adhesive manufacturing | | 326 | Plastics and rubber products manufacturing | | 327 | Nonmetallic mineral product manufacturing | | 331 | Primary metal manufacturing | | 332 | Fabricated metal product manufacturing | | 333 | Machinery manufacturing | | 334 | Computer and electronic product manufacturing | | 335 | Electrical equipment, appliance, and component manufacturing | | 336 | Transportation (equipment) manufacturing | | 337 | Furniture and related product manufacturing | | 339D | Other miscellaneous durable goods manufacturing | | 339E | Other miscellaneous nondurable goods manufacturing | | 4232 | Furniture and home furnishing merchant wholesalers | | 4233 | Lumber and other construction materials merchant wholesalers | | 42341 | Photographic equipment and supplies merchant wholesalers | | 42342 | Office equipment merchant wholesalers | | 42343 | Computer and computer peripheral equipment and software merchant wholesalers | | 42344 | Other commercial equipment merchant wholesalers | | 42349 | Other professional equipment and supplies merchant wholesalers | | 4235 | Metal and mineral (except petroleum) merchant wholesalers | | 4236 | Household appliances, electrical, and electronic goods merchant wholesalers | | 4237 | Hardware, plumbing, and heating equipment and supplies merchant wholesalers | | 4238 | Machinery, equipment, and supplies merchant wholesalers | | 42399 | Other miscellaneous durable goods merchant wholesalers | | 4241 | Paper and paper products merchant wholesalers | | 4243 | Apparel, piece goods, and notions merchant wholesalers | | 4244 | Grocery and related products merchant wholesalers | | 4245 | Farm product raw material merchant wholesalers | | 42491 | Farm supplies merchant wholesalers | | 42492 | Book, periodical, and newspaper merchant wholesalers | | 42493 | Flower, nursery stock, and florists' supplies merchant wholesalers | | 42495 | Paint, varnish, and supplies merchant wholesalers | | 42499 | Other miscellaneous nondurable goods merchant wholesalers | | 42511 | Business-to-business electronic markets | | 42512 | Wholesale trade agents and brokers | | 44121 | Recreational vehicle dealers | | 4412A | Mobile home dealers | | 4412B | Utility trailer dealers | | 441222 | Boat dealers | | 441228 | Motorcycle, ATV, and all other motor vehicle dealers | | 442A | Furniture stores | | 442B | Home furnishings stores | | 443141 | Household appliance stores | | 443142 | Electronics stores | | 4431A | Computer software stores | | 4431B | Telecommunication Equipment and Telephone Stores | | 44411 | Home centers | | 44412 | Paint and wallpaper stores | | 44413 | Hardware stores | | 44419 | Other building material stores | | 4451 | Grocery stores, Supermarkets | | 4452 | Specialty food stores | | 311811 | Bakeries | | 44612 | Cosmetics, beauty supplies, and perfume stores | | 44613 | Optical goods store | | 446199 | All other health and personal care stores | | 447 | Gasoline stations | | 44811 | Men's clothing stores | | 44812 | Women's clothing stores | | 4481A | Men's and Women's clothing stores | | 44813 | Children's and Infants' clothing stores | | 44814 | Family clothing stores | | 4481B | Sports and riding apparel stores | | 44819 | Other Clothing (accessories) stores | | 4482 | Shoe stores | | 44832 | Luggage and leather goods stores | | 45111 | Sporting goods stores | | 45112 | Hobby, toy, and game stores | | 45113 | Sewing, needlework, and piece Goods stores | | 45114 | Musical instrument and supplies stores | | 4512 | Book stores and news dealers | | 4522 | Department stores | | 4523 | General merchandise stores, including warehouse clubs and supercenters | | 4531 | Florists | | 45321 | Office supplies and stationery stores | | 45322 | Gift, novelty, and souvenir stores | | 4533 | Used merchandise stores | | 45391 | Pet and Pet Supplies stores | | 45393 | Manufactured (mobile) home dealers | | 4539H | Discount stores | | 4539I | Duty-free stores | | 4539J | Second hand stores | | 4539K | Antique stores | | 453998 | All other miscellaneous store retailers | | 4542A | Vending machines (Food) | | 4542B | Vending machines (Non-Food) | | 481B | Other air transportation | | 482A | Passenger rail transportation | | 482B | Freight rail transportation | | 483B | Ferries | | 483C | Water Freight | | 484 | Truck transportation | | 4851 | Urban transit systems | | 4852 | Interurban and rural bus transportation | | 4853 | Taxi and limousine service | | 4854 | School and employee bus transportation | | 4855 | Charter bus industry | | 4859 | Other transit and ground passenger transportation | | 4881A | Airports, airport terminals, flying fields | | 48819 | Other support activities for air transportation | | 4882 | Support activities for rail transportation | | 4883 | Support Activities for water Transportation | | 48841 | Motor vehicle towing | | 4884A | Bridge and road fees, tolls | | 4884B | Electric vehicle charging | | 48849 | Other support activities for road transportation | | 4889 | Other support activities for transportation | | 491 | Postal service | | 492 | Couriers and messengers | | 493 | Warehousing and storage | | 5111 | Newspaper, periodical, book, and directory publishers (except internet) | | 5112A | Digital goods - audiovisual media including books, movies, and music | | 5112B | Digital goods - games | | 51121 | Digital goods - software applications | | 51211 | Motion picture and video production | | 51212 | Motion picture and video distribution | | 51213 | Motion picture and video exhibition | | 5122 | Sound recording industries | | 515 | Broadcasting (except internet) | | 517311 | Wired and Wireless Telecommunications Carriers | | 51731B | Wireless telecommunications carriers - Prepaid | | 51731D | Other wireless telecommunications carriers | | 5179 | Other telecommunications | | 517911 | Telecommunications Resellers | | 51911 | News Agency | | 51913 | Internet publishing and broadcasting and web search portals | | 5191A | All other information services | | 53211 | Passenger car rental and leasing | | 53212 | Truck, and utility trailer rental and leasing | | 5321B | Motor home and recreational vehicle rental | | 53221 | Consumer electronics and appliances rental | | 532281 | Formal wear and costume rental | | 532282 | Video tape and disc rental | | 532283 | Home health equipment rental | | 532284 | Recreational goods rental | | 532289 | All other consumer goods rental | | 5324 | Commercial, industrial machinery and equipment rental and leasing | | 5411A | Lawyers (except bankruptcy) | | 541211 | Offices of certified public accountants | | 541213 | Tax preparation services | | 5413 | Architectural, engineering, and related services | | 5414 | Specialized design services | | 5415 | Computer systems design and related services | | 5416 | Management, scientific, and technical consulting services | | 54171 | Research and development in the Physical, Engineering, and Life Sciences | | 5417B | Other research and development in the Social Sciences and Humanities | | 5418 | Advertising, public relations, and related services | | 54192 | Photographic services | | 54194 | Veterinary services | | 54199 | All other professional, scientific, and technical services | | 55 | Management of companies and enterprises | | 5611 | Office administrative services | | 5612 | Facilities support services | | 5613 | Employment services | | 56141 | Document preparation services | | 56142 | Telephone call centers | | 56143 | Business service centers | | 56149 | Other business support services | | 5616A | Security services | | 56171 | Exterminating and pest control services | | 56172 | Janitorial services | | 56173 | Landscaping services | | 56174 | Carpet and upholstery cleaning services | | 56179 | Other services to buildings and dwellings | | 5619 | Other support services | | 562 | Waste management and remediation services | | 6111 | Elementary and secondary schools | | 6112 | Junior colleges | | 6113 | Colleges, universities, and professional schools | | 6114 | Business schools, and computer and management training | | 6115 | Technical and trade schools | | 6116A | Dance Schools | | 61161 | Fine arts schools | | 61162 | Sports and recreation instruction | | 61163 | Language schools | | 61169 | All other schools and instruction | | 6214 | Outpatient care centers | | 6219 | Other ambulatory health care services | | 6241 | Individual and family services | | 6242 | Community food and housing, and emergency and other relief services | | 6243 | Vocational rehabilitation services | | 6244 | Child day care services | | 624A | All other social services | | 7111 | Performing arts companies | | 7112 | Spectator sports | | 7113 | Promoters of performing arts, sports, and similar events | | 7114 | Agents and managers for artists, athletes, entertainers, and other public figures | | 7115 | Independent artists, writers, and performers | | 712 | Museums, historical sites, and similar institutions | | 71311 | Amusement and theme parks | | 71312 | Amusement arcades | | 7139A | Public golf courses | | 7139B | Private golf courses and country clubs | | 71392 | Skiing facilities | | 71393 | Marinas | | 71394 | Fitness and recreational sports centers | | 71395 | Bowling centers | | 7139C | All other amusement and recreation industries | | 7139D | Billiard and pool establishments | | 7139E | Aquariums, seaquariums, dolphinariums, and zoos | | 72111 | Hotels (except casino hotels) and motels | | 7211B | Other traveler accommodation | | 7212 | Recreational vehicle parks and recreational camps | | 7213 | Rooming and boarding houses, dormitories, and workers' Camps | | 7223 | Special food services | | 722511 | Full-service restaurants | | 722513 | Limited-service restaurants (Fast food restaurants) | | 722514 | Cafeterias, grill buffets, and buffets | | 722515 | Snacks and nonalcoholic beverage bars | | 8111 | Automotive repair and maintenance | | 8112 | Electronic and precision equipment repair and maintenance (including computers) | | 8113 | Commercial and industrial machinery and equipment (except automotive and electronic) repair and maintenance | | 8114 | Personal and household goods repair and maintenance | | 81211 | Hair, nail, and skin care services | | 8121A | Massage parlors | | 8121B | Health and beauty spas | | 8122 | Death care services | | 8123 | Drycleaning and Laundry services | | 8129E | Other personal services | | 8134 | Civic and social organizations | | 81391 | Business associations | | 81392 | Professional organizations | | 81393 | Labor unions and similar labor organizations | | 81399 | Other similar organizations (except business, professional, labor, and political organizations) | []()3Only for Issuing and Business Accounts. ## Source of funds list Only applicable for [business accounts](/business-accounts/) and [card issuing](/issuing). Adyen is required to verify the source of funds (SOF) used to fund an account. This requirement is applicable for both [card issuing](/issuing) and [business accounts](/business-accounts/). Depending on the type of funds, we may request additional documents as proof. We strongly recommend that you have these documents available before starting in order to speed up this process. To submit this information to Adyen, make a POST [/businessLines](https://docs.adyen.com/api-explorer/legalentity/4/post/businessLines) request, specifying the `service` as either: * **banking** for business accounts * **issuing** for card issuing If the source of funds was processed through Adyen, set the `sourceOfFunds.adyenProcessedFunds` to **true**. If the source of funds was not processed through Adyen, set the `sourceOfFunds.adyenProcessedFunds` to **false**. You must then include the `sourceOfFunds.type` and `sourceOfFunds.description`. The description must state the origin of the source of funds. The following table shows the accepted funding sources and the required documents for each type, if requested. If the type of accepted document has a listed date requirement, the document must meet this requirement. | Type of Source of Funds | `businessLines.sourceOfFunds.type` API value | Documents must show | Examples of accepted documents | | ----------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Business earnings processed through Adyen | Set `businessLines.adyenProcessedFunds` to **true** | N/A | No supporting document is required | | Previous business earnings | **business** | * Name of company * Amounts earned * Description of business activity | - Latest accounts (issued within the last financial year) - Annual Statements (within 12 months) - Latest tax filing (issued within the last year) - Letter from accountant (signed and dated within 12 months) - Recent Invoices (last 3 months) | | (Previous) employment | **employment** | * Your business name * Date document was issued * Bank logo/name (for bank statement) * Employer’s name (for payslips) | - Last 3 months of bank statements - Last 3 months of payslips | | Cryptocurrency | **cryptocurrencyIncome** | * Your business name * Date document was issued (no older than 12 months) * Name of Crypto-exchange * Name of coin | - Proof of ownership of wallet - Statement of transaction history (showing crypto) - Latest tax report (showing crypto) (no older than 12 months) | | Investments (dividends) | **dividendIncome** | * Your business name * The date your business received the money * The amount received * The type of investments * Names of the parties involved | - Contract specifying dividends - Latest tax returns of the company (no older than 12 months) - Investment certificate - Broker statement (issued within 3 months) | | Loans | **loans** | * Your business name * Amount you borrowed * The date you received the money * Name of the lender * Address of the lender * Purpose of the loan | - Loan agreement - Loan statement (no older than 12 months) | | Subsidies / Grants | **financialAid** | * Amount of Subsidy / Grant * Providers(s) of Subsidy / Grant * Time Period | - Confirmation of Subsidy / Grant - Subsidy Receipt | | Third Party Funding (capital investments) | **thirdPartyFunding** | * Your business name * The date your business received the money * The amount received * Names of the parties involved * Addresses of the parties involved * Signatures of the parties involved * Payment purpose | - Investor contracts - Investor memoranda - Notarized statements (no older than 12 months) - Partnership agreement | | Property Sale | **assetSale** | * Date money was received * Amount you received * Address (if applicable) * Description of property | - Proof of ownership (notarized) - Signed letter from the solicitor / estate agent (no older than 12 months) - Copy of contract of sale - Tax declaration (no older than 12 months) - Title deed (notarized) | | Rental Income | **rentalIncome** | * Amount received * Address * Name of parties to the agreement | - Rental Agreement - Proof of Ownership | | Donations / Gifts | **donations** | * Amount received * Date of transfer * Full name of donor | - Original or certified copy of grant | | Royalty Income | **royaltyIncome** | * Description of (intellectual) property * Amount received | - Royalty agreement - Tax declaration (no older than 12 months) | | Gambling / Lottery | **gamblingWinnings** | * Amount won * Date of winning * Location / Site | - Proof of Winnings - Win Report - Win/Loss Statement (issued within 3 months) - Tax declaration that shows winnings (issued within 12 months) | | Inheritance | **inheritance** | * Name of person who made the will * Amount received / Value of estate * Date received * Name of benefactor | - Certificate of inheritance - A grant of probate - Letter from solicitor / notary (no older than 12 months) - Signed copy of the will | | Pension | **pensionIncome** | * Amount to be received * Legal Name of recipient | - Pension slip (no older than 12 months) - Letter from previous employer - Pension statement form (no older than 12 months) | | Insurance / Settlement | **insuranceSettlement** | * Amount of settlement * Legal name of recipient * Date received | - Court order - Letter from lawyer / solicitor - Letter from insurer | --- # Source: https://docs.adyen.com/business-accounts/verify-account-holder.md Section: Business accounts Title: Bank account verification with open banking Description: Quickly verify unregistered third-party individuals using the Adyen open banking gateway. --- title: "Bank account verification with open banking" description: "Quickly verify unregistered third-party individuals using the Adyen open banking gateway." url: "https://docs.adyen.com/business-accounts/verify-account-holder" source_url: "https://docs.adyen.com/business-accounts/verify-account-holder.md" canonical: "https://docs.adyen.com/business-accounts/verify-account-holder" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Bank account verification with open banking Quickly verify unregistered third-party individuals using the Adyen open banking gateway. [View source](/business-accounts/verify-account-holder.md) Adyen's verification through bank report service uses Adyen's open banking gateway to retrieve bank account verification reports from third-party banks. For example, you consider hiring an unregistered third-party individual on a contract-basis for services, such as food-delivery or as a courier. You want to make sure the person is who they say they are *before* you enter into an agreement with them for their services. You can verify them through Account Information Service Providers (AISPs) such as Plaid or Tink. The third-party individual can authorize their bank to share a bank account verification report with you, which provides bank account ownership verification and Know Your Customer (KYC) verification quickly and securely. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | This feature is supported with an [Adyen for Platforms](/platforms), [Marketplaces](/marketplaces), or a [Classic integration](/point-of-sale/classic-library-deprecation). | | **API credentials** | You must have an [API key](/development-resources/api-credentials/#generate-api-key) (recommended) or [basic authentication username and password](/development-resources/api-credentials/#basic-authentication) to access this API. Ensure that you have asked your Adyen contact to assign the following role to your API credential:- **Role for OpenBanking account verification use case: EXTERNAL** | | **Setup steps** | Before you begin, you have the option to customize the open banking widget. If you choose to, provide Adyen the necessary information to customize and display your company name and logo within the widget when the flow transitions to the Adyen's open banking gateway:Information Required? Shown to third-party individual Company name Yes No Logo No, but recommended Yes Application name Yes Yes Legal entity name Yes No Website Yes No Address Yes No | ## How it works When you want to verify a third-party individual's bank account ownership through a redirect, use the following flow. 1. Make a request to the [/routes](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes) generation endpoint to get a list of available account verification routes. Each route represents a possible connection path between the third-party individual and their bank. When the third-party individual successfully connects through one of these routes, you will receive a report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code). Use the [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) to: * Request a bank account verification report. * Verify the third-party individual's identity using the information in the bank account verification report. The [/routes](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes) generation endpoint dynamically compiles and returns a list of the most suitable AISPs available for account verification. The list is based on the location of the bank where the third-party individual (the external account holder) is registered. Note, the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) you provide is used to receive the report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code), but it does not influence route selection. A report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) is not guaranteed for every route. The third-party individual must successfully complete the bank connection flow for a [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) to be generated. 2. Redirect the third-party individual to the AISP's bank selection and authentication/authorization flow. After the third-party individual completes the authentication flow and authorizes their bank to generate and share a report, the merchant receives a report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) (or error details). This report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) or error details will be provided in the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) the merchant specified in the routes generation request. 3. Use the report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) to make a request to the [/reports/{code}](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)) endpoint. This request retrieves a bank account verification report containing information about the third-party individual and account number (ACH, BSB, EFT, IBAN) the third-party individual has agreed to share with the merchant. [![Sequence diagram for account verification using Adyen's Open Banking auth flow](/user/pages/reuse/pfs-open-banking/account-holder-report/account-verification-sequence.svg)](/user/pages/reuse/pfs-open-banking/account-holder-report/account-verification-sequence.svg) ## Generate a list of routes To get a list of available account verification routes. 1. Make a POST [/routes](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes) request with the following parameters in the request body. The request header includes, your `ADYEN-API-KEY` and `application/json` specifying the format of the request body: | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [country](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-country) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The location where the third-party individual's bank account is registered. Adyen uses this information to determine the best provider for the given location, and to configure the open banking flow for that respective location. | | [locale](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-locale) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The language to configure for the verification flow user interface. This information is used to configure the open banking flow with the same language for a consistent user experience. | | [state](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-state) | | This is an optional value to identify the request in callback handling. You can generate this value on a per-session basis to protect the callback against Cross-Site Request Forgery (CSRF) attacks. This value must be composed of characters that can be successfully URL-encoded. Note, this value will be stored in external systems, so make sure that you avoid exposing any sensitive information in a plain-text format. | | [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The URL where Adyen should redirect the third-party individual when the open banking flow finishes. Adyen's open banking gateway returns a report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) as a parameter in the URL response. You can use this [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) when making a request to the [/reports/{code}](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)) endpoint to get the bank account verification report for the third-party individual. | **Request: Get a list of AISP routes** ```bash curl https://obgateway-test.adyen.com/obgateway/v1/accountVerification/routes \ -H 'x-api-key: ADYEN-API-KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "country": "NL", "locale": "en-US", "state": "123A-456B-789C-10D", "redirectUrl": "https://merchanturl.example.org/redirect/url" }' ``` 2. The response contains the details about the [provider](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#responses-200-routes-provider) that the third-party individual will be redirected to during the flow, and the [link](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#responses-200-routes-link) to begin the open banking flow. | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [provider](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#responses-200-routes-provider) | Metadata about the selected provider, including the name and company logo. You can use this information to inform the third-party individual about the provider they will be redirected to when they select the link. | | [link](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#responses-200-routes-link) | The redirection link. You can use this link to redirect the third-party individual to the open banking flow when it is selected. | **Response: List of available routes sorted by priority.** ```bash { "routes": [ { "provider": { "name": "Tink", "logoURL": "https://obgateway.adyen.com/obgateway/static/provider/images/tink-logo.svg" }, "link": "https://obgateway.adyen.com/obgateway/provider/outgoing/tink/redirect/13ec4802-c987-4f8c-8909-9a75ff567256" } ] } ``` ## Redirect and handle the result The Adyen open banking gateway handles the outgoing and incoming communications with the AISP. When the third-party individual opens the route link, the gateway redirects them to the external financial institution for account verification. After the verification flow at the external financial institution is complete, the gateway redirects the third-party individual from the financial institution back to the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) provided in the [generate list of routes](#generate-a-list-of-routes) step. For successful callbacks, the gateway adds a report [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) to the query parameters. Use this [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) to download a bank account verification report from the [/reports/{code}](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)) endpoint in the [view the bank account verification report](#view-the-bank-account-verification-report) step. In cases where there are errors, the third-party individual is redirected to the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) with the error information in the query parameters. 1. View the response of the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) and check if there was a successful redirection callback. A successful redirection callback may look like this: **Successful redirection callback** ```bash https://merchanturl.example.org/redirect/url?code=e30248de-fc54-45e8-8e80-b3dcfe717e8c&state=123A-456B-789C-10D&type=success&signature=eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6Im9iZ2F0ZXdheS5zaWduaW5nLjEifQ.eyJleHAiOjE3NTMyNjc0NzksInR5cGUiOiJzdWNjZXNzIiwic3RhdGUiOiJ1c2VySWQ6MTIzIiwidXJsIjoiaHR0cHM6Ly9kaXNwbGF5LXBhcmFtZXRlcnMuY29tIiwiY29kZSI6Ik9CQ080MkM4UTIyMzIyNzY1TVZHODZaQjdRNVA0RCJ9.p5CXtewNS43HazYmF4S6063bi4P__f8Noddbwfh3Ud5sNJktrSpV0ZramxUbNy6LjwakMF4gG6TMC0EmBtQGW9P7vQgThNRcAtvH-cynrCXE2hR3M7yuEwKwb3eg0ySM ``` 2. The response contains the details about the `type` indicating **success** or **error**, the [state](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-state) , a `signature`, and a [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code). Use this [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code)to download a bank account verification report from the [/reports/{code}](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)) endpoint in the [view the bank account verification report](#view-the-bank-account-verification-report) step. | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) | The report `code` that can be used to download the verification report in the gateway `/reports/{code}` endpoint. | | [state](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-state) | The state provided in the [generate a list of routes](#generate-a-list-of-routes) step. | | `type` | The event type, **success** in the case of a successful callback or **error**, if the callback fails. | | `signature` | A JSON Web Signature (JWS) that signs the contents of the redirect URL, ensuring the integrity and authenticity of the data. | If you encounter a redirection error callback, it may look like this: **Unsuccessful redirection callback** ```bash https://merchanturl.example.org/redirect/url?type=error&error_code=USER_CANCELED&error_message=The%20user%20canceled%20the%20authorization%20process&state=123A-456B-789C-10D&signature=eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6Im9iZ2F0ZXdheS5zaWduaW5nLjEifQ.eyJleHAiOjE3NTMyNjc0NzksInR5cGUiOiJzdWNjZXNzIiwic3RhdGUiOiJ1c2VySWQ6MTIzIiwidXJsIjoiaHR0cHM6Ly9kaXNwbGF5LXBhcmFtZXRlcnMuY29tIiwiY29kZSI6Ik9CQ080MkM4UTIyMzIyNzY1TVZHODZaQjdRNVA0RCJ9.p5CXtewNS43HazYmF4S6063bi4P__f8Noddbwfh3Ud5sNJktrSpV0ZramxUbNy6LjwakMF4gG6TMC0EmBtQGW9P7vQgThNRcAtvH-cynrCXE2hR3M7yuEwKwb3eg0ySM ``` The response contains the details about the `type` indicating **success** or **error**, the `error_code` and `error_message` associated with the failed redirection request callback, [state](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-state), and a `signature`. | Parameter | Description | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `error_code` | The error code associated with the failed redirection request callback. | | `error_message` | The error message associated with the failed redirection request callback. | | [state](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-state) | The state provided in the [generate a list of routes](#generate-a-list-of-routes) step. | | `type` | The event type, **success** in the case of a successful callback or **error**, if the callback fails. | | `signature` | A JSON Web Signature (JWS) that signs the contents of the redirect URL, ensuring the integrity and authenticity of the data. | ### Error codes and messages Here's a list of error codes and corresponding error messages you can receive from Adyen's open banking gateway. Depending on the context of the error code and message, you choose how to handle the error and present options to your third-party individual. | `error_code` | `error_message` | | ------------------------- | ------------------------------------------------------------------ | | `USER_CANCELED` | The third-party individual canceled the authorization process. | | `CONNECTION_ERROR` | An error occurred during the authentication process with the bank. | | `PROVIDER_INTERNAL_ERROR` | The provider has responded with an internal error. | | `PROVIDER_UNKNOWN_ERROR` | The provider has responded with an unknown error. | ## View the bank account verification report To download the bank account verification report for a third-party individual. 1. Make a GET [/reports/{code}](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)) request, where [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) is a unique identifier for a specific bank account verification report. This is the [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) you received as a result of a [successful callback](#redirect-and-handle-the-result) to the open banking flow: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [code](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#path-code) you receive after a successful open banking flow that is included as a query parameter in the [redirectUrl](https://docs.adyen.com/api-explorer/open-banking/latest/post/accountVerification/routes#request-redirectUrl) callback. | **Request: Retrieve the bank account verification report for a third-party individual** ```bash curl https://obgateway-test.adyen.com/obgateway/v1/accountVerification/reports/e30248de-fc54-45e8-8e80-b3dcfe717e8c \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` 2. Confirm that the `x-state` header matches the state provided in the [generate a list of routes](#generate-a-list-of-routes) request. **Response header** ```json "x-state: 123A-456B-789C-10D" ``` 3. The response returns the report resource, identified by its unique [id](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#responses-200-id). You also receive the `country` where the report was generated, and the `accounts` that were verified through the open banking authorization flow. | Parameter | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#responses-200-id) | The unique identifier of the report. | | [country](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#responses-200-country) | The location where the report was generated. | | [accounts](https://docs.adyen.com/api-explorer/open-banking/latest/get/accountVerification/reports/\(code\)#responses-200-accounts) | The list of verified accounts for the third-party individual. The accounts array allows for use-cases where more than one account can be verified. When a single account selection is permitted, the list will return that account. | ### Tab: Response with IBAN account ```json { "id": "69ee9452ef824fe092f1417f37535755", "country": "ES", "accounts": [ { "accountId": "ed5080e4f485430290475d246534c8fd", "accountType": "CURRENT", "accountName": "Checking Account 1", "accountNumber": "ES1376230223254275408743", "currency": "EUR", "identifiers": { "iban": { "iban": "ES1376230223254275408743", "bban": "76230223254275408743" } }, "parties": [ { "identity": { "fullLegalName": "Alberta Bobbeth Charleson", "name": "Alberta Bobbeth Charleson" }, "role": "HOLDER" } ], "bankName": "Tink Demo Bank" } ] } ``` ### Tab: Response with ACH accounts ```json { "id": "nJwJE68h6vlSEnk", "country": "US", "accounts": [ { "accountId": "XvNzLGMpl3fBevllWEwks3jvBvPy88sbkypkP", "accountType": "CURRENT", "accountName": "Plaid Gold Standard 0% Interest Checking", "accountNumber": "1111222233330000", "currency": "USD", "identifiers": { "ach": { "accountNumber": "1111222233330000", "routingNumber": "011401533" } }, "parties": [ { "identity": { "fullLegalName": "Jane Doe", "name": "Jane Doe" }, "role": "HOLDER" } ], "bankName": "Wells Fargo" }, { "accountId": "XvNzLGMpl3fBevllWEwks3jvBvPy88sbkypkP", "accountType": "CURRENT", "accountName": "Plaid Gold Standard 0% Interest Checking", "accountNumber": "3333222211110000", "currency": "USD", "identifiers": { "ach": { "accountNumber": "3333222211110000", "routingNumber": "033587521" } }, "parties": [ { "identity": { "fullLegalName": "Jane Doe", "name": "Jane Doe" }, "role": "HOLDER" } ], "bankName": "Bank of America" } ] } ``` ### Tab: Response with ETF account ```json { "id": "69ee9452ef824fe092f1417f37535755", "country": "CA", "accounts": [ { "accountId": "th7681t6j876930300478t246534j8fi", "accountType": "CURRENT", "accountName": "Checking Account 1", "accountNumber": "111122220000", "currency": "CAD", "identifiers": { "eft": { "accountNumber": "111122220000", "branch": "01533", "institution": "114" } }, "parties": [ { "identity": { "fullLegalName": "Jessie Dean", "name": "Jessie Dean" }, "role": "HOLDER" } ], "bankName": "Plaid Demo Bank" } ] } ``` ### Tab: Response with BSB account ```json { "id": "lkumovjdFQFy6JhbSaWTa8sCH79fzJJnFMKpkSST09ism2lCMlsnSEsrjx6XNr4u_kxhSg==", "country": "AU", "accounts": [ { "accountId": "lkumovjdFQFy6JhbSaWTa8sCH79fzJJnFMKpkSST09ism2lCMlsnSEsrjx6XNr4u_kxhSg==", "accountType": "UNKNOWN", "accountName": "Savings Account", "accountNumber": "37458052", "currency": "AUD", "identifiers": { "bsb": { "accountNumber": "37458052", "bsbCode": "413574" } }, "parties": [ { "identity": { "fullLegalName": "Peter Sherman", "name": "Peter" }, "role": "HOLDER" } ], "bankName": "Banking Sandbox Data Holder" } ] } ``` ## See also * [Open banking](/business-accounts/) --- # Source: https://docs.adyen.com/business-accounts/view-transfers-details.md Section: Business accounts Title: View transfer details for your business account Description: View information about your transfers involving third parties. --- title: "View transfer details for your business account" description: "View information about your transfers involving third parties." url: "https://docs.adyen.com/business-accounts/view-transfers-details" source_url: "https://docs.adyen.com/business-accounts/view-transfers-details.md" canonical: "https://docs.adyen.com/business-accounts/view-transfers-details" last_modified: "2019-12-06T14:44:00+01:00" language: "en" --- # View transfer details for your business account View information about your transfers involving third parties. [View source](/business-accounts/view-transfers-details.md) ##### Best practice: Webhooks Track transfers by listening to [webhooks](/business-accounts/third-party-transfer-webhooks). This page explains how to view transfer details using your [Customer Area](https://ca-test.adyen.com/) and the API. In your balance platform, transfers represent funds that are credited or debited from a balance account. Before any money movement occurs, transfers must be: 1. **Initiated** by events such as [sending](/business-accounts/send-funds) or [receiving](/business-accounts/receive-funds) funds from third-party accounts. 2. **Authorized** by Adyen. 3. **Booked** in your business account. You can track the status and details of transfers to support your business operations. For recurring operations, such as reconciling fund transfers, we recommend that you listen to [webhooks](/business-accounts/third-party-transfer-webhooks). In other cases, you can view transfer details by using the **Transfers** page in your [Customer Area](https://ca-test.adyen.com/) or by making a GET [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers) request. ## Requirements Before you begin, take into account the following requirements | Requirement | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the following role:- **TransferService Webservice Retrieve role** | | **[Customer Area roles](/account/user-roles)** | Make sure that you have the following role:- **Balance platform base role** | ## View a list of transfers You can view the list of transfers in your balance platform by using your [Customer Area](https://ca-test.adyen.com/) or by making a GET [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers) request. ### Tab: Customer Area To view a list of transfers in your [Customer Area](https://ca-test.adyen.com/): 1. Go to **Transactions** > **Transfers**. 2. Use the **Balance platform** filter to find the accounts you need. You can only see results from one **Balance platform** at a time. With filters, you can tailor the list of transfers based on the date, status, or reference numbers. This helps to highlight transfers with refusal problems. ### Tab: Transfers API To get a list of transfers, make a GET [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers) request including the query parameters in the following table: | Query parameter | Required | Description | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [createdSince](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#query-createdSince) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies that the response must include transfers created **after** this date. This date must be less than 6 months from the `createdUntil` date. The date must be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. For example: `2026-05-12T15:00:00+01:00`. | | | [createdUntil](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#query-createdUntil) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies that the response must include transfers created **before** this date. This date must not be greater than 6 months from the `createdSince` date. The date must also be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. For example: `2026-05-13T15:00:00+01:00`. | | | [balanceAccountId](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#query-balanceAccountId) | | Limits the returned list to the transfers related to the specified balance account ID. | | | [accountHolderId](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#query-accountHolderId) | | Limits the returned list to the transfers related to the specified account holder ID. | | | [limit](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#query-limit) | | The number of transfers returned per page. | | You must provide at least one of the unique identifiers in your request. The following example shows a GET [/transfers](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers) request for a list that includes: * Transfers created after **May 12, 2025 at 3:00 PM**, but before **May 13, 2026 at 3:00 PM**. * A limit of **5** transfers per page. **Example GET /transfers request** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers?createdSince=2026-05-12T15:00:00Z&createdUntil=2026-05-13T15:00:00Z&limit=5 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request TransfersApi service = new TransfersApi(client); FindTransfersResponse response = service.getAllTransfers("String", "String", "String", "String", "String", "String", LocalDateTime.parse("2026-05-12T15:00:00");, LocalDateTime.parse("2026-05-13T15:00:00");, "String", 1, null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); $requestOptions['queryParams'] = array('balancePlatform' => 'string', 'accountHolderId' => 'string', 'balanceAccountId' => 'string', 'paymentInstrumentId' => 'string', 'reference' => 'string', 'category' => 'string', 'createdSince' => 'date-time', 'createdUntil' => 'date-time', 'cursor' => 'string', 'limit' => 'integer'); // Send the request $service = new TransfersApi($client); $response = $service->getAllTransfers($requestOptions); ``` #### C\# ```cs // Adyen .net API Library v27.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TransfersService(client); var response = service.GetAllTransfers(balancePlatform: "string", accountHolderId: "string", balanceAccountId: "string", paymentInstrumentId: "string", reference: "string", category: "string", createdSince: DateTime.Parse("2026-05-12T15:00:00"), createdUntil: DateTime.Parse("2026-05-13T15:00:00"), cursor: "string", limit: 1); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.getAllTransfers("string", "string", "string", "string", "string", "string", Date.now(), Date.now(), "string", 1); ``` #### Go ```go // Adyen Go API Library v16.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v16/src/common" "github.com/adyen/adyen-go-api-library/v16/src/adyen" "github.com/adyen/adyen-go-api-library/v16/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Transfers() req := service.TransfersApi.GetAllTransfersInput() req = req.BalancePlatform("string").AccountHolderId("string").BalanceAccountId("string").PaymentInstrumentId("string").Reference("string").Category("string").CreatedSince(DateTime.Parse("2026-05-12T15:00:00")).CreatedUntil(DateTime.Parse("2026-05-13T15:00:00")).Cursor("string").Limit(1) res, httpRes, err := service.TransfersApi.GetAllTransfers(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. query_parameters = { "balancePlatform" : "string", "accountHolderId" : "string", "balanceAccountId" : "string", "paymentInstrumentId" : "string", "reference" : "string", "category" : "string", "createdSince" : "date-time", "createdUntil" : "date-time", "cursor" : "string", "limit" : "integer" } # Send the request result = adyen.transfers.transfers_api.get_all_transfers(query_parameters=query_parameters) ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) query_params = { :balancePlatform => 'string', :accountHolderId => 'string', :balanceAccountId => 'string', :paymentInstrumentId => 'string', :reference => 'string', :category => 'string', :createdSince => 'date-time', :createdUntil => 'date-time', :cursor => 'string', :limit => 'integer' } # Send the request result = adyen.transfers.transfers_api.get_all_transfers(query_params: query_params) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.getAllTransfers("string", "string", "string", "string", "string", "string", Date.now(), Date.now(), "string", 1); ``` The response contains the following parameters: | Response parameter | Description | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [data](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#responses-200-data) | An array that contains all the transfers that match the query parameters. | | [\_links](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers#responses-200-_links) | An object that contains links to the next or previous page, when applicable. | **Example GET /transfers response** ```json { "data": [ { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-10-12T15:43:28+02:00", "id": "3JNC3P60KGBMOGA0", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "EUR", "value": 110 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001" }, "category": "bank", "categoryData": { "priority": "regular", "type": "bank" }, "counterparty": { "bankAccount": { "accountHolder": { "address": { "city": "Amsterdam", "country": "NL", "postalCode": "1011DJ", "stateOrProvince": "NH", "line1": "Simon Carmiggeltstraat 6-50" }, "fullName": "S. Hopper" }, "accountIdentification": { "type": "iban", "iban": "NL45INGB0000000001" } } }, "description": "Your description of the transfer", "direction": "outgoing", "paymentInstrument": { "id": "PI00000000000000000000001" }, "reason": "counterpartyAccountNotFound", "reference": "Your internal reference for the transfer", "referenceForBeneficiary": "Your-reference-sent-to-the-beneficiary", "status": "booked", "balances": [ { "balance": 110, "currency": "EUR", "received": 0, "reserved": 0 } ], "events": [ { "bookingDate": "2023-10-12T15:43:36+02:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -110 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-10-12T15:43:36+02:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 110, "reserved": -110 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-10-12T15:43:37+02:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -110, "currency": "EUR", "received": 0, "reserved": 110 } ], "status": "booked", "transactionId": "EVJN00000000000000000000000003EUR", "type": "accounting", "valueDate": "2023-10-12T15:43:28+02:00" }, { "estimatedArrivalTime": "2023-10-13T18:00:00+02:00", "id": "EVTR00000000000000000000000001", "type": "tracking", "updateDate": "2023-10-12T15:43:39+02:00" } ], "sequenceNumber": 4, "tracking": { "estimatedArrivalTime": "2023-10-13T18:00:00+02:00", "type": "estimation" }, "transactionRulesResult": { "allHardBlockRulesPassed": true }, "type": "bankTransfer" }, { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-10-13T08:29:05+02:00", "id": "48NJID60KRHQ8VNK", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001" }, "amount": { "currency": "USD", "value": 3 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001" }, "category": "internal", "counterparty": { "balanceAccountId": "BA00000000000000000000002" }, "description": "Your description of the transfer", "direction": "outgoing", "reason": "approved", "reference": "Your internal reference for the transfer", "referenceForBeneficiary": "reference_for_beneficiary", "status": "booked", "balances": [ { "balance": -3, "currency": "USD", "received": 0, "reserved": 0 } ], "events": [ { "bookingDate": "2023-10-13T10:29:15+02:00", "id": "EVJN00000000000000000000000004", "mutations": [ { "currency": "USD", "received": -3 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-10-13T10:29:15+02:00", "id": "EVJN00000000000000000000000005", "mutations": [ { "currency": "USD", "received": 3, "reserved": -3 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-10-13T10:29:15+02:00", "id": "EVJN00000000000000000000000006", "mutations": [ { "balance": -3, "currency": "USD", "received": 0, "reserved": 3 } ], "status": "booked", "transactionId": "EVJN00000000000000000000000006USD", "type": "accounting", "valueDate": "2023-10-13T10:29:05+02:00" } ], "sequenceNumber": 3, "type": "internalTransfer" } ], "_links": {} } ``` ## View a specific transfer The following tabs explain how to find a specific transfer using your [Customer Area](https://ca-test.adyen.com/) or our [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview). ### Tab: Customer Area You can search for a transfer by its ID or description. You can limit the scope of search results by applying filters before searching. To search for a transfer: 1. Go to **Transactions** > **Transfers**. 2. Select **Search**. 3. On the dropdown menu, select **Transfers**. 4. In the text field, enter information such as the **Transfer ID** or **Description**. The search window now shows only the corresponding transfers. You can also see the transfer details listed in a separate **Transfers details** page. To open this page, select a **Transfer ID**. ### Tab: Transfers API To get the details of a specific transfer, make a GET [/transfers/{id}](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)) request, specifying the transfer [id](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#path-id) in the path. **Example GET /transfers/{id} request** #### curl ```bash curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/3JNC4O615TH2D8JY \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.transfers.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.transfers.*; Client client = new Client("ADYEN_BALANCE_PLATFORM_API_KEY", Environment.TEST); // Send the request TransfersApi service = new TransfersApi(client); TransferData response = service.getTransfer("id", null); ``` #### PHP ```php setXApiKey("ADYEN_BALANCE_PLATFORM_API_KEY"); $client->setEnvironment(Environment::TEST); // Send the request $service = new TransfersApi($client); $response = $service->getTransfer('id'); ``` #### C\# ```cs // Adyen .net API Library v27.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Transfers; using Adyen.Service.Transfers; var config = new Config() { XApiKey = "ADYEN_BALANCE_PLATFORM_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TransfersService(client); var response = service.GetTransfer("id"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, TransfersAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.getTransfer("id"); ``` #### Go ```go // Adyen Go API Library v16.3.0 import ( "context" "github.com/adyen/adyen-go-api-library/v16/src/common" "github.com/adyen/adyen-go-api-library/v16/src/adyen" "github.com/adyen/adyen-go-api-library/v16/src/transfers" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.Transfers() req := service.TransfersApi.GetTransferInput("id") res, httpRes, err := service.TransfersApi.GetTransfer(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_BALANCE_PLATFORM_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Send the request result = adyen.transfers.transfers_api.get_transfer(id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_BALANCE_PLATFORM_API_KEY' adyen.env = :test # Set to "live" for live environment # Send the request result = adyen.transfers.transfers_api.get_transfer('id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, TransfersAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_BALANCE_PLATFORM_API_KEY", environment: "TEST" }); // Send the request const transfersAPI = new TransfersAPI(client); const response = transfersAPI.TransfersApi.getTransfer("id"); ``` The response contains all the details of the transfer. Take note of the following: | Response parameter | Description | | | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | - | | [amount](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#responses-200-amount) | An object that contains the amount and currency of the transfer funds. | | | [direction](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#responses-200-direction) | Specifies whether the transferred funds are **incoming** or **outgoing**. | | | [events](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#responses-200-events) | An array that contains the event history of the transfer. | | | [reference](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#responses-200-reference) | Your internal reference for the transfer. | | | [status](https://docs.adyen.com/api-explorer/transfers/latest/get/transfers/\(id\)#responses-200-status) | The current status of the transfer. For example: **received**, **authorised**, or **booked**. | | **Example GET /transfers/{id} response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "creationDate": "2023-12-05T10:36:10+01:00", "id": "3JNC4O615TH2D8JY", "accountHolder": { "description": "Your description for the account holder", "id": "AH00000000000000000000001", "reference": "Your reference for the account holder" }, "amount": { "currency": "EUR", "value": 1235 }, "balanceAccount": { "description": "Your description for the balance account", "id": "BA00000000000000000000001" }, "category": "bank", "counterparty": { "bankAccount": { "accountHolder": { "fullName": "A. Klaassen" }, "accountIdentification": { "type": "iban", "iban": "NL91ABNA0417164300" } } }, "description": "Your description for the transfer", "direction": "outgoing", "paymentInstrument": { "description": "Your description of the payment instrument", "id": "PI00000000000000000000001" }, "reason": "approved", "reference": "Your internal reference for the transfer", "referenceForBeneficiary": "Your reference sent to the beneficiary", "status": "booked", "balances": [ { "balance": -1235, "currency": "EUR", "received": 0, "reserved": 0 } ], "events": [ { "bookingDate": "2023-12-05T10:36:24+01:00", "id": "EVJN00000000000000000000000001", "mutations": [ { "currency": "EUR", "received": -1235 } ], "status": "received", "type": "accounting" }, { "bookingDate": "2023-12-05T10:36:24+01:00", "id": "EVJN00000000000000000000000002", "mutations": [ { "currency": "EUR", "received": 1235, "reserved": -1235 } ], "status": "authorised", "type": "accounting" }, { "bookingDate": "2023-12-05T10:36:25+01:00", "id": "EVJN00000000000000000000000003", "mutations": [ { "balance": -1235, "currency": "EUR", "received": 0, "reserved": 1235 } ], "status": "booked", "transactionId": "EVJN00000000000000000000000003EUR", "type": "accounting", "valueDate": "2023-12-05T10:36:10+01:00" }, { "estimatedArrivalTime": "2023-12-05T18:00:00+01:00", "id": "EVTR00000000000000000000000001", "type": "tracking", "updateDate": "2023-12-05T10:36:28+01:00" } ], "sequenceNumber": 4, "tracking": { "estimatedArrivalTime": "2023-12-05T18:00:00+01:00", "type": "estimation" }, "transactionRulesResult": { "allHardBlockRulesPassed": true, "score": 0 }, "type": "bankTransfer" } ``` ## Download a transfer confirmation letter If a user asks about a transfer, you can send them a bank transfer confirmation letter which you can download from your Customer Area. The letter is in PDF format, shows the transfer details and the beneficiary account, and confirms that Adyen has sent the instruction to carry out the transfer. To download bank transfer confirmation letters, your account must have the following [role](/account/user-roles#platforms): * **Download transfer confirmation letter** To download a confirmation letter from your [Customer Area](https://ca-test.adyen.com/): 1. Go to **Transactions** > **Transfers**. 2. Set filters: 1. Select **More filters**. 2. Set **Status** to **Booked**. 3. Set **Type** to **Bank transfer**. 4. Select **Apply all**. 3. Select the **Transfer ID** of the transfer for which you want to download a confirmation letter. 4. Select **Transfer confirmation letter**. ## See also * [Set up webhooks](/business-accounts/third-party-transfer-webhooks) * [Track third-party transactions](/business-accounts/transactions) --- # Source: https://docs.adyen.com/capital.md Section: Capital Title: Capital Description: Offer business financing to users within your platform or marketplace. --- title: "Capital" description: "Offer business financing to users within your platform or marketplace." url: "https://docs.adyen.com/capital" source_url: "https://docs.adyen.com/capital.md" canonical: "https://docs.adyen.com/capital" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Capital Offer business financing to users within your platform or marketplace. [View source](/capital.md) ##### Request an invite Interested to learn more about Adyen Capital? [Fill out this form](https://www.adyen.com/capital#form) to let us know. Adyen Capital allows you to build an embedded financing offering for eligible users to support their operational needs. With Capital, you can allow your users to get business financing from Adyen by using our APIs or low-code components that you integrate in your UI. We assess risks upfront and proactively create offers for your users. This allows your users to quickly get funds paid out to their balance account or transfer instrument, without the need for an additional application process. Users repay daily based on a *fixed percentage of their processed volume* through Adyen. This way, they only repay as they earn and repayments do not impede their cash flow. In addition, users pay one transparent fixed fee — no interest and no hidden costs. ## Supported countries/regions You can offer business financing to users operating in any of the following countries and regions. | Europe | | | ------ | - | Finland\ France\ Sweden\ United Kingdom (including the Channel Islands and Isle of Man) | North America | | | ------------- | - | Canada (excluding Saskatchewan)\ United States (including Puerto Rico) | Asia Pacific | | | ------------ | - | Australia ## Next steps Find out how you can get started with your integration. [required](/capital/get-started) [Get started](/capital/get-started) [See an overview of the steps from signing up to going live.](/capital/get-started) [Account structure and resources](/capital/account-structure-resources) [Learn about the resources you need to use and manage Capital.](/capital/account-structure-resources) [How Capital works](/capital/how-capital-works) [Get familiar with the process of offering business financing to your users.](/capital/how-capital-works) --- # Source: https://docs.adyen.com/capital/account-structure-resources.md Section: Capital Title: Account structure and resources Description: Understand the account structure you need for offering Capital to your users. --- title: "Account structure and resources" description: "Understand the account structure you need for offering Capital to your users." url: "https://docs.adyen.com/capital/account-structure-resources" source_url: "https://docs.adyen.com/capital/account-structure-resources.md" canonical: "https://docs.adyen.com/capital/account-structure-resources" last_modified: "2026-01-02T09:06:00+01:00" language: "en" --- # Account structure and resources Understand the account structure you need for offering Capital to your users. [View source](/capital/account-structure-resources.md) Before you start building the integration, you need to understand the account structure of Adyen Capital, as well as the general [account structure of Adyen for Platforms](/platforms/account-structure-resources). This knowledge is crucial for accurately onboarding users, creating resources, managing user capabilities, and ensuring compliance. This page explains how the structure of Adyen for Platforms and its legal entity management form the foundation for Adyen Capital. It also outlines the specific resources needed for business financing. ## Adyen for Platforms structure Capital is currently available only for merchant accounts with an [Adyen for Platforms](/adyen-for-platforms-model) integration. With Adyen for Platforms, your merchant accounts are connected to your **balance platform**. The balance platform is an accounting system that manages the flow of funds within your business. In your balance platform, you can: * Onboard users of your platform and [request capabilities](/capital/manage-user-capabilities) for them. * View [grant offers](/capital/how-capital-works#get-available-grant-offers) available for your users. * [Pay out grants](/capital/how-capital-works#pay-out-the-grant) to your users. * Manage all existing [grants](#capital-structure) in your balance platform. To enable your users to use Capital, you must create the following resources for them: * **Legal entity**: Contains information about your user, for example, the legal name, address, and tax information of the organization. Adyen uses this information to perform verification checks as required by payment industry regulations. * **Transfer instrument**: Your user's verified bank account where they can receive grant payouts. * **Supporting document**: A document that allows us to verify the information provided about your user's legal entity or transfer instrument. * **Account holder**: Specifies what your user can do in your platform, for example, receive fund transfers to their balance account and payouts to their verified transfer instrument (bank account). An account holder must be linked to your user's balance account and [main legal entity](/platforms/account-structure-resources/legal-entity-management). * **Balance account**: Holds the funds of your user. All financial activities in your platform, such as paying out to a bank account, happen through balance accounts. ## Capital structure Capital allows you to provide business financing in units called *grants*. Grants are conceptually similar to the funds paid out to the user and the conditions they need to meet to repay the funds. When you start using Capital, we create the following resources in your balance platform: * **Grant account**: Allows you to track the total amount of outstanding receivables that Adyen has in relation to grants in your balance platform. * **Grant reference**: Tracks the balances related to specific grants. These references are created when a grant is paid out. The following diagram shows an example of an account structure that supports Capital. ![](/user/pages/docs/07.capital/02.account-structure-resources/account_structure.svg?decoding=auto\&fetchpriority=auto) ### Grant account For your balance platform, we create a new type of account — **grant account**. This account doesn't hold any funds, it allows you to track the total amount of outstanding receivables that Adyen has in relation to grants in your balance platform. You can view the total of all outstanding grants on your balance platform on your grant account. We assign one currency per grant account. If you need to offer grants in multiple currencies, you will need multiple grant accounts — one for each currency. For example, if Adyen pays out five grants worth **EUR 10,000** with a fee of **EUR 1,000** each to your users, then this account will have a total of **EUR 55,000**. The grant account has an ID starting with **CG**, for example, **CG00000000000000000000001**, where CG stands for **Capital Grant Account**. ### Grant reference For your users, we create a **grant reference** that has a one-to-one relationship with the grant. This means that every time a new grant is paid out, a new grant reference is created. The grant reference tracks the total balance, the principal balance, and the fee balance to keep a record of the outstanding grant. The grant reference has an `Active` status until the grant is fully repaid. Once the grant is fully repaid, the grant reference is closed—status `Repaid`. For example, if Adyen pays out a grant worth **EUR 10,000** with a fee of **EUR 1,000** to your user, then this reference will have a total of **-EUR 11,000**. The negative balance decreases as the user repays the grant until the balance is **EUR 0**. The grant reference has an ID starting with **GR**, for example, **GR00000000000000000000001**. ## Next steps [required](/capital/integration-checklist) [Integration checklist](/capital/integration-checklist) [Learn how to integrate Capital into your platform or marketplace.](/capital/integration-checklist) [How Capital works](/capital/how-capital-works) [Get familiar with the process of offering business financing to your users.](/capital/how-capital-works) --- # Source: https://docs.adyen.com/capital/capital-components.md Section: Capital Title: Integrate capital components Description: Enable users to access business financing from Adyen using Platform Experience components. --- title: "Integrate capital components" description: "Enable users to access business financing from Adyen using Platform Experience components." url: "https://docs.adyen.com/capital/capital-components" source_url: "https://docs.adyen.com/capital/capital-components.md" canonical: "https://docs.adyen.com/capital/capital-components" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Integrate capital components Enable users to access business financing from Adyen using Platform Experience components. [View source](/capital/capital-components.md) The capital components are designed to comply with financial product regulations and include all necessary disclosures out of the box. It is crucial **not** to alter or hide: * Any text indicating that loans are provided by Adyen or its local branches. * Any country-specific legal notices, such as the Equal Credit Opportunity Act (ECOA) in the United States. Read more in [product guidelines for marketing and communication material](/capital/marketing-user-communication). ##### Learn more ![GitHub logo](/user/pages/reuse/pfs-components/platform-experience/github-logo.svg?decoding=auto\&fetchpriority=auto)  [View our repository on GitHub](https://github.com/Adyen/adyen-platform-experience-web) ![Click icon](/user/pages/reuse/pfs-components/platform-experience/click.svg?decoding=auto\&fetchpriority=auto)  [Try it out with a live demo](https://demotool.adyen.com/se/pie/platform-tx) ![Megaphone icon](/user/pages/reuse/pfs-components/platform-experience/megaphone.svg?decoding=auto\&fetchpriority=auto)  [Explore the latest updates](/release-notes/platforms-and-financial-products) Capital components enable you to offer Adyen Capital in your portal's user interface (UI) with minimal engineering effort. These components integrate all the features required to offer business financing (also called a grant) to your users without making multiple API requests. This means you do not need to implement API calls to access available grant offers, generate the Terms of Service, or handle the grant payouts. The components handle all of this automatically. Additionally, the components provide greater flexibility, allowing users to choose a grant amount and repayment term that best fits their business needs, within their qualifying limits. This page provides guidance on: * The available capital components, which include the **Capital Overview** component and the **Capital Offer** component. * A standard user flow that these components cover. * Other information required to understand capital components, such as a term sheet and statuses of a grant. The guidance and features available may differ based on the library version in use. We recommend using the latest library version to take advantage of the newest features and improvements. Ensure you select a version in the next section before starting your integration. ## Capital components Use Platform Experience components to offer business financing to your users. ### Component Description ## Capital Overview component The **Capital Overview** component provides detailed information (also known as a term sheet) for a grant, its current status, and repayment progress. This component allows users to view bank account details needed to send unscheduled repayments for active grants, such as early repayments, or if they are behind schedule due to insufficient acquiring volume. It also prompts users to complete necessary actions to secure the grant, such as signing the Terms of Service. The following tabs illustrate how the component appears on various screen sizes. ### Tab: Mobile [![capital overview mobile](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-overview-mobile.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-overview-mobile.svg) ### Tab: Desktop [![capital overview desktop](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-overview-desktop.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-overview-desktop.svg) The **Capital Overview** component enables users to: * View messages indicating their eligibility to receive a grant. * Sign the Terms of Service required to secure a grant from Adyen. * Provide additional information when a loan exceeding EUR 25,000 is requested. * Check the current status of their grant. * Access the term sheet for detailed information about the active grant, such as the 30-day repayment minimum, repayment period, fees, the amount already repaid, and the remaining amount. * Track their [repayment](/capital/how-capital-works#repaying-the-grant) progress. * View the bank account details needed to pay back their grant, whether to send early repayments or catch up if behind schedule (for active grants only). By default, the **Capital Overview** component includes the **Capital Offer** component, which together provide a standard user flow. ## Capital Offer component The **Capital Offer** component shows users the maximum grant amount they qualify for and a preliminary term sheet, enabling them to apply for a grant. The following tabs illustrate how the component appears on various screen sizes. ### Tab: Mobile [![capital offer mobile](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-offer-mobile.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-offer-mobile.svg) ### Tab: Desktop [![capital offer desktop](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-offer-desktop.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/component-description/capital-offer-desktop.svg) The **Capital Offer** component enables users to: * Select a grant amount within their qualifying limit using a dynamic slider, and choose a repayment plan [variable terms](#variable-terms). Term durations are offered for 3, 6, or 12 months, each option shows its corresponding daily repayment rate. * View a preliminary term sheet of the selected grant offer, such as the 30-day repayment minimum, repayment period, and fees. * Apply for a grant. ## Standard user flow By default, the **Capital Offer** component is embedded in the **Capital Overview** component, creating a standard user flow. This flow consists of a series of interactive screens that users engage with, all rendered within a single component element on the same portal's UI page. 1. Not qualified for a grant 2. Pre-qualified for a grant 3. Grant offer selection 4. Grant offer term sheet 5. Required actions 6. Active grant 7. Fully repaid grants ### Tab: Not qualified **Not qualified for a grant**: when the user is not yet qualified for a grant, they see a message informing them of their ineligibility.\ This screen is part of the **Capital Overview** component.\ [![not qualified](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/not-qualified.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/not-qualified.svg) ### Tab: Pre-qualified **Pre-qualified for a grant**: if the user is pre-qualified for a grant, they see a message indicating the maximum grant amount they qualify for. The user can select the **See options** button to proceed.\ This screen is part of the **Capital Overview** component.\ [![pre-qualified](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/pre-qualified.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/pre-qualified.svg) ### Tab: Grant offer **Grant offer selection**: on this screen, the user can: * Select a grant amount and choose a repayment plan within their qualifying limit using a dynamic slider and [variable terms](#variable-terms). Term durations are offered for 3, 6, or 12 months, with each option displaying its corresponding daily repayment rate. * View a preliminary term sheet based on their selection, such as the 30-day repayment minimum, repayment period, and fees. The user can select the **Review request** button to proceed. This screen is part of the **Capital Offer** component.\ [![grant offer](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/offer-selection.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/offer-selection.svg) ### Tab: Term sheet **Grant offer term sheet**: on this screen, the user can view a preliminary term sheet of the selected grant offer and apply for a grant by selecting the **Submit request** button.\ This screen is part of the **Capital Offer** component.\ [![term sheet](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/preliminary-term-sheet.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/preliminary-term-sheet.svg) ### Tab: Required actions Here are the possible required actions, depending on the use case: * **Provide Additional Information** (for loans greater than EUR 25,000): After a user applies for a grant over EUR 25,000, a message prompts them to submit extra information. Once this information is submitted, the grant amount is credited to their primary balance account. * **Sign the Terms of Service**: after the user applies for a grant, they see a message prompting them to sign Adyen's Terms of Service. When the grant is approved and the Terms of Service are signed, the grant amount is credited to the user's primary balance account.\ This screen is part of the **Capital Overview** component. [![required actions](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/required-steps.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/required-steps.svg) ### Tab: Active grant **Active grant**: after receiving the grant, the user can view their active grant information, such as the outstanding amount and the term sheet. They have the option to send unscheduled repayments, such as early repayments, or catch up if behind schedule. By selecting the **Send repayment** button, they can view and copy the bank account details needed to initiate a bank transfer from their bank account. Users can only send repayments from a bank account (transfer instrument) which is verified by Adyen. This screen is part of the **Capital Overview** component.\ [![active grant](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/active-grant.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/active-grant.svg) ### Tab: Repaid grants **Fully repaid grants**: on this screen, the user can see the details of any grants they have previously received and repaid. They can also apply for a new grant from this screen, if eligible.\ This screen is part of the **Capital Overview** component.\ [![repaid grants](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/repaid-grant.svg)](/user/pages/filters/pe-components-capital-concept/1-12-0/standard-user-flow/repaid-grant.svg) The user flow described above is applicable for scenarios where a user is operating in a [supported country or region](/capital#supported-countriesregions). Additionally, the capital components handle situations where a user is in a country/region that is not yet supported. In these cases, a dedicated screen is shown to the user. You can modify this standard user flow by including additional [component instance methods and parameters](/capital/integration-steps-components?component=Capital\&integration=components\&version=1.5.x#component-methods) in your implementation. ### Grant Statuses ## Statuses of a grant The capital components show the status of a grant, which represents the different stages the grant goes through. The components automatically manage status updates, so no further action is needed on your part. The following diagram illustrates how grant statuses evolve over time. [![](/user/pages/filters/pe-components-capital-concept/1-7-0/grant-statuses/grant-statuses.svg)](/user/pages/filters/pe-components-capital-concept/1-7-0/grant-statuses/grant-statuses.svg) You can find a detailed explanation for each status in the following table. | Status | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pending** | The grant is requested and the Terms of Service are signed, but the funds are not yet paid out to the user's balance account. | | **Action needed** | The grant is requested, and the user is required to sign Adyen's Terms of Service. Additionally, if the requested loan exceeds EUR 25,000, extra information is required. | | **Active** | The grant is approved and paid out to the user's balance account. The user can only have one active grant at a time. | | **Failed** | The grant is requested, but not approved or paid out due to technical failures or incomplete documentation. | | **Fully repaid** | The grant is fully repaid. The user can see a new grant offer, if eligible. | | **Revoked** | The grant is canceled by the user. The grant funds are returned to Adyen. | | **Written off** | The grant is closed by Adyen because the user failed to repay it. | ### Grant Qualifying Limit ## Qualifying limit of a grant The qualifying limit of a grant is the maximum amount for which a user can be eligible. This limit varies for each individual and is determined based on their risk level assessment. In general, the grant amount a user may apply for through the capital components ranges from EUR 500 to EUR 50,000, or the equivalent amount in another supported currency. ## Variable terms Capital components support variable repayment terms, and give your users greater flexibility and control over their cash flow. When users configure an offer, they are not locked into a single fixed timeline. Instead, they can customize their financing by selecting a repayment term that best matches their business cycle and predictable revenue streams alongside their desired grant amount. The component dynamically determines the daily repayment rate, fees, total repayment amount, and maximum repayment amount based on two primary inputs: * **Grant amount**: Adjusted using a dynamic slider within the user's maximum qualifying limit. * **Term duration**: Predefined periods of 3, 6, or 12 months. The available term options and associated fee structures are calculated dynamically based on the user's risk level assessment and processing history. ### Grant Term Sheet ## Term sheet of a grant The capital components show a term sheet for a grant. Depending on where the user is in the user flow, this may either be a preliminary term sheet for a grant offer with limited details or a full term sheet for an active grant. The term sheet can include these details: | Term sheet item | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Account** | The unique reference of the balance account to which the grant amount is paid out. | | **Account ID** | The unique identifier of the balance account to which the grant amount is paid out. By default, this is the user's primary balance account, which is the first balance account created for the associated account holder. | | **Daily repayment rate** | The percentage of the user's daily net captured volume that is withheld each day for the repayment of the total repayment amount. | | **Expected repayment period** | The period in days or months during which the user is expected to repay the grant amount. This period is calculated based on the volume of transactions processed for this user. | | **Grant ID** | The unique identifier of the grant. | | **Maximum repayment period** | The period in days or months during which the grant repayment amount must be paid in full. | | **Remaining amount** | The outstanding grant amount, excluding fees, as of a specific date. | | **Remaining fees** | The outstanding fee amount as of a specific date. | | **Repaid amount** | The grant amount paid back to Adyen as of a specific date. | | **Repaid fees** | The fee amount paid back to Adyen as of a specific date. | | **30-day repayment minimum** | The minimum amount the user is expected to repay every 30-day period to fully pay off the grant within the expected repayment period. If the total 30-day repayment drops below this threshold, Adyen may take additional actions to ensure that the user repays on time. | | **Total fees** | The fixed fees associated with the grant that the user must pay to Adyen in relation to business financing. | | **Total repayment amount** | The total amount due for repayment, which includes the grant amount received along with any associated fees. | ## Next steps [required](/capital/integration-steps-components) [Integration steps for capital components](/capital/integration-steps-components) [Integrate capital components to let users access business financing from Adyen.](/capital/integration-steps-components) [Component libraries](/platforms/components-overview) [Learn about different types of components.](/platforms/components-overview) --- # Source: https://docs.adyen.com/capital/collect-user-data.md Section: Capital Title: Collect user data for higher financing amounts Description: Learn how to collect additional KYC data from your user when they request more than EUR 25,000 in combined business financing. --- title: "Collect user data for higher financing amounts" description: "Learn how to collect additional KYC data from your user when they request more than EUR 25,000 in combined business financing." url: "https://docs.adyen.com/capital/collect-user-data" source_url: "https://docs.adyen.com/capital/collect-user-data.md" canonical: "https://docs.adyen.com/capital/collect-user-data" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Collect user data for higher financing amounts Learn how to collect additional KYC data from your user when they request more than EUR 25,000 in combined business financing. [View source](/capital/collect-user-data.md) In specific situations, Adyen may require your users to provide additional information about their businesses to comply with the [European Central Bank's AnaCredit data collection requirements](https://www.ecb.europa.eu/stats/ecb_statistics/anacredit/html/index.en.html). This requirement applies to certain legal entity types when: * A selected financing offer meets the threshold, usually EUR 25,000 or the equivalent in another supported currency. * The combined total of a new financing offer and any existing outstanding balance meets the threshold, usually EUR 25,000 or the equivalent in another supported currency. The amount thresholds and restrictions on legal entity types differ by country or region. Refer to the [country and region-specific regulations](#country-region-regulations) for more details. This page gives an overview of the steps needed to collect Know Your Customer (KYC) data from users requesting higher financing amounts. These instructions apply if you are integrating Capital through our [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). If you are using our [UI components for Capital](/capital/capital-components), you can also benefit from this feature. The components automatically facilitate the collection of user data through the Adyen-hosted page, so no additional actions are required on your part. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration that supports Capital. | | **API credentials** | You must have:- [Balance Platform API key](/capital/manage-access#manage-api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Ensure that you have asked your Adyen contact to assign the following role to your API credential: * **Balance\_Platform\_Capital\_Configuration\_Role** * **Balance\_Platform\_Capital\_Grant\_Initiation\_Role** - [Legal Entity Management API key](/platforms/manage-access/api-credentials-web-service?tab=create-lem_2) (for example, **ws\[\_123456]@Scope.Company\_\[YourCompanyAccount]**) to access the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). | | **Capabilities** | Make sure that your user's account holder has the following [capabilities](/capital/manage-user-capabilities):- **getGrantOffers** - **receiveGrants** | | **Webhooks** | Subscribe to the following webhooks:- [Capital webhooks](https://docs.adyen.com/api-explorer/capital-webhooks/latest/overview) - [Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview) | | **Limitations** | * The feature is compatible only with legal entities created using **version 3 or higher** of the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). * Requesting a higher financing amount automatically assigns the user to a risk level that requires additional KYC information. This assignment is currently irreversible, so users must provide the required data before receiving any future grants, even if those grants are below the higher financing threshold. * Users must submit their data before the expiration date of the grant offer. Otherwise, the offer expires, and the user need to request the grant again. * When using Adyen's-hosted page to collect user data, consider the following: * You have four minutes to redirect users before a hosted onboarding link expires. * The link can only be clicked once by the user. They have access to the hosted onboarding page for one hour. After this time, the link expires. The link also expires if the user refreshes the page. This ends the user's session. If the link expires, you must generate a new link. | | **Setup steps** | Before you begin, make sure:* You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. * You reviewed the [country and region-specific regulations](#country-region-regulations) that may apply to your situation, such as thresholds for combined business financing or restrictions on legal entity types. * You [configured a grant](/capital/make-grant-request) to trigger the required checks. | ## How it works After a user selects a grant offer, you [send an API request to configure a grant](/capital/make-grant-request) for them. Adyen then performs checks to calculate the user's total exposure. This calculation includes the new grant request along with any outstanding balance for that user. If the total amount exceeds the threshold determined for a specific country or region, additional KYC data is required. The procedure is as follows: 1. Adyen performs checks whether the user's exposure exceeds the threshold. 2. Adyen sends webhooks to your server to [notify you that additional KYC data is required](#kyc-required). 3. You [collect the necessary KYC data](#collect-kyc) and submit it to Adyen. 4. Adyen reviews the user data and [notifies you about the verification results](#get-results). 5. After Adyen verifies the data and approves the grant, the grant amount is automatically disbursed to the user. The following diagram illustrates an example when a user selects an offer of EUR 25,000 or more, and how it affects the status of the grant and the user's capabilities. ![Higher financing amounts flow](/user/pages/docs/07.capital/16.collect-user-data/higher-financing-amounts.svg?decoding=auto\&fetchpriority=auto) ## 1. Select a way to collect user data Adyen offers two options for collecting additional KYC data from users requesting higher financing amounts. Select the option that best suits your needs. | Option | Hosted onboarding (recommended) | API-only | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Your users are redirected to a secure, Adyen-hosted page. You make a single API request to generate a one-time link, which you then present to the user in your user interface (UI). The hosted onboarding page handles the entire data collection process and user flow. | You build a custom user interface directly within your platform. You use Adyen's Legal Entity Management APIs to determine what information is needed from the user and then submit that data through subsequent API calls. | | **Provides you with** | * **Speed and simplicity**: Minimal technical effort as Adyen provides a prebuilt UI. * **Guaranteed compliance**: Adyen handles compliance with the latest regulatory requirements. The hosted onboarding page automatically includes all necessary fields for collecting information about the user's legal entity. * **Security**: Adyen manages the secure data collection environment. * **Customized design**: You can optionally [customize your hosted onboarding page](/platforms/onboard-users/customize-hosted-onboarding) so that the interface looks like it is owned by your platform. | - **Complete control**: Full control over UI and user experience. - **Native experienc**e: User never leaves your site. | | **Required from you** | * **Minimal resources**: You make a single API request to create a hosted onboarding link and then present the generated link to the user in your UI. | - **Significant resources**: Requires dedicated development resources. - **Data management**: You are responsible for identifying and submitting data. - **Ongoing maintenance**: You must stay informed and update your integration to comply with the latest regulatory changes. | ## 2. Get updates when additional data is required Adyen sends a webhook to your server to notify you that additional KYC data is required for the user to receive a higher financing amount. Alternatively, you can make an API request to get details about a specific grant. 1. Get updates about the grant status and required actions for higher financing amount using one of the following options: * Listen to [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhooks * Make a GET [/grants/{grantId}](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)) request 2. In the webhook payload or the API response, note the following: * `actions.code`: Set to **AnaCreditCapabilityRule** * `actions.resolved`: Set to **false** * `status.code`: Set to **Reviewing** This indicates that an additional KYC data requirement has been established for the grant. To receive the grant, users must provide the necessary information. The grant status remains **Reviewing** until the required actions are completed. **balancePlatform.grants.updated - additional KYC data required** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "amount": { "currency": "EUR", "value": 2999999 }, "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Reviewing", "actions": [ { "actionCode": "AnaCreditCapabilityRule", "resolved": false } ] } } }, "environment": "test", "timestamp": "2025-09-17T12:58:06.749Z", "type": "balancePlatform.grants.updated" } ``` The unresolved **AnaCreditCapabilityRule** code impacts the Capital capabilities, `getGrantOffers` and `receiveGrants`, of your user's account holder:\ \- [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): Set to **pending**\ \- [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Set to **false**.\ \- [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems): Contains verification errors that must be resolved. ## 3. Collect user data Follow the steps depending on your selected way of data collection: ### Tab: Hosted onboarding (recommended) 1. Create a link to the hosted onboarding page by making a POST [/legalEntities/{id}/onboardingLinks](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/onboardingLinks) request, using the ID of the main legal entity in the path. You can optionally [customize your hosted onboarding page](/platforms/onboard-users/customize-hosted-onboarding), or the default Adyen page is shown to your user. **Create a hosted onboarding link** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/onboardingLinks \ -H 'Authorization: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "themeId":"YOUR_THEME_ID", "redirectUrl":"https://your-company.example.com", "locale":"nl-NL" }' ``` #### Java ```java // Adyen Java API Library v41.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) // Send the request HostedOnboardingApi service = new HostedOnboardingApi(client); OnboardingLink response = service.getLinkToAdyenhostedOnboardingPage("id", onboardingLinkInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) // Send the request $service = new HostedOnboardingApi($client); $response = $service->getLinkToAdyenhostedOnboardingPage('id', $onboardingLinkInfo); ``` #### C\# ```cs // Adyen .NET API Library v34.0.2 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) // Send the request var service = new HostedOnboardingService(client); var response = service.GetLinkToAdyenhostedOnboardingPage("id", onboardingLinkInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.1.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const onboardingLinkInfo = { themeId: "YOUR_THEME_ID", redirectUrl: "https://your-company.example.com", locale: "nl-NL" } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.HostedOnboardingApi.getLinkToAdyenhostedOnboardingPage("id", onboardingLinkInfo); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) // Send the request service := client.LegalEntityManagement() req := service.HostedOnboardingApi.GetLinkToAdyenhostedOnboardingPageInput("id").OnboardingLinkInfo(onboardingLinkInfo) res, httpRes, err := service.HostedOnboardingApi.GetLinkToAdyenhostedOnboardingPage(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "themeId": "YOUR_THEME_ID", "redirectUrl": "https://your-company.example.com", "locale": "nl-NL" } # Send the request result = adyen.legalEntityManagement.hosted_onboarding_api.get_link_to_adyenhosted_onboarding_page(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v11.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :themeId => 'YOUR_THEME_ID', :redirectUrl => 'https://your-company.example.com', :locale => 'nl-NL' } # Send the request result = adyen.legalEntityManagement.hosted_onboarding_api.get_link_to_adyenhosted_onboarding_page(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.HostedOnboardingApi.getLinkToAdyenhostedOnboardingPage("id", onboardingLinkInfo); ``` 2. In the response, note the `url`. This is the link to the hosted onboarding page. You need to provide this link to the user in the next step. **Hosted onboarding link created** ```json { "url": "YOUR_HOSTED_ONBOARDING_LINK" } ``` 3. Provide the user with a link to the hosted onboarding page. For example, in your UI, show a link or button. When the user selects it, get the hosted onboarding link you generated in the previous step, and redirect the user to the page. ![Collect data through hosted onboarding](/user/pages/docs/07.capital/16.collect-user-data/collect-with-hosted-onboarding.svg?decoding=auto\&fetchpriority=auto) The user can then provide details about their business on the hosted onboarding page. After providing all required information, users must select **Submit data**. This automatically sends the data to Adyen. ### For businesses with an immediate parent or ultimate parent company If the user's business has an immediate parent or ultimate parent company, they must provide the details for those companies. To do this, the user must create separate legal entities for each parent company and link them to their main legal entity. This can be completed on the hosted onboarding page. ![Ownership structure](/user/pages/docs/07.capital/16.collect-user-data/ownership-structure.svg?decoding=auto\&fetchpriority=auto) ### Tab: API-only 1. Determine what data needs to be collected from the user by choosing one of the following options: * Listen to [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks * Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request 2. In the webhook payload or API response, note the following for each of the Capital capabilities: * [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities) array, including * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): Set to **pending** * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Set to **false** * [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) array: Contains [verification errors](#verification-errors), including the indication of what data is missing, that must be resolved. **balancePlatform.accountHolder.updated** ```json { "id" : "LE00000000000000000000001", "type" : "organization", "organization" : { "legalName" : "Test", "type" : "privateCompany", "vatNumber" : "NL123456789B01", "registrationNumber" : "12345678", "registeredAddress" : { "street" : "My street", "city" : "AMS", "postalCode" : "1052AA", "country" : "NL" }, "doingBusinessAsAbsent" : true, "registrationNumberAbsent" : false }, "documentDetails" : [ { "id" : "SE00000000000000000000001", "type" : "registrationDocument", "fileName" : "proof_of_registration_number", "description" : "Document type: registrationDocument", "active" : true, "modificationDate" : "2025-09-15T16:30:21.022+02:00" } ], "entityAssociations" : [ { "legalEntityId" : "LE00000000000000000000002", "type" : "signatory", "jobTitle" : "Director", "associatorId" : "LE00000000000000000000001", "entityType" : "individual", "name" : "Test" }, { "legalEntityId" : "LE00000000000000000000003", "type" : "uboThroughControl", "jobTitle" : "Director", "associatorId" : "LE00000000000000000000001", "entityType" : "individual", "name" : "Test" } ], "capabilities" : { "receiveGrants" : { "allowed" : false, "requested" : true, "verificationStatus" : "pending" }, "getGrantOffers" : { "allowed" : false, "requested" : true, "verificationStatus" : "pending" } }, "problems" : [ { "entity" : { "id" : "LE00000000000000000000001", "type" : "LegalEntity" }, "verificationErrors" : [ { "code" : "2_8227", "message" : "Status of legal proceedings was missing.", "type" : "dataMissing", "remediatingActions" : [ { "code" : "2_907", "message" : "Provide 'organization.statusOfLegalProceeding' to legal entity" } ], "capabilities" : [ "receiveGrants" ] }, { "code" : "2_8203", "message" : "organization.economicSector was missing", "type" : "dataMissing", "remediatingActions" : [ { "code" : "2_905", "message" : "Provide 'organization.economicSector' to legal entity" } ], "capabilities" : [ "receiveGrants" ] }, { "code" : "2_8226", "message" : "Legal form was missing.", "type" : "dataMissing", "remediatingActions" : [ { "code" : "2_906", "message" : "Provide 'organization.legalForm' to legal entity" } ], "capabilities" : [ "receiveGrants" ] }, { "code" : "2_8228", "message" : "Date of initiation of legal proceedings was missing.", "type" : "dataMissing", "remediatingActions" : [ { "code" : "2_908", "message" : "Provide 'organization.dateOfInitiationOfLegalProceeding' to legal entity" } ], "capabilities" : [ "receiveGrants" ] } ] } ] } ``` 3. Collect the necessary data from your user through your user interface. Note, if the user's business has an immediate parent or ultimate parent company, [additional steps are required](#parent-company). 4. Make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request using the [id](https://docs.adyen.com/api-explorer/legalentity/4/patch/legalEntities/\(id\)#path-id) of the main legal entity in the path. In the request, include the new details. Only parameters passed in the request body are updated. The following is a complete list of KYC data points that may be required for higher financing amounts eligibility. | Parameter | Type | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [organization.dateOfInitiationOfLegalProceeding](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-dateOfInitiationOfLegalProceeding) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if the value of `statusOfLegalProceeding` is one of the following:- **underJudicialAdministration** - **bankruptcyInsolvency** - **otherLegalMeasures**The date at which a legal proceeding was initiated, in **YYYY-MM-DD** format. Example: **2000-02-12** | | [organization.economicSector](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-economicSector) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The sector of the economy the legal entity operates within, represented by a 2-4 digit code that may include a ".". Example: **45.11** You can locate economic sector codes for your area by referencing codes defined by the [NACE](https://ec.europa.eu/eurostat/documents/3859598/5902521/KS-RA-07-015-EN.PDF) (Nomenclature of Economic Activities) used in the European Union. | | [organization.financialReports](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports) | Array of objects | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The financial report information of the organization. Required for organizations registered within the EU. | | [organization.financialReports.annualTurnover](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-annualTurnover) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The annual turnover of the business. The value must not include any separator symbols. Example: **400000** Required for organizations registered within the EU. | | [organization.financialReports.balanceSheetTotal](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-balanceSheetTotal) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The balance sheet total of the business.The value must not include any separator symbols. Example: **400000** Required for organizations registered within the EU. | | [organization.financialReports.currencyOfFinancialData](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-currencyOfFinancialData) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The currency used for the annual turnover, balance sheet total, and net assets, in [ISO currency code](/development-resources/currency-codes#currency-codes) format. Example: **EUR** Required for organizations registered within the EU. | | [organization.financialReports.dateOfFinancialData](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-dateOfFinancialData) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The date the financial data were provided, in YYYY-MM-DD format. Example: **2000-02-12** Required for organizations registered within the EU. | | [organization.financialReports.employeeCount](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-employeeCount) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The number of employees of the business. Example: **1234** Required for organizations registered within the EU. | | [organization.financialReports.netAssets](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-financialReports-netAssets) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | The net assets of the business. The value must not include any separator symbols. Example: **400000** Required for organizations registered within the EU. | | [organization.globalLegalEntityIdentifier](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-globalLegalEntityIdentifier) | String | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | A 20-character, alpha-numeric [code](https://search.gleif.org/#/search/) for the organization, based on the [ISO 17442 standard](https://www.gleif.org/en/organizational-identity/introducing-the-legal-entity-identifier-lei/iso-17442-the-lei-code-structure). The value is not required if [registrationNumber](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization-registrationNumber) has been provided. | | [organization.headOfficeIndicator](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-headOfficeIndicator) | Boolean | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Indicates that the registered business address is also the company's headquarters. | | [organization.institutionalSector](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-institutionalSector) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The institutional sector the organization operates within. The value must be in accordance with the [regulations of the European Central Bank](https://www.ecb.europa.eu/stats/ecb_statistics/anacredit/html/index.en.html). | | [organization.legalForm](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-legalForm) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The legal form for registration of the organization. Use a legal form listed within the [accepted legal forms (.xlsx format)](https://www.ecb.europa.eu/stats/ecb_statistics/anacredit/html/index.en.html) compiled by the Central Bank of Europe. | | [organization.statusOfLegalProceeding](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-organization-statusOfLegalProceeding) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The status of any current or past legal action taken against the legal entity. Possible values:- **noLegalActionsTaken** - **underJudicialAdministration** - **bankruptcyInsolvency** - **otherLegalMeasures**If the value of this field is `noLegalActionsTaken`, then `dateOfInitiationOfLegalProceeding` is not required. Otherwise, it is required. Example: **noLegalActionsTaken** | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required **Update legal entity details** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "economicSector" : "45.11", "legalForm" : "EU300", "statusOfLegalProceeding" : "noLegalActionsTaken", "financialReports" : [ { "annualTurnover" : "150000", "balanceSheetTotal": "350000", "currencyOfFinancialData" : "EUR", "dateOfFinancialData" : "2024-02-12", "employeeCount" : "50", "netAssets" : "400000" } ] } }' ``` #### Java ```java // Adyen Java API Library v41.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo(); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.updateLegalEntity("id", legalEntityInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $legalEntityInfo = new LegalEntityInfo(); $legalEntityInfo; // Send the request $service = new LegalEntitiesApi($client); $response = $service->updateLegalEntity('id', $legalEntityInfo); ``` #### C\# ```cs // Adyen .NET API Library v34.0.2 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo }; // Send the request var service = new LegalEntitiesService(client); var response = service.UpdateLegalEntity("id", legalEntityInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.1.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const legalEntityInfo = { economicSector: "45.11", legalForm: "EU300", statusOfLegalProceeding: "noLegalActionsTaken", financialReports: [ { annualTurnover: "150000", balanceSheetTotal: "350000", currencyOfFinancialData: "EUR", dateOfFinancialData: new Date("2024-02-12"), employeeCount: "50", netAssets: "400000" } ] } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) legalEntityInfo := legalEntityManagement.LegalEntityInfo, } // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.UpdateLegalEntityInput("id").LegalEntityInfo(legalEntityInfo) res, httpRes, err := service.LegalEntitiesApi.UpdateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "economicSector": "45.11", "legalForm": "EU300", "statusOfLegalProceeding": "noLegalActionsTaken", "financialReports": [ { "annualTurnover": "150000", "balanceSheetTotal": "350000", "currencyOfFinancialData": "EUR", "dateOfFinancialData": "2024-02-12", "employeeCount": "50", "netAssets": "400000" } ] } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v11.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :economicSector => '45.11', :legalForm => 'EU300', :statusOfLegalProceeding => 'noLegalActionsTaken', :financialReports => [ { :annualTurnover => '150000', :balanceSheetTotal => '350000', :currencyOfFinancialData => 'EUR', :dateOfFinancialData => '2024-02-12', :employeeCount => '50', :netAssets => '400000' } ] } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const legalEntityInfo: Types.legalEntityManagement.LegalEntityInfo = }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` ### For businesses with an immediate parent or ultimate parent company If the user's business has an immediate parent or ultimate parent company, you also need to collect the details for those companies. Then, submit this information to Adyen as follows: 1. Create a separate legal entity for each parent company, in addition to the main legal entity. For this, make a POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) request using the [organization](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization) details. The following example shows how to create a legal entity for the immediate parent company. **Create legal entity for immediate parent company** #### curl ```bash curl https://kyc-test.adyen.com/lem/v4/legalEntities \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "organization", "organization": { "economicSector": "69.20", "legalForm": "EU200", "legalName": "Test", "principalPlaceOfBusiness": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "registeredAddress": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "statusOfLegalProceeding": "noLegalActionsTaken" } }' ``` #### Java ```java // Adyen Java API Library v41.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.createLegalEntity(legalEntityInfoRequiredType, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) // Send the request $service = new LegalEntitiesApi($client); $response = $service->createLegalEntity($legalEntityInfoRequiredType); ``` #### C\# ```cs // Adyen .NET API Library v34.0.2 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) // Send the request var service = new LegalEntitiesService(client); var response = service.CreateLegalEntity(legalEntityInfoRequiredType); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.1.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const legalEntityInfoRequiredType = { type: "organization", organization: { economicSector: "69.20", legalForm: "EU200", legalName: "Test", principalPlaceOfBusiness: { city: "AMS", country: "NL", postalCode: "1052AA", street: "My street" }, registeredAddress: { city: "AMS", country: "NL", postalCode: "1052AA", street: "My street" }, statusOfLegalProceeding: "noLegalActionsTaken" } } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.createLegalEntity(legalEntityInfoRequiredType); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.CreateLegalEntityInput().LegalEntityInfoRequiredType(legalEntityInfoRequiredType) res, httpRes, err := service.LegalEntitiesApi.CreateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "type": "organization", "organization": { "economicSector": "69.20", "legalForm": "EU200", "legalName": "Test", "principalPlaceOfBusiness": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "registeredAddress": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "statusOfLegalProceeding": "noLegalActionsTaken" } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.create_legal_entity(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :type => 'organization', :organization => { :economicSector => '69.20', :legalForm => 'EU200', :legalName => 'Test', :principalPlaceOfBusiness => { :city => 'AMS', :country => 'NL', :postalCode => '1052AA', :street => 'My street' }, :registeredAddress => { :city => 'AMS', :country => 'NL', :postalCode => '1052AA', :street => 'My street' }, :statusOfLegalProceeding => 'noLegalActionsTaken' } } # Send the request result = adyen.legalEntityManagement.legal_entities_api.create_legal_entity(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.createLegalEntity(legalEntityInfoRequiredType); ``` 2. In the response, note the generated legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id). You need it to associate the additional legal entity with the main legal entity in the next step. **Legal entity for immediate parent company created** ```json { "organization": { "economicSector": "69.20", "legalForm": "EU200", "legalName": "Test", "principalPlaceOfBusiness": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "registeredAddress": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "statusOfLegalProceeding": "noLegalActionsTaken" }, "type": "organization", // Generated legal entity ID "id": "LE00000000000000000000002" } ``` 3. Associate additional legal entity with the main legal entity. For this, make a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request using the [id](https://docs.adyen.com/api-explorer/legalentity/4/patch/legalEntities/\(id\)#path-id) of the main legal entity in the path. In the request, specify an [entityAssociations](https://docs.adyen.com/api-explorer/legalentity/4/patch/legalEntities/\(id\)#request-entityAssociations) array containing the following parameters: When updating the [entityAssociations](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations), note that a PATCH request replaces the whole array. If you only want to update one array item, make sure you include all existing items along with the specific change in your request. | Parameter | Type | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [entityAssociations.type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-type) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Defines the relationship of the legal entity to the current legal entity. Set this to **ultimateParentCompany** or **immediateParentCompany**. | | [entityAssociations.legalEntityId](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-legalEntityId) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the associated legal entity. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required **Add entity association** #### curl ```bash curl https://kyc-test.adyen.com/lem/v4/legalEntities/LE00000000000000000000001 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d ' "entityAssociations":[ { "legalEntityId":"LE00000000000000000000002", "type":"immediateParentCompany" } ] }' ``` #### Java ```java // Adyen Java API Library v41.1.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo(); // Send the request LegalEntitiesApi service = new LegalEntitiesApi(client); LegalEntity response = service.updateLegalEntity("id", legalEntityInfo, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $legalEntityInfo = new LegalEntityInfo(); $legalEntityInfo; // Send the request $service = new LegalEntitiesApi($client); $response = $service->updateLegalEntity('id', $legalEntityInfo); ``` #### C\# ```cs // Adyen .NET API Library v34.0.2 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) LegalEntityInfo legalEntityInfo = new LegalEntityInfo }; // Send the request var service = new LegalEntitiesService(client); var response = service.UpdateLegalEntity("id", legalEntityInfo); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.1.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const legalEntityInfo = { } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) legalEntityInfo := legalEntityManagement.LegalEntityInfo, } // Send the request service := client.LegalEntityManagement() req := service.LegalEntitiesApi.UpdateLegalEntityInput("id").LegalEntityInfo(legalEntityInfo) res, httpRes, err := service.LegalEntitiesApi.UpdateLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request=json_request, id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v11.2.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { } # Send the request result = adyen.legalEntityManagement.legal_entities_api.update_legal_entity(request_body, 'id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const legalEntityInfo: Types.legalEntityManagement.LegalEntityInfo = }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.LegalEntitiesApi.updateLegalEntity("id", legalEntityInfo); ``` The following shows an example response for adding entity association. **Entity association added** ```json { "capabilities": { "getGrantOffers": { "allowed": false, "requested": true, "verificationStatus": "invalid" }, "receiveGrants": { "allowed": false, "requested": true, "verificationStatus": "invalid" } }, "entityAssociations": [ { "associatorId": "LE00000000000000000000001", "entityType": "organization", "legalEntityId": "LE00000000000000000000002", "name": "Test", "type": "immediateParentCompany" } ], "organization": { "doingBusinessAs": "Test", "economicSector": "55", "financialReports": [ { "annualTurnover": "132.00", "currencyOfFinancialData": "EUR", "dateOfFinancialData": "2000-01-01", "employeeCount": "123", "netAssets": "123.00" } ], "legalForm": "EU200", "legalName": "Test", "registeredAddress": { "city": "AMS", "country": "NL", "postalCode": "1052AA", "street": "My street" }, "registrationNumber": "12345678", "statusOfLegalProceeding": "noLegalActionsTaken", "type": "privateCompany", "vatNumber": "NL123456789B01" }, "type": "organization", "id": "LE00000000000000000000001", "problems": [ { "entity": { "id": "LE00000000000000000000001", "type": "LegalEntity" }, "verificationErrors": [ { "capabilities": [ "getGrantOffers", "receiveGrants" ], "code": "2_8141", "message": "'Registration document' was missing.", "remediatingActions": [ { "code": "1_501", "message": "Upload a registration document" } ], "type": "dataMissing" }, { "capabilities": [ "getGrantOffers", "receiveGrants" ], "code": "2_902", "message": "Terms Of Service forms are not accepted.", "remediatingActions": [ { "code": "2_902", "message": "Accept TOS" } ], "type": "invalidInput" } ] } ] } ``` ## 4. Get verification results and grant status updates In order for the grant to be approved, the verification errors must be resolved for the account holder and the necessary actions related to the grant must be completed. 1. Get updates about the verification status and results using one of the following options: * Listen to [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks * Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request The webhook and the API response indicates the following for each of the Capital capabilities: * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): Set to **valid** * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Set to **true** **balancePlatform.accountHolder.updated webhook - verification completed** ```json { "id" : "LE00000000000000000000001", "type" : "organization", "organization" : { "legalName" : "Test", "type" : "privateCompany", "vatNumber" : "NL123456789B01", "registrationNumber" : "12345678", "registeredAddress" : { "street" : "My street", "city" : "AMS", "postalCode" : "1052AA", "country" : "NL" }, "economicSector" : "55", "legalForm" : "NL206", "statusOfLegalProceeding" : "noLegalActionsTaken", "financialReports" : [ { "employeeCount" : "123", "annualTurnover" : "123.00", "netAssets" : "123.00", "currencyOfFinancialData" : "EUR", "dateOfFinancialData" : "2000-02-12" } ], "doingBusinessAsAbsent" : true, "registrationNumberAbsent" : false }, "documentDetails" : [ { "id" : "SE00000000000000000000001", "type" : "registrationDocument", "fileName" : "proof_of_registration_number_20250915_163020_983", "description" : "Document type: registrationDocument", "active" : true, "modificationDate" : "2025-09-15T16:30:21.022+02:00" } ], "entityAssociations" : [ { "legalEntityId" : "LE00000000000000000000002", "type" : "signatory", "jobTitle" : "Director", "associatorId" : "LE00000000000000000000001", "entityType" : "individual", "name" : "Kishore test" }, { "legalEntityId" : "LE00000000000000000000003", "type" : "uboThroughControl", "jobTitle" : "Director", "associatorId" : "LE00000000000000000000001", "entityType" : "individual", "name" : "Test" } ], "capabilities" : { "receiveGrants" : { "allowed" : true, "requested" : true, "verificationStatus" : "valid" }, "getGrantOffers" : { "allowed" : true, "requested" : true, "verificationStatus" : "valid" } } } ``` 2. Get updates about the grant status and required actions using one of the following options: * Listen to [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhooks * Make a GET [/grants/{grantId}](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)) request The webhook and the API response indicates the following: * `actions.code`: Set to **AnaCreditCapabilityRule** * `actions.resolved`: Set to **true** * `status.code`: Set to **Approved** **balancePlatform.grants.updated - grant approved** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "amount": { "currency": "EUR", "value": 2999999 }, "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Approved", "actions": [ { "actionCode": "AnaCreditCapabilityRule", "resolved": true } ] } } }, "environment": "test", "timestamp": "2025-09-17T12:58:06.749Z", "type": "balancePlatform.grants.updated" } ``` ## Country and region-specific regulations For each country or region where Capital is available, the following table specifies: * The legal entity types that are subject to additional regulatory reporting. * The thresholds of combined business financing that trigger these requirements. | Country/Region | Additional regulatory reporting requirements | | -------------------------------------------------------------- | ------------------------------------------------ | | Australia | Not applicable | | Canada (excluding Saskatchewan) | Not applicable | | Finland | Organizations From EUR 25,000 | | France | Organizations From EUR 25,000 | | Spain (limited availability while in a pilot phase) | Organizations From EUR 3,000 | | Sweden | Organizations From EUR 25,000 (local equivalent) | | United Kingdom (including the Channel Islands and Isle of Man) | Organizations From EUR 25,000 (local equivalent) | | United States (including Puerto Rico) | Organizations From EUR 25,000 (local equivalent) | ## Verification errors The following are the common verification errors indicating missing data for higher financing amounts with Capital. Complete the corresponding remediation actions to resolve the errors. | Error | Error code | Remediation action | Remediation action code | | -------------------------------------- | ---------- | ---------------------------------------- | ----------------------- | | `ECONOMIC_SECTOR` | 2\_8203 | `provideEconomicSector` | 2\_905 | | `GLOBAL_LEGAL_ENTITY_IDENTIFIER` | 2\_8204 | `provideGlobalLegalEntityIdentifier` | 2\_909 | | `INSTITUTIONAL_SECTOR` | 2\_8225 | `provideInstitutionalSector` | 2\_910 | | `LEGAL_FORM` | 2\_8226 | `provideLegalForm` | 2\_906 | | `STATUS_OF_LEGAL_PROCEEDINGS` | 2\_8227 | `provideStatusOfLegalProceeding` | 2\_907 | | `DATE_OF_INITIATION_LEGAL_PROCEEDINGS` | 2\_8228 | `provideDateOfInitiationLegalProceeding` | 2\_908 | | `HEAD_OFFICE_INDICATOR` | 2\_8229 | `provideHeadOfficeIndicator` | 2\_911 | | `CNAE_NUMBER` | 2\_8230 | `noPossibleRemediation` | 1\_100 | ## Next steps [Get grant details](/capital/get-grant-balances) [Learn how to get information about all grants in your balance platform.](/capital/get-grant-balances) [Manage disbursements](/capital/manage-disbursements) [Learn how to get and update configurations of a disbursement.](/capital/manage-disbursements) --- # Source: https://docs.adyen.com/capital/compliance-guidelines.md Section: Capital Title: Compliance guidelines for Capital Description: Learn how to remain compliant with financial regulations when offering Capital in your marketplace or platform. --- title: "Compliance guidelines for Capital" description: "Learn how to remain compliant with financial regulations when offering Capital in your marketplace or platform." url: "https://docs.adyen.com/capital/compliance-guidelines" source_url: "https://docs.adyen.com/capital/compliance-guidelines.md" canonical: "https://docs.adyen.com/capital/compliance-guidelines" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Compliance guidelines for Capital Learn how to remain compliant with financial regulations when offering Capital in your marketplace or platform. [View source](/capital/compliance-guidelines.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. To offer Capital to users in your balance platform, you must follow Adyen's guidelines for topics like your user interface (UI), communications, and reporting. These guidelines are required for your balance platform and Adyen to remain compliant with financial regulations. Further guidance on the Compliance Guidelines is available in Adyen’s [Platform Compliance Guidelines Best Practices and Templates](/capital/compliance-financial-products/platform-compliance.pdf). Specifically, this document provides guidance on the following: * the form of materials that may be accepted to demonstrate compliance with each section of the Guidelines; * best practices for drafting policies that are required under the Guidelines; and * best practices for handling customer complaints, along with suggested templates to be used for responding to complaints. ## Overview of guidelines The table in this section shows an overview of the compliance requirements that your balance platform must meet for each topic. After your financial product offering is approved by Adyen, before publishing and distributing any new materials related to financial products, you **must** (where pre-approval of the relevant material is required under the Compliance Guidelines): 1. Submit the materials to Adyen for review and pre-approval by sending an email to **merchantkyc\@adyen.com**. 2. Update the materials to reflect any further changes requested by Adyen (if applicable). 3. Re-submit the materials to Adyen for approval (if applicable). Note that you also are required to provide materials for review: * Annually * For periodic review * Upon Adyen's request Select the links in the table for detailed guidelines for each topic. | Topic | Compliance requirements | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[User application and interface](/capital/user-interface)** | Your user application and interface must:- Not present your balance platform as a bank. - Enable your users to request Capital. - Collect KYC information and send it to Adyen. - Show and provide access to the required agreements and user terms. - Collect consent from your users. - Show and provide access to the accepted agreements and user terms. - Enable your users to view and access information regarding their Capital. | | **[Marketing and communication with users](/capital/marketing-user-communication)** | Ensure that this material:- Follows Adyen's guidelines for collateral materials. - Is approved by Adyen. - Discloses Adyen as the provider of Capital. | | **[Customer service and support](/capital/customer-service-support)** | Provide to your users:- Guidance on how to get support. - First and second lines of support. - Access to support channels. - Critical support 24/7 for specific notifications. | | **[Customer complaints](/capital/customer-complaints)** | When receiving a complaint, you must:- Acknowledge and respond to the complaint. - Escalate security, legal, and regulatory complaints to Adyen. - Submit quarterly complaint reports to Adyen. | | **[Pricing and eligibility](/capital/pricing-and-eligibility)** | You must submit the following to Adyen for approval:- The fees and/or credits for your users. - Your eligibility criteria to allow users to request Capital. | | **[Notification and reporting to Adyen](/capital/reporting-to-adyen)** | You must submit the following reports to Adyen:- Daily fraud report. - Daily card status report. - Quarterly complaint report. | | **[Keeping records](/capital/keeping-records)** | For at least five years after the termination of the financial product offering, keep copies of the following:- Customer consent to open accounts. - User interface. - Account statements. - Marketing materials and user communications. | | **[Registration as intermediary in France](/capital/french-intermediary)** | When you are registered in France and offer Capital to French users, you must:- Register as an intermediary. - Add a disclaimer on your website. - Renew your registration as an intermediary every year. | --- # Source: https://docs.adyen.com/capital/customer-complaints.md Section: Capital Title: Customer complaints and escalation Description: Learn about types of customer complaints and proper complaint handling. --- title: "Customer complaints and escalation" description: "Learn about types of customer complaints and proper complaint handling." url: "https://docs.adyen.com/capital/customer-complaints" source_url: "https://docs.adyen.com/capital/customer-complaints.md" canonical: "https://docs.adyen.com/capital/customer-complaints" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Customer complaints and escalation Learn about types of customer complaints and proper complaint handling. [View source](/capital/customer-complaints.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. Proper handling of complaints is mandatory for all platform that offer one of Adyen's financial services. *Complaints* refer to an expression of dissatisfaction about Adyen products, services, terms, communications, or actions, where a response or resolution is explicitly or implicitly expected. Even if the customer does not use the word "complaint" in their communication, if the content of the inquiry expresses dissatisfaction with Adyen products or services, the inquiry should be treated as a complaint. It is the substance of the complainant’s feedback and not the tone or format, that determines if the inquiry is a complaint. This definition is inclusive of complaints communicated in any form, written or oral, and through any channel. A complaint is not a customer service question or inquiry, either verbal or written, that includes a request to the platform for information and assistance related to a process or product. For example, the following **are not** complaints: * Requests to change an address. * Inquiries regarding account details. * Questions about a product's availability in specific locations or requests for general information. * Questions related to technical assistance (such as error messages) or issues interacting with Adyen's platform or a third-party platform integrated with Adyen's services. * Requests for a refund of fees or a chargeback. However, if any customer request concerning any of the above matters alleges unfair treatment or expresses dissatisfaction, this should be treated as a complaint. ## Complaint handling process The platform must operate a complaints handling process that includes the following features. ### Access to support Provide users with an easily identifiable and accessible way to submit support inquiries. ### Complaint identification Identify complaints that are received through all available customer support channels. The platform can require complaints to be submitted through a complaints form. A link to this form should be provided in customer support channels where a user has raised a complaint. * **Guidance on complaint handling**. Provide clear guidance and information to users on how the platform will work to resolve complaints. This includes: * The platform's acknowledgement of the complaint (within the timelines listed under complaint resolution timelines). * Communicating the ultimate deadline for resolving the complaint (within the timelines listed under complaint resolution timelines). * Providing regular updates on the investigation of the complaint. If the complaint has not been resolved within the specified timelines, the platform must notify the customer of the anticipated timeframe for resolving the complaint. * The platform must investigate the Complaint and take all actions deemed necessary to address the complaint in a timely manner, in accordance with the timelines as outlined under complaint resolution timelines. * For any regulatory and legal complaints, Adyen will be involved in the resolution and work with the platform. * **Complaint resolution timelines**. Adyen expects the platform to: * Acknowledge all user complaints within 5 business days. * Resolve them within 10 business days from the complaint submission date. * Notify users if complaints will take longer than 10 business days to resolve. ### Recordkeeping The platform must maintain records relating to all support inquiries (and complaints) responses for five years from the date of the termination of the Adyen Service and the user's account closure, unless the platform’s own data retention requirements stipulate a longer time period. Such records must be maintained in a durable and accessible format, for example, in the form of a log. ## When to escalate a complaint to Adyen There are several categories of complaints relevant to Adyen’s services that the platform may encounter being in the first and second line support for the user. | Category of compliants | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | General complaints | Operational complaints related to customer service, product functionality, account management, transactions. | | Security complaints | Complaints from the user related, but not limited to:- Fraud - Identity theft - Criminal activity, such as robbery or theft - Unauthorized access to a customer’s information - Account takeover | | Regulatory and legal complaints | Complaints that involve legal or regulatory matters. | Security and Regulatory/Legal complaints must be reported to Adyen within one to two working days. Adyen will then work with a platform to resolve the complaint. The platform is required to forward user complaints to Adyen so Adyen can assist the platform with preparing the response in the following situations: * The platform has received and acknowledged the complaint and is unable to substantively resolve the issue without Adyen's input. * Adyen has a responsibility to handle and resolve the complaint in accordance with the criteria outlined for each type of compliant in the following table. ## Types of complaints to escalate | Type of complaint | Example | Who responds to the user | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Legal** | * Legal action addressed to Adyen, for example, court or official documentation where Adyen is a defendant. * Complaint accompanying threat of legal action, for example, complaint submitted alongside court documentation. * Complaint about official court orders, for example, seizure order or other court orders. | **Adyen** responds to legal actions directly. The **platform** handles the complaint aspect and resolution unless Adyen's input is required for a substantive response. | | **Data Privacy** | - Official court orders against the customer, for example, seizure order or subpoena addressed to Adyen. - Breach of GDPR/UK GDPR, for example, mishandled data, shared data, or requests for access/deletion. - Threat to refer Adyen to a regulator or court for breaching privacy rules. | **Adyen** (responds to the user, Court/FIU, or regulator directly). | | **Regulatory** | * Complaint accompanying regulatory referral (complaint to be considered alongside the referral). * Regulatory referral, for example, customer indicates they will refer Adyen to a regulator/ombudsman. | **Adyen** responds to the regulator/ombudsman. The **platform** handles resolution unless Adyen's input is required for a substantive response. | | **Financial Crime** | - Victim of a financial crime (relevant for bank accounts/cards for refunding/blocking, or chargebacks). - Blocked funds, for example, customer states they are unable to access funds or account has been blocked. | The **platform** performs handling and resolution. | | **Technical Issues** | * Issues caused by an Adyen API or component that requires technical support. | The **platform** performs handling and resolution. | ## Escalation procedure 1. Provide the information as soon as possible, but no later than two business days after the complaint is received. 2. Adyen will forward the complaint to the relevant team based on the criteria in the table. 3. If Adyen needs further information from the platform to prepare a response, the platform must provide a response when Adyen within two business days. 4. Once Adyen has prepared the final response, this will be sent to the platform, and the platform must provide this response to the user in line with the complaints handling timelines in the Compliance Guidelines. ## For Customers in the UK & Ireland ### Receipt and acknowledgement The platform’s complaints resolution process must contain the following additional elements: * Within 5 working days of the platform concluding its investigation of the complaint, the platform must notify the user of * The decision in relation to the complaint (including the reasons for the decision). * If applicable, the terms of any offer or settlement made. * That the user may be entitled to refer their complaint to the relevant ombudsman if they are not satisfied with the platform’s conclusion; and again provide the above contact details of the relevant ombudsman. * The platform’s acknowledgement of the complaint must state that the user may be entitled to raise the complaint with the relevant financial ombudsman in the user’s jurisdiction (in Ireland, the Financial Services and Pensions Ombudsman and in the UK, the Financial Ombudsman Service) where the user is not satisfied with the platform’s or Adyen’s final response to the complaint or the complaint has not been resolved within 15 working days. * The platform must provide the user making the complaint with a point of contact in relation to the complaint. * The acknowledgement should also include the contact details of the relevant ombudsman, as follows: **Ireland**\ *Address: Lincoln House, Lincoln Place, Dublin 2, D02 VH29.\ Phone: +353 1 567 7000\ Email: info\@fspo.ie* **UK**\ *Website: \ Online complaint form: \ Mail: The Financial Ombudsman Service Exchange Tower, London, E14 9SR\ Phone: 0800 023 4 567 (free), 0300 123 9 123, weekdays from 8:00am–5:00pm (GMT). If you are not located in the UK, call +44 20 7964 0500.\ You have 6 months to make a complaint after we send you a final response.* ### Resolution The platform must provide the user making the complaint with regular updates on the investigation of the complaint, at intervals of maximum 15 business days (starting on the date the complaint was received). Where the complaint has not been resolved within 35 working days, the platform must notify the user of the anticipated timeframe for resolving the complaint and that the customer may be entitled to refer the complaint to the relevant ombudsman (providing again the above contact details for the relevant ombudsman). ### Escalation If Adyen receives any complaint directly from BACS and requires your platform to provide any information for Adyen to respond to the complaint, your platform must provide this within two business days. Adyen does not consider that any complaints about the payment services made available to users should be forwarded to Adyen under the DISP 1.7 complaints and forwarding rules. ## See also * [Customer service and support](/capital/customer-service-support) * [Notification and reporting to Adyen](/capital/reporting-to-adyen) * [Overview of compliance guidelines](/capital/compliance-guidelines) --- # Source: https://docs.adyen.com/capital/customer-service-support.md Section: Capital Title: Customer service and support Description: Learn about the compliance guidelines you need to follow when offering support to your users. --- title: "Customer service and support" description: "Learn about the compliance guidelines you need to follow when offering support to your users." url: "https://docs.adyen.com/capital/customer-service-support" source_url: "https://docs.adyen.com/capital/customer-service-support.md" canonical: "https://docs.adyen.com/capital/customer-service-support" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Customer service and support Learn about the compliance guidelines you need to follow when offering support to your users. [View source](/capital/customer-service-support.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. The platform is responsible for providing first and second line support to customers. The platform must provide a way for customers to submit support requests and provide resolution support. The platform also serves as Adyen’s point of contact for any communications from customers. ## Customer service essentials The following table outlines the responsibilities of the platform when providing support to customers. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Support teams** | The platform is responsible for the following:- Provide first line support: A general help desk that takes more information, offers simple solutions, and determines if an issue requires escalation to someone with more expertise. - Provide second line support: A team with more technical knowledge who can assist with more complex issues. - Ensure that both the first and the second line support services work effectively: * Customer helplines shall be sufficiently resourced and capable of dealing with unexpected surges in demand of customer support. * Tickets shall be prioritized based on the severity of the issue, ensuring a timely response. * Where relevant, customers shall be provided with a unique case number for their support query. The status of a support query shall be clear for a customer at all times. * In case of expected delays in response (for example, due to an unexpected surge in customer support queries), customers must be informed accordingly. * The information provided by a user needs to be registered properly, allowing for central access by subsequent customer service advisors. | | **Support guidance** | The platform must provide its customers with clear guidance and information on how to receive support:- Guidance should allow customers to easily find key information, with clear signposting to the platform's customer support channels. - Phone system, menus, webpages or web chats must be easy to navigate. | | **Support channels** | The platform must have multiple support channels available and communicate these channels clearly towards their customers:- Support needs to be offered by multiple channels, allowing for live-support (for example, phone, emails, social media channels, video call, in-office support, call-back service), in accordance with the needs of their user base. - If support is offered digitally or though a chatbot, human touch points are required wherever complex needs are identified or if so requested by a merchant. - A reasonable level of support must be provided through channels in the event of an issue arising with their services (for example, IT outage, temporary works or a cyber-attack). - The platform's support channel cannot include any sludge practices or barriers, hindering the ability of customers to raise a support query or file a complaint. - Support channels must be available and free of charge, regardless of the channel used to provide support. | | **Critical support** | The platform must enable 24/7 ability to raise any query or notification by customers about (possible) unauthorized use, fraud, loss or theft of personal security credentials and/or card. | | **Training** | The platform should properly train and equip their front-line staff to deliver good customer support, including training to identify risks of vulnerability. See [Considerations for vulnerable customers](#vulnerable) below for more information. | | **Monitoring** | The platform are required to monitor and assess the quality of support they provide to ensure that customers receive the support they need, and to limit the risk of systematic issues that create unreasonable barriers or costs for customers. | | **Record-keeping** | The platform are requested to maintain records relating to all support queries and responses thereto for five years from the date of the termination of the Adyen Service and the user's account closure, unless the platform's own data retention requirements stipulate a longer time period. | ## Considerations for vulnerable customers (UK and Ireland) Adyen requires platforms to ensure that any customers in vulnerable circumstances receive reasonable assistance and support that they require to engage with Adyen’s financial services. Vulnerable customers are *"customers who, due to their personal circumstances, are especially susceptible to harm, particularly when a firm is not acting with appropriate levels of care"*. Adyen is required to ensure that platforms receive appropriate training for dealing with vulnerable customers. This is to ensure that necessary staff within platforms can understand and recognise vulnerable customers and respond to their needs. For further information refer to [Identifying vulnerable users](/capital/compliance-financial-products/vulnerable-users#identifying-vulnerable-users). The platform must ensure that this information is provided to and understood by all staff members specified. In addition to the general requirements outlined above, customer service and support systems should also incorporate the following requirements to ensure that necessary assistance is provided to vulnerable user: * Communication systems should enable and encourage customers to specify if they have particular needs or require special assistance, and to share/update information in their own time and at their own pace. This should be done with a popup or other prominent notice on the platform's user interface, stating that customers should contact the platform if they require any special assistance. The notice must contain a link, phone number, and email address for the standard support channels. * Digital channels should be complemented with human touchpoints wherever this need is identified. * Customer support channels and information relevant to these should be compatible with assistive technologies such as text-to-speech applications. --- # Source: https://docs.adyen.com/capital/download-offers.md Section: Capital Title: Download financing offers for eligible users Description: Learn how to download a list of offers for all eligible users in your balance platform. --- title: "Download financing offers for eligible users" description: "Learn how to download a list of offers for all eligible users in your balance platform." url: "https://docs.adyen.com/capital/download-offers" source_url: "https://docs.adyen.com/capital/download-offers.md" canonical: "https://docs.adyen.com/capital/download-offers" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Download financing offers for eligible users Learn how to download a list of offers for all eligible users in your balance platform. [View source](/capital/download-offers.md) You can get financing offers for all eligible users across the entire balance platform. Adyen provides this information in a CSV format, making it easy to analyze and utilize. For example, you can use this data to launch marketing campaigns that promote business financing. Each offer is personalized for the account holder based on their processing history and has its own expiration date. The CSV file contains the minimum and the maximum grant amount each account holder is eligible for. The actual offer will fall within this specified range, but the exact amount may vary. Offer data is generated automatically each day at midnight Central European Time (CET). Account holders with an active grant may still receive new offers in this list. Consider filtering the list before scheduling marketing campaigns if necessary. If an account holder is not listed, no active offers are currently available for them. This page explains how to download a list of financing offers through your Customer Area. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration. | | **Customer Area roles** | Make sure that you have the following [user role](/account/user-roles):- **Capital base role** | | **Limitations** | * Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). * The offer remains valid for seven days. After this period, a new offer is generated for an account holder if they still meet the qualification criteria. The offer amount may differ from one offer to another. | | **Setup steps** | Before you begin, ensure compliance with our [guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. | ## Download financing offers for all eligible users To get financing offers for all eligible users in your [Customer Area](https://ca-test.adyen.com/), for the selected balance platform: 1. Go to **Financial products** > **Capital**. 2. Select **Download Capital Offers CSV** from the banner at the top of the page. This will generate and download a list of account holders eligible for business financing, including their offer details, to your local file storage. ### Sample [Download a sample eligible offer list](/capital/download-offers/SAMPLE_TestBalancePlatform_EligibleCapitalOffers_2025-10-07.csv) for examples of the included data. Your downloaded file name should be similar to this: `BalancePlatformName_EligibleCapitalOffers_YYYY_MM_DD.csv`. Here is an example of what the list looks like. | Balance Platform name | Account holder ID | Min amount | Max amount | Currency | Start date (CEST | Expiry Date (CEST | | --------------------- | ------------------------- | ---------- | ---------- | -------- | ----------------------------- | ----------------------------- | | TestBalancePlatform | AH00000000000000000000001 | 1.00 | 6083.14 | NOK | 2025-10-05T22:42:44.6+02:00 | 2025-10-12T22:42:44.6+02:00 | | TestBalancePlatform | AH00000000000000000000002 | 1.00 | 2600.11 | EUR | 2025-10-05T22:42:44.517+02:00 | 2025-10-12T22:42:44.517+02:00 | | TestBalancePlatform | AH00000000000000000000003 | 1.00 | 8668.44 | GPB | 2025-10-05T22:42:46.255+02:00 | 2025-10-12T22:42:46.255+02:00 | ### Data structure If you need to upload the CSV data to any other application for future analysis, here is how you should interpret the columns and their data types. | # | Column | Data type | Description | | - | --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Balance Platform name | Unicode Text | The name of your Balance Platform account. | | 2 | Account holder ID | Unicode Text | The unique identifier of the account holder. | | 3 | Min amount | String | The minimum grant amount the account holder is eligible for, expressed in major units. | | 4 | Max amount | String | The maximum grant amount the account holder is eligible for, expressed in major units. | | 5 | Currency | Alpha Text (3-character limit) | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) for the offer. | | 6 | Start date | Date field + Time field + Timezone | The timestamp indicating the start date and time of the offer's validity, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. | | 7 | Expiry date | Date field + Time field + Timezone | The timestamp indicating the end date and time of the offer's validity, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. | ## See also * [Get offers through the API](/capital/get-grant-offers/) --- # Source: https://docs.adyen.com/capital/french-intermediary.md Section: Capital Title: Registration as an intermediary in France Description: To be allowed to offer Capital in France, register as an intermediary with ORIAS. --- title: "Registration as an intermediary in France" description: "To be allowed to offer Capital in France, register as an intermediary with ORIAS." url: "https://docs.adyen.com/capital/french-intermediary" source_url: "https://docs.adyen.com/capital/french-intermediary.md" canonical: "https://docs.adyen.com/capital/french-intermediary" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Registration as an intermediary in France To be allowed to offer Capital in France, register as an intermediary with ORIAS. [View source](/capital/french-intermediary.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. The French Monetary and Financial Code (CMF) regards your platform as an **intermediary** if the following is true: * You offer Adyen Capital to French users.\ **and** * Your platform is incorporated and registered in France. In France, intermediation is a regulated activity that requires you to register with [ORIAS](https://www.orias.fr), the organization that is in charge of the French registry of intermediaries in insurance, banking, and finance. ## Requirements Before you begin, take into account the following requirements and limitations. | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | | **Integration type** | An [Adyen for Platforms](/adyen-for-platforms-model/) integration offering financial products. | | **Limitations** | Only applies when registered in France and offering financial products to French users. | ## Proof of professional capacity When you register with ORIAS, you are required to provide proof of professional capacity of at least one of your organization's directors. The director's proof of professional capacity must show experience, a diploma, or training relevant for the financial products to be offered. This proof can be either of the following: * A certificate of employment showing at least six months of experience in the past two years with providing similar financial products. * A relevant diploma. This can be: * A diploma under the Répertoire National des Certifications Professionnelles (RNCP) category NSF 122, 128, 313, or 314, levels 7 to 5. * A diploma from a business school registered with the French Ministry of Education. * A similar foreign diploma officially recognized by [France Education International](https://www.france-education-international.fr). * A certificate from an [approved training organization](https://www.data.gouv.fr/fr/datasets/liste-publique-des-organismes-de-formation-l-6351-7-1-du-code-du-travail/) showing at least 20 hours of training in the financial products to be offered. The director should not be subject to: * The convictions mentioned in Article L500-1 of the CMF: convictions for a felony, a sentence of imprisonment, or a suspended imprisonment of six months or more for certain listed offences. * Disciplinary sanctions no. 3 or 7 mentioned in Article L612-41 of the CMF: a prohibition to carry out certain intermediation operations and any other limitations in the exercise of this activity, or a prohibition of intermediation activities. ## Register as an intermediary To be allowed to offer Adyen Capital, you have to register with ORIAS as a: * **Level I IOBSP intermediary** if your Nomenclature des Activités Françaises (NAF) code is [NAF 64.19 Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/64.19Z) or [NAF 64.92 Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/64.92z) * **Level II IOBSP intermediary** if your NAF code is [NAF 66.22Z](https://www.insee.fr/fr/metadonnees/nafr2/sousClasse/66.22Z) or [NAF 66.19.99](https://www.insee.fr/fr/metadonnees/cpfr21/sousCategorie/66.19.99). * **Level III IOBSP intermediary** if the above NAF codes do not apply. It usually takes less than two months for ORIAS to validate and accept your registration. After your initial registration as an intermediary, you must renew your registration every year before it expires. 1. Gather the following documents (in PDF, JPG, or PNG format), which you will need to upload to ORIAS in a later step: * Proof of registration with the French Chamber of Commerce. This is referred to as a **kbis extract**. The extract must be less than three months old. * [Proof of professional capacity](#professional-capacity) of at least one of your organization's directors. 2. If you do not have an ORIAS account yet, create an account on the [ORIAS website](https://www.orias.fr/public/enregistrement/index), selecting **Personne morale** and providing the details of one of your organization's directors. 3. Log in to your ORIAS account and proceed as follows: 1. Select the category **Activité IOB** and the subcategory **Mandataire non-exclusif en opérations de banque et en services de paiement**. 2. Select the following: * **Je déclare que l'on ne me confie pas de fonds** to indicate that no funds are entrusted to you. * **Accessoire** to indicate that offering Capital is not your organization's primary activity. * **Oui**. 3. Provide the kbis extract and the proof of professional capacity of one of your organization's directors. 4. Provide Adyen with your SIREN number and legal name so that Adyen can issue your **Attestation de Mandat** (mandate) and send it to you.\ You can resume the registration process on the ORIAS website when you have received the mandate. 5. Upload your **Attestation de Mandat** to ORIAS. 6. Pay the fees. For questions about the registration you can contact ORIAS directly at . 4. When you receive a confirmation by email that ORIAS has approved your registration, add the following disclaimer on the website where you offer Adyen Capital: \[YOUR ORGANIZATION], société immatriculée au R.C.S de \[XXXX] sous le numéro \[XXXXX], et inscrit au Registre unique des Intermédiaires en Assurance, Banque et Finance sous le numéro d’immatriculation \[XXXXX] en qualité de Mandataire non exclusif en opérations de banque et en services de paiement. Do not forget to renew your registration every year. ## See also * [Compliance guidelines for Capital](/capital/compliance-guidelines) --- # Source: https://docs.adyen.com/capital/get-grant-balances.md Section: Capital Title: Get grant details Description: Learn how to get information about all grants in your balance platform. --- title: "Get grant details" description: "Learn how to get information about all grants in your balance platform." url: "https://docs.adyen.com/capital/get-grant-balances" source_url: "https://docs.adyen.com/capital/get-grant-balances.md" canonical: "https://docs.adyen.com/capital/get-grant-balances" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Get grant details Learn how to get information about all grants in your balance platform. [View source](/capital/get-grant-balances.md) After you successfully create a grant, you can get the details of these grants by making API requests. These details include, for example, the grant balances, repayment configuration, and status. You can use this information to: * Show your user the details of their grant. * Track whether your user is repaying their grant. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an Adyen for Platforms integration with the Capital financial product enabled. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capabilities](/capital/manage-user-capabilities):- **getGrantOffers** - **receiveGrants** | | **Limitations** | Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). | | **Setup steps** | Before you begin, make sure:- You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). - You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. - Your user [selected a grant offer](/capital/get-grant-offers) and [signed the Terms of Service](/capital/terms-of-service). - You [disbursed at least one grant](/capital/make-grant-request). | ## Get all grants of an account holder You can get the details of all the grants given to a specific account holder. To do so: 1. Make a GET [/grants](https://docs.adyen.com/api-explorer/capital/latest/get/grants) request with the receiving [counterpartyAccountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/grants#query-counterpartyAccountHolderId) as a query parameter. **Get all grant references of an account holder** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants?counterpartyAccountHolderId=AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` 2. In the response, note the `grants` array, which includes an object for each grant associated to the account holder. Each object includes the following parameters: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-id) | The identifier of the grant reference. | | [grantAccountId](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-grantAccountId) | The identifier of the grant account used to account for the grant. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-grantOfferId) | The identifier of the grant offer that has been selected by the receiving account holder. | | [counterparty](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-counterparty) | An object containing the details of the receiving account holder. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-amount) | An object containing the amount of the grant, in [minor units](/development-resources/currency-codes). | | [fee](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-fee) | An object containing the fee amount. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-repayment) | An object containing the repayment amount, in [basis points](https://en.wikipedia.org/wiki/Basis_point). | | [balances](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-balances) | An object containing the details of the existing grant. | | [status](https://docs.adyen.com/api-explorer/capital/latest/get/grants#responses-200-grants-status) | The status of the grant. | **Response** ```json { "grants": [ { "id": "GR322XC22322625HQ7NCX2FWJ", "amount": { "currency": "EUR", "value": 310534 }, "counterparty": { "accountHolderId": "AH322XC22349655HQ7NCSFJMQ", "balanceAccountId": "BA322XC22349655HQ7NCSFJNV" }, "fee": { "amount": { "currency": "EUR", "value": 31053 } }, "grantAccountId": "CG322LZ223222B5F6SFQWBANK", "repayment": { "basisPoints": 500 }, "balances": { "currency": "EUR", "fee": 31053, "principal": 310534, "total": 341587 }, "status": "Active" }, { "id": "GR322XC39137294KQ1NCX4MWR", "amount": { "currency": "EUR", "value": 31053 }, "counterparty": { "accountHolderId": "AH322XC22349655HQ7NCSFJMQ", "balanceAccountId": "BA322XC22349655HQ7NCSFJNV" }, "fee": { "amount": { "currency": "EUR", "value": 3105 } }, "grantAccountId": "CG322LZ223222B5F6SFQWBANK", "repayment": { "basisPoints": 500 }, "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "status": "Repaid" } ] } ``` ## Get details of a specific grant To get the balance of a specific grant: 1. Make a GET [/grants/{grantId}](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)) request with the receiving [grantId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#path-grantId) as a query parameter. **Get the balances of a grant** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants/GR00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. In the response, note the following parameters: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-id) | The identifier of the grant reference. | | [grantAccountId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-grantAccountId) | The identifier of the grant account used to account for the grant. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-grantOfferId) | The identifier of the grant offer that has been selected by the receiving account holder. | | [counterparty](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-counterparty) | An object containing the details of the receiving account holder. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-amount) | An object containing the amount of the grant, in [minor units](/development-resources/currency-codes). | | [fee](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-fee) | An object containing the fee amount. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-repayment) | An object containing the repayment amount, in [basis points](https://en.wikipedia.org/wiki/Basis_point). | | [balances](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-balances) | An object containing the details of the existing grant. | | [status](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-status) | The status of the grant. | **Response** ```json { "id": "GR00000000000000000000001", "grantAccountId": "CG00000000000000000000001", "grantOfferId": "00000000001", "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "amount": { "currency": "EUR", "value": 1000000 }, "fee" : { "amount" : { "value" : 120000, "currency" : "EUR" } }, "repayment": { "basisPoints": 1400 }, "balances": { "principal": 1000000, "fee": 120000, "total": 1120000, "currency": "EUR" }, "status": "Active" } ``` ## Get details of your grant account The balances of all grants in your balance platform are tracked by your grant account. To get the details of your grant account: 1. Make a GET [/grantAccounts/{id}](https://docs.adyen.com/api-explorer/capital/latest/get/grantAccounts/\(id\)) request with the receiving [id](https://docs.adyen.com/api-explorer/capital/latest/get/grantAccounts/\(id\)#path-id) as a query parameter. **Get the balances of all grants** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grantAccounts/CG00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ -d '' ``` 2. In the response, note the following parameters: | Parameter | Description | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/capital/latest/get/grantAccounts/\(id\)#responses-200-id) | The unique identifier of the grant account. | | [balances](https://docs.adyen.com/api-explorer/capital/latest/get/grantAccounts/\(id\)#responses-200-balances) | An object containing the details of all the existing grant(s) on your platform's grant account. | | [limits](https://docs.adyen.com/api-explorer/capital/latest/get/grantAccounts/\(id\)#responses-200-limits) | An object containing the details about the maximum allowed total amount for all grants on this grant account. | **Response** ```json { "balances": [ { "currency": "EUR", "fee": 120000, "principal": 1000000, "total": 1120000 } ], "id": "CG00000000000000000000001", "limits": [ { "amount": { "currency": "EUR", "value": -100000000 } }, { "amount": { "currency": "USD", "value": -100000000 } }, { "amount": { "currency": "GBP", "value": -100000000 } } ] } ``` ## See also * [Grant lifecycle and status](/capital/grant-lifecycle-and-status) * [Manage disbursements](/capital/manage-disbursements) --- # Source: https://docs.adyen.com/capital/get-grant-offers.md Section: Capital Title: Get financing offers Description: Get personalized financing offers that you can present to your users. --- title: "Get financing offers" description: "Get personalized financing offers that you can present to your users." url: "https://docs.adyen.com/capital/get-grant-offers" source_url: "https://docs.adyen.com/capital/get-grant-offers.md" canonical: "https://docs.adyen.com/capital/get-grant-offers" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Get financing offers Get personalized financing offers that you can present to your users. [View source](/capital/get-grant-offers.md) **Limited availability**\ Variable repayment terms (90, 180, and 360 days) for financing offers are currently in a pilot phase. To request access, reach out to your Adyen contact. *** Adyen conducts a proactive risk assessment for each user based on their processed payment volume before offering business financing. This process results in personalized financing offers. When integrating Capital into your platform, you can choose how to get and present financing offers in your user interface (UI). Select the option that best fits your needs and refer to the relevant implementation guide. * **Dynamic financing offers**: Allow users to select a financing amount within a specified range. Based on their processing history, users may receive up to three dynamic offers, with one offer created for each available repayment term: 90, 180, and 360 days. You can use data from dynamic offers, for example, to implement a slider for selecting the financing amount and a dropdown or buttons for selecting the repayment term. * **Static financing offers**: Present users with a list of fixed financing amounts. Based on their processing history, users may receive up to nine offers, with three offers created for each available repayment term: 90, 180, and 360 days. You can use data from static offers, for example, to implement a dropdown or buttons for selecting predefined amount-term combinations. *Example*\ Suppose a user qualifies for up to EUR 25,000 with 90- and 180-day repayment terms. * With dynamic offers, they receive two offers with the amount ranges: from EUR 500 to EUR 12,800 for 90 days and from EUR 500 to EUR 25,000 for 180 days.\ The user selects a repayment term and any amount within the applicable range. This provides flexibility, though the maximum amount depends on the chosen term. * With static offers, they receive six offers with the fixed amounts: EUR 6,784, EUR 10,240, and EUR 12,800 for 90 days, as well as EUR 13,250, EUR 20,000, and EUR 25,000 for 180 days.\ The user selects from predefined amount-term combinations and cannot request an amount in between. ## Next steps [Get dynamic offers](/capital/get-grant-offers/dynamic-offers/) [Learn how to get dynamic offers with flexible financing amounts and repayment terms for your users.](/capital/get-grant-offers/dynamic-offers/) [Get static offers](/capital/get-grant-offers/static-offers/) [Learn how to get static offers with fixed financing amounts and repayment terms for your users.](/capital/get-grant-offers/static-offers/) --- # Source: https://docs.adyen.com/capital/get-grant-offers/dynamic-offers.md Section: Capital Title: Dynamic financing offers Description: Learn how to get dynamic offers with flexible financing amounts and repayment terms. --- title: "Dynamic financing offers" description: "Learn how to get dynamic offers with flexible financing amounts and repayment terms." url: "https://docs.adyen.com/capital/get-grant-offers/dynamic-offers" source_url: "https://docs.adyen.com/capital/get-grant-offers/dynamic-offers.md" canonical: "https://docs.adyen.com/capital/get-grant-offers/dynamic-offers" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Dynamic financing offers Learn how to get dynamic offers with flexible financing amounts and repayment terms. [View source](/capital/get-grant-offers/dynamic-offers.md) **Limited availability**\ Variable repayment terms (90, 180, and 360 days) for financing offers are currently in a pilot phase. To request access, reach out to your Adyen contact. *** Adyen provides increased flexibility by supporting dynamic financing offers through the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Rather than presenting a list of fixed amounts, dynamic offers allow users to choose a preferred amount from a specified range. Based on their processing history, users may receive up to three dynamic offers with repayment terms of 90, 180, and 360 days. Higher amounts are typically available with longer terms. You can use data from dynamic offers, for example, to implement a slider in your user interface (UI) that lets users select their financing amount. Additionally, you can offer a dropdown or buttons for repayment term selection. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an Adyen for Platforms integration that supports Capital. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capability](/capital/manage-user-capabilities):- **getGrantOffers** | | **Limitations** | * Requests to the following endpoints are subject to rate limits in both Test and Live environments: * [/dynamicOffers/{dynamicOfferId}/calculate](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate): **120 requests per minute** * [/dynamicOffers/{dynamicOfferId}/grantOffer](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer): **30 requests per minute** * The amount a user selects on your UI must be within the range available to this user. However, you can set a custom logic for amount increments within the range. For example, you can specify steps of EUR 100 or EUR 500. * Each financing offer remains valid for seven days. After this period, a new offer is generated for an account holder if they still meet the qualification criteria. The range may differ from one offer to another. | | **Setup steps** | Before you begin, make sure:* You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. * You built a user interface that allows users to select their preferred financing amount from a range. | ## How it works The process to get a financing offer through the dynamic offers flow is as follows: 1. Make an API request to [get the range of available financing](#get-financing-range) for a specific account holder. The API may return up to three dynamic offers, each with a different range and repayment term. Use the data from the API response to present offers in your UI. 2. After the user selects an amount and repayment term, make an API request to [calculate a preliminary offer](#preliminary-offer). This returns an initial breakdown of costs and conditions for the selected amount. 3. When the user confirms their selection, make an API request to [create a static offer](#static-offer). This action generates a legally binding offer with a final breakdown of costs and conditions. 4. Get updates when a new offer is created for your account holder. The following sections provide more details about each step of integrating dynamic financing offers. ## 1. Get the range of available financing To get the financing range available for a specific user: 1. Make a GET [/dynamicOffers](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers) request including the following query parameters: | Parameter | Type | Required | Description | | ------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#query-accountHolderId) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of that the dynamic offer is for. | | [financingType](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#query-financingType) | String | | The type of financing that the offer is for. Currently, only **businessFinancing** is supported. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required The following code sample shows how to get the range of available financing for the account holder ID **AH00000000000000000000001**. **Get available financing range** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/dynamicOffers?accountHolderId=AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. The API can return up to three dynamic offers, each with a different range and repayment term. In the response, review the [dynamicOffers](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers) object, which contains the following parameters for each dynamic offer returned. You can use this data to, for example, implement a slider in your UI, allowing users to choose their financing amount, and provide a dropdown or selector for repayment terms. | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-accountHolderId)\` | The unique identifier of the account holder that the dynamic offer is for. | | [contractType](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-contractType) | The legal type of the offer. Possible values: **loan**, **cashAdvance**. | | [expiresAt](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-expiresAt) | The expiration date and time of the offer validity period. | | [financingType](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-financingType) | The type of financing that the offer is for. Currently, only **businessFinancing** is supported. | | [id](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-id) | The unique identifier of the dynamic financing offer. | | [maximumAmount](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-maximumAmount) | An object containing the maximum amount of the financing offer, including both the value and the currency. | | [minimumAmount](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-minimumAmount) | An object containing the minimum amount of the financing offer, including both the value and the currency. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-repayment) | An object containing the details of the repayment configuration. | | [repayment.term.estimatedDays](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-repayment-term-estimatedDays) | The estimated period for repaying the grant, in days. | | [repayment.term.maximumDays](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-repayment-term-maximumDays) | The maximum period for repaying the grant, in days. | | [startsAt](https://docs.adyen.com/api-explorer/capital/latest/get/dynamicOffers#responses-200-dynamicOffers-startsAt) | The starting date and time of the offer validity period. | **Available financing range received** ```json { "dynamicOffers": [ { "id": "0000000000000001", "repayment": { "term": { "estimatedDays": 180, "maximumDays": 270 } }, "accountHolderId": "AH00000000000000000000001", "contractType": "loan", "startsAt": "2026-01-08T23:00:00Z", "expiresAt": "2026-01-15T23:00:00Z", "financingType": "businessFinancing", "maximumAmount": { "value": 2500000, "currency": "EUR" }, "minimumAmount": { "value": 50000, "currency": "EUR" } }, { "id": "0000000000000002", "repayment": { "term": { "estimatedDays": 90, "maximumDays": 120 } }, "accountHolderId": "AH00000000000000000000001", "contractType": "loan", "startsAt": "2026-01-08T23:00:00Z", "expiresAt": "2026-01-15T23:00:00Z", "financingType": "businessFinancing", "maximumAmount": { "value": 1280000, "currency": "EUR" }, "minimumAmount": { "value": 50000, "currency": "EUR" } } ] } ``` ## 2. Calculate a preliminary offer for a selected amount and term When a user selects an amount and repayment term in your UI, you must show preliminary terms and conditions for the offer. This includes a selected amount, a daily repayment in basis points, a threshold amount, applicable fees, an estimated and a maximum repayment term, and an offer validity period. The preliminary offer is for informational purposes only and cannot be used to initiate a grant. To calculate a preliminary offer for selected amount and term: 1. Make a POST [/dynamicOffers/{dynamicOfferId}/calculate](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate) request. In the path, include the [id](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#path-id) of the dynamic offer that the user made a selection from. Requests to this endpoint are subject to rate limits. All requests to the endpoint, including those that result in failure, count toward the specified limit. * Test environment: **120 requests per minute** * Live environment: **120 requests per minute** 2. Additionally, specify the following parameters in your request body: | Parameter | Type | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [amount.currency](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#request-amount-currency) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](/development-resources/currency-codes). This value must match the currency of the dynamic offer. | | [amount.value](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#request-amount-value) | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The financing amount that the user selected, in [minor units](/development-resources/currency-codes). The amount be within the range of the corresponding dynamic offer. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required **Calculate a preliminary offer for the selected amount** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/dynamicOffers/00000000000000001/calculate \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 250000, "currency": "EUR" } }' ``` In the response, note the parameters in the following table: | Parameter | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-accountHolderId) | The unique identifier of the account holder that the dynamic offer is for. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-amount) | An object containing offer currency and value, in [minor units](/development-resources/currency-codes). | | [contractType](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-contractType) | The contract type of the offer. | | [expiresAt](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-expiresAt) | The expiration date and time of the offer validity period. | | [fee](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-fee) | An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-repayment) | An object containing the details of the repayment configuration. | | [repayment.basisPoints](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-repayment-basisPoints) | The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. | | [repayment.term.estimatedDays](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-repayment-term-estimatedDays) | The estimated period for repaying the grant, in days. | | [repayment.term.maximumDays](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-repayment-term-maximumDays) | The maximum period for repaying the grant, in days. | | [repayment.threshold.amount](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-repayment-threshold-amount) | An object containing the details of the minimum threshold amount that your user must repay every 30-day period. | | [startsAt](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/calculate#responses-200-startsAt) | The starting date and time of the offer validity period. | **Preliminary offer calculated** ```json { "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": 250000 }, "contractType": "loan", "expiresAt": "2026-01-15T23:00:00Z", "fee": { "amount": { "currency": "EUR", "value": 95000 } }, "repayment": { "basisPoints": 750, "term": { "estimatedDays": 90, "maximumDays": 120 }, "threshold": { "amount": { "currency": "EUR", "value": 38330 } } }, "startsAt": "2026-01-08T23:00:00Z" } ``` ## 3. Create a static offer for a selected amount and term After the user selects a final amount and repayment term from the dynamic offer, use this data to create a static offer with definitive terms and conditions. This includes a fixed amount, a daily repayment in basis points, a threshold amount, applicable fees, an estimated and a maximum repayment term, and an offer validity period. This is a formal, legally binding offer that must be provided for the user's review in your UI to comply with the [user interface requirements](/capital/user-interface) for Capital. To create a static offer for the selected amount and term: 1. Make a POST [/dynamicOffers/{dynamicOfferId}/grantOffer](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer) request. In the path, include the [id](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#path-id) of the dynamic offer that the user made their final selection from. Requests to this endpoint are subject to rate limits. All requests to the endpoint, including those that result in failure, count toward the specified limit. * Test environment: **30 requests per minute** * Live environment: **30 requests per minute** 2. Additionally, specify the following parameters in your request body: | Parameter | Type | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [amount.currency](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#request-amount-currency) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](/development-resources/currency-codes). This value must match the currency of the dynamic offer. | | [amount.value](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#request-amount-valu) | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The final financing amount that the user selected, in [minor units](/development-resources/currency-codes). The amount be within the range of the corresponding dynamic offer. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required **Create a static offer for the selected amount** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/dynamicOffers/00000000000000001/grantOffer \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "value": 500000, "currency": "EUR" } }' ``` In the response, note the parameters in the following table. The [id](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-id) parameter represents a static offer and is required to [configure a grant](/capital/make-grant-request/). | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-accountHolderId) | The unique identifier of the account holder that the dynamic offer is for. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-amount) | An object containing offer currency and value, in [minor units](/development-resources/currency-codes). | | [contractType](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-contractType) | The contract type of the offer. | | [expiresAt](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-expiresAt) | The expiration date and time of the offer validity period. | | [fee](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-fee) | An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). | | [id](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-id) | The unique identifier of the static offer. Required to initiate a grant in the next step. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-repayment) | An object containing the details of the repayment configuration. | | [repayment.basisPoints](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-repayment-basisPoints) | The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. | | [repayment.term.estimatedDays](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-repayment-term-estimatedDays) | The estimated period for repaying the grant, in days. | | [repayment.term.maximumDays](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-repayment-term-maximumDays) | The maximum period for repaying the grant, in days. | | [repayment.threshold.amount](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-repayment-threshold-amount) | An object containing the details of the minimum threshold amount that your user must repay every 30-day period. | | [startsAt](https://docs.adyen.com/api-explorer/capital/latest/post/dynamicOffers/\(id\)/grantOffer#responses-200-startsAt) | The starting date and time of the offer validity period. | **Static offer created** ```json { "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": 250000 }, "id": "0000000000000002", "contractType": "loan", "expiresAt": "2026-01-15T23:00:00Z", "fee": { "amount": { "currency": "EUR", "value": 95000 } }, "repayment": { "basisPoints": 750, "term": { "estimatedDays": 90, "maximumDays": 120 }, "threshold": { "amount": { "currency": "EUR", "value": 38330 } } }, "startsAt": "2026-01-08T23:00:00Z" } ``` ## 4. Get notified about an offer created You can get updates every time a new offer is created for an account holder by subscribing to the following webhooks: * [balancePlatform.capital.dynamicOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.capital.dynamicOffer.created) webhook: Notifies your server when a new dynamic offer is created for an account holder. * [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) webhook: Notifies your server when a new static offer is created for an account holder. ### Tab: Dynamic offer created The [balancePlatform.capital.dynamicOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.capital.dynamicOffer.created) webhook includes information about the offer, such as: * `accountHolderId`: The unique identifier of the account holder that the dynamic offer is for. * `id`: The unique identifier of the dynamic offer. * `contractType`: **loan**. * `maximumAmount`: An object containing currency and value of the maximum offer amount, in [minor units](/development-resources/currency-codes). * `minimumAmount`: An object containing currency and value of the minimum offer amount, in [minor units](/development-resources/currency-codes). * `repayment.term.estimatedDays`: The estimated period for repaying the grant, in days. * `repayment.term.maximumDays`: The maximum period for repaying the grant, in days. * `financingType`: **businessFinancing**. * `startsAt` and `expiresAt`: The dates when the financing offer begins and ends. The offer must be accepted before the expiration date. **Dynamic offer created** ```json { "data": { "balancePlatform": "BalancePlatform", "id": "0000000000000001", "dynamicOffer": { "accountHolderId": "AH00000000000000000000001", "contractType": "loan", "expiresAt": "2026-02-19T20:22:39.489+01:00", "financingType": "businessFinancing", "id": "0000000000000001", "maximumAmount": { "currency": "EUR", "value": 4567 }, "minimumAmount": { "currency": "EUR", "value": 1234 }, "repayment": { "term": { "estimatedDays": 180, "maximumDays": 270 } }, "startsAt": "2026-02-12T20:22:39.489+01:00" } }, "environment": "test", "timestamp": "2026-02-12T19:22:39.699Z", "type": "balancePlatform.capital.dynamicOffer.created" } ``` ### Tab: Static offer created from the dynamic offer The [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) webhook includes information about the offer, such as: * `accountHolderId`: The unique identifier of the account holder that the static offer is for. * `id`: The unique identifier of the static offer. * `contractType`: **loan**. * `amount`: An object containing currency and value of the offer, in [minor units](/development-resources/currency-codes). * `repayment.term.estimatedDays`: The estimated period for repaying the grant, in days. * `repayment.term.maximumDays`: The maximum period for repaying the grant, in days. * `repayment.basisPoints`: The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. * `repayment.threshold`: An object containing the details of the minimum threshold amount that your user must repay every 30-day period. * `fee`: An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). * `startsAt` and `expiresAt`: The dates when the financing offer begins and ends. The offer must be accepted before the expiration date. **Static offer created from the dynamic offer** ```json { "data": { "balancePlatform": "TestBalancePlatform", "creationDate": "2026-01-19T17:17:35+01:00", "id": "0000000000000002", "offer": { "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": 629375 }, "contractType": "loan", "expiresAt": "2026-01-26T17:17:34.328+01:00", "fee": { "amount": { "currency": "EUR", "value": 94406 } }, "id": "0000000000000002", "repayment": { "basisPoints": 800, "term": { "estimatedDays": 180, "maximumDays": 270 }, "threshold": { "amount": { "currency": "EUR", "value": 80420 } } }, "startsAt": "2026-01-19T17:17:34.328+01:00" } }, "environment": "test", "timestamp": "2026-01-19T16:17:35.558Z", "type": "balancePlatform.balanceAccountHolder.capitalOffer.created" } ``` ## Next steps [required](/capital/terms-of-service) [Show the Terms of Service](/capital/terms-of-service) [Get your users to accept Adyen's Terms of Service.](/capital/terms-of-service) [required](/capital/make-grant-request) [Disburse a grant](/capital/make-grant-request) [Learn how to make a request for a grant and disburse the funds to your user's account.](/capital/make-grant-request) --- # Source: https://docs.adyen.com/capital/get-grant-offers/static-offers.md Section: Capital Title: Static financing offers Description: Learn how to get static offers with fixed financing amounts and repayment terms. --- title: "Static financing offers" description: "Learn how to get static offers with fixed financing amounts and repayment terms." url: "https://docs.adyen.com/capital/get-grant-offers/static-offers" source_url: "https://docs.adyen.com/capital/get-grant-offers/static-offers.md" canonical: "https://docs.adyen.com/capital/get-grant-offers/static-offers" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Static financing offers Learn how to get static offers with fixed financing amounts and repayment terms. [View source](/capital/get-grant-offers/static-offers.md) **Limited availability**\ Variable repayment terms (90, 180, and 360 days) for financing offers are currently in a pilot phase. To request access, reach out to your Adyen contact. *** Adyen supports static financing offers through the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Based on their processing history, users may receive up to nine offers with fixed financing amounts and repayment terms of 90, 180, and 360 days. You can then show these predefined offers in your user interface (UI). ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration that supports Capital. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#manage-api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capability](/capital/manage-user-capabilities):- **getGrantOffers** | | **Limitations** | The grant offer remains valid for seven days. After this period, a new offer is generated for an account holder if they still meet the qualification criteria. The amount of the grant offer may differ from one offer to another. | | **Setup steps** | Before you begin, make sure you followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. | ## Get static offers available to an account holder This API request also returns static offers created using the [dynamic offers flow](/capital/get-grant-offers/dynamic-offers/). To get static offers available to your user: 1. Make a GET [/grantOffers](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers) request with the receiving [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#query-accountHolderId) as a query parameter. **Get grants available for the account holder** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grantOffers?accountHolderId=AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. In the response, review the [grantOffers](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers) object, which contains the following parameters for each static offer returned. | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-accountHolderId) | The unique identifier of the receiving account holder. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-amount) | An object containing the amount of the grant, in [minor units](/development-resources/currency-codes). | | [contractType](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-contractType) | The legal type of the grant offer. Possible values: **loan**, **cashAdvance**. | | [expiresAt](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-expiresAt) | The expiration date and time of the offer validity period. | | [fee](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-fee) | An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). | | [id](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-id) | The unique identifier of the static offer. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-repayment) | An object containing the details of the repayment configuration. | | [repayment.basisPoints](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-repayment-basisPoints) | The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. | | [repayment.term.estimatedDays](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-repayment-term-estimatedDays) | The estimated term for repaying the grant, in days. | | [repayment.term.maximumDays](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-repayment-term-maximumDays) | The maximum term for repaying the grant, in days. Only returned when `contractType` is **loan**. | | [repayment.threshold](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-repayment-threshold) | An object containing the details of the minimum threshold amount that your user must repay every 30-day period. | | [startsAt](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers#responses-200-grantOffers-startsAt) | The starting date and time of the offer validity period. | The following example shows three static offers for each available repayment term for the account holder **AH00000000000000000000001**. **Response including static offers available to the account holder** ```json { "grantOffers": [ { "id": "0000000000000001", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 800, "threshold": { "amount": { "value": 388, "currency": "EUR" } }, "term": { "estimatedDays": 90, "maximumDays": 120 } }, "fee": { "amount": { "value": 145, "currency": "EUR" } }, "amount": { "value": 1403, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000002", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1500, "threshold": { "amount": { "value": 727, "currency": "EUR" } }, "term": { "estimatedDays": 90, "maximumDays": 120 } }, "fee": { "amount": { "value": 273, "currency": "EUR" } }, "amount": { "value": 2632, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000003", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1200, "threshold": { "amount": { "value": 582, "currency": "EUR" } }, "term": { "estimatedDays": 90, "maximumDays": 120 } }, "fee": { "amount": { "value": 218, "currency": "EUR" } }, "amount": { "value": 2106, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000004", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1200, "threshold": { "amount": { "value": 517, "currency": "EUR" } }, "term": { "estimatedDays": 180, "maximumDays": 270 } }, "fee": { "amount": { "value": 623, "currency": "EUR" } }, "amount": { "value": 4025, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000005", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1500, "threshold": { "amount": { "value": 646, "currency": "EUR" } }, "term": { "estimatedDays": 180, "maximumDays": 270 } }, "fee": { "amount": { "value": 779, "currency": "EUR" } }, "amount": { "value": 5032, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000006", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 800, "threshold": { "amount": { "value": 345, "currency": "EUR" } }, "term": { "estimatedDays": 180, "maximumDays": 270 } }, "fee": { "amount": { "value": 415, "currency": "EUR" } }, "amount": { "value": 2682, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000007", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 800, "threshold": { "amount": { "value": 414, "currency": "EUR" } }, "term": { "estimatedDays": 360, "maximumDays": 450 } }, "fee": { "amount": { "value": 1168, "currency": "EUR" } }, "amount": { "value": 5027, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000008", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1500, "threshold": { "amount": { "value": 775, "currency": "EUR" } }, "term": { "estimatedDays": 360, "maximumDays": 450 } }, "fee": { "amount": { "value": 2192, "currency": "EUR" } }, "amount": { "value": 9431, "currency": "EUR" }, "contractType": "loan" }, { "id": "0000000000000009", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1200, "threshold": { "amount": { "value": 620, "currency": "EUR" } }, "term": { "estimatedDays": 360, "maximumDays": 450 } }, "fee": { "amount": { "value": 1753, "currency": "EUR" } }, "amount": { "value": 7544, "currency": "EUR" }, "contractType": "loan" } ] } ``` ## Get a specific static offer This API request also returns static offers created using the [dynamic offers flow](/capital/get-grant-offers/dynamic-offers/). To get the details of a specific static offer: 1. Make a GET [/grantOffers/{id}](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers/\(id\)) request, specifying the [id](https://docs.adyen.com/api-explorer/capital/latest/get/grantOffers/\(id\)#path-id) in the path. **Get a specific static offer** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grantOffers/0000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET ``` 2. In the response, note an object containing all the information about the offer. **Response including information about the specified offer** ```json { "id": "0000000000000003", "accountHolderId": "AH00000000000000000000001", "startsAt": "2026-03-18T23:00:00Z", "expiresAt": "2026-03-25T23:00:00Z", "repayment": { "basisPoints": 1500, "threshold": { "amount": { "value": 64600, "currency": "EUR" } }, "term": { "estimatedDays": 360, "maximumDays": 450 } }, "fee": { "amount": { "value": 77900, "currency": "EUR" } }, "amount": { "value": 703200, "currency": "EUR" }, "contractType": "loan" } ``` ## Get notified about a static offer created You can get updates every time a new static offer is created for an account holder by subscribing to the [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) webhook. The webhook includes information about the offer, such as: * `accountHolderId`: The unique identifier of the account holder that the static offer is for. * `id`: The unique identifier of the static offer. * `contractType`: **loan**. * `amount`: An object containing currency and value of the offer, in [minor units](/development-resources/currency-codes). * `repayment.term.estimatedDays`: The estimated period for repaying the grant, in days. * `repayment.term.maximumDays`: The maximum period for repaying the grant, in days. * `repayment.basisPoints`: The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. * `repayment.threshold`: An object containing the details of the minimum threshold amount that your user must repay every 30-day period. * `fee`: An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). * `startsAt` and `expiresAt`: The dates when the financing offer begins and ends. The offer must be accepted before the expiration date. **Static offer created** ```json { "data": { "balancePlatform": "TestBalancePlatform", "creationDate": "2026-01-19T17:17:35+01:00", "id": "0000000000000001", "offer": { "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": 629375 }, "contractType": "loan", "expiresAt": "2026-01-26T17:17:34.328+01:00", "fee": { "amount": { "currency": "EUR", "value": 94406 } }, "id": "0000000000000001", "repayment": { "basisPoints": 800, "term": { "estimatedDays": 180, "maximumDays": 270 }, "threshold": { "amount": { "currency": "EUR", "value": 80420 } } }, "startsAt": "2026-01-19T17:17:34.328+01:00" } }, "environment": "test", "timestamp": "2026-01-19T16:17:35.558Z", "type": "balancePlatform.balanceAccountHolder.capitalOffer.created" } ``` ## Next steps [required](/capital/terms-of-service) [Show the Terms of Service](/capital/terms-of-service) [Get your users to accept Adyen's Terms of Service.](/capital/terms-of-service) [required](/capital/make-grant-request) [Disburse a grant](/capital/make-grant-request) [Learn how to make a request for a grant and disburse the funds to your user's account.](/capital/make-grant-request) --- # Source: https://docs.adyen.com/capital/get-started.md Section: Capital Title: Get started Description: An overview of the steps for signing up for Capital. --- title: "Get started" description: "An overview of the steps for signing up for Capital." url: "https://docs.adyen.com/capital/get-started" source_url: "https://docs.adyen.com/capital/get-started.md" canonical: "https://docs.adyen.com/capital/get-started" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Get started An overview of the steps for signing up for Capital. [View source](/capital/get-started.md) To get you started, this page gives an overview of the process of integrating with Adyen Capital, from scoping and designing your implementation to going live. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model) integration. | | **Limitations** | Your user must operate in one of the [supported countries/regions](#supported-countriesregions). | | **Setup steps** | [Contact us](https://www.adyen.com/contact/sales) to register your interest for Capital. | ## How it works To start offering Adyen Capital to your users: 1. [Scope and design your implementation](#design-implementation) 2. [Build your integration](#build-integration) 3. [Test your integration](#test-integration) 4. [Configure your live account](#configure-live-account) The following sections explain how to complete these steps. ## 1. Scope and design your implementation Your Adyen contact will work with you to design your implementation. During this phase, you decide how to: * [Comply with financial regulations](/capital/compliance-guidelines) related to Capital. * Configure the required [capabilities](/capital/manage-user-capabilities) to allow your users to use Capital. * Choose a way to integrate with Capital: * **Prebuilt UI components**: Use our [capital components](/capital/capital-components) to integrate all Capital features in your user interface with low engineering effort. * **API-only integration**: Use our [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview) and [library](https://github.com/Adyen/adyen-java-api-library) to build a custom user interface for offering Capital. ## 2. Build your integration When you have your test account and credentials, you can start building your Capital integration. To integrate using capital components: 1. Learn about [components](/capital/capital-components) and the standard user flow they offer. 2. Follow the [integration steps](/capital/integration-steps-components). To integrate using our Capital API, follow the steps to: 1. [Get grant offers](/capital/get-grant-offers) 2. [Show the Terms of Service](/capital/terms-of-service) 3. [Disburse a grant](/capital/make-grant-request) 4. [Get grant details](/capital/get-grant-balances) 5. [Manage disbursements](/capital/manage-disbursements) Additionally, you can refer to our [integration checklist](/capital/integration-checklist), [Postman collections](https://github.com/Adyen/adyen-postman), [GitHub repo and libraries](https://github.com/Adyen) for help with the implementation process. ## 3. Test your integration After you integrate with our APIs, you are responsible for testing what you built in our test environment. We recommend that you test your integration again after you [configure your live account](#configure-live-account). ## 4. Configure your live account The setup and configuration of your test account is *not* replicated to your live account. You need to replicate your test account setup in the live environment. After you configure your account on the live environment, test your integration on the live environment as well. Follow our [go-live checklist](/capital/integration-checklist#go-live) to make sure your integration is ready. ## Next steps [required](/capital/integration-checklist) [Integration checklist](/capital/integration-checklist) [Learn how to integrate Capital into your platform or marketplace.](/capital/integration-checklist) [Account structure and resources](/capital/account-structure-resources) [Learn about the resources you need to use and manage Capital.](/capital/account-structure-resources) [How Capital works](/capital/how-capital-works) [Get familiar with the process of offering business financing to your users.](/capital/how-capital-works) --- # Source: https://docs.adyen.com/capital/grant-lifecycle-and-status.md Section: Capital Title: Grant lifecycle and status Description: Learn how the grant status evolves throughout the grant lifecycle. --- title: "Grant lifecycle and status" description: "Learn how the grant status evolves throughout the grant lifecycle." url: "https://docs.adyen.com/capital/grant-lifecycle-and-status" source_url: "https://docs.adyen.com/capital/grant-lifecycle-and-status.md" canonical: "https://docs.adyen.com/capital/grant-lifecycle-and-status" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Grant lifecycle and status Learn how the grant status evolves throughout the grant lifecycle. [View source](/capital/grant-lifecycle-and-status.md) Grants undergo changes over time and their status can be modified based on various events. For instance, grants that have been approved are automatically activated by a background processing system, which initiates the fund disbursement process. You can monitor changes in the grant status using either way: * Call our [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview) and check the [status.code](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)#responses-200-status-code) parameter in the response. * Listen to the [Capital webhooks](https://docs.adyen.com/api-explorer/capital-webhooks/latest/overview). The lifecycle of a grant consists of two main stages: 1. **Grant initiation:** During this stage, Adyen prepares the requested offer as the user applies for business financing. Status updates at this stage trigger only capital webhook types. No transfers or transactions occur during grant initiation. 2. **Grant management:** This stage involves managing and overseeing the funds that have been disbursed to the user. Grant management status updates trigger capital, transfer, and transaction webhook types. The following diagram and explanation detail the various grant statuses that occur during these two stages. [![Grant lifecycle](/user/pages/docs/07.capital/12.grant-lifecycle-and-status/grant-lifecycle.svg)](/user/pages/docs/07.capital/12.grant-lifecycle-and-status/grant-lifecycle.svg) ## Grant initiation statuses | Status | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Requested** | This status indicates the initial stage of the grant initiation process, showing that a formal request for a grant has been successfully submitted. | | **Reviewing** | This status indicates that the user has accepted the offer, and Adyen conducts a thorough secondary review of the grant request. This re-evaluation is crucial, as it considers any changes in the user's financial situation or eligibility that may have occurred between the offer creation and acceptance, such as acquiring additional financial obligations from other financial products. In specific situations, Adyen may require your users to provide additional information about their businesses, such as when the [total user's exposure meets or exceeds the threshold](/capital/collect-user-data), typically EUR 25,000. **User action needed:**- When requesting a higher grant amount, the user must submit the required information before the grant offer expires. | | **Approved** | This status indicates that the grant request has successfully met all necessary criteria and has received final approval from Adyen. | | **Rejected** | This status indicates that the grant request did not meet the required criteria and has been declined by Adyen. | | **Cancelled** | This status indicates that the user has chosen to withdraw their grant request. This action can occur at any point during the grant initiation stage, up until the grant transaction is formally booked and the grant transitions to the **Pending** status. | ## Grant management statuses | Status | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pending** | This status indicates that the user has accepted the offer, marking the completion of the grant initiation stage. The grant remains pending until:- All required actions are completed on the user's side. - The grant transaction is booked to the user's balance account. - The security cooldown period ends. For example, if a user updates their bank account details (transfer instrument), Adyen waits 72 hours before processing transactions to the new account. **User action needed:**- The user must sign the Terms of Service. | | **Failed** | This status indicates that the grant disbursement was unsuccessful. This can happen for various reasons, such as when the user fails to complete the required actions (like signing the Terms of Service) before the offer expires, or due to unforeseen technical or administrative issues. This does not affect the user's future eligibility for business financing with Adyen. | | **Active** | This status indicates that the grant has been successfully disbursed to the user, marking the beginning of the grant's active phase. | | **Repaid** | This status indicates that the user has successfully met all repayment obligations, and the grant has been fully settled. | | **Revoked** | This status indicates that the user has requested to revoke the grant. Depending on regional regulations, a grant may be legally revoked within a specified timeframe after offer acceptance. When a grant is revoked, the principle amount is paid off and the fees are waived. This does not affect the user's future eligibility for business financing with Adyen. | | **Written Off** | This status indicates that the grant has been officially classified as a write-off, with the likelihood of recovering the outstanding amount very low. The user will not qualify for business financing with Adyen for a certain period based on our risk appetite. | ## See also * [Webhook structures and types for Capital](/capital/webhook-types) --- # Source: https://docs.adyen.com/capital/how-capital-works.md Section: Capital Title: How Capital works Description: Learn the basics about Adyen Capital. --- title: "How Capital works" description: "Learn the basics about Adyen Capital." url: "https://docs.adyen.com/capital/how-capital-works" source_url: "https://docs.adyen.com/capital/how-capital-works.md" canonical: "https://docs.adyen.com/capital/how-capital-works" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # How Capital works Learn the basics about Adyen Capital. [View source](/capital/how-capital-works.md) This page covers the basics of Adyen Capital. You can learn about the eligibility requirements, financing process, and the structure of financing offers. ## Eligibility To offer business financing to your users, they must meet specific requirements regarding their location, business type, and processing history ### Minimum eligibility requirements To qualify for a financing offer through Capital, your users must: 1. Be located in a [supported country or region](/capital#supported-countries-regions) and have an eligible legal entity type. 2. Have processed payments with Adyen for at least three consecutive months (90 days). 3. Maintain a processing volume of at least 1,000 EUR, GBP, USD, or AUD for a minimum of three consecutive months. 4. Not operate in a high-risk industry as defined by payment risk categorization. Note that meeting these minimum eligibility requirements does not guarantee qualification for a Capital offer. ### Eligible legal entity types The following table shows the legal entity types that are eligible for financing through Capital. | Country/Region | Organization | Unincorporated partnership | Sole proprietorship | Trust | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Canada (excluding Saskatchewan) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") (excluding Quebec) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") (excluding Quebec) | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Finland | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | France | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | Sweden | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | United Kingdom (including the Channel Islands and Isle of Man) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | United States (including Puerto Rico) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ## Financing process The process of offering business financing through Adyen Capital follows a specific lifecycle, from risk assessment to repayment. The following table outlines each phase of this process: | Phase | Description | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Risk assessment and underwriting** | Adyen configures the required capabilities for your user and assesses the risk of their account. This assessment, based on your user's payments data, determines which financing offers are available to your user. | | **Offers** | Adyen generates financing offers for your user based on the risk assessment. Depending on your integration (API or UI components), users are presented with specific options or a maximum limit. | | **Terms of Service** | After selecting their preferred financing offer, the user accepts Adyen's [Terms of Service](/capital/terms-of-service). Upon acceptance, the required capabilities are enabled on the user's account. | | **Fund disbursement** | The grant amount specified in the offer is disbursed to the user's balance account. The funds can also be transferred to the user's verified bank account (transfer instrument) if provided in the API request. | | **Repayment** | Repayments are primarily handled through scheduled repayments, where Adyen automatically deducts a fixed percentage from the user's daily net captured volume. Users in certain regions can also make unscheduled repayments. Adyen monitors progress against a minimum 30-day threshold to ensure timely repayment. | The following sections provide more details about each phase of the financing process. ### Risk assessment and underwriting Adyen Capital requires users to have [specific capabilities](/capital/manage-user-capabilities#capital-capabilities). In most cases, Adyen automatically configures and requests the necessary capabilities for your business when you [design your implementation](/capital/get-started#design-implementation). After the necessary capabilities are requested, Adyen assesses financing risks based on the user's payments data. This risk assessment defines which financing offers are available to your users. ### Financing offer Based on the results of the risk assessment, Adyen generates financing offers for your users. Each offer includes the following information: * The grant amount available to the user. * The fee associated with the grant. * The repayment terms for the grant. Based on the risk assessment, Adyen generates offers as follows: * If you are using an [API-only integration](/capital/get-grant-offers), Adyen generates a maximum of three offers that you can present to your user. Each offer includes different grant amounts. * If you are using [UI components](/capital/capital-components), Adyen determines a maximum grant amount that your user qualifies for. Your user can select any grant amount that does not exceed the maximum grant amount. ### Terms of Service After your user selects an offer, you must provide them with the following information: * The [terms of the selected offer](#structure-and-terms-of-the-financing-offer). * The [Terms of Service](/capital/terms-of-service) related to the Capital product. Depending on your implementation: * If you are using an API-only implementation, you must [generate a Terms of Service document](/capital/terms-of-service), present it to the user, and request their acceptance. * If you are using UI components, the user will complete this step as part of the prebuilt [user flow](/capital/capital-components/?component=Capital\&integration=components\&version=1.7.x#standard-user-flow). To receive a grant, users must accept the Terms of Service for Capital, even if they have already accepted them previously when requesting business financing. When a user selects an offer and signs the Terms of Service, the necessary [capabilities](/capital/manage-user-capabilities#capital-capabilities) are enabled. The grant can then be disbursed to the user. ### Fund disbursement After your user signs the Terms of Service, the necessary [capabilities](/capital/manage-user-capabilities#capital-capabilities) become enabled for them. You can then proceed to disburse the grant to your user. The amount that you disburse to the user is called a *disbursement*. The disbursement is assigned a unique identifier that enables you to: * [Manage disbursement configuration](/capital/manage-disbursements). * Track the disbursement data, including repayment progress and outstanding amounts. You can configure the grant to be disbursed to the user's balance account or their transfer instrument (a bank account verified by Adyen). You can specify the desired destination of the disbursement in your [API request to configure a grant](/capital/make-grant-request): * The grant amount is initially disbursed to the balance account linked to the account holder of your user. * After the initial disbursement has settled, you can instruct Adyen to transfer the grant amount to the user's transfer instrument by indicating this in the same API request. ### Repayment Adyen offers two options for [grant repayment](/capital/repayment): * **Scheduled repayments**: Adyen automatically reserves and deducts a fixed percentage from each processed sale. This is the default option and is fully managed by Adyen. * **Unscheduled repayments**: This option allows users to make early repayments or address missed payments. It requires additional action from you. Both repayment options are available regardless of your chosen integration option (UI components or API). ## Structure of the financing offer Each Capital offer has the following elements: | Element | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Principal amount | The amount that the user is prequalified to receive. | | Fee | The fixed fee on top of the principal amount. | | Daily repayment rate | The percentage of the user's daily net captured volume that is reserved each day for the repayment of the total repayment amount. The total repayment amount is the sum of the principal amount and the fee. | | Repayment threshold | The minimum amount that the user is expected to repay every 30-day period. The repayment threshold monitors that your user fully pays off the grant within the expected repayment period. If the total 30-day repayment drops below this threshold, Adyen may take additional actions to ensure that the user repays on time. | | Maximum repayment period | The period in days or months during which your user must repay the grant amount in full. | ## Integration options Adyen provides two options for integrating with Capital: * **Prebuilt UI Components**: Use our [Capital components](/capital/capital-components) to seamlessly integrate all Capital features into your user interface with minimal engineering effort. This option eliminates the need for multiple API requests to access offers, generate Terms of Service, or manage disbursements, as everything is managed automatically. For more details, refer to the [integration steps overview](/capital/integration-checklist?tab=ui_components_0_1). * **API-only integration**: Use our [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview) for complete control over the integration process, allowing you to create a custom user interface for offering Capital. For more details, refer to the [integration steps overview](/capital/integration-checklist?tab=implement-capital-api_2). ## Next steps [required](/capital/integration-checklist) [Integration checklist](/capital/integration-checklist) [Learn how to integrate Capital into your platform or marketplace.](/capital/integration-checklist) --- # Source: https://docs.adyen.com/capital/integration-checklist.md Section: Capital Title: Integration checklist Description: An overview of the steps from signing up for Capital to going live. --- title: "Integration checklist" description: "An overview of the steps from signing up for Capital to going live." url: "https://docs.adyen.com/capital/integration-checklist" source_url: "https://docs.adyen.com/capital/integration-checklist.md" canonical: "https://docs.adyen.com/capital/integration-checklist" last_modified: "2022-10-26T11:36:00+02:00" language: "en" --- # Integration checklist An overview of the steps from signing up for Capital to going live. [View source](/capital/integration-checklist.md) This page explains the steps to integrate Adyen Capital into your existing [Adyen for Platforms](/adyen-for-platforms-model) integration. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an [Adyen for Platforms](/adyen-for-platforms-model) integration. | | **Limitations** | Your user must operate in one of the [supported countries/regions](#supported-countriesregions). | | **Setup steps** | Before you begin, make sure:- You [contacted us](https://www.adyen.com/contact/sales) to register your interest for Capital. - You [designed your implementation](/capital/get-started#design-implementation) with your Adyen contact. | ## How it works Integrating Capital consists of the following steps: 1. [Review your account structure](#review-account-structure) 2. [Complete the integration checklist for Adyen for Platforms](#complete-integration-adyen-for-platforms) 3. [Test your API keys](#test-api-keys) 4. [Set up webhooks](#set-up-webhooks) 5. [Implement Capital features](#implement-capital-features) 6. [Go live](#go-live) ## 1. Review your account structure Before you start the integration process, you must be familiar with the [account structure for Capital](/capital/account-structure-resources). You need this information to building the different parts of your implementation. Every integration that includes Capital must have at least the following resources: * **Company account**: Represents your core business entity and holds your merchant accounts. * **Merchant account**: The account where we process payments for your users. You can have multiple merchant accounts. * **Balance platform**: The accounting system in which you manage your users and funds. * **Account holder**: Specifies what your user can do in your platform, for example, receive fund transfers to their balance account and payouts to their verified transfer instrument (bank account). * **Balance account**: Holds the funds of your user or your platform. All financial activities in your platform, such as paying out to a bank account, happen through balance accounts. * **Legal entity**: Contains information about your user, for example, the legal name, address, and tax information of the organization. Adyen uses this information to perform verification checks required by payment industry regulations. * **Transfer instrument**: Your user's verified bank account where they can receive payouts. * **Grant account**: allows you to track the total amount of outstanding receivables that Adyen has in relation to grants in your balance platform. * **Grant references**: tracks the balances related to specific grants. These references are created when a grant is paid out. ## 2. Complete the integration checklist for Adyen for Platforms Before integrating Capital, you must complete the integration steps for either the [marketplace](/marketplaces/integration-checklist) or [platform](/platforms/integration-checklist) model of Adyen for Platforms. ## 3. Test your API keys To make API requests related to Capital, you can use the same API credentials that you generated for your [marketplace](/marketplaces/integration-checklist/#generate-and-test-your-api-keys) or [platform](/platforms/integration-checklist/#generate-and-test-your-api-keys). If needed, you can [generate your API credentials](/capital/manage-access/#manage-api-credentials) and assign roles to them in your [Customer Area](https://ca-test.adyen.com/). Make sure that you have the following API credentials and roles. | API | Credential | Roles | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview) [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) | **ws\@BalancePlatform.\[YourBalancePlatform]** Use this API credential to make grant requests and disburse grants, create resources such as account holders and balance accounts, and request user capabilities. | * **Balance Platform BCL role** * **Balance Platform Capital Configuration Role** * **Balance Platform Capital Grant Initiation role** | | [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) | **ws\_\[123456]@Scope.Company\_\[YourCompanyAccount]** Use this API credential to create and manage legal entities that contain the information required for verification checks. | | ## 4. Set up webhooks Adyen sends webhooks to notify you of business financing-related events in your balance platform. For more details, see [Webhook structures and types for Capital](/capital/webhook-types). To configure webhooks: 1. [Set up webhook endpoints](/development-resources/webhooks/#expose-an-endpoint-on-your-server) on your server and build the logic for acknowledging webhooks. 2. [Configure webhooks](/development-resources/webhooks/#set-up-webhooks-in-your-customer-area) in your Customer Area. 3. [Secure webhooks](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures/) with HMAC signing. ## 5. Implement Capital features You can implement Capital features in two ways: * By using capital components * By using the Capital API ### Tab: Components To reduce implementation time and effort, use Adyen's prebuilt component libraries that you can integrate into your user interface. To implement capital components: 1. **Create an authentication session from your server**\ Create a session token to ensure secure communication between the component and the Adyen server. 2. **Install the component library in your front end**\ Install the npm package, then import the library, component, and style sheet in your front-end application. 3. **Initialize the component** 1. Gather the required information on the specific library and component you want to integrate. 2. Create a DOM element on your user interface page where you want the component to be rendered. 3. Add a function that calls your API to retrieve and refresh an authentication session token. 4. Initialize the component and mount it to the DOM element you created. 4. **Customize the component(s)**\ Customize the component to match your platform's look and feel. ### Tab: API You can use our [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview) to build your own user interface for offering Capital. As part of your API-only integration, you need to implement the necessary features to: 1. **Present available grant offers to your users**\ Get personalized [grant offers](/capital/get-grant-offers/) and present them in your user interface for user selection. 2. **Show the Terms of Service to your users.**\ Enable your users to digitally sign Adyen's [Terms of Service](/capital/terms-of-service/) in your user interface. 3. **Disburse grant amount to your user**\ [Make a request](/capital/make-grant-request/) for the selected grant offer on behalf of your users. ## 6. Go live To take your Capital integration live: 1. **Replicate your test account setup in your live account**: The Capital setup from your test account for Adyen for Platforms is *not* automatically replicated in your live account. 2. **Update your code base** 3. **Switch to live API credentials**\ Get your live API credentials from your Adyen contact. Use these credentials in your live account. 4. **Switch from test to live endpoints**\ Change the endpoints from `test` to `live`. For example, `https://balanceplatform-api-test.adyen.com/` to\ `https://balanceplatform-api-live.adyen.com/`. 5. **Run end-to-end tests** * Live API credentials: Make your first live API requests to make sure that your live API credentials are working. * Grant account: Create a grant account in your live environment. * Grant offers: Confirm that you can get grant offers for users with the required [capability](/capital/manage-user-capabilities#capital-capabilities). * Pay out grants: Confirm that grant amounts are correctly paid out to the corresponding balance accounts or transfer instruments. * Webhooks: Confirm that you can receive and accept webhooks in the live environment. ## Next steps [Integrate with components](/capital/capital-components) [Learn how to integrate our prebuilt UI components to accelerate your Capital integration process.](/capital/capital-components) [Integrate using APIs](/capital/make-grant-request) [Learn how to use our APIs to build your Capital integration from scratch.](/capital/make-grant-request) [Manage access for your team](/capital/manage-access) [Learn how to manage your integration in your Customer Area.](/capital/manage-access) --- # Source: https://docs.adyen.com/capital/integration-steps-components.md Section: Capital Title: Integration steps for capital components Description: A step-by-step guide for integrating Adyen's capital components. --- title: "Integration steps for capital components" description: "A step-by-step guide for integrating Adyen's capital components." url: "https://docs.adyen.com/capital/integration-steps-components" source_url: "https://docs.adyen.com/capital/integration-steps-components.md" canonical: "https://docs.adyen.com/capital/integration-steps-components" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Integration steps for capital components A step-by-step guide for integrating Adyen's capital components. [View source](/capital/integration-steps-components.md) ##### Learn more ![](/user/pages/reuse/pfs-components/platform-experience/github-logo.svg?decoding=auto\&fetchpriority=auto)  [View our repository on GitHub](https://github.com/Adyen/adyen-platform-experience-web) ![](/user/pages/reuse/pfs-components/platform-experience/click.svg?decoding=auto\&fetchpriority=auto)  [Try it out with a live demo](https://demotool.adyen.com/se/pie/platform-tx) ![](/user/pages/reuse/pfs-components/platform-experience/megaphone.svg?decoding=auto\&fetchpriority=auto)  [Explore the latest updates](/release-notes/platforms-and-financial-products) This page provides guidance on integrating the [capital components](/capital/capital-components) into your portal's user interface (UI). The guidance and features available may differ based on the library version in use. We recommend using the latest library version to take advantage of the newest features and improvements. Ensure you select a version in the next section before starting your integration. ## Capital components Use Platform Experience components to offer business financing to your users. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an Adyen for Platforms integration. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#manage-api-credentials) (for example, **ws\[\_123456]@BalancePlatform.****\[YourBalancePlatform]**) to access the [Session authentication API](https://docs.adyen.com/api-explorer/sessionauthentication/latest/overview). Ensure that you have asked your Adyen contact to assign the following role to your API credential:- **Capital Component: Manage** | | **Capabilities** | Make sure that your account holders have the following [capability](/capital/manage-user-capabilities):- **getGrantOffers** | | **Limitations** | With the capital components, you can only pay out the business financing funds to the user's balance account. Payouts to transfer instruments are not supported in this implementation. | | **Setup steps** | Before you begin:- Reach out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. - Review our [compliance guidelines](/capital/compliance-guidelines) for Capital. - Verify that the components are available in the [languages](#supported-languages) that apply to your situation. - Check our [Component libraries](/platforms/components-overview) page for additional information on the supported countries/regions and browser versions. | ### Methods And Parameters ## Component instance methods and parameters By default, the **Capital Offer** component is embedded in the **Capital Overview** component, creating a [standard user flow](/capital/capital-components#standard-user-flow). This flow consists of a series of interactive screens that users engage with, all rendered within a single component element on the same portal's UI page. You can modify this standard user flow to create a more tailored and relevant experience for your users. For example, you may want to show a message about their eligibility for a grant on one page while directing users to complete the remaining steps on another page in your portal's UI. To do this, you can use additional methods and parameters that enable you to register and unregister events, making it easier to manage multiple instances of components. There are various approaches you can take for each of the components. When integrating the **Capital Overview** component, you can: * Decide whether to render the component based on its state. For example, if the state is **isUnqualified**, you can choose not to render the component. * Interrupt the standard user flow at certain points to redirect a user to a different page in your interface to continue their flow. When integrating the **Capital Offer** component, you can: * Render it as standalone component and place it on a separate page in your portal's UI. * Configure the component to only show a specific screen. You can specify the necessary methods and parameters when [initializing components](#initialize-components). Refer to the [use case examples](#use-cases) for more details. ## How it works The integration of components involves both server-side and client-side processes. You can find more details on the [Component libraries](/platforms/components-overview) page. ### Integration steps Follow these steps to integrate the component(s): 1. [Create an authentication session from your server](#create-token) 2. [Install component library in your front end](#install-library) 3. [Initialize components](#initialize-components) 4. [Optional: Localize components](#localize-components) 5. [Optional: Customize component appearance](#customize-appearance) ### Create A Session ## 1. Create an authentication session from your server To ensure secure communication between components and Adyen server, you must configure your server for authentication and create a session token. To create the token: 1. From your server, make a POST [/sessions](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions) request specifying the following parameters: To make this API request, your API key must have the **Capital Component: Manage** role in your Customer Area. Read more in [Requirements](#requirements). | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [allowOrigin](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-allowOrigin) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The URL where the component will appear. Must follow the format: `https://www.yourcompany.com` or `https://*.yourcompany.com`, where `yourcompany.com` is the actual web address of your platform. On live, only the HTTPS protocol is supported. | | [policy](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains:- [resources](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-resources): An object that contains: * `accountHolderId`: The unique identifier of the account holder that is linked to the balance account shown in the component. * [type](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-resources-type): The type of resource. Set this to **accountHolder**. - [roles](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-policy-roles): The role required to use the component. Set this to **Capital Component: Manage**. | | [product](https://docs.adyen.com/api-explorer/sessionauthentication/latest/post/sessions#request-product) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of product the component belongs to. Set this to **platform**. | Here is an example request for creating a session token. **Create a session token** ```bash curl https://test.adyen.com/authe/api/v1/sessions \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -D '{ "allowOrigin":"YOUR_DOMAIN", "product":"platform", "policy": { "resources": [ { "accountHolderId": "AH00000000000000000000001", "type": "accountHolder" } ], "roles": [ "Capital Component: Manage" ] } }' ``` 2. Note the API response. Later, when [initializing the components](#initialize-components), you need to create and call a function that passes the entire session object from the response to your front end. **Session token created** ```json { "id": "EC1234-1234-1234-1234", "token": "xxxxx.yyyyy.zzzzzz" } ``` ### Install Component Library ## 2. Install component library in your front end Use the Adyen Web npm package, or embed the Adyen Platform Experience script and stylesheet into your HTML file: ### Tab: npm (recommended) Install the **Adyen Platform Experience** library in your front-end application as follows: 1. Install the npm package. ```bash npm install @adyen/adyen-platform-experience-web ``` 2. Import the library, the components, and the style sheet. ```bash import { AdyenPlatformExperience, component_name } from '@adyen/adyen-platform-experience-web'; import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css"; ``` ### Tab: Embed script and stylesheet Use the `integrity` attribute so browsers can verify that the script and stylesheet have not been changed unexpectedly. The value of the `integrity` attribute is the [Subresource Integrity (SRI) hash](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) which Adyen provides for each version of the Adyen Web JavaScript and CSS files. Get the SRI hashes from the [release notes](/release-notes/platforms-and-financial-products) for the Platform Experience components, under **Updating to this version**. **embed-script-stylesheet.html** ```html ``` ### Initialize Components ## 3. Initialize components To initialize the components: 1. Gather the following information to be passed when initializing the library and its components. 1. Gather these parameters to initialize the library. | Parameter | Required | Description | | --------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `availableTranslations`Deprecated | | **Deprecated.** This field is no longer needed because locales are now dynamically loaded on demand via CDN. Setting this field will trigger a deprecation warning. An array containing the names of the imported locale files used for localizing the components. For example, `[es_ES, nl_NL, fr_FR]`. | | `environment` | | Specifies the environment for the component integration. The default value is **test**. Set the parameter to **live** when you are ready to go live. | | `locale` | | Specifies the locale code, which determines the desired language of the components. This code must correspond to a [supported language](#supported-languages). For example, use **es-ES** for Spanish. | | `onSessionCreate` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The callback function that retrieves an authentication session token and refreshes the current session. | 2. Gather these parameters to initialize each component. Select the tab for the component you want to use: ### Tab: Capital Overview component | Parameter | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `core` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The instance of the library. | | `onFundsRequest` | | The callback function triggered after the user selects the **Request funds** button on the grant offer term sheet screen, and the grant request has been successful. Define this function if you need to exit the default flow after a successful grant request. The function accepts an argument that includes the data for the requested grant. For more information, [read here](#component-methods). | | `onOfferDismiss` | | The callback function triggered after the user selects the **Back** button on the grant offer selection screen. Define this function if you need to handle the dismissal of the flow when the `skipPreQualifiedIntro` parameter is provided. For more information, [read here](#component-methods). | | `onOfferOptionsRequest` | | The callback function triggered after the user selects the **See options** button on the pre-qualified screen. Define this function if you need to exit the default flow after the button is selected. For more information, [read here](#component-methods). | | `skipPreQualifiedIntro` | | Determines whether to show a screen indicating that the user is being pre-qualified for a grant offer. For more information, [read here](#component-methods) Default value: **false**. | ### Tab: Capital Offer component | Parameter | Required | Description | | ---------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `core` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The instance of the library. | | `onFundsRequest` | | The callback function triggered after the user selects the **Request funds** button on the grant offer term sheet screen, and the grant request has been successful. Define this function if you need to exit the default flow after a successful grant request. The function accepts an argument that includes the data for the requested grant. For more information, [read here](#component-instance-methods-and-parameters). | | `onOfferDismiss` | | The callback function triggered after the user selects the **Back** button on the grant offer selection screen. Define this function if you need to handle the dismissal of the flow when the `skipPreQualifiedIntro` parameter is provided. For more information, [read here](#component-methods). | | `onOfferSelect` | | The callback function triggered after the user selects the **Review offer** button on the grant offer selection screen, and the grant offer selection has been successful. Define this function if you need to exit the default flow after the grant offer is selected. For more information, [read here](#component-methods). | 3. (Optional) Define the following component instance method. | Method | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `getState` | Retrieves the state of the component, which is an object containing a `state` field. The possible values of this field are:- **isUnqualified**: The user is not yet qualified for a grant. - **isPreQualified**: The user is pre-qualified for a grant. - **hasRequestedGrants**: The user has previously received and repaid grants. - **isInUnsupportedRegion**: The user is operating in a country/region where Adyen Capital is not yet supported. For more information, [read here](#component-methods). | 2. Create a DOM element on your portal's UI page where you want the component to be rendered. Assign the element a unique and descriptive ID. This unique ID is important to avoid any misconfigurations when integrating multiple components into your portal's UI. By default, the **Capital Offer** component is embedded in the **Capital Overview** component. In this scenario, you only need to create a DOM element for the **Capital Overview** component. If you want to render the **Capital Offer** component outside the **Capital Overview** component, you need to create a separate DOM element for it. If you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element. Select the tab for the component you want to use: ### Tab: Capital Overview component **Create DOM element** ```html
``` ### Tab: Capital Offer component **Create DOM element** ```html
``` 3. Add a function that [calls your API](#create-token) to retrieve and refresh an authentication session token. The following code is the same for both capital components. **Add function to retrieve and refresh an authentication session token** ```bash async function handleSessionCreate() { const response = await fetch('YOUR_IMPLEMENTATION_OF_CREATE_SESSION_ENDPOINT'); return response.json(); } ``` 4. Initialize the component and mount it to the container you created. Be sure to include the function for retrieving and refreshing the session token that you added in the previous step. Select the tab for the component you want to use: ### Tab: Capital Overview component **Initialize library and create component** ```javascript import { AdyenPlatformExperience, CapitalOverview } from '@adyen/adyen-platform-experience-web'; import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css"; const core = await AdyenPlatformExperience({ onSessionCreate: handleSessionCreate, }); const capitalOverview = new CapitalOverview({ core }); capitalOverview.mount('#capital-overview-container'); ``` ### Tab: Capital Offer component **Initialize library and create component** ```javascript import { AdyenPlatformExperience, CapitalOffer } from '@adyen/adyen-platform-experience-web'; import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css"; const core = await AdyenPlatformExperience({ onSessionCreate: handleSessionCreate, }); const capitalOffer = new CapitalOffer({ core }); capitalOffer.mount('#capital-offer-container'); ``` ### Localize Components ## 4. Optional: Localize components You can configure the components to use one of the [supported languages](#supported-languages). Update your component initialization code to include the localization settings. If no localization settings are provided, the components will default to English. **Localize components** ```javascript import { AdyenPlatformExperience } from '@adyen/adyen-platform-experience-web'; const core = await AdyenPlatformExperience({ locale: 'es-ES', // See supported languages for possible values /* ... */ }); ``` ### Customize Appearance ## 5. Optional: Customize component appearance The capital components have a default appearance with pre-defined styles, such as colors, fonts, and borders. You can customize the appearance of your components by overriding the default values of CSS variables and the class settings: 1. Inspect the components using your browser's developer tools. 2. Modify the styles in your style sheet file. The following tabs show examples of how to style the components. The first example shows how to override predefined CSS variables to use different colors and values. The second example demonstrates how to update the CSS class setting to change the layout of the info box element from a prominent blue background to an inline view with a bottom border. ### Tab: Example 1: Override CSS variables **style.css** ```bash :root { --adyen-sdk-border-radius-s: 10px; --adyen-sdk-border-radius-m: 20px; --adyen-sdk-border-radius-l: 30px; --adyen-sdk-color-background-disabled: #9ecdb1; --adyen-sdk-color-background-inverse-primary: #0abf53; --adyen-sdk-color-background-inverse-primary-hover: #57d389; --adyen-sdk-color-decorative-blue: #0abf53; --adyen-sdk-color-outline-primary-active: #0abf53; } ``` ### Tab: Example 2: Update CSS class settings **style.css** ```bash .adyen-pe-capital-offer-summary__details, .adyen-pe-grant-details .adyen-pe-structured-list { gap: 0; } .adyen-pe-capital-offer-summary__details .adyen-pe-structured-list__item, .adyen-pe-grant-details .adyen-pe-structured-list .adyen-pe-structured-list__item { padding: 6px 4px; } .adyen-pe-capital-offer-summary__details .adyen-pe-structured-list__item:nth-child(even), .adyen-pe-grant-details .adyen-pe-structured-list .adyen-pe-structured-list__item:nth-child(even) { background: #f7f7f8; } ``` ### Use Cases ## Use case examples Here you can find code examples demonstrating how to use the [component instance methods and parameters](#component-methods) for specific use cases in the components' implementation. ** #### Example 1: Show the Capital Overview component based on its state This example demonstrates how to render the **Capital Overview** component based on its state. For instance, if the state is **isUnqualified**, the component will not be rendered. This means that if a user is not yet qualified for grant offers, they will not see the component. You can use the same approach for the **Capital Offer** component. **JavaScript** ```javascript import { AdyenPlatformExperience, CapitalOverview } from '@adyen/adyen-platform-experience-web'; import "@adyen/adyen-platform-experience-web/adyen-platform-experience-web.css"; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capitalOverview = new CapitalOverview({ core }); const { state } = await capitalOverview.getState(); if (state === "isUnqualified") { // Don't render the component } else { capitalOverview.mount('.container'); } ``` ** #### Example 2: Show the Capital Offer component as a standalone This example demonstrates how to integrate the **Capital Overview** component and the **Capital Offer** component on separate pages. This setup allows you to place the **Capital Offer** component in a more prominent location within your user interface, such as on a dashboard page, which can help improve user conversion rates for grant applications. When a user applies for a grant from the dashboard page, they will be redirected to the page featuring the **Capital Overview** component. This component will recognize that a grant has been requested and will show the list of available grants, thus continuing the flow initiated on the previous page. If the user navigates directly to the capital overview page without having requested funds beforehand, the **Capital Overview** component will instead render the section for requesting grants. **JavaScript** ```javascript // Capital overview page import { AdyenPlatformExperience, CapitalOverview } from '@adyen/adyen-platform-experience-web'; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capital = new CapitalOverview({ core }).mount('.container'); // Dashboard page import { AdyenPlatformExperience, CapitalOffer } from '@adyen/adyen-platform-experience-web'; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capital = new CapitalOffer({ core, onFundsRequest: () => { // Redirect to capital overview page } }).mount('.container'); ``` ** #### Example 3: Show the pre-qualified screen as a standalone This example demonstrates how to show an introductory message for pre-qualified users on a dashboard page, while presenting the rest of the flow on a separate page. Both pages use a separate instance of the **Capital Overview** component. The dashboard page features only the introductory message for pre-qualified users. When a user selects the button to apply for a grant, they will be redirected to the page containing the rest of the flow, bypassing the introductory message. **JavaScript** ```javascript // Dashboard page import { AdyenPlatformExperience, CapitalOverview } from '@adyen/adyen-platform-experience-web'; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capital = new CapitalOverview({ core, onOfferOptionsRequest: () => { // Redirect to capital overview page } }).mount('.container'); // Capital overview page import { AdyenPlatformExperience, CapitalOverview } from '@adyen/adyen-platform-experience-web'; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capital = new CapitalOverview({ core, skipPreQualifiedIntro: true, // Default: false }).mount('.container'); ``` ** #### Example 4: Show the grant offer selection screen as a standalone This example demonstrates how to render only the grant offer selection screen of the **Capital Offer** component, which features a dynamic slider. The rest of the flow will be implemented through direct integration with the Adyen API rather than using components. While this approach is not recommended, it does provide the flexibility to use the **Capital Offer** component partially to address your specific needs. **JavaScript** ```javascript import { AdyenPlatformExperience, CapitalOffer } from '@adyen/adyen-platform-experience-web'; import { onSessionCreate } from '../my-platform/utils'; const core = await AdyenPlatformExperience({ onSessionCreate }); const capital = new CapitalOffer({ core, onOfferSelect: () => { // Redirect to the grant offer term sheet screen } }).mount('.container'); ``` ## Supported languages You can set one of the following languages to localize any of the Platform Experience components. | Language | Locale code | Locale file | | --------------- | ----------- | ----------- | | Danish | **da-DK** | **da\_DK** | | Dutch | **nl-NL** | **nl\_NL** | | English | **en-US** | **en\_US** | | Finnish | **fi-FI** | **fi\_FI** | | French | **fr-FR** | **fr\_FR** | | German | **de-DE** | **de\_DE** | | Italian | **it-IT** | **it\_IT** | | Norwegian | **no-NO** | **no\_NO** | | Portuguese (BR) | **pt-BR** | **pt\_BR** | | Spanish | **es-ES** | **es\_ES** | | Swedish | **sv-SE** | **sv\_SE** | ## See also * [Component libraries](/platforms/components-overview) --- # Source: https://docs.adyen.com/capital/keeping-records.md Section: Capital Title: Keeping records Description: Learn about the guidelines for keeping records regarding financial products. --- title: "Keeping records" description: "Learn about the guidelines for keeping records regarding financial products." url: "https://docs.adyen.com/capital/keeping-records" source_url: "https://docs.adyen.com/capital/keeping-records.md" canonical: "https://docs.adyen.com/capital/keeping-records" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Keeping records Learn about the guidelines for keeping records regarding financial products. [View source](/capital/keeping-records.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. While you offer Capital to your users, your platform must keep detailed records regarding your service. Your platform must keep these service records for at least **five years** after the termination of the Capital offering (unless your platform's internal data retention requirements indicate a longer timeframe.) ## Types of records | Record type | Examples | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User experience | Screenshots of deployed versions of the financial product, application flow, user dashboard, support pages | | Marketing | All versions of materials described in (/capital/marketing-user-communication). | | User communications and complaints | Email or website messaging interactions (for example chat or customer support) and documentation related to complaints. Notifications to customers of action taken for loans and charge cards. (UK and IE only)Vulnerable customers: The systems for recording details of customer communications must include the ability to categorise customers as showing signs of vulnerability during an interaction and should include at least the following categorisation options:- **Health**: Physical or mental health conditions that impact a customer's ability to manage their affairs. This could include emotional distress, or any other conditions that means they may require additional support. - **Life Events**: Significant life changes such as bereavement, job loss, or relationship breakdown that can affect resilience and decision-making. - **Resilience**: Low ability to withstand financial or emotional shocks. - **Capability**: Low levels of financial literacy, confidence in managing money, or other relevant skills such as digital literacy. Any communications received from a vulnerable user must be accessible (in accordance with legal requirements) to the staff of the platform responsible for assisting users. | | Statements | Historical statements generated and made available to users | ## See also * [Overview of compliance guidelines](/capital/compliance-guidelines) * [User application and interface](/capital/user-interface) * [Marketing and communication with users](/capital/marketing-user-communication) * [Customer service and support](/capital/customer-service-support) * [Customer complaints](/capital/customer-complaints) --- # Source: https://docs.adyen.com/capital/make-grant-request.md Section: Capital Title: Disburse a grant Description: Learn how to make a request for a grant and disburse the funds to your user's account. --- title: "Disburse a grant" description: "Learn how to make a request for a grant and disburse the funds to your user's account." url: "https://docs.adyen.com/capital/make-grant-request" source_url: "https://docs.adyen.com/capital/make-grant-request.md" canonical: "https://docs.adyen.com/capital/make-grant-request" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Disburse a grant Learn how to make a request for a grant and disburse the funds to your user's account. [View source](/capital/make-grant-request.md) After your user selects a grant offer and signs the Terms of Service, you can make an API request to configure the grant for the user. If the request is successful, then Adyen initiates a transfer to settle the grant funds in your user’s balance account. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | You must have an Adyen for Platforms integration with the Capital financial product enabled. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#manage-api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capabilities](/capital/manage-user-capabilities):- **getGrantOffers** - **receiveGrants** | | **Webhooks** | Subscribe to the following webhooks:- [Capital webhooks](https://docs.adyen.com/api-explorer/capital-webhooks/latest/overview) - [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) | | **Limitations** | * Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). * Currently, only one disbursement per grant is allowed. We are working on enabling multiple disbursements to different balance accounts. | | **Setup steps** | Before you begin, make sure:* You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). * You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. * Your user [selected a grant offer](/capital/get-grant-offers) and [signed the Terms of Service](/capital/terms-of-service). | ## 1. Configure a grant To configure a grant: 1. Make a POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) request, specifying the following parameters: | Parameter | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [counterparty.balanceAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-counterparty-balanceAccountId) | | The identifier of the balance account that belongs to the receiving account holder. Pass this parameter if you choose to pay out to the balance account of the user. | | [counterparty.transferInstrumentId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-counterparty-transferInstrumentId) | | The identifier of the transfer instrument that belongs to the legal entity of the account holder. Pass this parameter if you choose to pay out to the transfer instrument of the user. | | [grantAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-grantAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant account. Reach out to your Adyen contact to get this value. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-grantOfferId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant offer that has been selected by the user. | If `balanceAccountId` is not provided in the request, the grant is paid out to the account holder's [primaryBalanceAccount](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-primaryBalanceAccount). Here's an example of how to request a payout of a grant to the specified balance account. **Disburse a grant** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "grantAccountId": "CG00000000000000000000001", "grantOfferId": "0000000000000001", "counterparty": { "balanceAccountId": "BA00000000000000000000001" } }' ``` 2. In the response, note the following parameters: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-id) | The unique identifier of the grant. | | [grantAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-grantAccountId) | The identifier of the [grant account](#grant-account) used to account for the grant. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-grantOfferId) | The unique identifier for the related grant offer, which determines the grant conditions. | | [counterparty](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-counterparty) | An object containing the details of the receiving account holder. | | [status](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-status) | The status of the grant. | **Response** ```json { "grantAccountId": "CG00000000000000000000001", "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantOfferId": "0000000000000001", "id": "GR00000000000000000000001", "status": { "code": "Requested" }, "balances": { "principal": 0, "fee": 0, "total": 0, "currency": "EUR" } } ``` Requests using POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) are processed asynchronously. You will receive a response to your API request, but you must wait for the [webhook](/capital/make-grant-request?tab=grant_configured_0_1) to know the final result of a request. ## 2. Get updates Adyen will send the webhook messages for the following event types to your server to update you about the grant and fund transfer status. | Event type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.grants.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.created) | The grant has been configured. | | [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) | The grant has been fully repaid, reconfigured, or written off in case the user did not pay back all outstanding funds. | | [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) | The outgoing or incoming grant transfer request has been received. | | [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) | The outgoing or incoming grant transfer request has been authorized and/or booked. | | [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) | The funds have been paid out to the balance account or the payment instrument. | To keep track of webhooks, make sure that your server can [receive and accept webhooks](/development-resources/webhooks). ### Tab: Grant configured After the requested grant has been configured on the Adyen side, you will receive a webhook message with the event type `balancePlatform.grants.created`. **Grant configured webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Requested" } } }, "environment": "test", "timestamp": "2026-01-21T19:56:42.107Z", "type": "balancePlatform.grants.created" } ``` ### Tab: Transfer received After the grant has been configured, you will receive a webhook message with the event type [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) and the `status` **received**. **Incoming transfer received** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "received", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 1, "balances": [ { "currency": "EUR", "received": 1850000 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] } ], "eventId": "EV0000000000000000000000000001" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.created" } ``` ### Tab: Transfer authorised After the grant payout request has been received, you will receive a webhook message with the event type [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) and the `status` **authorized**. **Incoming transfer authorized** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "authorised", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 2, "balances": [ { "reserved": 1850000, "currency": "EUR", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "EUR", "received": -1850000 } ] } ], "eventId": "EV0000000000000000000000000002" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Transfer booked After the grant payout request has been authorized, you will receive another webhook message with the event type [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) and the `status` **booked**. **Incoming transfer booked** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "booked", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 3, "balances": [ { "reserved": 0, "balance": 1850000, "currency": "EUR", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "EUR", "received": -1850000 } ] }, { "id": "EV0000000000000000000000000003", "status": "booked", "transactionId": "EV000000000000000000000000000EUR", "bookingDate": "2025-10-15T18:53:08+02:00", "valueDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": -1850000, "balance": 1850000, "currency": "EUR", "received": 0 } ] } ], "eventId": "EV0000000000000000000000000003" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.36Z", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Grant paid out After the funds have been paid out to the receiving balance account or payment instrument, you will receive a webhook message with the event type `balancePlatform.transaction.created`. **Grant paid out webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3JFBE65XIXOPZ30N", "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": -1850000 }, "balanceAccountId": "BA00000000000000000000001", "bookingDate": "2023-01-09T16:36:35+01:00", "counterparty": { "balanceAccountId": "BA00000000000000000000002" }, "createdAt": "2023-01-09T16:36:34+01:00", "description": "GR00000000000000000000001", "instructedAmount": { "currency": "EUR", "value": -1850000 }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "transferId": "1OUUU768NUBED14V", "valueDate": "2025-10-15T18:54:08+02:00" }, "environment": "test", "type": "balancePlatform.transaction.created" } ``` ### Tab: Grant repaid After the account holder fully repays the grant, you will receive a webhook message with the event type `balancePlatform.grants.updated`. **Grant repaid webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Repaid" } } }, "environment": "test", "timestamp": "2026-01-21T19:59:10.153Z", "type": "balancePlatform.grants.updated" } ``` ## Next steps [Get grant details](/capital/get-grant-balances) [Learn how to get information about all grants in your balance platform.](/capital/get-grant-balances) [Manage disbursements](/capital/manage-disbursements) [Learn how to get and update configurations of a disbursement.](/capital/manage-disbursements) --- # Source: https://docs.adyen.com/capital/manage-access.md Section: Capital Title: Manage access for your team Description: Learn how to manage your integration in your Customer Area. --- title: "Manage access for your team" description: "Learn how to manage your integration in your Customer Area." url: "https://docs.adyen.com/capital/manage-access" source_url: "https://docs.adyen.com/capital/manage-access.md" canonical: "https://docs.adyen.com/capital/manage-access" last_modified: "2023-07-20T12:03:00+02:00" language: "en" --- # Manage access for your team Learn how to manage your integration in your Customer Area. [View source](/capital/manage-access.md) When you first sign up for Adyen, we automatically create an admin user account for your platform. After we create your admin user, you receive an email to verify the account. When you complete the verification, your admin user becomes active. ## Customer Area The Customer Area is an online dashboard that helps you manage your platform integration. In your [Customer Area](https://ca-test.adyen.com/), you can: * Manage your Adyen [resources](/capital/account-structure-resources), such as your company account, merchant account, account holders, balance accounts, and grant accounts. * Manage access for members of your team. * Manage your [API credentials](/development-resources/api-credentials) for your balance platform. * Configure [webhooks](/development-resources/webhooks/configure-and-manage) to get updates on changes in your platform. * View information about your Capital offerings. ## User management Your [Customer Area](https://ca-test.adyen.com/) includes an admin user who has access to all the permissions required to manage your integration. These permissions also enable you to create more user accounts for your team. User accounts allow members of your team to access your Customer Area. With your admin user account, you can provide each user with a specific set of permissions to perform certain actions. You control your user's permissions by assigning roles to them. All users with an Adyen account must set up [Multifactor Authentication (MFA)](/account/multifactor-authentication/) or [Single Sign-On](/account/single-sign-on) in the Customer Area. ### User roles To view information about Capital in the Customer Area, your users need the following role: | Role | The user can... | | --------------------- | -------------------------------------- | | **Capital base role** | View capital grants and grant details. | For more information about how you can manage access for members of your team, see [Manage users](/account/users). ## API credentials To make requests to Adyen's APIs, you must have the appropriate API credentials. When your balance platform account is set up, it includes: * An API credential for web services. * An API credential for legal entity management. For more information on how to manage these credentials, see [API credentials for Balance Platform](/platforms/manage-access/api-credentials-web-service/). A credential for web services has web service (ws) roles assigned to it. These roles specify what API requests a user can perform with this credential. ### Roles for API credentials The following tabs show the most frequently used web service roles that are available in your [Customer Area](https://ca-test.adyen.com/). ### Tab: Balance platform configuration The following table shows roles that you use to make requests for general configuration of your Balance Platform. | Web service role | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Balance Platform BCL role** | You can create, update, and delete resources in your balance platform. For example: account holders, balance accounts, or transfer instruments. | | **Balance Platform BCL PCI role** | You can unmask and view PANs and CVVs/CVCs in the response of a POST [/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments) request.To use this role, you must also have the Balance Platform BCL role enabled. | ### Tab: Capital The following table shows roles that you use to make requests related Adyen Capital. | Web service role | Description | | -------------------------------------------------- | -------------------------------------------------------- | | **Balance Platform Capital Configuration Role** | You can view details of grant offers and grant accounts. | | **Balance Platform Capital Grant Initiation Role** | You can configure grants. | ## Next steps [Integrate with components](/capital/terms-of-service) [Learn how to integrate our prebuilt UI components to accelerate your Capital integration process.](/capital/terms-of-service) [Integrate using APIs](/capital/make-grant-request) [Learn how to use our APIs to build your Capital integration from scratch.](/capital/make-grant-request) --- # Source: https://docs.adyen.com/capital/manage-disbursements.md Section: Capital Title: Manage disbursements Description: Learn how to get and update configurations of a disbursement. --- title: "Manage disbursements" description: "Learn how to get and update configurations of a disbursement." url: "https://docs.adyen.com/capital/manage-disbursements" source_url: "https://docs.adyen.com/capital/manage-disbursements.md" canonical: "https://docs.adyen.com/capital/manage-disbursements" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Manage disbursements Learn how to get and update configurations of a disbursement. [View source](/capital/manage-disbursements.md) After the grant amount is disbursed to your user, you can retrieve information about a particular disbursement and update its configurations. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an Adyen for Platforms integration with the Capital financial product enabled. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capabilities](/capital/manage-user-capabilities):- **getGrantOffers** - **receiveGrants** | | **Limitations** | * Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). * Currently, only one disbursement per grant is allowed. We are working on enabling multiple disbursements to different balance accounts. * Unscheduled repayments are only available for users operating in Europe, the United Kingdom, and the United States. | | **Setup steps** | Before you begin, make sure:* You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). * You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. * Your user [selected a grant offer](/capital/get-grant-offers) and [signed the Terms of Service](/capital/terms-of-service). * You [disbursed at least one grant](/capital/make-grant-request). | ## Get all disbursements of a grant To get all disbursements related to a grant: 1. Make a GET [/grants/{grantId}/disbursements](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements) request with the receiving [grantId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#path-grantId). **Get all disbursements of a grant** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants/GR00000000000000000000001/disbursements \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ ``` 2. In the response, note the following parameters: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-accountHolderId) | The unique identifier of the account holder that received the disbursement. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-amount) | An object containing the amount of the disbursement, in [minor units](/development-resources/currency-codes). | | [balanceAccountId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-balanceAccountId) | The unique identifier of the balance account that received the disbursement. | | [balances](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-balances) | An object containing the balances of the disbursement. | | [fee](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-fee) | An object containing the fee that your user must pay for the disbursement. | | [fundsCollections](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-fundsCollections) | An object containing the accounts that Adyen uses to collect funds related to repayments. | | [grantId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-disbursements-grantId) | The unique identifier of the grant related to the disbursement. | | [disbursementsId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-disbursements-id) | The unique identifier of the disbursement. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements#responses-200-repayment) | An object containing the [basis points](https://www.investopedia.com/terms/b/basispoint.asp) configured for repaying the disbursement. | **Response** ```json { "disbursements": [ { "id": "CPTL00000000000000000000001", "grantId": "GR00000000000000000000001", "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001", "repayment": { "basisPoints": 500 }, "balances": { "principal": -748379, "fee": -74837, "total": -823216, "currency": "EUR" }, "amount": { "value": 748379, "currency": "EUR" }, "fee": { "amount": { "value": 74837, "currency": "EUR" } }, "fundsCollections": [ { "fundsCollectionType": "UnscheduledRepayment", "accountIdentification": { "type": "iban", "iban": "NL000000000001" } } ] } ] } ``` ## Update repayment configuration of a disbursement You can update the repayment configuration of a specific disbursement. Specifically, you can change the percentage of your user's incoming net volume that is deducted for repaying the grant. To do this: 1. Make a PATCH [/grants/{grantId}/disbursements/{disbursementId}](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)) request specifying the following parameters: | Parameter | Parameter type | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [disbursementId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#path-disbursementId) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the disbursement. | | [grantId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#path-grantId) | Path | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant reference. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#request-repayment) | Request | | An object containing the [basis points](https://www.investopedia.com/terms/b/basispoint.asp) configured for repaying the disbursement. | Here's an example of how to update the repayment configuration of a specific disbursement. **Update repayment configuration of a disbursement** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants/GR00000000000000000000001/disbursements/CPTL00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "repayment": { "basisPoints": 5000 } }' ``` 2. In the response, note the following parameters: | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-accountHolderId) | The unique identifier of the account holder that received the disbursement. | | [amount](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-amount) | An object containing the amount of the disbursement, in [minor units](/development-resources/currency-codes). | | [balanceAccountId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-balanceAccountId) | The unique identifier of the balance account that received the disbursement. | | [balances](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-balances) | An object containing the balances of the disbursement. | | [fee](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-fee) | An object containing the fee that your user must pay for the disbursement. | | [fundsCollections](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-fundsCollections) | An object containing the accounts that Adyen uses to collect funds related to repayments. | | [grantId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-grantId) | The unique identifier of the grant related to the disbursement. | | [disbursementId](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-disbursementId) | The unique identifier of the disbursement. | | [repayment](https://docs.adyen.com/api-explorer/capital/latest/patch/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-repayment) | An object containing the [basis points](https://www.investopedia.com/terms/b/basispoint.asp) configured for repaying the disbursement. | **Response** ```json { "id": "CPTL00000000000000000000001", "grantId": "GR00000000000000000000001", "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001", "repayment": { "basisPoints": 5000 }, "balances": { "principal": -639, "fee": -89, "total": -728, "currency": "EUR" }, "amount": { "value": 639, "currency": "EUR" }, "fee": { "amount": { "value": 89, "currency": "EUR" } }, "fundsCollections": [ { "fundsCollectionType": "UnscheduledRepayment", "accountIdentification": { "type": "iban", "iban": "NL000000000001" } } ] } ``` ## Retrieve bank account details for unscheduled repayments Users can make unscheduled payments to repay their grant using the dedicated bank account details (for example, IBAN) assigned to each disbursement. You can retrieve these bank account details by making an API call. Then, you can share the information with your users. To retrieve bank account details for a particular disbursement: 1. Make a GET [/grants/{grantId}/disbursements/{disbursementId}](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)) request, specifying the following path parameters: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------ | | [disbursementId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)#path-disbursementId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the disbursement. | | [grantId](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)#path-grantId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant reference. | **Retrieve bank account details for unscheduled repayments** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants/GR00000000000000000000001/disbursements/CPTL00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X GET \ ``` 2. In the response, note the [fundsCollections](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-fundsCollections) object containing the following parameters: | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [fundsCollections.accountIdentification](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-fundsCollections-accountIdentification) | An object containing the identification information of the account to which your user can transfer funds related to unscheduled repayments. For example, the international bank account number (IBAN). | | [fundsCollections.type](https://docs.adyen.com/api-explorer/capital/latest/get/grants/\(grantId\)/disbursements/\(disbursementId\)#responses-200-fundsCollections-fundsCollectionType) | The type of funds collection. Must be set to **UnscheduledRepayment**. | **fundsCollections object** ```json { "fundsCollections": [ { "fundsCollectionType": "UnscheduledRepayment", "accountIdentification": { "type": "iban", "iban": "NL000000000001" } } ] } ``` ## See also * [Grant lifecycle and status](/capital/grant-lifecycle-and-status) * [Get grant details](/capital/get-grant-balances) --- # Source: https://docs.adyen.com/capital/manage-user-capabilities.md Section: Capital Title: Manage user capabilities Description: Learn about the capabilities your user must have to get business financing and how to manage them. --- title: "Manage user capabilities" description: "Learn about the capabilities your user must have to get business financing and how to manage them." url: "https://docs.adyen.com/capital/manage-user-capabilities" source_url: "https://docs.adyen.com/capital/manage-user-capabilities.md" canonical: "https://docs.adyen.com/capital/manage-user-capabilities" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Manage user capabilities Learn about the capabilities your user must have to get business financing and how to manage them. [View source](/capital/manage-user-capabilities.md) Your users are represented by an account holder resource in your balance platform. Each account holder is associated with a set of capabilities that determine what they can do on your platform. To access business financing with Adyen Capital, users must have *capital capabilities*. In most cases, Adyen configures the necessary capabilities during the [design phase](/capital/get-started#design-implementation) of your Capital integration. These capabilities are then automatically requested for your users when you create account holders for them. However, you can request these capabilities later and enable or disable them for individual account holders if needed. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | You must have an Adyen for Platforms integration with the Capital financial product enabled. | | **API credentials** | To manage user capabilities through the API, you must have a [Balance Platform API key](/capital/manage-access#api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). Your API credential must have the following role:- **Balance Platform BCL role** | | **Customer Area roles** | To manage user capabilities in the Customer Area, you must have the following [user role](/account/user-roles#platforms):- **Manage account holder capabilities** | | **Limitations** | Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). | | **Setup steps** | Before you begin, make sure:- You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). - You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. - You read our documentation about [capability settings](/platforms/verification-overview/capabilities#capability-settings) and [capability verification statuses](/platforms/verification-overview/capabilities#verification-status-of-a-capability). | ## Capital capabilities Adyen Capital requires your user's account holder to have the following capabilities: | Capability name | Display name in Customer Area | Description | | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **getGrantOffers** | Receive grant offers | Allows users to receive offers for business financing based on the volume of their payment processing. When you request this capability for a user, Adyen evaluates their eligibility for business financing. When the user qualifies and the capability is [allowed](/platforms/verification-overview/capabilities#capability-settings), Adyen generates [grant offers](/capital/get-grant-offers) for them. | | **receiveGrants** | Receive grants | Allows users to receive business financing funds from Adyen. When you request this capability, Adyen verifies whether the account holder has signed the [Terms of Service](/capital/terms-of-service). When they have and both `getGrantOffers` and `receiveGrants` capabilities are [allowed](/platforms/verification-overview/capabilities#capability-settings), you can proceed to [disburse the funds](/capital/make-grant-request) to your user. | ## Request a capability If needed, you can request capabilities for your account holders in your Customer Area or using the Configuration API. The following tabs show how to request a capability. ### Tab: Customer Area To request a capability for an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab and select **+ Request new capability**. 3. From the dropdown menu, select a capability and, if applicable, its level. 4. Select **Submit**. 5. On the confirmation window, select **Submit request**. The capability request is sent to Adyen for approval. ### Tab: API To request a capability for an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a PATCH [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)) request, specifying the key-value pairs for each capability in the [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)#responses-200-capabilities) object. Set the [requested](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)#request-capabilities-requested) parameter to **true**. Here is an example of how to request the `getGrantOffers` capability for an existing user. If you are requesting multiple capabilities, add another set of key-value pairs. **Request a capability** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "capabilities" : { "getGrantOffers" : { "requested" : true } } }' ``` 2. In the response, note the following parameters and their respective values for the capability: * `requested`: **true** * `allowed`: **false** * `verification status`: **pending** **Response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "id": "AH00000000000000000000001", "legalEntityId": "LE00000000000000000000001", "description": "S.Hopper", "capabilities": { "getGrantOffers": { "requested": true, "allowed": false, "verificationStatus": "pending" } } } ``` ## View capabilities You can view an account holder's capabilities and their verification status in your [Customer Area](https://ca-test.adyen.com/) or by making a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request. The following tabs explain both methods. ### Tab: Customer Area To view capabilities of an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab. You can view the capabilities that are enabled, allowed and their verification status. ### Tab: API To view the capabilities of an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a GET [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)) request. 2. In the [capabilities](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities) object of the response, note the following parameters and values that are listed for each capability: * [allowed](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-allowed): Boolean that indicates whether the capability is allowed. The possible values are **true** or **false**. * [enabled](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-enabled): Boolean that indicates whether the user can use the capability. The possible values are **true** or **false**. * [verificationStatus](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-verificationStatus): The status of the checks. The possible values are **invalid**, **pending**, **rejected**, or **valid**. * [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) array: When this array is not empty, this means that there are errors that you need to address. Refer to [verification error codes](/capital/kyc-verification-codes) for a list of verification errors. ## Enable or disable a capability To allow or prevent an account holder from using a capability, update the capability in your [Customer Area](https://ca-test.adyen.com/) or make an API request. The following tabs explain both methods. ### Tab: Customer Area To enable or disable a capability for an account holder in your [Customer Area](https://ca-test.adyen.com/): 1. Do one of the following: * Go to **Accounts & balances** > **Account holders** and select an account holder ID from the table. * Search for an account holder by selecting **Search**. You can use the account holder ID, account holder reference, or the ID of the linked legal entity. 2. On the **Account holder details** page, select the **Capabilities** tab and select **Edit**. 3. In the **Enabled** column: * Select the corresponding checkbox to *enable* the capability. * Clear the corresponding checkbox to *disable* the capability. 4. Select **Save**. 5. On the confirmation window, select **Save changes**. ### Tab: API To enable or disable a capability for an account holder using the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview): 1. Make a PATCH [/accountHolders/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)) request specifying the following parameter for a capability: * [enabled](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-enabled): Set this to **true** or **false** to enable or disable the capability, respectively. Here is an example of how to disable the `getGrantOffers` capability for an account holder. If you are requesting multiple capabilities, add another set of key-value pairs. **Disable a capability** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "capabilities": { "getGrantOffers": { "enabled": false } } }' ``` 2. In the response, note the following parameters and their respective values for each capability: * `enabled`: **false** * `allowed`: **true** * `verification status`: **valid** **Response** ```json { "balancePlatform": "YOUR_BALANCE_PLATFORM", "id": "AH00000000000000000000001", "legalEntityId": "LE00000000000000000000001", "description": "S.Hopper", "capabilities": { "getGrantOffers": { "enabled": false, "allowed": true, "verificationStatus": "valid" } } } ``` ## Next steps [Integrate with components](/capital/terms-of-service) [Learn how to integrate our prebuilt UI components to accelerate your Capital integration process.](/capital/terms-of-service) [Integrate using APIs](/capital/make-grant-request) [Learn how to use our APIs to build your Capital integration from scratch.](/capital/make-grant-request) --- # Source: https://docs.adyen.com/capital/marketing-user-communication.md Section: Capital Title: Material for marketing and communication with users Description: Learn about the requirements and review process for your collateral material about your Capital offering. --- title: "Material for marketing and communication with users" description: "Learn about the requirements and review process for your collateral material about your Capital offering." url: "https://docs.adyen.com/capital/marketing-user-communication" source_url: "https://docs.adyen.com/capital/marketing-user-communication.md" canonical: "https://docs.adyen.com/capital/marketing-user-communication" last_modified: "2023-12-14T12:09:00+01:00" language: "en" --- # Material for marketing and communication with users Learn about the requirements and review process for your collateral material about your Capital offering. [View source](/capital/marketing-user-communication.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. ### Marketing Materials Collateral material is defined as all communication that the user sees in relation to Adyen's offering through your platform’s interface. We also refer to this communication as *collateral material*. Collateral materials can include, but are not limited to: * Platform web pages, * Platform user interface pages (for example, application flow, customer dashboard, support pages), * Platform marketing communications, * Platform communication to users, * User statements, * Direct mail advertisements, * Other print or media advertisements, * Press or media releases, * Advertisements, * Materials accompanying card distribution(carriers, pin mailers, proprietary packaging) * Physical or Virtual Card Proofs * App store descriptions and screenshots of platforms All collateral material used by the platform must: * Adhere to the general principles listed below for each product offering; and * Include relevant bank disclosures (as detailed in Adyen’s Disclosure and Consent Procedure) for each service offered. For all financial products, all collateral material used by the platform must: * Be reviewed and pre-approved by Adyen before publishing or distributing; * Resubmitted for approval to when changes are made, excluding typographical or grammatical error changes. Changes that do not impact the description or marketing of the Adyen product or service content do not need to be resubmitted for approval. Content can be submitted for use in multiple collateral materials. * Any additional collateral material that the platform wishes to publish following go-live should also be submitted for approval to . ### General Principles #### Communication style * All collateral material must be written in plain language. * Material must be tailored to the target customer, in accordance with their level of sophistication; non-sophisticated customers generally require simpler (jargon-free) communication. * All collateral material should present terms, benefits, limitations, availability and risks of the Service line adequately, accurately, clearly and conspicuously. Collateral materials must not make claims, representations, or statements that are misleading to the target customer. * All representations within the collateral materials should be reasonable and factual. If claims are made that require additional data to support them, source or disclose the additional data. Any research, statistics or claims quoted in collateral materials must be substantiated and refer in the advertisement to the source of the research or statistics, or grounds for the claim, including the date of the research or statistics and any assumptions that have been made based on the research, statistics or claims. * Where used, the collateral material must explain the meaning of any abbreviations or acronyms. * Where more than one financial service is advertised in collateral material, the collateral material must clearly distinguish which service the provided information relates to. #### Testimonials * If using testimonials or endorsements in collateral materials, the testimonial must be a real customer, using the Service they are talking about. The testimonial or endorsement must be attributed to the author of the statement and correctly dated. Permission must be obtained in writing to use the testimonial or endorsement. If any money was paid to the customer for the testimonial or endorsement, a disclaimer must be included stating this fact. * Any comparisons or contrasts in the information provided in collateral material must either be based on verified facts or reasonable assumptions stated within the advertisement. The comparisons or contrasts must be specified in a clear, fair and balanced way and not omit any key information. * The collateral material should include a reference to the Platform’s contact information (i.e., phone number, website address, or email address). #### Vocabulary to avoid * Avoid using exaggerated or unsubstantiated claims or absolute statements that are hard to prove. For example: "all", "never", "always", "fastest", "cheapest", "lightning speed", "prevents all fraud". * Avoid the use of the term "free" if there are charges, costs or fees that may be outlined in user terms. * Avoid using terms such as "pre-approved" or "guaranteed". If using those terms, it must be clear if there are any limitations, conditions, or restrictions on the offer. However, the term "pre-qualified" may be used. * Avoid using terms such as "protected" or "secure". If using those terms, it must be clear if there are any limitations, conditions, or restrictions on the offer. * Materials must not require a consumer credit check or consumer credit report or infer that a consumer credit check is performed in order to grant the product. Forbidden content: * Collateral material must not include language or images that are profane, sexual or political in nature, are offensive, including to racial or religious classes, or language that is defamatory towards other third parties. Format/Layout: * The design and format of all collateral material must not obscure or disguise any key information concerning the service. Key information must always be confirmed in writing. * Any disclosures in the collateral material must be done in the predominant font size, i.e., a font size large enough to read and in a color that visibly contrasts with the background. * Recommended: 8-point font for paper materials; 10-point font for online materials * Key information or disclosures should not be buried in other non-key disclosures or footnotes. Footnotes shall only be used to supplement or elaborate on the key information included in the body text. * Recommended: footnotes should be no more than 2 points smaller than the font size used for the body of the text * All communications should be accessible to users of differing abilities (for example, all websites should be compatible with text-to-speech technology). * Collateral materials may only include a hyperlink linking to information that forms part of the advertisement where the advertisement containing the link specifies the name of the advertised financial service and/or an invitation to discuss the financial service in more detail. In addition, the hyperlink must be displayed prominently and link directly to the additional information on a single webpage. #### Specific disclosures for countries/regions * (UK only) Platforms shall include on their webpage or application a clear explanation on the role of Adyen as provider of the regulated financial service versus the role of the platform. Example below: * "*To facilitate payments and offer financial products, \[Platform] works together with Adyen UK, which is authorised by the Prudential Regulatory Authority and the Financial Conduct Authority.*" * More information on Adyen and its offering can be found in the FCA’s register (firm number [779800](https://register.fca.org.uk/s/firm)) and [Adyen's United Kingdom page](https://www.adyen.com/en_GB/). * (Ireland only): Any webpage on the Platform’s website that relates to a financial service offered in partnership with Adyen, that is accessed from someone based in Ireland, must display the following statement: * "*We work with Adyen N.V. to offer financial services. Adyen N.V., trading as Adyen, is authorised by De Nederlandsche Bank in the Netherlands and is regulated by the Central Bank of Ireland for consumer protection rules.*" ## Product-specific requirements ### Collateral material review principles for Issuing | Representation | EU | UK | US | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Platform’s Card Program Name and network name text the same size | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | (Prepaid Cards Only): Language must not suggest the card is a bank card/bank account card. Note, this requirement **does not apply** to Debit Cards. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | An issuing statement is required to appear anytime the card, payment scheme/network brand marks or logo is portrayed, identified or displayed in any form of collateral. A program can work with Adyen to request a variance from the Schemes. Please refer to each network’s guidelines for approved variances of the below statements. EU - Mastercard: "*This card is issued by Adyen N.V. pursuant to license by Mastercard International.*" - Visa: "*This card is issued by Adyen N.V, pursuant to a license from Visa Europe Limited.*"UK - Mastercard: "*This card is issued by Adyen N.V. London Branch pursuant to license by Mastercard International.*" - Visa: "*This card is issued by Adyen N.V. London Branch, pursuant to a license from Visa Europe Limited.*"US In-House Issuing Programs - Mastercard: "*\[Program name] Mastercard® \[Prepaid Card/Debit Card/Credit Card] is issued by Adyen N.V. pursuant to license by Mastercard International.*" - Visa: "*\[Program name] Visa® \[Prepaid Card/Debit Card/Credit Card] is issued by Adyen N.V. , pursuant to a license from Visa U.S.A. Inc.*" | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For physical and virtual cards, the network standards must be met for required elements, prohibited elements, and card images. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | The use of cards in any marketing material or advertisements must meet network standards and card image standards. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | USA PATRIOT Act must be disclosed when an individual’s personal information is collected. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | PREPAID Card Programs: Use language promoting the benefits of the card such as "better than cash", "spend only what you load", "spend only what you have on the card". Avoid using phrases like "better than credit", "no interest", "no debt", "debit card", "credit card". | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For General Purpose Reloadable (GPR) Prepaid Cards Programs: The card must not be marketed or labeled as a gift card or gift certificate, meaning either directly or indirectly offering, advertising or otherwise suggesting the potential use of a general-use prepaid card as a gift for another person. Examples of marketed or labeled as a gift card or gift certificate include: - Using the word "gift" or "present" on a card or accompanying material, including documentation, packaging and promotional displays; - Representing or suggesting that a card can be given to another person, for example, as a "token of appreciation" or a "stocking stuffer," or displaying a congratulatory message on the card or accompanying material; - Incorporating gift-giving or celebratory imagery or motifs, such as a bow, ribbon, wrapped present, candle, or a holiday or congratulatory message, on a card, accompanying documentation, or promotional material. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | For Business-Purpose Card Programs: Indicate that the card can be used for "business needs" or "commercial needs" and can not be used for personal, family, or household purposes. Avoid using phrases like "Use card program for anything you want", "personal cards", "use these cards like a payday loan". Do not use consumer use cases in Collateral materials. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Collateral material must truthfully reflect the program scope and specifications agreed upon in the Card Service Agreement. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Any use of the Visa and Mastercard Marks must not degrade, devalue, denigrate, or cause injury or damage to the Marks or the Schemes in any way. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Platform must not use "bank" or "banking" in their website name. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | If the Platform uses "bank" or "banking" in any materials, there must be a disclosure stating that the program is not a bank and the program is provided by Adyen, N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Collateral material review principles for Business Accounts | Representation | EU | UK | US | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Platform must not use "bank" or "banking" in their website name or infer that the Platform itself is the provider of the bank account. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Platform cannot use the word "bank account" but solely "business account" or "e-money account". | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Platform cannot state "open a \[Platform] bank account" or similar language. There must be a disclosure stating that the Platform is not a bank and that the account is a business account provided by Adyen, N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Any FAQ must explain that the accounts are held at: - Adyen, N.V. (EU) - Adyen N.V. London Branch (UK) - Adyen N.V. San Francisco Branch(US) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Provide disclosure that: In the EU, Adyen N.V. is registered with the Dutch deposit guarantee scheme register and eligible funds up to EUR 100,000 are legally protected by the Dutch deposit guarantee scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Provide disclosure that: Business Accounts offered by Adyen N.V. London Branch include issuance of electronic money. Electronic money is not a deposit and therefore not protected by the Financial Services Compensation Scheme. | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Must distinguish that the account is not FDIC Insured using the approved statement below: Adyen Business Bank Accounts in the U.S. are not insured by the FDIC and are not guaranteed by the Federal Government. If Adyen places deposits in a cash sweep program utilizing FDIC insured depository institutions, such deposits may be covered by FDIC insurance up to applicable limits in accordance with the FDIC rules, including those relevant to the aggregation of multiple accounts. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Collateral material Review Principles for Adyen Capital #### Loans | Representation | EU | US | AU | UK | CA | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Disclose that Capital is provided by Adyen N.V. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | | Disclose that Capital is provided by Adyen N.V. London Branch | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Disclose that Capital is provided by Adyen Australia Pty Limited Adyen Capital is provided by Adyen Australia Pty Limited ABN 55 162 682 411. Adyen Capital is offered exclusively for business purposes and not for any personal, domestic or household use. Minimum qualifications and eligibility may change from time to time. Adyen reserves the right to withhold Adyen Capital from users who do not meet minimum qualifications. Please see full terms and conditions. | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | Include the disclosure: "*Loans are issued by Adyen N.V. San Francisco Branch and subject to credit approval.*" | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | Include disclosure: "*Please note that Loans provided by Adyen do not qualify as regulated credit agreements under the Consumer Credit Act.*" | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | Disclose that Capital is provided by Adyen Canada Ltd. | | | | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Disclose that the rate charged for Capital is fixed. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | | #### Merchant Cash Advances (UK only) * Do not misrepresent a cash advance as a loan. * Do not make reference or compare to other loan products or products that have a credit element. * Disclose that Capital is provided by Adyen N.V. London Branch * If a communication names the FCA, PRA or both as the regulator of Adyen, make clear that Merchant Cash Advances are not regulated by the FCA, PRA or both. * Include disclosure: "*Please note that Merchant Cash Advances provided by Adyen do not qualify as regulated credit agreements.*" --- # Source: https://docs.adyen.com/capital/pricing-and-eligibility.md Section: Capital Title: Pricing and eligibility Description: Learn how to disclose prices, fees, and requirements for Capital. --- title: "Pricing and eligibility" description: "Learn how to disclose prices, fees, and requirements for Capital." url: "https://docs.adyen.com/capital/pricing-and-eligibility" source_url: "https://docs.adyen.com/capital/pricing-and-eligibility.md" canonical: "https://docs.adyen.com/capital/pricing-and-eligibility" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Pricing and eligibility Learn how to disclose prices, fees, and requirements for Capital. [View source](/capital/pricing-and-eligibility.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. To offer Capital to your users, you must clearly explain to them: * [The pricing information of the service](#pricing) * [The eligibility requirements to use the service](#eligibility) ## Pricing In addition to the Adyen supplied agreements, the platform’s terms of service and fee schedule must clearly outline the fees and terms that the platform implements as part of the services program. * (EU and US only) Any increase to user fees charged for an Adyen product must be disclosed to the affected users in writing at least 30 days before the increased fee takes effect. * (UK only) Any increase to user fees charged for an Adyen product must be disclosed to the affected users in writing at least 60 days before the increased fee takes effect. ### Product-specific requirements #### Adyen for Platforms * Disclosure of fees: the platform may charge the user additional fees provided those fees are disclosed to the user in advance of enrollment in the product. * Foreign Exchange (FX): platforms must provide users with a sufficiently clear presentation of costs so that they understand the FX rate and any associated fees both at the point the user confirms they want to convert funds, and in any statement for the period or in a transaction overview in the UI. For additional examples, see the Foreign Exchange Fees section. * Cost and Fee Access: all fees and costs must remain available on request of the user. * (Only for UK) Reasonable Fees: All fees and costs must be reasonable and appropriate. #### Issuing and Bank Accounts * Disclosure of fees: the platform may charge the user additional fees provided those fees are disclosed to the user in advance of enrollment in the product. * Pre-Approval of fees: all fees and costs user is charged by the platform shall be notified to and agreed with Adyen in advance of enrollment in the product. * Cost and Fee Access: all fees and costs must remain available on request of the user. * Reasonable Fees: All fees and costs must be reasonable, appropriate and in line with the actual costs of the platform’s services. #### Business Accounts (EU & UK) * No additional fees for instant payments: the platforms may not impose fees for instant payments which are higher than fees for regular payments. Instant and regular payments must be subject to the same pricing. #### Capital The platform may not charge directly or indirectly additional fees to the user for Adyen Capital. Fees may also not be discounted without prior written approval from Adyen. ## Eligibility In general, the platforms must not be applying additional eligibility criteria for bank accounts, Capital, and Issuing beyond Adyen’s defined requirements. However, if a Platform has additional eligibility requirements for their users to request accounts, Capital or issued cards, those requirements should be submitted to Adyen for review that they have been properly disclosed to the user. Requirements: * Disclosure of requirements: the platform must clearly disclose any platform-specific eligibility requirements to users before offering the product to them. * Reasonable eligibility requirements: Platform specific eligibility requirements must not be discriminatory, unfair, or deceptive. ### Pricing onboarding questionnaire (UK only) In order to assess whether the proposed fees by the platformare reasonable, the platforms are required to respond to the following questions when onboarding | Order for question | Question | | | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | - | - | | 1. | Provide a detailed description of the pricing model and the fees (description + amount) you charge your customer for using your Platform/services. Outline the expected total price to be paid by a customer. This should include a breakdown of any product or feature fees, fixed/variable fees, subscriptions, commissions, service charges, penalty fees, lock-ins or other fees by the customer. | * Adyen for Platforms * Bank Accounts; * Card Issuing; | | | | 2. | Do you charge a specific fee for the payment processing services offered by Adyen? If yes please indicate the amount. | - Adyen for Platforms | | | | 3 | If yes to #3 - Are you charging a blended or interchange fee model? If so, how do you determine which pricing model is offered to whom? (for example, the annual volume is greater than a certain GBP total or by request) | * Adyen for Platforms | | | | 4. | What are the parameters/criteria you base your rate on? What determines where a merchant’s pricing falls within those parameters/criteria? | - Adyen for Platforms | | | | 5. | What is your pricing strategy for Business Accounts? Describe whether you charge for account opening, a monthly account fee, execution of payment transactions, etc. | * Bank Accounts | | | | 6. | What is your pricing strategy for Card Issuing product? Describe whether you charge any fee per card issued, per transaction, etc. | - Card Issuing | | | | 7. | Do you charge any specific fees for foreign exchange services? | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | | 8. | What, if any, discounts, incentives, or promotions, specifically in relation to Adyen's services? | - Adyen for Platforms/li> - Bank Accounts; - Card Issuing | | | | 9. | What, if any, processes do you have in place for reviewing pricing for existing customers? If applicable, please describe the frequency and review process. | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | | 10. | How do you ensure your pricing strategy is fair and transparent? Explain how you internally assess fairness in pricing (e.g., competitive research, customer research/feedback, regulatory caps, A/B-testing,...). | - Adyen for Platforms/li> - Bank Accounts; - Card Issuing | | | | 11. | How do you communicate pricing information to customers to ensure clarity and understanding? Explain the methods used to disclose fees, ensuring customers are fully informed before purchase. Where available, provide copies of such communication. | * Adyen for Platforms/li> * Bank Accounts; * Card Issuing | | | ## See also * [Overview of compliance guidelines](/capital/compliance-financial-products) --- # Source: https://docs.adyen.com/capital/repayment.md Section: Capital Title: Repayment Description: Learn how to make payments toward your user's business financing balance. --- title: "Repayment" description: "Learn how to make payments toward your user's business financing balance." url: "https://docs.adyen.com/capital/repayment" source_url: "https://docs.adyen.com/capital/repayment.md" canonical: "https://docs.adyen.com/capital/repayment" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Repayment Learn how to make payments toward your user's business financing balance. [View source](/capital/repayment.md) By default, Adyen deducts a fixed percentage from each sale to repay the outstanding grant amount. This process is known as *scheduled* (regular) repayment. Your users can also make *unscheduled* repayments, such as paying off their grant early or covering missed payments. This option requires additional steps from you. Both scheduled and unscheduled repayment options are available with any integration method, whether you use UI components or the API. This page explains how to make payments toward your users' business financing balances. ## Scheduled repayments With scheduled repayments, we reserve a fixed percentage of funds from the net captured volume immediately upon capture. The net captured volume is calculated as the funds captured minus the funds refunded or charged back. At the end of each [sales day](https://docs.adyen.com/platforms/settle-funds#sales-day-settlement/?target=_blank), we deduct the reserved funds from your user's balance account as part of the repayment process. If the net captured volume for a specific day is negative, we release the reserved amount for that day. On these days, we do not trigger any repayments due to the release. To monitor that repayments are made on time, we calculate a *threshold amount*. This threshold represents the minimum repayment we expect the user to make each 30-day period to ensure the entire grant amount is repaid within the maximum repayment term. If the total repayment within a 30-day period falls under this threshold, we may take additional steps to secure timely repayment. ## Unscheduled repayments This feature is currently only available for users operating in Europe, the United Kingdom, and the United States. Users can make unscheduled repayments by transferring funds to the dedicated bank account, such as an IBAN, assigned to each disbursement. You can obtain dedicated bank account details in two ways, depending on your Capital implementation: * For API-only implementations, [retrieve the bank account details](/capital/manage-disbursements#unscheduled-repayments) through an API call and share them with your users. * With UI components, users can view and copy bank account details for their active grant directly in the interface. This feature is available from library version 1.4.0. Refer to the [standard user flow](/capital/capital-components/?component=Capital\&integration=components\&version=1.5.x#standard-user-flow) for more information. After users have the bank details, they can transfer repayment funds from their verified bank account (transfer instrument). ## See also * [Grant lifecycle and status](/capital/grant-lifecycle-and-status) * [Webhook structures and types for Capital](/capital/webhook-types) --- # Source: https://docs.adyen.com/capital/reporting-to-adyen.md Section: Capital Title: Notification and reporting to Adyen Description: Learn what situations to notify Adyen of and what reports to submit periodically. --- title: "Notification and reporting to Adyen" description: "Learn what situations to notify Adyen of and what reports to submit periodically." url: "https://docs.adyen.com/capital/reporting-to-adyen" source_url: "https://docs.adyen.com/capital/reporting-to-adyen.md" canonical: "https://docs.adyen.com/capital/reporting-to-adyen" last_modified: "2024-01-10T12:09:00+01:00" language: "en" --- # Notification and reporting to Adyen Learn what situations to notify Adyen of and what reports to submit periodically. [View source](/capital/reporting-to-adyen.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. If your platform offers Capital, there are specific situations that you must notify Adyen of when they occur. There are also certain reports that you must submit to Adyen. ## When to notify Adyen Platforms must notify Adyen immediately (within 1-2 business days) in the following instances: * The platform receives a Security, Regulatory or Legal Complaint. You must notify Adyen of these complaints, using the [dedicated template](/capital/reporting-to-adyen/Adyen_Complaints_Reporting.xlsx) for complaints reporting. Also see [How to make a complaint](https://www.adyen.com/contact/complaint). * Customer Support Circumstances (these are to be raised through normal Adyen support lines): * The platform, acting reasonably, cannot resolve a user’s request for support. * Any unauthorised use, loss/theft of personal security credentials, (potential) fraud, or illegal/suspicious activity. This applies whether it was reported by the user to the platform or by the software or systems of the platform. * Any (dispute raised by the user about) unauthorised payment or an error on an account statement. * A material incident, potential security breach or personal data breach. * Any explicit statement made from a user through customer support channels that they are facing difficulties repaying the loan. * Any material non-compliance by a user that the platform has become aware of or should have been reasonably aware of. For notifications that can be made through API requests, such as a request to block or terminate an account, no additional reporting is required. ## Daily reporting The following information must be submitted by the platform to Adyen daily for each of the services available when such instances occur: * Number of fraud related incidents/disputes (including transactions charged back due to fraud-related reasons and transactions for which fraud losses were recovered by a means other than a chargeback) and subsequent reason codes/descriptions in accordance with Adyen’s API. For fraud reporting, the platform can choose to either integrate with the Disputes API or send reports to an email address communicated by Adyen. ## Periodic reporting To the extent not prohibited by any applicable law, the platform must share reporting with Adyen on a quarterly basis (using the template provided by Adyen) of all users’ complaints that relate to Adyen products. The quarterly reporting period commences on the date of onboarding of the first user in your live environment. The following information must be contained in the quarterly reports: * The date of receipt of the complaint * The date complaint was acknowledged by the platform as received * Current status of the complaint * The date complaint was resolved * The date a resolution was communicated to the customer (if a complaint has been resolved) * Complaint outcome (upheld or not upheld) * User name * User legal entity reference * Country of the user * Brief description of the complaint * Product to which the complaint relates (if applicable) * Complaint category (the substance of the complaint) * Description of steps taken to resolve the complaint * Complaint determination of either "Upheld" or "Not upheld" before they can be closed * "Upheld" means that the platform agrees that there have been failings and that the customer's complaint is justified in whole or in part. * "Not Upheld" means that the platform has not identified any failings and does not agree that the customer's complaint is justified. The template must be sent to within the following deadlines for each quarter: * 10 January * 10 April * 10 July * 10 October ### UK & Ireland Complaint reporting must contain the number of users who are vulnerable, including the following information: | Data point | Explanation | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Total number of users tagged as vulnerable | Where a user is identified as vulnerable per our training, this should be recorded in the platform CRM system to ensure that the user continually receives the additional support that they need for as long as it is needed. | | Total number of users flagged as vulnerable broken down by categorisation of vulnerability | The user’s specific vulnerability should be recorded under one of these four categories (Health, Life Events, Resilience, and Capability) to allow Adyen to better understand the types of vulnerability Adyen and the platform need to account for when building products and supporting their customers. | | Outcomes of any user requests for specific additional support | If a user requests specific support such as having information presented in a different way to accommodate their needs, or for more time to make a decision, this request should be documented and the outcome recorded. The outcome should cover the actions taken by the platform to accommodate the user’s needs, and details of any relevant follow-up requests from the user. | Reports must be provided in accordance with the same deadlines outlined for quarterly complaints reporting and sent to complaintreports\@adyen.com. Only the total figures for vulnerable users are required. In addition, the platform is required to share with Adyen annually any specific patterns of vulnerability they have identified within their customer base that the platform believes may require Adyen’s attention or further action. ## See also * [Overview of compliance guidelines](/capital/compliance-guidelines) * [Customer service and support](/capital/customer-service-support) * [Customer complaints](/capital/customer-complaints) * [Keeping records](/capital/keeping-records) --- # Source: https://docs.adyen.com/capital/terms-of-service.md Section: Capital Title: Show the Terms of Service document Description: Get your users to accept Adyen's Terms of Service --- title: "Show the Terms of Service document" description: "Get your users to accept Adyen's Terms of Service" url: "https://docs.adyen.com/capital/terms-of-service" source_url: "https://docs.adyen.com/capital/terms-of-service.md" canonical: "https://docs.adyen.com/capital/terms-of-service" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Show the Terms of Service document Get your users to accept Adyen's Terms of Service [View source](/capital/terms-of-service.md) Your user must accept the Terms of Service (ToS) before Adyen can pay out the grant. After your user accepts the required Terms of Service, the `receiveGrants` [capability](/capital/manage-user-capabilities#capital-capabilities) is enabled for them. You can choose to have your user accept the ToS either before or after receiving the [grant offers](/capital/how-capital-works#grant-offers). If you are unable to generate the required Terms of Service documents, reach out to your Adyen contact. The Terms of Service document must be accepted by an individual legal entity that represents a physical person. For organizations, the document must be accepted by an authorized signatory of the organization. For example: * A cardholder accepts the document on their own behalf. * The owner of a restaurant accepts the document on behalf of the legal entity that represents the business. ## Requirements Before you begin, take into account the following requirements and preparations. | Requirement | Description | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | **Integration type** | You must have an Adyen for Platforms integration with the Capital financial product enabled. | | | **API credentials** | You must have API credentials for the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) (for example, **ws\[123456]@Scope.Company\[YourCompanyAccount]**) | | | **Capabilities** | Make sure that you have requested the following [capability](/capital/manage-user-capabilities) for your user:- **receiveGrants** | | | **Webhooks** | Ensure that your server can receive and accept [standard webhooks](/development-resources/webhooks). Subscribe to the following webhooks:- [Configuration webhooks](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/overview) | | | **Limitations** | Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). | | | **Setup steps** | Before you begin, make sure:- You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). - You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. - You created legal entities for: * The user that has a contractual relationship with your platform. * The individual legal entity who will accept the document. | | ## How it works To generate the Terms of Service and have them accepted by your users, follow these steps: 1. Listen to the webhook to [confirm Terms of Service requirements](#get-updates). 2. Make an API request to [get the types of Terms of Service required](#get-required). 3. Make an API request to [generate the Terms of Service documents](#get-document). 4. [Present the Terms of Service document](#present-document) to your user. 5. Make an API request to [confirm that your user has accepted the Terms of Service](#accept-tos). 6. Optionally, make an API request to [see the Terms of Service information for a specific legal entity](#tos-for-le). Learn more about [how Capital works](/capital/how-capital-works). ## 1. Confirm Terms of Service requirements When you create an account holder, certain [capabilities](/capital/manage-user-capabilities) are requested for them. To check whether your user must accept the Terms of Service, listen to [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/#/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) webhooks. If your user is required to accept Adyen's Terms of Service, it is indicated in the `verificationErrors` array. **balancePlatform.accountHolder.updated webhook - with verification errors array** ```json { "data":{ "accountHolder":{ "capabilities":{ "sendToTransferInstrument":{ "allowed":"false", "enabled":"true", "problems":[ { "entity":{ "id":"LE00000000000000000000001", "type":"LegalEntity" }, "verificationErrors":[ { "code":"2_902", "message":"Terms Of Service forms are not accepted.", "remediatingActions":[ { "code":"2_902", "message":"Accept TOS" } ], "type":"invalidInput" } ] } ], "requested":"true", "verificationStatus":"invalid" } }, "description":"Test Account holder", "reference":"YOUR_INTERNAL_IDENTIFIER", "id":"AH00000000000000000000001", "legalEntityId":"LE00000000000000000000001", "status":"Active" }, "balancePlatform":"YOUR_BALANCE_PLATFORM" }, "environment":"test", "type":"balancePlatform.accountHolder.updated" } ``` ## 2. Get the types of Terms of Service required If your user is required to accept Adyen's Terms of Service, you must determine which types of documents they need to accept. Make a GET [/legalEntities/{id}/termsOfServiceStatus](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)/termsOfServiceStatus) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. Note that your user may need to accept more than one Terms of Service document. In your test environment, only the document type `adyenForPlatformsAdvanced` is returned regardless of your actual integration. This is since all accounts use the same default configuration. In your live environment, the actual Terms of Service document types are returned. **Response** ```json { "termsOfServiceTypes": [ "adyenForPlatformsAdvanced", "adyenCapital", "adyenAccount" ] } ``` ## 3. Generate the Terms of Service documents To generate the Terms of Service documents, make a POST [/legalEntities/{id}/termsOfService](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of document based on the services and capabilities requested by the user and your platform integration. Set this to **adyenCapital**. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-language) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The language used for the Terms of Service document, specified by the two letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Possible value: **en** for English or **fr** for French. Note that French is only available for some integration types in certain countries/regions. Reach out to your Adyen contact for more information. | | [termsOfServiceDocumentFormat](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-termsOfServiceDocumentFormat) | | The requested format for the Terms of Service document. Default value: **JSON**. Possible values: **JSON**, **PDF**, or **TXT**. | **Generate the Terms of Service document** ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfService \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -d '{ "type": "adyenCapital", "language": "en" }' ``` The response returns the following information: | Parameter | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-document) | The generated document in the Base64-encoded format. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-id) | The unique identifier of the organization legal entity. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-language) | The language of the document. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | | [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-termsOfServiceDocumentId) | The unique identifier of the document. | | [termsOfServiceDocumentFormat](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#request-termsOfServiceDocumentFormat) | The requested format for the Terms of Service document. Default value: **JSON**. Possible values: **JSON**, **PDF**, or **TXT**. | **Response** ```json { "id": "LE00000000000000000000001", "type": "adyenCapital", "language": "en", "document": "termsOfServiceDocumentResponse" , "termsOfServiceDocumentId": "abc123", "termsOfServiceDocumentFormat": "JSON" } ``` The response returns the [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-document) and its unique [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId). Your user may need to accept more than one Terms of Service document depending on your integration. In this case, every required [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-document) and [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId) is returned in the response. You will need to present the document to your user in the [next step](#present-document). Use the document ID when you confirm your user has [accepted the Terms of Service](#accept-tos). ## 4. Present the Terms of Service document to your user You need to ask your user to review and accept the Terms of Service document. The process to do this depends on the format of the document. ### Tab: Format: JSON To present the document to your user, you can use the Adyen Document Viewer to render the document in your website. Before passing the document to the Adyen Document Viewer, you need to decode it. ```js const documentViewer = new AdyenDocumentViewer('#test'); const document = JSON.parse(decodeURIComponent(escape(window.atob(termsOfServiceDocumentResponse.document)))); documentViewer.render(document); ``` ### Tab: Format: PDF or TXT In the response from the previous step, take the Base64-encoded data from the [document](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/termsOfService#responses-200-document). Decode it and present it to your user in your UI. ## 5. Accept the Terms of Service To confirm that your user has accepted the Terms of Service, make a PATCH [/legalEntities/{id}/termsOfService/termsOfServicedocumentid](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)/termsOfService/\(termsofservicedocumentid\)) request, specifying the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity and the [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/_id_/termsOfService#responses-200-termsOfServiceDocumentId) of the document in the path. For sole proprietorships, include the legal entity ID of the owner in the path. For organizations, include the legal entity ID of the organization in the path. In the body of the request, specify the following: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#request-acceptedBy) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The individual legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the user accepting the Terms of Service. For sole proprietorships, this is the individual legal entity ID of the owner. For organizations, this is the legal entity ID of an authorized signatory for the organization. | | [ipAddress](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#request-ipAddress) | | The IP address of the user. | This request populates the Terms of Service document with the data of the main legal entity. For sole proprietorships, this is the information for the individual legal entity of the owner. For organizations, this means the document contains both the data for the organization and the individual legal entity of the authorized signatory who accepted the document. **Accept Terms of Service document** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfService/abc123 \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "acceptedBy" : "LE00000000000000000000002", "ipAddress" : "127.0.0.1" }' ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Create the request object(s) AcceptTermsOfServiceRequest acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest() .ipAddress("127.0.0.1") .acceptedBy("LE00000000000000000000002"); // Send the request TermsOfServiceApi service = new TermsOfServiceApi(client); AcceptTermsOfServiceResponse response = service.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest(); $acceptTermsOfServiceRequest ->setIpAddress("127.0.0.1") ->setAcceptedBy("LE00000000000000000000002"); // Send the request $service = new TermsOfServiceApi($client); $response = $service->acceptTermsOfService('id', 'termsofservicedocumentid', $acceptTermsOfServiceRequest); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) AcceptTermsOfServiceRequest acceptTermsOfServiceRequest = new AcceptTermsOfServiceRequest { IpAddress = "127.0.0.1", AcceptedBy = "LE00000000000000000000002" }; // Send the request var service = new TermsOfServiceService(client); var response = service.AcceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const acceptTermsOfServiceRequest = { acceptedBy: "LE00000000000000000000002", ipAddress: "127.0.0.1" } // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) acceptTermsOfServiceRequest := legalEntityManagement.AcceptTermsOfServiceRequest{ IpAddress: common.PtrString("127.0.0.1"), AcceptedBy: "LE00000000000000000000002", } // Send the request service := client.LegalEntityManagement() req := service.TermsOfServiceApi.AcceptTermsOfServiceInput("id","termsofservicedocumentid").AcceptTermsOfServiceRequest(acceptTermsOfServiceRequest) res, httpRes, err := service.TermsOfServiceApi.AcceptTermsOfService(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "acceptedBy": "LE00000000000000000000002", "ipAddress": "127.0.0.1" } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.accept_terms_of_service(request=json_request, id="id", termsofservicedocumentid="termsofservicedocumentid") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :acceptedBy => 'LE00000000000000000000002', :ipAddress => '127.0.0.1' } # Send the request result = adyen.legalEntityManagement.terms_of_service_api.accept_terms_of_service(request_body, 'id', 'termsofservicedocumentid') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Create the request object(s) const acceptTermsOfServiceRequest: Types.legalEntityManagement.AcceptTermsOfServiceRequest = { ipAddress: "127.0.0.1", acceptedBy: "LE00000000000000000000002" }; // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.acceptTermsOfService("id", "termsofservicedocumentid", acceptTermsOfServiceRequest); ``` The response returns the following information. | Parameter | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-acceptedBy) | The individual legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the user who accepted the terms of service. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-id) | The unique identifier of the accepted document. | | [ipAddress](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-ipAddress) | The IP address of the user. Only if provided in the request. | | [language](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-language) | The language of the document. | | [termsOfServiceDocumentId](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-termsOfServiceDocumentId) | The unique identifier of the document. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_/termsOfService/_termsofservicedocumentid_#responses-200-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | **Terms of Service document accepted** ```json { "acceptedBy": "LE00000000000000000000002", "id": "TOSA000AB00000000B2AAAB2BA0AA0", "ipAddress": "127.0.0.1", "language": "en", "termsOfServiceDocumentId": "abc123", "type": "adyenCapital" } ``` ## 6. (Optional): Get the Terms of Service information for a legal entity To see the Terms of Service information for a legal entity, make a GET [/legalEntities/{id}/termsOfServiceAcceptanceInfos](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/\(id\)/termsOfServiceAcceptanceInfos) request with the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity in the path. For sole proprietorships, this is the individual legal entity ID of the owner. **Get Terms of Service information for a legal entity** #### curl ```bash curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001/termsOfServiceAcceptanceInfos \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -X GET \ ``` #### Java ```java // Adyen Java API Library v33.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.legalentitymanagement.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.legalEntityManagement.*; Client client = new Client("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment.TEST); // Send the request TermsOfServiceApi service = new TermsOfServiceApi(client); GetTermsOfServiceAcceptanceInfosResponse response = service.getTermsOfServiceInformationForLegalEntity("id", null); ``` #### PHP ```php setXApiKey("ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY"); $client->setEnvironment(Environment::TEST); // Send the request $service = new TermsOfServiceApi($client); $response = $service->getTermsOfServiceInformationForLegalEntity('id'); ``` #### C\# ```cs // Adyen .net API Library v28.0.0 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.LegalEntityManagement; using Adyen.Service.LegalEntityManagement; var config = new Config() { XApiKey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Send the request var service = new TermsOfServiceService(client); var response = service.GetTermsOfServiceInformationForLegalEntity("id"); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v23.3.0 const { Client, LegalEntityManagementAPI } = require('@adyen/api-library'); const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceInformationForLegalEntity("id"); ``` #### Go ```go // Adyen Go API Library v17.0.0 import ( "context" "github.com/adyen/adyen-go-api-library/v17/src/common" "github.com/adyen/adyen-go-api-library/v17/src/adyen" "github.com/adyen/adyen-go-api-library/v17/src/legalEntityManagement" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", Environment: common.TestEnv, }) // Send the request service := client.LegalEntityManagement() req := service.TermsOfServiceApi.GetTermsOfServiceInformationForLegalEntityInput("id") res, httpRes, err := service.TermsOfServiceApi.GetTermsOfServiceInformationForLegalEntity(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v13.3.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY" adyen.client.platform = "test" # The environment to use library in. # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_information_for_legal_entity(id="id") ``` #### Ruby ```rb # Adyen Ruby API Library v10.1.1 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' adyen.env = :test # Set to "live" for live environment # Send the request result = adyen.legalEntityManagement.terms_of_service_api.get_terms_of_service_information_for_legal_entity('id') ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v23.3.0 import { Client, LegalEntityManagementAPI, Types } from "@adyen/api-library"; const client = new Client({ apiKey: "ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY", environment: "TEST" }); // Send the request const legalEntityManagementAPI = new LegalEntityManagementAPI(client); const response = legalEntityManagementAPI.TermsOfServiceApi.getTermsOfServiceInformationForLegalEntity("id"); ``` The response returns information about the Terms of Service document linked to the legal entity. | Parameter | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [createdAt](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-createdAt) | The date the document was created. | | [id](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-id) | The unique identifier of the accepted document. | | [acceptedBy](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-acceptedBy) | The [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the individual who accepted the terms of service. | | [acceptedFor](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-acceptedFor) | The [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) of the main legal entity. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/get/legalEntities/_id_/termsOfServiceAcceptanceInfos#responses-200-data-type) | The type of document based on the services and capabilities requested by the user and your platform integration. | **Response** ```json { "data": [ { "acceptedBy": "LE00000000000000000000002", "acceptedFor": "LE00000000000000000000001", "createdAt": "2022-12-05T13:36:58.212253Z", "id": "TOSA000AB00000000B2AAAB2BA0AA0", "type": "adyenCapital" } ] } ``` ## Next steps [required](/capital/make-grant-request) [Disburse a grant](/capital/make-grant-request) [Learn how to make a request for a grant and disburse the funds to your user's account.](/capital/make-grant-request) [Get grant balances](/capital/get-grant-balances) [Learn how to get the balances of all grants in your balance platform.](/capital/get-grant-balances) --- # Source: https://docs.adyen.com/capital/user-interface.md Section: Capital Title: User application and interface Description: Learn about the compliance requirements for your user interface and application. --- title: "User application and interface" description: "Learn about the compliance requirements for your user interface and application." url: "https://docs.adyen.com/capital/user-interface" source_url: "https://docs.adyen.com/capital/user-interface.md" canonical: "https://docs.adyen.com/capital/user-interface" last_modified: "2023-12-12T12:09:00+01:00" language: "en" --- # User application and interface Learn about the compliance requirements for your user interface and application. [View source](/capital/user-interface.md) The information in this page does **not** constitute legal advice. It only provides an overview of Adyen's compliance guidelines for financial products and Adyen for Platforms (referred to as the Compliance Guidelines). For additional, non-legal clarifications about this content, reach out to your Adyen contact. Platforms must provide a user interface that includes the following: * **Product Request:** Let the user request any of the financial services that the platform has agreed with Adyen to provide. * **KYC:** Provide required KYC information to Adyen as required under Adyen’s customer due diligence procedures. * **Agreements and Terms:** Present all required agreements and user terms including bank disclosures and fees, as detailed in [Adyen’s Customer Disclosure and Consent Procedure](#customer-disclosure-and-consent-procedure). If the platform is using [hosted onboarding](/platforms/onboard-users#hosted-onboarding), KYC fields, agreements, and terms of service will be hosted by Adyen. If the platform is using Adyen’s components in the UI, certain requirements may be embedded into the components provided by Adyen. * **User consent:** Ensure that the user reads and accepts the required legal agreements, using language detailed in [Adyen’s Customer Disclosure and Consent Procedure](#customer-disclosure-and-consent-procedure): *“I have read and I accept these terms and confirm that I am a legal representative authorized to accept these terms on behalf of the company. I have taken notice of the privacy statement (www\.adyen.com/privacy-policy) and I consent to my (personal) data being used for the purposes described therein."* * **Terms and Conditions availability:** Provide ongoing access to all the agreements that have been accepted by the user. * **Account Access:** Provide the user, free of charge, with ongoing access to their Balance or Bank Account, Capital, or Issuing product to view transactions, fees and other account information, as provided by Adyen to the platformthrough API as detailed below. * **Preselected Options:** The user interface must not include pre-selected options to indicate that the user has confirmed that they have read or understood the provided information concerning financial services. * **Financial Service Provider:** The user interface may not present the platform as a bank and should include a disclosure indicating Adyen as the financial services provider. * (Ireland Only): For all products, the following wording in the interface must be used: *“We work with Adyen N.V. to offer financial services. Adyen N.V., trading as Adyen, is authorised by De Nederlandsche Bank in the Netherlands and is regulated by the Central Bank of Ireland for consumer protection rules."* ### Product-specific requirements | | | | ------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Service** | **Terms** | | Adyen for Platforms | AfP Terms and Conditions | | Bank Accounts | * Adyen Business Bank Account Agreement - User Terms (Regional versions, if applicable) * Adyen’s Privacy Statement | | Card Issuing | - Account Holder Terms (EU/US) - Adyen’s Privacy Statement | | Capital | * Adyen Capital User Terms * Adyen’s Privacy Statement | ### User interface requirements | | | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Service** | **Interface requirements** | | Adyen for Platforms | * Balance overview (showing the total amount of funds paid into the user’s account) * Transaction history (showing the date of the transaction, total value of the transaction, fees and unique payment ID). | | Business Accounts | - Balance overview - Individual transaction information - Sender and/or receiver reference - IBAN (EU) Bank account number (US) - BIC (EU) - (EU only): Platforms need to provide users in the EU with a Depositor Information Sheet both before offering business accounts and thereafter annually. This information need to be provided as a PDF using the same language shown in the Depositor Information Sheet. - User consent: Ensure that the user interface contains a confirmation for the user to confirm they have read and accepted the terms of the Depositor Information Sheet, using the following language: “*I have read and I accept these terms and confirm that I am a legal representative authorized to accept these terms on behalf of the company. I have taken notice of the [privacy statement](https://www.adyen.com/privacy-policy) and I consent to my (personal) data being used for the purposes described therein.*" - (EU and UK only): Adyen is required to perform a service called verification of payee (EU) and confirmation of payee (UK) for payments made using an Adyen bank account. The verification/confirmation is usually performed by calling Adyen’s API built for this purpose. The platform’s user interface must display a notice to the user and the notice is four-fold as follows: * Match: A notice confirming that the account holder's name and IBAN match the information provided. * Partial Match: A notice indicating the name partially matches, which includes the correct recipient name for the sub-merchant to review. * No Match: A notice stating the names do not match, providing the sub-merchant with the option to cancel, edit, or continue with the transfer or adding the payee. * Service Not Supported: A warning that the verification service is not supported for the specific account, with the option to cancel, edit, or continue with the transfer or adding the payee. - (UK only) BACS Direct Debits: Platforms that wish to offer Business Accounts that are enabled for BACS Direct Debits must ensure that their user interfaces facilitate the following: **Mandate management** * Clearly disclose that only paperless/electronic mandate creation is supported. * Embed the following functionalities for mandate management in the user interface: * Account holders can view all of their mandates, along with the date the mandate was created and the name/reference of the payee. * Account holders receive a notification when a new mandate has been created (sent before the first payment is collected) containing the following details: * Payee details (sort code, account number, name). * payer (i.e., account holder) details (sort code, account number, name). * Account holders can cancel mandates at any time and cancellations must be effective immediately and confirmed to the Account holder. To enable this, the platform must integrate with our mandate cancellation API. Platforms are required to call the API immediately after the cancellation, so Adyen can notify the payee. * Account holders can amend mandates at any time, and amendments must also be effective immediately. **Transaction overview** * Provide in the user interface a clear visibility of the transactions that have been debited from the account, with a reference to the mandate to which each payment relates. **Refund** * Allow the account holder to request a refund at any time. Account holders are entitled to a refund where there is an error in the direct debit payment. This can be done via a dedicated button in the user interface, or through customer support channels. * The platform is required to provide Adyen with the details of the refund claim on the same business day the claim is made. The following details of the transaction must be provided: * Amount * Crediting date * Payee details (sort code, account number, name) * Payer details (sort code, account number, name) * Reason for refund - (US only): FDIC language must be presented the first time the Adyen business bank account is introduced in the UI. - (US only): Regulation GG - Unlawful Internet Gambling Enforcement Act Certification: users requesting business bank accounts must be asked the following prior to the acceptance of the User Terms: * *Is the legal entity opening the business bank account engaged in internet gambling? \[Yes/No]* * Any \[Yes] response should not be able to proceed to open a business bank account. | | Card Issuing | * Account balance information/ Issued card balance information * Account Transaction history/ Issued card Transaction histor * (For Charge Cards): Card balance repayment method; * Applicable fees, interest, and APR * Card transaction dispute functionality; * (US only): Equal Credit Opportunity Act disclosures must be presented with Capital Offers and Charge Card Applications * (US only): The platform must notify users when their request for a Loan or Charge Card has been declined by Adyen (Lender of Record). The platform must use a method that allows for retained documentation of the notification (e.g., UI message, email, or verbal communication documented in a system of record with the date and time). | | Capital Interface | - Capital Contract Type - Capital Balance and term, if applicable - Capital Fee (for Canada, must be shown as annual interest rate) - Capital Repayment Amount and repayment percentage; if applicable, the monthly threshold amount - If applicable, serving Adyen’s offered alternative ways of paying off the financing - (Ireland only): The following statements must be displayed to the user in the Capital interface before the user becomes bound by the Capital contract: * "*As a borrower in a credit agreement, you may have rights and duties under the Credit Reporting Act 2013 (available [here](https://www.irishstatutebook.ie/eli/2013/act/45/enacted/en/html))*". * "*NOTICE: Under the Credit Reporting Act 2013 lenders are required to provide personal and credit information for credit applications and credit agreements of €500 and above to the Central Credit Register. This information will be held on the Central Credit Register and may be used by other lenders when making decisions on your credit applications and credit agreements.*". Note, this notice must be displayed in bold, in a text box and in font size at least equal to that used for other information.) - (Ireland only): The following information must be shown to the user in the Capital user interface before the user becomes bound by the Capital contract: * Capital Balance (the total amount lent) * The length of time for which the loan offer is valid. - (Ireland only): Before the user is bound by the Capital contract, the Capital interface must prompt the user to provide their consent with a tick box to the following statement: "*I understand the features of Capital and I wish to proceed.*" | ** ### Customer disclosure and consent procedure This document outlines the Customer Disclosures and Consent Procedure of Adyen. It describes when and under what conditions Adyen makes disclosures and gains consent from its customers. This document is reviewed on an annual basis. This procedure encompasses disclosures and consents which Adyen presents to its customers; 1. As part of Adyen's customer due diligence (CDD) process. This refers to the due diligence which Adyen performs on all customers as a result of Know Your Customer (KYC) obligations during onboarding or periodic review. 2. As a result of regulatory obligations in the US which mandate that c certain disclosures and/or consent, reflected in the relevant agreement(s), must be detailed within a procedure. This document does not encompass other legal disclosures and consents that Adyen may require as part of the agreements. #### Legal Background Adyen enters a contractual agreement with every user directly, or indirectly (through a platform). This agreement outlines the terms of use for Adyen’s products and services. In addition to the terms of use, there is additional information that must be disclosed and/or requires consent to/from customers, due to local and/or global regulatory obligations, outside of these agreements. This procedure differentiates between Disclosures and Consents. * Disclosure: refers to mandatory information that must be disclosed to the customer, meaning that they must be made explicitly aware of that information prior - or during - the customer due diligence process; * Consent: refers to provisions that the customer must explicitly consent to or certify. Consent must be freely given, informed and specific. #### Applicability This procedure applies to all entities with whom Adyen enters into a business relationship with or on whose behalf Adyen performs a transaction, or provides embedded finance solutions (hereinafter: ‘customer’). Consent can only be given to Adyen by natural persons type: Authorized Signatory. The identification and verification requirements of authorized signatories is described in Adyen’s Natural Person Screening Procedure. The disclosures and consents presented to customers are based on the service line being utilized. Identification and verification requirements on service lines are described in Adyen’s Service Line Screening Procedure. When a term is not defined in this procedure, please refer to the definitions stated in Adyen’s Global AMLCFT and Sanctions Policy and related documents. #### Methodology Adyen discloses all disclosures and obtains all consents remotely through Adyen’s Onboarding forms and/or API’s, all evidence of consents obtained must be retained. ## See also * [Overview of compliance guidelines](/capital/compliance-guidelines) - [Keeping records](/capital/keeping-records) --- # Source: https://docs.adyen.com/capital/vulnerable-users.md Section: Capital Title: Vulnerable users (UK and Ireland only) Description: Learn how to support potential users in vulnerable circumstances. --- title: "Vulnerable users (UK and Ireland only)" description: "Learn how to support potential users in vulnerable circumstances." url: "https://docs.adyen.com/capital/vulnerable-users" source_url: "https://docs.adyen.com/capital/vulnerable-users.md" canonical: "https://docs.adyen.com/capital/vulnerable-users" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Vulnerable users (UK and Ireland only) Learn how to support potential users in vulnerable circumstances. [View source](/capital/vulnerable-users.md) This document assists Adyen partners in identifying and assisting the platform’s users who may be in vulnerable circumstances. Adyen recognizes that, due to personal circumstances, certain users may have or acquire traits of vulnerability throughout their lifetime. As a result, such users may require additional assistance to fully engage with the offered financial services and to ensure their needs are being met. In some countries where Adyen offers its financial services, Adyen is obliged by regulation to identify and assist vulnerable customers. To ensure these regulatory requirements are fulfilled, Adyen requires Platforms to adhere to certain processes concerning vulnerable customers, which are outlined in Adyen’s compliance guidelines. This instruction document is an important component of Adyen’s compliance guidelines. It provides practical, step-by-step guidance on how Platform staff should identify vulnerable customers and the procedures they should follow to ensure vulnerable customers receive the necessary assistance. Platforms are required to provide the following instructions to all members of staff who interact directly with users. This includes: * Customer Support Staff * Sales and Marketing Staff who communicate directly with users for sales/marketing purposes. * Managers responsible for overseeing staff who interact directly with users. Platforms must ensure all in-scope staff members read and fully understand these instructions. Staff should be encouraged to raise any queries. If there is any unclarity, Platforms should **seek clarification from Adyen**. Agents should be encouraged to properly support the customer and be given all the additional time needed. Your organisation should also flag any support available for agents when they have been dealing with users who are in distress, as these situations can be stressful. ## Identifying vulnerable users Adyen applies the following definition for vulnerable users: *“Users who, due to their personal circumstances, are especially susceptible to harm, particularly when a firm is not acting with appropriate levels of care.”* While all users are at risk of becoming vulnerable, the risk is increased by characteristics related to **four key drivers**: | Driver | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | Health | Physical or mental health conditions that impact a customer's ability to manage their affairs. | | Life Events | Significant life changes such as bereavement, job loss, or relationship breakdown that can affect resilience and decision-making. | | Resilience | Low ability to withstand financial or emotional shocks (for example., tight margins, limited financial reserves). | | Capability | Low levels of financial literacy, confidence in managing money, or other relevant skills such as digital literacy. | ### Vulnerability in a B2B Context Vulnerability is less likely in the B2B context than in retail financial services, but it can manifest for certain segments of Adyen's indirect customer base, particularly sole proprietors. Indicative examples of merchants who may be prone to vulnerability include: * Sole proprietors operating with tight margins and limited financial reserves who are susceptible to economic shocks. * Small e-commerce businesses experiencing a sudden increase in fraudulent transactions and lacking the resources to manage chargebacks. * Sole proprietors whose health conditions impact their ability to manage business finances effectively. * A business with an owner who has suddenly become incapacitated, leaving no one with the knowledge to manage online payments. * A business struggling with cash flow, making it difficult to pay suppliers. * Elderly sole traders or those with lower digital literacy who may struggle to navigate digital financial tools and processes. Vulnerability can be temporary. Merchants that do not exhibit signs of vulnerability one day may in fact experience it in the future, and vice versa. It is therefore important to routinely be on the lookout for signs of vulnerability. ## Instructions for staff ### Step 1: Initial Interaction Greeting and Introduction: Begin every customer interaction with a warm and empathetic greeting. Introduce yourself and let the customer know you are here to help. ### Step 2: Identifying Vulnerability Indicators of Vulnerability: Pay close attention to the customer's tone, language, and emotional cues. Be alert for any of the following: * Individual Factors: * Passing mentions of illness, disability, or impairment. * Reference to contact with the health or social care sector, or receipt of specific benefits. * Use of English as an additional language. * Behavioural Cues: * Sounding flustered, anxious, or under duress. * Displaying frustration or anger. * Asking unrelated questions, forgetfulness, or struggling to concentrate/understand detail. * Difficulty regulating emotional responses (being upset, tearful) or difficulty trusting the service/individual. * Confusion (for example., not knowing where a debt has come from). * Wider Circumstances: * Mention of life events (time in hospital, bereavement, income shocks). * Struggling with the cost of living (mentions of higher bills, struggling to pay household bills). * Signs of an unstable housing situation or abuse, including economic abuse. * Unexplained spending (which could indicate problem gambling or undeclared debt). * Organizational Actions: * Complaints about things your or another organization may have done (for example, changing communication methods). * Mention of failures to deal with a third party/carer, accept a different payment method, or explain key information clearly. * Example Statements: Statements that could indicate vulnerable circumstances include: * “My circumstances are bad, can you help?” * “I’m not very well at the moment and am finding it difficult.” * “I’m really struggling today, I’m so down.” * “I don’t understand you.” For identifying customers with potential mental capacity limitations, the **BRUCE** method can help identify difficulties with decision-making or limited ability to understand, remember, or "weigh up" information. | Acronym | Focus Area | Question to Consider | | ------- | ------------------ | ------------------------------------------------------------------ | | B | Behaviour and talk | Is there a limitation in the customer’s behaviour and speech? | | R | Remembering | Is the customer experiencing problems with their memory or recall? | | U | Understanding | Does the customer understand the information they are being given? | | C | Confusion | Is the customer confused about the situation or options? | | E | Evaluating | Can the customer “weigh up” the different options open to them? | ### Step 3: Providing Support Use the **TEXAS** method to respond to a customer who has provided information indicating they need additional support. | Acronym | Action | Example Script | | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | T | Thank | “Thanks for telling me about your situation, as it will help us take this into account.” | | E | Explain | “Let me explain how we’d like to use that information, just so you know.” | | X | Explicit Consent | “Are you happy to give me permission to note down and save the information you’ve shared with me today?” | | A | Ask | “How does your situation make it difficult to manage your finances?” "How does it affect your ability to communicate with us?" | | S | Signpost or Refer | Internally refer to a specialist team, or signpost to external help. | Use the **IDEA** method when more information is needed about a customer’s situation to take effective action. | Acronym | Action | Example Script | | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I | Impact | Ask about the impact of the circumstances on the customer’s financial situation (what does it stop them doing or make more difficult?). For example, “What has the impact been on your personal and financial situation?” | | D | Duration | Ask about the duration of the circumstances to help determine the time needed to consider options. For example, “So when did this first start to happen?” | | E | Experience | Understand the customer’s experience of the vulnerability (one-off or recurring?). Take fluctuating situations (including medication effects) into account. For example, “To help me understand your situation better, can you tell me whether this has happened before?” | | A | Assistance | Establish what, if any, assistance the customer has received. This helps determine if you need to refer them for additional support from an external agency. | If necessary, politely ask the customer for clarification about a condition or illness they mention. For example, “I’m really sorry, but I don’t know very much about (name of condition), could you tell me a little more about it?” #### Tailor your support * Customize your approach to meet the customer's specific needs. * Provide clear and concise explanations and solutions. Use plain language and avoid jargon. For complex topics, break them down into sub-topics and pause for questions. * Ask the customer if the current channel (chat, phone, etc.) is their preferred communications channel. * Ask the customer for feedback at appropriate times (for example., when proposing a resolution or next step) to ensure alignment and understanding. #### Offer Additional Assistance/Signposting * If the customer needs extra help, offer additional resources or escalate the issue to a supervisor if necessary. * Ensure that the customer feels supported throughout the process. * External Signposting Categories (Non-exhaustive list; identify an appropriate organisation in the relevant country/territory): * Debt advice services * Mental health support services * Bereavement counselling services * Domestic abuse helpline * Disability support services * Financial literacy/capability groups * Legal aid services * Housing advice services. ### Step 4: Documenting the Interaction A general principle is that customers should only be required to share information about their vulnerability once. The details must be recorded so other staff members who interact with the customer can also meet their needs. The specific vulnerability indicator(s) identified or shared should be recorded using the tags below. A record must be attached to the customer’s file. Take detailed notes about the customer’s situation, the support provided, and any follow-up actions. Make sure that you only record the facts shared with you by the user and do not include any proposed diagnoses or names of any specific conditions unless the customer has explicitly told you that they have that condition. Please also ensure that the notes are recorded in such a way that you would be comfortable with the customer or a third party reading that about themselves. | Tag | Examples of conditions or experiences | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Health/Ability | Physical or mental health conditions that impact a customer's ability to manage their affairs. These may include: significant illness, health issues, or disability. | | Life events | Significant life changes such as: bereavement, job loss, or relationship breakdown. | | Resilience | Low ability to withstand financial or emotional shocks such as being in debt or living paycheck to paycheck. | | Capability | Low levels of financial literacy, confidence in managing money, or other relevant skills, such as digital literacy. | The following are examples of best practices for user interactions with staff. | Example | Vulnerable circumstances tag | Follow-up/support | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer explained that they struggled to understand complex financial information and needed additional support in working through the terms and conditions. | Capability | Agent offered to spend time explaining terms and conditions (or any other aspect unclear to customer) in further detail. Agent added a note to the customer’s file that additional care may be needed to ensure the customer understands all relevant financial information. | | Customer appeared to have difficulty in understanding/retaining relevant financial information. | Capability | Agent offered to spend time explaining terms and conditions (or any other aspect unclear to customer) in further detail. Agent added a note to the customer’s file that additional care may be needed to ensure the customer understands all relevant financial information. | | Customer shared that they suffer from hearing loss and requested that we only communicate with them via email and do not call them. | Health/Ability | Agent added a note to the customer’s file that all communications are to occur in writing and not via call. | | Customer stated that they had recently suffered from a broken down boiler and they needed extra time to pay their fees. | Life events / Resilience | Agent offered to speak with the finance team and check if additional time to pay can be given. | | Customer shared that their finances are tight following a relationship ending and they needed extra time to pay. | Life events / Resilience | Agent offered to speak with the finance team and check if additional time to pay can be given. | The following are examples of unacceptable documentation for user interactions. * Customer did not speak very good English. * Customer had problems concentrating so may have ADHD. * Customer had difficulties understanding/remembering so may have dementia. Consult with your internal privacy or legal teams to ensure that your method of recording is compliant with your company's obligations under domestic privacy legislation such as GDPR. ### Step 5: Follow-Up If necessary, schedule a follow-up call or email to ensure the customer's issue has been resolved. Confirm that the customer is satisfied with the resolution. We recommend that you periodically review your interactions and feedback to continuously improve the handling of vulnerable users. ## See also * [Reporting on vulnerable customer information](/capital/reporting-to-adyen#periodic-reporting) --- # Source: https://docs.adyen.com/capital/webhook-types.md Section: Capital Title: Webhook structures and types for Capital Description: Learn which webhooks Adyen sends for business financing-related events. --- title: "Webhook structures and types for Capital" description: "Learn which webhooks Adyen sends for business financing-related events." url: "https://docs.adyen.com/capital/webhook-types" source_url: "https://docs.adyen.com/capital/webhook-types.md" canonical: "https://docs.adyen.com/capital/webhook-types" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Webhook structures and types for Capital Learn which webhooks Adyen sends for business financing-related events. [View source](/capital/webhook-types.md) To keep track of business financing-related events in your balance platform, you can subscribe to the following webhook types: * [Capital webhooks](https://docs.adyen.com/api-explorer/capital-webhooks/latest/overview): These notify your server of changes to grants at each stage of their lifecycle. The following webhooks are included: * **Capital dynamic offer webhook** * **Capital static offer webhook** * **Capital grant webhook** * [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview): These notify your server about incoming and outgoing transfers related to grants in your platform. * [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview): These notify your server when grant funds are deposited into a user's balance or credited for grant repayment. You can differentiate the events based on the `type`. Additionally, these webhooks include a `status` field that indicates the outcome of each event. To learn more about common webhook structure, see the [Platform webhooks documentation](/development-resources/webhooks/webhook-types#platforms-webhook-structure). The following diagram outlines the types of webhooks you can expect during the grant lifecycle. Note that grant initiation status updates generate only capital notifications, not transfer or transaction notifications. [![Grant lifecycle and webhooks](/user/pages/docs/07.capital/08.webhook-types/grant-lifecycle-and-webhooks.svg)](/user/pages/docs/07.capital/08.webhook-types/grant-lifecycle-and-webhooks.svg) ## Capital dynamic offer webhook Use Capital dynamic offer webhook to get notified when [dynamic offers](/capital/get-grant-offers/dynamic-offers/) are created for account holders in your platform. | Event type | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.capital.dynamicOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.capital.dynamicOffer.created) | After dynamic offers are created for an account holder, Adyen sends this webhook with information about the offers. | ## Capital static offer webhook Use Capital static offer webhook to get notified when [static offers](/capital/get-grant-offers/static-offers/) are created for account holders in your platform. | Event type | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) | After static offers are created for an account holder, Adyen sends this webhook with information about the offers. | ## Capital grant webhook Use Capital grant webhooks to track [lifecycle of grants](/capital/grant-lifecycle-and-status) in your platform. | Event type | Description | | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [balancePlatform.grants.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.created) | After a grant is created for an account holder, Adyen sends this webhook with information about the grant. | | [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) | After a grant is updated for an account holder, Adyen sends this webhook with information about the grant. | ## Transfer webhook Use Transfer webhooks to track the movement of funds, both incoming and outgoing, related to grants in your platform, from initiation to completion. | Event type | Description | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) | Adyen sends this webhook when there are fund movements on your platform. | | [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) | Adyen sends this webhook when the status of a transfer changes. | To identify Transfer webhooks triggered by grant-related events, review the following values: | Parameter | Description | Value | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | [category](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-category) | The category of the transfer. | **grants** | | [type](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-type) | The type of the transfer. | * Grant disbursement: **grant** * Regural grant repayment: **repayment** * Unscheduled grant repayment: **capitalFundsCollection** and **repayment** | | [direction](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-direction) | The direction of the transfer request from the perspective of the balance account. | - Grant disbursement: **incoming** - Regural grant repayment: **outgoing** - Unscheduled grant repayment: **incoming** and **outgoing** | | [counterparty](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated#request-data-counterparty) | The other party in the transfer. | * **balanceAccountId** * **transferInstrumentId** | ## Transaction webhook Use Transaction webhooks to confirm when grant funds are deposited into a user's balance or credited for grant repayment. | Event type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) | After a transfer is booked in a balance account, Adyen sends this webhook with information about the transaction. | To identify Transaction webhooks triggered by grant-related events, review the following values: | Parameter | Description | Value | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | | [transfer.id](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer-id) | The unique identifier of the transfer. | Must correspond to the transfer ID created for the grant fund movement. | | [transfer.reference](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created#request-data-transfer-reference) | The reference from the `/transfers` request. | Must correspond to the grant ID listed in the related transfer. | ## Next steps [Grant lifecycle-related events](/capital/webhook-types/capital-webhooks) [Learn which webhooks Adyen sends for updates on grant lifecycle.](/capital/webhook-types/capital-webhooks) [Fund transfers-related webhooks](/capital/webhook-types/fund-transfers-webhooks) [Learn which webhooks Adyen sends for updates on grant fund transfers.](/capital/webhook-types/fund-transfers-webhooks) --- # Source: https://docs.adyen.com/capital/webhook-types/capital-webhooks.md Section: Capital Title: Grant lifecycle-related events Description: Learn which webhooks are sent for each event. --- title: "Grant lifecycle-related events" description: "Learn which webhooks are sent for each event." url: "https://docs.adyen.com/capital/webhook-types/capital-webhooks" source_url: "https://docs.adyen.com/capital/webhook-types/capital-webhooks.md" canonical: "https://docs.adyen.com/capital/webhook-types/capital-webhooks" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Grant lifecycle-related events Learn which webhooks are sent for each event. [View source](/capital/webhook-types/capital-webhooks.md) Adyen sends webhooks for the following [grant lifecycle-related events](/capital/grant-lifecycle-and-status): * [Dynamic offer created](#dynamic-offer-created) * [Static offer created](#static-offer-created) * [Grant requested](#grant-requested) * Grant assessed * [Grant reviewing](#grant-reviewing) * [Grant approved](#grant-approved) * Grant rejected * Grant canceled * [Grant pending](#grant-pending) * Grant failed * [Grant active](#grant-active) * [Grant repaid](#grant-repaid) * Grant revoked * Grant written off The next sections show code samples for some of these events. ## Dynamic offer created When a new dynamic offer is created for an account holder, Adyen sends a [balancePlatform.capital.dynamicOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.capital.dynamicOffer.created) webhook to notify your server. The webhook includes information about the offer, such as: * `accountHolderId`: The unique identifier of the account holder that the dynamic offer is for. * `id`: The unique identifier of the dynamic offer. * `contractType`: **loan**. * `maximumAmount`: An object containing currency and value of the maximum offer amount, in [minor units](/development-resources/currency-codes). * `minimumAmount`: An object containing currency and value of the minimum offer amount, in [minor units](/development-resources/currency-codes). * `repayment.term.estimatedDays`: The estimated period for repaying the grant, in days. * `repayment.term.maximumDays`: The maximum period for repaying the grant, in days. * `financingType`: **businessFinancing**. * `startsAt` and `expiresAt`: The dates when the financing offer begins and ends. The offer must be accepted before the expiration date. **Offer created** ```json { "data": { "balancePlatform": "BalancePlatform", "id": "0000000000000001", "dynamicOffer": { "accountHolderId": "AH00000000000000000000001", "contractType": "loan", "expiresAt": "2026-02-19T20:22:39.489+01:00", "financingType": "businessFinancing", "id": "0000000000000001", "maximumAmount": { "currency": "EUR", "value": 4567 }, "minimumAmount": { "currency": "EUR", "value": 1234 }, "repayment": { "term": { "estimatedDays": 180, "maximumDays": 270 } }, "startsAt": "2026-02-12T20:22:39.489+01:00" } }, "environment": "test", "timestamp": "2026-02-12T19:22:39.699Z", "type": "balancePlatform.capital.dynamicOffer.created" } ``` ## Static offer created When a new static offer is created for an account holder, Adyen sends a [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) webhook to notify your server. The webhook includes information about the offer, such as: * `accountHolderId`: The unique identifier of the account holder that the static offer is for. * `id`: The unique identifier of the static offer. * `contractType`: **loan**. * `amount`: An object containing currency and value of the offer, in [minor units](/development-resources/currency-codes). * `repayment.term.estimatedDays`: The estimated period for repaying the grant, in days. * `repayment.term.maximumDays`: The maximum period for repaying the grant, in days. * `repayment.basisPoints`: The repayment amount, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), that is deducted daily from your user's incoming net volume. * `repayment.threshold`: An object containing the details of the minimum threshold amount that your user must repay every 30-day period. * `fee`: An object containing the fee currency and value, in [minor units](/development-resources/currency-codes). * `startsAt` and `expiresAt`: The dates when the financing offer begins and ends. The offer must be accepted before the expiration date. **Offer created** ```json { "data": { "balancePlatform": "TestBalancePlatform", "creationDate": "2026-01-19T17:17:35+01:00", "id": "0000000000000001", "offer": { "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": 629375 }, "contractType": "loan", "expiresAt": "2026-01-26T17:17:34.328+01:00", "fee": { "amount": { "currency": "EUR", "value": 94406 } }, "id": "0000000000000001", "repayment": { "basisPoints": 800, "term": { "estimatedDays": 180, "maximumDays": 270 }, "threshold": { "amount": { "currency": "EUR", "value": 80420 } } }, "startsAt": "2026-01-19T17:17:34.328+01:00" } }, "environment": "test", "timestamp": "2026-01-19T16:17:35.558Z", "type": "balancePlatform.balanceAccountHolder.capitalOffer.created" } ``` ## Grant requested When a user selects an offer using either the [capital components](/capital/capital-components) or your [custom interface built with our APIs](/capital/make-grant-request), Adyen sends a [balancePlatform.grants.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.created) webhook to your server. This webhook includes information about the grant, such as: * `id`: The unique identifier of the grant. * `counterparty.accountHolderId`: The unique identifier of the account holder for which a grant has been requested. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `status.code`: **Requested** **Grant requested** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Requested" } } }, "environment": "test", "timestamp": "2026-01-21T19:56:42.107Z", "type": "balancePlatform.grants.created" } ``` ## Grant reviewing In specific situations, Adyen may require your users to provide additional information about their businesses, such as when the total user's exposure meets or exceeds the threshold, typically EUR 25,000 or the equivalent amount in another supported currency. You then need to [collect additional data from your user](/capital/collect-user-data) and submit it to Adyen. Adyen sends a [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook to notify your server about this event, including the following information: * `id`: The unique identifier of the grant. * `counterparty.accountHolderId`: The unique identifier of the account holder for which a grant has been requested. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `status.code`: **Reviewing** * `actions.code`: **AnaCreditCapabilityRule** * `actions.resolved`: **false** **Grant reviewing - additional KYC data required** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Reviewing", "actions": [ { "actionCode": "AnaCreditCapabilityRule", "resolved": false } ] } } }, "environment": "test", "timestamp": "2026-01-21T19:56:47.889Z", "type": "balancePlatform.grants.updated" } ``` ## Grant approved After a thorough secondary review confirms the grant request meets all criteria, Adyen sends a [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook to notify your server of final approval. The webhook includes information about the grant, such as: * `id`: The unique identifier of the grant. * `counterparty.accountHolderId`: The unique identifier of the account holder for which a grant has been approved. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `status.code`: **Approved** **Grant approved** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Approved" } } }, "environment": "test", "timestamp": "2026-01-21T19:57:07.977Z", "type": "balancePlatform.grants.updated" } ``` ## Grant pending After Adyen approves the grant, the user must complete required actions, such as [signing the Terms of Service](/capital/terms-of-service).\ The grant remains pending until: * All required actions are completed on the user's side. * The grant transaction is booked to the user's balance account. * The security cooldown period ends. For example, if a user updates their bank account details (transfer instrument), Adyen waits 72 hours before processing transactions to the new account. Adyen notifies you of this stage by sending a [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook, which includes information about the grant, such as: * `id`: The unique identifier of the grant. * `counterparty.accountHolderId`: The unique identifier of the account holder for which a grant has been approved. * `counterparty.balanceAccountId`: The balance account details where the grant amount should be disbursed. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `status.code`: **Pending** **Grant pending** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Pending" } } }, "environment": "test", "timestamp": "2026-01-21T19:57:10.153Z", "type": "balancePlatform.grants.updated" } ``` After the user completes the required actions, Adyen disburses the grant amount to the specified balance account. At this point, Adyen also sends [webhooks about the corresponding fund transfer](/capital/webhook-types/fund-transfers-webhooks). ## Grant active After the grant is disbursed, Adyen sends a [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook, including the following information about the grant: * `id`: The unique identifier of the grant. * `accountHolderId`: The unique identifier of the account holder for which a grant has been approved. * `balanceAccountId`: The balance account details where the grant amount has been disbursed. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `balances.currency`: The currency of the grant amount. * `balances.fee`: The one-time fee for business financing. * `balances.principal`: The amount that has been disbursed to the user. * `balances.total`: The total amount that the user must repay. It is the sum of the fee amount and the principal amount. * `status.code`: **Active** **Grant active** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 94406, "principal": 629375, "total": 723781 }, "id": "GR00000000000000000000001", "status": { "code": "Active" } } }, "environment": "test", "timestamp": "2026-01-21T19:57:25.856Z", "type": "balancePlatform.grants.updated" } ``` ## Grant repaid After the user has made their last repayment towards the grant and the [corresponding transfer has been booked](/capital/webhook-types/fund-transfers-webhooks), Adyen sends a [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook which includes the following information: * `id`: The unique identifier of the grant. * `accountHolderId`: The unique identifier of the account holder for which a grant has been approved. * `balanceAccountId`: The balance account details where the grant amount has been disbursed. * `grantOfferId`: The unique identifier for the related grant offer, which determines the grant conditions. * `balances.currency`: The currency of the grant amount. * `balances.fee`: **0** * `balances.principal`: **0** * `balances.total`: **0** * `status.code`: **Repaid** **Grant repaid** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Repaid" } } }, "environment": "test", "timestamp": "2026-01-21T19:59:10.153Z", "type": "balancePlatform.grants.updated" } ``` ## See also * [Webhook structures and types for Capital](/capital/webhook-types) * [Grant lifecycle and status](/capital/grant-lifecycle-and-status) --- # Source: https://docs.adyen.com/capital/webhook-types/fund-transfers-webhooks.md Section: Capital Title: Fund transfer-related events Description: Learn which webhooks are sent for each event. --- title: "Fund transfer-related events" description: "Learn which webhooks are sent for each event." url: "https://docs.adyen.com/capital/webhook-types/fund-transfers-webhooks" source_url: "https://docs.adyen.com/capital/webhook-types/fund-transfers-webhooks.md" canonical: "https://docs.adyen.com/capital/webhook-types/fund-transfers-webhooks" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Fund transfer-related events Learn which webhooks are sent for each event. [View source](/capital/webhook-types/fund-transfers-webhooks.md) Adyen sends webhooks for the following fund transfer-related events when it disburses a grant or receives a repayment from the user: * [Grant disbursement initiated](#disbursement-initiated) * [Grant disbursement authorised](#disbursement-authorised) * [Grant disbursement booked](#disbursement-booked) * [Regular repayment initiated](#regular-repayment-initiated) * [Regular repayment authorised](#regular-repayment-authorised) * [Regular repayment booked](#regular-repayment-booked) * [Unscheduled repayment initiated](#unscheduled-repayment-initiated) * [Unscheduled repayment authorised](#unscheduled-repayment-authorised) * [Unscheduled repayment booked](#unscheduled-repayment-booked) * [Transaction created](#transaction-created) The following sections provide code samples for the specified events, focusing on cases where the transfer is successfully processed. For a complete list of possible outcomes, refer to the [status](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created#request-data-status) field in our API documentation. ## Grant disbursement initiated After the grant has been configured and the user has completed required actions, Adyen initiates grant disbursement and sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **grant** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `status`: **received** **Grant disbursement initiated** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "received", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 1, "balances": [ { "currency": "GBP", "received": 1850000 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 1850000 } ] } ], "eventId": "EV0000000000000000000000000001" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.created" } ``` ## Grant disbursement authorised After the grant disbursement request has been received, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **grant** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `status`: **authorized** **Grant disbursement authorised** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "authorised", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 2, "balances": [ { "reserved": 1850000, "currency": "GBP", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "GBP", "received": -1850000 } ] } ], "eventId": "EV0000000000000000000000000002" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.updated" } ``` ## Grant disbursement booked After the grant disbursement request has been authorized, Adyen sends another [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **grant** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `status`: **booked** **Grant disbursement booked** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "booked", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 3, "balances": [ { "reserved": 0, "balance": 1850000, "currency": "GBP", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "GBP", "received": -1850000 } ] }, { "id": "EV0000000000000000000000000003", "status": "booked", "transactionId": "EV000000000000000000000000000GBP", "bookingDate": "2025-10-15T18:53:08+02:00", "valueDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": -1850000, "balance": 1850000, "currency": "GBP", "received": 0 } ] } ], "eventId": "EV0000000000000000000000000003" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.36Z", "type": "balancePlatform.transfer.updated" } ``` ## Regular repayment initiated After the regular repayment request has been initiated, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with the following information: * `direction`: **outgoing** * `category`: **grants** * `type`: **repayment** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `description`: Contains information about the related grant ID, balance account ID, and processing date. For example, **\\/GREF\\/GR00000000000000000000001\\/FBAC\\/BA00000000000000000000001\\/DATE\\/2025-10-17T01:31:15+02:00\\/**. * `status`: **received** **Regular repayment initiated** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "38E9LB68OCJZ21JB", "creationDate": "2025-10-17T01:31:15+02:00", "createdAt": "2025-10-17T01:31:08+02:00", "status": "received", "reason": "approved", "direction": "outgoing", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "repayment", "amount": { "value": 15000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "description": "\/GREF\/GR00000000000000000000001\/FBAC\/BA00000000000000000000001\/DATE\/1*********020251016\/", "updatedAt": "2025-10-17T01:31:15+02:00", "sequenceNumber": 1, "balances": [ { "currency": "GBP", "received": -15000 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": -15000 } ] } ], "eventId": "EV0000000000000000000000000001" }, "environment": "test", "timestamp": "2025-10-16T23:33:19.804Z", "type": "balancePlatform.transfer.created" } ``` ## Regular repayment authorised After the regular repayment request has been received, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **outgoing** * `category`: **grants** * `type`: **repayment** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `description`: Contains information about the related grant ID, balance account ID, and processing date. For example, **\\/GREF\\/GR00000000000000000000001\\/FBAC\\/BA00000000000000000000001\\/DATE\\/2025-10-17T01:31:15+02:00\\/**. * `status`: **authorized** **Regular repayment authorised** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "38E9LB68OCJZ21JB", "creationDate": "2025-10-17T01:31:15+02:00", "createdAt": "2025-10-17T01:31:08+02:00", "status": "authorised", "reason": "approved", "direction": "outgoing", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "repayment", "amount": { "value": 15000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "description": "\/GREF\/GR00000000000000000000001\/FBAC\/BA00000000000000000000001\/DATE\/1*********020251016\/", "updatedAt": "2025-10-16T23:33:19.835Z", "sequenceNumber": 2, "balances": [ { "currency": "GBP", "received": 0, "reserved" : -15000 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": -15000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 15000, "reserved": -15000 } ] } ], "eventId": "EV0000000000000000000000000002" }, "timestamp": "2025-10-16T23:33:19.835Z", "environment": "test", "type": "balancePlatform.transfer.updated" } ``` ## Regular repayment booked After the [regular repayment](/capital/how-capital-works#regular-repayments) request has been authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **outgoing** * `category`: **grants** * `type`: **repayment** * `reference`: Contains the ID of the related grant. For example, **GR00000000000000000000001**. * `description`: Contains information about the related grant ID, balance account ID, and processing date. For example, **\\/GREF\\/GR00000000000000000000001\\/FBAC\\/BA00000000000000000000001\\/DATE\\/2025-10-17T01:31:15+02:00\\/**. * `status`: **booked** **Regular repayment booked** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "38E9LB68OCJZ21JB", "creationDate": "2025-10-17T01:31:15+02:00", "createdAt": "2025-10-17T01:31:08+02:00", "status": "booked", "reason": "approved", "direction": "outgoing", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "repayment", "amount": { "value": 15000, "currency": "GBP" }, "reference": "GR00000000000000000000001", "description": "\/GREF\/GR00000000000000000000001\/FBAC\/BA00000000000000000000001\/DATE\/1*********020251016\/", "updatedAt": "2025-10-17T01:31:15+02:00", "sequenceNumber": 3, "balances": [ { "currency": "GBP", "received": 0, "reserved" : 0, "balance": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": -15000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 15000, "reserved": -15000 } ] }, { "id": "EV0000000000000000000000000003", "status": "booked", "transactionId" : "EV0000000000000000000000000003GBP", "bookingDate": "2025-10-17T01:31:15+02:00", "valueDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 0, "reserved": 15000, "balance": -15000 } ] } ], "eventId": "EV0000000000000000000000000003" }, "type": "balancePlatform.transfer.created", "environment": "test", "timestamp": "2025-10-16T23:33:19.865Z" } ``` ## Unscheduled repayment initiated An [unscheduled repayment](/capital/how-capital-works#unscheduled-repayments) first triggers an **incoming** transfer to Adyen's internal Capital fund collection account. After this transfer is processed, an **outgoing** transfer completes the repayment on the grant according to the [regular repayment flow](#regular-repayment-initiated). After the unscheduled repayment request has been initiated, Adyen sends a [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **capitalFundsCollection** * `reference` and `description`: Contains the ID of Adyen's internal Capital fund collection account. For example, **CPTL00000000000000000000000001**. * `status`: **received** **Unscheduled repayment initiated** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3CE02F68VMWYNNI9", "creationDate": "2025-11-04T09:11:03+01:00", "createdAt": "2025-11-04T09:10:58+01:00", "status": "received", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "capitalFundsCollection", "amount": { "value": 100000, "currency": "GBP" }, "reference": "CPTL00000000000000000000000001", "description": "CPTL00000000000000000000000001", "updatedAt": "2025-11-04T09:11:03+01:00", "sequenceNumber": 1, "balances": [ { "currency": "GBP", "received": -100000 } ], "events": [ { "id": "EV0000000000000000000000000011", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 100000 } ] } ], "eventId": "EV0000000000000000000000000011" }, "environment": "test", "timestamp": "2025-11-04T08:11:06.614Z", "type": "balancePlatform.transfer.created" } ``` ## Unscheduled repayment authorised An [unscheduled repayment](/capital/how-capital-works#unscheduled-repayments) first triggers an **incoming** transfer to Adyen's internal Capital fund collection account. After this transfer is processed, an **outgoing** transfer completes the repayment on the grant according to the [regular repayment flow](#regular-repayment-initiated). After the unscheduled repayment request has been received, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **capitalFundsCollection** * `reference` and `description`: Contains the ID of Adyen's internal Capital fund collection account. For example, **CPTL00000000000000000000000001**. * `status`: **authorized** **Unscheduled repayment authorised** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3CE02F68VMWYNNI9", "creationDate": "2025-11-04T09:11:04+01:00", "createdAt": "2025-11-04T09:10:58+01:00", "status": "authorised", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "capitalFundsCollection", "amount": { "value": 100000, "currency": "GBP" }, "reference": "CPTL00000000000000000000000001", "description": "CPTL00000000000000000000000001", "updatedAt": "2025-11-04T09:11:04+01:00", "sequenceNumber": 2, "balances": [ { "currency": "GBP", "received": 0, "reserved": 100000 } ], "events": [ { "id": "EV0000000000000000000000000011", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 100000 } ] }, { "id": "EV0000000000000000000000000012", "status": "authorised", "bookingDate": "2025-11-04T09:11:04+01:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": -100000, "reserved": 100000 } ] } ], "eventId": "EV0000000000000000000000000012" }, "environment": "test", "timestamp": "2025-11-04T08:11:06.621Z", "type": "balancePlatform.transfer.updated" } ``` ## Unscheduled repayment booked An [unscheduled repayment](/capital/how-capital-works#unscheduled-repayments) first triggers an **incoming** transfer to Adyen's internal Capital fund collection account. After this transfer is processed, an **outgoing** transfer completes the repayment on the grant according to the [regular repayment flow](#regular-repayment-initiated). After the unscheduled repayment request has been authorized, Adyen sends a [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) webhook with the following information: * `direction`: **incoming** * `category`: **grants** * `type`: **capitalFundsCollection** * `reference` and `description`: Contains the ID of Adyen's internal Capital fund collection account. For example, **CPTL00000000000000000000000001**. * `status`: **booked** **Unscheduled repayment booked** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3CE02F68VMWYNNI9", "creationDate": "2025-11-04T09:11:04+01:00", "createdAt": "2025-11-04T09:10:58+01:00", "status": "booked", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "capitalFundsCollection", "amount": { "value": 100000, "currency": "GBP" }, "reference": "CPTL00000000000000000000000001", "description": "CPTL00000000000000000000000001", "updatedAt" : "2025-11-04T09:11:04+01:00", "sequenceNumber": 3, "balances": [ { "balance" : 100000, "currency": "GBP", "received": 0, "reserved": -100000 } ], "events": [ { "id": "EV0000000000000000000000000011", "status": "received", "bookingDate": "2025-10-17T01:31:15+02:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": 100000 } ] }, { "id": "EV0000000000000000000000000012", "status": "authorised", "bookingDate": "2025-11-04T09:11:04+01:00", "type": "accounting", "mutations": [ { "currency": "GBP", "received": -100000, "reserved": 100000 } ] }, { "id": "EV0000000000000000000000000013", "status": "booked", "transactionId" : "EV0000000000000000000000000013GBP", "bookingDate": "2025-11-04T09:11:04+01:00", "valueDate": "2025-11-04T09:11:04+01:00", "type": "accounting", "mutations": [ { "balance": 100000, "currency": "GBP", "received": 0, "reserved": -100000 } ] } ], "eventId": "EV0000000000000000000000000013" }, "environment": "test", "timestamp": "2025-11-04T08:11:06.758Z", "type": "balancePlatform.transfer.updated" } ``` ## Fund movement transaction When a grant is disbursed to a receiving balance account or a user makes a repayment, and the transfer is recorded, Adyen sends a [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/balancePlatform.transaction.created) webhook. The webhook includes details about the transaction and the corresponding transfer ID and grant ID. **Grant disbursement transaction created** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3JFBE65XIXOPZ30N", "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "GBP", "value": -1850000 }, "balanceAccountId": "BA00000000000000000000001", "bookingDate": "2023-01-09T16:36:35+01:00", "counterparty": { "balanceAccountId": "BA00000000000000000000002" }, "createdAt": "2023-01-09T16:36:34+01:00", "description": "GR00000000000000000000001", "instructedAmount": { "currency": "GBP", "value": -1850000 }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "transferId": "1OUUU768NUBED14V", "valueDate": "2025-10-15T18:54:08+02:00" }, "environment": "test", "type": "balancePlatform.transaction.created" } ``` ## See also * [Webhook structures and types for Capital](/capital/webhook-types) * [Grant lifecycle and status](/capital/grant-lifecycle-and-status) --- # Source: https://docs.adyen.com/classic-platforms.md Section: Classic Platforms integration Title: Classic integration Description: Power your platform with onboarding, payment processing, and payouts. --- title: "Classic integration" description: "Power your platform with onboarding, payment processing, and payouts." url: "https://docs.adyen.com/classic-platforms" source_url: "https://docs.adyen.com/classic-platforms.md" canonical: "https://docs.adyen.com/classic-platforms" last_modified: "2023-01-16T13:42:00+01:00" language: "en" --- # Classic integration Power your platform with onboarding, payment processing, and payouts. [View source](/classic-platforms.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Adyen for Platforms is an end-to-end payment solution for peer-to-peer marketplaces, on-demand services, crowdfunding platforms, and any other platform business models. Our solution enables you to onboard sellers, service providers or contractors as sub-merchants and accept payments on their behalf. You can also split payments, transfer funds, and pay out to sub-merchants. You maintain complete control over the buyer and seller experience while staying ahead of new regulations, like [PSD2](https://www.adyen.com/knowledge-hub/how-psd2-impacts-the-payment-landscape-marketplaces), and the latest trends in payments, like real time payouts to cards. With Adyen for Platforms, you can: * **Onboard and verify account holders**: Onboard sub-merchants as account holders and perform verification checks with our lightweight and flexible approach, or combine it with your own solution. * **Process payments**: Split payments between one or multiple sub-merchants, deduct costs as needed, and hold funds until payout. * **Transfer funds**: Securely transfer funds between your account and those of your sub-merchants. * **Pay out**: Decide when and how sub-merchants are paid, on demand or automated. * **Reconcile transactions**: Use Adyen-generated reports to build your platform's reconciliation processes. ![](/user/pages/docs/06.classic-platforms/MarketPay-overview.png) Configure the payment flow to suit your business's needs, and customize it as products and services change or new ones are added. ### Supported countries Adyen for Platforms is available in several locations. You can onboard sub-merchants operating in any of the following countries. | Asia Pacific | | ------------ | Australia\ Hong Kong\ New Zealand\ Singapore | North America | | ------------- | Canada\ United States (including Puerto Rico) | Europe | | ------ | Austria\ Belgium\ Bulgaria\ Croatia\ Cyprus\ Czech Republic\ Denmark\ Estonia\ Finland\ France\ Germany\ Greece\ Hungary\ Ireland\ Italy\ Latvia\ Liechtenstein\ Lithuania\ Luxembourg\ Malta\ Netherlands\ Norway\ Poland\ Portugal\ Romania\ Slovakia\ Slovenia\ Spain\ Sweden\ Switzerland\ United Kingdom (including Isle of Man and Jersey) If you plan to accept [point-of-sale](/classic-platforms/platforms-for-pos) payments through Adyen for Platforms, the country in which you want to process point-of-sale payments must also be in the list of supported countries for our [point-of-sale solution](/point-of-sale/what-we-support/supported-languages). ## Onboard and verify account holders Let sub-merchants sign up easily and at scale with a flexible and layered onboarding process: * Onboard businesses, non-profits, and individual sub-merchants in real time. * Retain full control over your platform's user experience. * Enable sub-merchants to start accepting payments immediately after signing up. * Let us perform the verification checks or use your own solution. * Use either a staggered or upfront verification approach. For more information, see [Onboard and verify users](/classic-platforms/onboard-users). ## Process payments For every payment, you can split funds between one or multiple sub-merchants and deduct various costs, such as commission, platform usage or payment fees. The split of funds can be customized for every payment, which reduces your manual workload and streamlines internal processes. You can also let us safely hold funds until they need to be paid out to a sub-merchant. You can offer customers a full range of payment methods, including all major card schemes and mobile wallets such as Apple Pay and Google Pay. We also support local payment methods like iDEAL in the Netherlands, and SEPA throughout the EU. For more information, see [Process payments](/classic-platforms/processing-payments). ## Transfer funds Moving funds around your platform and your sub-merchants can get complicated, especially if you are dealing with many sellers or using complex payment flows. Our solution gives you the flexibility to debit or credit accounts on demand, as well as move funds between your platform and sub-merchant accounts. You can even charge sub-merchants fees, such as subscription or chargeback fees, or credit their account with a bonus as and when needed. For more information, see [Transfer funds](/classic-platforms/fund-transfer). ## Pay out Control the timing, method, and amount of every payout or automate the process entirely. Automated payout schedules can be set up for each sub-merchant individually and modified via our API. Our Payout API enables you to send out payouts by specifying the amount and the account that needs to be debited for the payout. We also support real time payouts to cards as well as regular bank payouts. For more information, see [Pay out to bank accounts](/classic-platforms/payouts/scheduled-payout) and [Pay out to cards](/classic-platforms/payouts/manual-payout/payout-to-cards). ## Reconcile using reports Adyen provides several reports that you can use for your platform's accounting, bookkeeping, and reconciliation processes. You can use reports to: * Reconcile your platform's accounts receivable. * Build a transactional ledger. * Understand fees. For more information, refer to [Reconcile transactions using reports](/classic-platforms/reconciliation-use-cases). ## Next steps [Account structure](/classic-platforms/account-structure) [Learn about your account structure, and how to manage sub-merchants.](/classic-platforms/account-structure) [Quick start](/classic-platforms/quick-start) [Review the steps to integrate Adyen for Platforms.](/classic-platforms/quick-start) --- # Source: https://docs.adyen.com/classic-platforms/account-holders-and-accounts.md Section: Classic Platforms integration Title: Account holders and accounts Description: Create account holders and accounts for sub-merchants that sign up on your platform. --- title: "Account holders and accounts" description: "Create account holders and accounts for sub-merchants that sign up on your platform." url: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts" source_url: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts.md" canonical: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts" last_modified: "2021-11-22T12:16:00+01:00" language: "en" --- # Account holders and accounts Create account holders and accounts for sub-merchants that sign up on your platform. [View source](/classic-platforms/account-holders-and-accounts.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Start the onboarding process by creating an account holder. To create an account holder, you need to get the sub-merchant's legal entity type, collect the minimum required information, and send the information in an API request. Once the account holder is created and active, you can start processing payments for them. However, to pay out their funds, they have to provide more information (such as their bank account details) and pass verification checks. ## Step 1: Identify their legal entity type When creating an account holder, you need to specify the sub-merchant's legal entity type. Their legal entity type determines the kind of information that Adyen requires for their verification checks. An account holder can be one of the following legal entities: **Individual**, **Business**, **Nonprofit**, **Partnership**, or **Public company**. If an account holder signs up using an incorrect legal entity type, you can [change the legal entity](/classic-platforms/account-holders-and-accounts/change-legal-entity). ## Step 2: Collect the minimum required information Collect the minimum required information from your sub-merchant depending on their legal entity type. ### Tab: Individual To create an account holder for an individual, get: * Their name. * Their email. * The country they are operating in. ### Tab: Business To create an account holder for a business, get: * The legal business name. * Their email. * The country they are operating in. * The name and the country of residence of at least one of their ultimate beneficial owners who own 25% or more of the business. If there are none who own 25% or more of the business, get information about a signatory. ### Tab: Nonprofit To create an account holder for a nonprofit, get: * The legal organization name. * Their email. * The country they are operating in. * The name and the country of residence of at least one control officer responsible for managing the organization. ### Tab: Partnership To create an account holder for a business, get: * The legal business name. * Their email. * The country they are operating in. * The name and the country of residence of at least one of their ultimate beneficial owners who own 25% or more of the business. If there are none who own 25% or more of the business, get information about a signatory. ### Tab: Public company To create an account holder for a business, get: * The legal business name. * Their email. * The country they are operating in. * The name and the country of residence of a signatory, and their job title. ## Step 3: Create an account holder Submit the information that you collected with the [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) endpoint. The fields that you need to include depend on their legal entity type. ### Tab: Individual Make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request specifying: * A unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). This is the identifier that you will use in the Platforms API whenever referencing the account holder. * The [legalEntity](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-legalEntity) type set to **Individual**. * The minimum required information you have collected from the sub-merchant, such as [name.firstName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-individualDetails-name-firstName), [name.lastName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-individualDetails-name-lastName), [email](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-email), and [address.country](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-address-country). When collecting the name, make sure they provide the name shown on their photo ID. **Create an individual account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails":{ "address": { "country": "US" }, "email":"tim@green.com", "individualDetails":{ "name":{ "firstName":"Tim", "lastName":"Green" } } }, "legalEntity":"Individual" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"8815214563869136", "accountCode":"138215709", "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity":"Individual", "accountHolderDetails":{ "address":{ "country":"US" }, ... }, "accountHolderStatus": { "status": "Active", ... }, ... } ``` ### Tab: Business Make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request specifying: * A unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). This is the identifier that you will use in the Platforms API whenever referencing the account holder. * The [legalEntity](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-legalEntity) type set to **Business**. * The minimum required information you have collected from the sub-merchant, such as [businessDetails.legalBusinessName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-legalBusinessName), [businessDetails.shareholders](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-shareholders), [email](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-email), and [address.country](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-address-country). **Create a business account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "country": "US" }, "businessDetails": { "legalBusinessName": "Real Good Restaurant Inc.", "shareholders": [ { "name": { "firstName": "Maria", "lastName": "Green" }, "address": { "country": "US" } } ] }, "email": "maria@green.com" }, "legalEntity": "Business" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"8815214563869136", "accountCode":"138215709", "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity":"Business", "accountHolderDetails":{ "address":{ "country":"US" }, ... }, "accountHolderStatus": { "status": "Active", ... }, ... } ``` ### Tab: Nonprofit Make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request specifying: * A unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). This is the identifier that you will use in the Platforms API whenever referencing the account holder. * The [legalEntity](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-legalEntity) type set to **NonProfit**. * The minimum required information you have collected from the sub-merchant, such as [businessDetails.legalBusinessName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-legalBusinessName), [businessDetails.shareholders](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-shareholders), [email](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-email), and [address.country](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-address-country). **Create a nonprofit account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "country": "US" }, "businessDetails": { "legalBusinessName": "Real Good Company", "shareholders": [ { "name": { "firstName": "Maria", "lastName": "Green" }, "address": { "country": "US" } } ] }, "email": "maria@green.com" }, "legalEntity": "NonProfit" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"8815214563869136", "accountCode":"138215709", "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity":"NonProfit", "accountHolderDetails":{ "address":{ "country":"US" }, ... }, "accountHolderStatus": { "status": "Active", ... }, ... } ``` ### Tab: Partnership Make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request specifying: * A unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). This is the identifier that you will use in the Platforms API whenever referencing the account holder. * The [legalEntity](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-legalEntity) type set to **Partnership**. * The minimum required information you have collected from the sub-merchant, such as [businessDetails.legalBusinessName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-legalBusinessName), [businessDetails.shareholders](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-shareholders), [email](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-email), and [address.country](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-address-country). **Create a partnership account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "country": "US" }, "businessDetails": { "legalBusinessName": "Real Good Partnership", "shareholders": [ { "name": { "firstName": "Maria", "lastName": "Green" }, "address": { "country": "US" } } ] }, "email": "partnership@example.com" }, "legalEntity": "Partnership" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"8815214563869136", "accountCode":"138215709", "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity":"Partnership", "accountHolderDetails":{ "address":{ "country":"US" }, ... }, "accountHolderStatus": { "status": "Active", ... }, ... } ``` ### Tab: Public company Make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request specifying: * A unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). This is the identifier that you will use in the Platforms API whenever referencing the account holder. * The [legalEntity](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-legalEntity) type set to **PublicCompany**. * The minimum required information you have collected from the sub-merchant, such as [businessDetails.legalBusinessName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-legalBusinessName), [email](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-email), [address.country](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-address-country), and the [signatories](https://docs.adyen.com/api-explorer/Account/6/post/createAccountHolder#request-accountHolderDetails-businessDetails-signatories) information. **Create a public company account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "country": "US" }, "businessDetails": { "legalBusinessName": "Real Good Public Company", "signatories":[ { "name":{ "firstName":"Sam", "lastName":"Hopper" }, "jobTitle": "Vice President", "address": { "country": "US" } } ] }, "email": "publiccompany@example.com" }, "legalEntity": "PublicCompany" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"8815214563869136", "accountCode":"138215709", "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity":"PublicCompany", "accountHolderDetails":{ "address":{ "country":"US" }, ... }, "accountHolderStatus": { "status": "Active", ... }, ... } ``` Requests using [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) are processed asynchronously. You'll receive a response to your API request, but you must wait for the webhooks to know the final result of a request. The API response may contain any of the following HTTP status codes: * **HTTP 200**: You can use the information that the API returns in the response, such as the `accountCode`, but you should wait for the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) and [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_CREATED) notification webhooks before performing any business logic. The notification webhooks confirm when the resources have been added to our central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) and [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_CREATED) notification webhooks to confirm if the account holder has been successfully created. Get the corresponding `accountCode` from the notification. When an account holder is created, an **account** is also automatically created identified by the [accountCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#responses-200-accountCode). Save the `accountCode`—this is the ID you will use to process the account holder's transactions. The [accountHolderStatus.status](https://docs.adyen.com/api-explorer/Account/latest/post/createAccount#request-createAccountHolder-accountHolderStatus) determines if processing payments and payouts are allowed. A newly created account holder has `accountHolderStatus.status` **Active**. This means that you can immediately start processing payments on their behalf. For more information, refer to [account holder statuses](/classic-platforms/verification-process#account-holder-statuses). ## Step 4: (Optional) Create additional accounts You can optionally create additional accounts for an account holder. For example, create multiple accounts if an account holder has different business lines and would like to keep funds and accounting history separate for each line. To create an additional account, make a [/createAccount](https://docs.adyen.com/api-explorer/#/Account/createAccount) request and provide the [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccount#request-accountHolderCode). **Create an additional account** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccount \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE" }' ``` Requests using [/createAccount](https://docs.adyen.com/api-explorer/#/Account/createAccount) are processed asynchronously. You'll receive a response to your API request, but you must wait for the webhooks to know the final result of a request. The API response may contain any of the following HTTP status codes: * **HTTP 200**: You can use the information that the API returns in the response, such as the `accountCode`, but you should wait for the [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_CREATED) notification webhook before performing any business logic. The notification confirms when the resources have been added to our central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_CREATED) notification webhook to confirm if the account holder has been successfully created. Get the corresponding `accountCode` from the notification. ## Next steps [required](/classic-platforms/onboard-users) [Onboard and verify users](/classic-platforms/onboard-users) [Choose when and how to collect the required information from your account holders.](/classic-platforms/onboard-users) [required](/classic-platforms/configure-notifications) [Verification process](/classic-platforms/configure-notifications) [Find out the required information and how to get the verification results.](/classic-platforms/configure-notifications) --- # Source: https://docs.adyen.com/classic-platforms/account-holders-and-accounts/change-legal-entity.md Section: Classic Platforms integration Title: Changing the legal entity type Description: Modify the account holder's legal entity type to onboard them with the correct verification process. --- title: "Changing the legal entity type" description: "Modify the account holder's legal entity type to onboard them with the correct verification process." url: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts/change-legal-entity" source_url: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts/change-legal-entity.md" canonical: "https://docs.adyen.com/classic-platforms/account-holders-and-accounts/change-legal-entity" last_modified: "2020-09-01T12:27:00+02:00" language: "en" --- # Changing the legal entity type Modify the account holder's legal entity type to onboard them with the correct verification process. [View source](/classic-platforms/account-holders-and-accounts/change-legal-entity.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Account holders sometimes sign up with the incorrect legal entity type. To fix this, change the legal entity type with an [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request. When you change the legal entity type, the account holder retains the `accountHolderCode`, `accountCode` and the transaction history. To change the legal entity type, you can: * [Migrate existing details](#migrate-existing), including the verification checks. * Or [provide new details](#provide-new-details). This feature is supported from **v5 and later** of the [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) endpoint. ## Migrating existing details If you choose to migrate existing details, we also migrate the identity check status and the passport verification from the previous legal entity to the new one. We will perform the bank account verification again if required for the new legal entity. After we complete the update, you get the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification, containing the migrated and new verification check statuses or requirements. ### Changing from Individual to Business To change from **Individual** to **Business**, make an [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request and provide the following parameters: **Update legal entity to business** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "businessDetails":{ "legalBusinessName": "ACCOUNT_HOLDER_BUSINESS_NAME", "registrationNumber": "123456789" } }, "legalEntity": "Business" }' ``` ### Changing from Business to Individual You can only migrate data if the business account holder has only one shareholder. If the account holder has multiple shareholders, the request is rejected. To change from **Business** to **Individual**, make an `/updateAccountHolder` request and provide the following fields: **Update legal entity to individual** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity": "Individual" }' ``` ## Providing new details Alternatively, you can provide new details when changing the legal entity of an account holder. After we complete the update, you get the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification, containing new verification check statuses or requirements. ### Changing from Individual to Business To change from **Individual** to **Business**, make an `/updateAccountHolder` request and provide the following parameters: **Update to business and provide new details** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode" : "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity": "Business", "accountHolderDetails":{ "businessDetails": { "legalBusinessName": "ACCOUNT_HOLDER_BUSINESS_NAME", "registrationNumber": "RegNumber12712", "shareholders": [ { "address": { "city": "San Francisco", "country": "US", "houseNumberOrName": "9", "postalCode": "10621", "stateOrProvince": "CA", "street": "AwesomeStreet" }, "email": "test@email.com", "name": { "firstName": "Simon", "gender": "UNKNOWN", "lastName": "Hopper" }, "personalData": { "dateOfBirth": "1990-09-30", "documentData": [ { "number": "fa141fa2", "type": "ID" } ] } } ] } } }' ``` ### Changing from Business to Individual To change from **Business** to **Individual**, make an `/updateAccountHolder` request and provide the following parameters: **Update to individual and provide new details** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode" : "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "legalEntity": "Individual", "accountHolderDetails":{ "individualDetails": { "name": { "firstName": "Simon", "gender": "UNKNOWN", "lastName": "Hopper" }, "personalData": { "dateOfBirth": "1990-09-30", "documentData": [ { "number": "IdNumber42382", "type": "ID" } ] } } } }' ``` --- # Source: https://docs.adyen.com/classic-platforms/account-structure.md Section: Classic Platforms integration Title: Platforms account structure Description: Understand account structures to design a platform that suits your business needs. --- title: "Platforms account structure" description: "Understand account structures to design a platform that suits your business needs." url: "https://docs.adyen.com/classic-platforms/account-structure" source_url: "https://docs.adyen.com/classic-platforms/account-structure.md" canonical: "https://docs.adyen.com/classic-platforms/account-structure" last_modified: "2021-02-18T15:07:00+01:00" language: "en" --- # Platforms account structure Understand account structures to design a platform that suits your business needs. [View source](/classic-platforms/account-structure.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. ##### See examples For a practical application of platform structures, refer to [Example structures](/classic-platforms/account-structure/example-structures). To design a platform that suits your use cases, start with learning about: * Your Adyen account. * The resources within a platform. * How your Adyen account and your platform are connected. ## Your Adyen account When you sign up for an Adyen account, you receive a **company account** and one or several **merchant accounts**. The merchant account is where you configure payment methods and processing currencies. For many of our Adyen for Platforms customers, having one merchant account for each country is a common Adyen account setup. We refer to all your merchant accounts as your **Adyen merchant accounts**. For more information about your Adyen account, refer to [Adyen account structure](/account/account-structure). ## Your platform A platform is where you create and onboard third parties, hold funds, and trigger payouts. We refer to third parties in your platform—sellers, service providers, contractors, and so on—as sub-merchants. For each sub-merchant, you need to create the following resources: * **Account holder**: Represents the sub-merchant's entity. This resource contains all information about the sub-merchant, including individual details, company details, and bank account details for payouts. Adyen uses this information to perform Know Your Customer (KYC) checks. * **Account**: Holds the funds of an account holder. All financial activities in your platform, such as paying out to a bank account, happen through accounts. An account holder can have [multiple accounts](/classic-platforms/account-structure/example-structures#common-structures) but a single account is sufficient in most use cases. Similarly, your entity has its own account holder and account. * **Liable account holder**: Represents your entity. * **Liable account**: Your account where your funds are held. Adyen draws fees from this account. This account is liable if other accounts in your platform incur negative balances due to refunds and chargebacks. You can also have multiple liable accounts for accounting purposes to keep sets of transactions and funds separate. We refer to all accounts where financial activities are carried out as **accounts in your platform**. To see examples of platform account structures, refer to [Common structures](/classic-platforms/account-structure/example-structures#common-structures). ## How funds flow Your Adyen account is connected to your platform through the flow of funds. When customers of your platform make a payment, the payment is processed through **your Adyen merchant accounts**. Then the payment is captured and settled to the **accounts in your platform**. For example, here's the process of receiving a payment to paying out the account holder: 1. A customer buys goods or services on your platform. The payment is processed through your Adyen merchant account. 2. The payment is captured and settled to the accounts in your platform. You specify which accounts when you [split the funds](/classic-platforms/processing-payments#providing-split-instructions) at the time of payment or capture. The funds are held in the accounts in your platform until they are paid out. 3. When you pay out an account holder, the funds are taken out of their account and sent to any of their verified bank accounts. In case of a refund: 1. You process refund requests through your Adyen merchant account. 2. Funds are debited from the accounts in your platform, and credited to the customer. For an illustration of how your Adyen account and your platform account are connected, refer to [Example structures](/classic-platforms/account-structure/example-structures). ## See also * [Example account structures](/classic-platforms/account-structure/example-structures) --- # Source: https://docs.adyen.com/classic-platforms/account-structure/example-structures.md Section: Classic Platforms integration Title: Example structures Description: See applications of common platform account structures. --- title: "Example structures" description: "See applications of common platform account structures." url: "https://docs.adyen.com/classic-platforms/account-structure/example-structures" source_url: "https://docs.adyen.com/classic-platforms/account-structure/example-structures.md" canonical: "https://docs.adyen.com/classic-platforms/account-structure/example-structures" last_modified: "2019-09-02T15:18:00+02:00" language: "en" --- # Example structures See applications of common platform account structures. [View source](/classic-platforms/account-structure/example-structures.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. The image below shows how your Adyen account and your platform account are connected. Let's say that you have a company called **Example Travel** with the following setup: * An Adyen company account **ExampleTravelLLC**. * Two Adyen merchant accounts **ExampleTravel\_NL** and **ExampleTravel\_US**. * A platform called **ExampleTravel\_Platform**. * The **ExampleTravel\_Platform** has: * A business account holder with one account. * An individual account holder with multiple accounts. * Your account holder and liable account. ![This is an example Platforms structure.](/user/pages/docs/06.classic-platforms/00.account-structure/example-structures/platform-structure.svg?decoding=auto\&fetchpriority=auto)   The boxes in blue—**your Adyen merchant accounts** and the **accounts in your platform**—represent the resources where funds flow. For example, when a customer in the Netherlands pays for a trip offered by the individual account holder: 1. The payment is processed in **ExampleTravel\_NL**. 2. The funds are settled in the accounts in your platform. For this example, you specify to split the funds between your **Liable account** and the individual account holder's **Account 2**. The funds are kept in the account holder's account until they are paid out. 3. You pay out to the individual account holder's verified bank account. ## Common structures for the accounts in your platform Adyen for Platforms provides a flexible account structure that supports various platform types and models. In designing your platform, consider how you want to manage accounts and payouts. Most of our Adyen for Platforms customers use a one-to-one relationship between the account and bank account. * 1 account holder with 1 bank account. * 1 account. You pay out from the account to the account holder's verified bank account. ### Multiple accounts and bank accounts While most platforms only need one account per account holder, you can optionally create multiple accounts. Having multiple accounts helps when an account holder has different business lines and would like to keep funds and accounting history separate for each line. Similarly, an account holder can have multiple bank accounts. You can use a many-to-many relationship between accounts and bank accounts. * 1 account holder with multiple bank accounts. * Multiple accounts. To pay out the account holder, the platform instructs which account to take funds from and which verified bank account to send the funds to. In the image below, the account holder has two accounts and two verified bank accounts. When paying out, the platform directs to pay out the funds from **Account 2** and send it to **Bank account 1**.   ![](/user/pages/docs/06.classic-platforms/00.account-structure/example-structures/many-to-many-structure.svg?decoding=auto\&fetchpriority=auto)   In case of a one-to-many or many-to-one relationship between accounts and bank accounts, the platform instructs the source account or the destination bank account. --- # Source: https://docs.adyen.com/classic-platforms/api.md Section: Classic Platforms integration Title: Platforms API Reference Description: Learn about Platforms APIs. --- title: "Platforms API Reference" description: "Learn about Platforms APIs." url: "https://docs.adyen.com/classic-platforms/api" source_url: "https://docs.adyen.com/classic-platforms/api.md" canonical: "https://docs.adyen.com/classic-platforms/api" last_modified: "2019-07-08T08:27:00+02:00" language: "en" --- # Platforms API Reference Learn about Platforms APIs. [View source](/classic-platforms/api.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. The Adyen for Platforms API provides endpoints you connect to using your API credentials. These endpoints represent specific actions like managing account holders, processing payments, making payouts, and so on. To learn about Platforms API, refer to the corresponding sections in API Explorer: * [Account API](https://docs.adyen.com/api-explorer/#/Account/overview) * [Fund API](https://docs.adyen.com/api-explorer/#/Fund/overview) * [Notification Configuration API](https://docs.adyen.com/api-explorer/#/NotificationConfigurationService/overview) * [Notifications](https://docs.adyen.com/api-explorer/#/NotificationService/overview) * [Hosted onboarding API](https://docs.adyen.com/api-explorer/Hop/latest/overview) --- # Source: https://docs.adyen.com/classic-platforms/configure-notifications.md Section: Classic Platforms integration Title: Configure notifications Description: Learn how to set up and test notifications. --- title: "Configure notifications" description: "Learn how to set up and test notifications." url: "https://docs.adyen.com/classic-platforms/configure-notifications" source_url: "https://docs.adyen.com/classic-platforms/configure-notifications.md" canonical: "https://docs.adyen.com/classic-platforms/configure-notifications" last_modified: "2021-09-03T10:52:00+02:00" language: "en" --- # Configure notifications Learn how to set up and test notifications. [View source](/classic-platforms/configure-notifications.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. All Platforms API create, update, and delete requests are asynchronous, so you must rely on notifications to know the final result of a request. These notifications are sent as webhooks to the corresponding URLs configured on your server. On this page you'll learn how to: * [Create a configuration](#create-a-notification-configuration) for each notification type that you want to receive from Adyen for Platforms. * [Get information](#get-a-list-of-configurations) about existing notification configurations. * [Test](#test-a-notification) your notification set up. * [Update](#update-notification-configurations) existing notification configurations. * [Delete](#delete-notification-configurations) notification configurations. You also need to [accept each notification](#accept-notifications), to confirm that you have received it. ## Create a notification configuration To configure a notification, make a POST [/createNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/createNotificationConfiguration) call and pass the URL where the notifications should be sent and the [notification types](/classic-platforms/notification-types) that you want to receive. You can also provide the message format, protocol, username, password, and other parameters, as shown in the example below. **Create notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "apiVersion": 6, "active": true, "description":"Your unique description", "eventConfigs":[ { "eventType":"ACCOUNT_HOLDER_VERIFICATION", "includeMode":"INCLUDE" }, { "eventType":"ACCOUNT_HOLDER_CREATED", "includeMode":"INCLUDE" } ], "notifyURL":"https://www.merchant-domain.com/notification-handler", "notifyUsername":"yourUsername", "notifyPassword":"yourPassword", "sslProtocol":"SSL" } }' ``` **Response** ```json { "pspReference": "8515659468351668", "configurationDetails": { "active": true, "apiVersion": 5, "description": "Your unique description", "eventConfigs": [ { "eventType": "ACCOUNT_HOLDER_VERIFICATION", "includeMode": "INCLUDE" }, { "eventType": "ACCOUNT_HOLDER_CREATED", "includeMode": "INCLUDE" } ], "notificationId": 20272, "notifyURL": "https://www.merchant-domain.com/notification-handler", "sslProtocol": "SSLInsecureCiphers" } } ``` ## Get a configuration To get the details of a previously configured notification, make a POST [/getNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/getNotificationConfiguration) call and pass the notification ID as a parameter. **Get an existing configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/getNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "notificationId":20272 }' ``` **Response** ```json { "pspReference":"9914734158490053", "configurationDetails":{ "active":true, "apiVersion":5, "description":"Your unique description", "eventConfigs":[ { "NotificationEventConfiguration":{ "eventType":"ACCOUNT_HOLDER_VERIFICATION", "includeMode":"INCLUDE" } } ], "notificationId":2, "notifyURL":"https://www.merchant-domain.com/notification-handler", "sslProtocol":"SSL" } } ``` ## Get a list of configurations In addition, you can get a list of all configured notifications. For this, make the [/getNotificationConfigurationList](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/getNotificationConfigurationList) call and pass an empty request as a parameter. **Get all configurations** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/getNotificationConfigurationList \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ }' ``` **Response** ```json { "pspReference": "8815658961765256", "configurations": [ { "active": true, "description": "TestNotif11", "eventConfigs": [ { "eventType": "ACCOUNT_HOLDER_VERIFICATION", "includeMode": "INCLUDE" } ], "notificationId": 20052, "notifyURL": "https://www.merchant-domain.com/notification-handler", "sslProtocol": "SSLInsecureCiphers" }, { "active": false, "apiVersion": 6, "eventConfigs": [ { "eventType": "TRANSFER_FUNDS", "includeMode": "INCLUDE" }, { "eventType": "BENEFICIARY_SETUP", "includeMode": "INCLUDE" } ], "notificationId": 20008, "notifyURL": "https://www.merchant-domain.com/notification-handler", "sslProtocol": "SSLInsecureCiphers" } ] } ``` ## Update notification configurations To change notification settings, make a POST [/updateNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/updateNotificationConfiguration) call and pass new settings as its parameters. The notification to be updated is specified by the `notificationId` value. **Update a notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/updateNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "active":false, "apiVersion":6, "description":"new description799847", "eventConfigs":[ { "eventType":"ACCOUNT_HOLDER_CREATED", "includeMode":"EXCLUDE" }, { "eventType":"ACCOUNT_CREATED", "includeMode":"INCLUDE" } ], "notificationId":3, "notifyPassword":"testPassword2", "notifyURL":"https://www.merchant-domain.com/notification-handler", "notifyUsername":"testUserName2", "sendActionHeader":false, "sslProtocol":"SSL" } }' ``` **Response** ```json { "pspReference":"9914734160470077", "configurationDetails":{ "active":false, "apiVersion":5, "description":"new description799847", "eventConfigs":[ { "eventType":"ACCOUNT_CREATED", "includeMode":"INCLUDE" }, { "eventType":"ACCOUNT_HOLDER_CREATED", "includeMode":"EXCLUDE" } ], "notificationId":3, "notifyURL":"https://www.merchant-domain.com/notification-handler", "sslProtocol":"SSLInsecureCiphers" } } ``` ## Delete notification configurations If you no longer need some of configured notifications, delete them by making a POST [/deleteNotificationConfigurations](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/deleteNotificationConfigurations) call. Notifications to be deleted are specified by the IDs in the `notificationIds` array. **Delete notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/deleteNotificationConfigurations \ -H 'x-API-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "notificationIds":[ 11, 26 ] }' ``` **Response** ```json { "pspReference":"9914713525761479" } ``` ## Accept notifications To confirm that you have received a notification, your server should acknowledge the notification with the following response: ```bash [accepted] ``` We use [at-least-once delivery](http://www.cloudcomputingpatterns.org/At-least-once_Delivery) to ensure that your server has received a notification. If your server has not acknowledged a notification within 10 seconds we will queue all notifications to this endpoint. We'll then retry sending the notification until it is accepted. Once accepted, you'll receive all your queued notifications. Retry attempts will happen regularly, at increasing time intervals: * 2 minutes * 5 minutes * 10 minutes * 15 minutes * 30 minutes * 1 hour * 2 hours * 4 hours Retries then happen every 8 hours for the following 7 days. ## Test a notification To test a notification configuration, make a POST [/testNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/testNotificationConfiguration) call and pass a `notificationId` as a parameter. If you leave the `eventTypes` array empty, all the configured notification types will be generated. **Test notifications** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/testNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "eventTypes":[], "notificationId":10 }' ``` **Response in case of successful test** ```json { "pspReference":"9914734161240289", "errorMessages":[ ], "eventTypes":[ "ACCOUNT_HOLDER_CREATED" ], "exchangeMessages":[ { "ExchangeMessage":{ "messageCode":"Number", "messageDescription":"1" } }, { "ExchangeMessage":{ "messageCode":"Title", "messageDescription":"Test 1: Test_ACCOUNT_HOLDER_CREATED" } } ], "notificationId":10, "okMessages":[ "ResponseCode: 200", "ResponseTime_ms: 6", "Output: {\"name\":\"[accepted]\"}" ] } ``` **Response in case of a failed test** ```json { "pspReference":"9914734162410311", "errorMessages":[ "Failed to send message. Error description: Not equiped to send com.adyen.services.marketplace.notification.event.account.AccountHolderVerificationNotification" ], "eventTypes":[ "ACCOUNT_HOLDER_VERIFICATION" ], "exchangeMessages":[ { "ExchangeMessage":{ "messageCode":"Number", "messageDescription":"1" } }, { "ExchangeMessage":{ "messageCode":"Title", "messageDescription":"Test 1: Test_ACCOUNT_HOLDER_VERIFICATION" } } ], "notificationId":10, "okMessages":[ ] } ``` ## Next steps [Notification types](/classic-platforms/notification-types) [Learn about notification types sent by Adyen for Platforms.](/classic-platforms/notification-types) [Enable HMAC signatures](/classic-platforms/configure-notifications/signing-notifications-with-hmac) [Add extra security to your notifications.](/classic-platforms/configure-notifications/signing-notifications-with-hmac) --- # Source: https://docs.adyen.com/classic-platforms/configure-notifications/signing-notifications-with-hmac.md Section: Classic Platforms integration Title: Signing notifications with HMAC Description: Add an extra layer of security to the notifications sent by Adyen for Platforms. --- title: "Signing notifications with HMAC" description: "Add an extra layer of security to the notifications sent by Adyen for Platforms." url: "https://docs.adyen.com/classic-platforms/configure-notifications/signing-notifications-with-hmac" source_url: "https://docs.adyen.com/classic-platforms/configure-notifications/signing-notifications-with-hmac.md" canonical: "https://docs.adyen.com/classic-platforms/configure-notifications/signing-notifications-with-hmac" last_modified: "2023-03-28T13:32:00+02:00" language: "en" --- # Signing notifications with HMAC Add an extra layer of security to the notifications sent by Adyen for Platforms. [View source](/classic-platforms/configure-notifications/signing-notifications-with-hmac.md) This feature is supported from [Notifications v5](https://docs.adyen.com/api-explorer/#/NotificationService/v5/overview) and later. For information about platform integrations built after August 1, 2022, refer to our [new integration guide](/adyen-for-platforms-model) instead. By default, Adyen notifications use basic authentication. You can optionally enable [Hash-based Message Authentication Code (HMAC)](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) signatures, which adds an extra layer of security to your [standard notifications](/development-resources/webhooks/webhook-types#other-webhooks).  An HMAC signature is calculated using a request's key-value pairs and a secret key, which is known only to you and the Adyen payments platform. By verifying this signature, you'll confirm that the notification was not modified during transmission. ## Enable HMAC signatures You can use any **32bit hexadecimal** HMAC key you like. If you subscribe to payment notifications you can reuse the same key. For more information, see [Signing notifications with HMAC](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures). If you generate a new HMAC key, your previous notifications will still be signed with your previous HMAC key. ## Subscribe to notifications Subscribe to notifications with a HMAC Signature Key to receive HMAC signed notifications to the URL you specify in the `/createNotificationConfiguration` call. We activate the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) notification and send it to the endpoint on your server (https\://www\.merchant-domain.com/notification-handler) using the specified connection credentials (**testUserName** and **testPassword**). **Create notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "active":true, "apiVersion":6, "description":"Your unique description", "eventConfigs":[ { "eventType":"ACCOUNT_CREATED", "includeMode":"INCLUDE" } ], "hmacSignatureKey":"79A3EAF309C43708726A8C284C0D72618696A12E840DFA1DF3A158AFA3B577DA", "notifyPassword":"password", "notifyURL":"https://www.merchant-domain.com/notification-handler", "notifyUsername":"yourUsername" } }' ``` **Response** ```json { "pspReference": "8515658977098901", "configurationDetails": { "active": true, "apiVersion": 6, "description": "Your unique description", "eventConfigs": [ { "eventType": "ACCOUNT_CREATED", "includeMode": "INCLUDE" } ], "notificationId": 20271, "notifyURL": "https://www.merchant-domain.com/notification-handler", "sslProtocol": "SSLInsecureCiphers" } } ``` ## Verify HMAC signature To verify the signature, retrieve the values of the `HmacSignature` and `Protocol` parameters from the HTTP header of the incoming notification*.* `HmacSignature` contains the signature itself and `Protocol` is the protocol used to create the signature (only SHA256 is supported). To compute the HMAC signature, apply the algorithm/protocol to the whole HTTP body using the key. If the computed HMAC signature is equal to the one in the header, the verification is successful. Perform this check before deserializing the request. If you perform deserialization before verifying, a valid signature may fail due to a different order of the JSON elements  ## HMAC signature examples To calculate the HMAC signature: ```java import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import java.math.BigInteger; import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Base64; public class MarketplaceNotificationHmacExampleTest { @Test public void testMarketplaceNotificationHmac() { // Example HEX Key (submitted at the moment of subscription) String hmacSignatureKey = "79A3EAF309C43708726A8C284C0D72618696A12E840DFA1DF3A158AFA3B577DA"; // Signature. Retrieved from HTTP header under the name HmacSignature. String hmacSignature = "A2bHr0WPlKg1fJLVEDReVAdUDWt3znmsuYvp2KdihXY="; // Protocol. Retrieved from HTTP header under the name Protocol. String protocol = "HmacSHA256"; // Payload. the payload of the notification consists on the whole body of the notification String payload = "{\"eventDate\":\"2018-07-09T12:07:27+02:00\",\"eventType\":\"ACCOUNT_HOLDER_CREATED\",\"executingUserKey\":\"ws\",\"live\":false,\"pspReference\":\"9915311308462016\"," + "\"content\":{\"invalidFields\":[],\"pspReference\":\"9915311308462016\",\"accountCode\":\"9915311308462024\",\"accountHolderCode\":\"6750d8cf-80ab-4a34-b2c5-f8a1f37a79da\"," + "\"accountHolderDetails\":{\"bankAccountDetails\":[],\"email\":\"testEmail@gmail.com\",\"individualDetails\":{\"name\":{\"firstName\":\"TestFirstName\",\"gender\":\"MALE\"," + "\"lastName\":\"TestData\"}},\"merchantCategoryCode\":\"7999\"},\"accountHolderStatus\":{\"status\":\"Active\",\"processingState\":{\"disabled\":false," + "\"processedFrom\":{\"currency\":\"EUR\",\"value\":0},\"processedTo\":{\"currency\":\"EUR\",\"value\":0},\"tierNumber\":0},\"payoutState\":{\"allowPayout\":false," + "\"disabled\":false,\"tierNumber\":0},\"events\":[]},\"legalEntity\":\"Individual\",\"verification\":{}}}"; try { // decode HEX Key into bytes byte[] keyBytes = new BigInteger(hmacSignatureKey, 16).toByteArray(); // get payload in bytes byte[] payloadBytes = payload.getBytes(StandardCharsets.UTF_8); // instantiate the MAC object using HMAC / SHA256 Mac hmacSha256 = Mac.getInstance(protocol); // create a key object using the secret key and MAC object SecretKey secretKey = new SecretKeySpec(keyBytes, hmacSha256.getAlgorithm()); // initialise the MAC object hmacSha256.init(secretKey); // finalise the MAC operation byte[] signedPayload = hmacSha256.doFinal(payloadBytes); // encode the signed payload in Base64 byte[] encodedSignedPayload = Base64.getEncoder().encode(signedPayload); System.out.println("original HMAC signature: " + hmacSignature); System.out.println("computed HMAC signature: " + new String(encodedSignedPayload, StandardCharsets.US_ASCII)); // assert the calculated Base64 encoded HMAC is equal to the received Base64 encoded HMAC Assertions.assertArrayEquals(encodedSignedPayload, hmacSignature.getBytes(StandardCharsets.UTF_8)); } catch (NoSuchAlgorithmException e) { // HmacSHA256 should be supported } catch (InvalidKeyException e) { // The key is invalid } } } ``` If the calculated `HmacSignature` matches the value you received in the notification, the notification wasn't modified during transmission. The following is an example of a header containing an HMAC signature: ```bash [Content-Type: application/json; charset=utf-8, Authorization: Basic dGVzdFVzZXJOYW1lOnRlc3RQYXNzd29yZA==, HmacSignature: awA4ZTCAYLp/ctyt9yFPlidqZcLjWs5EZikhIQCz98k=, Protocol: HmacSHA256, Content-Length: 819, Host: localhost:57851, Connection: Keep-Alive, User-Agent: Adyen HttpClient 1.0, Accept-Encoding: gzip,deflate] ``` ## See also * [Configure notifications](/classic-platforms/configure-notifications) * [Notification types](/classic-platforms/notification-types) * [HMAC](https://en.wikipedia.org/wiki/HMAC) --- # Source: https://docs.adyen.com/classic-platforms/error-codes.md Section: Classic Platforms integration Title: Error codes Description: Learn about error codes and what they mean. --- title: "Error codes" description: "Learn about error codes and what they mean." url: "https://docs.adyen.com/classic-platforms/error-codes" source_url: "https://docs.adyen.com/classic-platforms/error-codes.md" canonical: "https://docs.adyen.com/classic-platforms/error-codes" last_modified: "2019-05-02T06:24:00+02:00" language: "en" --- # Error codes Learn about error codes and what they mean. [View source](/classic-platforms/error-codes.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. This page contains codes and descriptions of all errors that may occur when you communicate with the Platforms API. These codes are returned in the `errorCode` fields in both the Platforms API response and in the [notifications](/classic-platforms/notification-types). ## General error codes These are the common error codes, which may be returned when you communicate with Adyen for Platforms: | Error code | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 10\_001 | Internal timeout | | 10\_002 | Internal error: message='{0}' | | 10\_003 | Failed to authorize user | | 10\_004 | Account with accountCode='{0}' does not exist | | 10\_005 | Account already exists: accountCode='{0}' | | 10\_006 | Failed to create account: accountCode='{0}' | | 10\_007 | Failed to create account: accountCode='{0}'; message='{1}' | | 10\_008 | Invalid accountCode: accountCode='{0}'; pattern='{1}' | | 10\_009 | Invalid email address: '{0}'' | | 10\_010 | Account with accountCode='{0}' has already been closed | | 10\_011 | Failed to close account: accountCode='{0}' | | 10\_012 | Invalid account type: accountCode='{0}', type='{1}', expected='{2}' | | 10\_013 | Failed to upload document '{0}' | | 10\_014 | Shareholder with code='{0}' does not exist | | 10\_015 | Required field '{0}' is not specified | | 10\_016 | The country code '{0}' is not supported | | 10\_017 | No content supplied for document '{0}' | | 10\_018 | File '{0}' can possibly contain malware or a virus. Not accepted | | 10\_019 | Failed to delete bank accounts for account holder '{0}' | | 10\_020 | Failed to delete shareholders for account holder '{0}' | | 10\_021 | Failed to retrieve documents for account '{0}' | | 10\_022 | Failed to get account details for account '{0}' | | 10\_023 | Failed to get legal entity type for account '{0}' | | 10\_024 | Invalid accountstatus '{0}' | | 10\_025 | Invalid Notification Service Version '{0}' | | 10\_026 | Invalid Notification URL '{0}' | | 10\_027 | Not able to determine accountHolder balance | | 10\_028 | Amount not specified | | 10\_029 | Invalid amount '{0}' | | 10\_030 | Events cannot be included and excluded from the notification in the same time. Invalid events: {0} | | 10\_031 | Notification configuration cannot be saved. Details: | | 10\_032 | There is no notification configuration with id {0}, defined for marketplace {1} | | 10\_033 | Notification configuration {0} cannot be retrieved | | 10\_034 | Notification configurations {0} cannot be deleted | | 10\_035 | Failed to retrieve account holder '{0}' | | 10\_036 | Details of account {0} cannot be saved | | 10\_037 | The minimum accepted file size : {0} bytes. The size of the file '{1}' is {2} bytes | | 10\_039 | File '{0}' is of invalid format. Accepted formats: pdf, jp(e)g and png | | 10\_046 | Bank account not found, accountHolder: '{0}', bankAccountUUID: '{1}' | | 10\_047 | Failed to retrieve account holder review information | | 10\_048 | There is no review information with review id '{0}' | | 10\_049 | Failed to update account holder review information for review id '{0}' | | 10\_050 | There is no review comment specified for review id '{0}' | | 10\_051 | Cannot update review with review id '{0}'. The status '{1}' is not a final status | | 10\_052 | Cannot update review with review id '{0}', since it is already in the final status | | 10\_053 | Notification configuration {0} cannot be saved, since its description is missing | | 10\_054 | Notification configuration {0} cannot be saved, since description '{1}' has already be reserved for another configuration. Please provide another description. | | 10\_055 | Marketplace with code='{0}' does not exist | | 10\_056 | Modification of KYC check review '{0}' is not allowed | | 10\_057 | KYC check review retrieval is not allowed | | 10\_058 | Payout limit reached for account '{0}', limit: '{1}' | | 10\_059 | Failed to suspend account: accountCode='{0}' | | 10\_060 | Failed to unSuspend account: accountCode='{0}' | | 10\_061 | Operation not allowed because of account status. accountCode: '{0}', status: '{1}' | | 10\_062 | Processing is not allowed because the account holder {0} is not in the processing state. | | 10\_063 | Payout is not allowed because the account holder {0} is not in the payout state. | | 10\_064 | Unable to retrieve KYC verification statuses for account holder {0} | | 10\_066 | There is not enough balance available for account {0}. Available balance: {1}; Requested amount: {2} | | 10\_067 | Not able to find bank account for {0} in currency {1} with bank account UUID {2} | | 10\_068 | Not able to find bank account for {0} in currency {1} | | 10\_069 | Payout has been failed for account {0}. Details: {1}. | | 10\_070 | Filename is missing for the document being uploaded. Account holder code: {0} | | 10\_071 | When disabling account holder state, a reason must be specified | | 10\_072 | Failed to update state {0} for account holder {1} | | 10\_073 | Unknown Tx Satus: {0} | | 10\_074 | The bankAccountUUID is missing, this is required for bank statement upload | | 10\_075 | Processing limit reached for account '{0}', limit: '{1}' | | 10\_076 | No transferCodes configured for Marketplace | | 10\_077 | Provided transfer code cannot be used | | 10\_078 | Fund transfer failed for account {0} | | 10\_079 | Source and destination must be different accounts | | 10\_080 | No account holder or account specified | | 10\_081 | Both bank account and shareholder specified | | 10\_082 | KYC Check {0} not defined for owner {1} | | 10\_083 | KYC check {0} is already in state {1} | | 10\_084 | Schedule '{0}' is unknown | | 10\_085 | Beneficiary flow not allowed for marketPlace | | 10\_086 | Account {0} already has a beneficiary setup | | 10\_087 | Account {0} has already been paid out | | 10\_088 | The maximum accepted file size : {0} bytes. The size of the file '{1}' is {2} bytes | | 10\_089 | Not allowed to transfer a negative amount. Amount: {0} | | 10\_090 | Bank account with uuid {0} of account {1} already exists. | | 10\_091 | The liable account holder, {0}, can not be modified, please contact Adyen Support for modifications. | | 10\_092 | When disabling account schedule, a reason must be specified | | 10\_093 | Existing beneficiary transfer in progress for account, please try again later. | | 10\_094 | Either shareholder code or bank account UUID, but not both of them, can be provided in order to retrieve account holder documents | | 10\_095 | The beneficiary account holder {0} has not completed onboarding requirements for a tier equal to or higher than the benefactor account holder {1} | | 10\_096 | Increasing the tier for account holder {0} is not possible | | 10\_097 | Provided {0} tier {1} is invalid | | 10\_098 | Neither data provided for account holder update request | | 10\_100 | The document '{0}' has already been uploaded | | 10\_102 | The provided legal entity type {0} is not valid | | 10\_103 | The provided primary currency {0} is not valid | | 10\_104 | Shareholder codes {0} cannot be deleted, as business account {1} must have at least one shareholder. | | 10\_105 | The shareholderCode is missing. This is required for a photo ID upload for shareholders | | 10\_106 | The image uploaded is too small. The minimum accepted image file size : {0} bytes. The size of the file '{1}' is {2} bytes | | 10\_107 | When manually disabling payouts internal and external reasons must be provided | | 10\_108 | Provided document {0} is deemed invalid, it could not be read | | 10\_109 | The document {0} exceeds the maximum allowed number of pages {1} | | 10\_110 | Invalid accountCode: accountCode='{0}'; reason='{1}' | | 10\_111 | Payout schedule cannot be modified, it is blocked at marketplace | | 10\_112 | There is not enough balance available in the marketplace virtual account to perform an express payout. Available balance: {0}; Requested amount: {1} | | 10\_113 | Validation error occurred, see invalidFields property | | 10\_114 | The provided Hmac key is invalid. A 32 bytes key is required | | 10\_115 | Failed to close account: accountCode='{0}'. Non-zero balance remaining. | | 10\_116 | Failed to close accountHolder: accountHolderCode='{0}'. Non-zero balance remaining. | | 10\_117 | Failed to close accountHolder: accountHolderCode='{0}' | | 10\_118 | Not able to find payout method for {0} with payout method code {1} | | 10\_119 | Bank account and payout method cannot both be present in the request | | 10\_120 | idNumber field and documentData field not allowed in the same time on personalData object with different value | | 10\_121 | The provided document type {0} is not supported. | | 10\_122 | Bank statement is not allowed for shareholders. | | 10\_123 | ID document is not allowed for bank accounts. | | 10\_124 | The marketplace is not allowed to use the HOP service | | 10\_125 | There is no valid stores configuration found on the marketplace account | | 10\_126 | There is no return url configured to use the HOP service | | 10\_127 | Store not found, accountHolder: '{0}', storeCode: '{1}' | | 10\_128 | Invalid operation for current store status, accountHolder: '{0}', storeCode: '{1}', status: '{2}' | | 10\_129 | Store does not belong to account '{0}', storeCode: '{1}' | | 10\_130 | Failed to initiate the automated direct debit. | | 10\_131 | HOP cannot be used on SUSPENDED or CLOSED accounts. | | 10\_132 | Payout has been failed for account {0}. Details: Invalid Account Number. | | 10\_133 | Payout has been failed for account {0}. Details: Invalid ACH Routing Number. | | 10\_134 | Payout has been failed for account {0}. Details: No Account/Unable to Locate Account. | | 10\_135 | Payout has been failed for account {0}. Details: Account Closed. | | 10\_136 | The maximum number of chained beneficiaries has been reached | | 10\_137 | Failed to retrieve account holder by legal entity reference '{0}' | | 10\_138 | Payout method with code {0} of account holder {1} already coupled with an account. | | 10\_139 | The marketplace is not allowed to use the PCI Questionnaire | | 10\_140 | Invalid tax form type '{0}' requested. | | 10\_141 | No tax form available for the selected year. | | 10\_142 | Legal arrangement with code='{0}' does not exist | | 10\_143 | Legal arrangement entity with code='{0}' does not exist | | 10\_144 | The document type '{0}' is not allowed for {1} | | 10\_145 | Failed to initiate the direct debit for account holder. | | 10\_146 | Debit Account Holders has not been enabled for this marketplace. | ## Account holder error codes These error codes may be returned when you manage account holders by making `/createAccountHolder` and `/updateAccountHolder` calls. | Error code | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Field is missing | | 2 | Email address is invalid | | 3 | Country code is invalid | | 4 | Value contains illegal characters (numbers) | | 5 | URL is invalid | | 6 | Date is not in a format yyyy-MM-dd | | 7 | Date is not in a valid range (1900 - now) | | 8 | Bank details are invalid | | 9 | Postal code is invalid for the country ç | | 10 | State code is invalid, should be 1-3 characters | | 11 | State code is unknown for the country | | 12 | AccountHolderDetails.fullPhoneNumber and AccountHolderDetails.phoneNumber provided, please provide one or another | | 13 | fullPhoneNumber is not a valid phone number | | 14 | phoneNumber is too short | | 15 | Country is not supported | | 16 | Unknown currency | | 17 | IBAN and accountNumber/branchCode/bankCode are specified, please provide one or another. | | 18 | Can not determine bank code from branch code {0} and account number {1}, please supply bank code. | | 19 | Provided tier number {0} is not valid, value needs to equal or higher then 0 and lower or equal than the maximum available tier. | | 20 | Field should not be filled for country {0}. | | 21 | Account description '{0}' is not valid. | | 22 | This currency and/or country is not supported for payouts. | | 23 | Account holder code does not exists or invalid. | | 24 | Business details field not allowed on individual account. | | 25 | Individual details field not allowed on business or non-profit account. | | 26 | No tier configuration found for account. | | 27 | Account update not allowed. | | 28 | Account holder already exists with the accountHolderCode: {0}. | | 29 | Account code does not exist or invalid. | | 30 | Field should not be filled. | | 31 | Account holder does not exists with the accountHolderCode: {0}. | | 32 | Account holder update not allowed. | | 33 | Account has an invalid status for requested operation, current status: {0}. | | 34 | An invalid {0} code is provided for value '{1}'"), // e.g. An invalid bankAccount code is provided. | | 40 | No document content was provided. | | 41 | The maximum accepted file size : {0} bytes. The size of the file '{1}' is {2} bytes. | | 42 | The image uploaded is too small. The minimum accepted image file size : {0} bytes. The size of the file '{1}' is {2} bytes. | | 43 | File '{0}' can possibly contain malware or a virus. Not accepted. | | 44 | The document '{0}' has already been uploaded. | | 45 | File '{0}' is of invalid format. Accepted formats: pdf, jp(e)g and png. | | 46 | The document {0} exceeds the maximum allowed number of pages {1}. | | 50 | Bank account does not exist for bankAccountCode: {0}. | | 51 | Currency code is invalid. code: {0}. | | 52 | Amount is negative or zero. value: {0}. | | 53 | Source and destination must be different accounts. | | 54 | Not enough balance. | | 55 | Account holder has an invalid status for requested operation, current status: {0}. | | 56 | Account holder {0} has beneficiary setup. Fund transfer is not allowed. | | 57 | Fund transfer/payout is not allowed for account: {0} | | 58 | Outgoing transfer/payout limit reached for account '{0}', limit: '{1}' | | 70 | Shareholder does not exist for shareHolderCode: {0}. | | 71 | Shareholder codes {0} cannot be deleted, as business account {1} must have at least one shareholder. | | 72 | Payout instrument token does not exist for payoutInstrumentTokenCode: {0} | | 73 | Bank account and payout instrument token cannot both be present in the request. | | 74 | P.O. Boxes are not allowed. | | 75 | Bank statement is not allowed for shareholders. | | 76 | ID document is not allowed for bank accounts. | | 77 | Value {0} contains invalid characters. | | 78 | No phone number or email found in the request. Please provide at least one. | | 79 | Invalid POS stores configuration for marketplace. Reason: {0}. | | 80 | The provided {0} tier may not be lower than or equal to the account holder's current Processing tier. | | 81 | The provided {0} tier may not be lower than or equal to the account holder's current Payout tier. | | 82 | Store does not exist for account '{0}', store: '{1}'. | | 83 | Invalid operation for current store status. store: '{0}', with status: '{1}'. | | 84 | Payout method with {0}: '{1}' not verified. | | 85 | No verified payout method could be found for `accountHolderCode`: '{0}'. | | 86 | Stores cannot be created in countries different from the account holder's address country. | | 87 | Invalid `bankAccountDetails` in combination with resulting field value. Reason: {0}. | | 88 | There is no user configured to use the HOP service. | | 89 | There is no return URL found for the request. | | 90 | The max no. of allowed chars in the URL are: {0}. | | 91 | The return URL specified is invalid. | | 92 | The `fullPhoneNumber` must be in the format of a beginning plus (+) followed by the country code and phone number. Only digits and the leading plus are permitted. | | 93 | Error with the `countryCode` | | 94 | Error with the `accountNumber` | | 95 | Error in the `bankAccountName` | | 96 | Error with the `bankCode` | | 97 | Error with the `branchCode` | | 98 | Error with the `checkCode` | | 99 | Error with the `iban` | | 100 | Error with the `bankBicSwift` | | 101 | Error with the `ownerName` | | 102 | Error with the `bankCity` | | 103 | Error with the `ownerCity` | | 104 | Error with the `ownerStreet` | | 105 | Error with the `stateOrProvince` | | 106 | Error with the `ownerPostalCode` | | 107 | Error with the `ownerCountryCode` | | 108 | Error with the `accountType` | | 109 | Error with the `taxId` | | 110 | Bank account already registered for this account holder with bank account UUID. | | 111 | Bank account not found for current currency and UID. | | 112 | Bank account country cannot be different from address country except for EU. | | 113 | To create POS stores in this country, a valid registrationNumber (for businesses) or passport number (for individuals) must be present. | | 117 | "There is no valid configuration for the provided verification profile, legal entity and country. | | 118 | Registration number '{0}' is not a valid for country '{1}' | | 119 | Given value '{0}' contains leading and/or trailing spaces | | 120 | Market Identifier Code '{0}' is not a valid. The MIC is 4-character alphanumeric code. | | 121 | International Securities Identification Number '{0}' is not a valid. The ISIN is 12-character alphanumeric code. | | 122 | Please specify Stock number or Ticker symbol | | 123 | The legal entity type can only be changed when there are no stores with an active or pending status | | 124 | Payout method with payout method code {0} already coupled with an account. | | 125 | Virtual account does not exists with the account code: {0} | | 125 | Account: {0} is not a parent for virtual account: {1} | | 126 | Year is missing | | 127 | Invalid year {0} provided | | 128 | Invalid form type {0} provided | | 129 | The member '{0}' is not allowed for legal arrangement type '{1}' | | 130 | The legal form '{0}' is not allowed for legal arrangement type '{1}' | | 131 | The legal arrangement with code '{0}' does not exists | | 132 | The legal arrangement entity with code '{0}' does not exists for legal arrangement '{1}' | | 133 | Split data is missing | | 134 | The split total does not match the debit amount | | 135 | Instant verification of type {0} is not applicable. | | 136 | Request is not valid, because it contains duplicate signatories. | | 137 | Signatory does not exist for signatoryCode: {0} | | 138 | Principal Address country cannot be different from address country except for EU | | 139 | Operation not allowed on legalEntity: {0} | | 140 | Signatory codes {0} cannot be deleted, as business account {1} does not have all the signatories. | | 141 | Unrecognized stock exchange (MIC) provided | | 142 | Unapproved stock exchange (MIC) has been identified as high risk/inactive | | 143 | Stock field prohibited unless legal entity is of type 'PublicCompany'. | | 144 | Request is not valid because ultimateParentCompanyCode should be given | | 145 | Ultimate Parent Company does not exist for ultimateParentCompanyCode: {0} | | 147 | ID document is not allowed for ultimate parent company. | | 148 | Bank statement is not allowed for ultimate parent company. | | 149 | There is no matching split configuration for the UUID provided: {0} | | 150 | Payout schedule cannot be modified, it is blocked at marketplace | ## See also * [Verification process](/classic-platforms/verification-process) * [Processing payments](/classic-platforms/processing-payments) * [Payouts](/classic-platforms/payouts) * [API Reference](/classic-platforms/api) --- # Source: https://docs.adyen.com/classic-platforms/fund-transfer.md Section: Classic Platforms integration Title: Fund transfer Description: Transfer funds between accounts using Customer Area or the API. --- title: "Fund transfer" description: "Transfer funds between accounts using Customer Area or the API." url: "https://docs.adyen.com/classic-platforms/fund-transfer" source_url: "https://docs.adyen.com/classic-platforms/fund-transfer.md" canonical: "https://docs.adyen.com/classic-platforms/fund-transfer" last_modified: "2020-05-26T12:23:00+02:00" language: "en" --- # Fund transfer Transfer funds between accounts using Customer Area or the API. [View source](/classic-platforms/fund-transfer.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Depending on your use cases, there might be scenarios that require you to move funds between accounts in your platform. Some examples are if you want to send a bonus, or when it is necessary to transfer funds from one account holder's account to another. You can transfer funds between accounts using: * An [API request](#transfer-funds). * Your [Customer Area](#transfer-funds-customer-area). After the funds have been transferred, you can also fully or partially [refund a funds transfer](#refund-the-fund-transfer) using an API request. ## Requirements Before you can transfer funds or refund a fund transfer, you must: 1. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable fund transfers and define your transfer codes. These codes specify the reason for the transfer and must be defined for your platform in compliance with local regulations. 2. Set up [notification webhooks](/classic-platforms/configure-notifications) for event types [TRANSFER\_FUNDS](https://docs.adyen.com/api-explorer/Notification/latest/post/TRANSFER_FUNDS) and [REFUND\_FUNDS\_TRANSFER](https://docs.adyen.com/api-explorer/Notification/latest/post/REFUND_FUNDS_TRANSFER). Fund transfers and refund fund transfers are processed asynchronously, so you must rely on webhooks to know the outcome of your requests. ## Transfer funds through the API You can use the [/transferFunds](https://docs.adyen.com/api-explorer/Fund/latest/post/transferFunds) endpoint to programmatically initiate a fund transfer. In your POST request, specify: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [sourceAccountCode](https://docs.adyen.com/api-explorer/#/Fund/latest/post/transferFunds__reqParam_sourceAccountCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The code of the account from which the funds are to be debited. The status of the account's [account holder](/classic-platforms/verification-process#account-holder-statuses) be **Active** and payouts must be allowed. | | [destinationAccountCode](https://docs.adyen.com/api-explorer/#/Fund/latest/post/transferFunds__reqParam_destinationAccountCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The code of the account to which the funds are to be credited. The status of the account's [account holder](/classic-platforms/verification-process#account-holder-statuses) must be **Active** and processing must be allowed. | | [amount](https://docs.adyen.com/api-explorer/Fund/latest/post/transferFunds#request-amount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `currency` and `value` of the fund transfer. | | [transferCode](https://docs.adyen.com/api-explorer/#/Fund/latest/post/transferFunds__reqParam_transferCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The reason for the transfer, preconfigured on Adyen's side. If you haven't defined this yet, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | [merchantReference](https://docs.adyen.com/api-explorer/Fund/latest/post/transferFunds#request-merchantReference) | | A string that you provide so you can link multiple transactions. | **Transfer funds request** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/transferFunds \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "sourceAccountCode":"100000000", "destinationAccountCode":"190324759", "amount":{ "currency":"EUR", "value":2000 }, "transferCode":"CREDIT_DISCOUNT", "merchantReference":"MyTransferReference-6718A" }' ``` Requests for fund transfers are processed asynchronously so in the response, we only inform you that we received your request. You'll get the result from the [TRANSFER\_FUNDS](https://docs.adyen.com/api-explorer/Notification/latest/post/TRANSFER_FUNDS) webhook. The response returns a `pspReference`. You'll need the `pspReference` in case you have to [refund the funds transfer](#refund-the-fund-transfer). **Response** ```json { "pspReference":"9914828517650017", "resultCode":"Received" } ``` Successful fund transfers are reported with a **FundTransfer** journal entry in your [Marketplace Payment Accounting Report](/reporting/marketpay-payments-accounting-report). ## Transfer funds through Customer Area You can use the Customer Area to manually transfer funds. To do this you must have the **Perform and manage Fund Transfers from the customer area** role for your Customer Area user. If you do not have the role, contact your Admin user. To transfer funds through Customer Area: 1. Log in to your Customer Area and switch to your merchant account. 2. Go to **Platform** > **Sub-merchant**. 3. Select the source account holder, then select the **Accounts** tab. The source account holder must have an active status and have payouts allowed. 4. Select the more actions menu (**) then select **Transfer to another account**. 5. In the **New transfer** page, specify: * The source account. The source account must have a positive balance. * The destination accounts. The account's account holder must have an active status and have processing allowed. * The amount to be transferred. Then select the transfer code from the drop-down list. These codes are configured on Adyen's side. If you haven't defined this yet, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). 6. Select **Transfer** to initiate the fund transfer. You can check the status of the transfer in the **Transactions** tab. You can also get the result from the [TRANSFER\_FUNDS](https://docs.adyen.com/api-explorer/Notification/latest/post/TRANSFER_FUNDS) webhook. Successful fund transfers are reported with a **FundTransfer** journal entry in your [Marketplace Payment Accounting Report](/reporting/marketpay-payments-accounting-report). ## Refund the funds transfer If you need to revert a previous funds transfer, you can refund the transfer for the full amount or a partial amount. You can revert a fund transfer regardless of the [account holder status](/classic-platforms/verification-process#account-holder-statuses). This allows you to reverse a fund transfer from an account even if that account is no longer **Active**. To completely or partially refund a funds transfer, make a POST [/refundFundsTransfer](https://docs.adyen.com/api-explorer/Fund/latest/post/refundFundsTransfer) request, specifying: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | [originalReference](https://docs.adyen.com/api-explorer/Fund/latest/post/refundFundsTransfer#request-originalReference) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `pspReference` that you received in the response to the original funds transfer. | | [amount](https://docs.adyen.com/api-explorer/Fund/latest/post/refundFundsTransfer#request-amount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `currency` and `value` of the funds transfer that you are refunding. This can be the full original amount or part of the original amount. | | [merchantReference](https://docs.adyen.com/api-explorer/Fund/latest/post/refundFundsTransfer#request-merchantReference) | | A string that you provide so you can link multiple transactions. | **Refund funds transfer request** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/refundFundsTransfer \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "originalReference": "9914828517650017", "amount": { "currency": "EUR", "value": 2000 }, "merchantReference": "MyTransferReference-6718A" }' ``` Requests for refunding fund transfers are processed asynchronously so in the response, we only inform you that we received your request. You'll get the result from the [REFUND\_FUNDS\_TRANSFER](https://docs.adyen.com/api-explorer/Notification/latest/post/REFUND_FUNDS_TRANSFER) webhook. **Response** ```json { "pspReference": "8815789044698840", "resultCode": "Received", "merchantReference": "YOUR_MERCHANT_REFERENCE" } ``` Successfully refunded fund transfers are reported with a **FundTransferReversed** journal entry in your [Marketplace Payment Accounting Report](/reporting/marketpay-payments-accounting-report). ## See also * [Reconcile fund transfers](/classic-platforms/reconciliation-use-cases/build-transactional-ledger) * [Notification webhooks](/classic-platforms/notifications) --- # Source: https://docs.adyen.com/classic-platforms/identify-account-holder-risk.md Section: Classic Platforms integration Title: Identify and mitigate account holder risk Description: Spot potential malicious activities from account holders in your platform. --- title: "Identify and mitigate account holder risk" description: "Spot potential malicious activities from account holders in your platform." url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk" source_url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk.md" canonical: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk" last_modified: "2020-12-22T11:33:00+01:00" language: "en" --- # Identify and mitigate account holder risk Spot potential malicious activities from account holders in your platform. [View source](/classic-platforms/identify-account-holder-risk.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Identify fraudulent behavior, stop suspicious payouts, and flag unusual account holder activities with Adyen's Score, a feature that you can now use with your Adyen for Platforms integration. To enable Score for your , contact your Adyen Account Manager. ## How Score works Adyen analyzes the account holder's [verification](/classic-platforms/verification-process) data and their transactions to highlight unusual behavior. These are behaviors that indicate potential malicious and fraudulent activities. We call these indicators [risk signals](#risk-signals). For example, a risk signal can be a high number of transactions made by the same shopper, or the billing address is in a different country/region than their bank account. We use risk signals to: * Detect possible fraud networks. * Calculate an account holder's [risk score](#risk-score), a number representing the degree of unusualness of their activities. The value can range from 0 to 100, with 100 as the highest risk score. Adyen flags the risk signals so that you can investigate unusual behavior. Aside from detecting unusual behavior, Adyen also uses the data to identify linked accounts. Linking accounts can provide insight into returning malicious users, and fraud attacks at scale. We call these linked accounts [identities](#identity-network). By default, Adyen does not disable payouts or processing. You are responsible for [reviewing the cases](/classic-platforms/identify-account-holder-risk/review-and-manage#score-dashboard) and taking action, whether by manually reviewing the account or setting up automated actions on your end. Depending on the outcome of your review, you can take actions such as: * Disable payouts. * Suspend account holders. * Flag risk signals as false positive. * Refund payments. You can find the risk scores for your account holders, review cases, and take action from your [Customer Area](https://ca-test.adyen.com/). You can access this data from: * The **Case management** dashboard. To access the dashboard, go to **Platform** > **Score**. * The **Score** tab in the account holder details. To access this tab, go to **Platform** > **Sub-merchant**, then select an account holder. ## Risk score calculation The risk score represents Adyen's conclusion on the unusualness of the activity of an account holder. The value can range from 0 to 100, where 100 is the highest possible risk score. A risk score of 100 does not mean confirmed malicious or fraudulent behavior. You have to investigate and review the account holder to decide if they display true malicious behavior or if the risk signals indicate a false positive. Risk scores are based on [risk signals](#risk-signals). Each risk signal has a weight that is based on the severity of the impact if the scenario occurs. Because of this, some risk signals contribute more to the risk score. An example of a risk signal that strongly increases the risk score is an account holder using the same bank account as a previously suspended account. You can change the weight of a risk signal or add your own to influence the risk score. ## Identities We analyze the KYC data of all the account holders in your to detect account holders that have the same characteristics. We group these account holders into an *identity*. Risk signals raised for an account holder are automatically applied to the whole identity, giving the same risk score to all account holders in that identity. Take the following scenario for example. 1. Account holder A has bank account ABZ003. Their risk score is 20. 2. Account holder B signs up to your . They also have a bank account ABZ003. 3. Adyen groups the two account holders in Identity\_1. 4. Adyen sets the risk score of account holder B to 100. The whole identity gets a risk score of 100. Because account holder A is part of Identity\_1, their risk score increases to 100. ## Risk signals Risk signals are indicators that we use to spot unusual account holder activity. Besides the default risk signals defined by Adyen, you can also add your own. * **Defined by Adyen** * **KYC data**: Risk signals related to KYC information, such as if the account holder has the same bank account as another account holder. KYC data is updated and evaluated in real time. * **Transaction signals**: Risk signals related to transactions. For example, having an unusual number of refusals where issuers indicated fraud. Transaction signals are updated on a daily basis. * **Defined by you** * **Custom risk signals**: [General KYC values or transaction patterns that you define](/classic-platforms/identify-account-holder-risk/review-and-manage#score-custom-risk). For example, if you think that account holders with a bank account from a specific bank must always flag a risk signal, add the bank in the custom risk list. Custom risk signals are evaluated in real time. * **High risk lists signals**: [More granular KYC values that you define](/classic-platforms/identify-account-holder-risk/review-and-manage#score-action). You can use this to add KYC values from confirmed fraudulent account holders, so you will receive a risk signal if they come back to your . High risk lists signals are evaluated in real time. ## Next steps Find risk scores, review cases, and take action from your Customer Area. [Manage account holder risk](/classic-platforms/identify-account-holder-risk/review-and-manage) [Start using Score in Customer Area.](/classic-platforms/identify-account-holder-risk/review-and-manage) [Configure notifications for risk signals](/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals) [Set up and test webhooks for risk signals.](/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals) --- # Source: https://docs.adyen.com/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals.md Section: Classic Platforms integration Title: Configure notifications for risk signals Description: Learn how to set up and test notifications for risk signals in your platform. --- title: "Configure notifications for risk signals" description: "Learn how to set up and test notifications for risk signals in your platform." url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals" source_url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals.md" canonical: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals" last_modified: "2022-07-27T14:04:00+02:00" language: "en" --- # Configure notifications for risk signals Learn how to set up and test notifications for risk signals in your platform. [View source](/classic-platforms/identify-account-holder-risk/configure-notifications-for-risk-signals.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. When a new risk signal triggers for an account holder, Adyen can send webhooks to your server. If you want to get notified of these events, you can subscribe to the webhook. This works the same way as adding other [webhooks](/classic-platforms/configure-notifications). The event type for risk signals is `SCORE_SIGNAL_TRIGGERED`. You can add a [new notification configuration](#create-a-notification-configuration), or you can [update your existing configuration](#update-notification-configurations). After you have completed your setup, notify us so that we can turn on the webhook notification. ## Create a notification configuration Make a POST [/createNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/createNotificationConfiguration) call, passing the URL where the notifications should be sent, and the notification type. **Create notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "active": false, "eventConfigs":[ { "eventType":"SCORE_SIGNAL_TRIGGERED", "includeMode":"INCLUDE" } ], "notifyURL":"https://www.merchant-domain.com/notification-handler" } }' ``` **Response** ```json { "pspReference": "XB7XNCQ8HXSKGK82", "configurationDetails": { "active": true, "eventConfigs": [ { "eventType": "SCORE_SIGNAL_TRIGGERED", "includeMode": "INCLUDE" } ], "notificationId": 12345, "notifyURL": "https://www.merchant-domain.com/notification-handler", } } ``` ## Update a notification configuration If you have already have an existing notification configuration, you can update your notification setup. Make a POST [/updateNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/updateNotificationConfiguration) call and pass the new setting as its parameters. The notification to be updated is specified by the `notificationId` value. **Update a notification configuration** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/updateNotificationConfiguration \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "active":false, "eventConfigs":[ { "eventType":"ACCOUNT_CREATED", "includeMode":"INCLUDE" }, { "eventType":"SCORE_SIGNAL_TRIGGERED", "includeMode":"INCLUDE" } ], "notificationId":12345, "notifyURL":"https://www.merchant-domain.com/notification-handler" } }' ``` **Response** ```json { "pspReference":"R5CZ2NWPJTGV9D82", "configurationDetails":{ "active":false, "eventConfigs":[ { "eventType":"ACCOUNT_CREATED", "includeMode":"INCLUDE" }, { "eventType":"SCORE_SIGNAL_TRIGGERED", "includeMode":"INCLUDE" } ], "notificationId":12345, "notifyURL":"https://www.merchant-domain.com/notification-handler", } } ``` ## Example notification The following is an example notification body for the `SCORE_SIGNAL_TRIGGERED` event type, triggered by the `EmailSyntaxCheck` risk signal. **Example notification** ```json { "eventDate": "2022-04-05T13:29:15+02:00", "eventType": "SCORE_SIGNAL_TRIGGERED", "executingUserKey": "IdentityRisk", "live": "false", "mimeType": "genericNotification", "pspReference": "JDD6LKT8MBLZNN84", "content": { "accountHolderCode": "YOUR_ACCOUNT_HOLDER_CODE", "riskScore": 80, "scoreSignalsTriggered": [ "EmailSyntaxCheck"] } } ``` --- # Source: https://docs.adyen.com/classic-platforms/identify-account-holder-risk/review-and-manage.md Section: Classic Platforms integration Title: Manage account holder risk Description: Review identities and risk scores of account holders in your platform. --- title: "Manage account holder risk" description: "Review identities and risk scores of account holders in your platform." url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/review-and-manage" source_url: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/review-and-manage.md" canonical: "https://docs.adyen.com/classic-platforms/identify-account-holder-risk/review-and-manage" last_modified: "2020-12-22T11:33:00+01:00" language: "en" --- # Manage account holder risk Review identities and risk scores of account holders in your platform. [View source](/classic-platforms/identify-account-holder-risk/review-and-manage.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. To enable Score for your platform, contact your Adyen Account Manager. When we enable Score for your platform, we also assign the required roles for your Customer Area users. To check if your Customer Area user has the roles, log in to your {[Customer Area](https://ca-live.adyen.com/), then go to **Account** > **Users**. If you need additional roles, contact your admin user. | User role | Access | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Merchant MarketPlace** | The user can view the **Case management** dashboard and **Risk signals** to [review identities](#score-review). | | **Merchant Marketplace Risk** | In addition to the **Merchant MarketPlace** access, the user can [take action](#score-action) on identities. Actions include: disable payouts, suspend account holders, refund transactions, add values to the high risk list, and flag signals as false positives. | | **Merchant Marketplace Risk Admin** | In addition to the **Merchant Marketplace Risk** access, the user can configure the settings page. Settings include: create or edit [custom risk signals](#score-custom-risk), set up [automated actions](#score-automated), or [influence the weight](#score-risk-impact) of risk signals. The user can also trust an identity, [exclude linking identifiers](#score-exclude-kyc) from an identity, and bulk edit the [high risk list](#score-high-risk-bulk) page. | ## Case management dashboard The case management dashboard shows a list of identities and their risk scores, and the number of account holders that are part of an identity. By default, the list is sorted by the highest risk score to help you prioritize which cases to review. To access case management: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **View case management**. The dashboard also has filtering and sorting functions, which you can use to tailor the list of cases shown on the page. For example, you can use filters to only show specific risk signals. Then you can save the view for next time. You can use the dashboard to [review identities](#score-review). If you want to change which identities are displayed, you can [manage score settings](#score-settings). ## Review identities You can review all current signals on the full identity. Go to [case management](#score-dashboard), and then select the **Risk score**. Alternatively, you can go to the **Score** tab on the account holder details page. After reviewing, you can do one of the following: * [Take action on an identity](#score-action). * [Dismiss risk signals as false positives](#score-dismiss). * [Exclude linked KYC values](#score-exclude-kyc) to break up the identity. This action requires the role **Merchant Marketplace Risk Admin**. ### Take action on an identity To take a specific action on an identity, select the **Take action on account** button in the **Score** tab on the account holder details page. You can: * Disable payouts. * Suspend account holders. * Refund transactions. This is only possible after an account is suspended. * Add KYC values to the high risk list. Only add KYC values from confirmed fraudulent account holders. * Trust an identity. You can use this to prevent a known and trusted identity to appear in case management. ### Dismiss risk signals If one or more risk signals triggered, but you do not agree that the signal is a risk for this identity, you can flag the signal as false positive. Flagging a signal as false positive lifts the signal for the whole identity. To dismiss a signal: 1. Select the signal, and from the dropdown menu select **Dismiss risk signal**. This flags this signal as false positive. You can leave feedback in the comment box to help improve future risk signals. To dismiss all signals: 1. Select the **Dismiss all risk signals** button to flag all signals as false positives. When you dismiss all signals for an identity, you mark them all as not relevant for this identity, and reset the risk score. ### Exclude linked KYC values When you know that a KYC value is not a valid link within an identity, you can exclude the identifier. This can be useful, for example, when you know that a telephone number or a registration address is used for several different identities. To exclude an identifier, select the identifier and select **Exclude linked KYC values button**. You will see a list of all the linked identifiers, and the number of times that specific identifier is present. This action cannot be undone and is permanent. You will be asked to confirm this action. ## Manage Score settings (admin only) Apart from taking action on identities, users with the **Merchant Marketplace Risk Admin** role can configure the Score settings. 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. From the **Score settings** page, you can: * Influence the risk score, and [change the impact of a risk signal](#score-risk-impact). * Add [custom risk signals](#score-custom-risk). * Specify [automated actions](#score-automated). From the **High risk list** page, you can: * [Bulk add KYC values](#score-high-risk-bulk) to the high risk list. ### Change the impact of a risk signal Certain scenarios pose a higher risk for your platform than others, and should lead to a higher risk score. You can optimize the risk scores for signals in your platform by editing the weight of each signal. Per signal, you can specify if the impact on the risk score should be: * No impact * Low impact * Medium impact * High impact * Maximum impact ### Add custom risk signals Add your own risk signals based on transactional or KYC values. We recommend that you use the custom risk list for general patterns. For example, accounts that process more than EUR 10,000 in less than two hours after account creation, or accounts with bank accounts from a specific bank that should always flag a risk signal. To create custom transaction signals: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **Settings**. 4. Select **Transaction custom risk signals**. 5. Select **Create transaction custom risk signal** to create a custom rule. 6. Select the scenario and fill in the required parameters. To create custom KYC signals: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **Settings**. 4. Select **Custom KYC risk signals**. 5. Select **Create KYC custom risk signal** to create a custom rule. 6. Select the KYC check category and provide the value that you want to check. ### Add automated actions For high risk lists and custom risk signals, you can let Adyen automatically take a specific action when the check is triggered. To automate the action: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **Settings**. * Select the following: * Whether you want the triggering risk signal to impact the risk score. * The level of impact on the risk score. * The automated action you want to take: **No action**, **Bump KYC tier** or **Disable payouts**. To see which automated actions were taken for which account, look at the **Automated actions** log. 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **Automated actions** > **See automated actions log**. ### Bulk upload KYC values to high risk lists You can use the high risk lists to add KYC values from fraudulent account holders. To add known malicious KYC attributes in bulk, upload a CSV file to the high risk list. To upload a CSV file: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Score**. 3. Select **High risk list**. 4. Select the KYC attribute for which you want to bulk upload values. 5. Select **Add item(s)**. 6. Upload one or more values using the specified CSV format. --- # Source: https://docs.adyen.com/classic-platforms/kyc-action-required-snapshot-report.md Section: Classic Platforms integration Title: KYC action required snapshot report --- title: "KYC action required snapshot report" url: "https://docs.adyen.com/classic-platforms/kyc-action-required-snapshot-report" source_url: "https://docs.adyen.com/classic-platforms/kyc-action-required-snapshot-report.md" canonical: "https://docs.adyen.com/classic-platforms/kyc-action-required-snapshot-report" last_modified: "2019-05-17T15:19:00+02:00" language: "en" --- # KYC action required snapshot report [View source](/classic-platforms/kyc-action-required-snapshot-report.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. The KYC action required snapshot report contains all sub-merchants that have processed a payment or received a fund transfer in the last 3 months and have not yet completed KYC. The report is generated in .csv format on a schedule that is configured from the Customer Area. The schedule for this report is: daily, weekly or monthly. This report can help you to identify if users are having issues with KYC verification. We recommend you use [notifications](/classic-platforms/notifications) to identify these users rather than reports, as they are real time and allow for quicker resolution of issues. **Report name format: **kyc\_snapshot\_report\_YYY-MM-DD.csv \ **Subscription**: Default \ **Frequency**: Daily, weekly or monthly. ## Report structure | # | Column | Description | | -- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Marketplace | Name of the marketplace. | | 2 | Account Holder Code | Unique account holder code defined by the Marketplace upon creation. | | 3 | Account holder Country Code | Account holder country code (address). | | 4 | Creation date (UTC) | Timestamp (UTC) the account holder was created. | | 5 | Entity type | Either Business or Individual. | | 6 | Tier number | Processing tier is calculated based on the amount processed by the account holder. Depending on the tier configuration the tier number is determined. Possible values are: 0, 1, 2 and 3. | | 7 | Account status | Account holder status (active, inactive, suspended, or closed). | | 8 | Next deadline (UTC) | Timestamp (UTC) of the deadline for the account holder to finish the KYC requirements for their tier. | | 9 | Payment instrument code | Unique identifier for the bank account. Note that a account holder can have multiple bank accounts. | | 10 | Shareholder Code | Unique identifier for the shareholder. Note that a account holder can have multiple shareholders. | | 11 | Identity Verification | Status for the Identity Verification check. See [verification process](/classic-platforms/verification-process) for possible KYC status check values. | | 12 | Company Verification | Status for the Company Verification check. See [verification process](/classic-platforms/verification-process)  for possible KYC status check values. | | 13 | Bank Account Verification | Status for the Bank Account Verification check. See [verification process](/classic-platforms/verification-process)  for possible KYC status check values. | | 14 | Document Verification | Status for the Document Verification check. See [verification process](/classic-platforms/verification-process)  for possible KYC status check values. | --- # Source: https://docs.adyen.com/classic-platforms/notification-types.md Section: Classic Platforms integration Title: Notification types Description: Learn about the notification types sent by Adyen for Platforms. --- title: "Notification types" description: "Learn about the notification types sent by Adyen for Platforms." url: "https://docs.adyen.com/classic-platforms/notification-types" source_url: "https://docs.adyen.com/classic-platforms/notification-types.md" canonical: "https://docs.adyen.com/classic-platforms/notification-types" last_modified: "2020-05-07T11:25:00+02:00" language: "en" --- # Notification types Learn about the notification types sent by Adyen for Platforms. [View source](/classic-platforms/notification-types.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. To keep you informed of events on your platform, we send notifications to endpoints that you specify when [configuring notifications](/classic-platforms/configure-notifications). Notification messages include a number of different fields, which vary depending on the event type that triggers this specific notification. Adyen for Platforms sends the following notifications. | Notification | Description | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [ACCOUNT\_CLOSED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_CLOSED) | This notification is triggered when an account is closed. | | [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_CREATED) | This notification is triggered when an account is created. | | [ACCOUNT\_FUNDS\_BELOW\_THRESHOLD](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_FUNDS_BELOW_THRESHOLD) | This notification is triggered when a liable account's current funds are below the threshold configured on the Adyen platform. | | [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_CREATED) | This notification is triggered when an [account holder](/classic-platforms/account-structure) is created, or when an error occurred during account holder creation. | | [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_PAYOUT) | This notification is triggered when a [payout](/classic-platforms/payouts) is initiated. If the payout process has started successfully for a specified account, amount, and bank account, the notification contains `statusCode` = Initiated; in case of any error the notification contains `statusCode` = Failed. | | [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_STATUS_CHANGE) | This notification is triggered when the status of an account holder is changed (for example, when the processing amount exceeds the current tier's limits and proceeds to the next tier). | | [ACCOUNT\_HOLDER\_STORE\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_STORE_STATUS_CHANGE) | This notification is triggered when the status of a store associated with an account holder has changed. | | [ACCOUNT\_HOLDER\_UPCOMING\_DEADLINE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_UPCOMING_DEADLINE) | This notification is triggered when there's an upcoming deadline for an account holder to fulfill the requirements of a specific event. | | [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_UPDATED) | This notification is triggered when an account holder is updated. | | [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) | This notification is triggered when some events occur during account holder verification. For more information, refer to [KYC verification checks](/classic-platforms/verification-process). | | [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_UPDATED) | This notification is triggered when an account is updated. | | [BENEFICIARY\_SETUP](https://docs.adyen.com/api-explorer/#/NotificationService/latest/BENEFICIARY_SETUP) | This notification is triggered when a benefactor and beneficiary relationship between accounts is set up. | | [COMPENSATE\_NEGATIVE\_BALANCE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/COMPENSATE_NEGATIVE_BALANCE) | On the last day of each month Adyen for Platforms checks if there are any accounts with a negative balance that is a month old. When such accounts are found, Adyen for Platforms compensates their balance from the liable platform account and sends the COMPENSATE\_NEGATIVE\_BALANCE notification to the platform. | | [DIRECT\_DEBIT\_INITIATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/DIRECT_DEBIT_INITIATED) | This notification is triggered when an automated direct debit is initiated from the Adyen platform. | | [PAYMENT\_FAILURE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/PAYMENT_FAILURE) | This notification is triggered when a [split payment](/classic-platforms/processing-payments) has failed. | | [REFUND\_FUNDS\_TRANSFER](https://docs.adyen.com/api-explorer/#/NotificationService/latest/REFUND_FUNDS_TRANSFER) | This notification is triggered a [/refundFundsTransfer](https://docs.adyen.com/api-explorer/Fund/latest/post/refundFundsTransfer) request is made. | | [REPORT\_AVAILABLE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/REPORT_AVAILABLE) | This notification is triggered when Adyen generates a platform-specific report. | | [SCHEDULED\_REFUNDS](https://docs.adyen.com/api-explorer/#/NotificationService/latest/SCHEDULED_REFUNDS) | This notification contains scheduled refunds, and is triggered when a [/refundNotPaidOutTransfers](https://docs.adyen.com/api-explorer/Fund/latest/post/refundNotPaidOutTransfers) request is made. | | [TRANSFER\_FUNDS](https://docs.adyen.com/api-explorer/#/NotificationService/latest/TRANSFER_FUNDS) | This notification is triggered when a [/transferFunds](https://docs.adyen.com/api-explorer/Fund/latest/post/transferFunds) request is made. | --- # Source: https://docs.adyen.com/classic-platforms/onboard-users.md Section: Classic Platforms integration Title: Onboard and verify users Description: Move your account holders through the verification process. --- title: "Onboard and verify users" description: "Move your account holders through the verification process." url: "https://docs.adyen.com/classic-platforms/onboard-users" source_url: "https://docs.adyen.com/classic-platforms/onboard-users.md" canonical: "https://docs.adyen.com/classic-platforms/onboard-users" last_modified: "2020-04-08T14:30:00+02:00" language: "en" --- # Onboard and verify users Move your account holders through the verification process. [View source](/classic-platforms/onboard-users.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. As required by payment industry regulations, sub-merchants have to go through a verification process before you can enable payouts for them. These checks are required to help prevent fraudulent activities in your platform. Before you can start the verification process, you must decide on: * When to collect information: all at once for upfront verification, or whenever necessary for staggered verification. * How to collect information: Use Adyen's Hosted Onboarding Page, or build your own onboarding application. After we receive information from you or directly from your account holders, we automatically conduct the required verification checks. ## Upfront verification In the upfront verification approach, the information for all required verification checks is collected and verified right after an account holder is created, eliminating the need to go back to them for more data later in the process. Once the account holder is verified, payouts are allowed regardless of the volume the account holder will process later on, ensuring uninterrupted business. To enable upfront verification for your platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Staggered verification During a staggered verification process, you collect the required information only when needed. This approach enables a faster initial sign-up, as not all account holders have to go through the full verification process. Account holders that process small amounts, for example, individuals, will have an easy onboarding process and can get paid out quickly. However, for account holders that process higher amounts, their business may be interrupted when payouts are temporarily disabled. When they reach the limits of their current processing tier, additional verification checks are required and payouts are disabled. You must contact your account holder to provide the required information. After all data has been verified by Adyen, the account holder will be placed in a higher payout tier and payouts will be enabled again. ### Verification tiers In a staggered verification approach, the verification tiers determine what additional information has to be collected and verified by Adyen to enable or continue payouts for account holders. The tiers and limits are defined based on the account holder's country, legal entity, and processing volume. The tier system consists of two categories: * **Processing tiers** are determined by the amount of funds processed. * **Payout tiers** are determined by the verification checks passed. When an account holder processes a larger volume of funds than what their current processing tier allows, they are moved to higher tier. Reaching a higher processing tier disables payouts and automatically triggers new verification checks. If the information required by the verification checks is missing or incorrect, we send [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) and [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notifications, specifying the data the account holder needs to provide. After we receive all the data and there has been no request to precheck this information, the validation runs automatically. The account holders move to a higher payout tier when the validation is successful. ### Precheck the required information When onboarding your account holders with a staggered verification process, Adyen does not verify their details until they reach a certain processing tier. However, there may be situations where you want to verify your account holder's details before they meet the thresholds. For example, verify an account holder early to prevent a pending verification from temporarily disabling payouts, or verify a high-risk account holder before allowing them to pay out. To precheck the required information, send a POST [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/checkAccountHolder) request and set the `accountStateType` to: * **Payout** if you want to verify account holder details proactively. * **Processing** if you want to force immediate verification. ### Tab: Proactively verify account holder details You can run verification checks before they are required without interrupting processing and payouts by sending a POST [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/checkAccountHolder) request and providing the following information: * `accountHolderCode` of the account holder you want to verify. * `accountStateType` set to **Payout**. * `tier` set to the tier that you want to verify your account holder up to. Reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) if you are unsure which tier you need to set. **Set payout tier to 2** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/checkAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "CODE_OF_ACCOUNT_HOLDER", "accountStateType": "Payout", "tier": 2 }' ``` **Response** ```json { "pspReference": "8836183819713023", "resultCode": "Success" } ``` We will perform verification on the account holder for all checks in the tier number provided. If the checks do not have enough information to verify or if a check fails, the current payout state will not be affected. Your account holder can continue processing payments and being paid out in their current tier. For each verification check performed, we send the following notifications: *  [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) : Contains the result of the verification. *  [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_STATUS_CHANGE): Contains the tier the account holder has been verified against. **Example ACCOUNT\_HOLDER\_STATUS\_CHANGE notification** ```json { "eventDate": "2019-02-13T15:26:32+01:00", "eventType": "ACCOUNT_HOLDER_STATUS_CHANGE", "executingUserKey": "Status Update", "live": false, "pspReference": "8836183819713023", "content": { "accountHolderCode": "AH000001", "oldStatus": {...}, "newStatus": { "status": "Active", "statusReason": "Reason of status", "processingState": { "disabled": false, "processedFrom": { "currency": "USD", "value": 0 }, "processedTo": { "currency": "USD", "value": 0 }, "tierNumber": 0 }, "payoutState": { "allowPayout": true, "disabled": false, "tierNumber": 2 }, "events": [ ] } } } ``` ### Tab: Force immediate verification Verifying an account holder before allowing them to pay out can help protect your platform from high-risk users. You can set the tier you want the account holder to successfully verify before they can pay out. To verify while disabling payouts, make a POST [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/checkAccountHolder) call and provide: * `accountHolderCode` of the account holder you want to verify. * `accountStateType` set to **Processing**. * `tier` set to the tier that you want to verify your account holder up to. Reach out to [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) if you are unsure which tier you need to set. **Set processing tier to 2** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/checkAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "CODE_OF_ACCOUNT_HOLDER", "accountStateType": "Processing", "tier": 2 }' ``` **Response** ```json { "pspReference": "8836183819713023", "resultCode": "Success" } ``` We will perform verification on the account holder for all checks in the tier number provided. This immediately initiates the required checks for that tier, and only allow payouts if the verification is successful. If the checks do not have enough information to verify or if a check fails, payouts are disabled. You then need to collect the appropriate details from your account holder and make another `/checkAccountHolder` call to restart the verification. For each verification check performed, we send the following notifications: *  [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) : Contains the result of the verification. *  [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_STATUS_CHANGE): Contains the tier the account holder has been verified against. **Example ACCOUNT\_HOLDER\_STATUS\_CHANGE notification** ```json { "eventDate" : "2019-02-13T15:25:32+01:00", "eventType" : "ACCOUNT_HOLDER_STATUS_CHANGE", "executingUserKey" : "Status Update", "live" : false, "pspReference" : "8836183819713023", "content" : { "accountHolderCode" : "CODE_OF_ACCOUNT_HOLDER", "oldStatus" : { "status" : "Active", "processingState" : { "disabled" : false, "processedFrom" : { "currency" : "USD", "value" : 50000 }, "tierNumber" : 2 }, "payoutState" : { "allowPayout" : false, "disabled" : false }, "events" : [ { "event" : "InactivateAccount", "executionDate" : "2019-03-15T15:25:16+01:00", "reason" : "Processed more than USD 500.00 or equivalent, deadline triggered" } ] }, "newStatus" : { "status" : "Active", "processingState" : { "disabled" : false, "processedFrom" : { "currency" : "USD", "value" : 50000 }, "tierNumber" : 2 }, "payoutState" : { "allowPayout" : true, "disabled" : false, "tierNumber" : 2 }, "events" : [ ] } } } ``` ## Onboarding options To get the required information and verify your account holders, you can choose from the following onboarding options: * **Hosted Onboarding Page**: Send account holders to an onboarding page where they provide additional information directly to Adyen. This is our recommended solution, because it requires less implementation effort on your side. * **Custom onboarding application**: Collect information from account holders and pass it to Adyen using our API. You are in full control of the user interface and experience. ### Choose an option [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page) [Redirect account holders to an onboarding page.](/classic-platforms/onboard-users/hosted-onboarding-page) [Custom onboarding](/classic-platforms/onboard-users/custom-onboarding) [Build your own onboarding application.](/classic-platforms/onboard-users/custom-onboarding) --- # Source: https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding.md Section: Classic Platforms integration Title: Custom onboarding Description: Onboard your account holders and move them through the verification process. --- title: "Custom onboarding" description: "Onboard your account holders and move them through the verification process." url: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding" source_url: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding.md" canonical: "https://docs.adyen.com/classic-platforms/onboard-users/custom-onboarding" last_modified: "2020-09-08T13:38:00+02:00" language: "en" --- # Custom onboarding Onboard your account holders and move them through the verification process. [View source](/classic-platforms/onboard-users/custom-onboarding.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. We recommend that you use the [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page), because it requires less implementation effort on your side and account holders can send the necessary information directly to Adyen. However, it is also possible to build your own onboarding flow. If you choose to build your own onboarding implementation, you need to set up a way to collect data from your account holder to pass the verification checks required by Adyen. Your onboarding process must follow these main steps: 1. [Create an account holder.](#create-account-holder) 2. [Update the account holder](#update-account-holder) with additional details, depending on the verification check you are trying to pass. 3. [Keep track of the verification results](#get-the-kyc-results) through notification webhooks. 4. [Upload additional documents](#upload-documents) if necessary. ## Requirements 1. Before you start the verification process, you must decide whether to collect all required information once in the beginning, or later in stages as they become necessary. * [Upfront verification](/classic-platforms/onboard-users#upfront-verification) unlocks all payment processing and payouts tiers. It requires you to collect all necessary data at the beginning of the onboarding flow. * [Staggered verification](/classic-platforms/onboard-users#staggered-verification) requires you to collect additional information from the account holder whenever the funds processed exceed their current processing tier. 2. Get the [verification requirements](/classic-platforms/verification-process/required-information) based on the country and legal entity type. ## Step 1: Create an account holder Before you start the verification process, you must [create an account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder), taking note of the `accountHolderCode` in the response. After an account holder is created, they can immediately start processing payments. ## Step 2: Update the account holder When the account holder starts processing a larger volume of funds than what their current processing tier allows, they automatically advance to higher processing tier. This triggers additional verification checks. If you have chosen the upfront verification approach, the verification checks run automatically without any request for additional information from you, unlocking higher payout tiers when necessary. Adyen sends an [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) notification to your server containing the [`status` ](/classic-platforms/verification-process/check-verification-results#verification-statuses)of the verification checks. If you have chosen the [staggered verification method](/classic-platforms/onboard-users#staggered-verification) or if the previously collected data is missing or invalid, payouts will be disabled and Adyen sends an [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_STATUS_CHANGE) notification. You need to ask the account holder for more information at this point. The information that Adyen requires from the account holder depends on their legal entity type. 1. Listen to the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) and [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notifications to learn what information you need to collect from your account holder. 2. Collect the information and provide the data in a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) call. The following example shows how to provide the full address of an existing account holder. **Provide information for verification** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "city": "NY", "country": "US", "postalCode": "12345", "stateOrProvince": "NH", "street": "Teststreet 1", "houseNumberOrName": "100" } } }' ``` The API response may contain any of the following HTTP status codes: * **HTTP 200**: You can use the information that the API returns in the response, such as the `accountCode`, but you should wait for the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification webhook before performing any business logic. The notification webhooks confirm when the resources have been updated in our central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification webhook to confirm if the account holder has been successfully updated. For each verification check that did not pass, the account holder needs to provide information within a [deadline](/classic-platforms/verification-process#inactivation-suspension-deadline). After you send the information to Adyen and the verification is successful, we will re-enable payouts in a higher tier and update the verification check status to **PASSED**. ## Step 3: Get the verification results You receive all the subsequent verification results in [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification webhooks. For more information, refer to [verification results](/classic-platforms/verification-process/check-verification-results). ## Step 4: Upload documents Additional documents, such as a passport, bank statement, or a business registration document, may be required by some countries or regions to verify the account holder's identity, or if the automatic verification of the provided information fails. For example, in the EU, we may require [photo identification](/classic-platforms/verification-process/document-requirements#upload-photo-id) (such as passport) of your account holders. If the account holder's identity cannot be validated, the photo ID verification is used as the ultimate verification. Once you have collected the required document, submit the document to Adyen. To do this, make a POST [/uploadDocument](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument) request with the following: * [documentContent](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument#request-documentContent): The document in base64-encoded string format. * [documentDetail.accountHolderCode](https://docs.adyen.com/api-explorer/Account/6/post/uploadDocument#request-documentDetail-accountHolderCode): The code of the account holder that owns the document. * [documentDetail.documentType](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument#request-documentDetail-documentType): The corresponding type of document. | `documentType` | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | **BANK\_STATEMENT** | Bank statement or other document proving ownership of a specific bank account. | | **COMPANY\_REGISTRATION\_SCREENING** | A company registration document. Supported from v5 and later. | | **CONSTITUTIONAL\_DOCUMENT** | A document containing information about the account holder's legal arrangement. | | **PASSPORT** | The identity page(s) of a passport. | | **DRIVING\_LICENCE\_FRONT** | The front of a driver's licence. When provided, the **DRIVING\_LICENCE\_BACK** is also required. | | **DRIVING\_LICENCE\_BACK** | The back of a driver's licence. When provided, the **DRIVING\_LICENCE\_FRONT** is also required. | | **ID\_CARD\_FRONT** | The front of a government-issued ID card. When this is provided, the **ID\_CARD\_FRONT** is also required. | | **ID\_CARD\_BACK** | The back of a government-issued ID card. When this is provided, the **ID\_CARD\_FRONT** is also required. | The following example shows how to upload a scan of a passport. **Upload a document** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/uploadDocument \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50...VcdCB=", "documentDetail":{ "accountHolderCode":"YOUR_ACCOUNT_HOLDER_CODE", "documentType":"PASSPORT", "filename": "passport.png" } }' ``` **Response** ```json { "invalidFields": [], "pspReference": "8515658815512840", "accountHolderCode": "YOUR_ACCOUNT_HOLDER_CODE", ... "verification": {} } ``` Adyen validates documents asynchronously. On average, it takes Adyen about 30 seconds to validate a photo ID, and two days for registration documents and bank statements. ## See also * [Notifications](/classic-platforms/notifications) * [Verification requirements](/classic-platforms/verification-process/required-information) * [Verification process](/classic-platforms/verification-process) --- # Source: https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page.md Section: Classic Platforms integration Title: Hosted Onboarding Page Description: Simplify your implementation with an Adyen-hosted onboarding page. --- title: "Hosted Onboarding Page" description: "Simplify your implementation with an Adyen-hosted onboarding page." url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page" source_url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page.md" canonical: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page" last_modified: "2021-11-29T09:13:00+01:00" language: "en" --- # Hosted Onboarding Page Simplify your implementation with an Adyen-hosted onboarding page. [View source](/classic-platforms/onboard-users/hosted-onboarding-page.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Send account holders to Adyen's Hosted Onboarding Page (HOP) where they provide additional information directly to Adyen. This is our recommended solution, because it requires less implementation effort on your side. With HOP, you can: * Collect more information. For example, if the verification fails, account holders can use HOP to provide the new information required from them. * Render the page in your account holder's preferred [language](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience#change-page-language). * [Customize the page's appearance](/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance) in your [Customer Area](https://ca-test.adyen.com/). * [Customize the hosted onboarding user experience](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience) through the [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) endpoint. * Receive account updates and verification results through notification webhooks. ### How it works 1. [Create an account holder](#create-account-holder) and present a link or a button to start the verification process. 2. When the account holder selects the link or the button, provide Adyen with the account holder code and [get a one-time HOP URL](#get-hosted-onboarding-page-url). 3. [Handle the redirect](#handle-redirect). After the account holder is successfully redirected to the page, the session starts. The session is valid for 30 minutes. When the account holder provides their information, we send account updates through notification webhooks. The account holder is redirected back to your website after they finish providing their details or when the session expires. 4. [Receive the verification results](#get-the-kyc-results) through notification webhooks. Play the video to see a sample HOP session. [Your browser does not support the video tag.](/user/pages/docs/06.classic-platforms/05.onboard-users/01.hosted-onboarding-page/hop-demo.mov?loading=auto\&decoding=auto\&fetchpriority=auto) ## Requirements 1. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to: * Enable hosted onboarding for your platform. * Provide a default return URL. The default return URL takes the account holder back to your website. 2. Decide whether to collect all required information once in the beginning, or later in stages as they become necessary. * [Upfront verification](/classic-platforms/onboard-users#upfront-verification) unlocks all payment processing and payouts, which means you only need to generate the HOP URL once to collect the necessary data. * [Staggered verification](/classic-platforms/onboard-users#staggered-verification) requires you generate a new onboarding URL to collect additional information from the account holder whenever the funds processed exceed their current processing tier. ## Step 1: Create an account holder Before you start the verification process, you must [create an account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder), taking note of the `accountHolderCode` in the response. After an account holder is created, they can immediately start processing payments. ## Step 2: Get the HOP URL When the account holder selects the link or button, make a POST [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. In your request, you can also include optional parameters such as the URL where the account holder will be redirected back to ( [returnUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-returnUrl)), the [language](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience#change-page-language) the page is rendered in ( [shopperLocale](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-shopperLocale)), and the name of the platform shown in the welcome page ( [platformName](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-platformName)). Here's an example of how you generate a HOP URL for an account holder with `accountHolderCode` **AH0121-TimGreen** with the page rendered in Dutch: **Generate a HOP URL** ```bash curl https://cal-test.adyen.com/cal/services/Hop/v6/getOnboardingUrl \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "{hint:The unique account holder code}accountHolderCode{/hint}": "AH0121-TimGreen", "returnUrl": "https://your.return-url.com/?submerchant=123", "platformName" : "MyShop.com", "shopperLocale": "nl-NL" }' ``` The response contains: * `redirectURL`: The page to where you should redirect your account holder. This URL must be used within 15 seconds and can only be used once. * `pspReference`: The reference for this transaction. We recommend that you store this for troubleshooting purposes. **/getOnboardingUrl response** ```json { "invalidFields": [], "pspReference": "9115677600500127", "resultCode": "Success", "redirectUrl": "https://hop-test.adyen.com/hop/view/?token=" } ``` ## Step 3: Handle the redirect 1. Redirect the account holder to the `redirectURL` within 15 seconds after you received the response. When they are successfully redirected to a hosted onboarding page, the session starts. The session is valid for 30 minutes. The account holder receives an **HTTP 401** status code if: * The redirection did not occur within 15 seconds. * The account holder refreshes or reloads the browser after the session has started. To resume the session, repeat [Step 2](#get-hosted-onboarding-page-url) to get a new URL. 2. Keep track of your account holder's onboarding progress based on the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification webhooks you receive. 3. When the account holder is redirected back to your return URL, inform them of their onboarding progress based on the notification webhooks you received. For example, if the account holder's session expired or they did not finish the onboarding process, repeat [Step 2](#get-hosted-onboarding-page-url) to get a new URL and to resume the process. The information they provide is saved per section, so the next session continues from the remaining, unsaved sections. ## Step 4: Get the verification results You receive all the subsequent verification results in [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification webhooks. For more information, refer to [verification results](/classic-platforms/verification-process/check-verification-results). ## Access HOP on behalf of an account holder After you generate a HOP link for an account holder, you can also access their HOP link. This is useful, for example, if an account holder is having issues updating their data or uploading documents. To be able to view and access the HOP link, you must have the **Manage HOP settings** role enabled for your Customer Area user. If you do not have the role, contact your Admin user. 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. Go to **Platform** > **Sub-merchants** then select the account holder. 3. In the account holder view, you can select the **Hosted onboarding** link shown next to the account holder code. ## See also * [Configure notifications](/classic-platforms/configure-notifications) * [Verification process](/classic-platforms/verification-process) --- # Source: https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience.md Section: Classic Platforms integration Title: Customize the hosted onboarding experience Description: Customize the users' experience on the Hosted Onboarding Page. --- title: "Customize the hosted onboarding experience" description: "Customize the users' experience on the Hosted Onboarding Page." url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience" source_url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience.md" canonical: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience" last_modified: "2022-03-07T15:43:00+01:00" language: "en" --- # Customize the hosted onboarding experience Customize the users' experience on the Hosted Onboarding Page. [View source](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. You can easily customize the hosted onboarding user experience through the [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) endpoint. The request parameters allow you to: * Offer a modular experience by: * [Collecting only specific data points.](#collect-specific-information) * [Controlling which pages are presented on HOP.](#specify-summary-pages) * [Set the default language logic.](#change-page-language) * [Make it possible for users to update their information, even after check have passed.](#change-edit-settings) * [Choose which name to display on the welcome page.](#customize-platform-name) * [Override the default return URL.](#override-default-url) ## Collect information only for specific verification checks The Hosted Onboarding Page collects information for all verification checks that apply to the [legal entity type](/classic-platforms/account-holders-and-accounts#legal-entity-types). To collect information only for specific [verification checks](/classic-platforms/verification-process), specify the `collectInformation` object in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. You can choose to collect information only on the following checks or a combination thereof: * Bank details * Business details * Individual details * PCI questionnaire * Shareholder details ## Specify which summary pages to show to the account holder You can decide whether to show specific pages to the account holder by sending `showPages` object in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. You can show or hide the following pages: * Welcome page * Bank details summary * Business details summary * Individual details summary * Shareholder details summary The welcome page is not shown by default. ## Change the page language By default, an onboarding page is rendered in the language set in the browser settings. If the browser language is not supported, the page is rendered in **en-US**. To change the language: * The account holder can select the language from the drop-down menu at the top or the bottom of the page, depending on the header configuration. * Alternatively, you can send the `shopperLocale` in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. When the account holder opens the page, the page is automatically rendered in the language you specified. If the `shopperLocale` you specified is not supported, the page is rendered in the language set in the browser settings. The following are the supported values for `shopperLocale`: | Language | `shopperlocale` | | ---------------------- | --------------- | | Croatian | **hr-HR** | | Czech | **cs-CZ** | | Danish | **da-DK** | | Dutch | **nl-NL** | | English - US (default) | **en-US** | | Finnish | **fi-FI** | | French | **fr-FR** | | German | **de-DE** | | Hungarian | **hu-HU** | | Italian | **it-IT** | | Norwegian | **no-NO** | | Polish | **pl-PL** | | Portuguese | **pt-BR** | | Romanian | **ro-RO** | | Slovakia | **sk-SK** | | Slovenian | **sl-SI** | | Spanish | **es-ES** | | Swedish | **sv-SE** | ## Change editing settings The main purpose of HOP is to be a one-time onboarding tool, which means that, by default, account holders cannot edit data on HOP that has already been verified.\ However, there may be special circumstances that require information to be updated even after verification checks have passed.\ To change the default behavior and allow editing data, send the `editMode` parameter in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. ## Customize platform name The name of your platform is shown on the welcome page.\ To change the name, you must send the `platformName` in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request. ## Override the default return URL After the account holders complete the onboarding or their session times out, they are redirected back to the default return URL configured in your platform account. To change this URL, send the `returnURL` object in your [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request.\ The maximum length of the URL is 500 characters. --- # Source: https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance.md Section: Classic Platforms integration Title: Customize HOP appearance Description: Customize your Hosted Onboarding Page to fit the look and feel of your own website. --- title: "Customize HOP appearance" description: "Customize your Hosted Onboarding Page to fit the look and feel of your own website." url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance" source_url: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance.md" canonical: "https://docs.adyen.com/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Customize HOP appearance Customize your Hosted Onboarding Page to fit the look and feel of your own website. [View source](/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. You can customize your Hosted Onboarding Page (HOP) to fit the onboarding style of your platform.\ In [Customer Area](https://ca-test.adyen.com/), you can configure how the page is displayed, including: * [Enabling the header.](#customize-HOP-appearance) * [Adding a logo.](#add-name-logo) * [Adding a background image or change its color.](#change-background) * [Adding an FAQ URL that links back to your platform.](#add-faq-url) You can further [customize the onboarding experience](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience), like making the flow more modular, through a set of parameters in [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl). ## Enable the page header You can decide whether to use a navigation header on your HOP, which also changes the position of the logo if you have added one. To change the header settings, you must have the **Manage HOP settings** role enabled for your Customer Area user. If you do not have the role, contact your Admin user. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select **Platform** > **Configure** > **Hosted Onboarding**. 2. Select one of the following options: * **With default header**: The logo appears in the top-left corner, and the language selection and the **Help** button appears in the header of the page. * **Without header**: The logo appears at the top center, and the language selection and the **Help** button appears at the bottom of the page. ## Add your logo You can add a customized logo shown to your HOP. To add or change the logo, you must have the **Manage HOP settings** role enabled for your Customer Area user. If you do not have the role, contact your Admin user. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select **Platform** > **Configure** > **Hosted Onboarding**. 2. Upload a logo for your onboarding page with the following image requirements: * Maximum size: 400 x 128 pixels * File types: JPG, JPEG, PNG, SVG * Maximum file size: 100KB ## Change the background You can change the background color or upload an image to use as background of your HOP. To change the page background, you must have the **Manage HOP settings** role enabled for your Customer Area user. If you do not have the role, contact your Admin user. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select **Platform** > **Configure** > **Hosted Onboarding**. 2. To use an image as the background, select the **Background image** option and upload an image with the following requirements: * File types: JPEG, PNG, SVG * Maximum file size: 5MB 3. To change the background color, select the **Background color** option, then enter the hexadecimal code of the chosen color (#RRGGBB format). ## Add an FAQ URL You can include a link to your Frequently Asked Questions page. It will appear when account holders select the **Help** button, below Adyen's FAQ. To add the address of your FAQ page to HOP, you must have the **Manage HOP settings** role enabled for your Customer Area user. If you do not have the role, contact your Admin user. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select **Platform** > **Configure** > **Hosted Onboarding**. 2. Enter the URL in the **Additional URL for FAQs** field. --- # Source: https://docs.adyen.com/classic-platforms/payouts.md Section: Classic Platforms integration Title: Payouts Description: Learn how to make scheduled or manual payouts to account holders. --- title: "Payouts" description: "Learn how to make scheduled or manual payouts to account holders." url: "https://docs.adyen.com/classic-platforms/payouts" source_url: "https://docs.adyen.com/classic-platforms/payouts.md" canonical: "https://docs.adyen.com/classic-platforms/payouts" last_modified: "2023-02-01T14:50:00+01:00" language: "en" --- # Payouts Learn how to make scheduled or manual payouts to account holders. [View source](/classic-platforms/payouts.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Adyen gives you the ability to control the payout timing and amounts for account holders. After an account holder starts receiving funds to their account, these funds can be paid out according to the current payout tier of the account holder. For more information on tiers and verification checks required for payouts, refer to [Onboard and verify users](/classic-platforms/onboard-users). An account with a positive balance can be paid out manually via API or automatically, according to a specific payout schedule. To ensure optimized payout timing, we recommend using scheduled payouts. * [Scheduled payouts](/classic-platforms/payouts/scheduled-payout) are set with a specific cadence for each individual account. The full balance available at that time is paid out. Scheduled payouts can only be made to bank accounts. * [Manual payouts](/classic-platforms/payouts/manual-payout) can be triggered anytime to bank accounts or [eligible cards](/classic-platforms/payouts/manual-payout/payout-to-cards). It is possible to pay out partial balances, therefore you must include the amount to be paid out in the request. By default, both payout methods depend on the standard payout processing of the region, for example, [Bankers' Automated Clearing Services (BACS)](https://www.bacs.co.uk/pages/home.aspx) in the UK and [Automated Clearing House (ACH) network](https://www.nacha.org/content/ach-network) in the US.\ To speed up this process, Adyen offers the premium option to trigger **faster** [scheduled](/classic-platforms/payouts/scheduled-payout#faster-scheduled-payout) or [manual](/classic-platforms/payouts/manual-payout#faster-manual-payout) payouts. ## Limitations The country of the payout method must be the same as the country of the account holder. For example, if the account holder is onboarded in the US, the bank account also needs to be located in the US. In Europe, Adyen allows for more flexibility: if an account holder is onboarded in one European country, they can add a bank account in a different European country. The maximum number of bank accounts for an account holder is 200. ## Supported currencies Adyen only supports payouts in the local currencies. For example, USD is supported in the United States and AUD in Australia. There two exceptions: * EUR payouts in countries that are part of the [Single Euro Payments Area (SEPA)](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en) but not the eurozone. * USD payouts in Canada. See the overview below of supported currencies per country. | Country | Currency | | -------------- | -------- | | Australia | AUD | | Austria | EUR | | Belgium | EUR | | Bulgaria | BGN, EUR | | Canada | CAD, USD | | Croatia | EUR | | Cyprus | EUR | | Czech Republic | CZK, EUR | | Denmark | DKK, EUR | | Estonia | EUR | | Finland | EUR | | France | EUR | | Germany | EUR | | Hong Kong | HKD | | Hungary | HUF, EUR | | Ireland | EUR | | Italy | EUR | | Latvia | EUR | | Liechtenstein | CHF, EUR | | Lithuania | EUR | | Luxembourg | EUR | | Malta | EUR | | Netherlands | EUR | | Norway | NOK, EUR | | Poland | PLN, EUR | | Portugal | EUR | | Romania | RON, EUR | | Singapore | SGD | | Slovakia | EUR | | Spain | EUR | | Sweden | SEK, EUR | | Switzerland | CHF, EUR | | United Kingdom | GBP | ## See also * [Verification process](/classic-platforms/verification-process) * [Error codes](/classic-platforms/error-codes) * [Notifications](/classic-platforms/notifications) --- # Source: https://docs.adyen.com/classic-platforms/payouts/manual-payout.md Section: Classic Platforms integration Title: Manual payouts Description: Learn how to initiate one-off payouts to cards or bank accounts. --- title: "Manual payouts" description: "Learn how to initiate one-off payouts to cards or bank accounts." url: "https://docs.adyen.com/classic-platforms/payouts/manual-payout" source_url: "https://docs.adyen.com/classic-platforms/payouts/manual-payout.md" canonical: "https://docs.adyen.com/classic-platforms/payouts/manual-payout" last_modified: "2020-03-20T12:39:00+01:00" language: "en" --- # Manual payouts Learn how to initiate one-off payouts to cards or bank accounts. [View source](/classic-platforms/payouts/manual-payout.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Manual payouts give you the flexibility to trigger a payout off-schedule, and to pay out partial balances. You can manually pay out the positive balance on an account, less any negative pending balance, by making an API request or through your Customer Area. When triggering a manual payout, you must consider the cutoff times for each bank transfer method in each region. Cutoff times affect the expected time for the account holders to receive the funds in their bank account. ## Pay out manually You can issue payouts using your Customer Area or the Fund API. ### Tab: Customer Area You can issue payouts to bank accounts in your Customer Area. To do this, your Customer Area user must have the **Instruct payouts to bank accounts for all account holders from the customer area** role. If you do not have the role, contact your Admin user. To issue payouts from the Customer Area: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and switch to the merchant account. 2. Go to **Platform** > **Sub-merchants**. 3. Select the account holder you want to pay out to, then select the **Accounts** tab. 4. Select the more actions menu (**), then select **Payout to bank**. If it appears dimmed, the account does not have a positive balance. 5. In the **New payout** page, specify: * The account from which you want to pay out. The account must have a positive balance. * The bank account to which you want to pay out. * The amount to be paid out. * Optionally, you can add a description to the payout, which will appear on the account holder's bank statement. You can also specify the merchant reference, which you can use to reconcile payouts in reports. 6. Select **Payout** to initiate the payout. You can check the status of the payout in the **Transactions** tab. ### Tab: Fund API To manually trigger payouts to your account holder's bank account or to a [card eligible for payouts](/classic-platforms/payouts/manual-payout/payout-to-cards), make a  [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request. **Initiate manual payout to a bank account** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/payoutAccountHolder \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "accountCode":"118731451", "amount":{ "currency":"EUR", "value":99792 }, "accountHolderCode":"TestAccountHolder877209", "description":"12345 – Test", "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c" }' ``` **Response** ```json { "invalidFields": [], "pspReference":"9914719437810080", "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c" } ``` **Response in case of a validation error** ```json { "invalidFields": [ { "errorCode": 29, "errorDescription": "Account code does not exist or invalid", "fieldType": { "field": "accountCode", "fieldName": "accountCode" } } ], "pspReference": "8515659454939302", "resultCode": "Failed" } ``` Wait for the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification to confirm the status of the payout. You can also [track your payouts](/classic-platforms/payouts/track-payouts) in your Customer Area. To learn about payout status codes, see [Payout notifications](/classic-platforms/payouts/payout-notifications). ## Set the payout speed By default, all payouts are scheduled according to the standard payout processing of the region, for example, [Bankers' Automated Clearing Services (BACS)](https://www.bacs.co.uk/pages/home.aspx) in the UK and [Automated Clearing House (ACH) network](https://www.nacha.org/content/ach-network) in the US. To speed up this process, Adyen offers the option to set a faster payout schedule, where the payouts are available to the account holder the same day if processed before the bank cutoff time. These payouts are processed via express methods such as NPP, FPS, and Same Day ACH are restricted to the countries/regions in which they are available. This functionality is supported in the following countries/regions: * Australia * United Kingdom * United States To enable faster payouts for the whole platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). To enable the faster payout option for specific payouts, send the POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request with `payoutSpeed` **SAME\_DAY**. **Set faster manual payouts** ```json { "accountCode":"131863447", "amount":{ "currency":"GBP", "value":100 }, "accountHolderCode":"CODE_OF_ACCOUNT_HOLDER", "merchantReference":"10000000", "description":"FasterPayoutsTest", "payoutSpeed":"SAME_DAY", "bankAccountUUID": "d23a2144-4e0a-4f64-b9b3-d8c92a83f42e" } ``` ## Change the payout descriptor To change the payout descriptor, send the POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request with the `description` parameter.\ The value must be between 1 to 35 characters and must only contain the following supported characters: * Characters between **a-z**, **A-Z**, and **0-9** * Special characters: **/?:().,'+ ";** ## See also * [Scheduled payouts](/classic-platforms/payouts/scheduled-payout) * [Verification process](/classic-platforms/verification-process) * [Pay out to cards](/classic-platforms/payouts/manual-payout/payout-to-cards) * [Payout notifications](/classic-platforms/payouts/payout-notifications) --- # Source: https://docs.adyen.com/classic-platforms/payouts/manual-payout/payout-to-cards.md Section: Classic Platforms integration Title: Payouts to cards Description: Learn how to save your account holder's card details and make a payout. --- title: "Payouts to cards" description: "Learn how to save your account holder's card details and make a payout." url: "https://docs.adyen.com/classic-platforms/payouts/manual-payout/payout-to-cards" source_url: "https://docs.adyen.com/classic-platforms/payouts/manual-payout/payout-to-cards.md" canonical: "https://docs.adyen.com/classic-platforms/payouts/manual-payout/payout-to-cards" last_modified: "2021-02-18T15:12:00+01:00" language: "en" --- # Payouts to cards Learn how to save your account holder's card details and make a payout. [View source](/classic-platforms/payouts/manual-payout/payout-to-cards.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Aside from paying out to bank accounts, you also have the option to send payouts to eligible Mastercard and Visa debit cards. This feature is available in [Fund API](https://docs.adyen.com/api-explorer/#/Fund/v6/overview) version 5 and later. When paying out to cards, the funds arrive to the cardholder within 30 minutes and there is no dependency on bank cutoffs. ## Requirements Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable card payouts for your platform. ## Step 1: Check if the card is eligible for payouts and save the card details 1. Submit a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request with your account holder's card details and the following parameters: * [merchantAccount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-merchantAccount): Your merchant account. * [shopperReference](https://docs.adyen.com/api-explorer/Payment/latest/post/authorise#request-shopperReference): Your unique account holder reference (minimum length three characters). * [enablePayOut](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-enablePayOut): Indicates if the card details should be stored for payouts. Set this to **true**. * [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod): Object containing your account holder's card details. You can only pass raw card data if you are [fully PCI compliant](/get-started-with-adyen/adyen-glossary/#pci-compliance). Otherwise, use our [Card Component](/payment-methods/cards/custom-card-integration) to securely collect and encrypt your account holder's card details. **Submit a zero-value payment request** ```json { "{hint:Your account holder's card details}paymentMethod{/hint}": { "type": "scheme", "number": "4111111111111111", "expiryMonth": "3", "expiryYear": "2030", "cvc": "737", "holderName": "John Smith" }, "amount": { "value": 0, "currency": "EUR" }, "{hint:Your unique reference for this account holder, minimum length 3}shopperReference{/hint}": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j", "enablePayOut": true, "reference": "YOUR_TRANSACTION_REFERENCE", "{hint:Your merchant account}merchantAccount{/hint}": "YOUR_MERCHANT_ACCOUNT" } ``` **Response** ```json { "additionalData": { "{hint: Use this when creating a payout method in step 2}recurring.recurringDetailReference{/hint}": "8315659584588245", "recurring.shopperReference": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j", "merchantReference": "YOUR_TRANSACTION_REFERENCE", "{hint: If value is I, this means that the card is eligible for instant payouts}fundsAvailability{/hint}": "I", "{hint: Indicates if this card is eligible for payouts}payoutEligible{/hint}": "Y" }, "pspReference": "881566214605773J", "resultCode": "Authorised" } ``` If you are using the [classic integration](/online-payments/classic-integrations/classic-api-integration#authorise-request), include [recurring.contract](https://docs.adyen.com/api-explorer/Payment/latest/post/authorise#request-recurring-contract) **PAYOUT** in your request. 2. Check the [payoutEligible](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-additionalData-ResponseAdditionalDataCommon-payoutEligible) parameter in the response. The value should be either: * **Y**: Eligible for payout. For Mastercard, this means that the card is eligible for both domestic and cross-border payouts. * **D**: Applies only to Mastercard. Card is eligible only for domestic payouts. If you receive an **N** or **U**, the card cannot be used for payouts. 3. If the card is eligible for payouts, get the `recurring.recurringDetailReference` from the response. This is your account holder's tokenized card details. You will need this value when adding the new payout method and for submitting future payout requests. ## Step 2: Add card as a payout method 1. Submit a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request with the following parameters: * [shopperReference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperReference): Your unique account holder reference. The minimum length is three characters. * [recurringDetailReference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-additionalData-ResponseAdditionalDataCommon-recurring-recurringDetailReference): This is the `recurring.recurringDetailReference` returned in the response in [Step 1](#check-and-store). **Update account holder request** ```json { "accountHolderCode" : "4a55294d-7841-484d", "accountHolderDetails" : { "payoutMethods" : [ { "merchantAccount" : "YOUR_MERCHANT_ACCOUNT", "recurringDetailReference" : "8315659584588245", "shopperReference" : "YOUR_UNIQUE_SELLER_ID_IOfW3k9G2PvXFu2j" } ], ... } } ``` **Response** ```json { "invalidFields" : [], "pspReference" : "9915402175055353", "accountHolderCode" : "4a55294d-7841-484d", "accountHolderDetails" : { ... "payoutMethods" : [ { "merchantAccount" : "YOUR_MERCHANT_ACCOUNT", "payoutMethodCode": "4a55294d-7841-484d-be06-2e6e9cac824f", "recurringDetailReference" : "9915402174902084", "shopperReference" : "YOUR_UNIQUE_SELLER_ID_IOfW3k9G2PvXFu2j" } ], ... } } ``` You receive a response that might contain any of the following status codes: * **HTTP 200**: You can use the information returned in API response, such as the `payoutMethodCode`, but wait for the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification before performing any business logic. The notification confirms when the new payout method has been added in our central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification to confirm if the new payout method has been successfully added. Get the corresponding `payoutMethodCode` from the notification. ## Step 3: Submit a card payout 1. Submit a POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) using the `payoutMethodCode` returned in the response or notification in [Step 2](#add-card-payout). **Submit a payout to the card** ```json { "accountCode" : "9915402177165382", "accountHolderCode" : "4a55294d-7841-484d", "amount" : { "currency" : "USD", "value" : 1000 }, "description" : "YOUR_DESCRIPTION", "merchantReference" : "YOUR_PAYOUT_REFERENCE", "payoutMethodCode" : "4a55294d-7841-484d-be06-2e6e9cac824f" } ``` **Response** ```json { "invalidFields" : [], "merchantReference": "YOUR_PAYOUT_REFERENCE", "pspReference" : "9915402175055353", "resultCode": "Received" } ``` 2. Wait for the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification to confirm the status of the payout.\ For more information, see [Payout notifications](/classic-platforms/payouts/payout-notifications). ## See also * [Scheduled payouts](/classic-platforms/payouts/scheduled-payout) * [Manual payouts](/classic-platforms/payouts/manual-payout) * [Verification process](/classic-platforms/verification-process) * [Payout notifications](/classic-platforms/payouts/payout-notifications) --- # Source: https://docs.adyen.com/classic-platforms/payouts/payout-notifications.md Section: Classic Platforms integration Title: Payout notifications --- title: "Payout notifications" url: "https://docs.adyen.com/classic-platforms/payouts/payout-notifications" source_url: "https://docs.adyen.com/classic-platforms/payouts/payout-notifications.md" canonical: "https://docs.adyen.com/classic-platforms/payouts/payout-notifications" last_modified: "2022-11-24T14:49:00+01:00" language: "en" --- # Payout notifications [View source](/classic-platforms/payouts/payout-notifications.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. After a payout is initiated, Adyen sends an [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification for each status update of the payout. The notification may contain any of the following `status.statusCode`: * [**Initiated**](#payout-initiated) * [**Confirmed**](#payout-confirmed) * [**Failed**](#payout-failed) ## Payout initiated Receiving the notification with `status.statusCode` **Initiated** means that the payout has been scheduled to be sent to the account holder's bank. In this case, you can inform your account holder to expect the funds at the indicated `estimatedArrivalDate`. ## Payout confirmed *Available in [Notification v5 or later](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT#request-content-status-statusCode).* Receiving the notification with `status.statusCode` **Confirmed** means that the funds have left Adyen and are on their way to the account holder's bank. You can inform your account holder to expect the funds within a few business days. From the **Confirmed** notification you can gather the following details: * `payoutReference`: The unique payout id. * `payoutAccountNumber`: The account number of the bank from which the payout is initiated. * `payoutBranchCode`: The branch code of the bank from which the payout is initiated. * `payoutAccountCountry`: The country code of the bank from which the payout is initiated. * `payoutBankName`: The name of the bank the payout is made from.\ These details can help your account holder find the payout. After receiving a **Confirmed** notification, it is still possible that the payout is returned to Adyen by the receiving bank. ## Payout failed Receiving the notification with `status.statusCode` **Failed** means that the payout failed due to one of the following reasons: * **10\_132**: Invalid Account Number. * **10\_133**: Invalid ACH Routing Number. * **10\_134**: No Account/Unable to Locate Account. * **10\_135**: Account Closed. * **10\_069**: Funds have been returned to Adyen. * Validation error. For example, payouts are not enabled for the account holder or you pay out a higher amount than the available payable balance. You receive an `invalidFields` array in the notification. Make sure to update the account holder's bank account details by making a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/4/post/updateAccountHolder) request. For detailed information on error codes and messages, refer to [General error codes](/classic-platforms/error-codes). A failed payout will have a new `pspReference`, different from the initial payout. If you set up [scheduled payouts](/classic-platforms/payouts/scheduled-payout) and the payout was returned, the account holder's payout state will be automatically disabled. Update their bank account details by making a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/4/post/updateAccountHolder) request and enable the payout state by making a POST [/updateAccountHolderState](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolderState) request. You can link the returned payout to the initial payout using the [MarketPay payments accounting report](/reporting/marketpay-payments-accounting-report). --- # Source: https://docs.adyen.com/classic-platforms/payouts/scheduled-payout.md Section: Classic Platforms integration Title: Scheduled payouts to bank accounts Description: Learn how to schedule payouts to account holders. --- title: "Scheduled payouts to bank accounts" description: "Learn how to schedule payouts to account holders." url: "https://docs.adyen.com/classic-platforms/payouts/scheduled-payout" source_url: "https://docs.adyen.com/classic-platforms/payouts/scheduled-payout.md" canonical: "https://docs.adyen.com/classic-platforms/payouts/scheduled-payout" last_modified: "2020-03-20T12:39:00+01:00" language: "en" --- # Scheduled payouts to bank accounts Learn how to schedule payouts to account holders. [View source](/classic-platforms/payouts/scheduled-payout.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. With scheduled payouts, you do not have to handle the complexity around how much to pay out or when, since all available funds in the account are paid out to the account holder. ## Default payout schedule The default payout schedule for your platform is **DAILY**. This means that your platform is configured to automatically send payouts every day to all account holders with a positive balance. If you want to change the default payout schedule for the whole platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). []() In [newer classic integrations](/classic-platforms/release-notes#releaseNote=2022-05-17-general), by default, the timing for daily payouts is optimized for local timezones based on the account holder's country code. The following schedules apply. | Country | Optimized payout timing | | ------------------------- | ----------------------- | | Australia and New Zealand | 19:50:00 CET | | Canada and United States | 12:50:00 CET | | Singapore | 09:50:00 CET | | Other countries | 05:50:00 CET | For existing integrations, you can contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable the same feature. If not enabled, daily payouts are scheduled at 00:00 CET. ## Override the default payout schedule To override your platform's [default payout schedule](#default-schedule) and set a schedule for a specific account, make a POST [/updateAccount](https://docs.adyen.com/api-explorer/#/Account/latest/updateAccount) call and pass a new `schedule` in the `payoutSchedule` object. Possible `schedule` values are: | Schedule | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DAILY** | Every day at midnight (00:00:00 CET). Otherwise if using the feature for [optimized timing](#optimized-timing), the schedule depends on the account holder's country code. | | **DAILY\_US** | Every day, optimized for US (12:50:00 CET). | | **DAILY\_EU** | Every day, optimized for EU/UK (05:50:00 CET). | | **DAILY\_AU** | Every day, optimized for AU (19:50:00 CET). | | **DAILY\_SG** | Every day, optimized for SG (09:50:00 CET). | | **WEEKLY** | Once a week on Monday at midnight (00:00:00 CET). | | **WEEKLY\_ON\_TUE\_FRI\_MIDNIGHT** | Weekly every Tuesday and Friday at midnight (00:00:00 CET). | | **BIWEEKLY\_ON\_1ST\_AND\_15TH\_AT\_MIDNIGHT** | Monthly on the 1st and 15th at midnight (00:00:00 CET). | | **MONTHLY** | First day of every month at midnight (00:00:00 CET). | | **HOLD** | No scheduled payout by Adyen. In this case, you need to provide a `reason` for putting the payouts on hold. All payouts to this account holder have to be now [triggered manually](/classic-platforms/payouts/manual-payout). | **Update payout schedule request** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccount \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "accountCode": "198360329", "payoutSchedule": { "{hint:Optional. How to handle previously scheduled payouts.}action{/hint}": "CLOSE", "{hint:Required when the schedule parameter is set to HOLD.}reason{/hint}": "Update the payout schedule", "schedule": "WEEKLY" } }' ``` **Response** ```json { "invalidFields": [], "pspReference": "8515659450108985", "accountCode": "8516026831348764", "payoutSchedule": { "schedule": "WEEKLY" } } ``` You receive a response that may contain any of the following status codes: * **HTTP 200**: You can use the information returned in API response but wait for the [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_UPDATED) notification to confirm when the resource has been updated in our central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_UPDATED) notification to confirm if the payout schedule has been successfully updated. ## Set the payout speed By default, all payouts are scheduled according to the standard payout processing of the region, for example, [Bankers' Automated Clearing Services (BACS)](https://www.bacs.co.uk/pages/home.aspx) in the UK and [Automated Clearing House (ACH) network](https://www.nacha.org/content/ach-network) in the US. To speed up this process, Adyen offers the option to set a faster payout schedule, where the payouts are available to the account holder the same day if processed before the bank cutoff time. These payouts are processed via express methods such as NPP, FPS, and Same Day ACH are restricted to the countries/regions in which they are available. This functionality is supported in the following countries/regions: * Australia * United Kingdom * United States To enable faster payouts for the whole platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). To enable the faster payout option for specific accounts, send the POST [/updateAccount](https://docs.adyen.com/api-explorer/#/Account/latest/updateAccount) request with `payoutSpeed` **SAME\_DAY**. **Set the payout speed** ```json { "accountCode": "8516026831348764", "payoutSpeed": "SAME_DAY", "payoutSchedule": { "schedule": "DAILY", "action": "UPDATE" } } ``` You receive a response that may contain any of the following status codes: * **HTTP 200**: You can use the information returned in API response, but wait for the [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_UPDATED) notification to confirm when the resource has been updated in Adyen's central database. * **HTTP 202**: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_UPDATED) notification to confirm whether the payout schedule has been successfully updated. ## Payout descriptors Payouts carry the default descriptor of your platform's name on the account holder's bank statement. To change the descriptor, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). We can configure the descriptor to dynamically use the values of the following fields: * `accountCode` * `accountHolderCode` * `accountDescription` * `accountHolderDescription` * `pspReference`, the PSP reference of the payout. You can use this reference to link a payout to the corresponding report. The value must be between 1 to 35 characters and must only contain the following supported characters: * Characters between **a-z**, **A-Z**, and **0-9** * Special characters: **/?:().,'+ ";** ## See also * [Manual payouts](/classic-platforms/payouts/manual-payout) * [Verification process](/classic-platforms/verification-process) * [Pay out to cards](/classic-platforms/payouts/manual-payout/payout-to-cards) * [Payout notifications](/classic-platforms/payouts/payout-notifications) --- # Source: https://docs.adyen.com/classic-platforms/payouts/track-payouts.md Section: Classic Platforms integration Title: Tracking payouts Description: Find out what you can do to check payouts. --- title: "Tracking payouts" description: "Find out what you can do to check payouts." url: "https://docs.adyen.com/classic-platforms/payouts/track-payouts" source_url: "https://docs.adyen.com/classic-platforms/payouts/track-payouts.md" canonical: "https://docs.adyen.com/classic-platforms/payouts/track-payouts" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Tracking payouts Find out what you can do to check payouts. [View source](/classic-platforms/payouts/track-payouts.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. In general, a regular speed payout can take up to 1-2 business days to confirm if it is successful or if it failed. If the payout is successful, it can take another 3 business days for the funds to reach the receiving bank. If you are unsure of the status of a payout, you can further investigate by tracking its progress through notifications or in your [Customer Area](https://ca-test.adyen.com/). ## Check if payout was initiated ### Notifications Once the payout is initiated, you will receive an [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification with `statusCode` **Initiated**. From notification version 5, you can also collect the estimated payout date through the `content.estimatedArrivalDate` parameter, and send it to your account holder. ### Customer Area 1. Log in to [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Select the sub-merchant. 4. Select the **Transactions** tab. 5. Filter to **Type** > **Payout**. 6. Expand the payout. If the payout has been initiated, it is reflected as such under **History**. ## Check if payout was confirmed ### Notifications Once the payout is debited from your platform account, you receive another [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification with `statusCode` **Confirmed**. In this notification you also receive the unique payout reference and the details of the bank account from which the payout was initiated. You can send this information to your account holder as a confirmation and to help with troubleshooting if needed. You can also [download the payout letter confirmation](/classic-platforms/payouts/track-payouts#download-payout-letter) and share this with the account holder. ### Customer Area 1. Log in to [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Select the sub-merchant. 4. Select the **Transactions** tab. 5. Filter to **Type** > **Payout**. 6. Expand the payout. If the payout has been confirmed, it is reflected as such under **History**. ## Download the payout letter from Customer Area After the payout is confirmed, you can proceed to download the payout letter from your Customer Area and share it with the account holder. To download the letter, you must have the **Allow the user to download the payout confirmation letter** or **Merchant Extended MarketPlace role** assigned to your Customer Area user. 1. Log in to [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Select the sub-merchant. 4. Select the **Transactions** tab. 5. Filter to **Status** > **Payout**. 6. Expand the payout. 7. In the **History** section, select **Download document**. The letter is downloaded in PDF format. If the payout letter is not available to download, and the payout status is **Initiated** for longer than 2-3 business days, it means that the payout hasn't been confirmed yet. In this case, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), mentioning the PSP reference, the date of the payout, and the account holder code to facilitate further investigation. ## Check if payout was returned to Adyen ### Notifications If a payout was returned to Adyen, you will receive an [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification with `statusCode` **Failed**. In some instances the receiving bank shares a return reason, which helps to identify the cause of the return. Adyen sends the reason in the `status.message.code` and `status.message.text` fields of the notification. If the receiving bank does not share a reason, the account holder should reach out to their bank for further clarification. The following are common return reasons: * 10\_069: Payout failed, check bank account details * 10\_132: Payout failed, Invalid Account Number * 10\_133: Payout failed, Invalid ACH Routing Number * 10\_134: Payout failed, No Account/Unable to Locate Account After receiving a **Confirmed** notification, it is still possible that the payout is returned to Adyen by the receiving bank triggering a new notification with `status.statusCode` **Failed**. **Failed payout notification example** ```json { "eventDate": "2019-01-01T01:00:00+01:00", "eventType": "ACCOUNT_HOLDER_PAYOUT", "executingUserKey": "executing-user-key", "live": false, "pspReference": "TSTPSPR0001", "content": { ... "status": { "message": { "code": "10_069", "text": "Payout has been failed for account seller1. Details: Payout has been rejected by the beneficiary bank." }, "statusCode": "Failed" } } } ``` ### Customer Area 1. Log in to [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Select the sub-merchant. 4. Select the **Transactions** tab. 5. Filter to **Type** > **Payout reversed**. If the funds are returned to Adyen, there may be a further delay of around 3-6 business days before the funds are booked back to the account holder's payable balance. ## Resolve returned payouts If you are making scheduled payouts and a payout was returned, Adyen will block further payouts to that bank account. If this occurs, you can follow the below steps to re-issue a successful payout. If you are making manual payouts, retrying payouts to the same bank account details will likely result in additional payout returns. Make sure to follow the below steps before attempting a new payout. ### Step 1: Verify the account holder's bank details The most common reason among payout issues is an error in the bank account details that the account holder submitted. Ask them to verify and update their bank details. If the details are correct, the account holder's bank could still be rejecting the payout for various reasons, including: * Incorrect account type. * The payout amount is in a different currency than the denomination of the target account. * Some banks have restrictions on the size and/or frequency of payouts. * The account couldn't be located. * The account was frozen. To resolve such cases, ask the account holder to contact their bank, or use a different bank account for payouts. You can re-submit valid bank account details by making a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder) request, or [via our Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page). ### Step 2: Update the account holder's payout state or re-issue payouts #### Manual payouts If you are paying out manually, you can re-issue the payout in your [Customer Area](https://ca-test.adyen.com/), or by making a POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request. ### Tab: Customer Area To re-issue payouts from the Customer Area, you must have the **Instruct payouts to bank accounts for all account holders from the customer area** role. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and switch to the merchant account. 2. Go to **Platform** > **Sub-merchants**. 3. Select the account holder you want to pay out to, then select the **Accounts** tab. 4. Select the more actions menu (**), then select **Payout to bank**. If it appears dimmed, the account does not have a positive balance. 5. In the **New payout** page, specify: * The account from which you want to pay out. The account must have a positive balance. * The bank account to which you want to pay out. * The amount to be paid out. * Optionally, you can add a description to the payout, which will appear on the account holder's bank statement. You can also specify the merchant reference, which you can use to reconcile payouts in reports. 6. Select **Payout** to initiate the payout. You can check the status of the payout in the **Transactions** tab, or listen to the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) webhook. ### Tab: Fund API To re-issue the payout using the Fund API, make a POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request. **Re-issue payout manually** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/payoutAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountCode": "118731451", "amount": { "currency": "EUR", "value": 99792 }, "accountHolderCode": "CODE_OF_ACCOUNT_HOLDER", "description": "Re-issued payout", "bankAccountUUID": "000b81aa-ae7e-4492-aa7e-72b2129dce0c" }' ``` #### Scheduled payouts If you have scheduled payouts, you can update the account holder's payout status in your [Customer Area](https://ca-test.adyen.com/) or via the Account API. ### Tab: Customer Area To update the account holder's payout status in the Customer Area: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Select the sub-merchant. 4. Go to the **Summary** section of the **Overview** tab. 5. Next to **Account Holder Operations**, select **Unblock payouts**. ### Tab: Account API To update the account holder's payout status, send the POST [/updateAccountHolderState](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolderState) request with `disable` **false** and `stateType` **Payout**. **Allow payouts** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolderState \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "CODE_OF_ACCOUNT_HOLDER", "disable": false, "stateType": "Payout" }' ``` --- # Source: https://docs.adyen.com/classic-platforms/platforms-for-partners.md Section: Classic Platforms integration Title: Partner platform requirements Description: Onboard sub-merchants and add online stores so that they can process ecommerce transactions. --- title: "Partner platform requirements" description: "Onboard sub-merchants and add online stores so that they can process ecommerce transactions." url: "https://docs.adyen.com/classic-platforms/platforms-for-partners" source_url: "https://docs.adyen.com/classic-platforms/platforms-for-partners.md" canonical: "https://docs.adyen.com/classic-platforms/platforms-for-partners" last_modified: "2023-02-20T16:48:00+01:00" language: "en" --- # Partner platform requirements Onboard sub-merchants and add online stores so that they can process ecommerce transactions. [View source](/classic-platforms/platforms-for-partners.md) The content on this page only applies when you have a partner arrangement for Adyen for Platforms. For information about platform integrations built after August 1, 2022, refer to our [new integration guide](/adyen-for-platforms-model) instead. On your partner platform, you cannot process payments on behalf of your sub-merchants. Instead, Adyen establishes a direct relationship between each sub-merchant and the card schemes. For us to be able to establish that relationship, and for your sub-merchants to be able to process ecommerce transactions, we need you to: * Collect additional PCI DSS compliance documentation in the form of the [Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf) (SAQ A). * Create online stores for each sub-merchant to establish a direct connection between them and the schemes. Sub-merchants that process point-of-sale (POS) transactions also need stores to be created for them. However, they do not have to complete the SAQ A. The connection between the card networks and each store is established through the POS terminals, as are the PCI DSS requirements. See [Point of sale for platforms](/classic-platforms/platforms-for-pos) for more information. This is an overview of the steps to take: 1. [Create an account holder](/#create-account-holder-platform) for your sub-merchant. 2. [Onboard account holders and collect the SAQ A information](#onboard-partner-platform). 3. [Add a store](#add-store) for the account holder. 4. [Add allowed origins](#add-allowed-origins) for sub-merchants that use their own domains. 5. [Route payments](#route-payments) to the account holder's store. ## Requirements Before you start with your integration, you must: * Be familiar with the features of [Adyen for Platforms](/platforms), such as the [account structure](/classic-platforms/account-structure), the [onboarding and verification process](/classic-platforms/onboard-users), and notifications. The only differences for partner platforms are: * While onboarding, you have to gather the additional PCI compliance data in the form of the SAQ A. * You have to create an online store for each account holder on the platform. * Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) and provide the following required information. * Countries * Currencies * Merchant category codes (MCCs) * Payment methods You can specify different currencies, MCCs, and payment methods for each country/region. We use this information to enable you to create stores based on the type of payments that must be processed in the store. ## Step 1: Create an account holder Create an account holder for your sub-merchant. For details, see [account holders and accounts](/classic-platforms/account-holders-and-accounts). You need to create the account holder before you can proceed to onboard your sub-merchants. Apart from the [minimum information](/classic-platforms/account-holders-and-accounts?tab=minimum-info-business_2#minimum-required-information) needed to create an account holder, also collect the following details from your sub-merchant. You will need these details later when you create a store. * Website address for the [webAddress](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-webAddress) field. * Telephone number (including country code) for the [fullPhoneNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-fullPhoneNumber) field. ## Step 2: Onboard account holders and collect SAQ A details The onboarding process is the same as onboarding regular sub-merchants, with the added requirement to send them the SAQ A. Make sure that each sub-merchant has completed the SAQ A and has passed the KYC verification process before you add a store. ### Collect SAQ A details using the Hosted Onboarding Page If you use our [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page) (HOP), the SAQ A will automatically appear for the sub-merchant as part of the onboarding flow. ### Collect SAQ A details using your own onboarding flow If you have built your [own onboarding implementation](/classic-platforms/onboard-users/custom-onboarding), you have to include an additional call in your onboarding flow. 1. Make a POST request to the [/getPciQuestionnaireUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getPciQuestionnaireUrl) endpoint, specifying: * `accountHolderCode`: The unique reference to the account holder. * `returnUrl`: The URL to your partner platform website. **Get a PCI questionnaire link** ```bash curl https://cal-test.adyen.com/cal/services/Hop/v6/getPciQuestionnaireUrl \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "returnUrl": "URL_TO_YOUR_PLATFORM_PORTAL" }' ``` The response contains: * `redirectURL`: The page to where you redirect your account holder. This URL must be used within 15 seconds and can only be used once. * `pspReference`: The reference to this session. We recommend that you store this for troubleshooting purposes. **Response** ```json { "invalidFields": [], "pspReference": "8315748692943050", "resultCode": "Success", "redirectUrl": "https://hop-test.adyen.com/hop/pci/?token=" } ``` 2. Redirect the account holder to the redirect URL within 15 seconds after you received the response. When they are successfully redirected to the questionnaire, the session starts. The session is valid for 30 minutes. The account holder receives an HTTP 401 status code if: * The redirection did not occur within 15 seconds. * The account holder refreshes or reloads the browser after the session has started. To restart the session, make another POST request to [/getPciQuestionnaireUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getPciQuestionnaireUrl). 3. Make sure that you have [configured webhooks](/classic-platforms/configure-notifications) so you can get the [verification statuses](/classic-platforms/verification-process/check-verification-results#verification-statuses) in the **ACCOUNT\_HOLDER\_VERIFICATION** notification. **Example notification** ```json { "eventDate": "2020-11-05T14:48:10+01:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "Account Holder Update", "live": false, "pspReference": "8515659450108980", "content": { "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "kycCheckStatusData": { "type": "PCI_VERIFICATION", "status": "PASSED" } } } ``` When you have verified that the account holder provided the SAQ A successfully and that the KYC verification is complete, you can continue with the next steps. ## Step 3: Create a store for the account holder An account holder is successfully onboarded on your platform when they have passed the KYC checks and completed the SAQ A. Now, you need to provide us with the details of their store. Make sure our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) has enabled creating stores. If you haven't requested this yet, refer to the [requirements](#requirements). Once our Support Team has enabled creating stores, you can start adding stores for your account holders. 1. Make sure that you have [configured webhooks](/classic-platforms/configure-notifications) so that you are able to receive notifications. Create a [notification configuration](/classic-platforms/configure-notifications#create-a-notification-configuration) with an `eventConfigs` array with: * `eventType`: **ACCOUNT\_HOLDER\_STORE\_STATUS\_CHANGE** * `includeMode`: **INCLUDE** 2. To provide the store details, include a `storeDetails` array when you update an existing account holder. Make a POST request to [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder). In the request body, include an [accountHolderDetails.storeDetails](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails) array, specifying: * [address](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-address): The address of the store. * [fullPhoneNumber](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-fullPhoneNumber): The phone number of the store. * [merchantAccount](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-merchantAccount): The merchant account used for accepting payments. * [merchantCategoryCode](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-merchantCategoryCode): The merchant category code (MCC) that classifies the business of the account holder. * [storeName](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-storeName): The name of the account holder's store. This will be included in the shopper statement. * [storeReference](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-storeReference): Your unique reference for the account holder's store. * [webAddress](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-webAddress): The URL of the account holder's online store. * [shopperInteraction](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-shopperInteraction): The sales channel. In this case, use **Ecommerce**. The next example shows an [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request to add a store to an account holder. **Add store** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "storeDetails" : [ { "address" : { "city": "Store City", "country": "US", "houseNumberOrName": "1", "postalCode": "123", "stateOrProvince": "CA", "street": "Store Street" }, "fullPhoneNumber": "+31201234567", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "7999", "storeName": "Store Name", "storeReference": "YOUR_SUBMERCHANT_STORE_ID", "webAddress": "URL_TO_SUBMERCHANT_WEBSITE", "shopperInteraction": "Ecommerce" } ] } }' ``` The response contains various account holder details, including the `storeDetails` showing that the status of the store is **Pending**. **Response** ```json { "invalidFields": [], ... "accountHolderDetails":{ ... "storeDetails" : [ { "address" : { "city": "Store City", "country": "US", "houseNumberOrName": "1", "postalCode": "123", "stateOrProvince": "CA", "street": "Store Street" }, "fullPhoneNumber": "+31201234567", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "7999", "status": "Pending", "store": "UNIQUE_SUBMERCHANT_STORE_ID", "storeName": "Store Name", "storeReference": "YOUR_SUBMERCHANT_STORE_ID", "webAddress": "URL_TO_SUBMERCHANT_WEBSITE", "shopperInteraction": "Ecommerce" } ], ... }, ... } ``` 3. Before processing any payments, wait until you receive an [ACCOUNT\_HOLDER\_STORE\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_STORE_STATUS_CHANGE) notification showing that the new status of the store is **Active**. **Notification** ```json { "eventType":"ACCOUNT_HOLDER_STORE_STATUS_CHANGE", "eventDate":"2018-04-23T13:13:44+02:00", "executingUserKey":"ws", "live":true, "pspReference":"1313642467023511", "content":{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "store": "UNIQUE_SUBMERCHANT_STORE_ID", "storeReference":"YOUR_SUBMERCHANT_STORE_ID", "newStatus":"Active", "oldStatus":"Pending", "reason":"YOUR_REASON" } } ``` ## Step 4: Add sub-merchant domains to allowed origin If any of your sub-merchants take payments from their own domains, you need to [add their domains to your allowed origins](/development-resources/client-side-authentication#manage-allowed-origins). ## Step 5: Route a payment to a store Each sub-merchant has their own unique connection to the card networks. This connection is represented by their store. When processing payments, you have to direct them to the appropriate store. To route a payment to a store, include the `store` field in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. You can get the value for this field from the response you received when you [added the store](#add-store), or from the [ACCOUNT\_HOLDER\_STORE\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_STORE_STATUS_CHANGE) notification webhook. When processing payments through a store, you can [create a split configuration](/classic-platforms/split-configuration-for-stores) to automatically split payments or you can provide [split instructions](/classic-platforms/processing-payments#processing-split-payments) in every API request. You can split payments across multiple account holders, but you can only process a payment through a single store. The following example shows how to provide split instructions in the API, routing them over a single store. **Process a payment** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v68/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount": { "currency": "USD", "value": 5000 }, "store": "UNIQUE_SUBMERCHANT_STORE_ID", "reference": "YOUR_ORDER_NUMBER", "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_4111111111111111", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737", "holderName": "John Smith" }, "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "splits":[ { "amount":{ "value":4000 }, "type":"MarketPlace", "account":"8815628270908491", "reference":"YOUR_REFERENCE_TO_SPLIT_#1" }, { "amount":{ "value":500 }, "type":"MarketPlace", "account":"181472818", "reference":"YOUR_REFERENCE_TO_SPLIT_#2" }, { "amount":{ "value":500 }, "type":"Commission", "reference":"YOUR_REFERENCE_TO_SPLIT_#3" } ] }' ``` ## See also * [Adyen for Platforms](/platforms) * [Account holders and accounts](/classic-platforms/account-holders-and-accounts) * [Onboard and verify users](/classic-platforms/onboard-users) * [Adyen for Platforms Account API](https://docs.adyen.com/api-explorer/#/Account/latest/overview) --- # Source: https://docs.adyen.com/classic-platforms/platforms-for-pos.md Section: Classic Platforms integration Title: Point of sale for platforms Description: Process point-of-sale payments on behalf of your account holders. --- title: "Point of sale for platforms" description: "Process point-of-sale payments on behalf of your account holders." url: "https://docs.adyen.com/classic-platforms/platforms-for-pos" source_url: "https://docs.adyen.com/classic-platforms/platforms-for-pos.md" canonical: "https://docs.adyen.com/classic-platforms/platforms-for-pos" last_modified: "2021-08-02T16:33:00+02:00" language: "en" --- # Point of sale for platforms Process point-of-sale payments on behalf of your account holders. [View source](/classic-platforms/platforms-for-pos.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Adyen for Platforms enables you to onboard account holders with point-of-sale (POS) integrations to accept in-person payments. To make this happen, you need to: * [Subscribe to store notifications](#subscribe-to-notifications). * [Add a store](#add-store) for the account holder. * [Assign a terminal to the store](#assign-terminal-to-store) and ship it to the the account holder's store address. * [Split funds](#split-a-payment) between accounts in your platform. ## Requirements Before you start processing point-of-sale payments for your account holders, you need to: * Have a [Terminal API integration with Adyen](/point-of-sale/get-started). * Be familiar with the features of [Adyen for Platforms](/platforms), such as [account structure](/classic-platforms/account-structure), the [onboarding and verification process](/classic-platforms/onboard-users), split payments, and notifications. * Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) and provide the following required information. * Countries * Currencies * Merchant category codes (MCCs) * Payment methods You can specify different currencies, MCCs, and payment methods for each country/region. We use this information to enable you to create stores based on the type of payments that must be processed in the store. ## Subscribe to store notifications When you add a store for an account holder, we send a notification to let you know the store has been set up. To ensure you receive this notification: 1. Make a POST request to the [Terminal API endpoint](/point-of-sale/design-your-integration/terminal-api#endpoints), specifying: * `active`: **true**. * `description`: Your text to recognize the notification subscription by. * An `eventConfigs` array with `eventType`: **ACCOUNT\_HOLDER\_STORE\_STATUS\_CHANGE** and `includeMode`: **INCLUDE**. * `notifyURL`: Endpoint on your server where you'll receive the notifications. * `hmacSignatureKey`: Use this parameter if you want us to [protect notifications with HMAC signatures](/classic-platforms/configure-notifications/signing-notifications-with-hmac). It specifies the HMAC key that we'll use to calculate the HMAC signatures of the notifications we send to the `notifyURL`. On your end you'll need to verify the signatures of the incoming notifications. * `notifyUsername` and `notifyPassword`: Username and password that we need for basic authentication with the server where you'll receive the notifications. * `sslProtocol`: Protocol used to secure the communication, such as **TLS** or **SSL**. **/createNotificationConfiguration request** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "active": true, "description":"YOUR_UNIQUE_DESCRIPTION", "eventConfigs":[ { "eventType":"ACCOUNT_HOLDER_STORE_STATUS_CHANGE", "includeMode":"INCLUDE" } ], "notifyURL":"https://www.merchant-domain.com/notification-handler", "hmacSignatureKey":"c6c608e9d2ec95889cb9757e6beb4956c187f44cf7bb7297b16880c0310af7ff", "notifyUsername":"YOUR_USERNAME", "notifyPassword":"YOUR_PASSWORD", "sslProtocol":"SSL" } }' ``` **Response** ```json { "pspReference": "8515681150749298", "configurationDetails": { "active": true, "description": "YOUR_UNIQUE_DESCRIPTION", "eventConfigs": [ { "eventType": "ACCOUNT_HOLDER_STORE_STATUS_CHANGE", "includeMode": "INCLUDE" } ], "notificationId": 20337, "notifyURL": "https://www.merchant-domain.com/notification-handler", "sslProtocol": "SSLInsecureCiphers" } } ``` 2. Make sure that your server [accepts the notifications](/classic-platforms/configure-notifications#accept-notifications). 3. Use the `notificationId` you receive in the response to [test the notification](/classic-platforms/configure-notifications#test-a-notification). ## Create a store for the account holder Make sure our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) has enabled creating stores. If you haven't requested this yet, refer to the [requirements](#requirements). Once our Support Team has enabled creating stores, you can start adding stores for your account holders. To provide store details, include a `storeDetails` array when you create a new account holder or when you update an existing one: 1. Make a POST request to one of the following endpoints: | Situation | Endpoint | Specify | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | There is no account holder for the sub-merchant yet. | [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) | The usual [parameters to create a business account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder), as well as `businessDetails.taxId`. | | You want to add a store to an existing account holder. | [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) | `accountHolderCode`: Your unique reference for the account holder. Include `businessDetails.taxId`, unless it is already present as part of `businessDetails`. | 2. In the request body, include an [accountHolderDetails.storeDetails](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails) array, specifying: * [address](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-address): The `city`, `country`, `houseNumberOrName`, `postalCode`, `stateOrProvince`, and `street` of the physical store where the account holder will process payments from. * [fullPhoneNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-fullPhoneNumber): The phone number of the store. * [merchantAccount](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-merchantAccount): The merchant account used for accepting payments. * [merchantCategoryCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-merchantCategoryCode): The merchant category code (MCC) that classifies the business of the account holder. * [storeName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-storeName): The name of the account holder's store. This will be included in the shopper statement. * [storeReference](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-storeReference): Your unique reference for the account holder's store. The next example shows a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request to create a new account holder with a store. **/createAccountHolder request** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "country": "US" }, "businessDetails": { "legalBusinessName": "Real Good Restaurant Inc.", "taxId": "444455555", "shareholders": [ { "name": { "firstName": "Maria", "gender": "FEMALE", "lastName": "Green" }, "address": { "country": "US" } } ] }, "email": "maria@green.com", "storeDetails" : [ { "storeReference": "YOUR_SUBMERCHANT_STORE_ID", "storeName": "Store Name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "7999", "address" : { "city": "Store City", "country": "US", "houseNumberOrName": "1", "postalCode": "123", "stateOrProvince": "CA", "street": "Store Street" }, "fullPhoneNumber": "+31201234567" } ] }, "legalEntity": "Business" }' ``` The following example shows how to add a store to an existing account holder using an [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) call. **/updateAccountHolder request** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "storeDetails" : [ { "storeReference": "YOUR_SUBMERCHANT_STORE_ID", "storeName": "Store Name", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "7999", "address": { "city": "Store City", "country": "US", "houseNumberOrName": "1", "postalCode": "123", "stateOrProvince": "CA", "street": "Store Street" }, "fullPhoneNumber": "+31201234567" } ] } }' ``` The response contains various account holder details, including the `storeDetails` showing that the status of the store is **Pending**. **Response** ```json { "invalidFields": [], ... "accountHolderDetails":{ ... "storeDetails" : [ { "address": { "city": "Store City", "country": "US", "houseNumberOrName": "1", "postalCode": "123", "stateOrProvince": "CA", "street": "Store Street" }, "fullPhoneNumber": "+31201234567", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "7999", "status": "Pending", "store": "6db2bdbc-5e77-4388-9a6e-9e653905d3e5", "storeReference": "YOUR_SUBMERCHANT_STORE_ID", "storeName": "Store Name", } ], ... }, ... } ``` 3. Before processing point-of-sale (POS) payments, wait until you receive an `ACCOUNT_HOLDER_STORE_STATUS_CHANGE` notification showing that the new status of the store is **Active**. **Notification** ```json { "eventType":"ACCOUNT_HOLDER_STORE_STATUS_CHANGE", "eventDate":"2018-04-23T13:13:44+02:00", "executingUserKey":"ws", "live":true, "pspReference":"12312312313", "content":{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "store": "6db2bdbc-5e77-4388-9a6e-9e653905d3e5", "storeReference":"YOUR_SUBMERCHANT_STORE_ID", "newStatus":"Active", "oldStatus":"Pending", "reason":"Test Reason" } } ``` ## Assign a terminal to the store To process POS payments, the account holder's store needs to have one or more payment terminals. The process is as follows: 1. [Select a terminal](/point-of-sale/what-we-support/select-your-terminals) and inform the account holder of the [communication requirements](/point-of-sale/design-your-integration/choose-your-architecture). 2. [Order a terminal](/point-of-sale/managing-terminals/order-terminals#sales-order-steps) if you do not have the required terminal in your inventory. 3. Assign the terminal from your inventory to the store of the account holder in one of the following ways: * Assign terminals [using your Customer Area](/point-of-sale/managing-terminals/assign-terminals)\ or * Assign terminals in bulk [using API calls](/point-of-sale/automating-terminal-management/assign-terminals-api) The advantage of using the Terminal Management API over the Customer Area, is that API calls enable you to automate assigning terminals and retrieving an overview of terminal assignments. 4. Configure the terminals in the [Customer Area](https://ca-live.adyen.com/ca/ca/login.shtml), under **Point of Sale** > **Terminal settings**. 5. Ship the terminal to the physical store address and instruct the account holder to [board the terminal](/point-of-sale/managing-terminals/board-terminal). ## Split a payment To split a point-of-sale payment, you can: * Create a split configuration to automatically split payments processed through the store. For more information, refer to [How split configuration works](/classic-platforms/split-configuration-for-stores#how-split-configuration-works). * Send split instructions for every transaction at [time of payment](#make-pos-payment) or [at capture](#split-at-capture). When you use a split configuration, Adyen evaluates the rules in the split configuration for all the transactions processed through the store. If you need to change the commission fees for specific transactions, you can send split instructions in the payment or capture API request. Any split instructions that you send through the API overrides the automatic split. ### Make a split payment using the Terminal API To split a POS payment, you make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) call. In the `PaymentRequest` you provide the split payment data in the `SaleToAcquirerData`, in key-value pair or Base64-encoded format. This credits payments directly to an account holder's account. To make the payment: 1. Make a POST request to a [Terminal API endpoint](/point-of-sale/design-your-integration/terminal-api#endpoints), specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - `PaymentRequest`: The request body. This must include: | Parameter | Required | Description | | ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TransactionID`: your reference to identify a payment. We recommend using a unique value per payment. In your Customer Area and Adyen reports, this will show as the **merchant reference** for the transaction. - `TimeStamp`: date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.SaleToAcquirerData` | | Provides the split payment data as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format. See the tables below for details. | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: the transaction [currency](/development-resources/currency-codes). - `RequestedAmount`: the transaction amount. | - To provide the split payment data in `PaymentRequest.SaleData.SaleToAcquirerData`, use the following fields: | Field | Description | Example | | -------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------- | | `split.api` | Version of the Split API: **1**. | **split.api=1** | | `split.totalAmount` | Amount to be split, in minor units. Must be equal to the transaction amount and to the sum of the split amounts. | **split.totalAmount=62000** | | `split.currencyCode` | Currency of the amount to be split. | **split.currencyCode=EUR** | | `split.nrOfItems` | Number of times you will split the payment. Must match the number of split items in the request. | **split.nrOfItems=2** | Specify each split as a `split.item{item#}` starting at **1**: `split.item1`, `split.item2`, and so on. Each split item includes: | Field | Description | Example | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `split.item{item#}.amount` | Amount of the split, in minor units. | **split.item1.amount=60000** and **split.item2.amount=2000** | | `split.item{item#}.type` | Split type. A type of **MarketPlace** or **VAT** sends the amount to the `account` specified. A type of **Commission** or **PaymentFee** sends the amount to your [liable account](/classic-platforms/account-structure). | **split.item1.type=MarketPlace** and **split.item2.type=Commission** | | `split.item{item#}.account` | Account that will receive the split. This is the `accountCode` of one of your account holder's accounts or your own liable account. You do not need to specify an account when `split.type` is **Commission**. |  **split.item1.account=8815628270908491** | | `split.item{item#}.reference` | The reference for that specific transaction split, which is returned in our reporting. We strongly recommend that you always include a reference for the split item. Required if the `split.type` is **MarketPlace**. |   | The following example shows how to split a EUR 620.00 payment into EUR 600.00 to be paid into the account holder's account with `accountCode` 8815628270908491 and EUR 20.00 commission to be paid to the platform. **Payment request with split instructions** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "SaleID":"POSSystemID12345", "ServiceID":"0207111104", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"27908", "TimeStamp":"2019-03-07T10:11:04+00:00" }, "SaleToAcquirerData": "split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=MarketPlace&split.item1.account=8815628270908491&split.item1.reference=test1&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=TestCommission" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":620.00 } } } } } ``` The payment request is routed to the terminal, for the shopper to present their card and verify the payment. The payment is then sent to the Adyen payments platform for processing. 2. Receive the payment result. If your integration uses [asynchronous cloud communications](/point-of-sale/design-your-integration/choose-your-architecture/cloud#async), you must set up event notifications. We then send the Terminal API responses to your endpoint. If the payment is successful: * **Approved** is shown on the terminal display. * You receive a payment response containing: * `POIData.POITransactionID.TransactionID`: [Transaction identifier](/point-of-sale/design-your-integration/terminal-api#transaction-identifier) for the payment in the format `tenderReference.pspReference`. For example, **oLkO0012498220087000.981517998282382C**. * `PaymentResponse.Response.Result`: **Success** * `PaymentResponse.Response.AdditionalResponse`: A base64 string. When decoded, this is a JSON object with additional transaction data. * `PaymentReceipt`: Object containing data you can use to [generate a receipt](/point-of-sale/basic-tapi-integration/generate-receipts). You can also view the details of a payment in your [Customer Area](https://ca-test.adyen.com/), under **Transactions** > **Payments**. ### Split at capture using the API Some platforms do not know the final split amounts at the moment the payment request is made. If this applies to your account holder's POS payments, you need to [enable manual capture for POS payments](/point-of-sale/capturing-payments#enable-manual-capture) and follow up each authorised Terminal API payment with a [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) API call. Splitting at capture is also the procedure to use for tipping (gratuity) and partial authorizations. Enabling manual capture for POS payments applies to all your point-of-sale account holders. Proceed as follows to split at capture: 1. From the [`transactionID` ](/point-of-sale/design-your-integration/terminal-api#transaction-identifier)field in the [payment response](/point-of-sale/basic-tapi-integration/make-a-payment#payment-response), get the `pspReference` of the authorization you want to capture. 2. To capture and split a payment at the same time, send a POST [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) request, where `paymentPspReference` is the `pspReference` of the authorization you want to capture. In the body, include the [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-splits) array. For each item in the array, specify the following fields: | Parameter | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [account](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-splits-account) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The account that will receive (or be charged) the split amount. This is the `accountCode` of your account holder's accounts or your liable balance account. You do not need to specify this field when `type` is **Commission**. | | [amount.value](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-amount-value) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The value of the split amount. You do not need to specify this field for transaction fees, since they are not known at the time of payment. | | [type](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-type) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Defines the part of the payment you want to book to a specific `account`. Possible values:- **Commission**: books the commission to your platform's liable account. - **MarketPlace**: books the sale amount to the specified account. - **PaymentFee**: books the transaction fees to your platform's liable account. - **VAT**: books the value-added tax for the sale amount to the specified account. | | [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-reference) | | Required if `type` is **MarketPlace** Your reference for the split, which you can use to link the split to other operations and to reconcile payments. If the reference is not provided, the split is reported as part of the aggregated **TransferBalance** record in the [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report). | | [description](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-description) | | Your description for that specific transaction split, which is returned in our reporting. | The example below shows how to capture a USD 80.00 authorization with `pspReference` 981517998282382C, and split it into USD 76.00 to be paid into the account holder's account with `accountCode` 8815628270908491 and USD 4.00 commission to be paid to your liable account. **Split funds at time of capture** #### curl ```bash curl https://checkout-test.adyen.com/v72/payments/981517998282382C/captures \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" }, "reference": "YOUR_REFERENCE_NUMBER", "splits":[ { "amount":{ "value":7600 }, "type":"MarketPlace", "account":"8815628270908491", "reference":"YOUR_REFERENCE_TO_SPLIT_#1" }, { "amount":{ "value":400 }, "type":"Commission", "reference":"YOUR_REFERENCE_TO_SPLIT_#2" } ] }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) SplitAmount splitAmount1 = new SplitAmount() .value(7600L); SplitAmount splitAmount2 = new SplitAmount() .value(400L); Amount amount = new Amount() .currency("USD") .value(8000L); Split split1 = new Split() .reference("YOUR_REFERENCE_TO_SPLIT_#1") .amount(splitAmount1) .type(Split.TypeEnum.MARKETPLACE) .account("8815628270908491"); Split split2 = new Split() .reference("YOUR_REFERENCE_TO_SPLIT_#2") .amount(splitAmount2) .type(Split.TypeEnum.COMMISSION); PaymentCaptureRequest paymentCaptureRequest = new PaymentCaptureRequest() .reference("YOUR_REFERENCE_NUMBER") .amount(amount) .splits(Arrays.asList(split1, split2)) .merchantAccount("YOUR_MERCHANT_ACCOUNT"); // Send the request ModificationsApi service = new ModificationsApi(client); PaymentCaptureResponse response = service.captureAuthorisedPayment("paymentPspReference", paymentCaptureRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $splitAmount1 = new SplitAmount(); $splitAmount1 ->setValue(7600); $splitAmount2 = new SplitAmount(); $splitAmount2 ->setValue(400); $amount = new Amount(); $amount ->setCurrency("USD") ->setValue(8000); $split1 = new Split(); $split1 ->setReference("YOUR_REFERENCE_TO_SPLIT_#1") ->setAmount($splitAmount1) ->setType("MarketPlace") ->setAccount("8815628270908491"); $split2 = new Split(); $split2 ->setReference("YOUR_REFERENCE_TO_SPLIT_#2") ->setAmount($splitAmount2) ->setType("Commission"); $paymentCaptureRequest = new PaymentCaptureRequest(); $paymentCaptureRequest ->setReference("YOUR_REFERENCE_NUMBER") ->setAmount($amount) ->setSplits(array($split1, $split2)) ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new ModificationsApi($client); $response = $service->captureAuthorisedPayment('paymentPspReference', $paymentCaptureRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) SplitAmount splitAmount1 = new SplitAmount { Value = 7600 }; SplitAmount splitAmount2 = new SplitAmount { Value = 400 }; Amount amount = new Amount { Currency = "USD", Value = 8000 }; Split split1 = new Split { Reference = "YOUR_REFERENCE_TO_SPLIT_#1", Amount = splitAmount1, Type = Split.TypeEnum.MarketPlace, Account = "8815628270908491" }; Split split2 = new Split { Reference = "YOUR_REFERENCE_TO_SPLIT_#2", Amount = splitAmount2, Type = Split.TypeEnum.Commission }; PaymentCaptureRequest paymentCaptureRequest = new PaymentCaptureRequest { Reference = "YOUR_REFERENCE_NUMBER", Amount = amount, Splits = new List{ split1, split2 }, MerchantAccount = "YOUR_MERCHANT_ACCOUNT" }; // Send the request var service = new ModificationsService(client); var response = service.CaptureAuthorisedPayment("paymentPspReference", paymentCaptureRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const paymentCaptureRequest = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", amount: { value: 8000, currency: "EUR" }, reference: "YOUR_REFERENCE_NUMBER", splits: [ { amount: { value: 7600 }, type: "MarketPlace", account: "8815628270908491", reference: "YOUR_REFERENCE_TO_SPLIT_#1" }, { amount: { value: 400 }, type: "Commission", reference: "YOUR_REFERENCE_TO_SPLIT_#2" } ] } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.captureAuthorisedPayment("paymentPspReference", paymentCaptureRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) splitAmount1 := checkout.SplitAmount{ Value: 7600, } splitAmount2 := checkout.SplitAmount{ Value: 400, } amount := checkout.Amount{ Currency: "USD", Value: 8000, } split1 := checkout.Split{ Reference: common.PtrString("YOUR_REFERENCE_TO_SPLIT_#1"), Amount: &splitAmount1, Type: "MarketPlace", Account: common.PtrString("8815628270908491"), } split2 := checkout.Split{ Reference: common.PtrString("YOUR_REFERENCE_TO_SPLIT_#2"), Amount: &splitAmount2, Type: "Commission", } paymentCaptureRequest := checkout.PaymentCaptureRequest{ Reference: common.PtrString("YOUR_REFERENCE_NUMBER"), Amount: amount, Splits: []checkout.Split{ split1, split2, }, MerchantAccount: "YOUR_MERCHANT_ACCOUNT", } // Send the request service := client.Checkout() req := service.ModificationsApi.CaptureAuthorisedPaymentInput("paymentPspReference").IdempotencyKey("UUID").PaymentCaptureRequest(paymentCaptureRequest) res, httpRes, err := service.ModificationsApi.CaptureAuthorisedPayment(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 8000, "currency": "USD" }, "reference": "YOUR_REFERENCE_NUMBER", "splits": [ { "amount": { "value": 7600 }, "type": "MarketPlace", "account": "8815628270908491", "reference": "YOUR_REFERENCE_TO_SPLIT_#1" }, { "amount": { "value": 400 }, "type": "Commission", "reference": "YOUR_REFERENCE_TO_SPLIT_#2" } ] } # Send the request result = adyen.checkout.modifications_api.capture_authorised_payment(request=json_request, paymentPspReference="paymentPspReference", idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :amount => { :value => 8000, :currency => 'USD' }, :reference => 'YOUR_REFERENCE_NUMBER', :splits => [ { :amount => { :value => 7600 }, :type => 'MarketPlace', :account => '8815628270908491', :reference => 'YOUR_REFERENCE_TO_SPLIT_#1' }, { :amount => { :value => 400 }, :type => 'Commission', :reference => 'YOUR_REFERENCE_TO_SPLIT_#2' } ] } # Send the request result = adyen.checkout.modifications_api.capture_authorised_payment(request_body, 'paymentPspReference', headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const splitAmount1: Types.checkout.SplitAmount = { value: 7600 }; const splitAmount2: Types.checkout.SplitAmount = { value: 400 }; const amount: Types.checkout.Amount = { currency: "USD", value: 8000 }; const split1: Types.checkout.Split = { reference: "YOUR_REFERENCE_TO_SPLIT_#1", amount: splitAmount1, type: Types.checkout.Split.TypeEnum.MarketPlace, account: "8815628270908491" }; const split2: Types.checkout.Split = { reference: "YOUR_REFERENCE_TO_SPLIT_#2", amount: splitAmount2, type: Types.checkout.Split.TypeEnum.Commission }; const paymentCaptureRequest: Types.checkout.PaymentCaptureRequest = { reference: "YOUR_REFERENCE_NUMBER", amount: amount, splits: [split1, split2], merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.ModificationsApi.captureAuthorisedPayment("paymentPspReference", paymentCaptureRequest, { idempotencyKey: "UUID" }); ``` 3. In the capture response, note the following: * `paymentPspReference`: The PSP reference of the authorization. * `pspReference`: The PSP reference associated with this capture request. This is different from the PSP reference of the authorization. * `status`: **received** 4. Listen to the [CAPTURE webhook](/point-of-sale/capturing-payments#capture-webhook) to learn the outcome of the request. ## See also * [Adyen for Platforms](/platforms) * [Terminal API](/point-of-sale/design-your-integration/terminal-api) * [API Explorer - Capture](https://docs.adyen.com/api-explorer/#/Payment/latest/capture) --- # Source: https://docs.adyen.com/classic-platforms/platforms-integration-checklist.md Section: Classic Platforms integration Title: Platforms integration and go live checklist Description: Understand the core integration checks you can perform before you go live. --- title: "Platforms integration and go live checklist" description: "Understand the core integration checks you can perform before you go live." url: "https://docs.adyen.com/classic-platforms/platforms-integration-checklist" source_url: "https://docs.adyen.com/classic-platforms/platforms-integration-checklist.md" canonical: "https://docs.adyen.com/classic-platforms/platforms-integration-checklist" last_modified: "2021-02-01T15:26:00+01:00" language: "en" --- # Platforms integration and go live checklist Understand the core integration checks you can perform before you go live. [View source](/classic-platforms/platforms-integration-checklist.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. On this page, you can find the checks that you can perform to make sure you have set up your Adyen for Platforms integration correctly before you go live. ## Requirements The [integration checklist](#afp-integration-check) and the [go live checklist](#afp-golive) on this page assume that you have set up a test integration and that you are familiar with the Adyen for Platforms integration options and choices. If you haven't started yet, check out the [Platforms quick start guide](/classic-platforms/quick-start). The choices you make have an impact how and what you should verify for your integration. Make sure that you have made a decision on how you: * Collect information necessary for verifying sub-merchants; [staggered or all at once](/classic-platforms/onboard-users). * **Onboard** sub-merchants as account holders; using a [Hosted Onboarding Page (HOP)](/classic-platforms/onboard-users/hosted-onboarding-page) or using [your own onboarding flow](/classic-platforms/onboard-users/custom-onboarding). * Handle **payouts**; [automatically](/classic-platforms/payouts/scheduled-payout) trigger scheduled payouts to bank accounts, or [manually](/classic-platforms/payouts/manual-payout) send payouts to bank accounts or eligible cards. Also, make sure that you are familiar with: * The [account structure](/classic-platforms/account-structure) of Adyen for Platforms. * The endpoints in the [Platforms API](/classic-platforms/api) and the [error codes](/classic-platforms/error-codes). * The Adyen for Platforms reports: the [balance report](/classic-platforms/reports-and-fees/marketpay-balance-report), the [payments accounting report](/reporting/marketpay-payments-accounting-report) and the [payout report](/classic-platforms/reports-and-fees/marketpay-payout-report) (for automatic payouts only). ## Integration checklist Onboard a test sub-merchant as an account holder, test a payment and test your integration before you configure your live environment, process real payments and start payouts. Follow the steps in this checklist: * [Step 1: Verify your test account](#afp-testaccount) * [Step 2: Test your onboarding and verification process](#afp-onboarding) * [Step 3: Processing payments](#afp-payments) * [Step 4: Verify payouts](#afp-payouts) * [Step 5: Set up and test notifications](#afp-notifications) * [Step 6: Reconcile transactions using reports](#afp-reports) ## Step 1: Verify your test account Before you start your integration test, check that you have an Adyen for Platforms [test account](/classic-platforms/quick-start#before-you-begin) with the required API credentials. You can only verify your integration if these are in place. 1. Log in to your test Customer Area with your Adyen for Platforms test account. 2. Select your platform merchant account, and then **Accounts** > **API credentials**. 3. Check that you have API credentials for your platform account and for processing payments: 1. Platform: **ws\_\[123456]@MarketPlace.\[YourPlatformAccount]**. 2. Payments: **ws\@Company.****\[YourCompanyAccount]**. 4. By default, the [cards payment method](/payment-methods/cards) is added to your platform test account. If you want to test other payment methods, make sure you [request](/payment-methods/add-payment-methods) them first. ## Step 2: Test your onboarding and verification process Configure [verification notifications](#afp-kyc-notifications) and then sign up, onboard a sub-merchant as an account holder, and perform checks to verify that your process works. Test the process that you have chosen: using a [Hosted Onboarding Page](#afp-hop) or using your [own onboarding flow](#afp-own-onboarding). ### Set up verification notifications Because the verification process is such an important part of your platform, we strongly recommend that you set up the [notifications](/classic-platforms/notification-types) `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE` and `ACCOUNT_HOLDER_VERIFICATION` to be able to fully verify that your onboarding process works. Once you go live, you will use these notifications to monitor an account holder's [verification status](/classic-platforms/verification-process/check-verification-results#verification-statuses), so that you can take the appropriate follow-up action and communicate with account holder about their onboarding status. You have to complete the [verification process](/classic-platforms/verification-process) in order to send [payouts](#afp-payouts) to an account holder. 1. **Set up verification notifications**.\ [Create a notification configuration](/classic-platforms/configure-notifications) for the following notification types: * `ACCOUNT_HOLDER_CREATED` * `ACCOUNT_HOLDER_UPDATED` * `ACCOUNT_HOLDER_STATUS_CHANGE` * `ACCOUNT_HOLDER_VERIFICATION` 2. **Expose an endpoint to handle notifications**.\ By [exposing an endpoint](/development-resources/webhooks/configure-and-manage#expose-an-endpoint-on-your-server), you make sure that you can [accept notifications](/classic-platforms/configure-notifications#accept-notifications). 3. **Test the notifications while you test your onboarding process**.\ Continue with the onboarding verification steps in using a [Hosted Onboarding Page](#afp-hop) or using your [own onboarding flow](#afp-own-onboarding) to verify that the notifications work. ### Onboard using a Hosted Onboarding Page (HOP) Sign up, onboard a sub-merchant as an account holder, and perform a check to verify that the process works. You can use the details from the Adyen for Platforms [test scenarios](/classic-platforms/test-scenarios) when you fill out the Hosted Onboarding Page. 1. **Create an account holder**.\ [Create an account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder) with a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder) request. The minimum required information depends on the legal entity type and the country where the account holder is based. 2. **Test your [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page)**. * Start the verification process and get the HOP URL. * When you [redirect](/classic-platforms/onboard-users/hosted-onboarding-page#handle-redirect) the sub-merchant to your return URL, inform them of their onboarding progress based on the notification webhooks you receive. * Look at the [notifications](#afp-kyc-notifications) to determine if the sub-merchant is successfully onboarded as an account holder, stopped the process or that you require additional information to complete the verification. You are responsible for following up on the [verification status](/classic-platforms/verification-process) and communicating with sub-merchants onboarding on your platform. ### Onboard using your own verification process When you build your own verification process, you need a webpage or an app that sub-merchants can use to fill out their information. To test your onboarding process, make sure that you have a webpage or an app ready to collect the required information, and that you understand how to send the information to Adyen. See [Build your own implementation](/classic-platforms/onboard-users/custom-onboarding) for more information. You can use the details from the Adyen for Platforms [test scenarios](/classic-platforms/test-scenarios) when you fill out your onboarding webpage or app. 1. **Create an account holder**.\ [Create an account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder) for with a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder) request. The minimum required information depends on the legal entity type and the country where the account holder is based. 2. **Test your webpage or app: onboard a sub-merchant as an account holder**. * On your webpage or app, collect the relevant details based on [country requirements and their legal entity type](/classic-platforms/verification-process/required-information). Send the information to Adyen with a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder) request. * Look at the [notifications](#afp-kyc-notifications) to determine if the sub-merchant is successfully onboarded as an account holder, stopped the process or that you require additional information to complete the verification. You are responsible for following up on the [verification status](/classic-platforms/verification-process) and communicating with sub-merchants onboarding on your platform. ## Step 3: Processing payments When a customer pays on your platform, you can automatically split these funds between multiple accounts. With every payment, capture, or refund you can customize the split between any number of [accounts in your platform](/classic-platforms/account-structure#your-platform) and amounts including your liable account. How you want to split your payments, and at what stage in the payment - immediately at [authorisation](/classic-platforms/processing-payments#providing-split-instructions) or later at [capture](/classic-platforms/processing-payments#split-at-capture) - is your decision. For more information, see [processing payments](/classic-platforms/processing-payments). 1. **Provide split instructions**\ Provide an array of [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits) objects in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) call. 2. **Check if split payments work**\ Test a split payment with your preferred way of splitting with a [test card number](/development-resources/test-cards-and-credentials/test-card-numbers). To check what happens to the payment, see [payment statuses](/classic-platforms/processing-payments#payment-statuses). We recommend to test the following: * Split at [authorization](/classic-platforms/processing-payments#providing-split-instructions) * Split at [capture](/classic-platforms/processing-payments#split-at-capture) * Split a [refund](/classic-platforms/processing-payments#split-a-refund) * [Chargebacks](/classic-platforms/processing-payments#chargeback-and-disputes) and [fund transfer](/classic-platforms/fund-transfer) ## Step 4: Verify payouts To be able to perform payouts, account holders have to pass the verification checks and you have to know the `accountCode` and, for manual payouts, the `accountHolderCode`. Your platform's liable account also has its own `accountCode`. For more information, see [payouts](/classic-platforms/payouts) and [accounts](/classic-platforms/account-structure/#your-platform). 1. **Test a one-off payout**\ Use the test account holder and make a POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request. 2. **Verify the payout**\ Check that you get a successful `200` response to confirm that the payout is successful. You can also set up and test notifications for payouts, see the next step. ## Step 5: Set up and test notifications Because the requests you send to the Platforms API are asynchronous, you have to set up notification webhooks to know the final result of the request. In step 2, you set up and tested the essential [verification checks](#afp-kyc-notifications). In this step, you verify any other notifications that you want to use. You configure notification webhooks to be able to get notifications of: * The verification process, as mentioned earlier. * Status changes of your **accounts** and **account holders**, as mentioned earlier. * Fund management: notifications of **payouts**, **transfers** and **refunds**. * Availability of **reports**. For more information, see [Notifications](/classic-platforms/notifications). 1. **Create a notification configuration**.\ [Configure a notification configuration](/classic-platforms/configure-notifications) for the notifications that you want to receive. 2. **Test your notification configuration**.\ Follow the steps in the documentation to [test your notification configuration](/classic-platforms/configure-notifications#test-a-notification). ## Step 6: Reconcile transactions using reports Use the reports generated in the test environment to test your reconciliation processes. For more information on how you can use the reports, refer to [Reconcile transactions through reports](/classic-platforms/reconciliation-use-cases). Make sure that you are able to: 1. [Download reports](/reporting/downloading-reports). 2. Run your reconciliation process. ## Go live checklist After you have built out and tested your Adyen for Platforms integration, you will want to go live. When you are ready, follow these steps: 1. **Request your account to be taken live**\ Make sure that you have signed the Adyen for Platforms contract to get a live account. Your sales or account manager will help you with this process. 2. **Access the live Customer Area**\ Once you get an email confirmation that your live account is ready, use the live credentials to log in to the [live Customer Area](https://ca-live.adyen.com/). 3. **Update account settings**\ When your account is taken live, some settings are copied over, but you need to update the settings for the following: * Notifications * Report subscriptions * API responses * Shopper statements for payouts and payments, aligned with your sales or account manager. * [Recurring payment details](/online-payments/tokenization/make-token-payments#test-and-go-live) (if applicable) 4. **Set up risk configurations**\ It is important that risk management is set up to handle live transactions, including selecting a [risk profile](/risk-management/create-and-use-risk-profiles/) that best matches your business. 5. **Add a platform payout account**\ Provide information for the payout account where you want to receive payments for the platform merchant account. 6. **Request additional payment methods**\ Review the payment methods in your [Adyen merchant account](/classic-platforms/account-structure#your-adyen-account). Based on where your platform is located, you will have some default payment methods that are ready for use. You can add [more payment methods](/classic-platforms/processing-payments#supported-payment-methods). Once your platform is live, onboarded and verified account holders can offer all the payment methods that you add to your platform merchant account. 7. **Update code base**\ Update your code base and platform merchant account settings. * **Switch to live API credentials**\ Generate API keys in your [live Customer Area](https://ca-live.adyen.com/). Copy these keys to your live platform. * **Switch your test endpoints to your live, custom URLs**\ Change the [Platforms API](/classic-platforms/api) endpoints that you used to test your integration to live endpoints.\ For example, to change the [Account API](https://docs.adyen.com/api-explorer/#/Account/overview) from **test** to **live**, change `https://cal-test.adyen.com/cal/services/Account/v5` to `https://cal-live.adyen.com/cal/services/Account/v5`.\ Also change the [payment endpoints](/development-resources/live-endpoints) to live. 8. **End-to-end test**\ Make sure that your platform can handle the entire payment lifecycle from authorization and refusals through payout and reconciliation. We suggest testing the following: * Payments: * Test the happy flow by making payments with real cards, and payments with real details for other payment methods that you support. * Test non-happy payment flows to ensure your integration can handle errors and refusal reasons. * Test the 3D Secure flow, if you implemented that. * Payment modifications, like cancellations and refunds. * Notification webhooks: Confirm you are able to acknowledge any [notification type](/classic-platforms/configure-notifications) with an `[accepted]` response, to prevent notifications being queued. * Order handling. * Bank statements: Verify that payments appear correctly on the shopper's bank statement. * Payouts: Confirm you can onboard merchants, perform verification checks and can send and receive payouts. * Reconciliation: Confirm your system completes the reconciliation process. ## See also * [Platforms quick start](/classic-platforms/quick-start) * [Test scenarios](/classic-platforms/test-scenarios) * [Adyen for Platforms API](/classic-platforms/api) --- # Source: https://docs.adyen.com/classic-platforms/prepare-reports.md Section: Classic Platforms integration Title: Prepare the reports Description: Configure, download, and combine reports. --- title: "Prepare the reports" description: "Configure, download, and combine reports." url: "https://docs.adyen.com/classic-platforms/prepare-reports" source_url: "https://docs.adyen.com/classic-platforms/prepare-reports.md" canonical: "https://docs.adyen.com/classic-platforms/prepare-reports" last_modified: "2023-01-09T13:30:00+01:00" language: "en" --- # Prepare the reports Configure, download, and combine reports. [View source](/classic-platforms/prepare-reports.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. ## Requirements Before you start preparing reports, make sure to: * Be familiar with the [payment lifecycle](/reporting/reports-and-the-payments-lifecycle), [a platform's account structure](/classic-platforms/account-structure), and [how funds flow](/classic-platforms/account-structure#how-funds-flow). * Find out which [types of reports](/classic-platforms/reports-and-fees#relevant-reports) are relevant for your use case. * Understand the [types of fees](/classic-platforms/reports-and-fees#fees). ## Step 1. Configure reports When you know the reports that are relevant for your reconciliation processes, proceed to: * [Configure timezones](/reporting/time-zone-setting). Reports are generated at different periods and can be based on different time zones. If reconciliation fails, mismatches in reporting periods or time zones are the common causes. * [Configure more report columns](#add-report-columns). ### Configure more report columns The reports come with default columns, and for some of the reports you can optionally configure the columns, adding more if necessary. Adding columns increases the report file size. We recommend to first review the default settings and only add columns necessary for your specific insights and reconciliation process needs. * [Adyen account reports](/classic-platforms/reports-and-fees#adyen-account-reports): configure the columns in your Customer Area. To know if additional columns are available for a report, refer to the report documentation. For example, [additional columns for Settlement details report](/reporting/settlement-reconciliation/transaction-level/settlement-details-report#additional-columns). * [Platform reports](/classic-platforms/reports-and-fees#platform-reports): to configure additional columns, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). For a full financial reconciliation, we recommend enabling the following additional report columns. | Report | Recommended additional columns | Description | | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [Settlement details report](/reporting/settlement-detail-report) | Split Payment Data | Shows the exact split instructions provided during payments processing requests. You can use this to fully reconcile against corresponding funds postings in the Marketplace Payments accounting report. [Configure this column](/reporting/settlement-reconciliation/transaction-level/settlement-details-report#configure-report-columns) for relevant merchant accounts connected to your platform. | | | [Settlement details report](/reporting/settlement-detail-report) | AMS Booking Date | Shows when Adyen assessed and booked a line item to the monthly invoicing period. Depending on the scope and volume of your platform operations, settlement line items can potentially span the start or end of a monthly invoicing period. You can use this to reconcile the invoicing period. [Configure this column](/reporting/settlement-reconciliation/transaction-level/settlement-details-report#configure-report-columns) for relevant merchant accounts connected to your platform. | | | [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report) | storecode, storereference | Shows the store code and store reference from which a payment is processed. Enable one or both of these columns if your platform uses [stores](/classic-platforms/split-configuration-for-stores), such as for in-person payments. Adding these columns may reduce the need to combine report data. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to add these columns. | | | [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report) | settlementbatchid | Shows the identifier of the corresponding Settlement Detail Report batch identifier. If your platform is subject to shopper disputes and chargebacks, enable this column on your platform to fully reconcile the funds postings related to specific dispute events. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to add this column. | | ## Step 2. Download reports Download reports, either [manually](/reporting/manually-get-reports) through your [Customer Area](https://ca-test.adyen.com/) or [generate and download reports automatically](/reporting/automatically-get-reports). If you want to regularly do a full reconciliation, consider building a scalable solution by automatically ingesting and combining reports. ## Step 3. Combine reports Combining data from several reports can be helpful when tracking a transaction throughout its [entire lifecycle](/reporting/reports-and-the-payments-lifecycle) and is necessary for full reconciliation. To facilitate the use of multiple reports, Adyen includes the references that you sent in the original transactions to help you correctly identify and match each entry. To combine reports, you need to match the following references: | Settlement details report, Payment accounting report | Marketplace Payments accounting report | Description | | ---------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Psp Reference | Payment Psp Reference | A unique identifier generated by Adyen for each transaction. | | Merchant Reference | Payment Merchant Reference | The [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-reference) field that you provide to Adyen for each transaction. The API does not require that the value be unique, but we recommend that you use a unique value per transaction so you can use the field to match payments with your records. | These references are also returned in the API responses and sent in the [notification webhooks](/development-resources/webhooks). When combining reports, make sure you check that: * The reports are from the same reporting period. * The reports are generated using the same time zone. Reports are generated at different periods and can be based on different time zones. If reconciliation fails, mismatches in reporting periods or time zones are the common causes. ## Step 4. Test your reconciliation process Before you start reconciliation in the live environment, we also recommend that you test your processes using complete reports. In the [common reconciliation processes guides](/classic-platforms/reconciliation-use-cases), we only show selected rows and columns to illustrate the examples. To get complete reports, you can: * Download examples from the [Reporting documentation](/reporting). * Make test transactions and then [download reports in the test environment](/reporting/downloading-reports). ## Next steps [Common reconciliation processes](/classic-platforms/reconciliation-use-cases) [Learn how you can use reports in common reconciliation use cases.](/classic-platforms/reconciliation-use-cases) --- # Source: https://docs.adyen.com/classic-platforms/processing-payments.md Section: Classic Platforms integration Title: Processing online payments Description: Learn how to split transactions with your account holders. --- title: "Processing online payments" description: "Learn how to split transactions with your account holders." url: "https://docs.adyen.com/classic-platforms/processing-payments" source_url: "https://docs.adyen.com/classic-platforms/processing-payments.md" canonical: "https://docs.adyen.com/classic-platforms/processing-payments" last_modified: "2021-08-26T13:50:00+02:00" language: "en" --- # Processing online payments Learn how to split transactions with your account holders. [View source](/classic-platforms/processing-payments.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. With every payment, capture, or refund on Adyen for Platforms, you can split the funds between any number of [accounts in your platform](/classic-platforms/account-structure/#your-platform), including your liable account. For example, when a customer pays on your platform, you can split the funds so that a portion goes to your liable account as platform fee, and the sale amount goes to the account holder's account. You can [provide split instructions through API requests](#providing-split-instructions), or if your integration processes payments through stores, you can also [create a split configuration](/classic-platforms/processing-payments/split-data-in-additionaldata) to automatically split payments. If you do not provide split instructions, the payments and all associated fees are booked to your platform's liable account. ### Supported payment methods Adyen for Platforms supports a wide range of payment methods, such as major card brands (Visa, Mastercard, American Express, Discover/Diners), Apple Pay, Google Pay, SEPA, iDEAL, and more. Restrictions may apply where Adyen is not in the settlement flow. Reach out to your sales manager to confirm. ## Providing split instructions through API requests You can split an incoming or outgoing fund transfer into a maximum of 1000 split items, booked to different [accounts in your platform](/classic-platforms/account-structure/#your-platform), including your liable account. You can provide split instructions: * [At the time of payment](#processing-split-payments). * When [capturing](#split-at-capture) a payment. * When [refunding](#split-a-refund) a payment. To split funds, you'll need to send the [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits) array. For each split object in the array, you need to specify the following fields: * [account](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits-account): The [accountCode](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder#responses-200-accounts-accountCode) of the account where the split amount will be sent. * [amount.value](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits-amount-value): The split amount. * [type](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits-type): When sending the amount to any other account in your platform, set the type to **MarketPlace**. Other types such as **Commission** or **VAT** sends the split amount to your liable account. * [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits-reference): Your unique identifier for the split. While this field is only required in the API if `type` is **MarketPlace**, we strongly recommend that you send a reference for all other types. You can use the reference to reconcile the split and the associated payment in the transaction overview and in the [reports](/classic-platforms/reconciliation-use-cases). Without a reference, the amounts are merged and you will be unable to reconcile the split. For example, when a customer pays for goods on your platform for USD 400.00, you can split the payment such that: * USD 300.00 goes to the seller's account as payment for the goods. You'll send the payment to the account of the seller account holder with `accountCode` **8516026831348764**. * USD 100.00 goes to your liable account as your platform's commission. **Structure of a splits array** ```json { "splits":[ { "amount":{ "value":30000 }, "type":"MarketPlace", "account":"8516026831348764", "reference":"QXhlbFN0b2x0ZW5iZXJnCg" }, { "amount":{ "value":10000 }, "type":"Commission", "reference":"THVjYXNCbGVkc29lCg" } ] } ``` ### Validating split instructions Adyen frontend systems only validate the format of the split instructions. The accounts provided in split instructions are **not** validated by the frontend. If you provide split instructions with an account that does not exist, or an account belonging to an account holder with a [**Closed** status](/classic-platforms/verification-process#account-holder-statuses), the full amount of the transaction will be sent to the liable account regardless of the original split instructions. You will receive a [PAYMENT\_FAILURE](https://docs.adyen.com/api-explorer/#/NotificationService/latest/PAYMENT_FAILURE) notification of the failed split. You can use [Fund transfer](/classic-platforms/fund-transfer) to correct any account balances. ## Split at payment To split funds at the time of payment, [provide split instructions](#providing-split-instructions) in your POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. You can send split instructions regardless of your [PCI compliance level](/get-started-with-adyen/adyen-glossary/#pci-compliance). If you do not know what the total split will look like for your account holders at the time of a payment, you can skip providing any split instructions at payment and instead [provide split instructions at capture](#split-at-capture). Split data provided at capture overrides any split instructions provided with the initial payment request. Below is an example of a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request with split instructions. To make test payments, refer to [Test card numbers](/development-resources/test-cards-and-credentials/test-card-numbers). **Split funds at time of payment** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "paymentMethod": { "type": "scheme", "number": "4111111111111111", "cvc": "737", "expiryMonth": "03", "expiryYear": "2030", "holderName": "John Smith" }, "amount": { "value": 40000, "currency": "USD" }, "reference": "YOUR_ORDER_NUMBER", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "returnUrl": "https://your-company.example.com/...", "splits":[ { "amount":{ "value":30000 }, "type":"MarketPlace", "account":"8516026831348764", "reference":"QXhlbFN0b2x0ZW5iZXJnCg" }, { "amount":{ "value":10000 }, "type":"Commission", "reference":"THVjYXNCbGVkc29lCg" } ] }' ``` ### Payment statuses Once a payment has reached the **SentForSettle** state, the transaction will show up in the account as a **PENDING\_CREDIT** transaction. Once Adyen has received the funds for the payment, the transaction will be updated to **CREDITED** and the funds will be available to [pay out on the account](/classic-platforms/payouts). You can always look at the transaction associated with all accounts on a account holder using the [/accountHolderTransactionList](https://docs.adyen.com/api-explorer/Fund/latest/post/accountHolderTransactionList) call. ## Split at capture If you do not know the final split amounts at the time of payment, you can provide split instructions with in your [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) request. You can only split at capture for payment methods that support [separate captures](/online-payments/capture). For example, you cannot split at capture for [iDEAL](/payment-methods/ideal) payments, because iDEAL does not support separate captures. Providing split instructions at capture overrules data from the original payment request. If you do not send split instructions in the capture request, then we'll use the split instructions from the payment authorization. Partial captures require you to supply split instructions. If you do not provide split instructions, then all the funds to go to the liable account. **Split funds at capture** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v72/payments/{paymentPspReference}/captures \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 599, "currency": "EUR" }, "reference": "YOUR_REFERENCE_NUMBER", "splits":[ { "amount":{ "value":399 }, "type":"MarketPlace", "account":"151272963", "reference":"Partial capture #1" }, { "amount":{ "value":200 }, "type":"MarketPlace", "account":"181472818", "reference":"Partial capture #2" } ] }' ``` ## Split a refund We recommend that you always provide split instructions in refunds so that you are always in control and can support different refund scenarios, such as partial and multiple partial refunds. ### Tab: Provide split instructions (Recommended) Send split instructions in your refund request to support different refund scenarios, such as a partial and multiple partial refunds. When sending split instructions on a refund request, you must: * Only use accounts that were part of the original split. * Use the same `reference` values from the original split. For example, let's split a USD 10 payment with USD 2 going to your liable account and USD 8 going to `account` **12345.** If you provide a split `reference` of **splitId\_1** for the payment, then on the refund, you will need to use the same split `reference` of **splitId\_1**. Here is the example [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request of USD 10 with USD 2 going to your liable account and USD 8 to `account` **12345**. **Make a payment with split instructions** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "paymentMethod":{ "type":"scheme", "number":"4400 0000 0000 0008", "expiryMonth":"03", "expiryYear":"2030", "holderName":"John Smith", "cvc":"737" }, "amount":{ "value":1000, "currency":"USD" }, "reference":"YOUR_REFERENCE_NUMBER", "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "returnUrl":"https://your-company.example.com/...", "splits":[ { "amount":{ "value":200 }, "type":"Commission", "reference":"splitId_1_commission" }, { "amount":{ "value":800 }, "type":"MarketPlace", "account":"12345", "reference":"splitId_1" } ] }' ``` This following example would be the refund of that payment if you were going to split the refund with USD 5 from your liable account and USD 5 from `account` **12345**. Here is an example [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request. **Split a refund with different data** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v72/payments/{paymentPspReference}/refunds \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "reference":"YOUR_REFERENCE_NUMBER", "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "amount":{ "value":1000, "currency":"USD" }, "splits":[ { "amount":{ "value":500 }, "type":"Commission", "reference":"splitId_1_commission" }, { "amount":{ "value":500 }, "type":"MarketPlace", "account":"12345", "{hint:This is the same reference used in the split payment}reference{/hint}":"splitId_1" } ] }' ``` ### Tab: Use split instructions from payment authorization A refund without split instructions uses the original information from the payment authorization. Only leave the split instructions empty in the following conditions: * The refund amount is the same as the authorized amount. * The payment authorization contained split instructions. * You want to debit the amount based on the original split. If the payment authorization did not have split instructions, by default the full refund amount is debited from the liable balance account. To split a refund using the original split instructions, send a refund request without any split instructions. The refund uses the split instructions from the authorization, *not* the split instructions from a capture. Here is an example [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request without providing split instructions. **Split a refund using the original split instructions** ```bash # Set your X-API-KEY with the API key from the Customer Area. curl https://checkout-test.adyen.com/v72/payments/{paymentPspReference}/refunds \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "reference":"YOUR_REFERENCE_NUMBER", "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "amount":{ "value":599, "currency":"USD" } }' ``` ## Chargeback and disputes You are responsible for all disputes and [dispute management](/risk-management/understanding-disputes). This includes providing first line support to your sub-merchants and the customers of your platform, clearly communicating your contact details on your website or app, and managing all disputes between your customers and your sub-merchants. ### Split chargebacks Chargebacks, by default, deduct according to original split instructions. Where a chargeback reversal amount does not match the payment amount, funds are deducted entirely from your liable account. You can [transfer funds](/classic-platforms/fund-transfer) to correct any account balances. If you want to configure your platform to deduct chargebacks entirely from your liable account instead, reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). When your platform is liable for chargebacks, you can also book the full amount of chargebacks or chargeback reversals entirely from your liable account regardless of the split. To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Next steps [Pay out to bank accounts](/classic-platforms/payouts) [Make scheduled or one-off payouts to bank accounts.](/classic-platforms/payouts) [Pay out to cards](/classic-platforms/payouts/manual-payout/payout-to-cards) [Make one-off payouts to cards.](/classic-platforms/payouts/manual-payout/payout-to-cards) --- # Source: https://docs.adyen.com/classic-platforms/quick-start.md Section: Classic Platforms integration Title: Platforms quick start Description: Start accepting payments and making payouts to your sub-merchants. --- title: "Platforms quick start" description: "Start accepting payments and making payouts to your sub-merchants." url: "https://docs.adyen.com/classic-platforms/quick-start" source_url: "https://docs.adyen.com/classic-platforms/quick-start.md" canonical: "https://docs.adyen.com/classic-platforms/quick-start" last_modified: "2021-08-04T10:18:00+02:00" language: "en" --- # Platforms quick start Start accepting payments and making payouts to your sub-merchants. [View source](/classic-platforms/quick-start.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. ## Requirements Before you start using Adyen for Platforms, make sure to: 1. [Contact our Sales Team](https://www.adyen.com/contact/sales) to check if your use cases are eligible for Adyen for Platforms. When we confirm that Adyen for Platforms is a good fit for your use cases, you receive your Adyen test credentials including two API credentials. 2. Create API keys for your two API credentials. * Platform: **ws\_\[123456]@MarketPlace.\[YourPlatformAccount]**.\ You'll use the API key to onboard sub-merchants as account holders and to send payouts. * Payments: **ws\@Company.\[YourCompanyAccount]**.\ You'll use the API key to process payments for your account holders. ## Step 1: Sign up sub-merchants To start with your integration, sign up sub-merchants as account holders in your platform. For each sub-merchant, create a corresponding [account holder](/classic-platforms/account-structure), and one or more (if necessary) accounts. To create an account holder, call [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder), specifying: * `firstName` * `lastName`  * `email` * `legalEntity` (individual or business) * `country` The fields above are required for an account holder to start [accepting payments](#step-3-process-payments) and initiating the verification process. The following code illustrates how to create an individual account holder with the basic fields: **Create account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"TestAccountHolder5691", "accountHolderDetails":{ "address": { "country": "US" }, "email":"test@adyen.com", "individualDetails":{ "name":{ "firstName":"First name", "gender":"MALE", "lastName":"Last Name" } } }, "createDefaultAccount":true, "legalEntity":"Individual" }' ``` When you create an account holder, by default we also create an account for this account holder. If you'd rather create accounts manually using the [/createAccount](https://docs.adyen.com/api-explorer/#/Account/createAccount) endpoint, include in your [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request: * `createDefaultAccount`: **false** ## Step 2: Onboard and verify account holders During the onboarding process, you need to collect additional information from the account holder for verification checks. The account holder must pass these checks before they can process payments at higher [tiers](/classic-platforms/onboard-users) and have [payouts](/classic-platforms/payouts) enabled. You can either build your own onboarding implementation or send the account holders to a [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page) where they can directly submit their information. If you choose to build your own implementation, you'll have to collect the required information and send this information to Adyen using either the `/updateAccountHolder` or `/uploadDocument` API calls.  The account holder might also need to provide additional documents. The code below illustrates how to upload a passport using the `/uploadDocument` call. The image file, which contains the document, must be encoded as a Base64 string and assigned to the `documentContent` field, and the `documentDetail` object should contain an account holder code and other information about the document. **Upload a document** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/uploadDocument \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50", "documentDetail":{ "accountHolderCode":"TestAccountHolder5691", "documentType":"PASSPORT", "filename":"passport.png", "description":"test passport description" } }' ``` The verification is usually performed asynchronously. Adyen sends the results to your backend through notification webhooks. To accept these notifications, configure them as described in [Set up notifications](#step-5-set-up-notifications). ## Step 3: Process payments After creating account holders with the basic information, you can immediately start processing payments for them. In this case, the amount customers pay to your platform should be split between an account holder's account and your platform's account.  To make a payment, you'll need to send a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request and provide the API key for your **ws\@Company.\[YourCompanyAccount]** API credential. In your request, pass [split-specific fields](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/payments__reqParam_splits). In the example below, `paymentMethod` and `amount` fields contain payment details, while `split` contains instructions on how to split a payment. In this case, EUR 62.00 will be split between an account holder's account (EUR 60.00) and your platform commission (EUR 2.00). **Process payments** ```bash curl https://checkout-test.adyen.com/v68/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "reference":"platforms-test-6426782037", "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "paymentMethod":{ "type":"scheme", "number":"4111 1111 1111 1111", "expiryMonth":"03", "expiryYear":"2030", "holderName":"John Smith", "cvc":"737" }, "amount":{ "value": 6200, "currency":"EUR" }, "splits":[ { "amount":{ "value": 6000, "currency":"EUR" }, "type": "MarketPlace", "account":"151272963", "reference":"6124145", "description":"Porcelain Doll: Eliza (20cm)" }, { "amount":{ "value": 200, "currency":"EUR" }, "type":"Commission", "reference":"6124146" } ] }' ``` After a transaction has been successfully authorised, you must capture it for the payment to be settled. You can either use automatic capture (contact the [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to set this up) or make the `/capture` request manually. In addition, you can partially capture or refund the payment. For more information, refer to [Processing payments](/classic-platforms/processing-payments). ## Step 4: Pay out After an account holder successfully passes required [verification checks](#step-2-onboard-sub-merchants), you can initiate a payout to either their bank account or to a [card eligible for payouts](/classic-platforms/payouts/manual-payout/payout-to-cards#check-and-store). For this, call `/payoutAccountHolder` as follows. In the example below, `currency` and `value` specify the amount to be paid out (EUR 997.92), `accountCode` and `accountHolderCode` uniquely identify the source account, while the `bankAccountUUID` specifies the bank account that receives the payout. **Send a payout** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/payoutAccountHolder \ -H 'x-API-key: YOUR_X-API-KEY' \ -H 'content-type: application/json' \ -d '{ "accountCode":"118731451", "amount":{ "currency":"EUR", "value":99792 }, "accountHolderCode":"TestAccountHolder877209", "description":"12345 – Test", "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c" }' ``` You can also schedule a payout job to automatically make a payout (e.g. once per day). For more information, refer to [Payouts](/classic-platforms/payouts). ## Step 5: Set up notifications All Platforms API create, update, and delete requests are asynchronous, so you must rely on notifications to know the final result of a request. To be aware of all the events that happen to your platform account, as well as get the results of verification and other important changes, your system must be able to accept notifications. You receive these notifications as callbacks to the URLs you specify in the [/createNotificationConfiguration](https://docs.adyen.com/api-explorer/NotificationConfiguration/latest/post/createNotificationConfiguration) call. In this case, we activate the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) notification that should be sent to the endpoint on your server (https\://www\.merchant-domain.com/notification-handler) using the specified connection credentials (**testUserName** and **testPassword**). For more information, refer to [Configure notifications](/classic-platforms/configure-notifications) and [Notification types](/classic-platforms/notification-types). You may also want to configure HMAC signing of notifications for additional verification. To do this, see [Signing notifications with HMAC](/classic-platforms/configure-notifications/signing-notifications-with-hmac). **Create notification configuration request** ```bash curl https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "configurationDetails":{ "apiVersion": 6, "active": true, "description":"Your unique description", "eventConfigs":[ { "eventType":"ACCOUNT_HOLDER_VERIFICATION", "includeMode":"INCLUDE" }, { "eventType":"ACCOUNT_HOLDER_CREATED", "includeMode":"INCLUDE" } ], "notifyURL":"https://www.merchant-domain.com/notification-handler", "notifyUsername":"yourUsername", "notifyPassword":"yourPassword", "sslProtocol":"SSL" } }' ``` ## Step 6: Reconcile transactions using reports After you have made transactions in the test environment, check the generated reports so you can start building your reconciliation process. For more information on how most Adyen for Platforms merchants use the reports, refer to [Reconcile transactions using reports](/classic-platforms/reconciliation-use-cases). ## Next steps [required](/classic-platforms/onboard-users) [Onboarding and verification](/classic-platforms/onboard-users) [Onboard sub-merchants as account holders and move them through the verification process.](/classic-platforms/onboard-users) [required](/classic-platforms/processing-payments) [Process payments](/classic-platforms/processing-payments) [Split payments with your account holders.](/classic-platforms/processing-payments) [required](/classic-platforms/configure-notifications) [Set up notifications](/classic-platforms/configure-notifications) [Receive notifications about your platform account.](/classic-platforms/configure-notifications) --- # Source: https://docs.adyen.com/classic-platforms/reconciliation-use-cases.md Section: Classic Platforms integration Title: Common reconciliation processes Description: Use reports to track and reconcile transactions for the accounts in your platform. --- title: "Common reconciliation processes" description: "Use reports to track and reconcile transactions for the accounts in your platform." url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases" source_url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases.md" canonical: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases" last_modified: "2021-07-23T16:53:00+02:00" language: "en" --- # Common reconciliation processes Use reports to track and reconcile transactions for the accounts in your platform. [View source](/classic-platforms/reconciliation-use-cases.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. In this guide, we describe common reconciliation processes and how you can use reports to implement these processes. ## Requirements Before you start building your reconciliation processes, make sure to: * Be familiar with the [payment lifecycle](/reporting/reports-and-the-payments-lifecycle), [a platform's account structure](/classic-platforms/account-structure), and [how funds flow](/classic-platforms/account-structure#how-funds-flow). * Find out which [types of reports](/classic-platforms/reports-and-fees#relevant-reports) are relevant for your use case. * [Configure](/classic-platforms/prepare-reports#configure-reports), [download](/classic-platforms/prepare-reports#download-reports), and [combine](/classic-platforms/prepare-reports#combine-reports) reports. * Understand the [types of fees](/classic-platforms/reports-and-fees#fees). [Reconcile accounts receivable](/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable) [Reconcile the net amount settled to the accounts in your platform.](/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable) [Build a transactional ledger](/classic-platforms/reconciliation-use-cases/build-transactional-ledger) [Track all transactions for each account holder and account in your platform.](/classic-platforms/reconciliation-use-cases/build-transactional-ledger) [Reconcile automatic payouts](/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts) [Track transactions part of scheduled payouts.](/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts) [Reconcile fees](/classic-platforms/reconciliation-use-cases/understand-fees) [Learn how you can reconcile fees debited from your liable account.](/classic-platforms/reconciliation-use-cases/understand-fees) --- # Source: https://docs.adyen.com/classic-platforms/reconciliation-use-cases/build-transactional-ledger.md Section: Classic Platforms integration Title: Build a transactional ledger Description: Track transactions for each account holder and account in your platform. --- title: "Build a transactional ledger" description: "Track transactions for each account holder and account in your platform." url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/build-transactional-ledger" source_url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/build-transactional-ledger.md" canonical: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/build-transactional-ledger" last_modified: "2023-03-28T13:38:00+02:00" language: "en" --- # Build a transactional ledger Track transactions for each account holder and account in your platform. [View source](/classic-platforms/reconciliation-use-cases/build-transactional-ledger.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. To break down the amounts credited or debited for the [accounts in your platform](/classic-platforms/account-structure/#your-platform), use the [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report). The report contains all the financial activities within your platform—useful when creating a transactional ledger for your account holders or to reconcile your records. You can use the information in the Marketplace Payments accounting report to: * Track credits resulting from payments and transfers. * Track debits resulting from refunds, chargebacks, transfers, fees, and payouts. * Reconcile the balance of your platform's liable account, from which Adyen deducts all payment fees. ## Split data in reports Adyen credits funds to the accounts in your platform based on the [split instructions](/classic-platforms/processing-payments#providing-split-instructions) that you provide at the time of payment or capture. The split information is reflected in the Marketplace Payments accounting report. If you split a payment between two accounts, the split is reflected in two separate rows that credits each account with the specified split amount. The same applies for refunds; a refund split between two accounts results in two rows indicating a debit to each account. If you do not provide instructions for the split instructions, Adyen credits or debits the amount to or from your liable account. For example, if you do not provide split instructions in a partial refund, Adyen debits the funds from your liable account. The aggregate of these debits and credits are reflected in the report with a **TransferBalance** [record type](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report#record-types). All the transaction fees are deducted from your liable account. The total fees are reflected in the row with **Fee** record type. ## Example We show selected rows and columns below to illustrate how you can track transactions. To get a complete report, refer to [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report). In this example, we group the transactions for the same **Account holder** and **Account** by using different colors for each. ### Selected columns from Marketplace Payments accounting report | Account holder | Account | Payment PSP reference | Payment merchant reference number | Main currency | Main amount | Record type | | --------------------------- | ------- | --------------------- | --------------------------------- | ------------- | ----------- | ----------- | | LiableAccountHolderPlatform | 1234567 | 852584129291587A | REF\_001 | EUR | 60 | Credited | | AccountHolder\_1 | 7891012 | 852584129291587A | REF\_001 | EUR | 240 | Credited | | LiableAccountHolderPlatform | 1234567 | 853781278121997C | REF\_002 | EUR | -2 | Debited | | AccountHolder\_2 | 3823129 | 853781278121997C | REF\_002 | EUR | -48 | Debited | | LiableAccountHolderPlatform | 1234567 | 852584132050336H | REF\_003 | EUR | 30 | Credited | | AccountHolder\_2 | 3823129 | 852584132050336H | REF\_003 | EUR | 120 | Credited | | LiableAccountHolderPlatform | 1234567 | | | EUR | -9.72 | Fee | | AccountHolder\_1 | 7891012 | | | EUR | -240 | Payout | When you filter based on the **Account holder** and **Account**, you can get transactions for each account holder and account in your platform. Below is an example of a summary of their transactions. | Account holder | Account | Transactions | | --------------------------- | ------- | --------------------------------------------------------- | | LiableAccountHolderPlatform | 1234567 | Credited EUR 90, Debited EUR 2, Debited EUR 9.72 for fees | | AccountHolder\_1 | 7891012 | Credited EUR 240, Paid out EUR 240 | | AccountHolder\_2 | 3823129 | Debited EUR 48, Credited EUR 120 | Note: to find out more about transaction identifiers, refer to [Combining reports](/classic-platforms/prepare-reports#combine-reports). ## Getting the balance for each account You can calculate the balance of an account holder's account by tracking all the credits, debits, and payouts for each account holder and account in the Marketplace Payments accounting report. Alternatively, you can also use the [MarketPay balance report](/classic-platforms/reports-and-fees/marketpay-balance-report) where you can get the available balances of all the accounts in your platform, including your liable account. ### Negative balances Accounts in your platform can have a negative balance as a result of refunds or chargebacks. Adyen allows negative balances for up to 30 days. At the end of the month, if an account has had a negative balance for more than 30 days, Adyen compensates by debiting the amount from your platform's liable account. If you'd rather have account holders cover their negative balances instead, you can provide them the option to [top up their accounts](/classic-platforms/top-up-accounts). When Adyen compensates a negative balance, this will be reflected in an entry of record type **FundTransfer** in the Marketplace Payments accounting report. The description provides more information about the negative balance compensation, for example, *Compensate negative balance from account 1 to account 2*. Note that negative balances only occur as a result of refunds or chargebacks. An account cannot have a negative balance due to paying out or transferring a balance. You can only pay out or transfer the available balance. ### Example We show selected rows and columns below to illustrate how you can get an overview of the balances per account. To get a complete report, refer to [Marketpay Balance Report](/classic-platforms/reports-and-fees/marketpay-balance-report). The example below shows what the corresponding balances will be based from the [previous example](#selected-columns-from-marketplace-payments-accounting-report). #### Selected columns from Marketpay Balance Report | Account holder | Virtual account | Currency | Balance | | --------------------------- | --------------- | -------- | ------- | | LiableAccountHolderPlatform | 1234567 | EUR | 78.28 | | AccountHolder\_1 | 7891012 | EUR | 0 | | AccountHolder\_2 | 3823129 | EUR | 72 | ## See also * [Adyen for Platforms account structure](/classic-platforms/account-structure) * [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report) * [Marketpay Balance Report](/reporting/settlement-reconciliation/transaction-level/marketpay-balance-report) --- # Source: https://docs.adyen.com/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable.md Section: Classic Platforms integration Title: Reconcile accounts receivable Description: Reconcile the net amount settled to the accounts in your platform. --- title: "Reconcile accounts receivable" description: "Reconcile the net amount settled to the accounts in your platform." url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable" source_url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable.md" canonical: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable" last_modified: "2023-02-21T10:28:00+01:00" language: "en" --- # Reconcile accounts receivable Reconcile the net amount settled to the accounts in your platform. [View source](/classic-platforms/reconciliation-use-cases/reconcile-accounts-receivable.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. When customers of your platform make a payment, the payment is processed through [your Adyen merchant accounts](/classic-platforms/account-structure#your-adyen-account). After Adyen receives the funds, Adyen settles and credits the funds to the [accounts in your platform](/classic-platforms/account-structure/#your-platform). When Adyen settles a batch of transactions, Adyen also creates a corresponding [Settlement details report](/reporting/settlement-detail-report). You can use the information in the Settlement details report to: * Get the net amount settled to the accounts in your platform. * Identify which transactions have settled in the batch and get the net debit or net credit for each batch. * Determine the fees associated with settled transactions, such as scheme and interchange fees. ## Example We show selected rows and columns below to illustrate how you can get the net amount settled to the accounts in your platform. To get a complete report, refer to [Settlement details report](/reporting/settlement-detail-report). In this example, the batch includes: * Three settled transactions: two payments and one refund. * A deduction for other fees incurred. If you want to further reconcile the amount, refer to [Understanding fees](/classic-platforms/reconciliation-use-cases/understand-fees). ### Selected columns from Settlement details report | Merchant account | PSP reference | Merchant reference | Type | Gross currency | Gross debit | Gross credit | Net currency | Net debit | Net credit | Commission | Markup | Scheme | Interchange | | ------------------- | ---------------- | ------------------ | --------------- | -------------- | ----------- | ------------ | ------------ | --------- | ---------- | ---------- | ------ | ------ | ----------- | | YourMerchantAccount | 852584129291587A | REF\_001 | Settled | EUR | | 300 | EUR | | 297.6 | | 0.6 | 0.2 | 1.6 | | YourMerchantAccount | 853781278121997C | REF\_002 | Refunded | EUR | 50 | | EUR | 54 | | 4 | | | | | YourMerchantAccount | 852584132050336H | REF\_003 | Settled | EUR | | 150 | EUR | | 147 | 3 | | | | | YourMerchantAccount | **** | **** | Fee | | | | EUR | 0.32 | | | | | | | YourMerchantAccount | **** | **** | **XASTransfer** | | | | EUR | 390.28 | | | | | | The row with [type](/reporting/settlement-reconciliation/transaction-level/settlement-details-report#journal-types) **XASTransfer** (cross accounting system transfer) reflects the net amount that Adyen settles to the accounts in your platform. * **XASTransfer** = Total of the **Net credit** column - total of **Net debit** column For this report, Adyen settled and credited **EUR 390.28** to accounts in your platform. To break down the amount to corresponding credits and debits for each account in your platform, refer to [Build a transactional ledger](/classic-platforms/reconciliation-use-cases/build-transactional-ledger). ## See also * [Adyen for Platforms account structure](/classic-platforms) * [Settlement details report](/reporting/settlement-detail-report) --- # Source: https://docs.adyen.com/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts.md Section: Classic Platforms integration Title: Track transactions in scheduled payouts Description: Track transactions that are part of scheduled payouts. --- title: "Track transactions in scheduled payouts" description: "Track transactions that are part of scheduled payouts." url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts" source_url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts.md" canonical: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Track transactions in scheduled payouts Track transactions that are part of scheduled payouts. [View source](/classic-platforms/reconciliation-use-cases/transactions-scheduled-payouts.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. If you set up [scheduled payouts](/classic-platforms/payouts/scheduled-payout), you can use the [Marketpay Payout Report](/classic-platforms/reports-and-fees/marketpay-payout-report). The timing of this report is optimized to match the timing of scheduled payouts. This report contains all the payouts initiated within the day and the transactions (both credits and debits) that were part of the paid out amount. The report is grouped per account holder and account. ## Example We show selected rows and columns below to illustrate how you can track transactions that were part of the amount automatically paid out. To get a complete report, refer to [Marketpay Payout Report](/classic-platforms/reports-and-fees/marketpay-payout-report). This daily reports contains all the payouts initiated within the day, grouped by the **Account holder** and **Account**. ### Selected columns from Marketplace Payout report | Account holder | Account | PSP reference | Payment merchant reference number | Main currency | Main amount | Record type | | --------------------------- | ------- | ---------------- | --------------------------------- | ------------- | ----------- | ----------- | | LiableAccountHolderPlatform | 1234567 | 852584129291587A | REF\_001 | EUR | 60 | Credited | | LiableAccountHolderPlatform | 1234567 | 852584132050336H | REF\_003 | EUR | 30 | Credited | | LiableAccountHolderPlatform | 1234567 | | | EUR | -9.72 | Fee | | LiableAccountHolderPlatform | 1234567 | 853781278121997C | REF\_002 | EUR | -2 | Debited | | LiableAccountHolderPlatform | 1234567 | 8915844059375211 | | EUR | -78.28 | Payout | | AccountHolder\_1 | 7891012 | 852584129291587A | REF\_001 | EUR | 240 | Credited | | AccountHolder\_1 | 7891012 | 8915844059375211 | | EUR | -240 | Payout | | AccountHolder\_2 | 3823129 | 853781278121997C | REF\_002 | EUR | -48 | Debited | | AccountHolder\_2 | 3823129 | 852584132050336H | REF\_003 | EUR | 120 | Credited | | AccountHolder\_2 | 3823129 | 8915844059375211 | | EUR | -72 | Payout | ## See also * [Adyen for Platforms account structure](/classic-platforms/account-structure) * [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report) * [Marketpay Balance Report](/reporting/settlement-reconciliation/transaction-level/marketpay-balance-report) --- # Source: https://docs.adyen.com/classic-platforms/reconciliation-use-cases/understand-fees.md Section: Classic Platforms integration Title: Reconcile fees Description: Reconcile fees debited from your platform's liable account. --- title: "Reconcile fees" description: "Reconcile fees debited from your platform's liable account." url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/understand-fees" source_url: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/understand-fees.md" canonical: "https://docs.adyen.com/classic-platforms/reconciliation-use-cases/understand-fees" last_modified: "2021-07-23T16:37:00+02:00" language: "en" --- # Reconcile fees Reconcile fees debited from your platform's liable account. [View source](/classic-platforms/reconciliation-use-cases/understand-fees.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Your platform incurs [fees](/classic-platforms/reports-and-fees#fees), such as processing fees for each received transaction and fees for premium features. Adyen deducts fees from settlement and debits them from your platform's liable account. To reconcile these fees, you can get the totals and the breakdown from the following reports. * [Settlement details report](/reporting/settlement-detail-report): contains a breakdown of fees for settled transactions. * [Payment accounting report](/reporting/invoice-reconciliation/payment-accounting-report): contains a breakdown of all transaction-related fees, including those that have not settled. * [Payment processing invoice](/reporting/invoice-reconciliation/payment-processing-invoice): contains totals for fees incurred during the month, including those charged on a monthly basis. ### Invoice deduction The monthly invoice takes into account the fees that were already deducted in the [Payment accounting report](/reporting/invoice-reconciliation/payment-accounting-report) and [Settlement details report](/reporting/settlement-detail-report). Aside from fees, the monthly invoice also includes rebates, which you can get if you achieve preferable tiered pricing during any given month. Any outstanding debits for fees or credits for rebates outlined in the monthly invoice will be debited or credited from the settlement. These are reported as **InvoiceDeduction** types in the [Settlement details report](/reporting/settlement-detail-report). ## Reconcile total fees To reconcile the total fees debited from your liable account, we recommend using the Settlement details report. If you want, you can also match the total fees with the Marketplace Payments accounting report. When reconciling total fees, make sure you check: * That the reports are from the same reporting period. * The time zone of the reports. Reports are generated at different periods and can be based on different time zones; if reconciliation fails, mismatches in reporting periods or time zones are the common causes. To reconcile total fees: 1. Calculate the total fees from each [Settlement details report](/reporting/settlement-detail-report). * Total fees = Total of **Gross Credit** columns - Total of **Gross Debit** columns - **XASTransfer** row\ The **XASTransfer** row is the the net amount settled to the accounts in your platform. 2. Get the sum of the total transactional fees, other fees, and the monthly invoice deduction (if present) from each [Settlement details report](/reporting/settlement-detail-report). * Total fees = Total of **Commission** + **Markup** + **Scheme Fees** + **Interchange** columns + **Fee** + **InvoiceDeduction** rows 3. Calculate the total of the **Fee** record types and the monthly invoice deduction (if present) from each [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report). * Total fees = Total of **Fee** + **InvoiceDeduction** rows The *Total fees* in the 3 computations should match. ## Examples We show selected rows and columns below to illustrate how you reconcile fees debited from your platform's liable account. To get complete reports, refer to [Reporting documentation](/reporting). ### Selected columns from Marketplace Payments accounting report Let's take, for example, the EUR 9.72 fee deducted from the settlement for your platform's liable account. To reconcile these fees, start with getting the **Payment PSP reference** and the **Payment merchant reference number**. In the sample report below, we group the transactions that have the same references by using different colors for each. | Account holder | Account | Payment PSP reference | Payment merchant reference number | Main currency | Main amount | Record type | | --------------------------- | ------- | --------------------- | --------------------------------- | ------------- | ----------- | ----------- | | LiableAccountHolderPlatform | 1234567 | **852584129291587A** | **REF\_001** | EUR | 60 | Credited | | AccountHolder\_1 | 7891012 | **852584129291587A** | **REF\_001** | EUR | 240 | Credited | | LiableAccountHolderPlatform | 1234567 | **853781278121997C** | **REF\_002** | EUR | -2 | Debited | | AccountHolder\_2 | 3823129 | **853781278121997C** | **REF\_002** | EUR | -48 | Debited | | LiableAccountHolderPlatform | 1234567 | **852584132050336H** | **REF\_003** | EUR | 30 | Credited | | AccountHolder\_2 | 3823129 | **852584132050336H** | **REF\_003** | EUR | 120 | Credited | | LiableAccountHolderPlatform | 1234567 | **** | **** | EUR | -9.72 | Fee | | AccountHolder\_1 | 7891012 | **** | **** | EUR | -240 | Payout | Next we take the Settlement details report to match the **Payment PSP reference** and the **Payment merchant reference number**. ### Selected columns from Settlement details report In the Settlement details report, match the **PSP reference** and **Merchant reference** with the references from the Marketplace Payments accounting report. We find that the fees are associated with three settled transactions: two payments and one refund. | Merchant account | PSP reference | Merchant reference | Type | Gross currency | Gross debit | Gross credit | Net currency | Net debit | Net credit | Commission | Markup | Scheme | Interchange | | ------------------- | -------------------- | ------------------ | ----------- | -------------- | ----------- | ------------ | ------------ | --------- | ---------- | ---------- | ------ | ------ | ----------- | | YourMerchantAccount | **852584129291587A** | **REF\_001** | Settled | EUR | | 300 | EUR | | 297.6 | | 0.6 | 0.2 | 1.6 | | YourMerchantAccount | **853781278121997C** | **REF\_002** | Refunded | EUR | 50 | | EUR | 54 | | 4 | | | | | YourMerchantAccount | **852584132050336H** | **REF\_003** | Settled | EUR | | 150 | EUR | | 147 | 3 | | | | | YourMerchantAccount | **** | | Fee | | | | EUR | 0.32 | | | | | | | YourMerchantAccount | **** | | XASTransfer | | | | EUR | 390.28 | | | | | | We can then break down the **Fee** row in the Marketplace Payments accounting report by computing the following from the Settlement details Report: * Settlement details **Commissions** + **Markup** + **Scheme** + **Interchange** columns + **Fee** row = Marketplace Payments accounting report **Fee** * EUR 9.4 + EUR 0.32 = **EUR 9.72** If you want to go further, we can take the Payment accounting report to track the remaining **EUR 0.32** unreconciled fee. ### Selected columns from Payment accounting report We show selected rows and columns below to illustrate finding the processing fees. In a full report, if you filter on a reference, you get multiple rows for different payment statuses. To get a complete report, refer to [Payment accounting report](/reporting/invoice-reconciliation/payment-accounting-report). In the Payment accounting report, we find the processing fees associated with settled transactions and for a refused transaction (in red). The total processing fees incurred for all transactions is equal to **EUR 0.32**. | Merchant account | PSP reference | Merchant reference | Record Type | Payment Currency | Received | Processing Fee Currency | Processing Fee | | ------------------- | -------------------- | ------------------ | ------------- | ---------------- | -------- | ----------------------- | -------------- | | YourMerchantAccount | **852584129291587A** | **REF\_001** | Received | EUR | 500 | EUR | -0.08 | | YourMerchantAccount | **853781278121997C** | **REF\_002** | SentForRefund | EUR | 0 | EUR | -0.08 | | YourMerchantAccount | **852584132050336H** | **REF\_003** | Received | EUR | 150 | EUR | -0.08 | | YourMerchantAccount | **881584131869379D** | **REF\_004** | Received | EUR | 100 | EUR | -0.08 | | YourMerchantAccount | **881584131869379D** | **REF\_004** | Refused | EUR | -100 | | | ## See also * [Types of fees](/classic-platforms/reports-and-fees#fees) * [Adyen for Platforms account structure](/classic-platforms/account-structure) * [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report) * [Payment accounting report](/reporting/invoice-reconciliation/payment-accounting-report) * [Settlement details report](/reporting/settlement-detail-report) * [Payment processing invoice](/reporting/invoice-reconciliation/payment-processing-invoice) --- # Source: https://docs.adyen.com/classic-platforms/release-notes.md Section: Classic Platforms integration Title: Release notes Description: Learn about the latest updates for Adyen for Platforms. --- title: "Release notes" description: "Learn about the latest updates for Adyen for Platforms." url: "https://docs.adyen.com/classic-platforms/release-notes" source_url: "https://docs.adyen.com/classic-platforms/release-notes.md" canonical: "https://docs.adyen.com/classic-platforms/release-notes" last_modified: "2023-01-12T14:42:00+01:00" language: "en" --- # Release notes Learn about the latest updates for Adyen for Platforms. You can find all changes related to Adyen for Platforms on this page. To make it easier to have an overview of the changes in a specific area of your integration, we organized the release notes into the following categories: * APIs: new versions and changes to existing versions. * Notifications: new versions and changes to existing versions. * Hosted onboarding: changes to the hosted onboarding page and related pages in [Customer Area](https://ca-live.adyen.com/), and changes to existing versions of the [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) endpoint. * Customer Area: changes to pages under the **Platform** section in [Customer Area](https://ca-live.adyen.com/), except pages related to hosted onboarding. * KYC: changes to how Adyen handles KYC verification. * Reports: changes to how reports are generated. * General: other changes that do not fall in any of the previous categories, such as new supported countries or improvements to payouts. You can also use the [API Diff Tool](https://docs.adyen.com/api-explorer/api-diff-tool) to compare any two versions of an API. [![](/user/themes/adyen-docs/assets/icons/rss.svg) Get updates by RSS](/classic-platforms/release-notes.xml) ## Available filters Category..., Version..., Release date... ## 2023-06-05 — Hosted onboarding ### Improved Account holders with businesses based in Cyprus can now enter up to 8 characters of their company number on the Hosted Onboarding Page. ## 2023-05-08 — Hosted onboarding ### Fixed We fixed the issue where a signatory's email address and phone number did not always appear under their personal details. It is no longer required to enter these details more than once. ## 2023-04-17 — Hosted onboarding ### Improved The hosted onboarding page now shows a warning banner when any of the roles required for the KYC process are missing. The banner specifies the missing role(s). ## 2023-02-06 — Hosted onboarding ### Improved When adding or updating shareholder information on the hosted onboarding page, the triggered [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification now includes the [`shareholderType`](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED#request-content-accountHolderDetails-businessDetails-shareholders-shareholderType) field for each shareholder. If a shareholder has multiple roles, for example, **Owner** and **Controller**, the [`shareholderCode`](https://docs.adyen.com/api-explorer/Notification/6/post/ACCOUNT_HOLDER_UPDATED#request-content-accountHolderDetails-legalArrangements-legalArrangementEntities-businessDetails-shareholders-shareholderCode) will be the same for the different `shareholderType`. ## 2023-02-06 — Hosted onboarding ### Fixed We fixed the issue where deleting shareholders on HOP did not completely remove the resource from your account holders' profile. ## 2023-01-30 — Hosted onboarding ### Improved When adding a Swedish bank account, account holders can now also enter 5-digit branch codes (clearing numbers). ## 2023-01-09 — General ### Removed Because EUR is now the only official currency in Croatia, Adyen no longer supports bank accounts in HRK. ## 2023-01-09 — Hosted onboarding ### Changed Account holders residing in the US now need to provide their entire SSN or TIN (9 digits) on the hosted onboarding page. ## 2023-01-09 — API ### Improved You can now use the [/deleteShareholders](https://docs.adyen.com/api-explorer/Account/latest/post/deleteShareholders) endpoint to delete shareholders with multiple shareholder types. ## 2022-12-12 — Hosted onboarding ### New * Your account holder's bank information using Tink as a third-party service. * When your account holder uploads a supporting document on HOP, its status now changes to **Processing** instead of **Finished** until it is verified. ## 2022-12-12 — KYC ### Fixed When adding a Swedish bank account, your account holders are now required to enter the account number instead of the IBAN to avoid possible issues with payouts. ## 2022-11-14 — Hosted onboarding ### Improved Your account holders can now assign multiple shareholder types to the same individual on the Hosted Onboarding Page. ## 2022-10-31 — Hosted onboarding ### Changed It is now possible to enter a 5-digit branch code for Swedish bank accounts on the **Bank details** page on HOP. ## 2022-10-10 — Hosted onboarding ### Fixed Your account holders can now update the **BIC/SWIFT code** on HOP. ## 2022-10-10 — API ### Changed We increased the maximum character length in the [description](https://docs.adyen.com/api-explorer/#/Fund/latest/post/payoutAccountHolder#request-description) field of the POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request to 200 characters. ## 2022-10-03 — Hosted onboarding ### Improved The **BIC/SWIFT code** field is only required for Canadian bank accounts if the configured currency is not **CAD (C$)**. ## 2022-09-12 — Customer Area ### Improved The **PSP reference** is now also shown for refunds in the **Transfer detail** section. ## 2022-09-05 — Hosted onboarding ### Fixed We fixed the issue with validating the company phone number after it was edited on HOP. ## 2022-09-05 — Reports ### Fixed We fixed the issue with generating the [Settlement details report](/reporting/settlement-reconciliation/transaction-level/settlement-details-report) in the test environment of your [Customer Area](https://ca-test.adyen.com/). ## 2022-08-29 — Hosted onboarding ### Fixed Account holders can now enter 10-digit bank account numbers in New Zealand. ## 2022-08-22 — Hosted onboarding ### Fixed To enable payouts, HOP now request information on the correct business owner type. Previously, it requested information on a controller instead of a signatory. ### New When prodiving their bank account details, your account holders can now choose between the following options: * Instant verification by a third-party service * Verification by Adyen, where they need to manually enter their bank details and upload supporting documents ## 2022-08-01 — General ### New The upgraded Adyen for Platforms infrastructure's [documentation](/adyen-for-platforms-model) is now available for new integrations. If you have already integrated with our system, refer to the [classic integration guide](/classic-platforms). ## 2022-07-25 — Hosted onboarding ### Improved In the **Business owners** section, account holders will now see the specific role (**Owner**, **Signatory**, or **Controller**) of the individuals whose information is required for verification. ### New Account holders can now delete legal arrangements directly on HOP. ## 2022-07-25 — KYC ### Fixed Account holders are no longer required to provide a tax ID number for their business in the Czech Republic and Slovakia. ## 2022-07-25 — Customer Area ### New You can now suspend account holders on the **Overview** tab, next to **Account Holder Operations**. ## 2022-07-18 — Hosted onboarding ### Fixed * When adding a publicly listed parent company, the dropdown for selecting a **Stock exchange** is now working again. * When an ultimate beneficial owner was created without a role (owner, controller, or signatory), the **ID document** button is no longer shown. The account holder must provide data first before they can upload a document. * Account holders can now add signatories who have addresses in China. * Fixed the incorrect error message shown for invalid Singapore ID numbers. ## 2022-07-18 — API ### Fixed * When adding signatories, sending an empty string in the [signatoryCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-signatories-signatoryCode) now works as expected. The API no longer returns an error and the signatory is created. ## 2022-07-11 — Hosted onboarding ### Fixed We added the missing input fields for entering a legal arrangement member's personal details on HOP. ## 2022-07-04 — Customer Area ### Fixed The link to the target account in case of split payments now works as expected. Previously, the link in **Transactions** > **Payments** > **Payment details** > **Payments** > **Target account** pointed to the first account of the associated account holder. ## 2022-07-04 — Hosted onboarding ### Fixed * We fixed the issue where a 12 hour or more timezone difference between the account holder's system and an individual's place of birth altered their date of birth. * When onboarding a public company, not all required information was requested in the **Company details** section. Your account holders must now provide data in one of the following fields: * **Stock exchange** * **Stock ticker** ### New If your platform is already configured to implement the [new verification requirements](/classic-platforms/verification-process/requirements-update), we now require your account holders to provide the type of the shareholders associated with their business. ## 2022-07-04 — General ### Improved If you have set a [payout descriptor](/classic-platforms/payouts/scheduled-payout#scheduled-payout-descriptors) but its value is empty, the payout description now falls back to the default value (your platform's name). ## 2022-06-27 — Customer Area ### Fixed * The **Merchant reference** that you provide when [paying out manually from the Customer Area](/classic-platforms/payouts/manual-payout?tab=manual-payout-ca_2) is now shown in the **Transactions** list when you look up the payout. * When your account holder updates their bank account, the new account is now also shown in the **KYC** > **Summary** section and the **Payouts** tab. Previously, the change was only reflected in the **KYC** > **Timeline** section. ## 2022-06-27 — Hosted onboarding ### Fixed * Account holders that have bank accounts outside of the country they are operating in can now also select [local currencies](/classic-platforms/payouts#supported-currencies). For example, an account holder in DK that adds an NO bank can now choose between EUR and NOK currencies. * When entering a Swedish account number, the bank details form now only shows **Branch code**. Previously, it also showed that account holders can add the **BIC/SWIFT** which is different from the branch or clearing code. * Fixed broken icons. ## 2022-06-20 — Customer Area ### New For sub-merchants that have legal arrangements and parent companies, you can now view the following in the **Company** and **Legal Arrangement** verification checks on the **KYC** tab: * `legalArrangementCode` * `legalArrangementEntityCode` * `ultimateParentCompanyCode` ## 2022-06-13 — Hosted onboarding ### New You can now require account holders to upload their IDs and bank statements upfront instead of only requiring documents when the automatic verification fails. To enable this feature for your platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2022-06-06 — Customer Area ### Fixed The PSP references of transactions that are not related to payments, such as transfers, are no longer incorrectly linked to the **Payment details** page. ## 2022-06-06 — Hosted onboarding ### Improved Account holders can now provide a company registration number consisting of a maximum of 10 digits. ## 2022-05-31 — Customer Area ### Improved Timezones are now included whenever dates are shown in your [Customer Area](https://ca-test.adyen.com/). For example, when you select the **KYC** tab for a sub-merchant, you will now see the date and timezone of when Adyen performed the checks. ## 2022-05-23 — API ### Improved When providing an [accountHolderDetails.webAddress](https://docs.adyen.com/api-explorer/Account/6/post/createAccountHolder#request-accountHolderDetails-webAddress), you must now provide a URL with the following format: a protocol (`http://` or `https://`), a domain, and a maximum 1024 characters. Otherwise, the request fails. ## 2022-05-23 — Hosted onboarding ### Fixed * HOP now collects the shareholder's ID number even when the account holder's and shareholder's countries are different. * When changing the legal entity type from individual to business, account holders are now prompted to provide the address or Employer Identification Number (EIN) of the organization. Previously, when an individual legal entity was created without an address then later changed to an organization, the verification check required for payouts failed due to the lack of address. ## 2022-05-17 — General ### New By default, [daily payout schedules](/classic-platforms/payouts/scheduled-payout#default-schedule) are now optimized for local timezones based on the account holder's country code. For example, funds for an account holder in Australia gets paid out at 19:50:00 CET. The account holder's local timezone schedule overrides the default schedule of your platform. This feature is enabled for new integrations. If you want this feature for your existing integration, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2022-05-17 — Customer Area ### Fixed When you view the details of a split payment and select the **Target Account**, the sub-merchant transaction page that you're redirected to now shows the account holder code. ## 2022-05-17 — Hosted onboarding ### Fixed Account holders with a NOK bank account can now provide the **BIC/SWIFT code** on the **Bank details** page. The code is required for payouts. ### Improved For Australian businesses, we improved the UI for collecting the Australian Company Number (ACN) and Australian Business Number (ABN) to make it clear which number the account holder needs to provide. ## 2022-05-17 — API ### Improved When making a POST [/uploadDocument](https://docs.adyen.com/api-explorer/Account/6/post/uploadDocument) request with a `documentType` set to **SUPPORTING\_DOCUMENTS**, you can now send multiple documents without overwriting your previous uploads. You can use this type for documents related to shareholders and organizational charts. All other document types, such as passports and bank statements, still follow the default behavior: previous uploads are overwritten if you send an API request with the same type. ## 2022-05-09 — API ### Improved When making an instant card payout with a POST [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request, the value that you send in the [description](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder#request-description) field now appears on the sub-merchant's bank statement. ## 2022-04-11 — Hosted onboarding ### Changed Your account holders must provide their full address before adding their bank details. ### New Your account holders can now delete bank accounts even if there is only one bank account saved. ## 2022-04-11 — Reports ### New Payment Merchant Reference, Capture Psp Reference, and Capture Merchant Reference are now also retrieved for chargebacks in the [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report). ## 2022-04-04 — Reports ### Fixed When manually generating a Marketplace Hourly Payment Accounting Report, you now get a report that matches the time range in UTC. ## 2022-03-28 — API ### Fixed * When filtering for the **Payout** status in a POST [/accountHolderTransactionList](https://docs.adyen.com/api-explorer/Fund/latest/post/accountHolderTransactionList) request, the response now returns payouts to cards. * Fixed validation issues for postal codes in the [accountHolderDetails.storeDetails](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails) array. ## 2022-03-28 — General ### Improved For [platforms that are liable for chargebacks](/classic-platforms/processing-payments#chargeback-and-disputes), the full amount of chargebacks or chargeback reversals can now be booked entirely from your liable account regardless of the split. To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2022-03-28 — Customer Area ### Fixed When using the filters in the **Transactions** page, payouts to cards are now shown in the list. ## 2022-03-28 — Hosted onboarding ### Fixed * HOP now first checks if the shareholder type was already provided before showing the message to upload a document. * When using instant bank verification, the **Start** button is now shown only at the beginning of the process. * The feature for limiting account holders to provide only one bank account is again working as expected. To enable this for your platform, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2022-03-21 — Hosted onboarding ### Fixed It is now possible for Finnish account holders to enter Swedish bank account details on HOP. ### New When providing details for instant bank account verification, your account holders can now select banks from Denmark. ## 2022-03-14 — Hosted onboarding ### Fixed * Account holders can now update the bank name in the page for manual bank verification. * Account holders that are required to fill out the PCI DSS questionnaire can now do so even if they do not have a web address. ## 2022-03-14 — Reports ### Improved If you pay out to bank accounts in California, your Marketplace Payments accounting reports will now have a smaller file size. This is because Adyen no longer needs to include the "Right To Refund" text so we removed the text under the **Refund terms** column. ## 2022-03-07 — General ### Fixed We fixed the issue where shareholders could be created with the same name and shareholder type. It is no longer possible to create duplicate shareholders. ## 2022-03-07 — Hosted onboarding ### Fixed * HOP now shows a descriptive error message advising further action when your account holder attempts to change a legal entity type while stores are in active or pending status * We added a new **Singapore ID number** field that must be filled for Singaporean citizens or residents to enable upfront verification. Previously, the ID number was still required, but there was no field for it, which resulted in errors during validation. ## 2022-02-28 — Customer Area ### Improved If there are missing information required for verification or the account holder provided invalid data, the actions that you need to take are now highlighted in the sub-merchant **Overview** tab. ## 2022-02-28 — Hosted onboarding ### New New [supported language](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience#change-page-language): Slovakian. ### Fixed * Account holders can now update a phone number after it is verified. Previously, the leading **+** was omitted when saving and this caused validation errors. * If an ID number is required in the country of the shareholder but not in the country of the business, HOP was unable to collect the required information. We fixed this so that now HOP shows the section to upload a document for the shareholder. ### Improved * Account holders can now upload legal arrangement documents up to 25MB in size. * It is now possible to upload images with a minimum size of 1KB. ## 2022-02-28 — API ### Fixed When uploading a document for a business account holder that has a `shareholderReference` field, the field is now always returned in the POST `/uploadDocument` response. Previously the field was sometimes not returned. ## 2022-02-21 — Reports ### Fixed Card payouts now show the correct bookings in the [Marketplace payment accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report). Previously, the bookings were incorrectly duplicated as both credit and debit. ## 2022-02-21 — Hosted onboarding ### Improved * We improved the accessibility of HOP to be fully compliant with WCAG 2.1 requirements. * When adding the same shareholder with different roles in separate instances, we will merge the entities only when they have the same KYC status. For example, if an individual has **Signatory** role in one instance, and **Controller** in another, they are shown as separate entities until they reach the same KYC status. Previously, the shareholder entries were merged by default and the lowest KYC status was shown. ### Fixed The PCI verification check is now automatically triggered when the data is entered through HOP. Previously, if the PCI questionnaire was the last to be filled out on the page, the verification process was not triggered and the PCI check showed as **Awaiting data** in the Customer Area. ## 2022-02-21 — Customer Area ### New * We introduced the new **Data provided** status on the **KYC** tab for checks that have not passed yet, but the data was already provided for them. Previously, they were marked as **Awaiting data**. * You can now see the shareholder name, as well as their code, in the **Status** column for the checks on the **KYC** tab. If you configured your account to mask sensitive data, the names will be masked on this page as well. ## 2022-02-21 — API ### Deprecated The [ownerDateOfBirth](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-bankAccountDetails-ownerDateOfBirth) field is deprecated. If your integration still uses this field, make sure to send the values in a **yyyy-mm-dd** format to avoid validation errors. For example, **2000-01-31**. ## 2022-02-14 — Hosted onboarding ### Fixed HOP now collects ID numbers for individuals with a Singaporean nationality. Previously, HOP showed the ID number as required but did not have the corresponding field to collect the data. ### Improved When an account holder is required to upload a document, HOP now shows a button on the overview page that will take them to the upload document section. ## 2022-02-07 — Classic Platforms ### Fixed When you suspend an account holder, their payouts are blocked. However, the corresponding [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_STATUS_CHANGE) notification didn't reflect this payout status. We fixed this so now you'll see [accountHolderStatus.payoutState.allowPayout](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED#request-content-accountHolderStatus-payoutState-allowPayout) is set to **false**. ## 2022-02-07 — KYC ### Fixed We now support new area codes for US telephone numbers. Previously, the API and the hosted onboarding page returned errors for valid area codes such as 689. ### Improved We improved the validation process of phone numbers to automatically fix incorrect but "fixable" numbers. For example, if an international number starts with **0** that is only relevant for local numbers, we remove it and store only the correct international version. ## 2022-02-07 — API ### Fixed * The validation on the [name.infix](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-individualDetails-name-infix) field is now working as expected. The value must: * Have a maximum length of 20 characters. * Not contain numbers. * Not contain the following special characters: :;}{$#@!|<>%^\*+=�\\ * When creating an account holder and the Unicode character `\u0000` is included in the [legalBusinessName](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-legalBusinessName) field, this causes issues later on in the verification process. To avoid these issues, we now check this character and return an error message in the API response. * When you suspend an account holder, their payouts are blocked. However, when you make a [/getAccountHolder](https://docs.adyen.com/api-explorer/#/Account/getAccountHolder) request, the payout status was not reflected. We fixed this so now the [accountHolderStatus.payoutState.allowPayout](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder#responses-200-accountHolderStatus-payoutState-allowPayout) is set to **false**. ## 2022-01-31 — Hosted onboarding ### Improved To ensure that the documents uploaded by account holders are fully processed before moving on to the next step, HOP now redirects them to the main overview page after 10 seconds. On the overview page, they will see the status of the document upload. ## 2022-01-24 — Hosted onboarding ### Improved When more than one currency is supported in a country, HOP now shows the local currency first in the **Bank details** page. For example, when providing a GB bank account, GBP is shown before EUR. ## 2022-01-17 — API — Version 6 ### Fixed When sending the [/getAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder) request, the [`verification.accountHolder.checks.type`](https://docs.adyen.com/api-explorer/#/Account/latest/post/getAccountHolder__resParam_verification-accountHolder-checks-type) now returns the expected **PAYOUT\_METHOD\_VERIFICATION** value instead of the previous **BANK\_ACCOUNT\_VERIFICATION**. ## 2022-01-17 — Hosted onboarding ### Improved When submitting the personal details of ultimate beneficial owners on HOP, account holders can now select any country when providing their nationality. ## 2022-01-17 — API — Version 4 ### Fixed When providing an ID of a [signatory](https://docs.adyen.com/api-explorer/Account/4/post/createAccountHolder#request-accountHolderDetails-businessDetails-signatories), the [personalData.documentData.number](https://docs.adyen.com/api-explorer/Account/4/post/createAccountHolder#request-accountHolderDetails-businessDetails-signatories-personalData-documentData-number) is now returned in the response of the POST [/createAccountHolder](https://docs.adyen.com/api-explorer/Account/4/post/createAccountHolder) request. ## 2022-01-11 — KYC ### Improved Account holders operating in Guernsey and Jersey can now be onboarded with their GB bank accounts. This change also applies to account holders operating in the UK—they can now be onboarded with their GG and JE bank accounts. ## 2022-01-11 — General ### Improved When you [top up accounts](/classic-platforms/top-up-accounts) with the [/debitAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder) endpoint, we now send the name of your Adyen company account to the account holder's bank. This is shown in their bank statement. ### Fixed When creating liable accounts, the accounts now follow your platform's default payout schedule. Previously, the payout schedule was always set to daily. ## 2022-01-11 — Hosted onboarding ### New New [supported language](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience#change-page-language): Croatian. ### Fixed Account holders can now add USD as a [payout currency](/classic-platforms/payouts#supported-currencies) for Canadian bank accounts. ### Improved * Account holders can now see updated verification check statuses within the same HOP session. Previously, you had to get a new HOP URL to get the updates. * Account holders operating in Cyprus can now provide postal codes with 5 digits. * Account holders can now add an additional business address for a different country than the already provided address. ## 2022-01-11 — Customer Area ### Fixed You can now download the back side of an identification document from the **Documents** tab of an account holder in your Customer Area. Previously, the front image was downloaded instead. ## 2022-01-10 — Reports ### New We introduced a new `ReCredited` journal type to indicate the settlement of the reversal of a reversed credit. ## 2021-12-13 — Reports ### New It is now possible to mask all but the last four characters of the bank account numbers and IBANs in Adyen for Platforms reports. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this feature for your platform. ## 2021-12-13 — General ### New You can now request our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to set the `pspReference` of the payout as the [payout descriptor](/classic-platforms/payouts/scheduled-payout#scheduled-payout-descriptors) in your platform. This reference is included in your account holders' bank statements, and you can use it to link a payout to the corresponding report. ## 2021-12-13 — Hosted onboarding ### New Your account holders can now select multiple roles for an individiual when providing their information in the **Personal details** section on HOP. ## 2021-12-13 — Hosted onboarding ### Improved Account holders can now provide bank account numbers up to 19 digits in length. ## 2021-12-06 — API ### Fixed * We fixed an issue where updating a [storeDetails](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails) array would fail if the store doesn't have a [fullPhoneNumber](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-fullPhoneNumber). ### New You now pay out an account's the full balance to the account holder without specifying the exact amount. When sending the [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) request, you only need to provide the following parameters: * `accountCode` * `accountHolderCode` * `amount.currency` (if there are multiple currencies to pay out) ## 2021-12-06 — Hosted onboarding ### New * You can now use HOP to onboard account holders operating in New Zealand. * When providing information about controllers, the **Email address** and **Phone number** are now required. ### Fixed We fixed an issue where account holders with a business legal entity type cannot provide bank account details on HOP if they didn't provide their complete company address. ## 2021-12-02 — Customer Area ### Fixed The **Merchant reference** provided when transferring funds through the Customer Area is now shown in the **Transactions** tab of the selected sub-merchant. ### New It is now possible to mask all but the last four characters of the bank account numbers and IBANs in the Customer Area. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this feature for your platform. ## 2021-12-02 — Hosted onboarding ### Improved It is now possible to change the legal entity type in the **Business details** (for businesses, non-profits, public companies, and partnerships) or **Personal details** (for individuals) section of the HOP. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this feature for your platform. ### Fixed We fixed issues with [uploading a logo](/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance#add-name-logo) to HOP. ### New * Account holders can now remove a previously added parent company through HOP. Once a parent company is deleted, all related verification checks will be removed as well. * You can now redirect account holders directly to the bank account page where they get the verification results instantly. To do this, send the following new fields in your POST [/getOnboardingUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl) request: * [checksOverviewPage](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-showPages-checksOverviewPage): set to **false** to skip the overview page. * [bankVerificationPage](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-showPages-bankVerificationPage): set to **true**. ```json { "showPages": { "checksOverviewPage": false, "bankVerificationPage": true } } ``` ## 2021-11-15 — Hosted onboarding ### New You can now limit new account holders to add only a single bank account. Once this feature is enabled, those that already have multiple accounts can still view and update their bank details, but they will not be able to add new accounts. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this feature for your platform. ### Fixed Account holders can now change the role (owner, controller, or signatory) of individuals associated with an organization in the **Role** dropdown menu of the **Personal details** page. ## 2021-11-15 — API ### New You can now delete an existing `listedUltimateParentCompany` object by sending an [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder) request and setting the value of the object to **null**. ```json { "accountHolderCode": "ACCOUNT_HOLDER_CODE", "listedUltimateParentCompany": null } ``` ## 2021-11-01 — Customer Area ### Fixed Previously, the Customer Area would still show a schedule even when scheduled payouts are disabled for your whole platform. If this is the case for your platform, you'll now find **HOLD** as the payout schedule. ## 2021-11-01 — Hosted onboarding ### Fixed We fixed issues where some words were not translated to the selected languange. ## 2021-10-28 — Hosted onboarding ### New The **Job title** is now a required field when providing information about controllers and signatories. ## 2021-10-25 — API ### New You can now delete an existing `principalBusinessAddress` object by sending an [/updateAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder) request and setting the value of the object to **null**. ```json { "accountHolderCode": "ACCOUNT_HOLDER_CODE", "principalBusinessAddress": null, ... } ``` ## 2021-10-25 — Hosted onboarding ### Improved The instant bank verification flow is now part of the page itself. Account holders can now verify their banking information within the page instead of in a pop-up window. ## 2021-10-25 — Classic Platforms ### Improved You will now receive the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification with `statusCode` **Confirmed** if the card payout is processed successfully, and **Failed** if the payout fails. ## 2021-10-18 — Hosted onboarding ### Fixed In the header, clicking on the **FAQs** or the **Contact** links is working as expected again. ## 2021-10-18 — API ### Fixed When the `phoneNumber` object is missing required fields, the API now returns an error. Previously, the API accepted the request but the account holder setup failed at a later time. ## 2021-10-11 — API ### Improved * When providing information for the `listedUltimateParentCompany` object, now you only need to send the `address.country` parameter instead of the whole address. * We made the `houseNumberOrName` field optional, because in some countries, building and house numbers are already included in the street address. You can now include the building or house numbers in the `street` field. ## 2021-10-05 — General ### New You can now onboard sub-merchants operating in New Zealand. ## 2021-10-05 — Hosted onboarding ### Improved * We increased the size of logos shown on onboarding pages that do not have a [header](/classic-platforms/onboard-users/hosted-onboarding-page/hop-appearance#customize-HOP-appearance). Previously, the logos were less noticeable because they were smaller. * To make providing addresses more intuitive for account holders, they can now include their house or building number in the **Street** field. The **House/unit number** field is now optional. ## 2021-09-27 — Customer Area ### Improved We created a new user role specifically for downloading payout letters in [Customer Area](https://ca-test.adyen.com/). Until now, you had to assign the extensive **Merchant Extended MarketPlace role** to users to permit Customer Area users to download the payout letter containing the bank transfer details. To avoid having to give users more access to your platform than necessary, you can assign the **Allow the user to download the payout confirmation letter** role. ## 2021-09-27 — General ### Improved We improved how we handle funds when an account holder's status changes to suspended or closed. * Existing funds * Old: Existing funds were refunded by default. * New: The default handling is the same as before, but now you can contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to automatically transfer the funds to your liable account instead of refunding. * New payments (if payments for an already suspended or closed account holder were processed) * Old: The payments were automatically refunded by default. * New: The default handling is the same as before, but now you can contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to automatically transfer the funds to your liable account instead of refunding. * Chargebacks and refunds * Old: Refunds and chargebacks were deducted from a suspended or closed account holder's account by default. * New: Refunds and chargebacks are deducted from your liable account by default. These changes do not affect payouts. Only active account holders are allowed to get payouts. ## 2021-09-27 — API ### New We added the new `payoutMethodReference` parameter to the [Account API](https://docs.adyen.com/api-explorer/#/Account/overview). In this field you can provide your own reference to the `payoutMethod`, which allows easier mapping to the `payoutMethodCode`. ## 2021-09-13 — Hosted onboarding ### Improved Customer Area users that have a **Manage HOP settings** user role can now [access HOP on behalf of an account holder](/classic-platforms/onboard-users/hosted-onboarding-page#access-hop-from-customer-area) by default. Previously, this feature had to be requested and enabled for each platform. ## 2021-09-06 — Customer Area ### Fixed When the **Unsuspend Account Holder** button is not available and you hover over it, we used to always show this tooltip: *The account holder has been permanently suspended due to FAILED KYC verification check(s)*. We fixed this so now you only see this tooltip when one of the KYC checks failed. You will no longer see this when the account holder has been suspended because they sent invalid data or they are still awaiting KYC checks. ## 2021-09-06 — KYC ### Changed When onboarding account holders that are part of [legal arrangements](/classic-platforms/verification-process/legal-arrangements), you now only need to collect and upload a document if: * The account holder is part of a trust in Australia. * The automatic verification failed and Adyen required the account holder to provide a document. Previously, uploading a document was required for all legal arrangement types. ## 2021-08-30 — Hosted onboarding ### New We now support the following languages on HOP: * Czech * Hungarian * Romanian For instructions on how to render HOP in your preferred language, refer to [Change the page language](/classic-platforms/onboard-users/hosted-onboarding-page/customize-experience#change-page-language). ## 2021-07-26 — API ### New * Added the [listedUltimateParentCompany](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-listedUltimateParentCompany) array in all API version. You can now use this array to send information about account holders' parent companies. Previously this was only available in v6. ## 2021-07-05 — API — Version 6 ### New * Added the [listedUltimateParentCompany](https://docs.adyen.com/api-explorer/Account/6/post/createAccountHolder#request-accountHolderDetails-businessDetails-listedUltimateParentCompany) array, which you can use to send information about account holders' parent companies. ## 2021-05-31 — Hosted onboarding ### New * Added the [showPages](https://docs.adyen.com/api-explorer/Hop/6/post/getOnboardingUrl#request-showPages) object, which contains booleans. You can use these booleans to indicate whether HOP should show summary pages to account holders. ## 2021-05-17 — API ### New * Added the [/deleteSignatories](https://docs.adyen.com/api-explorer/Account/6/post/deleteSignatories) endpoint, which you can use to delete one or more signatories from an account holder. ## 2021-05-10 — API — Version 6 ### New * Added the [legalArrangements](https://docs.adyen.com/api-explorer/Account/6/post/createAccountHolder) array, which contains information such as the registration number and entities involved in the legal arrangement. You must send this when onboarding account holders involved in [legal arrangements](/classic-platforms/verification-process/legal-arrangements). ## 2021-05-10 — API ### New * Added the [/debitAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder) endpoint. You can use this endpoint to let account holders [top up their accounts](/classic-platforms/top-up-accounts). ## 2021-05-03 — General ### New * You can now onboard account holders operating in Singapore and more countries within the EU. See [Supported countries](/classic-platforms#supported-countries). ## 2021-04-19 — Hosted onboarding ### New * Added the [collectInformation](https://docs.adyen.com/api-explorer/Hop/latest/post/getOnboardingUrl#request-collectInformation) object, which contains booleans. You can use these booleans to indicate whether HOP should only collect information for specific KYC checks. ## 2021-02-15 — API ### Fixed When [splitting payments](/classic-platforms/processing-payments) for local payment methods such as iDEAL, the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint now returns a validation error if the sum of split amounts is not equal to the payment amount. The endpoint previously accepted these requests and this caused an issue in settling funds. ## 2021-02-08 — API ### New * We introduced a [jobTitle](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-shareholders-jobTitle) field in the shareholder object. If the [shareholderType](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-businessDetails-shareholders-shareholderType) is **Controller**, then `jobTitle` is required. * You can now use the [/getPciQuestionnaireUrl](https://docs.adyen.com/api-explorer/Hop/latest/post/getPciQuestionnaireUrl) endpoint for individual and nonprofit legal entity types. ## 2021-02-08 — Hosted onboarding ### New You can now use HOP to onboard account holders operating in Latvia. ## 2021-01-27 — Customer Area ### New In the overview of account holders in your [Customer Area](https://ca-test.adyen.com/), you can now search by PSP reference. ## 2021-01-27 — General ### Improved After a payout is unblocked, we restore the payout schedule for the account holder. In case the account holder has multiple accounts, we restore all payout schedules. ## 2021-01-13 — General ### Improved When adding an account to the split instructions, we now check whether the store and the account have the same account holder. This prevents split payments going to an unrelated account holder. ## 2021-01-13 — Reports ### Improved We extended the Marketplace Hourly Payments Accounting Report with more chargeback details. Partial chargebacks entries with a `ChargebackReversed` record type now include information in the **Payment Psp Reference** and **Payment Merchant Reference** columns. ### Fixed We now make sure that the `ChargebackReversed` correction is applied to all splits for your platform and account holders. ## 2021-01-06 — KYC ### Improved We now collect the *Principal place of business* address when this differs from the *Registered* address for the following legal entity types: **Business**, **NonProfit**, **PublicCompany**, and **Partnership**. To send this address, include the [principalBusinessAddress](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-principalBusinessAddress) object when creating or updating the account holder. ## 2020-11-25 — Hosted onboarding ### Improved The bank statements page now allows uploading a bank statement for solo-traders or freelancers who have their bank accounts under their business name. This prevents KYC checks failing because of the mismatch between their bank statement and the individual details that they provide. ## 2020-11-25 — General ### Improved We can enable a feature which ignores the pending balance from the calculation of the payout to account holders. ## 2020-11-11 — API ### Improved When creating a store with a [shopperInteraction](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-shopperInteraction) **Ecommerce**, you no longer need to provide the [fullPhoneNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-fullPhoneNumber) and [webAddress](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-storeDetails-webAddress). Instead, we'll take this data from the account holder. ## 2020-10-28 — General ### Fixed We now only create scheduled payouts on bank days. Previously, we allowed creating scheduled payouts every day, which sometimes resulted in two payouts in one day. ## 2020-10-21 — API ### Improved We now allow point-of-sale stores to make changes to `storeReference`, `storeFullPhoneNumber` and `address`. ### Fixed There are no more duplicate API keys (in test or live) saved for marketplace web service users. ## 2020-09-21 — API ### Fixed * Setting `payoutSchedule` to **DEFAULT** now works in a [/createAccount](https://docs.adyen.com/api-explorer/#/Account/createAccount) call. Previously it was throwing an exception, preventing the account to be created. * Previously when a payout request times out due to KYC not being available, we showed **Internal Error** and **Invalid Input** errors. The response now only shows **Internal Error**. ### Improved We improved the description for [verification error code](/classic-platforms/verification-process/verification-codes#company-verification) `2130` for [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder). Instead of **Invalid data**, the new description now says that the business registration, company name, or shareholder data is incorrect or can't be verified. ## 2020-09-21 — Classic Platforms ### Improved If a payout fails due to insufficient funds in the liable account, you now receive this information in the description within the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification. Previously the description was **Internal error**. ## 2020-08-31 — Hosted onboarding ### Improved * On HOP, we now specify that a bank cheque is only supported in specific regions. We added this to inform sellers to avoid uploading bank cheques as a valid proof of bank requirements when not supported for their region. * We specified on HOP that the name should be the same as the first and last name shown on their identification document to avoid KYC failures. ## 2020-08-17 — Classic Platforms ### New We can now send notifications if the funds on the liable account hit a certain threshold. To receive the notification, subscribe to the [ACCOUNT\_FUNDS\_BELOW\_THRESHOLD](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_FUNDS_BELOW_THRESHOLD) notification. ## 2020-08-17 — KYC ### New We added front end validations on all missing or wrong fields for the payment method creation. ## 2020-08-08 — Hosted onboarding ### Improved HOP now renders the seller summary page and allows the account holder to edit their personal details any time the identity verification fails. ## 2020-08-05 — API — Version 6 ### New * Stores can now be updated through the [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) endpoint, by including the `store` field in the request. * You can now use the **Partnership** legal entity for Partnerships, for example, German GbR entities. A **Partnership** is similar to the **Business** legal entity except that a `registrationNumber` is optional for a Partnership. It is available only for Germany and the United Kingdom. ### Changed We renamed `verification.bankAccounts` to `verification.payoutMethods` and `verification.bankAccounts.bankAccountUUID` to `verification.payoutMethods.payoutMethodCode` in the response of the [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder), [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder), [/getAccountHolder](https://docs.adyen.com/api-explorer/#/Account/getAccountHolder), and [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) endpoints. ## 2020-08-05 — Classic Platforms — Version 6 ### New * When a sub-merchant payout is returned, we now send the return reason in the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_PAYOUT) notification. | Error code | Message | | ---------- | ---------------------- | | 10\_132 | Invalid Account Number | | 10\_133 | Invalid Routing Number | | 10\_134 | No Account | | 10\_135 | Account Closed | * We added new fields to the content of the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_PAYOUT) webhook with status **Confirmed**, containing information on the payout you can send to the sub-merchant to provide more details and help with troubleshooting. | Parameter | Description | | ---------------------- | ------------------------------------------------------------------ | | `payoutReference` | The unique payout id. | | `payoutAccountNumber` | The account number of the bank from which the payout is initiated. | | `payoutBranchCode` | The branch code of the bank from which the payout is initiated. | | `payoutAccountCountry` | The country code of the bank from which the payout is initiated. | | `payoutBankName` | The name of the bank the payout is made from. | ### Changed * In the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_CREATED) and [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_UPDATED) notifications, we renamed the following: * `verification.bankAccounts`to `verification.payoutMethods` * `verification.bankAccounts.bankAccountUUID` to `verification.payoutMethods.payoutMethodCode` * In the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification, we have renamed `content.bankAccountUUID` to `content.payoutMethodCode`. ### Removed * We removed the `content.pspReference` field from the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_CREATED), [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_UPDATED), [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_CREATED), [ACCOUNT\_UPDATED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_UPDATED) and [ACCOUNT\_CLOSED](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_CLOSED) notifications. Use the root-level `pspReference` field instead. * We removed `content.amount` from the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_PAYOUT) notification. Use the `content.amounts` array instead. ## 2020-08-05 — API ### New You can now have multiple onboarding approaches for your sub-merchants, so one sub-merchant can go through an upfront verification and another with a staggered approach. To set the onboarding approach, include the [verificationProfile](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-verificationProfile) in the [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) and [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) requests. ## 2020-07-27 — Customer Area ### New We renamed **MarketPay** to **Adyen For Platforms** in the Adyen [Customer Area](https://ca-live.adyen.com/). ## 2020-07-27 — Classic Platforms ### Improved * If creating the account holder fails, the `accountHolderCode` is now included in the [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) notifications. * If you have not specified a schedule in the [/createAccount](https://docs.adyen.com/api-explorer/#/Account/createAccount) request, the `payoutSchedule` field in the [ACCOUNT\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_CREATED) notification is now populated with the set default payout schedule instead of `null`. ## 2020-07-20 — Classic Platforms ### Improved If the payout has been blocked by Adyen, the message will now specify that the payout has been blocked by Adyen to make it clear that it was not intentionally blocked by the merchant. ## 2020-07-06 — Hosted onboarding ### New You can now add a **Support** button on your page to redirect the account holder to your support page. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to have this enabled. ## 2020-07-06 — API ### New We added two new fields which are required when `legalEntity` is **publicCompany**: * `stockExchange` * `stockNumber` ## 2020-06-29 — Classic Platforms ### New We added the `returnReason` for a failed payout in the Adyen [Customer Area](https://ca-live.adyen.com/). You can find this under the **Transactions** list per account holder. We have also added the return reason to the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/ACCOUNT_HOLDER_PAYOUT) notification. ## 2020-05-26 — Classic Platforms ### Fixed We fixed an issue where express payout attempts did not work, even though you received a successful [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_PAYOUT) notification. ## 2020-05-26 — General ### New * If an account holder adds a bank account that is already being used by another account holder, they are now pushed to the highest tier. * We now allow the shareholder country to be different from the country of the business entity. ## 2019-11-04 — API ### Fixed Corrected the mapping of [verification codes](/classic-platforms/verification-process/verification-codes). Code `1161` will be used for [photo ID verification](/classic-platforms/verification-process/document-requirements#upload-photo-id), and code `3163` will be used for [bank account verification](/classic-platforms/verification-process/document-requirements#bank-statements). ## 2019-10-29 — General ### Improved You can now transfer funds between accounts that belong to the same account holder, regardless of the account holder's [payout status](/classic-platforms/verification-process#account-holder-statuses). ## 2019-10-21 — Reports ### Improved Partial captures that do not have split instructions are now credited to the liable account with the description "Payment with empty split data". ## 2019-10-14 — Classic Platforms ### Fixed The [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification now includes `bankAccountReference` if removing Personal Identifiable Information (PII) data is enabled for your platform. ## 2019-10-14 — API ### Fixed Fixed an issue where **PASSPORT\_VERIFICATION** checks were set to **AWAITING\_DATA** instead of **INVALID\_DATA**. ## 2019-10-07 — Customer Area ### Fixed The filters used in the [Customer Area](https://ca-test.adyen.com/) to view a list of account holder now also applies to the downloaded report. ## 2019-09-30 — API ### Improved The [/getAccountHolder](https://docs.adyen.com/api-explorer/Account/5/post/getAccountHolder) response now returns all verification statuses. In versions before v5, the response only contains the required and passed checks. ## 2019-09-16 — Classic Platforms ### Improved Added validation on the partial captures. If you submit a partial capture without split instructions, we'll send a capture notification with `success = false` and reason: `Incomplete split payment data provided: Partial captures on payments with split instructions are not supported`. ### Fixed Fixed an issue where the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification was not sent when the identity verification status changed from `INVALID_DATA` to `DATA_PROVIDED`. ## 2019-09-16 — General ### Fixed Transferring funds between two accounts that belong to the same account holder no longer increases the processed volume. ## 2019-09-02 — API ### Fixed Verification check status for `COMPANY_VERIFICATION` is now set to `PENDING` when uploading a company extract using the [`/uploadDocument`](https://docs.adyen.com/api-explorer/#/Account/latest/uploadDocument) call. ## 2019-08-26 — Classic Platforms ### Improved We now send an [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification when a validation error occurs on the [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) call. This now applies to versions earlier than v5 as well. ## 2019-08-19 — API ### Improved In the [`/checkAccountHolder`](https://docs.adyen.com/api-explorer/#/Account/latest/checkAccountHolder) request, we now validate if the payout or processing tier is not lower than or equal to the current tier of the account holder. If this validation fails, you can receive the following errors: * 80: The provided Payout or Processing tier cannot not be lower than or equal to the account holder's current Processing tier. * 81: The provided Payout tier cannot not be lower than or equal to the account holder's current Payout tier. ## 2019-08-12 — Customer Area ### New The "On Hold Balance" is now available in the [MarketPay balance report](/classic-platforms/reports-and-fees/marketpay-balance-report).\ To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2019-07-29 — API ### Fixed Updating a shareholder with an incorrect shareholder code will result in a validation error: `errorCode = 70` `Message = "Shareholder does not exist for shareHolderCode: {0}."` ## 2019-07-22 — Reports ### Fixed The exchange rate column in the [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report) is now populated. ## 2019-07-15 — API ### Improved Improved the order of validations for the [/payoutAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/payoutAccountHolder) call. The error `There is not enough balance available for account {0}. Available balance: {1}; Payout amount: {2}.` is now returned before the `Payout limit reached the account limit.` error. ### Changed You can now change the payout descriptor for [automatic payouts](/classic-platforms/payouts/scheduled-payout). ## 2019-07-15 — API ### New You can now upload supporting documents by sending **COMPANY\_REGISTRATION\_SCREENING** document type in the [/uploadDocument](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument) request. ## 2019-07-08 — Reports ### Fixed Corrected the **Main Amount** column for Express Payouts in the [Marketplace Payments accounting report](/reporting/marketpay-payments-accounting-report). ## 2019-07-08 — General ### New We added Lithuania to the countries we support. ## 2019-07-01 — API ### Changed The `email` is no longer required for shareholders. ## 2019-07-01 — Classic Platforms ### Fixed The `merchantReference` is populated in the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification if the API version and the notification version are different. For example, API v3 and notification v5. ### Improved When a request fails on the central system, the `accountHolderCode` or `accountCode` is now returned in the notifications. ## 2019-06-24 — Customer Area ### Improved You can now make partial refunds on specific split items in your [Customer Area](https://ca-test.adyen.com/). ## 2019-06-24 — API — Version 5 ### Fixed You can now change the legal entity type to **business** with multiple shareholders. ## 2019-06-24 — General ### Fixed A PayoutReturned to a source account of a beneficiary setup is now booked to the destination account. ## 2019-06-17 — KYC ### Changed The retry limit on a verification check is reset (set to zero) when an account holder passes the verification check. ## 2019-06-17 — Customer Area ### Improved Added a link to the destination and/or source account in the sub-merchant transaction list. ## 2019-06-17 — API ### Fixed When you make a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) call with incomplete `documentData`, the request will be refused. ## 2019-06-03 — API ### Fixed When using the [/refundNotPaidOutTransfers](https://docs.adyen.com/api-explorer/Fund/latest/post/refundNotPaidOutTransfers) for an account in a beneficiary setup, the transactions on destination account are now refunded. ## 2019-05-27 — General ### Changed We've lowered the minimum allowed size for [uploaded bank statements](/classic-platforms/verification-process) (in jpeg, jpg, and png) from 100kB to 10kB. ## 2019-05-19 — API ### Improved When an [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) or a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request includes a phone number for the shareholder and the account itself, these two get recorded separately. ## 2019-05-13 — Classic Platforms ### Fixed [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notifications with `verificationStatus`: **INVALID\_DATA** no longer contain a `requiredFields` object. ## 2019-05-12 — Hosted onboarding ### New The page now includes a field for the Photo ID, so that you can simulate tier 3 verification in test. ## 2019-05-06 — Classic Platforms ### Fixed The [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification now includes an error message when you try to update an account holder's bank account but the `bankAccountUUID` does not exist. ## 2019-05-06 — API ### Changed When making a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) call, you can now pass `fullPhoneNumber` instead of `email`. ### Fixed [/getUploadedDocuments](https://docs.adyen.com/api-explorer/#/Account/getUploadedDocuments) no longer returns documents of deleted bank accounts. ## 2019-04-29 — API ### Changed We renamed the `/verify` endpoint to [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/5/post/checkAccountHolder). ## 2019-04-29 — API ### Fixed When the `amount` in a [splits](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-splits) array is assigned a float value, you now get the following error message: `Invalid additionalData field split.item1.amount`. ## 2019-04-23 — API ### Fixed * [/getUploadedDocuments](https://docs.adyen.com/api-explorer/#/Account/getUploadedDocuments) now only returns the latest document of a check type. * When you pass an empty object in an API call, this object is no longer returned in the response. ## 2019-04-23 — General ### New We added Greece to supported countries. ## 2019-04-23 — KYC ### Changed When you unsuspend an account holder after they got suspended because of missing the [KYC deadline](/classic-platforms/verification-process#inactivation-suspension-deadline), they now have to submit the required information within 42 days, or they will get suspended again. ## 2019-04-15 — API ### Changed When [providing bank account information](/classic-platforms/verification-process), you no longer need to pass `bankAccount.countryCode`. We now get the country from the `address.country` field. ## 2019-04-15 — Customer Area ### Changed * When refunding a split payment, the refund now has as its reference the split item **Reference**, not the authorisation reference as before. * The date format for the account holder transaction export is now: **yyyy-MM-dd HH:mm:ss**. ## 2019-04-15 — Reports ### Fixed We fixed an issue that caused the hourly *Payment accounting report* to miss some data. ## 2019-04-15 — API ### Fixed We improved the flow for updating an account holder shortly after creating it. ## 2019-03-25 — Customer Area ### New You can now initiate [fund transfers](/classic-platforms/fund-transfer#transfer-funds-customer-area) from your [Customer Area](https://ca-test.adyen.com/). ### Improved Account holder level `metadata` is now displayed on the account holder overview page. ## 2019-03-25 — API ### Changed * Underscore is now allowed in the `accountHolderCode` parameter. * When refunding by using the [/refundNotPaidOutTransfers](https://docs.adyen.com/api-explorer/#/Account/refundNotPaidOutTransfers) call, you now have the option to use the authorisation reference as a reference for the refund. ### Removed You can no longer set up a beneficiary when the source account is suspended. ## 2019-03-25 — API — Version 5 ### Changed The [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) response and the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification now include the `payoutInstrumentTokens`. ## 2019-03-25 — KYC ### Fixed The 1501 KYC verification codes in the KYC timeline now show the full description. ## 2019-03-24 — Classic Platforms ### Fixed The [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification is now also triggered by the [/deleteBankAccounts](https://docs.adyen.com/api-explorer/#/Account/deleteBankAccounts) and [/deleteShareholders](https://docs.adyen.com/api-explorer/#/Account/deleteShareholders) requests. ## 2019-03-18 — Customer Area ### Fixed The description of a payout in the transaction list no longer contains a JSON object. ## 2019-03-11 — API ### New You can now consistently hide personally identifying information (PII) across API responses and notifications.\ To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Fixed [/getUploadedDocuments](https://docs.adyen.com/api-explorer/#/Account/getUploadedDocuments) no longer returns documents from deleted shareholders. ## 2019-03-11 — Customer Area ### Improved The transaction list now shows the description of a payout. ## 2019-03-04 — Customer Area ### Improved We improved the design of the sub-merchant list in your [Customer Area](https://ca-test.adyen.com/) for smaller screen sizes. ## 2019-02-21 — Classic Platforms ### Fixed Notifications now include the error message in addition to `errorCode`. ## 2019-02-21 — API ### Improved We now only reject duplicate [document uploads](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) for the documents that are active for this account holder. ### Fixed Fixed a bug that changed the `bankAccountUUID` and `shareholderCode` for marketplaces that had enabled the GDPR setting. ## 2019-02-14 — API ### Fixed * We no longer match duplicate bank account for account holder on just the `accountNumber`, but also include the `branchCode`. * We fixed an issue that would push an account holder in the highest tier when multiple [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) requests added the same bank account. ## 2019-02-14 — Reports ### Improved You can now retroactively generate the Marketpay Balance Report. ## 2019-02-14 — API ### Improved We added refusal reasons for automatic bank verification for US bank accounts. | Refusal reason code | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | 3111 | The routing number provided is incorrect. Provide the correct ABA routing number associated with this account. 1 | | 3112 | The account number provided is incorrect. Provide the correct account number. | | 3113 | This institution is not programmatically covered. Use a different financial institution or upload a copy of your bank statement. | | 3114 | This institution is not eligible for payouts on MarketPay. Provide a different bank account. | ## 2019-02-14 — Customer Area ### Improved Payments in the sub-merchant's transaction list now display the full transaction history in a single payment line. ## 2019-02-07 — KYC ### Improved We improved bank account verification rates in Germany for when an account holder only provides account number and branch code instead of the IBAN. ## 2019-02-07 — API — Version 5 ### Improved The [/getAccountHolder](https://docs.adyen.com/api-explorer/#/Account/getAccountHolder) response now contains system up to date time. ## 2019-01-31 — Reports ### Improved You can now generate MarketPay reports in bulk.\ To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2019-01-31 — Customer Area ### New You can now pay out to an account holder from the Customer Area.\ To enable this functionality, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## 2019-01-24 — API ### Improved We added security features to the Adyen for Platforms API credentials such as X-API-KEY, IP restriction, and adding a client certificate. ### Fixed The [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request no longer fails if made shortly after a [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request. ## 2019-01-24 — Classic Platforms ### Fixed The PSP reference in the [ACCOUNT\_HOLDER\_PAYOUT](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_PAYOUT) notification now matches the PSP reference in the Marketplace Payment accounting report. ## 2019-01-24 — Customer Area ### Fixed We fixed a display issue of account holder date of birth. ## 2019-01-17 — API ### Fixed * We fixed an issue where the **COMPANY\_VERIFICATION** returned **AWAITING\_DATA** instead of **PENDING**. * We fixed a bug that caused **BANK\_ACCOUNT\_VERIFICATION** to stay in **PENDING** status. ## 2019-01-17 — Customer Area ### New The transaction list on the account holder page now contains an estimated time of arrival for payouts. ### Improved * The **Upcoming deadline** on the account holder overview page now contains the year, in addition to month, day, and time. * Payments list - You can now also refund the commission or payment fee part in the split payment through the [Customer Area](https://ca-test.adyen.com/). ### Fixed * The account holder deadline date is now displayed correctly. * The account holder transaction list now starts from 1 instead of 0. ## 2019-01-17 — Reports ### Improved *MarketPay balance report*: Added two columns to the report displaying the *Pending Credit* and *Pending Debit* amounts. ### Removed We removed the MarketPay End of Month Balance Report. You can now get the data from this report in the [Marketpay Balance Report](/classic-platforms/reports-and-fees/marketpay-balance-report). ## 2019-01-17 — API ### Fixed We fixed a bug where a returned payout for an account holder was not correctly deducted from the total paid out amount. ## 2018-12-27 — API — Version 5 *\

For guidance on upgrading to this version, refer to the \migration guide\.\

* ### Breaking Changes * All create, update, and delete requests are now handled [asynchronously](/classic-platforms/migrating-to-v5#async). Your integration must use notification webhooks to get the outcome of your requests. * When making a [/createAccountHolder](https://docs.adyen.com/api-explorer/Account/5/post/createAccountHolder) request to create an account holder of `legalEntityType` **business**, the `country` field is now required. * We renamed the `/verify` endpoint to [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/5/post/checkAccountHolder). ### Improved * We implemented [more granular KYC verification error codes](/classic-platforms/verification-process/verification-codes) to help you determine which type of check the error is for. We divided the error codes into the following categories: * Photo ID verification: Error codes starting with 11xx. * Identity check: Error codes starting with 13xx. * Company verification: Error codes starting with 21xx. * Bank account verification: Error codes starting with 31xx. ### New * You can now [update the legal entity type of an existing account holder](/classic-platforms/account-holders-and-accounts/change-legal-entity). * You can now upload supporting documents by sending **COMPANY\_REGISTRATION\_SCREENING** document type in the [/uploadDocument](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument) request. * When adding payout methods, you can now include your own payout method reference in the `payoutMethodReference` field. * We added the following endpoints: * [/checkAccountHolder](https://docs.adyen.com/api-explorer/Account/5/post/checkAccountHolder) Use this endpoint to trigger account holder verification earlier than required by the currently processed volume. * [/deletePayoutMethods](https://docs.adyen.com/api-explorer/Account/5/post/deletePayoutMethods) Use this endpoint to delete payout methods of an existing account holder. ## 2018-12-27 — Classic Platforms — Version 5 ### New * You can now [enable HMAC signatures](/classic-platforms/configure-notifications/signing-notifications-with-hmac) as an extra layer of security for your notification webhooks. * All notification types now include a root-level [error](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED#request-error) object that contains `errorCode` and `message`. This new object contains both validation and server errors. * In all notification types, you can now see which fields are invalid or missing in the `content.invalidFields` array. --- # Source: https://docs.adyen.com/classic-platforms/reports-and-fees.md Section: Classic Platforms integration Title: Reports and fee types Description: Learn about relevant report data and how you can use it to reconcile your platform accounts. --- title: "Reports and fee types" description: "Learn about relevant report data and how you can use it to reconcile your platform accounts." url: "https://docs.adyen.com/classic-platforms/reports-and-fees" source_url: "https://docs.adyen.com/classic-platforms/reports-and-fees.md" canonical: "https://docs.adyen.com/classic-platforms/reports-and-fees" last_modified: "2023-06-07T19:05:00+02:00" language: "en" --- # Reports and fee types Learn about relevant report data and how you can use it to reconcile your platform accounts. [View source](/classic-platforms/reports-and-fees.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. To ensure accurate accounting of funds within your platform, use Adyen-generated reports for your bookkeeping and reconciliation processes. ## Types of reports Adyen generates reports for [your Adyen account](/classic-platforms/account-structure#your-adyen-account) and for [your platform](/classic-platforms/account-structure/#your-platform). You can use these reports to do [common reconciliation processes](/classic-platforms/reconciliation-use-cases). There are several reports that you can use, and depending on what you want to reconcile and track, you can use one or a combination of multiple reports. The diagram below introduces some of the reports that are most relevant for tracking [how platform funds flow](/classic-platforms/account-structure#how-funds-flow): from when a payment is processed up to when funds are paid out to the account holder. ![](/user/pages/docs/06.classic-platforms/20.reports-and-fees/AfPClassic_ReportingDocsContent_PublicDocs_001_BP-Report-Overview.svg?decoding=auto\&fetchpriority=auto) ### Adyen account reports Reports for your Adyen account contain payments processing details and invoices. | Report | Use this report to | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Received payment details report](/reporting/received-payment-details-report) | Get detailed insights about individual payment interactions. This report includes some shopper insights, payment information (such as payment method, issuing country, channel), interaction (such as if 3D Secure authentication was triggered), as well as statuses and reason codes. | | [Payment accounting report](/reporting/invoice-reconciliation/payment-accounting-report) Required for full financial reconciliation. | Get details of payment lifecycle events, including the fees associated with each event. Understand the breakdown of payment processing costs and get retrospective cost insight. With the cost breakdown, you can allocate payment costs at account holder level which you may want to include in your full monthly reconciliation. This report does not contain platform transaction charges, such as those applied for payouts, funds transfers, and KYC checks. | | [Settlement details report](/reporting/settlement-detail-report) Required for full financial reconciliation. | Get a full list of the transactions included in a single payable batch that settled funds from payments to account holders' accounts. This report includes all payment-related costs that can be assessed up to the point when the funds were settled. This report will also include other balance adjustments that might occur periodically, for example, final invoiced amounts on a monthly cadence. | | [Monthly invoice](/reporting/invoice-reconciliation/payment-processing-invoice) Required for full financial reconciliation. | Get a summary of all assessed fees and adjustments applied during the prior month. Use the Monthly invoice as part of a complete monthly reconciliation of platform operating costs, and to get insights to overall platform margin. Adjustments are subsequently passed through settlement flow to your platform, and are traceable in the Settlement details report for your Adyen account and the Marketplace Payments accounting report for your platform. | ### Platform reports Reports for your platform tie events to specific account holders. Reports related to funds also provide details about events that affect account balances for each account holder. | Report | Use this report to | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report) Required for full financial reconciliation. | Track all pending and credited/debited balance changes on a daily or hourly basis. build a full transactional ledger that you can show to your account holders. This report includes your platform's liable accounts and the accounts of account holders. | | [Marketpay Balance Report](/classic-platforms/reports-and-fees/marketpay-balance-report) | Get the balances of all the accounts in your platform, including your liable account on a daily basis. | | [Marketpay Payout Report](/classic-platforms/reports-and-fees/marketpay-payout-report) | Get all the transactions that were part of a payout on a given day, including payouts from your liable account. Use this report only for accounts set up with [scheduled payouts](/classic-platforms/payouts/scheduled-payout). | ## Types of fees Your platform incurs fees, such as processing fees for each received transaction and fees for premium features. The fees vary depending on the transaction. Adyen deducts fees from settlement and debits them from your platform's liable account. To fully reconcile these fees over the course of a month, you need to get totals and the breakdown from different reports. In general, the reports contain the following kinds of fees: * Settlement details report: breakdown of fees for settled transactions * Payment accounting report: breakdown of all transaction-related fees, including those that have not settled * Payment processing invoice: totals of fees incurred during the month, including fees charged on a monthly basis The following are possible fees that your platform might incur and the reports where you can find them. | Fee | Type | Find this fee in | Description of fee | | ------------------------------------ | ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Commission | Percentage | Settlement Details Report | Adyen processing fee for [blended rates](https://www.adyen.com/knowledge-hub/get-the-best-from-your-card-processing). | | FanF | Per authorisation | Monthly invoice | The Fixed Acquirer Network Fee assessed by Visa. Only applies to the US. | | Interchange | Variable | Settlement Details Report | Fee assessed by issuing banks. | | MarketPay Fund Transfer Service | Per instruction | Monthly invoice | Adyen fee for the use of the Fund Transfer API. | | MarketPay Payout Service | Per instruction | Monthly invoice | Adyen fee for each executed payout. | | MarketPay Sub-Merchant Verifications | Per sub-merchant | Monthly invoice | Adyen fee for sub-merchant KYC and verification. | | Markup | Percentage | Settlement Details Report | Adyen fee for [Interchange ++ pricing](https://www.adyen.com/knowledge-hub/get-the-best-from-your-card-processing). | | Merchant Location Fee | Per store | Monthly invoice | Merchant Location Fee assessed by Mastercard. Only applies to the US. | | Processing | Per authorisation | Payment Accounting Report | Adyen fee for processing the transaction. | | Scheme fees | Per authorisation | Settlement Details Report | Fee assessed by card schemes. | ## Next steps In the next section, we describe common reconciliation processes and the reports that you can use to implement them. [required](/classic-platforms/prepare-reports) [Prepare the reports](/classic-platforms/prepare-reports) [Configure, download, and combine reports.](/classic-platforms/prepare-reports) [Learn about common reconciliation use cases](/classic-platforms/reconciliation-use-cases) [Read our guides on how to use the reports to do financial reconciliation.](/classic-platforms/reconciliation-use-cases) --- # Source: https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-balance-report.md Section: Classic Platforms integration Title: Marketpay Balance Report Description: This report shows balances in your Adyen for Platforms accounts. --- title: "Marketpay Balance Report" description: "This report shows balances in your Adyen for Platforms accounts." url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-balance-report" source_url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-balance-report.md" canonical: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-balance-report" last_modified: "2023-02-20T13:18:00+01:00" language: "en" --- # Marketpay Balance Report This report shows balances in your Adyen for Platforms accounts. [View source](/classic-platforms/reports-and-fees/marketpay-balance-report.md) ##### Time zone This report is based on the CET time zone. Moving funds around your platform and to your account holders can get complicated, especially if you are dealing with many sellers or using complex payment flows. The Marketpay Balance Report gives you all balance information for your platform in one place, across account holders and accounts. You can use this report to [reconcile the balances of the accounts in your platform](/classic-platforms/reconciliation-use-cases/build-transactional-ledger#getting-the-balance-for-each-account). **Report name format:** MarketPay\_balance\_YYYY\_MM\_DD.csv\ **Subscription** : Default\ **Frequency** : Daily, Weekly, or Monthly ## Sample [Download a sample Marketpay Balance Report](/reporting/settlement-reconciliation/transaction-level/marketpay-balance-report/SAMPLE_MarketPay_balance_MarketPlaceCode_2021_04_20.csv) for examples of the included data. ## Structure ### Summary The first four lines of the report contain the following information. ```raw MarketPay Balance Report Report Time YYYY-MM-DD HH:MM:SS.0 Accounts balance ``` ### Entries Under the summary and header line (line 5), each line in the report is a separate entry. ### Columns Each column shows specific information about the entries. | # | Column | Data type | Description | | - | --------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Marketplace | Unicode Text | Name of your marketplace or platform. | | 2 | Account Holder | Unicode Text | The `accountHolderCode` you provided when you created the account holder. | | 3 | Virtual Account | Unicode Text (Either 9- or 16-character limit) | The `accountCode` of the account that belongs to the account holder. | | 4 | Currency | Alpha Text (3-character limit) | Three-character ISO currency code. | | 5 | Balance | Fixed point number | Available balance on the *Virtual Account* in the currency defined in the *Currency* column. The amount is in [minor units](/development-resources/currency-codes). | | 6 | Pending Credit | Fixed point number | Pending Credit balance that is available on the *Virtual Account* in the currency defined in the *Currency* column. The amount is in minor units. | | 7 | Pending Debit | Fixed point number | Pending Debit balance on the *Virtual Account* in the currency defined in the *Currency* column. The amount is in minor units. | ## See also * [Reconciliation transactions using reports](/classic-platforms/reports-and-fees#fees) --- # Source: https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-payout-report.md Section: Classic Platforms integration Title: Marketpay Payout Report Description: Use this report to reconcile each account holder's payout against debit and credit transactions. --- title: "Marketpay Payout Report" description: "Use this report to reconcile each account holder's payout against debit and credit transactions." url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-payout-report" source_url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-payout-report.md" canonical: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketpay-payout-report" last_modified: "2026-06-05T13:33:04+02:00" language: "en" --- # Marketpay Payout Report Use this report to reconcile each account holder's payout against debit and credit transactions. [View source](/classic-platforms/reports-and-fees/marketpay-payout-report.md) ##### Time zones Your [time zone setting](/reporting/time-zone-setting) affects the data in this report. The Marketpay Payout Report is only available for [Automatic payouts](/classic-platforms/payouts) and provides information about automatic payouts that were initiated within the day. The report also includes which account holders have been paid out and which transactions (both debits and credits) were part of the payout. To get the transactions included in the payout for a particular account, filter the report using the **Account holder**, **Account**, and **Currency** columns. We generate one record line per account, per currency. If an account has pending transactions (for example, a pending refund or chargeback), the amount is withheld from the payout amount. In such cases, the payout line of that account shows a non-zero rolling balance. The rolling balance is added to the balance of the next report, so you can use these reports to make a full reconciliation. **Report name format**: marketpay\_payout\_**YYYY\_MM\_DD**.csv\ **Subscription**: Subscribe to this report in your [Customer Area](https://ca-live.adyen.com/).\ **Frequency**: Daily, Weekly, or Monthly ## Sample [Download a sample Marketpay Payout Report](/reporting/settlement-reconciliation/transaction-level/marketpay-payout-report/SAMPLE_marketpay_payout_report_2020_03_17.csv) for examples of the included data. ## Structure The first line of the report shows **Marketpay Payout Report**. The second line is the header line containing the following information. ### Entries Under the header line, each line in the report is a separate entry. ### Columns Each column shows specific information about the entries. | Column # | Column | Data type | Description | | -------- | -------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Market Place | Unicode Text | Name of your marketplace or platform. | | 2 | Account Holder | Unicode Text | The `accountHolderCode` you provided when you created the account holder. | | 3 | Account | Unicode Text (9- or 16-character limit) | The `accountCode` of the account that belongs to the account holder. | | 4 | Record Type | Unicode Text | The type of record included in a report. See [Record types](#record-types) for a list of possible values. | | 5 | Psp Reference | Unicode Text (16-character limit) | PSP reference for the action in the Adyen for Platforms system. | | 6 | Payment Psp Reference | Unicode Text (16-character limit) | PSP reference of the payment in the PSP system/Customer Area. Can be empty if the action is not related to a payment. | | 7 | Payment Merchant Reference | Unicode Text (80-character) | The reference you provided when you submitted the payment. | | 8 | Capture Psp Reference | Unicode Text (16-character limit) | PSP reference for modification requests, such as a capture, refund, or chargeback request. | | 9 | Capture Merchant Reference | Unicode Text (80-character) | The reference you provided when you submitted a modification. When the [capture delay](/online-payments/capture#delayed-automatic-capture) is set to immediate, the value here is set to **auto**. | | 10 | Payout Psp Reference | Unicode Text (16-character limit) | PSP reference of a payout. | | 11 | Chargeback Psp Reference | Unicode Text (16-character limit) | PSP reference of a chargeback. | | 12 | Booking Date | Date field + Time field | Timestamp created when the booking was submitted. | | 13 | TimeZone | Alpha Text (4-character limit) | Timezone in which the report was generated. | | 14 | Currency | Alpha Text (3-character limit) | Currency in which the action was performed or in which the payment/payout/fundTransfer was submitted. | | 15 | Amount | Fixed point number | Amount defined in the split item line in the payment or payout/fundTransfer request. | | 16 | Rolling Balance | Fixed point number | Balance remaining in the account after the payout. This is usually 0, except when balance is withheld (for example, when there is a pending refund). The rolling balance is added to the next report's rolling balance. | ## Record types | Record type | Description | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Credited | The funds have settled | | . | | | CreditReversed | Adyen did not receive the funds and debits the original credited amount from the account. | | CreditFailed | The capture failed due to a technical issue, no funds were credited to the account. | | Debited | The funds were refunded | | . | | | DebitedReversed | An initiated refund was returned to Adyen and the funds are booked back to the account. For example, when the bank account of the cardholder was closed. | | DebitFailed | The refund failed due to a technical issue, no funds were debited from the account. | | Chargeback | Debit for a payment that was reversed by the bank, scheme, or the customer. | | ChargebackReversed | A previous chargeback was reversed after a payment was successfully defended, or after the shopper repaid. | | SecondChargeback | Debit for unsuccessful defense of a first chargeback. | | FundTransfer | Funds were transferred from one account to another. | | Payout | Funds were paid out to the account holder. | | VirtualAccountPayoutReturned | A payout could not be completed and the funds were returned to the account holder. For example, when the bank account of the cardholder is closed. | | DeprecatedManualCorrected | Manual booking or adjustment by Adyen, used in existing platforms. For new platforms, this record type is replaced by the [new record types](#contact-support): ManualCorrectionCredited and ManualCorrectionDebited. | | TransferBalance | Aggregate amount of debits and credits to the liable account. In previous versions of the report, this amount includes payment costs. For new platforms, the TransferBalance only contains the aggregate amount of credits and debits that could not have been booked due to missing split instructions, missing split reference, or a technical issue. Other debits and credits are reported under [new record types](#contact-support). For example, payment costs are reported under record type **Fee**. | | New Fee[ **\***](#contact-support) | Adyen fees booked against your platform's liable account during the specified period. This is enabled by default for new platforms. | | New DepositCorrection[ **\***](#contact-support) | Funds withheld from or released to your platform's liable account due to a change in the required security deposit (coverage of the exposure on the account). This is enabled by default for new platforms. | | New InvoiceDeduction[ **\***](#contact-support) | Represents a monthly invoice that is credited to or debited from your platform's liable account. This is enabled by default for new platforms. | | New MerchantPayin[ **\***](#contact-support) | A credit transfer or direct debit booked in your platform's liable account. This is enabled by default for new platforms. | | New MerchantPayinReversed[ **\***](#contact-support) | A payment meant to top up or fund your platform's liable account goes through a chargeback. This is enabled by default for new platforms. | | New ManualCorrectionCredited[ **\***](#contact-support) | Manual booking or adjustment by Adyen. The amount is added to the balance. This is enabled by default for new platforms. | | New ManualCorrectionDebited[ **\***](#contact-support) | Manual booking or adjustment by Adyen. The amount is deducted from the balance. This is enabled by default for new platforms. | []()**\*** This record type is used by default in new platforms. For existing platforms, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable the new record types. ## See also * [Reconciliation transactions using reports](/classic-platforms/reconciliation-use-cases) --- # Source: https://docs.adyen.com/classic-platforms/reports-and-fees/marketplace-payments-accounting-report.md Section: Classic Platforms integration Title: Marketplace Payments accounting report Description: Use this report to view financial status changes, events, and modifications for payments settled in Adyen for Platforms. --- title: "Marketplace Payments accounting report" description: "Use this report to view financial status changes, events, and modifications for payments settled in Adyen for Platforms." url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketplace-payments-accounting-report" source_url: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketplace-payments-accounting-report.md" canonical: "https://docs.adyen.com/classic-platforms/reports-and-fees/marketplace-payments-accounting-report" last_modified: "2023-02-20T13:53:00+01:00" language: "en" --- # Marketplace Payments accounting report Use this report to view financial status changes, events, and modifications for payments settled in Adyen for Platforms. [View source](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report.md) ##### Time zones Your [time zone setting](/reporting/time-zone-setting) affects the data in this report. The Marketplace Payments accounting report includes financial status changes, events, and modifications for all the payments across your marketplace or platform including full bookkeeping. You can use this report to [build a transactional ledger](/classic-platforms/reconciliation-use-cases/build-transactional-ledger) for all the accounts in your platform and to [reconcile total fees](/classic-platforms/reconciliation-use-cases/understand-fees#reconcile-total-fees) debited against your platform's liable account. **Report name format**:   * Daily: marketplace\_payments\_accounting\_report\_YYYY\_MM\_DD.csv * Hourly: marketplace\_hourly\_payments\_accounting\_report\_YYYY\_MM\_DD\_HH\_UTC.csv **Subscription**: Default\ **Frequency**: Hourly, or Daily ## Sample [Download a sample Marketpay Payments accounting report](/reporting/settlement-reconciliation/transaction-level/marketplace-payments-accounting-report/SAMPLE_marketplace_payments_accounting_report_2020_03_17.csv) for examples of the included data. ## Structure ### Entries Under the header line, each line in the report is a separate entry. ### Columns Each column shows specific information about the entries. | # | Column | Data type | Description | | -- | -------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Market Place | Unicode Text | Name of your marketplace or platform. | | 2 | Account Holder | Unicode Text | The `accountHolderCode` you provided when you created the account holder. | | 3 | Account | Unicode Text (Either 9- or 16-character limit) | The `accountCode` of the account that belongs to the account holder. | | 4 | Psp Reference | Unicode Text (16-character limit) | PSP reference for the action in the Adyen for Platforms system. | | 5 | Payment Psp Reference | Unicode Text (16-character limit) | PSP reference of the payment in the PSP system/Customer Area. Can be empty if the action is not related to a payment. | | 6 | Payment Merchant Reference | Unicode Text (80-character) | The reference you provided when you submitted the payment. | | 7 | Capture Psp Reference | Unicode Text (16-character limit) | PSP reference for modification requests, such as a capture, refund, or chargeback request. | | 8 | Capture Merchant Reference | Unicode Text (80-character) | The reference you provided when you submitted a modification. When the [capture delay](/online-payments/capture#delayed-automatic-capture) is set to immediate, the value here is set to **auto**. | | 9 | Payout Psp Reference | Unicode Text (16-character limit) | PSP reference of a payout. | | 10 | Chargeback Psp Reference | Unicode Text (16-character limit) | PSP reference of a chargeback. | | 11 | Booking Date | Date field + Time field | Timestamp created when the booking was submitted. | | 12 | TimeZone | Alpha Text (4-character limit) | Timezone in which the report was generated. | | 13 | Description | Unicode Text | For the split item line and record types Payout, FundTransfer, or FundTransferReversed, this is the description sent in the request. For record types PendingCredit, Credited, CreditFailed, PendingDebit, Debited, DebitedReversed, and DebitFailed , the format of the description is:*split.item.reference + " - " + split.item.description*For ChargebackReceived, Chargeback, ChargebackReversedReceived, and ChargebackReversed types, the format of the description is:*formatted:split.item.reference + " - " + chargeback reasonCode* | | 14 | Main Currency | Alpha Text (3-character limit) | Currency in which the action was performed or in which the payment/payout/fundTransfer/fundTransferReversed was submitted. | | 15 | Main Amount | Fixed point number | Amount defined in the split item line in the payment or payout/fundTransfer/fundTransferReversed request. | | 16 | Record Type | Unicode Text | The [type of record](#record-types). Indicates if the amount affects the pending balance or the available balance. | | 17 | Balance Currency | Alpha Text (3-character limit) | Currency of the balance after transferring it to the virtual account. | | 18 | Pending (BC) | Fixed point number | Pending balance, reflects pending debits or credits. [Record types](#record-types) such as PendingCredit and ChargebackReceived affect the pending balance. | | 19 | Balance (BC) | Fixed point number | Available balance, reflects amounts that have already been credited or debited. [Record types](#record-types) such as FundTransfer and DebitedReversed affect the balance. | | 20 | Exchange Rate | Floating point number | The exchange rate used for the payment, used only when there was as currency conversion between the main currency and the balance currency. | | 21 | Bank account details | Unicode Text | Bank account details used for payouts, in a JSON, single-line format. | | 22 | US State | Unicode Text | State where the transaction was processed. For example, FL or CA. | | 23 | Refund terms | Unicode Text | "Right To Refund" legal text. This applies when the bank account being paid out to is in California (US). | | 24 | Reserved5 | - | Reserved for future enhancements | | 25 | Reserved6 | - | Reserved for future enhancements | | 26 | Reserved7 | - | Reserved for future enhancements | | 27 | Reserved8 | - | Reserved for future enhancements | | 28 | Reserved9 | - | Reserved for future enhancements | | 29 | Reserved10 | - | Reserved for future enhancements | ### Configure report columns Refer to [Adyen for Platforms documentation](/classic-platforms/prepare-reports#add-report-columns) for recommended additional report columns. ## Record types The *Record type* value indicates the type of entry and whether the entry affects the pending balance (*Pending* column) or the available balance (*Balance* column) of the account. | Record type | Affected balance column | Description | | ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | PendingCredit | Pending | The payment was captured, but the balance is not yet available for payout because Adyen has not yet received the funds. The pending balance is adjusted accordingly. | | Credited | Pending, Balance | The funds have settled | | and are added to the balance accordingly. | | | | PendingDebit | Pending | A refund was initiated, but the funds have not been deducted yet. The pending balance is adjusted accordingly. | | Debited | Pending, Balance | The funds were refunded | | and are deducted from the balance accordingly. | | | | CreditFailed | Pending | The capture failed due to a technical issue, no funds were credited to the account. | | DebitFailed | Pending | The refund failed due to a technical issue, no funds were debited from the account. | | CreditReversed | Balance | Adyen did not receive the funds and debits the original credited amount from the account. | | DebitedReversed | Balance | An initiated refund was returned to Adyen and the funds are booked back to the account. For example, when the bank account of the cardholder was closed. | | ChargebackReceived | Pending | A chargeback was received but the amount is not yet deducted from the account. | | Chargeback | Pending, Balance | Debit for a payment that was reversed by the bank, scheme, or the customer. The chargeback amount is deducted from the account balance. | | ChargebackReversedReceived | Pending | A chargeback was reversed after a payment was successfully defended, or after the shopper repaid the funds, but the funds have not yet been received. The pending balance is adjusted accordingly. | | ChargebackReversed | Pending, Balance | A previous chargeback was reversed after a payment was successfully defended, or after the shopper repaid. The funds are added to the account balance. | | SecondChargebackReceived | Pending | A second chargeback is received for unsuccessful defense of a first chargeback, but the amount is not yet deducted from the account. The pending balance is adjusted accordingly. | | SecondChargeback | Pending, Balance | Debit for unsuccessful defense of a first chargeback. The chargeback amount is deducted from the account balance. | | FundTransfer | Balance | Funds were transferred from one account to another. The balance is adjusted accordingly. | | FundTransferReversed | Balance | A fund transfer was reversed, so the funds are still in the source account. | | PendingFundTransfer | Pending | Used only for funds transfers for accounts with a [beneficiary setup](https://docs.adyen.com/api-explorer/#/Fund/latest/setupBeneficiary). The pending balance is adjusted accordingly. | | Payout | Balance | For payouts to bank accounts. Funds were paid out to the account holder and are deducted from the available balance. | | VirtualAccountPayoutReturned | Balance | For payouts to bank accounts. A payout could not be completed and the funds were returned to the account holder. For example, when the bank account of the cardholder is closed. | | PayoutInitiated | Balance | For payouts to cards. A payout was initiated. The funds are deducted from the available balance. | | PaidOut | Balance | For payouts to cards. Funds were paid out to the account holder and are deducted from the available balance. | | PayoutFailed | Balance | For payouts to cards. A payout could not be completed and the funds were returned to the account holder. | | DeprecatedManualCorrected | Balance | Manual booking or adjustment by Adyen, used in existing platforms. For new platforms, this record type is replaced by the [new record types](#contact-support): ManualCorrectionCredited and ManualCorrectionDebited. | | TransferBalance | Balance | Aggregate amount of debits and credits to the liable account. In previous versions of the report, this amount includes payment costs. For new platforms, the TransferBalance only contains the aggregate amount of credits and debits that could not have been booked due to missing split instructions, missing split reference, or a technical issue. Other debits and credits are reported under [new record types](#contact-support). For example, payment costs are reported under record type **Fee**. | | NewFee[ **\***](#contact-support) | Balance | Adyen fees booked against your platform's liable account during the specified period. This is enabled by default for new platforms. | | NewDepositCorrection[ **\***](#contact-support) | Balance | Funds withheld from or released to your platform's liable account due to a change in the required security deposit (coverage of the exposure on the account). This is enabled by default for new platforms. | | NewInvoiceDeduction[ **\***](#contact-support) | Balance | Represents a monthly invoice that is credited to or debited from your platform's liable account. This is enabled by default for new platforms. | | NewMerchantPayin[ **\***](#contact-support) | Balance | A credit transfer or [direct debit](/classic-platforms/top-up-accounts) booked in your platform's liable account. This is enabled by default for new platforms. | | NewMerchantPayinReversed[ **\***](#contact-support) | Balance | A payment meant to top up or fund your platform's liable account goes through a chargeback. This is enabled by default for new platforms. | | NewManualCorrectionCredited[ **\***](#contact-support) | Balance | Manual booking or adjustment by Adyen. The amount is added to the balance. This is enabled by default for new platforms. | | NewManualCorrectionDebited[ **\***](#contact-support) | Balance | Manual booking or adjustment by Adyen. The amount is deducted from the balance. This is enabled by default for new platforms. | []()**\*** This record type is used by default in new platforms. For existing platforms, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable the new record types. ## See also * [Reconciliation transactions using reports](/classic-platforms/reports-and-fees#fees) --- # Source: https://docs.adyen.com/classic-platforms/split-configuration-for-stores.md Section: Classic Platforms integration Title: Automatically split payments in stores Description: Split payments automatically when processing through stores. --- title: "Automatically split payments in stores" description: "Split payments automatically when processing through stores." url: "https://docs.adyen.com/classic-platforms/split-configuration-for-stores" source_url: "https://docs.adyen.com/classic-platforms/split-configuration-for-stores.md" canonical: "https://docs.adyen.com/classic-platforms/split-configuration-for-stores" last_modified: "2021-12-28T10:37:00+01:00" language: "en" --- # Automatically split payments in stores Split payments automatically when processing through stores. [View source](/classic-platforms/split-configuration-for-stores.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. When processing payments through stores, you can configure the store to automatically apply your billing logic for your commission fees. This means that you no longer need to send split instructions in every payment or capture request. For Adyen to automatically apply split instructions, you'll need to: 1. [Create a split configuration](#create-split-configuration) that contains commission fees and transaction conditions. 2. [Create or update the store](#create-update-store) to add the split configuration and the account to which the split amount must be sent. ## How split configuration works A split configuration contains one or more rules that define commission fees and conditions when the fee applies. You create and manage split configurations in your [Customer Area](https://ca-test.adyen.com/). Each rule in a split configuration must have: * Commission fees. The fee can be a fixed amount, a percentage, or both. * Conditions for the rule. You must define a value for each of the following conditions. * *Channel*: The sales channel. This can be a specific channel (such as ecommerce) or any sales channel. * *Currency*: Can be specific or any currency. * *Payment method*: Can be specific, based on the funding source or any payment method available to the store. A transaction must meet all conditions before the rule can be applied. When a transaction meets all conditions, Adyen applies the corresponding commission fee. We recommend that you include a catchall rule (set all conditions to *any*), because if none of the rules apply to the transaction, then all the funds will go to the liable account. Adyen evaluates the rules in the split configuration for all the transactions processed through the store. If you need to change the commission fees for specific transactions, you can send [split instructions in the payment or capture API request](/classic-platforms/processing-payments#providing-split-instructions). Any split instruction that you send through the API overrides the automatic split. ### Rule hierarchy If a split configuration has multiple rules and more than one rule applies to the transaction, Adyen applies the fee from the rule with the highest priority. The rules are prioritized based on the following hierarchy: 1. Currency 2. Payment method 3. Funding source (debit or credit) 4. Channel #### Examples Let's take for example the following split configuration rules. | | Currency | Payment method | Channel | Fee | | - | -------- | -------------- | --------- | ------------- | | 1 | EUR | Any | Any | EUR 3.00 + 1% | | 2 | Any | Any | Ecommerce | USD 2.50 + 1% | | 3 | EUR | Visa | Any | EUR 2.00 + 1% | | 4 | EUR | Any | Ecommerce | EUR 1.40 + 1% | | 5 | EUR | credit\_only | Any | EUR 1.50 + 1% | **Scenario 1**\ An *ecommerce* transaction in *EUR*, using *American Express*. The transaction meets the conditions for rules 1, 2, 4 and 5, but rule 5 has the highest priority because it matches the specific currency (*EUR*) and funding source (credit). Adyen splits the transaction and sends EUR 1.50 + 1% to your liable account. **Scenario 2** An *ecommerce* transaction in *EUR*, using *Visa*. The transaction meets the conditions for all the rules, but rule 3 has the highest priority because of the combination of specific currency (*EUR*) and payment method (*Visa*). Rule 3 has higher priority than rule 2 with the specific currency (*EUR*) and channel (*ecommerce*). Adyen splits the transaction and sends EUR 2.00 + 1% to your liable account. ## Requirements 1. Check if you have an integration that uses [stores](https://docs.adyen.com/api-explorer/#/Account/latest/post/updateAccountHolder__resParam_accountHolderDetails-storeDetails). Stores are currently available only for [point of sale](/classic-platforms/platforms-for-pos) and [partner platforms](/classic-platforms/platforms-for-partners) integrations. 2. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable split configuration for your platform. 3. Make sure that you have the **Manage split configuration settings** role for your Customer Area user. ## Step 1: Create a split configuration Now that you know [how split configurations work](#how-split-configuration-works), you can create and manage split configurations in your Customer Area. To access the page, make sure your Customer Area user has the **Manage split configuration settings** role. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and switch to your merchant account. 2. Go to **Platform** > **Split configuration**. 3. Select the **Add configuration profile** button. 4. Specify a name for the configuration. 5. Select the **Create** button. The new configuration will have a UUID under the configuration name. Take note of this because you'll use this later to [create or update the store](#create-update-store). To add rules to a split configuration: 1. Go to **Platform** > **Split configuration**. 2. Find the specific profile and select the **+** button to see the configuration panel. 3. Select the **Add rule** button. 4. Configure the **Channel**, **Scheme** (payment method), **Currency**, **Fixed Fee**, and **Variable Fee**. Select the values from the dropdown list. 5. Select the **Create** button. The combination of **Channel**, **Scheme**, and **Currency** must be unique for each rule. ## Step 2: Create or update the store Make a POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request to add the split configuration. In your request, include the following in the [storeDetails](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails) array: * [splitConfigurationUUID](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-storeDetails-splitConfigurationUUID): The UUID of the split configuration from your [Customer Area](https://ca-test.adyen.com/). * [virtualAccount](https://docs.adyen.com/api-explorer/#/Account/latest/post/updateAccountHolder__reqParam_accountHolderDetails-storeDetails-virtualAccount): The account holder's `accountCode` to which the split amount will be sent. The following example shows how to update an account holder to create a store with a split configuration. **Add store with split configuration to an account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "storeDetails": [ { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "merchantCategoryCode": "5999", "fullPhoneNumber": "+14153671502", "virtualAccount": "1211992213193029", "splitConfigurationUUID": "c52bb45f-0ada-4e55-af04-df5bf637bf49", "storeName": "STORE_NAME", "storeReference": "YOUR_STORE_REFERENCE", "address": { "city": "San Francisco", "country": "US", "postalCode": "94107", "stateOrProvince": "CA", "street": "Brannan Street", "houseNumberOrName": "274" } } ] } }' ``` If the store already exists, you can update the store entry to add the split configuration. **Add split configuration to account holder with existing store** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "storeDetails": [ { "splitConfigurationUUID": "53da2e8e-1d38-11eb-adc1-0242ac120002", "virtualAccount": "1211992213193029", "store": "47cec6d6-725a-40b4-b8cc-3245a66c1ed4" } ] } }' ``` Requests using [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) are processed asynchronously. You'll receive a response to your API request, but you must rely on the [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) notification webhook to know the final result of your request. After the store is successfully created or updated, Adyen starts evaluating every transaction processed in the store and applies the split configuration rules. ## See also * [Point of sale for platforms](/classic-platforms/platforms-for-pos) * [Partner platforms](/classic-platforms/platforms-for-partners) --- # Source: https://docs.adyen.com/classic-platforms/tax-forms.md Section: Classic Platforms integration Title: Providing tax forms Description: Learn how to provide a 1099-K tax form. --- title: "Providing tax forms" description: "Learn how to provide a 1099-K tax form." url: "https://docs.adyen.com/classic-platforms/tax-forms" source_url: "https://docs.adyen.com/classic-platforms/tax-forms.md" canonical: "https://docs.adyen.com/classic-platforms/tax-forms" last_modified: "2023-07-06T22:12:00+02:00" language: "en" --- # Providing tax forms Learn how to provide a 1099-K tax form. [View source](/classic-platforms/tax-forms.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Head to the [IRS website](https://www.irs.gov/) to learn more about the 1099-K tax form. In the US, payment settlement entities, like Adyen, are required to file a 1099-K tax form with the Internal Revenue Service (IRS) for any US-based entity (merchant or sub-merchant): * To which they pay out directly. * That has crossed the processed volume threshold set by US tax authorities. Some states require filing of 1099-K forms as well. []()\ For 2024, Adyen is required to file 1099-K forms for all merchants and sub-merchants with a gross processed volume at or above the federal threshold of USD 5,000 per calendar year. At state level thresholds can vary depending on the state. Adyen follows the IRS requirements for reporting gross processed volume prior to deduction of fees, chargebacks and refunds. ## Retrieve digital tax forms Follow this general flow to provide your sub-merchant with a digital copy of their tax form. 1. In your platform, [show a button or a link](#build-ui) for getting the tax form. 2. Send an API request to [get a tax form](#get-a-tax-form). The response returns a Base64 binary. 3. [Convert the received Base64 binary to PDF format](#decode-convert-pdf) and provide the sub-merchant with a PDF copy of their tax form. ## Step 1. Present tax forms in your UI In your UI, show a button or link that your sub-merchants can use to get the tax form. When a sub-merchant clicks the link or button, this should trigger the API request in the next step. ## Step 2. Get a tax form Use the [/getTaxForm](https://docs.adyen.com/api-explorer/#/Account/latest/post/getTaxForm) endpoint to generate a Base64 binary format of the sub-merchant's tax form. From your server, make a POST [/getTaxForm](https://docs.adyen.com/api-explorer/#/Account/latest/post/getTaxForm) request, specifying: | **Field** | **Type** | **Required** | **Description** | | ------------------- | -------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `accountHolderCode` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique reference to the sub-merchant's account holder. | | `formType` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Type of the requested tax form. For example, **1099-K**. | | `year` | Integer | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The applicable tax year in the **YYYY** format. | A tax form is only generated for sub-merchants that hit the volume or transaction [threshold](#threshold). If you make an API request for an `accountHolderCode` that does not hit the threshold, you will receive an error response. **Get a tax form** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/getTaxForm \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"26e8447d-d779-4be4-8ea8-6a1f8510479r", "formType":"1099-K", "year":2019 }' ``` The response contains: | **Field** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------- | | `contentType` | String | The content type of the tax form. For example, `application/pdf`. | | `content` | String | The content of the tax form in the Base64 binary format. | ## Step 3. Decode Base64 binary and convert to PDF To present the tax form to the sub-merchant, use the [Base64.Decoder](https://base64.guru/developers/java/examples/decode-pdf) class. Provide the sub-merchant with a PDF copy of their tax form. --- # Source: https://docs.adyen.com/classic-platforms/test-scenarios.md Section: Classic Platforms integration Title: Test scenarios Description: Test your integration. --- title: "Test scenarios" description: "Test your integration." url: "https://docs.adyen.com/classic-platforms/test-scenarios" source_url: "https://docs.adyen.com/classic-platforms/test-scenarios.md" canonical: "https://docs.adyen.com/classic-platforms/test-scenarios" last_modified: "2020-10-26T10:15:00+01:00" language: "en" --- # Test scenarios Test your integration. [View source](/classic-platforms/test-scenarios.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Adyen for Platforms provides you with a set of predefined test scenarios to test your integration. To test the scenarios, you need to create certain account holder states. This page explain how to: * Create account holders in the states you need. * Use the predefined test scenarios. ## Create an account holder in the payout state Select the account holder type to see the relevant examples below: ### Tab: Individual account holder 1. Make a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request to create an account holder. In your request, specify: * `address.city`: **PASSED** * `bankAccountDetails.ownerCity`: **PASSED** for all banks accounts. At least one bank account must be defined. * `bankAccountDetails.ownerName`: **TestData** * `individualDetails.name.lastName`: **TestData** * `legalEntity`: **Individual** **/createAccountHolder request** ```json { "accountHolderCode":"YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "accountHolderDetails":{ "address":{ "city":"PASSED", "country":"NL", "houseNumberOrName":"1", "postalCode":"1234AB", "street":"Main Street" }, "bankAccountDetails":[ { "countryCode":"NL", "currencyCode":"EUR", "iban":"NL13TEST0123456789", "ownerCity":"PASSED", "ownerCountryCode":"NL", "ownerHouseNumberOrName":"1", "ownerName":"TestData", "ownerPostalCode":"1234AB", "ownerStreet":"Main Street" } ], "email":"a.holder@example.com", "individualDetails":{ "name":{ "firstName":"Anthony", "gender":"MALE", "lastName":"TestData" }, "personalData":{ "dateOfBirth":"2001-04-27" } }, "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"0612345678", "phoneType":"Landline" }, "webAddress":"https://www.example.com" }, "legalEntity":"Individual", "processingTier":3 } ``` 2. Upload a photo ID on a Hosted Onboarding Page (HOP) or through an API request. * Hosted Onboarding Page * Upload a document with a **PASSED** file name. For example, **PASSED.jpg**. * API * Make a POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request to upload a passport. In your request, specify: * `documentContent`: A Base64-encoded image larger than 1000 bytes. * `documentType`: **PASSPORT** * `description`: **PASSED** When uploading photo ID, the account holder is set to the limitless state. This means the account holder requires the highest level of KYC checks. **/uploadDocument request for passport upload** ```json { "documentContent":"JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL1N1YnR5cGUgL0ltYWdlCi9UeXBlIC9YT2JqZWN0Ci9XaWR0aCAxMzYyCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9IZWlnaHQgNjI0Ci9CaXRzUGVyQ29tcG9uZW50IDgKL0xlbmd0aCA0MDA2NQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCj4+CnN0cmVhbQp4nO3dB3gU1aRU9GCg==", "documentDetail": { "accountHolderCode":"YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "description":"PASSED", "documentType":"PASSPORT", "filename":"document_name_passport.pdf" } } ``` 3. Upload a bank statement on a Hosted Onboarding Page (HOP) or through an API request. * Hosted Onboarding Page * Upload a document with a **PASSED** file name. For example, **PASSED.pdf**. * API * Make another POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request to upload a bank statement: **/uploadDocument request for bank statement upload** ```json { "documentContent":"JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL1N1YnR5cGUgL0ltYWdlCi9UeXBlIC9YT2JqZWN0Ci9XaWR0aCAxMzYyCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9IZWlnaHQgNjI0Ci9CaXRzUGVyQ29tcG9uZW50IDgKL0xlbmd0aCA0MDA2NQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCj4+CnN0cmVhbQp4nO3dB3gU1aRU9GCg==", "documentDetail": { "accountHolderCode": "YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "bankAccountUUID": "{hint:The /createAccountHolder response contains a bankAccountUUID}THE_BANK_ACCOUNT_UUID_WHICH_NEEDS_VERIFICATION{/hint}", "description": "PASSED", "documentType": "BANK_STATEMENT", "filename": "document_name_bank_statement.pdf" } } ``` The individual account holder now has its identity, document and bank statement verified. ### Tab: Business account holder 1. Make a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request to create an account holder. In your request, specify : * `address.city`: **PASSED** * `bankAccountDetails.ownerName`: **TestData** * `bankAccountDetails.ownerCity`: **PASSED** for all banks accounts. At least one bank account must be defined. * `businessDetails.legalBusinessName`: **TestData** * `businessDetails.shareholders.address.city`: **PASSED** for each shareholder. * `businessDetails.shareholders.name.lastName`: **TestData** for each shareholder * `legalEntity`: **Business** **/createAccountHolder request** ```json { "accountHolderCode":"YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "accountHolderDetails":{ "address":{ "city":"PASSED", "country":"NL", "houseNumberOrName":"1", "postalCode":"1234AB", "street":"Main Street" }, "bankAccountDetails":[ { "countryCode":"NL", "currencyCode":"EUR", "iban":"NL13TEST0123456789", "ownerCity":"PASSED", "ownerCountryCode":"NL", "ownerHouseNumberOrName":"1", "ownerName":"TestData", "ownerPostalCode":"1234AB", "ownerStreet":"Main Street" } ], "businessDetails":{ "doingBusinessAs":"Furniture shop", "legalBusinessName":"TestData", "registrationNumber":"123456789", "shareholders":[ { "address":{ "city":"PASSED", "country":"NL", "houseNumberOrName":"1", "postalCode":"1234AB", "street":"Main Street" }, "email":"testshareholder@example.com", "name":{ "firstName":"Anthony", "gender":"MALE", "lastName":"TestData" }, "personalData":{ "dateOfBirth":"2001-04-27" } } ], "taxId":"1234567890" }, "email":"a.holder@example.com", "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"0612345678", "phoneType":"Landline" }, "webAddress":"https://www.example.com" }, "legalEntity":"Business", "processingTier":3 } ``` 2. Upload a photo ID on a Hosted Onboarding Page (HOP) or through an API request. * Hosted Onboarding Page * Upload a document with a **PASSED** file name. For example, **PASSED.jpg**. * API * Make a POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request to upload a passport. In your request, specify: * `documentType`: **PASSPORT** * `description`: **PASSED** When uploading photo ID, the account holder is set to the limitless state. This means the account holder requires the highest level of KYC checks. **/uploadDocument request for passport upload** ```json { "documentContent":"JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL1N1YnR5cGUgL0ltYWdlCi9UeXBlIC9YT2JqZWN0Ci9XaWR0aCAxMzYyCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9IZWlnaHQgNjI0Ci9CaXRzUGVyQ29tcG9uZW50IDgKL0xlbmd0aCA0MDA2NQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCj4+CnN0cmVhbQp4nO3dB3gU1aRU9GCg==", "documentDetail":{ "shareholderCode":"{hint:The /createAccountHolder response contains a shareholderCode}THE_SHAREHOLDER_WHICH_NEEDS_VERIFICATION{/hint}", "accountHolderCode":"YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "description":"PASSED", "documentType":"PASSPORT", "filename":"document_name_passport.pdf" } } ``` 3. Upload a bank statement on a Hosted Onboarding Page (HOP) or through an API request. * Hosted Onboarding Page * Upload a document with a **PASSED** file name. For example, **PASSED.pdf**. * API * Make another POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request to upload a bank statement: **/uploadDocument request for bank statement upload** ```json { "documentContent":"JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL1N1YnR5cGUgL0ltYWdlCi9UeXBlIC9YT2JqZWN0Ci9XaWR0aCAxMzYyCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9IZWlnaHQgNjI0Ci9CaXRzUGVyQ29tcG9uZW50IDgKL0xlbmd0aCA0MDA2NQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCj4+CnN0cmVhbQp4nO3dB3gU1aRU9GCg==", "documentDetail":{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNTHOLDER_CODE", "bankAccountUUID": "{hint:The /createAccountHolder response contains a bankAccountUUID}THE_BANK_ACCOUNT_UUID_WHICH_NEEDS_VERIFICATION{/hint}", "description":"PASSED", "documentType":"BANK_STATEMENT", "filename":"bank_statement.png" } } ``` The account holder now has its company, identity, document and bank statement verified. ## An account holder with one of KYC checks set to FAILED Select the account holder type to see the relevant examples below: ### Tab: Individual account holder Make a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request to create an account holder. In your request, specify: * `address.city`: **FRAUD** * `bankAccountDetails.ownerCity`: **FRAUD** for all banks accounts. At least one bank account must be defined. * `bankAccountDetails.ownerName`: **TestData** * `individualDetails.name.lastName`: **TestData** * `legalEntity`: **Individual** Here is an example of creating a suspended Individual legal entity account holder with its payouts blocked: **/createAccountHolder request** ```json { "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "city": "FRAUD", "country": "NL", "houseNumberOrName": "1", "postalCode": "1234AB", "street": "Main Street" }, "bankAccountDetails": [ { "countryCode": "NL", "currencyCode": "EUR", "iban": "NL13TEST0123456789", "ownerCity": "FRAUD", "ownerCountryCode": "NL", "ownerHouseNumberOrName": "1", "ownerName": "TestData", "ownerPostalCode": "1234AB", "ownerStreet": "Main Street" } ], "email": "a.holder@example.com", "individualDetails": { "name": { "firstName": "Anthony", "gender": "MALE", "lastName": "TestData" }, "personalData": { "dateOfBirth": "2001-04-27" } }, "phoneNumber": { "phoneCountryCode": "NL", "phoneNumber": "0612345678", "phoneType": "Landline" }, "webAddress": "https://www.example.com" }, "legalEntity": "Individual", "processingTier": 2 } ``` ### Tab: Business account holder Make a POST [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) request to create an account holder. In your request, specify: * `address.city`: **FRAUD** * `bankAccountDetails.ownerCity`: **FRAUD** for all banks accounts. At least one bank account must be defined. * `businessDetails.shareholders.address.city`: **FRAUD** * `businessDetails.shareholders.name.lastName`: **TestData** * `bankAccountDetails.ownerName`: **TestData** * `legalEntity`: **Business** Here is an example of creating a suspended Business legal entity account holder with its payouts blocked: **/createAccountHolder request** ```json { "accountHolderCode": "YOUR_UNIQUE_ACCOUNT_HOLDER_CODE", "accountHolderDetails": { "address": { "city": "FRAUD", "country": "NL", "houseNumberOrName": "1", "postalCode": "1234AB", "street": "Main Street" }, "bankAccountDetails": [ { "countryCode": "NL", "currencyCode": "EUR", "iban": "NL13TEST0123456789", "ownerCity": "FRAUD", "ownerCountryCode": "NL", "ownerHouseNumberOrName": "1", "ownerName": "TestData", "ownerPostalCode": "1234AB", "ownerStreet": "Main Street" } ], "businessDetails": { "doingBusinessAs": "Furniture shop", "legalBusinessName": "TestData", "registrationNumber": "123456789", "shareholders": [ { "address": { "city": "FRAUD", "country": "NL", "houseNumberOrName": "1", "postalCode": "1234AB", "street": "Main Street" }, "email": "testshareholder@example.com", "name": { "firstName": "Anthony", "gender": "MALE", "lastName": "TestData" }, "personalData": { "dateOfBirth": "2001-04-27" } } ], "taxId": "1234567890" }, "email": "a.holder@example.com", "phoneNumber": { "phoneCountryCode": "NL", "phoneNumber": "0612345678", "phoneType": "Landline" }, "webAddress": "https://www.example.com" }, "legalEntity": "Business", "processingTier": 1 } ``` ## An account holder with one of KYC checks set to INVALID\_DATA * Set `address.city` to **INVALIDDATA**. * Set `bankAccount.ownerCity` to **INVALIDDATA** for all banks accounts, which should be marked as Failed. * Set `description` to **INVALIDDATA** for a passport, if you need its KYC check to be marked as Failed. ## An account holder with a PASSPORT\_VERIFICATION KYC check set to INVALID\_DATA You can do this on a Hosted Onboarding Page (HOP) or through an API request. * Hosted Onboarding Page * Upload a document with **INVALIDDATA** in the file name. For example, **INVALIDDATA.jpg**. * API * Make a POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request with: * `documentContent`: A Base64-encoded image larger than 1000 bytes. * `documentType`: **PASSPORT** * `description`: **INVALIDDATA** ## Inactivate an account holder and schedule a refund * Set `address.city` to **INACTIVEDEADLINECITY**. The `/refundNotPaidOutTransfers` call is scheduled to be performed in 6 weeks. ## Inactivate an account holder and make a refund * Set `address.city` to **REFUNDDEADLINECITY**. In this case the `/refundNotPaidOutTransfers` call is performed immediately. ## See also * [API Reference](/classic-platforms/api) * [Error codes](/classic-platforms/error-codes) * [Payouts](/classic-platforms/payouts) * [Verification process](/classic-platforms/verification-process) --- # Source: https://docs.adyen.com/classic-platforms/top-up-accounts.md Section: Classic Platforms integration Title: Top up funds in accounts Description: Let account holders add funds to their account by debiting directly from their bank account. --- title: "Top up funds in accounts" description: "Let account holders add funds to their account by debiting directly from their bank account." url: "https://docs.adyen.com/classic-platforms/top-up-accounts" source_url: "https://docs.adyen.com/classic-platforms/top-up-accounts.md" canonical: "https://docs.adyen.com/classic-platforms/top-up-accounts" last_modified: "2023-02-20T16:53:00+01:00" language: "en" --- # Top up funds in accounts Let account holders add funds to their account by debiting directly from their bank account. [View source](/classic-platforms/top-up-accounts.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. While the funds in account holders' accounts usually come from [payments](/classic-platforms/processing-payments), you can also let them top up their accounts with direct debit. Topping up funds in accounts is useful when: * Covering for possible [negative balances](/classic-platforms/reconciliation-use-cases/build-transactional-ledger#negative-balances), caused by refunds and chargebacks. * Debiting costs from bank accounts when account holders' accounts have insufficient funds. Topping up funds is supported for account holders with bank accounts in the EU, the UK, and the US. The direct debit transactions are processed over corresponding standard debit rails of [Single Euro Payments Area (SEPA)](https://finance.ec.europa.eu/consumer-finance-and-payments/payment-services/single-euro-payments-area-sepa_en), [Bankers' Automated Clearing Services (BACS)](https://www.bacs.co.uk/pages/home.aspx), and [Automated Clearing House (ACH) network](https://www.nacha.org/content/ach-network). ## Requirements Make sure to: * Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable direct debits for your platform. * Have the account holder agree to your platform performing direct debits on their bank account. * When using ACH, business and non-profit account holders must contact their bank and request to allow direct debits from Adyen. Otherwise, banks might block the transactions.\ The bank must allow the following Company or Originator IDs: 2638633811, 9263863381, 8263863381, 4263863381, 3263863381, 2263863380. ## Step 1: Make a direct debit request To start a direct debit, send a POST [/debitAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder) request specifying: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | [accountHolderCode](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-accountHolderCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The code of the account holder. | | [amount](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-amount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The total amount to be debited. When debiting from bank accounts in the EU, the maximum amount is EUR 500 per transaction. | | [bankAccountUUID](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-bankAccountUUID) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the account holder's bank account from which funds are debited. | | [merchantAccount](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-merchantAccount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your merchant account. | | [splits](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-splits) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Array that contains your instructions on how to split the funds between the accounts in your platform. The array must have at least one item. | | [description](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder#request-description) | | Your description for the transaction, which you can use when [reconciling the direct debit](#reconciling-direct-debits). | Here is an example of making a direct debit request for USD 62 split to two accounts: USD 60 to the account holder's account and USD 2 to your platform's liable account. **Direct debit request** ```bash curl https://cal-test.adyen.com/cal/services/Fund/v6/debitAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "ACCOUNT_HOLDER_CODE", "description": "YOUR_DESCRIPTION", "bankAccountUUID": "000b81aa-ae7e-4492-aa7e-72b2129dce0c", "amount": { "value": 6200, "currency": "USD" }, "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "splits": [ { "amount": { "value": 6000 }, "type": "MarketPlace", "account": "8535516988037431", "reference": "YOUR_SPLIT_REFERENCE_1", }, { "amount": { "value": 200 }, "type": "Commission", "reference": "YOUR_SPLIT_REFERENCE_2" } ] }' ``` **Direct debit response** ```json { "pspReference":"8515681150749298", "resultCode":"Received", "accountHolderCode":"ACCOUNT_HOLDER_CODE", "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c", "merchantReferences":["YOUR_SPLIT_REFERENCE_1","YOUR_SPLIT_REFERENCE_2"] } ``` Requests using [/debitAccountHolder](https://docs.adyen.com/api-explorer/Fund/latest/post/debitAccountHolder) are processed asynchronously. You'll receive a response acknowledging that we have received your request, but you must listen to notification webhooks to know the result. ## Step 2. Check the direct debit result Listen to the [DIRECT\_DEBIT\_INITIATED](https://docs.adyen.com/api-explorer/Notification/latest/post/DIRECT_DEBIT_INITIATED) notification webhook and refer to the `status.statusCode` to know the outcome of your request. This webhook has two possible status codes: * **Initiated**: The direct debit has been initiated. As transactions are processed over standard debit rails of ACH, BACS, or SEPA, the funds settle to the accounts based on standard settlement times. Once settled, the transaction is included in [reports](#reconciling-direct-debits). * **Failed**: The direct debit failed. You may receive this notification up to 3 business days after you sent the request. When a direct debit fails, the possible causes are: * Validation errors, such as the [bankAccountUUID](https://docs.adyen.com/api-explorer/Fund/6/post/debitAccountHolder#request-bankAccountUUID) does not exist. * The transaction hit direct debit limits. For example, EUR 500 per transaction for SEPA. * The account holder failed to allow Adyen's Company or Originator IDs with their bank. * Adyen did not receive the funds. * Insufficient funds, or any other refusal from the bank. **Direct debit initiated** ```json { "eventDate": "2021-02-01T14:19:14-08:00", "eventType": "DIRECT_DEBIT_INITIATED", "live": "false", "pspReference": "8515681150749298", "content": { "accountCode": "8825579787887769", "amount": { "currency": "USD", "value": 6200 }, "debitInitiationDate": "2021-02-01", "splits": [ { "account": "8535516988037431", "amount": { "currency": "EUR", "value": 6000 }, "reference": "YOUR_SPLIT_REFERENCE_1", "type": "MarketPlace", }, { "amount": { "currency": "EUR", "value": 200 }, "reference": "YOUR_SPLIT_REFERENCE_2", "type": "Commission", } ], "status": { "statusCode": "Initiated" } } } ``` **Direct debit failed** ```json { "eventDate": "2021-07-07T16:30:37+02:00", "eventType": "DIRECT_DEBIT_INITIATED", "live": "false", "pspReference": "8315659584588245", "content": { "accountCode": "8825579787887769", "amount": { "currency": "EUR", "value": 20000 }, "debitInitiationDate": "2021-07-07", "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT", "splits": [ { "account": "8535516988037431", "amount": { "currency": "EUR", "value": 19000 }, "reference": "YOUR_SPLIT_REFERENCE_1", "type": "MarketPlace" }, { "amount": { "currency": "EUR", "value": 1000 }, "reference": "YOUR_SPLIT_REFERENCE_2", "type": "Commission" } ], "status": { "message": { "code": "10_145", "text": "Failed to initiate the direct debit for account holder." }, "statusCode": "Failed" } } } ``` ## Reconciling direct debits Successful direct debits are settled to your [Adyen merchant account](/classic-platforms/account-structure#your-adyen-account). You can see these transactions in the [Settlement details report](/reporting/settlement-detail-report) with the `Record Type` **MerchantPayin**. When funds are credited to the accounts based on split instructions, the credits are reported in the [Marketplace Payments accounting report](/classic-platforms/reports-and-fees/marketplace-payments-accounting-report). Using this report, you can match the direct debits using the `description` you provided in the `/debitAccountHolder` request. The `description` is included as the **Payment Merchant Reference**. ## See also * [Split payments](/classic-platforms/processing-payments) * [Settlement details report](/reporting/settlement-detail-report) * [Marketplace Payments accounting report](/reporting/settlement-reconciliation/transaction-level/marketplace-payments-accounting-report) --- # Source: https://docs.adyen.com/classic-platforms/verification-process.md Section: Classic Platforms integration Title: Verification process Description: Learn about the verification process and what you need to do to enable payouts. --- title: "Verification process" description: "Learn about the verification process and what you need to do to enable payouts." url: "https://docs.adyen.com/classic-platforms/verification-process" source_url: "https://docs.adyen.com/classic-platforms/verification-process.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process" last_modified: "2023-08-04T12:15:00+02:00" language: "en" --- # Verification process Learn about the verification process and what you need to do to enable payouts. [View source](/classic-platforms/verification-process.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. As required by payment industry regulations, account holders must pass verification checks before you can pay out to them. Account holders are generally required to provide more information after: * They process their first payment. * They advance to the [next tier](/classic-platforms/onboard-users#verification-tiers). The following diagram illustrates the verification process when an account holder signs up to your platform. ![](/user/pages/docs/06.classic-platforms/06.verification-process/verification-process.svg?decoding=auto\&fetchpriority=auto) 1. The account holder provides information when they sign up on your platform, which Adyen uses to verify them. 2. Adyen checks if there are requirements that they need to meet, and runs the required verification based on the details they provided. If the account holder needs to provide more information, they must submit the information within a [deadline](#inactivation-suspension-deadline). Adyen communicates all of these events and timelines through notification webhooks. 3. If the verification fails, the account holder can retry the verification by providing new or revised details. They can also provide additional documents. If the verification is successful, the account holder may start receiving payouts. If verification fails, payouts will not be enabled. ## Required information Adyen determines the required information for checks based on: * The account holder's legal entity type. * The country they are operating in. * Their current tier. * The account holder's [legal arrangements](/classic-platforms/verification-process/legal-arrangements), if applicable. To get a complete list of requirements, refer to [verification requirements](/classic-platforms/verification-process/required-information). ### Owners, controllers, and signatories As part of the checks for an organization, Adyen also verifies the identity of *all* individuals that are associated with the organization. We refer to these individuals as *owners*, *controllers*, and *signatories*. The table below describes the criteria for identifying them, and the minimum required number for each. | Who | Criteria | Required number of individuals | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Owners | Individuals who directly or indirectly own 25% or more of the total shares, voting rights or other equity in the organization. | Between *zero to four*. Adyen requires information about all individuals that fit this criterion. If no one owns 25% or more of the organization, then your user must provide information about a controller. | | Controllers | Any individuals who exercise ultimate effective control in making decisions for the whole company. If such an individual cannot be identified, then members of senior management must be identified as controllers. | *At least one*. Adyen requires information about all individuals that fit this criterion. For the United States of America it is required that *at least one individual is identified*. | | Signatories | Officers or representatives who legally represent the organization towards Adyen and are authorised to enter a binding agreement with Adyen on behalf of their organization. | *At least one*. All signatories are required to be identified. | ## Deadlines for providing information The account holder needs to provide the required information within a deadline. If the information is not sent to Adyen in a timely manner, the account holder status will be changed to inactive, and eventually suspended. Adyen informs your server of upcoming deadlines through [notifications webhooks](#deadline-notifications). | Deadline    | Account holder status | Description | | -------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 30 days after the account holder was required to provide information | **Inactive** | The account holder status is changed to **Inactive**. Payouts are temporarily disabled. You can still update the account holder data to proceed with the verification. | | 42 days after the account holder status was set to **Inactive** | **Suspended** | The account holder status is changed to **Suspended**. All payments that have not been paid out to the account holder are refunded. If you want to update the account holder data to continue with the verification, you must [unsuspend](#unsuspend) the account holder first. | If an account holder cannot meet a deadline, you can choose to [extend the deadline](#deadline-extensions). You can collect information from the account holder and continue the verification at any time after the deadlines. When they pass the verification, the account holder status is set back to **Active**. They can also start processing payments and payouts again. ### Notifications for upcoming deadlines Seven days before the account holder inactivation or suspension, Adyen sends an [ACCOUNT\_HOLDER\_UPCOMING\_DEADLINE](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPCOMING_DEADLINE) notification. You can get the actual date in the `executionDate` field, in YYYY-MM-DD format. When you receive the notification, we recommend that you follow up and remind the account holder to submit the required information. ### Example timeline for deadlines For example, if a new account holder signs up, and processes their first payment on **March 5th**, they will be required to submit information for verification. The following deadlines apply: * **April 5th**: Account holder status will be set to inactive. * **May 18th**: Account holder status will be set to suspended. ![Account suspension](/user/pages/docs/06.classic-platforms/06.verification-process/AccountSuspension.svg?decoding=auto\&fetchpriority=auto) If you want to collect information and continue the verification after **May 18th**, you must [unsuspend the account holder](#unsuspend). ## Deadline extensions The account holder may not be able to meet the inactivation or suspension deadline due to valid reasons. In these cases, you can extend the deadline for an additional *one week*. You can only extend the deadline *once during each deadline period*: once during the account inactivation (T+30 days) and once during the suspension deadline (T+30+42 days). When you extend the deadline for account holder inactivation, the counter for the suspension deadline starts after the extension. The new suspension deadline will be T+30+*7*+42 days. ### Extend a deadline You can extend the deadline in your [Customer Area](https://ca-test.adyen.com/). Your Customer Area user must have the **Merchant Extended Marketplace** user role. 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. Find the account holder and select **Extend one week** in the account holder overview. The **Extend one week** button appears dimmed and is not available if you have previously extended the deadline. ## Unsuspending an account holder You can only unsuspend account holders if they did not fail any verification checks ([ `status` ](/classic-platforms/verification-process/check-verification-results#verification-statuses)**FAILED**). When an account holder has been suspended because they didn't meet a [deadline](#inactivation-suspension-deadline), unsuspending them resets the deadline. They have 42 days to provide information before they are suspended again. You can unsuspend them as many times as you need to. Once unsuspended, their status changes from **Suspended** to **Inactive**, allowing you to update their information. To unsuspend an account holder, you can use [Customer Area](https://ca-test.adyen.com/) or make an API request. ### Tab: Customer Area To unsuspend an account holder in Customer Area, you must have the **Merchant Extended Marketplace** user role. 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform**> **Sub-merchants**. Find the account holder and select **Unsuspend Account Holder**. ### Tab: API To unsuspend an account holder, make POST [/unSuspendAccountHolder](https://docs.adyen.com/api-explorer/#/Account/unSuspendAccountHolder) request, specifying the `accountHolderCode`. **Unsuspend an account holder** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/unSuspendAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"YOUR_UNIQUE_ACCOUNT_HOLDER_CODE" }' ``` If the request is successful, you receive a `pspReference` in the response. Adyen also sends an [ACCOUNT\_HOLDER\_STATUS\_CHANGE](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_STATUS_CHANGE) to inform your server of the change. ## Account holder statuses The account holder status indicates whether an account holder can process payments and payouts. You can check the status of an account holder in the Customer Area, in the API response, and in [webhook notifications](/classic-platforms/notification-types). | Status | Updating data allowed? | Payments allowed? | Payouts allowed? | Description | | ------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") ![-x-](/user/data/smileys/emoji/x.png "-x-") | The default status of an active account holder, where payment processing and payouts are enabled. Payouts can be disabled when the account holder has not yet provided the required information for verification checks, or is required to provide additional information, for example in case of [staggered verification](/classic-platforms/onboard-users#staggered-verification). | | **Inactive** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The account holder did not provide information required for verification checks within the [30-day time limit](#inactivation-suspension-deadline). When the account holder provides the required information, their status is restored to **Active**. | | **Suspended** | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The account holder did not provide information required for verification checks within the [6-week time  limit](#inactivation-suspension-deadline) or they failed verification checks (`checks.status` **FAILED**). When an account holder is suspended, make sure to hide or remove the account holder from your platform to prevent processing of funds. Once suspended, you can only [unsuspend](#unsuspend) or [close](https://docs.adyen.com/api-explorer/Account/latest/post/closeAccountHolder) the account holder if none of the verification checks have a failed status. When you unsuspend them, the status goes back to **Inactive**. | | **Closed** | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The account holder has been closed and no operations are allowed. This status is final. | ## Next steps Find out the kind of information that account holders needs to provide, and how to get the results of the verification. [required](/classic-platforms/verification-process/required-information) [Required information](/classic-platforms/verification-process/required-information) [Get the required information for each country and legal entity type.](/classic-platforms/verification-process/required-information) [required](/classic-platforms/verification-process/document-requirements) [Document uploads](/classic-platforms/verification-process/document-requirements) [Learn more about file size, format, and document type requirements.](/classic-platforms/verification-process/document-requirements) [Legal arrangements](/classic-platforms/verification-process/legal-arrangements) [Additional requirements for account holders with contractual agreements.](/classic-platforms/verification-process/legal-arrangements) [required](/classic-platforms/verification-process/check-verification-results) [Verification results](/classic-platforms/verification-process/check-verification-results) [Track the results of the checks and learn when to retry.](/classic-platforms/verification-process/check-verification-results) --- # Source: https://docs.adyen.com/classic-platforms/verification-process/accepted-data-format.md Section: Classic Platforms integration Title: Accepted data formats Description: Identify the IDs, bank codes, registration and tax ID numbers accepted in different countries. --- title: "Accepted data formats" description: "Identify the IDs, bank codes, registration and tax ID numbers accepted in different countries." url: "https://docs.adyen.com/classic-platforms/verification-process/accepted-data-format" source_url: "https://docs.adyen.com/classic-platforms/verification-process/accepted-data-format.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/accepted-data-format" last_modified: "2023-08-04T12:18:00+02:00" language: "en" --- # Accepted data formats Identify the IDs, bank codes, registration and tax ID numbers accepted in different countries. [View source](/classic-platforms/verification-process/accepted-data-format.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. On this page you'll find accepted formats and examples of data that account holders need to provide. ## Individuals When collecting information from individuals, make sure that: * They do not provide PO boxes as these are not accepted as addresses. * They provide a name that matches their photo ID. This is needed in case they have to submit a photo ID. ### Individuals associated with organizations As part of the checks for an organization, Adyen also verifies the identity of *all* individuals that are associated with the organization. We refer to these individuals as *owners*, *controllers*, and *signatories*. The table below describes the criteria for identifying them, and the minimum required number for each. | Who | Criteria | Required number of individuals | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Owners | Individuals who directly or indirectly own 25% or more of the total shares, voting rights or other equity in the organization. | Between *zero to four*. Adyen requires information about all individuals that fit this criterion. If no one owns 25% or more of the organization, then your user must provide information about a controller. | | Controllers | Any individuals who exercise ultimate effective control in making decisions for the whole company. If such an individual cannot be identified, then members of senior management must be identified as controllers. | *At least one*. Adyen requires information about all individuals that fit this criterion. For the United States of America it is required that *at least one individual is identified*. | | Signatories | Officers or representatives who legally represent the organization towards Adyen and are authorised to enter a binding agreement with Adyen on behalf of their organization. | *At least one*. All signatories are required to be identified. | ### Identification numbers For some countries, account holders are required to provide their national identification number. For others, we highly recommend passing the ID number to to increase the likelihood of passing the checks. If the automatic verification fails, Adyen may require the account holder to provide an [additional document](/classic-platforms/onboard-users/custom-onboarding#upload-documents). | Country | National identification number | Example | | ------------- | ------------------------------------------ | ----------------------- | | Canada | Social Insurance Number | 123-456-789 | | Denmark | Det Centrale Personregister (CPR) | 0102031234 | | Hong Kong | Hong Kong ID (HKID) | X123456A | | Italy | Codice fiscale | MLLSNT82P65Z404U | | Spain | Documento Nacional de Identidad (DNI) | 12345678X | | Sweden | Personnummer (PIN) | 0012193421 | | Singapore | National Registration Identity Card (NRIC) | S7925433I | | United States | Social Security Number | 123-45-6789 **or** 6789 | #### For Australia If an account holder is from Australia, they can provide an ID, passport, visa, or driver's license. When providing a driver's license, we recommend that you provide the issuer state to increase the likelihood of passing the verification. ## Organizations The following data formats apply to data that you can get from businesses, nonprofits, partnerships, and public companies. When collecting information from the account holder, make sure that: * They do not provide PO boxes as these are not accepted as addresses. ### Registration numbers The following registration numbers are accepted for businesses and nonprofits. For nonprofits in some countries, you can upload documents if a nonprofit does not have a registration number. If the automatic verification fails, Adyen may require the account holder to provide an [additional document](/classic-platforms/verification-process/document-requirements#organization-documents). | Country | Registration number | Example | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Australia | Australian Business Number (ABN) or Australian Company Number (ACN) | ABN: 51 064 874 531 ACN: 064 874 531 | | Austria | Firmenbuchnummer | FN123456m | | Belgium | Company Number/Numéro d'entreprise | 1234567890 | | Bulgaria | ЕИК/UIC number | 812114069 | | Canada | Business Number | 123456789 | | Croatia | MBS | 080020970 | | Cyprus | Αριθμός Εγγραφής | C337518 | | Czech Republic | IČO | 123 45 678 | | Denmark | CVR-nummer | 22756214 | | Estonia | Registrikood | 10345833 | | Finland | Y-TUNNUS | 1234567-8 | | France | SIRET number or SIREN number or RNA number (for nonprofits) | SIRET: 542051180-00066 SIREN: 542051180 RNA: W833201200 | | Germany | Handelsregisternummer For nonprofits without a registration number, [upload copy of Articles of Association](/classic-platforms/verification-process/document-requirements#organization-documents). | HRB 100484 HRA 123121 VR 27261 GnR 1234 PR 9876 | | Greece | GEMI number ΑΡΙΘΜΟΣ Γ.Ε.ΜΗ ( Γενικού Εμπορικού Μητρώου) | 757001000000 | | Hong Kong | Business Registration Number (BRN) | 70000000–000-00-00-0 | | Hungary | Cégjegyzékszám | 01-17-000705 | | Ireland | Company Number | 123456 | | Italy | Codice fiscale or CCIAA number | Codice fiscale: 00470400011 CCIAA number: TO0091712 | | Latvia | Reģistrācijas numurs | 50003251661 | | Lichtenstein | Įmonės kodas | 166451720 | | Lithuania | Įmonės kodas | 210316340 | | Luxembourg | RCS number Registernummer Numéro RCS | B12345 or B123456 | | Malta | Company registration number | C 43070 | | Monaco | Numéro de RCI | 56S00448 | | Netherlands | Kamer van Koophandel (KvK) | 34179503 | | Norway | Organisasjonsnummer | 923 609 016 | | Poland | Numer KRS or Numer identyfikacyjny REGON | Numer KRS: 0000123456 Numer identyfikacyjny REGON: 610188201 | | Portugal | NIPC | 123456789 | | Romania | Numar de ordine in registrul comertului | J40/8302/1997 | | Singapore | UEN | 201688888A | | Spain | Número de Identificación Fiscal (NIF) | A39000013 | | Slovakia | Identifikačné číslo (IČO) | 12345679 | | Slovenia | Matična številka | 0101006500006 | | Sweden | Organisationsnummer | 202100-5489 | | Switzerland | UID/IDE/IDI or CH-number | UID/IDE/IDI: CHE123456789 CH-number: CH-550.0.067.293-5 | | United Kingdom | Company Number or Charity number (for nonprofits) For nonprofits without a registration number, [upload copy of Governing or Constitutional Document](/classic-platforms/verification-process/document-requirements#organization-documents). | 04366849 | | United States (including Puerto Rico) | Employer Identification Number (EIN) | 101002749 | ### Company Tax Identification Number Account holders of business legal entity type that have processed payments at a higher tier must provide the company's Tax Identification Number (TIN). The following list contains TINs for each country. For countries that have two TINs available, provide either one. For countries that are not in the list, the tax identification number and business registration numbers are the same. | Country | TIN | Example value | | -------------- | -------------------------------------------------- | ----------------------------- | | Austria | Umsatzsteuer-Identifikationsnummer or Tax number | ATU51507409 or 079/8331 | | Czech Republic | Daňové identifikační číslo | CZ00177041 | | Estonia | VAT/Tax number | EE100254507 | | Germany | Umsatzsteuer-Identifikationsnummer or Steuernummer | DE 115235681 or 143/102/60208 | | | Steuernummer | 143/102/60208 | | Greece | AFM | 94049864 | | Ireland | Value added tax identification number | IE99999999XX | | Latvia | VAT/Tax number | LV43603021620 | | Lithuania | VAT/Tax number | LT664517219 | | Luxembourg | VAT/Tax number Tax Identification Number | LU18928066 2001/2214/155 | | Netherlands | RSIN | 811786523 | | Poland | Numer identyfikacji podatkowej (NIP) number | 7740001454 | | Slovakia | VAT/Tax number | 2020382111 | | Slovenia | VAT/Tax number | 80267432 | ### Supported stock exchanges For businesses that are 100% subsidiaries of companies listed on public stock exchanges or other regulated markets, we require that they provide the stock exchange they are listed in. For example, for parent companies in the US, this means the companies are listed in the New York Stock Exchange, NYSE American, or NASDAQ. Refer to the complete [list of supported stock exchanges](/classic-platforms/verification-process/accepted-data-format/Approved_List_ISO10383_MIC_v2.xlsx). ## Bank accounts Adyen verifies that a bank account exists and that the account holder owns it. We perform the check for every bank account that an account holder adds as a payout method. When collecting information from the account holder, make sure that: * The name of the owner of the bank account matches the name of the account holder. * The country where the bank account is in matches the country where the account holder is operating. ### Countries with IBAN bank accounts For countries where an IBAN is available, you can send either: * The bank account's IBAN * Or a combination of bank code, branch code, and account number ### Branch code In some countries, the bank's branch code may be required. The branch code corresponds to the following values: | Country | Code | Example | | -------------- | -------------- | --------- | | United States | Routing number | 121122676 | | United Kingdom | Sort code | 123456 | --- # Source: https://docs.adyen.com/classic-platforms/verification-process/check-verification-results.md Section: Classic Platforms integration Title: Verification results Description: Keep track of the results of the verification and know when to retry. --- title: "Verification results" description: "Keep track of the results of the verification and know when to retry." url: "https://docs.adyen.com/classic-platforms/verification-process/check-verification-results" source_url: "https://docs.adyen.com/classic-platforms/verification-process/check-verification-results.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/check-verification-results" last_modified: "2021-11-29T09:16:00+01:00" language: "en" --- # Verification results Keep track of the results of the verification and know when to retry. [View source](/classic-platforms/verification-process/check-verification-results.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. You can find out about the verification results by: * Listening to the [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/#/NotificationService/latest/ACCOUNT_HOLDER_VERIFICATION) notification webhook. * Making a [/getAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder) request. * Checking in your Customer Area. ### Tab: Notification Adyen sends an [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notification webhook to inform your server of the results of the check. This notification contains: * [content.kycCheckStatusData.type](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION#request-content-kycCheckStatusData-type): The [type of verification](#verification-types). * [content.kycCheckStatusData.status](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION#request-content-kycCheckStatusData-status): The [status](#verification-statuses) of the check. The status determines if you have further actions to take. * [summary](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION#request-content-kycCheckStatusData-summary): Contains a [verification code](/classic-platforms/verification-process/verification-codes) and a description that provides more information about the results. * [requiredFields](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION#request-content-kycCheckStatusData-requiredFields): An array of fields that are required for the checks. Here is an example notification when the data that the account holder has provided is invalid. **Webhook for check with INVALID\_DATA** ```json { "error": { "errorCode": "1104", "message": "test error message" }, "eventDate": "1970-01-01T01:00:00+01:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "executing-user-key", "live": true, "pspReference": "TSTPSPR0001", "content": { "accountHolderCode": "AH0000001", "kycCheckStatusData": { "type": "PASSPORT_VERIFICATION", "status": "INVALID_DATA", "summary": { "kycCheckCode": 1104, "kycCheckDescription": "Document has expired" }, "requiredFields": [ "field.missing" ] }, "shareholderCode": "SH00000001" } } ``` ### Tab: Customer Area You can view verification statuses in your [Customer Area](https://ca-test.adyen.com/). Your Customer Area user must have the **Merchant MarketPlace role** user role. 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Platform** > **Sub-merchants**. 3. Find the account holder and select the **KYC** tab. Here you can find more information about the verification process, such status of the checks and the tiers for your platform. ### Tab: API You can also make a POST [/getAccountHolder](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder) request to get updates about the verification. Specify the `accountHolderCode` in your request. **/getAccountHolder request** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/getAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode": "YOUR_ACCOUNT_HOLDER_CODE" }' ``` The response returns a [verification](https://docs.adyen.com/api-explorer/Account/6/post/getAccountHolder#responses-200-verification) object. In this object you'll find the resource being verified, along with the following: * [type](https://docs.adyen.com/api-explorer/Account/6/post/getAccountHolder#responses-200-verification-accountHolder-checks-type): The [type of verification](#verification-types). * [status](https://docs.adyen.com/api-explorer/Account/6/post/getAccountHolder#responses-200-verification-accountHolder-checks-status): The [status](#verification-statuses) of the check. The status determines if you have further actions to take. * [summary](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder#responses-200-verification-accountHolder-checks-summary): Contains a [verification code](/classic-platforms/verification-process/verification-codes) and a description that provides more information about the results. * [requiredFields](https://docs.adyen.com/api-explorer/Account/latest/post/getAccountHolder#responses-200-verification-accountHolder-checks-requiredFields): An array of fields that are required for the checks. **/getAccountHolder response** ```json { "pspReference" : "8836183819713023", "accountHolderCode" : "YOUR_ACCOUNT_HOLDER_CODE", ... "verification" : { "accountHolder" : { "checks" : [ { "type" : "IDENTITY_VERIFICATION", "status" : "DATA_PROVIDED" }, { "type" : "PASSPORT_VERIFICATION", "status" : "INVALID_DATA", "summary": { "kycCheckCode": 1104, "kycCheckDescription": "Document has expired" }, "requiredFields": [ "field.missing" ] } ] } } } ``` ## Verification types The verification is categorized into the following checks. | Type | Description | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **COMPANY\_VERIFICATION** | Checks for a business legal entity. | | **IDENTITY\_VERIFICATION** | Checks for an individual account holder. | | **LEGAL\_ARRANGEMENT\_VERIFICATION** | Checks for an account holder with a legal arrangement. | | **NONPROFIT\_VERIFICATION** | Checks for a nonprofit organization. | | **PASSPORT\_VERIFICATION** | Checks for an identification documents such as a passport or driver's license. | | **PAYOUT\_METHOD\_VERIFICATION** | Checks for the payout methods that an account holder adds. This type is sent starting from notification webhook version 6. This replaces **BANK\_ACCOUNT\_VERIFICATION** and **CARD\_VERIFICATION** from earlier versions. | | **PCI\_VERIFICATION** | Checks for PCI SAQ A questionnaire. | ## Verification statuses Below are the different check statuses and the action that you can take. | Verification status | Description | Action to take | | ------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **AWAITING\_DATA** | There is still missing data required for the verification to start. | Get the required information from the account holder. | | **DATA\_PROVIDED** | All the required data has been provided. | None. | | **PENDING** | Verification is in progress. | None. The status will change once the validation is completed. | | **INVALID\_DATA** | There are errors in the data provided. | [Retry the verification](#retry-verification). | | **RETRY\_LIMIT\_REACHED** | The data has been updated too many times. | For some of the checks, you may [retry the verification](#retry-verification). | | **PASSED** | The verification has been completed and the data has passed the checks | None. The account holder can continue processing payments and payouts are enabled. | | **FAILED** | Adyen has verified the information, but has found reasons to refuse working with this entity. | None. This is a final state. When a check fails, the account holder status is set to suspended. | ## Retrying the verification Adyen uses the data from the account holder to automatically run the verification. However, in some cases, automatic verification might fail. This could be due to incorrect data or the data cannot be verified. In general, the following statuses mean that you can retry the verification. * **INVALID\_DATA**: You should ask the account holder to review their data and update when needed. * **RETRY\_LIMIT\_REACHED**: This means that Adyen has tried to verify the account holder more than three times. After the third attempt, Adyen may require additional documents. The following sections are specific for the [verification type](#verification-types). ### For individuals When the **IDENTITY\_VERIFICATION** type has the following statuses, you can ask the account holder to retry. | Status | Action to take | | ------------------------- | --------------------------------------------------------------------------------------------------- | | **INVALID\_DATA** | Ask the account holder to review and update their information. | | **RETRY\_LIMIT\_REACHED** | Upload a [photo ID](/classic-platforms/verification-process/document-requirements#for-individuals). | ### For bank accounts When the **PAYOUT\_METHOD\_VERIFICATION** type has the following statuses, you can ask the account holder to retry. | Status | Action to take | | ------------------------- | --------------------------------------------------------------------------------------------------------- | | **INVALID\_DATA** | Ask the account holder to review and update their information. | | **RETRY\_LIMIT\_REACHED** | Upload a [bank statement](/classic-platforms/verification-process/document-requirements#bank-statements). | ### For organizations When the **COMPANY\_VERIFICATION** or **NONPROFIT\_VERIFICATION** types has an **INVALID\_DATA** status, check the `kycCheckCode` to know if you can retry the verification by uploading documents. * For **API version 5 and later**, refer to [Company check verification codes](/classic-platforms/verification-process/verification-codes#company-verification) for a full list of codes. * For **API version 4 and earlier**, check if the `kycCheckCode` is "**1604: The submitted Taxpayer Identification Number and legal business name do not match. Correct any errors.**" If you receive any of the codes described above, you should: 1. Ask the account holder to review if their company name and business registration number are correct, and update if needed. 2. In case the account holder is certain that their company name and business registration number are correct, give them the *option* to upload a company registration document. 3. If after three attempts you still receive any of `kycCheckCode` described above, *require* the account holder to [upload a company registration document](/classic-platforms/verification-process/document-requirements#organization-documents) in addition to reviewing and updating their company name and registration number. Adyen will use the company registration document to manually verify the company. ## See also * [Onboard and verify users](/classic-platforms/onboard-users) * [Verification requirements](/classic-platforms/verification-process/required-information) --- # Source: https://docs.adyen.com/classic-platforms/verification-process/document-requirements.md Section: Classic Platforms integration Title: Requirements for document uploads Description: Check the size, file format, and other required information when uploading documents. --- title: "Requirements for document uploads" description: "Check the size, file format, and other required information when uploading documents." url: "https://docs.adyen.com/classic-platforms/verification-process/document-requirements" source_url: "https://docs.adyen.com/classic-platforms/verification-process/document-requirements.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/document-requirements" last_modified: "2021-11-17T16:37:00+01:00" language: "en" --- # Requirements for document uploads Check the size, file format, and other required information when uploading documents. [View source](/classic-platforms/verification-process/document-requirements.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Adyen verifies the account holder's entity based on the information provided during onboarding. If the automatic verification fails, due to incorrect data or data that cannot be verified, then Adyen asks the account holder to provide additional documents, such as a passport, bank statement, or a business registration document. A document can be uploaded through: * Adyen's [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page). The account holder can upload their document directly on the page. * Your [own onboarding flow](/classic-platforms/onboard-users/custom-onboarding#upload-documents) where you collect the document yourself and make an API request to Adyen. ## For individuals In the EU, we require photo identification (such as passport) of your account holders. In all countries, if the account holder's identity cannot be validated automatically, Adyen asks the individual to provide a photo ID. ### Photo ID The main types of photos that are accepted are: * Passport: Including the data page, with a picture, details, and the [machine-readable zone](https://en.wikipedia.org/wiki/Machine-readable_passport) clearly visible. * ID card: Including both front and back; each side in a separate file. * Driving license: Including both front and back; each side in a separate file. The name on the photo ID must match the name sent to Adyen during onboarding. If the names are different, for example: an account holder registers with their married name, but their passport shows their maiden name, then the photo ID check fails. If the check fails, the first and last name of the account holder that matches the name shown in the photo ID must be added. If the individual only has one name, they must use this name for both the first and last name fields when creating the account holder. The photo ID must: * Be non-expired. * Have the [machine-readable zone](https://en.wikipedia.org/wiki/Machine-readable_passport) visible (if available). * Be a physical photo ID document, not digital. * If there is an available field for a signature in the document, it must be signed. The uploaded document must: * Have separate files for front and back of the ID document (only when providing an ID card or driver's license). * Be a full color and straightened image. The corners and edges of the ID must be fully visible. * Be a photo or a scan of the physical photo ID document. We do not accept: * Digital IDs. * Secondary copies of IDs. These include screenshots of photos, a photo pasted onto another document, a photo of a screen, or a photo of a printout. * Low-quality images. The uploaded document can be a maximum of 15 pages. #### Additional information for specific countries/regions | Country | Notes | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | France | The validity of French national ID cards issued between 2 January 2004 and 31 December 2013 has been extended for 5 years beyond the original expiration date. The original period of validity of these cards was set at 10 years. Following the extension, they are now valid for 15 years from the year of issue. Note that f the card holder was under the age of 18 when the ID was issued, this extension does not apply. The extension does not apply to any other document types. | | Poland | Polish driving licenses do not show an expiration date. Any licenses issued before 2013/19/01 are valid until 2033. They must be exchanged for a new license prior to this date. | | Ukraine | Ukrainian passports are considered valid for 5 years from the original submission date for the extension of its validity period. A signed and stamped passport page must be included. | ### File format and size requirements * Formats: JPEG, JPG, PNG, or PDF (maximum 2 pages) * Size: minimum 1 KB, maximum 4 MB [![Visual examples of the photo IDs described in this section](/user/pages/reuse/pfs-verification/verification-requirements/photo-id-infographic/photo-id-afp.png)](/user/pages/reuse/pfs-verification/verification-requirements/photo-id-infographic/photo-id-afp.png) ## For organizations If the automatic verification for a business, nonprofit organization, a partnership, or a public company fails, Adyen asks the account holder to provide a copy of their registration document. Documents are verified asynchronously, and on average, the check will take about two days to complete. ### Requirements for the company registration document * Issued by a reliable, independent source, such as the national commercial register of the country where the business is registered in. * Issued within the last (one) year, or contains a signature and a state of affairs with the date not older than one year. ### File format and size requirements * Formats: JPEG, JPG, PNG, or PDF (maximum 2 pages) * Size: * PDFs for [legal arrangement documents](/classic-platforms/verification-process/legal-arrangements#upload-a-document-for-the-legal-arrangement): minimum 1 KB, maximum 25 MB * Other PDFs and other formats: minimum 1 KB, maximum 4 MB ## For bank accounts If Adyen cannot verify a bank account, then we ask your account holder for a scanned bank statement. ### Proof of bank account * Bank statements * Deposit tickets or deposit forms * Screenshots of their online banking environment * Official letters issued by a bank * Cheques Location-specific documents: * Relevé d'Identité Bancaire (RIB): bank document in France * TAMIEYTHPIO: bank document in Greece * Singaporian bank passbooks: bank document in Singapore Do not upload photos of bank-issued cards, such as credit or debit cards. These contain sensitive information. ### Mandatory information * The account holder name. This must match the legal business name, trading (doing business as) name, or the name of the individual conducting business with Adyen, which you set when creating an [account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder). * The account number or IBAN needs to be visible. * The date of issuance needs to be visible and needs to be dated less than 12 months ago. This requirement applies to all types of documents except for RIBs, cheques, online banking environment or TAMIEYTHPIO. Some RIBs and online banking environments contain a date of issuance. The date of issuance for these must also be less than 12 months ago. * The country/region where the bank account is located. For EU bank statements, Adyen infers the country/region from the IBAN. * An indicator that the document was issued by a bank, such as the bank logo or the bank name in its bank-specific font. We do not accept: * Photos of bank-issued cards, such as credit or debit cards. * Edited or personalized documents. * Documents issued more than 12 months ago. * Documents where required data points are missing. * Documents with cut-off, blurry, or low-quality images. * Documents issued by third party software platforms or programs. #### Requirements for specific document types Direct deposit tickets and forms: * Must contain a bank logo or bank letterhead. * Can only be accepted with a stamp or signature from the bank. Cheques: * The name of the account holder, account number, and name of the financial institution or logo need to be printed (not handwritten). * Security features need to be visible for cheques in US and CA. * The account number and routing number need to be fully visible. * We can only accept electronic cheques issued by banks in CA. * We cannot accept any cheques issued by banks in AU. Letters from bank or bank account agreements: * Must contain a bank logo or a bank letterhead. * All letters must have a stamp or signature from the bank. ### File format and size requirements * Formats: JPEG, JPG, PNG, PDF. * No maximum on the number of pages for PDF. * Size: minimum 1 KB, maximum 4 MB ![Visual examples of the bank statements described in this section](/user/pages/reuse/pfs-verification/verification-requirements/bank-document-infographic/bank-document.svg?decoding=auto\&fetchpriority=auto) --- # Source: https://docs.adyen.com/classic-platforms/verification-process/legal-arrangements.md Section: Classic Platforms integration Title: Legal arrangements check Description: Include information about an account holder's legal arrangements. --- title: "Legal arrangements check" description: "Include information about an account holder's legal arrangements." url: "https://docs.adyen.com/classic-platforms/verification-process/legal-arrangements" source_url: "https://docs.adyen.com/classic-platforms/verification-process/legal-arrangements.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/legal-arrangements" last_modified: "2021-07-27T18:50:00+02:00" language: "en" --- # Legal arrangements check Include information about an account holder's legal arrangements. [View source](/classic-platforms/verification-process/legal-arrangements.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. Account holders that conduct business with Adyen on behalf of another entity as established in a contractual agreement must also provide information about their agreement. We refer to contractual agreements as *legal arrangements*. Some examples of legal arrangements are: * Involvement in a trust. For example, a business is a corporate trustee and is conducting business on behalf of the trust. * Sole proprietorship. An individual is registered as a sole proprietor in the country they are operating in. You can onboard account holders with legal arrangements through: * [Hosted onboarding](/classic-platforms/onboard-users/hosted-onboarding-page): HOP supports collecting requirements by default. * Your own onboarding flow: Follow the steps on this page to [collect documents and additional information](#required-information) in your UI and then [send the information](#send-through-api) to Adyen. This requires **API version 6**. The information that account holders provide will be part of the verification checks. Failing to declare legal arrangements can result in blocked payouts and account suspensions. ## Types of legal arrangements Account holders in your platform must provide additional information if they are part of the following legal arrangements. * **Association**\ The account holder, along with one or more associates, manages and shares profits of the business in accordance with agreed upon articles of association. * **Partnership**\ The account holder, along with one or more legal entities (partners), manage, operate and share profits of their jointly-owned business. The account holder is wholly or partially liable for the debts of the partnership. * **Sole proprietorship**\ The individual is registered as a sole proprietor, operates the business on their own, and is personally liable for the debts of the sole proprietorship. * **Trust**\ The account holder (as the trustee) holds and manages assets for the beneficiaries in an agreement laid out in the trust deed. ### Supported legal arrangements Adyen supports different legal arrangements for account holders operating in the following countries. * **Association**: Both the account holder and the association must be operating and established in the US. * **Partnership**: Australia, Singapore * **Sole proprietorship**: Singapore * **Trust**: Australia, Singapore Except for associations, the country where the legal arrangement was established can be different from the account holder's country of operation. ## Step 1: Collect the required information Account holders that are part of a legal arrangement must provide the following additional information. ### Tab: Association If the account holder is a partner conducting business on behalf of the association, they need to provide: * The name of the association. * The country where the association was established. This can be different from the country where the account holder is operating. * The registration number. * Information about other associates. * Their legal entity type. Can be individual, business, nonprofit, or public company. * Their name, birthdate, and address. * Their ID number. ### Tab: Partnership If the account holder is a partner conducting business on behalf of the partnership, they need to provide: * The name of the partnership. * The type of partnership. Refer to [legalForm](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalForm) for possible values. * The country where the partnership was established. This can be different from the country where the account holder is operating. * The registration number. * Information about other partners. * Their legal entity type. Can be individual, business, nonprofit, or public company. * Their name, birthdate, and address. * Their ID number. ### Tab: Sole proprietorship If the account holder is a sole proprietor, they need to provide: * The name of the business. * The country where the sole proprietorship is registered. This can be different from the country where the account holder is operating. * The registration number. ### Tab: Trust If the account holder is a trustee conducting business on behalf of the trust, they need to provide: * The name of the trust. * The type of the trust. Refer to [legalForm](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalForm) for possible values. * The country where the trust was established. This can be different from the country where the account holder is operating. * The registration number of the trust. * A document that proves the trust (required for Australia). * Information about at least one member of the legal arrangement, such as other trustees, settlors, protectors, or beneficiaries. * Their legal entity type. Can be individual, business, nonprofit, or public company. * Their name, birthdate, and address. * Their ID number. Adyen uses the information to run automatic verification checks on the legal arrangement and other parties involved. For example, in a partnership where the other partner is a private company, Adyen performs a company check. If the checks fail, Adyen might require the account holder to provide a document that proves the legal arrangement. ## Step 2: Update the account holder Update an existing account holder and send the information that you received from them in the [legalArrangements](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements) array. ### Tab: Association The following example shows how to update an existing account holder to include information about their association. In your POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request, specify: * The unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). * The [legalArrangements](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements) array containing: * The [legalArrangementReference](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementReference): Your reference for the legal arrangement. * The [type](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-type): Set to **Association**. * The minimum required information you have collected from the account holder, such as the [name](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-name) of the association, [address](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-address-country), and [registrationNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-registrationNumber). * The [legalArrangementEntities](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementEntities): Contains information about other members of the legal arrangement. **Add information about an association** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"ACCOUNT_HOLDER_CODE", "accountHolderDetails":{ "legalArrangements":[ { "legalArrangementReference":"YOUR_REFERENCE", "name":"NAME_OF_ASSOCIATION", "type":"Association", "legalEntityType":"Business", "phoneNumber":{ "phoneCountryCode":"US", "phoneNumber":"0207112304", "phoneType":"Mobile" }, "registrationNumber":"13134A", "email":"entity_001@example.com", "address":{ "city":"San Francisco", "country":"US", "houseNumberOrName":"274", "postalCode":"94107", "stateOrProvince":"CA", "street":"Association street" }, "legalArrangementEntities":[ { "legalEntityType":"Business", "legalArrangementMembers":[ "ControllingPerson", "Shareholder" ], "address":{ "city":"Los Angeles", "country":"US", "houseNumberOrName":"Level 7 - 222", "postalCode":"30000", "stateOrProvince":"CA", "street":"Association Shareholder Street" }, "businessDetails":{ "legalBusinessName":"NAME_OF_SHAREHOLDER_BUSINESS", "shareholders":[ { "address":{ "city":"San Diego", "country":"US", "houseNumberOrName":"50", "postalCode":"88319", "stateOrProvince":"CA", "street":"Partner Street" }, "email":"partnershareholder@example.com", "name":{ "firstName":"Jane", "lastName":"Hopper" }, "personalData":{ "dateOfBirth":"1970-01-01", "documentData":[ { "number":"1994787577", "type":"ID" } ], "nationality":"NL" }, "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"4515076", "phoneType":"Mobile" }, "shareholderCode":"266af44b-733c-4c5e-90c8-f01f84d75ca8" } ] } } ] } ] } }' ``` ### Tab: Partnership The following example shows how to update an existing account holder to include information about their partnership. In your POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request, specify: * The unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). * The [legalArrangements](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements) array containing: * The [legalArrangementReference](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementReference): Your reference for the legal arrangement. * The [type](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-type): Set to **Partnership**. * The [legalForm](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalForm). The structure of the partnership as defined according to the country's legislation. * The minimum required information you have collected from the account holder, such as the [name](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-name) of the partnership, [address](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-address-country), and [registrationNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-registrationNumber). * The [legalArrangementEntities](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementEntities): Contains information about other members of the legal arrangement. **Add information about a partnership** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"ACCOUNT_HOLDER_CODE", "accountHolderDetails":{ "legalArrangements":[ { "legalArrangementReference":"YOUR_REFERENCE", "legalForm":"FamilyPartnership", "name":"NAME_OF_PARTNERSHIP", "type":"Partnership", "legalEntityType":"Business", "phoneNumber":{ "phoneCountryCode":"AU", "phoneNumber":"0207112304", "phoneType":"Mobile" }, "registrationNumber":"13134A", "email":"entity_001@example.com", "address":{ "city":"Sydney", "country":"AU", "houseNumberOrName":"50", "postalCode":"2010", "stateOrProvince":"NSW", "street":"Partnership street" }, "legalArrangementEntities":[ { "legalEntityType":"Business", "legalArrangementMembers":[ "Partner" ], "address":{ "city":"Melbourne", "country":"AU", "houseNumberOrName":"Level 7 - 222", "postalCode":"30000", "stateOrProvince":"VIC", "street":"Trust Legal Arrangement Street" }, "businessDetails":{ "legalBusinessName":"NAME_OF_PARTNER_BUSINESS", "shareholders":[ { "address":{ "city":"Melbourne", "country":"AU", "houseNumberOrName":"50", "postalCode":"88319", "stateOrProvince":"VIC", "street":"Partner Street" }, "email":"partnershareholder@example.com", "name":{ "firstName":"Jane", "lastName":"Hopper" }, "personalData":{ "dateOfBirth":"1970-01-01", "documentData":[ { "number":"1994787577", "type":"ID" } ], "nationality":"NL" }, "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"4515076", "phoneType":"Mobile" }, "shareholderCode":"YOUR_SHAREHOLDER_REFERENCE" } ] } } ] } ] } }' ``` ### Tab: Sole proprietorship The following example shows how to update an individual account holder to include details about their sole proprietorship. In your POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request, specify: * The unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). * The [legalArrangements](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements) array containing: * The [legalArrangementReference](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementReference): Your reference for the legal arrangement. * The [type](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-type): Set to **SoleProprietorship**. * The minimum required information you have collected from the account holder, such as the [name](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-name) of their business, the [address](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-address-country), and the [registrationNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-registrationNumber). **Add information for sole proprietor** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"ACCOUNT_HOLDER_CODE", "accountHolderDetails":{ "legalArrangements":[ { "legalArrangementReference":"YOUR_REFERENCE", "type":"SoleProprietorship", "name":"ABC Business", "address":{ "city":"Melbourne", "country":"AU", "houseNumberOrName":"Level 7 - 222", "postalCode":"30000", "stateOrProvince":"VIC", "street":"Exhibition Street" }, "registrationNumber":"13134A" } ] } }' ``` ### Tab: Trust The following example shows how to update an existing account holder to include information about a trust. In this example, the trust has two additional members - a business settlor and an individual protector. In your POST [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) request, specify: * The unique [accountHolderCode](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderCode). * The [legalArrangements](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements) array containing: * The [legalArrangementReference](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementReference): Your reference for the legal arrangement. * The [type](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-type): Set to **Trust**. * The [legalForm](https://docs.adyen.com/api-explorer/Account/6/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalForm). The structure of the trust as defined according to the country's legislation. * The minimum required information you have collected from the account holder, such as the [name](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-name) of the trust, [address](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-address-country), and [registrationNumber](https://docs.adyen.com/api-explorer/Account/latest/post/createAccountHolder#request-accountHolderDetails-legalArrangements-registrationNumber). * The [legalArrangementEntities](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccountHolder#request-accountHolderDetails-legalArrangements-legalArrangementEntities): Contains information about other members of the legal arrangement. **Add information about a trust** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "accountHolderCode":"ACCOUNT_HOLDER_CODE", "accountHolderDetails":{ "legalArrangements":[ { "legalArrangementReference":"YOUR_REFERENCE", "legalForm":"CashManagementTrust", "name":"NAME_OF_TRUST", "type":"Trust", "registrationNumber":"13134A", "email":"trustarrangement@example.com", "phoneNumber":{ "phoneCountryCode":"AU", "phoneNumber":"0207112304", "phoneType":"Mobile" }, "address":{ "city":"Melbourne", "country":"AU", "houseNumberOrName":"Level 7 - 222", "postalCode":"30000", "stateOrProvince":"VIC", "street":"Trust Legal Arrangement Street" }, "legalArrangementEntities":[ { "legalArrangementEntityReference":"YOUR_ENTITY_REFERENCE", "legalArrangementMembers":[ "Settlor", "Protector" ], "legalEntityType":"Business", "address":{ "city":"Sydney", "country":"AU", "houseNumberOrName":"1/255", "postalCode":"2010", "stateOrProvince":"NSW", "street":"Settlor street" }, "businessDetails":{ "legalBusinessName":"NAME_OF_SETTLOR_BUSINESS", "shareholders":[ { "address":{ "city":"Sydney", "country":"AU", "houseNumberOrName":"50", "postalCode":"2010", "stateOrProvince":"NSW", "street":"Settlor shareholder street" }, "email":"shareholder@example.com", "name":{ "firstName":"John", "lastName":"Smith" }, "personalData":{ "dateOfBirth":"1970-01-01", "documentData":[ { "number":"1994787577", "type":"ID" } ], "nationality":"NL" }, "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"4515076", "phoneType":"Mobile" }, "shareholderCode":"YOUR_SHAREHOLDER_REFERENCE" } ] } }, { "legalArrangementEntityReference":"YOUR_ENTITY_REFERENCE_2", "legalArrangementMembers":[ "Trustee" ], "legalEntityType":"Individual", "phoneNumber":{ "phoneCountryCode":"NL", "phoneNumber":"0207112311", "phoneType":"Mobile" }, "address":{ "city":"Sydney", "country":"AU", "houseNumberOrName":"60", "postalCode":"85058", "stateOrProvince":"NSW", "street":"Protector Street" }, "email":"entity_002@example.com", "individualDetails":{ "name":{ "firstName":"Jane", "lastName":"Hopper" }, "personalData":{ "dateOfBirth":"1970-01-01", "documentData":[ { "number":"2001185217", "type":"ID" } ], "nationality":"NL" } } } ] } ] } }' ``` Requests using [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) are processed asynchronously. You'll receive a response to your API request, but you must rely on notification webhooks to know the final result of a request. * The [ACCOUNT\_HOLDER\_CREATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED) or [ACCOUNT\_HOLDER\_UPDATED](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_UPDATED) webhook: Informs you when the account holder has been successfully updated. You'll get the status of the checks in the [verification](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_CREATED#request-content-verification) object under the `legalArrangements` and `legalArrangementsEntities` arrays. * [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION): Informs you of the status of the verification checks. For legal arrangement checks, refer to the `kyCheckStatusData` object with the `type` **LEGAL\_ARRANGEMENT\_VERIFICATION**. The API response and the webhooks contain the Adyen-generated `legalArrangementCode` and `legalArrangementEntityCode` which you'll use to update the entries or upload documents. **Example ACCOUNT\_HOLDER\_VERIFICATION notification for legal arrangements** ```json { "eventDate": "2019-01-01T01:00:00+01:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "executing-user-key", "live": false, "pspReference": "TSTPSPR0001", "content": { "accountHolderCode": "ACCOUNT_HOLDER_CODE", "payoutMethodCode": "00000000-0000-0000-0000-000000000000", "kycCheckStatusData": { "type": "LEGAL_ARRANGEMENT_VERIFICATION", "status": "PENDING", "summary": { "kycCheckCode": 100, "kycCheckDescription": "Verification check summary description" }, "requiredFields": [ "field.missing" ] }, "shareholderCode": "SH00000001", "legalArrangementEntityCode": "ADYEN-UUID-LAEC-1234-5678", "legalArrangementCode": "ADYEN-UUID-LA-1234-5678" } } ``` ## Step 3: Upload a document You only need to upload a document if: * The account holder is part of a trust in Australia. * The automatic verification failed and Adyen required the account holder to provide a document. The document must prove the account holder's contractual agreement such as a registration or a constitutional document. To upload a document, make a POST [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) request specifying: * [documentType](https://docs.adyen.com/api-explorer/Account/latest/post/uploadDocument#request-documentDetail-documentType) set to **CONSTITUTIONAL\_DOCUMENT**. * The `legalArrangementCode` to which the document must be linked. * The `documentContent` containing the document in Base64-encoded format. In case Adyen is unable to verify the identity of the other members of the legal arrangement, then you'll also be required to upload documents for the member identified by the `legalArrangementEntityCode`. **Upload a constitutional document** ```bash curl https://cal-test.adyen.com/cal/services/Account/v6/uploadDocument \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "documentContent":"dGVzdCBkb2N1bWVudCBjb250ZW50...VcdCB=", "documentDetail":{ "accountHolderCode":"ACCOUNT_HOLDER_CODE", "documentType":"CONSTITUTIONAL_DOCUMENT", "filename": "constitutionalDocument.pdf" } }' ``` Requests using [/uploadDocument](https://docs.adyen.com/api-explorer/#/Account/uploadDocument) are processed asynchronously. You'll receive a response to your API request, but you must rely on notification webhooks to know the final result of a request. * [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION): Informs you of the status of the verification checks. For legal arrangement checks, refer to the `kyCheckStatusData` object with the `type` **LEGAL\_ARRANGEMENT\_VERIFICATION**. ## See also * [Verification process](/classic-platforms/verification-process) --- # Source: https://docs.adyen.com/classic-platforms/verification-process/requirements-update.md Section: Classic Platforms integration Title: Changes to verification requirements Description: Learn about the updates in the verification requirements starting from August 1, 2022. --- title: "Changes to verification requirements" description: "Learn about the updates in the verification requirements starting from August 1, 2022." url: "https://docs.adyen.com/classic-platforms/verification-process/requirements-update" source_url: "https://docs.adyen.com/classic-platforms/verification-process/requirements-update.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/requirements-update" last_modified: "2022-11-11T11:00:00+01:00" language: "en" --- # Changes to verification requirements Learn about the updates in the verification requirements starting from August 1, 2022. [View source](/classic-platforms/verification-process/requirements-update.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. As part of Adyen's ongoing efforts to maintain high verification standards and to comply with local regulations, we started requiring additional information as part of our sub-merchant onboarding procedures since July 15, 2021. The new requirements will be enforced for all platforms as of August 1, 2022. The new information allows us to verify data from sub-merchants better and to ensure compliance with regulations specific to each country of business. On this page, you will learn about these updates and what you need to do to prepare for these changes. To give more time to update integrations, we've postponed enforcing these changes from July 15, 2021 to August 1, 2022. The following requirements apply to all new sub-merchants starting **August 1, 2022**. For existing sub-merchants, we might request additional information from them during our periodic risk assessments, or when an account holder's information or processing tier is updated. ## New requirements * [Distinguish between types of shareholders](#types-of-shareholders) * [Identify signatories](#signatories) * [Identify nationality of natural persons residing in Hong Kong or Singapore](#nationality-hk-singapore) * [Collect principal place of business address](#principal-place-of-business) * [Collect information about parent company](#parent-company-info) * [Collect company Tax Identification Number depending on customer risk classification](#company-tin) * [Stop collecting information about gender](#gender-info) ### Types of shareholders Shareholders can be of two types: * **Owner**: Individuals who directly or indirectly own 25% or more of the total shares, voting rights or other equity in the organization. * **Controller**: Any individuals who exercise ultimate effective control in making decisions for the whole company. If such an individual cannot be identified, then members of senior management must be identified as controllers. We do not limit the number of controllers you can add, but we require that you provide at least one shareholder (owner or controller) for sub-merchants operating in the European Economic Area (EEA). For sub-merchants operating in non-EEA countries, we require that you provide at least one controller. * **Signatory**: Officers or representatives who legally represent the organization towards Adyen and are authorised to enter a binding agreement with Adyen on behalf of their organization. All signatories must be identified. ### Tab: API version v6 and v5 **Owner shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "shareholderType": "Owner", "name": { ... } }] } } } ``` **Controller shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "shareholderType": "Controller", "name": { ... }, "jobTitle": "Chief Executive Officer" }] } } } ``` ### Tab: API version v4 and earlier **Owner shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "ShareholderContact": { "shareholderType": "Owner", "name": { ... } } }] } } } ``` **Controller shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "ShareholderContact": { "shareholderType": "Controller", "name": { ... }, "jobTitle": "Chief Executive Officer" } }] } } } ``` Acceptable `jobTitle` values include: * Chief Executive Officer * Chief Financial Officer * Chief Operating Officer * Chief Information Officer * Chief Strategy Officer * President * Vice President * Executive President * Managing Member * General Partner * Managing Partner * Partner * Treasurer * Director If you need to use a different value, you can specify that value in the `jobTitle` field. ### Signatories We introduce signatories — natural persons that are authorized to act on behalf of or represent the sub-merchant in their relation towards Adyen. We require that such individuals are identified by providing their name, job title, residence address, date of birth, email address, and phone number. Depending on their country of residence, the signatory's ID information may also be required. We do not limit the number of signatories you can add but we require that you provide at least one. ### Tab: API version v6 and v5 **Signatory** ```json { "accountHolderDetails": { "businessDetails": { "signatories": [{ "name": { "firstName": "John", "lastName": "Carpenter" }, "jobTitle": "Chief Executive Officer", "personalData": { "dateOfBirth": "1990-09-09" }, "address": { "city": "San Francisco", "country": "US", "houseNumberOrName": "1", "postalCode": "12345", "street": "Awesome St", "stateOrProvince": "CA" }, "email": "testshareholder@email.com", "fullPhoneNumber": "+31612345678" }] } } } ``` ### Tab: API version v4 and earlier **Signatory** ```json { "accountHolderDetails": { "businessDetails": { "signatories": [{ "SignatoryContact": { "name": { "firstName": "John", "lastName": "Carpenter" }, "jobTitle": "Chief Executive Officer", "personalData": { "dateOfBirth": "1990-09-09" }, "address": { "city": "San Francisco", "country": "US", "houseNumberOrName": "1", "postalCode": "12345", "street": "Awesome St", "stateOrProvince": "CA" }, "email": "testshareholder@email.com", "fullPhoneNumber": "+31612345678" } }] } } } ``` ### Nationality of persons residing in Hong Kong or Singapore For individual account holders, shareholders, and signatories that have an address in Hong Kong or Singapore, Adyen requires information about the nationality of the account holder. **Nationality Account Holder** ```json { "accountHolderDetails": { "individualDetails": { "personalData": { ... "nationality": "SG" } } } } ``` ### Tab: API version v6 and v5 **Nationality Shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "personalData": { "nationality": "SG", } }] } } } ``` ### Tab: API version v4 and earlier **Nationality Shareholder** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "ShareholderContact": { "personalData": { "nationality": "SG", } } }] } } } ``` ### Tab: API version v6 and v5 **Nationality Signatory** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "personalData": { "nationality": "SG" } }] } } } ``` ### Tab: API version v4 and earlier **Nationality Signatory** ```json { "accountHolderDetails": { "businessDetails": { "shareholders": [{ "SignatoryContact": { "personalData": { "nationality": "SG" } } }] } } } ``` ### Principal place of business address If a business's principal place of business is different from its registered address `accountHolder.address`, Adyen requires this to be identified through the `principalBusinessAddress` field. The country of the principal place of business and registered address must be the same. The principal place of business address cannot be a PO Box. **Principal business address (all API versions)** ```json { "accountHolderDetails": { "principalBusinessAddress": { "country": "US", "houseNumberOrName": "5", "postalCode": "94123", "street": "Short Street", "stateOrProvince": "CA", "city": "SF" } } } ``` ### Parent company information For sub-merchants that are 100% subsidiaries of companies listed on public stock exchanges or other regulated markets, we require the following: * `stockExchange`: The 4-character market identifier code, following the ISO Standard format. Here's a complete [list of supported stock exchanges](/classic-platforms/verification-process/requirements-update/Approved_List_ISO10383_MIC_v2.xlsx). For parent companies in the US, this means the companies are listed in the New York Stock Exchange, NYSE American, or NASDAQ. * One of either `stockNumber` or `stockTicker`: * `stockNumber` is the ISIN, a 12-character alphanumeric code, and is defined in [ISO 10383](https://www.iso20022.org/market-identifier-codes). * `stockTicker` is free format. ### Tab: API version v6 and v5 **Public companies** ```json { "accountHolderDetails": { "businessDetails": { "listedUltimateParentCompany": [{ "businessDetails": { "legalBusinessName": "Adyen", "registrationNumber": "123456", "legalEntity": "publicCompany", "stockExchange": "XAMS", "stockTicker": "ADYEN", "stockNumber": "NL0012969182" }, "address": { "country": "NL" } }] } } } ``` ### Tab: API version v4 and earlier **Public companies** ```json { "accountHolderDetails": { "businessDetails": { "listedUltimateParentCompany": [{ "UltimateParentCompany": { "businessDetails": { "legalBusinessName": "Adyen", "registrationNumber": "123456", "legalEntity": "publicCompany", "stockExchange": "XAMS", "stockTicker": "ADYEN", "stockNumber": "NL0012969182" }, "address": { "country": "NL" } } }] } } } ``` ### Company Tax Identification Number Adyen requires the merchant to provide a Tax Identification Number (TIN) for all business sub-merchants that have processed more than USD 1,000. The following list contains TINs for each country. For countries that have two TINs available, provide either one. For countries that are not listed, the Tax Identification Number and Business Registration Number are the same. | Country | TIN | Example value | | -------------- | ------------------------------------------- | ------------- | | Austria | Umsatzsteuer-Identifikationsnummer | ATU51507409 | | | Tax number | 079/8331 | | Czech Republic | Daňové identifikační číslo | CZ00177041 | | Estonia | VAT/Tax number | EE100254507 | | Germany | Umsatzsteuer-Identifikationsnummer | DE 115235681 | | | Steuernummer | 143/102/60208 | | Greece | AFM | 94049864 | | Ireland | Value added tax identification number | IE99999999XX | | Latvia | VAT/Tax number | LV43603021620 | | Lithuania | VAT/Tax number | LT664517219 | | Luxembourg | VAT/Tax number | LU18928066 | | | Tax Identification Number | 2001/2214/155 | | Netherlands | RSIN | 811786523 | | Poland | Numer identyfikacji podatkowej (NIP) number | 7740001454 | | Slovakia | VAT/Tax number | 2020382111 | | Slovenia | VAT/Tax number | 80267432 | **Tax Identification Number (all API versions)** ```json { "accountHolderDetails": { "businessDetails": [{ "taxId": "811786523" }] } } ``` ### Gender information Adyen will no longer require the `gender` field for individuals and shareholders. ## Verification notifications Signatories also go through the verification process similar to shareholders. We will keep you informed about the status through our [ACCOUNT\_HOLDER\_VERIFICATION](https://docs.adyen.com/api-explorer/Notification/latest/post/ACCOUNT_HOLDER_VERIFICATION) notifications. Here are the examples of identity verification notifications: ### Tab: AWAITING\_DATA **IDENTITY\_VERIFICATION** ```json { "eventDate": "2021-07-14T11:17:36+02:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "Account Holder Update", "live": false, "pspReference": "8515748691833060", "content": { "accountHolderCode": "AH1", "kycCheckStatusData": { "type": "IDENTITY_VERIFICATION", "status": "AWAITING_DATA", "requiredFields": ["AccountHolderDetails.BusinessDetails.shareholder", "AccountHolderDetails.BusinessDetails.signatory"] } } } ``` ### Tab: DATA\_PROVIDED **IDENTITY\_VERIFICATION** ```json { "eventDate": "2021-07-14T11:39:23+02:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "Account Holder Update", "live": false, "pspReference": "8515748691833060", "content": { "accountHolderCode": "AH1", "kycCheckStatusData": { "type": "IDENTITY_VERIFICATION", "status": "DATA_PROVIDED" }, "signatoryCode": "d0d93667-89ac-45be-9b9c-c6236049995f" } } ``` Here are the examples of passport verification notifications: ### Tab: AWAITING\_DATA **PASSPORT\_VERIFICATION** ```json { "eventDate": "2021-07-14T11:39:23+02:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "Account Holder Update", "live": false, "pspReference": "8515748691833060", "content": { "accountHolderCode": "AH1", "kycCheckStatusData": { "type": "PASSPORT_VERIFICATION", "status": "AWAITING_DATA", "requiredFields": ["AccountHolderDetails.BusinessDetails.Signatories.Document.document"] }, "signatoryCode": "d0d93667-89ac-45be-9b9c-c6236049995f" } } ``` ### Tab: INVALID\_DATA **PASSPORT\_VERIFICATION** ```json { "eventDate": "2021-07-14T12:03:22+02:00", "eventType": "ACCOUNT_HOLDER_VERIFICATION", "executingUserKey": "Account Holder Verification", "live": false, "pspReference": "8515748691833060", "content": { "accountHolderCode": "AH1", "kycCheckStatusData": { "type": "PASSPORT_VERIFICATION", "status": "INVALID_DATA", "summary": { "kycCheckCode": 1101, "kycCheckDescription": "The ID document does not belong to the configured account holder. Please upload a document that does belong to the account holder or change the details of the account. If the document is the correct one, please double check there are no typing errors in the name or date of birth of the account holder." } }, "signatoryCode": "f42c2593-341c-44af-b4f7-af502e567849" } } ``` ## What do I need to do Here are the necessary steps to ensure compliance with the new verification requirements. Choose your implementation option and proceed with the corresponding instructions: * [Hosted Onboarding Page](#hosted-onboarding-page) (HOP) * [Build your own implementation](#build-own-implementation) ### Hosted Onboarding Page #### Existing sub-merchants For existing sub-merchants, we might request additional information from them during our periodic risk assessments. Notify your existing sub-merchants about the upcoming changes and [start the verification](/classic-platforms/onboard-users/hosted-onboarding-page#get-hosted-onboarding-page-url) process when requested by Adyen. To check which information has been already provided, use the [/getAccountHolder](https://docs.adyen.com/api-explorer/#/Account/getAccountHolder) endpoint. #### New sub-merchants If you are onboarding a new sub-merchant using HOP, Adyen will take care of requesting the necessary information as described in [Step 2](/classic-platforms/onboard-users/hosted-onboarding-page#get-hosted-onboarding-page-url) of the HOP integration page. Alternatively, you can collect all the required information in advance and provide it when creating an account using the [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) endpoint. ### Build your own implementation #### Existing sub-merchants For existing sub-merchants, use the [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) endpoint to provide the above-mentioned required information when requested by Adyen. To check which information has been already provided, use the [/getAccountHolder](https://docs.adyen.com/api-explorer/#/Account/getAccountHolder) endpoint. #### New sub-merchants If you are onboarding a new sub-merchant, proceed with the provided instructions: 1. Create an [account holder](/classic-platforms/account-holders-and-accounts#create-an-account-holder). 2. Collect the above-mentioned [required information](#new-requirements). 3. Use the [/updateAccountHolder](https://docs.adyen.com/api-explorer/#/Account/updateAccountHolder) endpoint to send this information to Adyen as described in [Step 2](/classic-platforms/onboard-users/custom-onboarding#update-account-holder). 4. Follow the rest of the steps from the [Custom onboarding](/classic-platforms/onboard-users/custom-onboarding) page. Alternatively, you can collect all the required information in advance and provide it when creating an account using the [/createAccountHolder](https://docs.adyen.com/api-explorer/#/Account/createAccountHolder) endpoint. Then, skip steps 2 and 3. ## See also * [Onboard and verify users](/classic-platforms/onboard-users) * [Hosted Onboarding Page](/classic-platforms/onboard-users/hosted-onboarding-page) * [Build a custom onboarding application](/classic-platforms/onboard-users/custom-onboarding) --- # Source: https://docs.adyen.com/classic-platforms/verification-process/verification-codes.md Section: Classic Platforms integration Title: Verification codes Description: Review the codes that Adyen sends to inform you of verification errors. --- title: "Verification codes" description: "Review the codes that Adyen sends to inform you of verification errors." url: "https://docs.adyen.com/classic-platforms/verification-process/verification-codes" source_url: "https://docs.adyen.com/classic-platforms/verification-process/verification-codes.md" canonical: "https://docs.adyen.com/classic-platforms/verification-process/verification-codes" last_modified: "2019-09-16T14:19:00+02:00" language: "en" --- # Verification codes Review the codes that Adyen sends to inform you of verification errors. [View source](/classic-platforms/verification-process/verification-codes.md) This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our [new integration guide](/adyen-for-platforms-model) instead. When a verification error occurs, Adyen informs you by sending verification codes and descriptions through [notification webhooks or API responses](/classic-platforms/verification-process/check-verification-results). The descriptions are for you and should not be shared with your account holders as they might communicate information that can be used by malicious third parties. It is better to communicate general failures and request account holders to re-upload their details. On this page, you'll find verification codes for version 5 and later. For version 4 and earlier, refer to [v4 verification codes](/classic-platforms/verification-process/verification-codes/verification-codes-v4). ## Identity verification These codes can be returned when verifying the identity of an account holder. | Code | Description | | ---- | -------------------------------------------------------------------------------------------------- | | 1302 | This user was not found in the database. Please update your personal details or upload a document. | | 1311 | Please provide the identity document of the individual. | | 1312 | Unacceptable risks associated with the accountholder. | | 1304 | The maximum amount of retries has been surpassed. Please do not retry. Please provide a passport. | | 1320 | The user is being manually reviewed by Adyen's onboarding team. | | 1330 | Data is not valid. | ## Document verification These codes can be returned when verifying [document uploads](/classic-platforms/verification-process/document-requirements). | Code | Description | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1101 | The ID document does not belong to the configured account holder. Please upload a document that does belong to the account holder or change the details of the account. If the document is the correct one, please double check there are no typing errors in the name or date of birth of the account holder. | | 1102 | Not all details on document fully visible. | | 1103 | Not a valid/high quality document. | | 1104 | Document has expired. | | 1105 | Document type not supported in this area. | | 1106 | Data is not valid provided. | | 1107 | The maximum amount of retries has been surpassed. Please do not retry. Document verification is pending. | | 1108 | Not all security features are visible or readable in the image. | | 1109 | Unable to process image; the resolution is too low. | | 1110 | Unable to process image; the image is out of focus. | | 1111 | Unable to process image; the image has too much glare. | | 1112 | Unable to process image; the image is poorly exposed. | | 1113 | Unable to process image; the image color depth is too low. | | 1114 | Unable to process image; the image quality is too poor. | | 1115 | Unable to process image; the file format, language, or document type is not supported. | | 1116 | The image is in black and white; please provide a color image. | | 1117 | Unrecognized document; please provide a supported document type. | | 1120 | Possible fraud hit on account details. The user is being manually reviewed by Adyen's onboarding team. | | 1130 | Data is not valid. | | 1151 | Document does not belong to configured account holder. | | 1152 | Not a valid document. | | 1153 | The document is of insufficient image quality, please upload a clearer image. | | 1154 | Document has expired. | | 1155 | Document is not supported in this area; please upload passport or national ID. | | 1156 | MRZ code is missing / obstructed. | | 1157 | Please provide front and back of the ID. | | 1158 | Last name on the document does not match that of accountholder. | | 1159 | First name on the document does not match that of accountholder. | | 1160 | DOB on the document does not match that of the accountholder. | | 1161 | Document contains sensitive information. | ## Bank account verification These codes can be returned when verifying the bank account of an account holder. | Code | Description | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 3101 | Owner and/or account number do not match configured details. | | 3102 | Owner and/or account number missing from document. | | 3103 | Not a valid high quality bank document. | | 3104 | Unable to verify bank account with information provided. Please verify that the information provided is correct. If the information is correct, provide a bank statement clearly showing the bank logo, bank account number, and account holder name. This statement must verify that the bank account details are tied to the individual who is being verified. | | 3105 | Bank statement older than 3 months. | | 3106 | Not a valid bank statement. | | 3109 | The maximum amount of retries has been surpassed, please provide a document. | | 3110 | The maximum amount of retries has been surpassed. Please do not retry. Document verification is pending. | | 3111 | The routing number provided is incorrect. Please provide the correct ABA routing number associated with this account. | | 3112 | The account number provided is incorrect. Please provide the correct account number. | | 3113 | This institution is not programmatically covered. Please use a different financial institution or upload a copy of your bank statement. | | 3114 | This institution is not eligible for payouts on Platforms. Please provide a different bank account. | | 3120 | The user is being manually reviewed by Adyen's onboarding team | | 8000 | There was a technical issue when processing verification checks. A retry has been scheduled. | | 3130 | Data is not valid. | | 3151 | Bank logo not on statement. | | 3152 | Account number not on statement. | | 3153 | Account owner name not on statement. | | 3154 | Account number on statement does not match account holder entered information. | | 3155 | Bank account does not belong to account holder. | | 3156 | Image quality of statement not sufficient. | | 3157 | Document type not accepted. | | 3158 | Bank logo and account number not on statement. | | 3159 | Bank logo, account number, and account owner name not on statement. | | 3160 | Account number, and account owner name not on statement. | | 3161 | Bank logo and account owner name not on statement. | | 3162 | Bank account country does not match accountholder location. | | 3163 | Document contains sensitive information. | ## Company verification These codes can be returned when verifying the company information of an account holder. | Code | Description | | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | 2101 | Business registration and/or company name and/or the shareholders appear to be incorrect. | | 2102 | The maximum amount of retries has been surpassed. Please do not retry. Please provide a document. | | 2120 | The account is under manual risk evaluation, this evaluation may take longer than the usual approval times. | | 2130 | Business registration and/or company name and/or the shareholders appear to be incorrect or cannot be verified. | | 2151 | An individual appears to have on-boarded as a business. Please complete the individual on-boarding flow. | | 2152 | Business entity name could not be verified. | | 2153 | Business registration number could not be verified. | | 2154 | Business VAT number could not be verified. | | 2155 | Could not verify connection between individual listed as shareholder and the legal entity. | | 2156 | The submitted address does not match the company extract. | | 2157 | The submitted business registration number does not match the company extract. | | 2158 | The submitted legal name does not match the company extract. | | 2159 | The doing business as name is provided as legal name. | | 2160 | The submitted country does not match the company extract. | | 2161 | The address is a PO box. | | 2162 | The company extract does not contain the legal name. | | 2163 | The company extract does not contain the business registration number. | | 2164 | Unrecognized document; please provide a supported document type. | | 2165 | Unable to process image; the image quality is too poor. | | 2166 | The legal entity type submitted in the application does not match documentation provided (Trust). Update legal entity type. | | 2167 | The legal entity type submitted in the application does not match documentation provided (Partnership). Update legal entity type. | | 2168 | The legal entity type submitted in the application does not match documentation provided (Business). Update legal entity type. | | 2169 | The legal entity type submitted in the application does not match documentation provided (Individual). Update legal entity type. | ## See also * [Onboard and verify users](/classic-platforms/onboard-users) * [Verification process](/classic-platforms/verification-process) * [Notifications](/classic-platforms/notifications) --- # Source: https://docs.adyen.com/development-resources.md Section: Development resources Title: Development resources Description: Learn what you need to build a successful integration with Adyen. --- title: "Development resources" description: "Learn what you need to build a successful integration with Adyen." url: "https://docs.adyen.com/development-resources" source_url: "https://docs.adyen.com/development-resources.md" canonical: "https://docs.adyen.com/development-resources" last_modified: "2023-09-15T12:30:00+02:00" language: "en" --- # Development resources Learn what you need to build a successful integration with Adyen. [View source](/development-resources.md) ##### Latest news ![](/user/pages/docs/13.development-resources/news.svg?decoding=auto\&fetchpriority=auto) Sign up for our [developer newsletter](https://www.adyen.com/newsletter/developers) and read our [Knowledge Hub](https://www.adyen.com/knowledge-hub) for updates, including [how Adyen is building for AI](https://www.adyen.com/knowledge-hub/how-adyen-does-ai). Start here for everything you need to integrate with Adyen. This page covers AI developer tools like MCP and Agentic Commerce, as well as API credentials, libraries, webhooks, and testing resources. Join the [developer community](#dev-community) for meetups, feedback sessions, demos, and tutorials. ## AI developer tools Build integrations using natural language, make your products discoverable to AI agents, or connect your developer tools to Adyen's documentation. [![](/user/pages/docs/13.development-resources/tech.svg?decoding=auto\&fetchpriority=auto)](/development-resources/mcp-server) ###### [MCP server](/development-resources/mcp-server) [Use natural language with an LLM client to integrate and interact with Adyen APIs.](/development-resources/mcp-server) [![](/user/pages/docs/13.development-resources/paper-plane.svg?decoding=auto\&fetchpriority=auto)](https://www.adyen.com/knowledge-hub/agentic-commerce-control) ###### [Agentic Commerce](https://www.adyen.com/knowledge-hub/agentic-commerce-control) [Enable AI agents to discover your products and process secure payments with Adyen.](https://www.adyen.com/knowledge-hub/agentic-commerce-control) [![](/user/pages/docs/13.development-resources/api-explorer.svg?decoding=auto\&fetchpriority=auto)](/development-resources/documentation-tools) ###### [Documentation and knowledge tools](/development-resources/documentation-tools) [Index, access, and subscribe to Adyen documentation using AI and programmatic tools.](/development-resources/documentation-tools) ## Setup and integration These are some parts of what you need to build your integration. Before you use this section, [choose the type of integration you want to build](/get-started-with-adyen#step-2-build-your-integration) and follow the corresponding integration guide. While you follow the integration guide, you can reference this information. [![](/user/pages/docs/13.development-resources/credentials.svg?decoding=auto\&fetchpriority=auto)](/development-resources/api-credentials) ###### [API credentials](/development-resources/api-credentials) [Authenticate your API requests with Adyen.](/development-resources/api-credentials) [![](/user/pages/docs/13.development-resources/library.svg?decoding=auto\&fetchpriority=auto)](/development-resources/libraries) ###### [Libraries/SDKs](/development-resources/libraries) [Install and use our server-side API libraries/SDKs.](/development-resources/libraries) [![](/user/pages/docs/13.development-resources/event-code.svg?decoding=auto\&fetchpriority=auto)](/development-resources/webhooks) ###### [Webhooks](/development-resources/webhooks) [Receive important updates related to your account.](/development-resources/webhooks) [![](/user/pages/docs/13.development-resources/fingerprint.svg?decoding=auto\&fetchpriority=auto)](/development-resources/client-side-authentication) ###### [Client-side authentication](/development-resources/client-side-authentication) [Learn about the client key and how to generate it.](/development-resources/client-side-authentication) ## Examples and tutorials [![](/user/pages/docs/13.development-resources/postman.svg?decoding=auto\&fetchpriority=auto)](https://www.postman.com/adyendev/) ###### [Postman collections](https://www.postman.com/adyendev/) [Try out the Adyen APIs.](https://www.postman.com/adyendev/) [![](/user/pages/docs/13.development-resources/github.svg?decoding=auto\&fetchpriority=auto)](https://github.com/adyen-examples/) ###### [Example integrations](https://github.com/adyen-examples/) [Official implementation examples for Adyen products and services.](https://github.com/adyen-examples/) [![](/user/pages/docs/13.development-resources/api.svg?decoding=auto\&fetchpriority=auto)](https://github.com/Adyen/adyen-openapi) ###### [OpenAPI](https://github.com/Adyen/adyen-openapi) [Adyen API definition files represented in the OpenAPI specification format.](https://github.com/Adyen/adyen-openapi) [![](/user/pages/docs/13.development-resources/youtube.svg?decoding=auto\&fetchpriority=auto)](https://www.youtube.com/@adyendevs) ###### [Video tutorials](https://www.youtube.com/@adyendevs) [A guided walk-through on how to successfully integrate with Adyen products.](https://www.youtube.com/@adyendevs) ## Developer community [![](/user/pages/docs/13.development-resources/hands11111.svg?decoding=auto\&fetchpriority=auto)](https://www.meetup.com/eu-adyen-developer-events-and-meetups/) ###### [Developer meetup group](https://www.meetup.com/eu-adyen-developer-events-and-meetups/) [Adyen's developer events including feedback sessions, demos, tutorials, meetups, and more.](https://www.meetup.com/eu-adyen-developer-events-and-meetups/) [![](/user/pages/docs/13.development-resources/stackoverflow.svg?decoding=auto\&fetchpriority=auto)](https://stackoverflow.com/tags/adyen) ###### [Stack Overflow](https://stackoverflow.com/tags/adyen) [All questions related to Adyen on the biggest knowledge sharing platform — Stack Overflow.](https://stackoverflow.com/tags/adyen) [![](/user/pages/docs/13.development-resources/twitter.svg?decoding=auto\&fetchpriority=auto)](https://twitter.com/adyendevs) ###### [Twitter](https://twitter.com/adyendevs) [News, announcements, and more in a short familiar format.](https://twitter.com/adyendevs) Reach out to the Developer Experience team with your ideas and feedback at . --- # Source: https://docs.adyen.com/development-resources/api-authentication.md Section: Development resources Title: API authentication types Description: Learn how you can authenticate API requests that you make to Adyen. --- title: "API authentication types" description: "Learn how you can authenticate API requests that you make to Adyen." url: "https://docs.adyen.com/development-resources/api-authentication" source_url: "https://docs.adyen.com/development-resources/api-authentication.md" canonical: "https://docs.adyen.com/development-resources/api-authentication" last_modified: "2021-11-22T14:41:00+01:00" language: "en" --- # API authentication types Learn how you can authenticate API requests that you make to Adyen. [View source](/development-resources/api-authentication.md) Each API request that you make to Adyen must be authenticated. You can use either of the following authentication types: * [API key authentication](#api-key-authentication) * [Basic authentication](#using-basic-authentication) If you are using Adyen's [API libraries](/development-resources/libraries), you only need to generate and provide the credentials for the authentication type that you'll use. The libraries handle authenticating with Adyen. However, if you are making direct calls to Adyen APIs, then you must handle the authentication as described below. ## API key authentication Authenticate your request by sending an API key in an `x-API-key` HTTP request header. **API key in the request header** ```http POST /v68/paymentMethods HTTP/1.1 Host: checkout-test.adyen.com Content-Type: application/json x-API-key: ADYEN_API_KEY ``` You can [generate an API key](/development-resources/api-credentials#generate-api-key) from your Customer Area. ## Basic authentication Authenticate your request by sending a username and password in an `Authorization` HTTP request header. ```http Authorization: Basic YOUR_CREDENTIALS ``` In the header,`YOUR_CREDENTIALS` is the base64 encoded combination of the basic authentication username and password separated by a colon. For example, `ws_12345@Company.YourCompany:YOUR_BASIC_AUTH_PASSWORD`. **Basic authentication in the request header** ```http POST /v68/paymentMethods HTTP/1.1 Host: checkout-test.adyen.com Content-Type: application/json Authorization: Basic d3NfMTIzNDVAQ29tcGFueS5Zb3VyQ29tcGFueTpZT1VSX0JBU0lDX0FVVEhfUEFTU1dPUkQK ``` You can [generate a basic authentication username and password](/development-resources/api-credentials#basic-authentication) from your Customer Area. ## Next steps [Generate your API credentials](/development-resources/api-credentials) [Get your API credentials from your Customer Area.](/development-resources/api-credentials) --- # Source: https://docs.adyen.com/development-resources/api-credentials.md Section: Development resources Title: API credentials Description: Generate and configure credentials for the API requests that you make to Adyen. --- title: "API credentials" description: "Generate and configure credentials for the API requests that you make to Adyen." url: "https://docs.adyen.com/development-resources/api-credentials" source_url: "https://docs.adyen.com/development-resources/api-credentials.md" canonical: "https://docs.adyen.com/development-resources/api-credentials" last_modified: "2021-08-06T10:58:00+02:00" language: "en" --- # API credentials Generate and configure credentials for the API requests that you make to Adyen. [View source](/development-resources/api-credentials.md) To securely authenticate your requests to Adyen's APIs, you need API credentials. These act as the identity for your integration, and ensures that every request is authorized and linked to the correct account. When your account is set up it includes one API credential. You can also create [multiple API credentials](#multiple-api-credentials) to improve security and control access. An API credential consists of: * **Username**: An identifier in the format `ws_123456@Company.[YourCompanyAccount]`. * **API key**: A password to authenticate API requests. * **Roles**: Permissions that define what the credential is allowed to do. API credentials are created automatically during setup. You can manage them within your [Customer Area](https://ca-test.adyen.com/). From there, you can: * [Create additional API credentials](#create-additional-api-credentials) * [Generate an API key](#generate-api-key) * [Configure API permissions](#manage-api-permissions) by assigning specific roles to your credentials ## Requirements Before you begin, take into account the following requirements. | Requirement | Description | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An Adyen integration. | | **[Customer Area roles](/account/user-roles)** | Make sure that your user account has one of the following [roles](/account/user-roles):- **Manage API credentials** role - **Merchant admin** role | ## Multiple API credentials When deciding whether to create multiple API credentials, consider the following trade-offs. Fewer credentials mean fewer API keys to manage, while more credentials provide finer control over permissions and can improve security. For example: * If you have both an online sales channel and a point-of-sale sales channel, we strongly recommend creating a separate API credential for each channel. * If you are doing [unreferenced refunds](/online-payments/classic-integrations/modify-payments/refund#unreferenced-refund) for online payments, we strongly recommend creating a separate credential for processing these refunds. * If you have an ecommerce system and a shipping system, you can separate the permissions for initiating and capturing payments. Some merchants also create separate API credentials for different legal entities or different websites. The number of API credentials you create ultimately depends on how you want to structure access and permissions in your integration. ## Create additional API credentials Your account includes default API credentials with the default account scopes: * Credentials created on a company account can access the company account, including all linked merchant accounts. * Credentials created on a merchant account can only access that merchant account. You can create additional credentials and control their [account scope](#manage-api-scope) to better manage your integration. To create a new API credential: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account. 2. Go to **Developers** > **API credentials**.\ This opens a list with all API credentials linked to your company account. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select ****Create new credential**. 5. In the **Create API credential** dialog, under **Credential type**, select **Web service user**. 6. Optional. In the **Description** field, describe the purpose of the credential. 7. Select **Create credential**. 8. On the **Configure API credentials** page, save the generated **Username**, for example, **ws\_123456\@Company.****\[YourCompanyAccount]**. 9. Under **Server settings** > **Authentication** select the **API key** tab. 10. Select **Generate API key**. 11. Select the copy icon **and store your API key securely in your system. 12. Select **Save changes**. ## Generate an API key Use [API keys to authenticate your requests](/development-resources/api-authentication#api-key-authentication). You can generate a new API key at any time, for example if a key is lost or compromised. When you generate a new API key, it becomes active immediately. The previous key remains active for 24 hours to allow you to update your systems. To generate your API key: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account. 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. Under **Server settings** > **Authentication** select the **API key** tab. 6. Select **Generate API key**. 7. Select the copy icon **and store your API key securely in your system. You cannot copy the API key again after you leave the page. 8. Select **Save changes**. When you switch to your live environment, you must generate a new API key in your [live Customer Area](https://ca-live.adyen.com/). ## Generate a basic authentication password If you are using [basic authentication](/development-resources/api-authentication#using-basic-authentication) to authenticate your API requests, you can generate a basic authentication password for your API credential. When you generate a new basic authentication password, the previous password is deactivated immediately. If you want to continue using your existing password while updating your systems, you can instead [create a new API credential](#create-additional-api-credentials). This allows both credentials to remain active until you have updated your systems. To generate a basic authentication password: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Developers** > **API credentials**.\ A list appears with all API credentials linked to your company account. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username you want to generate the password for. 5. On the **Configure API credential** page, in the **Server settings** section, select **Basic auth**. 6. Select **Generate password**. 7. Select the copy icon **and store your basic authentication password securely in your system. 8. Select **Save changes**. When you switch to your live environment, use the basic authentication credentials from your [live Customer Area](https://ca-live.adyen.com/). ## Manage API permissions Permissions for a API credential are defined by its enabled [roles](/development-resources/api-credentials/roles). An API credential must have at least one enabled role. To manage API permissions: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account. 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. On the **Configure API credential** page, under **Permissions**, expand the categories to see the lists of available roles.\ You can also use the search bar to find specific roles. 6. Select the checkboxes of the roles you want to enable for the API credential. 7. Select **Save changes**. ## Manage API credential account scope The scope of an API credential is determined by the account where it is created. By default, the following applies: * Credentials created on a company account can access the company account, including all linked merchant accounts. * Credentials created on a merchant account can only access that merchant account. To manage the API account scope: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account. 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. On the **Configure API credential** page, under **Accounts**, expand the category to see the available options: * **Company account and all associated merchant accounts** * **Only selected account groups and merchant accounts** You can also use the search bar to locate specific accounts, then select the checkboxes for the accounts you want the API credential to access. 6. Select **Save changes**. ## Reset the expiry time of a previous API key You can reset the expiry time of a previous API key by following these steps: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account. 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. On the **Configure API credential** page, in the **Server settings** section, select **API key**. 6. Under **Expiring keys**, see how much time is left until the previous key expires, and then either: * Select the reset icon **to reset the expiry time to 24 hours. * Select the expire now icon **to expire the previous key immediately. 7. Select **Save changes**. ## Add an allowed IP range As a security measure, you can add allowed IP addresses to your API credential. When you add an allowed IP range, only requests originating from that range will be permitted. To add allowed IP addresses: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. Under **Server settings**, select **Allowed IP range**. 6. Add IP addresses that you want to allow access from. 7. Select **Save changes**. ## Deactivate an API credential API credentials cannot be deleted. However, you can deactivate a credential to prevent its API keys from being used. To deactivate an API credential: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Developers** > **API credentials**. 3. Select the **Payments** or **Platforms** tab, depending on your integration type. 4. Select the credential username. 5. Under **General Settings** use the toggle to switch the webservice user to **Inactive**. 6. Select **Save changes**. This change takes effect immediately and prevents the processing of API requests with this credential. You can switch it back to **Active** at any time to allow API requests again. ## See also * [Online payments](/online-payments) * [In-person payments](/point-of-sale) * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) * [Client-side authentication](/development-resources/client-side-authentication) --- # Source: https://docs.adyen.com/development-resources/api-credentials/roles.md Section: Development resources Title: Roles Description: Find out what roles your API credential needs to do an action. --- title: "Roles" description: "Find out what roles your API credential needs to do an action." url: "https://docs.adyen.com/development-resources/api-credentials/roles" source_url: "https://docs.adyen.com/development-resources/api-credentials/roles.md" canonical: "https://docs.adyen.com/development-resources/api-credentials/roles" last_modified: "2023-06-26T15:25:00+02:00" language: "en" --- # Roles Find out what roles your API credential needs to do an action. [View source](/development-resources/api-credentials/roles.md) API credentials have roles which say what the credential is allowed to do. Your company API credential, for example **ws\@Company.****\[YourCompanyAccount]**, has a set of roles that were assigned by default when the company account was created. These default roles are marked in the tables on this page. Any role that your **ws** credential has, can be assigned to other credentials in your company. These roles are available through the Customer Area UI and through Management API. If you need roles that your **ws** credential doesn't have, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Roles for payments The following table show the most frequently used API credential roles for payments. | Role name | Assigned by default | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Merchant PAL webservice role | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Make API requests to Adyen. If you disable this role, you can no longer process transactions with this API credential. | | Checkout webservice role | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Use our [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview). | | Merchant Recurring role | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Use [tokenization](/online-payments/tokenization) to save shopper's payment details and use them for future payments. | | Data Protection API | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Use the [Data Protection API](/development-resources/data-protection-api), which allowed you to delete data, as required by General Data Protection Regulation (GDPR). | | Checkout encrypted cardholder data | | Use our [Drop-in](/payment-methods/cards/web-drop-in), [Components](/payment-methods/cards/web-component), or [Custom Card fields](/payment-methods/cards/custom-card-integration) to send in encrypted card data. For this role, you need to assess your PCI DSS compliance according to [Self-Assessment Questionnaire A (SAQ A)](/development-resources/pci-dss-compliance-guide?tab=drop_in_or_components_2). | | API PCI Payments role | | If you want to submit payment requests with raw card data, you need to assess your PCI DSS compliance according to [Self-Assessment Questionnaire D (SAQ D)](/development-resources/pci-dss-compliance-guide?tab=api_only_4). If you are using a Service Provider who has access to your shoppers' cardholder data, see the [requirements when using a Service Provider](/development-resources/pci-dss-compliance-guide#service-providers). To enable this role, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | API Payment RefundWithData | | Submit [unreferenced refunds](/online-payments/classic-integrations/modify-payments/refund#unreferenced-refund). To enable this role, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Management API—Assign Terminal | | Use our [Management API](/point-of-sale/automating-terminal-management/assign-terminals-api) to assign payment terminals. | | Cloud Device API role | | Use our [Cloud device API](https://docs.adyen.com/api-explorer/cloud-device-api/latest/overview). | | Allow SDK download for POS developers | | Download the Android and iOS mobile SDKs to use our [Mobile solutions](/point-of-sale/ipp-mobile/). | ## Management API roles The following table show the most frequently used API credential roles for using the Management API. | Role name | Assigned by default | Description | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Management API—Account read | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get the company and merchant accounts that the API credential has access to. | | Management API—Stores read | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get the stores that the API credential has access to. | | Management API—Stores read and write | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get, create, and update the stores that the API credential has access to. | | Management API—API credentials read and write | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get, create, update, and delete the API credentials that the API credential has access to. | | Management API—Users read and write | | Get, create, and update the users that the API credential has access to. | | Management API—Webhooks read | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get the webhooks that the API credential has access to. | | Management API—Webhooks read and write | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get, create, update, and delete the webhooks that the API credential has access to. | | Management API—Payment methods read | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Get the payment methods that the API credential has access to. | | Management API—Payment methods read and write | | Get, create, and update the payment methods that the API credential has access to. | | Management API—Terminal ordering read | | Get the payment terminal orders, shipping locations, and billing locations that the API credential has access to. | | Management API—Terminal ordering read and write | | Get, create, and update the payment terminal orders, shipping locations, and billing locations that the API credential has access to. | | Management API—Terminal settings read | | Get the payment terminal settings that the API credential has access to. | | Management API—Terminal settings read and write | | Get, create, and update the payment terminal general settings that the API credential has access to. | | Management API—Terminal settings Advanced read and write | | Get, create, and update the [sensitive payment terminal settings](/point-of-sale/automating-terminal-management/configure-terminals-api#sensitive-terminal-settings) that the API credential has access to. | | Management API—Terminal actions read | | Get the payment terminal actions that the API credential has access to. | | Management API—Terminal actions read and write | | Get, create, and update the payment terminal actions that the API credential has access to. | | Management API—SplitConfiguration read and write | | Get, create, update, and delete split configuration profiles that determine if and how to split payments in an [Adyen for Platforms](/platforms/process-payments) integration. | --- # Source: https://docs.adyen.com/development-resources/api-idempotency.md Section: Development resources Title: API idempotency Description: Learn how to safely resend API requests without performing the same operation multiple times. --- title: "API idempotency" description: "Learn how to safely resend API requests without performing the same operation multiple times." url: "https://docs.adyen.com/development-resources/api-idempotency" source_url: "https://docs.adyen.com/development-resources/api-idempotency.md" canonical: "https://docs.adyen.com/development-resources/api-idempotency" last_modified: "2020-07-30T16:39:00+02:00" language: "en" --- # API idempotency Learn how to safely resend API requests without performing the same operation multiple times. [View source](/development-resources/api-idempotency.md) The Adyen API supports [idempotency](https://tools.ietf.org/html/rfc7231#section-4.2.2), allowing you to retry a request multiple times while only performing the action once. This helps avoid unwanted duplication in case of failures and retries. For example, in the case of a timeout error, it is possible to safely retry sending the same API payment call multiple times with the guarantee that the payment detail will only be charged once. The accounting rules in the Adyen payments platform take care of most potential double-processing issues that can impact payment [modifications](/get-started-with-adyen/adyen-glossary/#payment-modifications-definition). For example, the following default rules apply: * [Captures](/online-payments/capture): when partial captures are allowed, it is not possible to capture a higher amount than the authorized one. * [Refunds](/online-payments/refund): when multiple refunds are allowed, by default the total refunded value cannot exceed the captured amount. To minimize unwanted side effects when requests are duplicated, you can also take the following actions on your end: * Implement asynchronous server-to-server [webhooks](/development-resources/webhooks). For example, this approach helps keep track of missing responses, a common consequence of a data transmission timeout. * Enable idempotency in your API requests. The Adyen API supports idempotency on POST requests (other request types such as GET, DELETE and PUT are idempotent by definition). ## Enable idempotency To submit a request for idempotent processing, send a request with the `idempotency-key:` in the header. The `` is a unique identifier for the message with a maximum of 64 characters. We recommend using a UUID. If you do not receive a response (for example, in case of a timeout), you can safely retry the request with the same HTTP header. If the Adyen payments platform already processed the request, the response to the first attempt will be returned without duplication. To verify that a request was processed idempotently, check the `idempotency-key` HTTP header returned in the response. Make sure that you code for case-insensitive HTTP headers. Here is an example of how to include the `idempotency-key` in a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request: #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: {hint:Your API key from your Customer Area.}ADYEN_API_KEY{/hint}' \ -H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount": "{hint:Name of your merchant account.}YOUR_MERCHANT_ACCOUNT{/hint}", "reference": "My first Adyen test payment", "amount": { "value": {hint:10 euros in minor units}1000{/hint}, "currency": "EUR" }, "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_4111111111111111", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737" } }' ``` #### Java ```java // Import the required classes import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.service.checkout.PaymentsApi; import com.adyen.model.checkout.*; // Setup the client and service. Client client = new Client("ADYEN_API_KEY", Environment.TEST); PaymentsApi paymentsApi = new PaymentsApi(client); // Create a payment request. PaymentRequest paymentRequest = new PaymentRequest(); paymentRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); CardDetails cardDetails = new CardDetails(); cardDetails.encryptedCardNumber("test_4111111111111111") .encryptedSecurityCode("test_737") .encryptedExpiryMonth("test_03") .encryptedExpiryYear("test_2030"); paymentRequest.setPaymentMethod(new CheckoutPaymentMethod(cardDetails)); Amount amount = new Amount().currency("EUR").value(1000L); paymentRequest.setAmount(amount); paymentRequest.setReference("My first Adyen test payment with an API library/SDK"); paymentRequest.setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy.."); // Add your idempotency key. RequestOptions requestOptions = new RequestOptions(); requestOptions.setIdempotencyKey("YOUR_IDEMPOTENCY_KEY"); // Make a request to the /payments endpoint. PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest, requestOptions); ``` #### PHP ```php // Set up the client and service. $client = new \Adyen\Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(\Adyen\Environment::TEST); $client->setTimeout(30); $service = new \Adyen\Service\Checkout\PaymentsApi($client); $requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY"; // Create a PaymentMethod object. $paymentMethod = new CheckoutPaymentMethod(); $paymentMethod ->setType("scheme") ->setEncryptedCardNumber("test_4111111111111111") ->setEncryptedExpiryMonth("test_03") ->setEncryptedExpiryYear("test_2030") ->setEncryptedSecurityCode("test_737"); // Create an Amount object. $amount = new Amount(); $amount ->setValue(1500) ->setCurrency("EUR"); // Create the PaymentRequest object. $paymentRequest = new PaymentRequest(); $paymentRequest ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setPaymentMethod($paymentMethod) ->setAmount($amount) ->setReference("My first Adyen test payment with an API library/SDK") ->setReturnUrl("https://your-company.example.com/..."); // Make a /payments request. $result = $service->payments($paymentRequest, $requestOptions); ``` #### C\# ```cs using Adyen; using Adyen.Model.Checkout; using Adyen.Service; using Environment = Adyen.Model.Environment; // Create a paymentRequest object. var amount = new Amount("USD", 1000); var paymentRequest = new PaymentRequest { Reference = "My first Adyen test payment with an API library/SDK", Amount = amount, ReturnUrl = @"https://your-company.example.com/...", MerchantAccount = "YOUR_MERCHANT_ACCOUNT", }; // Set up the client and service. var config = new Config { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); var checkout = new PaymentsService(client); // Add your idempotency key. var requestOptions = new RequestOptions { IdempotencyKey= "YOUR_IDEMPOTENCY_KEY" }; // Make a /payments request. var paymentResponse = checkout.Payments(paymentRequest, requestOptions); ``` #### NodeJS (JavaScript) ```js // Step 1: Require the parts of the module you want to use. const { Client, CheckoutAPI} = require('@adyen/api-library'); // Step 2: Initialize the client object. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Step 3: Initialize the API object. const checkoutApi = new CheckoutAPI(client); // Step 4: Create the request object. const paymentRequest = { amount: { currency: "USD", value: 1000 // value in minor units }, reference: "My first Adyen test payment with an API library/SDK", paymentMethod: { type: "scheme", encryptedCardNumber: "test_4111111111111111", encryptedExpiryMonth: "test_03", encryptedExpiryYear: "test_2030", encryptedSecurityCode: "test_737" }, shopperReference: "YOUR_SHOPPER_REFERENCE", storePaymentMethod: true, shopperInteraction: "Ecommerce", recurringProcessingModel: "CardOnFile", returnUrl: "https://your-company.example.com/...", merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Optional: Add your idempotency key. const requestOptions = { "idempotencyKey": "YOUR_IDEMPOTENCY_KEY" }; // Step 5: Make a /payments request. checkoutApi.PaymentsApi.payments(paymentRequest, requestOptions) .then(paymentResponse => console.log(paymentResponse.pspReference)) .catch(error => console.log(error)); ``` #### Ruby ```ruby require 'adyen-ruby-api-library' adyen = Adyen::Client.new adyen.api_key = "ADYEN_API_KEY" headers = {"idempotency-key": "YOUR_IDEMPOTENCY_KEY"} response = adyen.checkout.payments_api.payments({ :amount => { :currency => "EUR", :value => 1000 }, :reference => "My first Adyen test payment with an API library/SDK", :paymentMethod => { :type => "scheme", :encryptedCardNumber => "test_4111111111111111", :encryptedExpiryMonth => "test_03", :encryptedExpiryYear => "test_2030", :encryptedSecurityCode => "test_737" }, :returnUrl => "https://your-company.example.com/checkout/", :merchantAccount => "YOUR_MERCHANT_ACCOUNT" }) ``` ## Key scope and validity time Keys are stored at a company account level. The system checks that the idempotency keys are unique to the company account. Idempotency keys are valid for a minimum period of 7 days after first submission. If you are targeting multiple regional endpoints simultaneously, idempotency keys will not be checked for duplication in other regions. ## Security considerations Generate unique idempotency keys per request using the **version 4 (random)** UUID type to prevent two API credentials under the same account from accessing each others responses. Lowering the access level for an API credential does not prevent them from retrieving past responses if the user still has access to previously used keys. ## Error handling ### Transient errors In rare instances, you could receive a transient error. This is a temporary error that has no side effects and can be retried. For example, it could come from a race condition of sending two payment requests with the same idempotency key at the same time. One will end up being processed while the other will return a transient error. The response will contain an HTTP header **transient-error** with the value **true**, which indicates that the request can be retried at a later time using the same idempotency key. If the API does not return a transient error header, or returns a header with a value of false, do not retry the request. If you submit a duplicate request before the first request has completed, the API returns an **HTTP 422 – Unprocessable Entity** or **HTTP 409 - Conflict** status with the error code **704: "request already processed or in progress"**. ### Retries and exponential backoff Use an exponential backoff strategy when retrying transactions to avoid flooding the API and running into rate-limiting. See [the Wikipedia article on exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) for more information. ### Designing for resilience To enable idempotent behavior, Adyen must retain a consistent, stateful data store to compare each request against. Idempotent processing relies on this data store being available. In the unlikely event that this data store should become unavailable, the API returns an **HTTP 503 – Service Unavailable** status with the error code **703: "required resource temporarily unavailable"**. The system marks the request as a transient error (see above). If there are many of these responses, you can either: * Pause processing and retry the requests later (if this is feasible). * Fall back to non-idempotent processing by not submitting the `idempotency-key` HTTP header. --- # Source: https://docs.adyen.com/development-resources/batch-processing.md Section: Development resources Title: Batch processing Description: Create and upload an input file to process transactions in bulk. --- title: "Batch processing" description: "Create and upload an input file to process transactions in bulk." url: "https://docs.adyen.com/development-resources/batch-processing" source_url: "https://docs.adyen.com/development-resources/batch-processing.md" canonical: "https://docs.adyen.com/development-resources/batch-processing" last_modified: "2019-12-06T09:53:00+01:00" language: "en" --- # Batch processing Create and upload an input file to process transactions in bulk. [View source](/development-resources/batch-processing.md) Batch processing allows you to submit a large number of payment requests or modification requests simultaneously by uploading an input file with the transactions you want us to process in bulk. This is handy for example when you need to process refunds or retry failed captures. Preparing the input file often requires manual effort, so for regular payments or [modifications](/online-payments/modify-payments) it is better to [use the API](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview). ## Batch processing options You can choose from several batch processing possibilities: | Allowed requests | Upload method | Input file | Details | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | [Modification only](/development-resources/batch-processing/submit-modifications) | Customer Area | Simple CSV | Allows modifications for different merchant accounts in the same file.The Customer Area helps you to add missing fields and fix errors. | | [Authorisation, Modification, RefundWithData, Payout, PayoutModification, AccountUpdater, StoreToken](/development-resources/batch-processing/advanced-sftp-batch-files) | SFTP | Complex CSV with headers, footers, counters, and multi-line records | Allows one type of transaction for one merchant account per file.You'll have to set up SFTP, and PGP-encrypt your input files. | ## Choose an option ###### [Submit modifications](/development-resources/batch-processing/submit-modifications) [Create batch files for modifications, and upload in your Customer Area.](/development-resources/batch-processing/submit-modifications) ###### [Submit through SFTP](/development-resources/batch-processing/advanced-sftp-batch-files) [Create batch files for your transactions, and upload through SFTP.](/development-resources/batch-processing/advanced-sftp-batch-files) | | | - | --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files.md Section: Development resources Title: Submit transaction batch files through SFTP Description: Create input files for batch processing of transactions and upload the input file through SFTP. --- title: "Submit transaction batch files through SFTP" description: "Create input files for batch processing of transactions and upload the input file through SFTP." url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files" last_modified: "2020-07-14T13:36:00+02:00" language: "en" --- # Submit transaction batch files through SFTP Create input files for batch processing of transactions and upload the input file through SFTP. [View source](/development-resources/batch-processing/advanced-sftp-batch-files.md) Batch file processing allows you to process multiple transactions in bulk: you submit a file listing all the payments you want us to process. This feature comes in handy when you need to process refunds or retry failed capture attempts, for example. You group all the transactions in a file and then upload it for Adyen to process all the data. Each batch file can hold only one request type per merchant account. Create separate files for each request like authorisation, refund, capture etc. If you need to process modifications for multiple merchant accounts, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this for you. A secure communication channel is required to submit batch files. To achieve that, we use the [SFTP](https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol) transfer protocol and [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) data encryption. ## SFTP configuration Send the following information to the [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to create a secure FTP (SFTP) directory for you to upload your batch files: * **Your Customer Area [company account](/account/account-structure#company-account)**. * **Your source IP address(s)**: the IP addresses of the servers you from which you are going to upload batch request files. Make sure that these are external IP addresses and not your internal network ones. * **Your public SSH key**: you need to generate an RSA SSH key pair (public and private keys). The length of your SSH key must be 2048 bits or 4096 bits. Reference for [Linux/terminal]() OR for [Windows](https://www.ssh.com/academy/ssh/putty/windows/puttygen). * **Technical point of contact**: the names and email addresses of your technical points of contact. You will receive a response from Adyen Support when your SFTP server is configured and ready for you to access. ## Connecting to the SFTP server When you connect to the SFTP server, use the following information: **Test**\ **Host**: `sftp-test.adyen.com`\ **Port**: `5892`\ **User**: the user provided to you by Support. For example: `batch_12345@Company.YOUR_COMPANY_ACCOUNT`.\ **Allowlist host IP**: `213.52.172.120`, `147.12.18.50` **Live**\ **Host**: `sftp-live.adyen.com`\ **Port**: `5631`\ **User**: the user provided to you by Support. For example: `batch_56789@Company.YOUR_COMPANY_ACCOUNT`.\ **Allowlist host IP**: `82.199.87.148` ## PGP encryption To keep your customer data secure, you must encrypt batch files with Adyen's PGP key before uploading them. Then, Adyen processes the batch and signs a [batch result file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file) using Adyen's PGP key. For additional security, you can [register your PGP public key](/development-resources/pgp-encryption#step-2-register-pgp-key-with-adyen) with Adyen. When you register your PGP public key in the Customer Area, Adyen encrypts the batch result file with it. To encrypt with Adyen's PGP key: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Settings** > **Account settings**. 2. Click the **Manage PGP Keys** link. 3. Select the Adyen key you want to use. To download the public part, select **Download**. 4. Encrypt the file with this key before sending it to Adyen. Adyen signs the [batch result file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file) with this key. If you want Adyen to encrypt result files, [register your PGP public key](/development-resources/pgp-encryption#step-2-register-pgp-key-with-adyen) with Adyen, and specify **Batch Files** as the **Purpose** of the key. ### PGP troubleshooting In some cases, your file may be rejected. You receive a [batch acknowledgment file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file) providing details about the rejections. Common causes for batch file rejection are: * You send a PGP-encrypted file whose decryption operation returns errors.\ For example, a failure to verify the signature, or the key used to sign the file is not configured for your company account. * You send a PGP-encrypted file, but you do not have a public key to encrypt the response file. * You send an unencrypted file containing live card numbers. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file.md Section: Development resources Title: Batch acknowledgement file --- title: "Batch acknowledgement file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file" last_modified: "2019-04-29T16:55:00+02:00" language: "en" --- # Batch acknowledgement file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file.md) We describe the fields included in the [batch acknowledgment (ACK) file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure). After validating the submitted batch request file, an ACK file generates: * If the batch request file successfully passes the validation check, the ACK file provides a report overview of the processed data. * If one or more lines in the requested file do not pass the validation check, they are included in the generated ACK file so you can review them. ## ACK - Validation successful After receiving a batch request file, the Adyen payments platform carries out a series of validation checks. If all validation checks are successful, a batch acknowledgment (ACK) file generates and returns with the fields described below. ```text FH,1.0,TEST,Company,TestCompany,CaptureOverAuthAmount,1,ws@Company.TestCompany,Modification,EchoData_BatchAck R,2,8 N,NextFileSubmissionNumber,2 ``` #### File Header \[FH] The File Header \[FH] record marks the start of the ACK file. | Field # | Format | Description | | ------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `FH`. | Record type identifier. | | 2 | Numeric | Version number. This field enables version control for the release of future enhancements for batch processing. | | 3 | Allowed values:- `TEST` - `LIVE` | It specifies the environment: either test or live/production. | | 4 | Fixed value: `Company` | Account type. | | 5 | Alphanumeric | Specifies the company account name. | | 6 | Alphanumeric | Submission platform. The value specified in the file should match the corresponding value in the file name. | | 7 | Numeric | File sequence number. The value specified in the file should match the corresponding value in the file name. | | 8 | Alphanumeric | The username of the API credential linked to your Adyen company account. | | 9 | Allowed values:- `Authorisation` - `Payout` - `RefundWithData` - `Modification` - `PayoutModification` - `AccountUpdater` | File type. Defines the type of transactions that are submitted for further processing. | | 10 | Alphanumeric | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | #### Record Line \[R] The File Trailer record specifies the number of blocks and lines in the ACK file. | Field # | Format | Description | | ------- | ---------------- | --------------------------------- | | 1 | Fixed value: `R` | Record type identifier. | | 2 | Numeric | Number of processed blocks. | | 3 | Numeric | Number of processed line records. | #### Next File Submission Number \[N] This line specifies the number of the next file to process in a batch submission sequence. File sequence numbers are associated with the submission platform the files originate from, and they sequentially increment by one unit after each successful file submission. The `NextFileSubmissionNumber` sub-line is always included in an ACK file, regardless of the file validation outcome: * When a file in a batch process is submitted successfully and without errors, the submission number for the next file in the process increases sequentially. * When a file in a batch process contains errors, the system tries to guess the submission number for the next file in the sequence. Therefore, this value may be incorrect. A correct file in a batch submission process satisfies the following minimum requirements: * The file name adheres to the naming conventions for batch acknowledgement files (ACK). * The file data matches the expected data type and format. The submission number is always incorrect when it is not possible to read or parse the header of a file. This can happen in the following cases: * The file sequence number is missing or it is incorrectly formatted in the file name. * The submission platform name is missing or it is incorrectly formatted in the file name. * A database exception might occur during file insertion. | Field # | Format | Description | | ------- | --------------------------------------- | ------------------------------------------------------------------------------ | | 1 | Fixed value: `N` | Record type identifier | | 2 | Fixed value: `NextFileSubmissionNumber` | Record content definition. | | 3 | Numeric | The number corresponding to the next expected file in the submission sequence. | ## ACK - Validation failed When one or more validation errors occur, an error line gets generated per line in the requested file that did not pass validation. ```text E,L,5,5000,Invalid Merchant Account E,L,6,5000,Invalid Merchant Account N,NextFileSubmissionNumber,2 ``` #### Error Line \[E] The File Header record contains marks the start of the ACK file. | Field # | Format | Description | | ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `E` | Record type identifier | | 2 | Allowed values:- `FH` - `L` - `SL` - `F` | The record type where the error occurred:- `FH`: the error occurred in the *file header*. - `L`: the error occurred in a *line* record. - `SL`: the error occurred in a *sub-line* record. - `F`: the error occurred as the file was incomplete or unreadable. | | 3 | Numeric | The file line number where the error occurred. | | 4 | Numeric | The error code associated with the error. | | 5 | Alphanumeric | The error description. | #### Next File Submission Number \[N] This line specifies the number of the next file to process in a batch submission sequence. File sequence numbers are associated with the submission platform the files originate from, and they sequentially increment by one unit after each successful file submission. The `NextFileSubmissionNumber` sub-line is always included in an ACK file, regardless of the file validation outcome: * When a file in a batch process is submitted successfully and without errors, the submission number for the next file in the process increases sequentially. * When a file in a batch process contains errors, the system tries to guess the submission number for the next file in the sequence. Therefore, this value may be incorrect. A correct file in a batch submission process satisfies the following minimum requirements: * The file name adheres to the naming conventions for batch acknowledgement files (ACK). * The file data matches the expected data type and format. The submission number is always incorrect when it is not possible to read or parse the header of a file. This can happen in the following cases: * The file sequence number is missing or it is incorrectly formatted in the file name. * The submission platform name is missing or it is incorrectly formatted in the file name. * A database exception might occur during file insertion. | Field # | Format | Description | | ------- | --------------------------------------- | ------------------------------------------------------------------------------ | | 1 | Fixed value: `N` | Record type identifier | | 2 | Fixed value: `NextFileSubmissionNumber` | Record content definition. | | 3 | Numeric | The number corresponding to the next expected file in the submission sequence. | --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure.md Section: Development resources Title: Batch file naming and structure --- title: "Batch file naming and structure" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure" last_modified: "2020-04-09T12:29:00+02:00" language: "en" --- # Batch file naming and structure [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure.md) ## Naming ### Batch request file The file name for each batch request file must be unique. To be accepted for further processing, a batch request file name must comply with the following format:  ```text [Submission Platform]_[File Sequence Number]_[FileType].csv ``` * **Submission Platform** is the unique identifier for the server you use to submit batch files to Adyen.\ This is especially important if you have multiple servers submitting files, and find it difficult to keep track of the sequence number across the servers. * **File Sequence Number** is the file submission number. It must always increment by exactly one unit after each successful file submission.\ File sequence numbers correlate with the submission platform, i.e. the server from where the files originate.\ The Adyen payments platform rejects batch files when: * The batch file submission number, i.e. the file sequence number, has already been used; * The system detects a gap in the number sequence because adjacent numbers are not consecutive. For example: 201 followed by 203. * **FileType** defines the type of transactions/requests that the file contains.\ Allowed values: * [`Authorisation`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) * [`Payout`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file) * [`StoreToken`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file) * [`RefundWithData`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file) * [`Modification`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file) * [`PayoutModification`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file) * [`AccountUpdater`](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file) ### Batch result file The file name for each batch result file will be original filename, with `_result` (if the file is not encrypted) or `_result_enc` (if the file is encrypted) appended to the end. | | | | --------------------------------------- | ------------------------------------------------------------------------------ | | *Non-encrypted* batch result file | ``` [Submission Platform]_[File Sequence Number]_[FileType].csv_result ``` | | *Encrypted *batch result file | ``` [Submission Platform]_[File Sequence Number]_[FileType].csv_result_enc ``` | The batch request file undergoes a series of validation checks at line item level, and then the batch result file is posted to the *result* folder on the SFTP. ### Batch acknowledgment file The file name for each batch acknowledgment file will be original filename, with `_ack` appended to the end. ```text [Submission Platform]_[File Sequence Number]_[FileType].csv_ack ``` The batch request file undergoes a series of validation checks at line item level. If any error occurs during the process, the batch acknowledgment file is posted to the *ack* folder on the SFTP. ## Structure The batch file should be delivered in CSV (Comma Separated Values) format, as per [RFC 4180](https://tools.ietf.org/html/rfc4180), with the following exceptions: * Multi-line fields are not allowed; * It is allowed to have a variable number of fields per line.  The file needs to have a file header and a file trailer to allow parsing.\ If either file header or file trailer is missing, it is not possible to top parse the file, and the process returns one or more errors. The batch file has the following structure: ![](/user/pages/docs/13.development-resources/14.batch-processing/03.advanced-sftp-batch-files/02.batch-file-naming-and-structure/batch-file-structure.png) The file must conform to the following parameters: * **File sequence number**: the file header (\[FH]) contains a file sequence number that *must match* the file sequence number in the [file name](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure). * **File types**: the batch file can contain *only one* of the allowed file types identifying the type of transaction that processes.\ It is not allowed to mix file types/transaction types in the same file. i.e. it is not possible to specify more than one file type/transaction type per batch file. * **File encoding**: the batch file should be encoded using [UTF-8](https://en.wikipedia.org/wiki/UTF-8). * **Column counts**: Some lines in the file contain optional fields.\ While the number of fields per line may vary depending on the specified transaction type, the column count per transaction type is fixed.\ For example, [File Header field 9](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file) is an optional field. However, if you do not use it, you need in any case to insert a delimiter as a placeholder. * **Character set**: the character set used to represent text data needs to be [Unicode](http://www.unicode.org/). --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file.md Section: Development resources Title: Batch request file --- title: "Batch request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Batch request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file.md) The following fields are common across all batch request files, regardless of the [transaction type](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure) being submitted. They must be included in each batch request file. ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData ... BT,5 FT,1 ``` #### File Header \[FH] Contains information that is crucial to successfully process the batch file: * It identifies the merchant account the transactions refers to; * It specifies the [file submission number](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure); * It defines the [transaction type](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure) that needs to be processed. | Field # | Format | Required | Description | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: \`FH\` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Fixed value: \`1.0\` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Version number. This field enables version control for the release of future enhancements for batch processing. | | 3 | Allowed values:* `TEST` * `LIVE` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | It specifies the environment: either test or live/production. | | 4 | Fixed value: \`Company\` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the company account name. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Submission platform. The value specified in the file should match the corresponding value in the file name. | | 7 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | File sequence number. The value specified in the file should match the corresponding value in the file name. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The username of the API credential linked to your Adyen company account. | | 9 | Allowed values:* [Authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) * [Payout](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file) * [RefundWithData](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file) * [Modification](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file) * [PayoutModification](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file) * [AccountUpdater](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | File type. Defines the type of transactions that are submitted for further processing. | | 10 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | \`EchoData\` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | #### File Trailer \[FT] Specifies the number of blocks in the batch file. | Field # | Format | Required | Description | | ------- | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------- | | 1 | Fixed value: `FT` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Number of blocks in the file. | #### Block Header \[BH] Notifies the Adyen payments platform about a new grouping of transactions that should be expected. | Field # | Format | Required | Description | | -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `BH` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Block number. | | Its value increments sequentially by one unit per block. | | | | | 3 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | #### Block Trailer \[BT] Specifies the number of lines in the block it refers to. | Field # | Format | Required | Description | | ------- | ----------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ | | 1 | Fixed value: `BT` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Number of line records in the block. | After preparing the batch file as outlined above, you can upload it to the *in* sub-folder of your SFTP folder. The Adyen payments platform can then fetch the file and add it to the processing queue. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file.md Section: Development resources Title: AccountUpdater request file --- title: "AccountUpdater request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file" last_modified: "2019-10-21T13:05:00+02:00" language: "en" --- # AccountUpdater request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/accountupdater-request-file.md) The structure of a batch request file from the Account Updater is as follows. ## AccountUpdater lines The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `L` line record number reference within the batch file block it belongs to.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Fixed value: `AccountUpdater`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## AccountUpdater sub-lines There are two kinds of Account Updater requests: `AccountUpdaterRecurring` request and `AccountUpdaterSingle` request. ### AccountUpdaterRecurring request You can make an `AccountUpdaterRecurring` request when no payment details for the shopper are available.\ The `AccountUpdaterRecurring` request stores shopper payment details in a [recurring contract](/online-payments/classic-integrations/classic-api-integration/tokenization). ### Mandatory sub-lines | Field # | Format | Required | Description | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AccountUpdaterRecurring` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A shopper's reference, which is the unique identifier for a shopper. | | 5 | Allowed values:- If the card details are not stored - The card alias - If the card details are stored: * recurring`DetailReference` Or * `LATEST` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Allowed values:- If the card details are not stored - The card alias - If the card details are stored: * recurring`DetailReference` Or * `LATEST` | ### Example ```text FH,1.0,TEST,Company,TestCompany,Default,1,ws@Company.TestCompany,AccountUpdater,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,AccountUpdater,MerchantReference1,EchoData1 SL,1,AccountUpdaterRecurring,s.hopper@email.com,LATEST BT,1 FT,1 ``` ### AccountUpdaterSingle request You can make an `AccountUpdaterSingle` request when the shopper's card details are at least partially available in your records. You can send live/actual card numbers with your batch file only if you [encrypt the file with PGP](/development-resources/batch-processing/advanced-sftp-batch-files#pgp-encryption) before submitting it. ### Mandatory sub-lines This sub-line holds information about single, ad-hoc account update requests. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AccountUpdaterSingle` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card number or card alias. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month.- Format: `MM`, zero-padded (eg: *03*) | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year.- Format: `YYYY` (eg: *2016*) | | 7 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [CVC code](https://www.cvvnumber.com/cvv.html). Leave this field blank. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Cardholder name. | | 9 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start month.- Format: `MM`, zero-padded (eg: *03*)Maestro UK only. | | 10 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start year.- Format: `YYYY` (eg: *2016*)Maestro UK only. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | One-digit card issue number.Maestro UK only. | ### Example ```text FH,1.0,TEST,Company,TestCompany,Default,1,ws@Company.TestCompany,AccountUpdater,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,AccountUpdater,MerchantReference1,EchoData1 SL,1,AccountUpdaterSingle,4111111111111111,06,2016,,CardHolderName,,, BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file.md Section: Development resources Title: Authorisation request file --- title: "Authorisation request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Authorisation request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file.md) ## Authorisation line The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`L\` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Fixed value: `Authorisation`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## Authorisation sub-lines The number and the type of sub-lines that you need to include varies depending on the payment method specified in the request. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment.md Section: Development resources Title: Authorisation for a card payment --- title: "Authorisation for a card payment" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment" last_modified: "2019-04-29T17:53:00+02:00" language: "en" --- # Authorisation for a card payment [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment.md) ## Mandatory sub-lines You can send this sub-line(s) with your batch file only if you encrypt the file with [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) before submitting it. The [`PaymentDetails` ](#paymentdetails)and [`Card` ](#card)sub-lines described below are mandatory when submitting a card payment authorization request. ### PaymentDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A shopper's reference, which is the unique identifier for a shopper.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | ### Card * This sub-line holds information about card payments. * In an authorization request for card payments, the `Card` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Card` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card number. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month.* Format: `MM`, zero-padded (eg: *03*) | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year.* Format: `YYYY` (eg: *2016*) | | 7 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [CVC code](https://www.cvvnumber.com/cvv.html).* Three-digit CVC/CVV code (Visa, Mastercard, Discover) * Four-digit CVC/CVV code (American Express) | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Cardholder name. | | 9 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start month.* Format: `MM`, zero-padded (eg: *03*)Maestro UK only. | | 10 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start year.* Format: `YYYY` (eg: *2016*)Maestro UK only. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | One-digit card issue number.Maestro UK only. | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,06,2016,737,CardHolderName,,, BT,1 FT,1 ``` ## Optional sub-lines The [ `Address` ](#address), [`MerchantOrderReference` ](#merchantorderreference), and [`ShopperInteraction` ](#shopperinteraction)sub-lines described below can be optionally included in the payment request. ### Address You can use the `Address` sub-line to include information about the shopper's billing and delivery addresses.\ You need to specify billing and deliver addresses on separate `Address` sub-lines: * One `Address` sub-line containing the billing address information; * One `Address` sub-line containing the delivery address information. | **Field #** | **Format** | **Required** | **Description** | | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Address` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `Billing` * `Delivery` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of address that is being submitted: either a billing or a delivery address. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street address. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | City. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ZIP/Post code. | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State/Province/Region. | | 10 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoDataBH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,06,2016,737,CardHolderName,,, SL,3,Address,Billing,South Buena Vista Street,500,Burbank,91521,CA,US SL,4,Address,Delivery,Some Street,123,Some Town,90102,CA,US BT,1 FT,1 ``` ### MerchantOrderReference | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantOrderReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Value of your order reference.  | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,08,2018,737,CardHolderName,,, SL,3,MerchantOrderReference,XY66AB BT,1 FT,1 ``` ### ShopperInteraction | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `ShopperInteraction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:- `Moto` - `ContAuth` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Value of `ShopperInteraction`. In this case, either `Moto` or `ContAuth`.This subline is required only for MOTO or recurring transactions.  | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,06,2016,737,CardHolderName,,, SL,3,Address,Billing,South Buena Vista Street,500,Burbank,91521,CA,US SL,4,Address,Delivery,Some Street,123,Some Town,90102,CA,US SL,6,ShopperInteraction,Moto,,,,,,, BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment.md Section: Development resources Title: Authorisation for a recurring payment --- title: "Authorisation for a recurring payment" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment" last_modified: "2019-05-01T12:58:00+02:00" language: "en" --- # Authorisation for a recurring payment [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment.md) ## Mandatory sub-lines The [`PaymentDetails` ](#paymentdetails), [`Recurring` ](#recurring), [`ShopperInteraction` ](#shopperinteraction)sub-lines described below are mandatory when submitting a recurring payment authorization request. ### PaymentDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A shopper's reference, which is the unique identifier for a shopper. | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | ### Recurring | Field # | Format | Required | Description | | ------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Recurring` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Fixed value: `RECURRING` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of a recurring contract. | | 5 | Allowed values:- Adyen's 16-character unique token, or - `LATEST` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | * The 16-character unique token corresponds to the `selectedRecurringDetailReference` field value. It targets a specific stored recurring data set. * If you specify `LATEST`, the latest/more recent data set is fetched for usage. | ### ShopperInteraction * This sub-line holds information about payments requests involving shopper interaction. * Include a `ShopperInteraction` sub-line when you are submitting these transaction types: * `ContAuth` * `Moto` You can add a `ShopperInteraction` sub-line to any sub-line option that supports a shopper interaction other than `Ecommerce`: * `Authorisation` * `Recurring` * `StoreToken` | Field # | Format | Required | Description | | -------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. | | The counter starts at 1, and it increments sequentially by one unit. | | | | | 3 | Fixed value: `ShopperInteraction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `ContAuth` * `Ecommerce` * `Moto` * `POS` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of shopper interaction transaction to carry out. | Unless you need to perform a MOTO transaction, set this field value to `ContAuth`. ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,Ref123,s.hopper@gmail.com,,, SL,2,Recurring,RECURRING,LATEST SL,3,ShopperInteraction,ContAuth BT,1 FT,1 ``` ## Optional sub-lines The `and` sub-lines described below can be optionally included in the payment request.  ### Address You can use the `Address` sub-line to include information about the shopper's billing and delivery addresses.\ You need to specify billing and deliver addresses on separate `Address` sub-lines: * One `Address` sub-line containing the billing address information; * One `Address` sub-line containing the delivery address information. | **Field #** | **Format** | **Required** | **Description** | | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Address` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `Billing` * `Delivery` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of address that is being submitted: either a billing or a delivery address. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street address. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | City. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ZIP/Post code. | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State/Province/Region. | | 10 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Recurring,RECURRING,LATEST SL,3,ShopperInteraction,ContAuth SL,4,Address,Billing,South Buena Vista Street,500,Burbank,91521,CA,US SL,5,Address,Delivery,Some Street,123,Some Town,90102,CA,US BT,1 FT,1 ``` ### MerchantOrderReference | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantOrderReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Value of your order reference.  | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,08,2018,737,CardHolderName,,, SL,3,MerchantOrderReference,XY66AB BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-ach-direct-debit.md Section: Development resources Title: Authorisation for ACH Direct Debit --- title: "Authorisation for ACH Direct Debit" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-ach-direct-debit" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-ach-direct-debit.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-ach-direct-debit" last_modified: "2019-04-30T14:25:00+02:00" language: "en" --- # Authorisation for ACH Direct Debit [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-ach-direct-debit.md) ## Mandatory sub-lines The [`PaymentDetails` ](#paymentdetails), [`BankAccount` ](#bankaccount), and [`Address` ](#address)sub-lines described below are mandatory when submitting a bank transfer or a ACH Direct Debit (DD) payment authorisation request. ### PaymentDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A shopper's reference, which is the unique identifier for a shopper.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | ### BankAccount * This sub-line holds information about bank transfer payments carried out using the shopper's bank account details. * In an authorisation request for bank account payments, the `BankAccount` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `BankAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter bank account owner name.* Format: `AA` | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account number. | | 7 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ABA routing number/ Branch location number. | ### Address You can use the `Address` sub-line to include information about the shopper's billing and delivery addresses.\ You need to specify billing and deliver addresses on separate `Address` sub-lines: * One `Address` sub-line containing the billing address information; * One `Address` sub-line containing the delivery address information. | **Field #** | **Format** | **Required** | **Description** | | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Address` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `Billing` * `Delivery` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of address that is being submitted: either a billing or a delivery address. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street address. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | City. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ZIP/Post code. | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State/Province/Region. | | 10 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | Sample authorisation for ACH Direct Debit file: ``` SL,1,PaymentDetails,100,2,USD,,,,, SL,2,BankAccount,Adyen Inc,US,4780345603,066000359 SL,3,Address,Billing,South Buena Vista Street,500,Burbank,91521,CA,US ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment.md Section: Development resources Title: Authorisation for an IBAN payment --- title: "Authorisation for an IBAN payment" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment" last_modified: "2019-04-30T17:18:00+02:00" language: "en" --- # Authorisation for an IBAN payment [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment.md) ## Mandatory sub-lines The [`PaymentDetails` ](#paymentdetails)and [`IBAN` ](#iban)sub-lines described below are mandatory when submitting a bank transfer or a SEPA Direct Debit (DD) payment authorisation request. ### PaymentDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A shopper's reference, which is the unique identifier for a shopper.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | ### IBAN * This sub-line holds information about bank transfer or SEPA Direct Debit (DD) payments carried out using the shopper's IBAN details. * In an authorization request for IBAN payments, the `IBAN` sub-line needs to be submitted as *sub-line 2*. | Field # | Format | Required | Description | | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `IBAN` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric Cannot be only numbers. Minimum three characters. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. If provided details do not match the required format, the response returns the error message: 203 'Invalid bank account holder name'. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [IBAN code](https://en.wikipedia.org/wiki/International_Bank_Account_Number). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [BIC code](https://en.wikipedia.org/wiki/ISO_9362). | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,IBAN,A. Klaassen,NL,NL13TEST0123456789, BT,1 FT,1 ``` ## Optional sub-lines The [ `Address` ](#address), and [`MerchantOrderReference` ](#merchantorderreference)sub-lines described below can be optionally included in the payment request.  ### Address You can use the `Address` sub-line to include information about the shopper's billing and delivery addresses.\ You need to specify billing and deliver addresses on separate `Address` sub-lines: * One `Address` sub-line containing the billing address information; * One `Address` sub-line containing the delivery address information. | **Field #** | **Format** | **Required** | **Description** | | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Address` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `Billing` * `Delivery` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of address that is being submitted: either a billing or a delivery address. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street address. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | City. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ZIP/Post code. | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State/Province/Region. | | 10 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,IBAN,A. Klaassen,NL,NL13TEST0123456789, SL,3,Address,Billing,South Buena Vista Street,500,Burbank,91521,CA,US SL,4,Address,Delivery,Some Street,123,Some Town,90102,CA,US BT,1 FT,1 ``` ### MerchantOrderReference | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantOrderReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Value of your order reference.  | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,08,2018,737,CardHolderName,,, SL,3,MerchantOrderReference,XY66AB BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-with-airline-data.md Section: Development resources Title: Authorisation with airline data --- title: "Authorisation with airline data" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-with-airline-data" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-with-airline-data.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-with-airline-data" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Authorisation with airline data [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-with-airline-data.md) When you send an authorisation request with a batch file submission, you can include [airline data information](#airline-data-sub-lines). To do so, you append the relevant airline data as sub-lines to the [card payment](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-card-payment), [IBAN payment](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-an-iban-payment) or [recurring payment](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file/authorisation-for-a-recurring-payment) authorisation requests. Below you can find an overview of the airline data sub-lines you can pass with the batch file requests. ## Airline data sub-lines Below you can find an overview of the airline data sub-lines you can pass with the batch file requests. ### Airline This sub-line holds information about airline data information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline) for details. | Field # | Format | Required | Description | | ------- | ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Airline` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Customer reference identifier/number. | | 5 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Airline code. | | 6 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Airline designator code. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Ticket issue address. | | 8 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Ticket number. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Travel agency code. | | 10 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Travel agency name. | | 11 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Agency plan name. | | 12 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Agency invoice number. | Example of isolated airline data batch file sub-line: ```text SL,3,Airline,BVQT04,074,KL,5th avenue 66,100020003034,12345678,,,, ``` Example of airline data batch file sub-line in a batch file context: ```text FH,1.0,DEVL,Company,TestCompany,Default,27,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,CaptureWithExternalAuth,Test Product 3,123456 SL,1,PaymentDetails,10000,2,EUR SL,2,Card,4111111111111111,6,2016,737,CardHolderName,,, SL,3,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,4,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,5,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,8,ShopperInteraction,Ecommerce BT,1 FT,1 ``` ### AirlineLeg This sub-line holds information about airline leg information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. If you include airline data in your request, the batch file needs to contain *at least one airline leg* sub-line as well. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline-airline-leg-carrier_code) for details. | Field # | Format | Required | Description | | ------- | ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AirlineLeg` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Leg number identifier. The counter starts at 1, and it increments sequentially by one unit. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Departure airport. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Flight number. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Carrier code. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [Fare basis code](https://en.wikipedia.org/wiki/Fare_basis_code). | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Travel class identifier. | | 10 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Stopover code. | | 11 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Destination code. | | 12 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Travel date. | | 13 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [Departure tax](https://en.wikipedia.org/wiki/Departure_tax). | Example of isolated airline leg data batch file sub-line: ```text SL,4,AirlineLeg,1,AMS,12345,AA,Y123456,B,O,LON,2014-08-02T19:05:00.000,Y ``` Example of airline leg data batch file sub-line in a batch file context: ```text FH,1.0,DEVL,Company,TestCompany,Default,27,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,CaptureWithExternalAuth,Test Product 3,123456 SL,1,PaymentDetails,10000,2,EUR SL,2,Card,4111111111111111,6,2016,737,CardHolderName,,, SL,3,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,4,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,5,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,8,ShopperInteraction,Ecommerce BT,1 FT,1 ``` ### AirlinePassenger This sub-line holds information about airline passenger information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. If you include airline data in your request, besides at least one airline leg sub-line the batch file needs to contain at least one airline passenger sub-line as well. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline-airline-passenger_name) for details. | Field # | Format | Required | Description | | ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AirlinePassenger` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger number identifier. The counter starts at 1, and it increments sequentially by one unit. | | 5 | Fixed value: `Name` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger data type. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger's first/given name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger's last/family name. | | 8 | Format: `yyyy-MM-dd` For example: *1980-02-28* | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Passenger's birth date. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Traveller type. Passenger type code (PTC). | Example of isolated airline passenger data batch file sub-line: ```text SL,1,PaymentDetails,100,2,EUR,,,,, SL,2,Card,4111111111111111,6,2016,737,CardHolderName,,, SL,3,Airline,BVQT04,074,KL,5th avenue 66,100020003034,12345678,,, SL,4,AirlineLeg,1,AMS,12345,AA,Y123456,B,O,LON,2014-08-02T19:05:00.000,Y SL,5,AirlinePassenger,1,Name,John,Doe,1979-02-28,, ``` Example of airline passenger data batch file sub-line in a batch file context: ```text FH,1.0,DEVL,Company,TestCompany,Default,27,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,CaptureWithExternalAuth,Test Product 3,123456 SL,1,PaymentDetails,10000,2,EUR SL,2,Card,4111111111111111,6,2016,737,CardHolderName,,, SL,3,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,4,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,5,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,8,ShopperInteraction,Ecommerce BT,1 FT,1 ``` ## Optional sub-lines The `MerchantOrderReference` sub-line described below can be optionally included in the payment request. ### MerchantOrderReference | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantOrderReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Value of your order reference.  | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Authorisation,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Authorisation,Test Product 6, SL,1,PaymentDetails,100,2,SEK,,,,, SL,2,Card,4111111111111111,08,2018,737,CardHolderName,,, SL,3,MerchantOrderReference,XY66AB BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file.md Section: Development resources Title: Modification request file --- title: "Modification request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Modification request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file.md) ## Modification line The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`L\` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Allowed values:- `AuthoriseReferral` - `Cancel` - `Capture` - `Refund` - `CancelOrRefund` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A merchant reference, that is, a unique identifier associated to a specific transaction.As for modification requests, the merchant reference value can either:- Keep the same value and refer to the original payment authorisation reference. Or - Take a new reference value for the modification request in question. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## Modification sub-lines The number and the type of sub-lines that you need to include varies depending on the modification request you are submitting. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/authorisationreferral-request.md Section: Development resources Title: AuthorisationReferral request --- title: "AuthorisationReferral request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/authorisationreferral-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/authorisationreferral-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/authorisationreferral-request" last_modified: "2019-04-30T17:21:00+02:00" language: "en" --- # AuthorisationReferral request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/authorisationreferral-request.md) When you process [MOTO transactions](/online-payments/classic-integrations/hosted-payment-pages/skin/moto-feature), you may need to handle transactions with a resulting `Declined` status and a corresponding `Referral` reason. If the shopper contacted their issuing bank and you have the [authorisation code](https://docs.adyen.com/api-explorer/#/Payment/latest/authorise__section_resParams) for the transaction, you can submit it in a batch file to update the transaction in the Adyen payments platform. When we receive and process the batch file, we book a new `Authorised` journal entry for the transaction and then proceed with the standard workflow. ![](/user/pages/docs/13.development-resources/14.batch-processing/03.advanced-sftp-batch-files/03.batch-request-file/02.modification-request-file/01.authorisationreferral-request/AuthorisationReferral-request.png) ## Mandatory sub-lines The [`PaymentDetails` ](#paymentdetails)and [`AuthoriseReferral` ](#authorisereferral)sub-lines described below are mandatory when submitting a bank transfer authorisation request. ### PaymentDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A shopper's reference, which is the unique identifier for a shopper.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | ### AuthoriseReferral | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AuthoriseReferral` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payment PSP reference. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The authorisation code for the transaction (authCode). | ```text FH,1.0,TEST,Company,TestCompany,Default,2,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,AuthoriseReferral,Test Product 6, SL,1,PaymentDetails,100,2,EUR,,,,, SL,2,AuthoriseReferral,8452147851579029,259016 BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancel-request.md Section: Development resources Title: Cancel request --- title: "Cancel request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancel-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancel-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancel-request" last_modified: "2019-04-30T17:23:00+02:00" language: "en" --- # Cancel request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancel-request.md) ## Mandatory sub-lines The [`Cancel` ](#cancel)sub-line described below is mandatory when submitting a payment cancellation request. ### Cancel * This sub-line holds information about `Cancel` [modification requests](/online-payments/modify-payments). * You cannot submit partial cancellation modifications. | Field # | Format | Required | Description | | ------- | --------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Cancel` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payment PSP reference. | ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Cancel,Test Product 3,EchoData SL,1,Cancel,8452147852369014 BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancelorrefund-request.md Section: Development resources Title: CancelOrRefund request --- title: "CancelOrRefund request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancelorrefund-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancelorrefund-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancelorrefund-request" last_modified: "2019-04-30T16:06:00+02:00" language: "en" --- # CancelOrRefund request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/cancelorrefund-request.md) ## Mandatory sub-lines The [`CancelOrRefund` ](#cancelorrefund)sub-line described below is mandatory when submitting a cancellation request. ### CancelOrRefund * This sub-line holds information about [Payment modifications](/online-payments/modify-payments) requests. * You cannot submit partial cancellation modifications. | Field # | Format | Required | Description | | ------- | ----------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `CancelOrRefund` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payment PSP reference. | ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,CancelOrRefund,Test Product 3,EchoData SL,1,CancelOrRefund,8452147851579029 BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request.md Section: Development resources Title: Capture request --- title: "Capture request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request" last_modified: "2019-04-30T17:23:00+02:00" language: "en" --- # Capture request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request.md) You can also include airline data into the capture request. For more information, refer [Capture with airline data](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data). ## Mandatory sub-lines The [`Capture` ](#capture)sub-line described below is mandatory when submitting a payment capture request. ### Capture This sub-line holds information about `capture` modification requests. | Field # | Format | Required | Description | | ------- | ---------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Capture` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payment PSP reference. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 7 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Capture,Test Product 3,EchoData SL,1,Capture,9145754231690158,100,2,EUR BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data.md Section: Development resources Title: Capture with airline data --- title: "Capture with airline data" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Capture with airline data [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/capture-request/capture-with-airline-data.md) When you send a capture request with a batch file submission, you can include [airline data information](#airline-data-sub-lines). To do so, you append the relevant airline data as sub-lines to the payment capture requests. ## Airline data sub-lines Below you can find an overview of the airline data sub-lines you can pass with capture batch file requests. ### Airline This sub-line holds information about airline data information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline) for details. | Field # | Format | Required | Description | | ------- | ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Airline` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Customer reference identifier/number. | | 5 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Airline code. | | 6 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Airline designator code. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Ticket issue address. | | 8 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Ticket number. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Travel agency code. | | 10 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Travel agency name. | | 11 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Agency plan name. | | 12 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Agency invoice number. | Example of isolated airline data batch file sub-line: ```text SL,2,Airline,BVQT04,074,KL,5th avenue 66,100020003034,12345678,,,, ``` Example of airline data batch file sub-line in a batch file context: ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Capture,Test Product 3,EchoData SL,1,Capture,9145754231690158,100,2,EUR SL,2,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,3,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,4,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,5,ShopperInteraction,Ecommerce SL,6,AuthorisationData,eci,1234 BT,1 FT,1 ``` ### AirlineLeg This sub-line holds information about airline leg information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. If you include airline data in your request, the batch file needs to contain *at least one airline leg* sub-line as well. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline-airline-leg-carrier_code) for details. | Field # | Format | Required | Description | | ------- | ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AirlineLeg` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Leg number identifier. The counter starts at 1, and it increments sequentially by one unit. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Departure airport. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Flight number. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Carrier code. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [Fare basis code](https://en.wikipedia.org/wiki/Fare_basis_code). | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Travel class identifier. | | 10 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Stopover code. | | 11 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Destination code. | | 12 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Travel date. | | 13 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [Departure tax](https://en.wikipedia.org/wiki/Departure_tax). | Example isolated airline leg data batch file sub-line: ```text SL,3,AirlineLeg,1,AMS,12345,AA,Y123456,B,O,LON,2014-08-02T19:05:00.000,Y ``` Example airline leg data batch file sub-line in a batch file context: ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Capture,Test Product 3,EchoData SL,1,Capture,9145754231690158,100,2,EUR SL,2,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,3,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,4,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,5,ShopperInteraction,Ecommerce SL,6,AuthorisationData,eci,1234 BT,1 FT,1 ``` ### AirlinePassenger This sub-line holds information about airline passenger information you want to send along with batch file [authorisation](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/authorisation-request-file) and [capture](/online-payments/modify-payments) requests. If you include airline data in your request, besides at least one airline leg sub-line the batch file needs to contain at least one airline passenger sub-line as well. Airline data fields may have specific format and/or character limitations: refer to the [airline data overview](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataAirline-airline-passenger_name) for details. | Field # | Format | Required | Description | | ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `AirlinePassenger` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger number identifier. The counter starts at 1, and it increments sequentially by one unit. | | 5 | Fixed value: `Name` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger data type. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger's first/given name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Passenger's last/family name. | | 8 | Format: `yyyy-MM-dd` For example: *1980-02-28* | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Passenger's birth date. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Traveller type. Passenger type code (PTC). | Example of isolated airline passenger data batch file sub-line: ```text SL,4,AirlinePassenger,1,Name,John,Doe,1979-02-28,, ``` Example of airline passenger data batch file sub-line in a batch file context:: ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Capture,Test Product 3,EchoData SL,1,Capture,9145754231690158,100,2,EUR SL,2,Airline,BVQT04,074,KL,C1,ABCDEF123456,A1B2C3D4,Adyen-Air,AP,123456 SL,3,AirlineLeg,1,AMS,FL123,AA,1,B,A,LND,2025-01-01 10:00,, SL,4,AirlinePassenger,1,Name,Miguel,Rodriguez,,, SL,5,ShopperInteraction,Ecommerce SL,6,AuthorisationData,eci,1234 BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/refund-request.md Section: Development resources Title: Refund request --- title: "Refund request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/refund-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/refund-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/refund-request" last_modified: "2019-04-30T17:24:00+02:00" language: "en" --- # Refund request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/modification-request-file/refund-request.md) ## Mandatory sub-lines The [`Refund` ](#refund)sub-line described below is mandatory when submitting a refund modification request. ### Refund This sub-line holds information about [refund modification](/online-payments/refund) requests. | Field # | Format | Required | Description | | ------- | --------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Refund` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payment PSP reference. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 7 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | ```text FH,1.0,TEST,Company,TestCompany,Default,3,ws@Company.TestCompany,Modification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Refund,Test Product 3,EchoData SL,1,Refund,9630124578963201,123,2,EUR BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file.md Section: Development resources Title: Payout request file --- title: "Payout request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Payout request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file.md) ## Payout lines The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`L\` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Allowed values:- `Payout` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction.As for modification requests, the merchant reference value can either:- Keep the same value and refer to the original payment authorisation reference. Or - Take a new reference value for the modification request in question. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## Payout sub-lines The number and the type of sub-lines that you need to include. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file/payout-request.md Section: Development resources Title: Payout request --- title: "Payout request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file/payout-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file/payout-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file/payout-request" last_modified: "2019-04-30T16:41:00+02:00" language: "en" --- # Payout request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payout-request-file/payout-request.md) ## Mandatory sub-lines The [`PayoutDetails` ](#payoutdetails)and [`Recurring` ](#recurring)sub-lines described below are mandatory when submitting a payout authorisation request. You also need to include either a [ `Card` ](#card), [ `BankAccount` ](#bankaccount), or [ `IBAN` ](#iban) sub-line on your payout request. ### PayoutDetails | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PayoutDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A shopper's reference, which is the unique identifier for a shopper. | | 8 | Email address | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's email address. | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | YYYY-MM-DD | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's birth date. | | 12 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's social security number. | | 13 | Allowed values:- `NaturalPerson` - `Company` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of the entity the payout is processed for.  | | 14 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's nationality.A valid value is an ISO 2-character country code (e.g. 'NL'). | ### Recurring | Field # | Format | Required | Description | | ------- | ------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Recurring` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Fixed value: `PAYOUT` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of recurring payment. | | 5 | Fixed value: `Latest` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Fixed value. | ### Card Besides the required `PayoutDetails` and `Recurring` sub-lines described above, a payout request needs to include either a `Card`, `BankAccount`, or `IBAN` payment method. For this payout, you need a user role with permission to store payout details. * This sub-line holds information about card payments. * In an authorization request for card payments, the `Card` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Card` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card number. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month.* Format: `MM`, zero-padded (eg: *03*) | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year.* Format: `YYYY` (eg: *2016*) | | 7 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [CVC code](https://www.cvvnumber.com/cvv.html).* Three-digit CVC/CVV code (Visa, Mastercard, Discover) * Four-digit CVC/CVV code (American Express) | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Cardholder name. | | 9 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start month.* Format: `MM`, zero-padded (eg: *03*)Maestro UK only. | | 10 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start year.* Format: `YYYY` (eg: *2016*)Maestro UK only. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | One-digit card issue number.Maestro UK only. | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Payout,MerchantReference, SL,1,PayoutDetails,1000,2,EUR,ShopperRef28411,test-payout@test.com,TESTING TX01234156XT,10.0.0.1,2017-01-11,123456789,NaturalPerson,NL SL,2,Card,4444333322221111,12,2012,J. de Tester,,, SL,3,Recurring,PAYOUT,LATEST BT,1 FT,1 ``` ### BankAccount Besides the required `PayoutDetails` and `Recurring` sub-lines described above, a payout request needs to include either a `Card`, `BankAccount`, or `IBAN` payment methods. For this payout, you need a user role with permission to store payout details. * This sub-line holds information about bank transfer payments carried out using the shopper's bank account details. * In an authorisation request for bank account payments, the `BankAccount` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `BankAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account number. | | 7 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter bank location.* Format: `AA` | | 8 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter bank name.* Format: `AA` | | 9 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank code. | | 10 | Alphabetic | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Two-letter check code.* Format: `AA` | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Payout,MerchantReference, SL,1,PayoutDetails,1000,2,EUR,ShopperRef28411,test-payout@test.com,TESTING TX01234156XT,10.0.0.1,2017-01-11,123456789,NaturalPerson,NL SL,2,BankAccount,Simon Hopper,SE,123456789,20010020,Postbank Stockholm,3125876,Hameln SL,3,Recurring,PAYOUT,LATEST BT,1 FT,1 ``` ### IBAN Besides the required `PayoutDetails` and `Recurring` sub-lines described above, a payout request needs to include either a `Card`, `BankAccount`, or `IBAN` payment methods. For this payout, you need a user role with permission to store payout details. * This sub-line holds information about bank transfer or SEPA Direct Debit (DD) payments carried out using the shopper's IBAN details. * In an authorization request for IBAN payments, the `IBAN` sub-line needs to be submitted as *sub-line 2*. | Field # | Format | Required | Description | | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `IBAN` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric Cannot be only numbers. Minimum three characters. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. If provided details do not match the required format, the response returns the error message: 203 'Invalid bank account holder name'. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [IBAN code](https://en.wikipedia.org/wiki/International_Bank_Account_Number). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [BIC code](https://en.wikipedia.org/wiki/ISO_9362). | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,Payout,MerchantReference, SL,1,PayoutDetails,1000,2,EUR,ShopperRef28411,test-payout@test.com,TESTING TX01234156XT,10.0.0.1,2017-01-11,123456789,NaturalPerson,NL SL,2,IBAN,A. Klaassen,NL,NL13TEST0123456789, SL,3,Recurring,PAYOUT,LATEST BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file.md Section: Development resources Title: PayoutModification request file --- title: "PayoutModification request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # PayoutModification request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file.md) ## PayoutModification lines The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `L` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Allowed values:- `PayoutConfirm` - `PayoutDecline` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead.   | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## PayoutModification sub-lines The number and the type of sub-lines that you need to include varies, depending on the payout modification specified in the request: either `PayoutConfirm` or `PayoutDecline`. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutconfirm-request.md Section: Development resources Title: PayoutConfirm request --- title: "PayoutConfirm request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutconfirm-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutconfirm-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutconfirm-request" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # PayoutConfirm request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutconfirm-request.md) ## Mandatory sub-lines This sub-line holds information about payout confirmation requests. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PayoutConfirm` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payout PSP reference. | ## Example ```text FH,1.0,TEST,Company,TestCompany,Default,1,reviewPayout@Company.TestCompany,PayoutModification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,PayoutConfirm,MerchantReference, SL,1,PayoutConfirm,9913122736590001 BT,1 FT,1 ``` For this PayoutConfirm, you need a user role with permission to review/decline a payout. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutdecline-request.md Section: Development resources Title: PayoutDecline request --- title: "PayoutDecline request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutdecline-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutdecline-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutdecline-request" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # PayoutDecline request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/payoutmodification-request-file/payoutdecline-request.md) ## Mandatory sub-lines This sub-line holds information about payout decline requests. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PayoutDecline` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The original payout PSP reference. | ## Example ```text FH,1.0,TEST,Company,TestCompany,Default,1,reviewPayout@Company.TestCompany,PayoutModification,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,PayoutDecline,MerchantReference, SL,1,PayoutDecline,9913122736590001 BT,1 FT,1 ``` For this PayoutDecline, you need a user role with permission to review/decline a payout. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file.md Section: Development resources Title: RefundWithData request file --- title: "RefundWithData request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # RefundWithData request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file.md) ## RefundWithData lines The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`L\` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Fixed value: `RefundWithData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction.As for modification requests, the merchant reference value can either:- Keep the same value and refer to the original payment authorisation reference. Or - Take a new reference value for the modification request in question. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## RefundWithData sub-lines `RefundWithData` has only one processing type and one sub-line. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file/refundwithdata-request.md Section: Development resources Title: RefundWithData request --- title: "RefundWithData request" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file/refundwithdata-request" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file/refundwithdata-request.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file/refundwithdata-request" last_modified: "2021-07-23T16:53:00+02:00" language: "en" --- # RefundWithData request [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/refundwithdata-request-file/refundwithdata-request.md) ## Mandatory sub-lines The [`PaymentDetails` ](#paymentdetails)sub-line along with either a `Card` or `IBAN` sub-line described below are mandatory when submitting a bank transfer authorisation request. ### PaymentDetails | **Field #** | **Format** | **Field Required** | **Value Required** | **Description** | | ----------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `PaymentDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Amount. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The [currency exponent](https://en.wikipedia.org/wiki/ISO_4217#Treatment_of_minor_currency_units_.28the_.22exponent.22.29). | | 6 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A shopper's reference, which is the unique identifier for a shopper.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 8 | Email address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's email address.Required element for recurring payments and to create [recurring contracts](/online-payments/classic-integrations/classic-api-integration/tokenization). | | 9 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Shopper statement. The soft [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) for the transaction. | | 10 | IP address | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The IP address the shopper used to carry out the transaction. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Fraud offset. The value to be applied to offset the calculated risk score. It can be either a positive or a negative value. | | 12 | YYYY-MM-DD | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's birth date. | | 13 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's social security number. | | 14 | Allowed values:- `NaturalPerson` - `Company` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The type of the entity the payout is processed for. | | 15 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The shopper's nationality.A valid value is an ISO 2-character country code (e.g. 'NL'). | #### Example PaymentDetails sub-lines The following example sub-line is valid:\ `SL,1,PaymentDetails,1000,2,USD,1991-01-11,NaturalPerson,US` * It includes all the fields that are required (amount, currency exponent, ISO currency code, shopper's birth date, type of entity, shopper's nationality) * It contains a value for each required field (respectively: 1000, 2, USD, 1991-01-11, NaturalPerson, US) The following example sub-line is also valid:\ `SL,1,PaymentDetails,1000,,USD,,,` * It includes all the fields that are required (amount, currency exponent, ISO currency code, shopper's birth date, type of entity, shopper's nationality) * It contains an empty value for required fields that do not need a value (currency exponent, shopper's birth date, type of entity, shopper's nationality) The following example sub-line is not valid:\ `SL,1,PaymentDetails,1000,USD` * It doesn't include all the required fields and (empty) values. ### Card Besides the required [`PaymentDetails` ](#paymentdetails)sub-line described above, a refund with data request needs to include either a `Card` or `IBAN` sub-line. * This sub-line holds information about card payments. * In an authorization request for card payments, the `Card` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Card` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card number. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month.* Format: `MM`, zero-padded (eg: *03*) | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year.* Format: `YYYY` (eg: *2016*) | | 7 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [CVC code](https://www.cvvnumber.com/cvv.html).* Three-digit CVC/CVV code (Visa, Mastercard, Discover) * Four-digit CVC/CVV code (American Express) | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Cardholder name. | | 9 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start month.* Format: `MM`, zero-padded (eg: *03*)Maestro UK only. | | 10 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start year.* Format: `YYYY` (eg: *2016*)Maestro UK only. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | One-digit card issue number.Maestro UK only. | ```text FH,1.0,TEST,Company,TestCompany,TestRefundWithData,1,ws@Company.TestCompany,RefundWithData,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,RefundWithData,40975 SL,1,PaymentDetails,1000,2,EUR,ShopperRef28411,test-payout@adyen.com,TESTING TX01234156XT,,,2017-01-11,123456789,NaturalPerson,NL SL,2,Card,4111111111111111,06,2016,CardHolderName,,, BT,1 FT,1 ``` ### IBAN Besides the required [`PaymentDetails` ](#paymentdetails)sub-line described above, a refund with data request needs to include either a `Card` or `IBAN` sub-line. * This sub-line holds information about bank transfer or SEPA Direct Debit (DD) payments carried out using the shopper's IBAN details. * In an authorization request for IBAN payments, the `IBAN` sub-line needs to be submitted as *sub-line 2*. | Field # | Format | Required | Description | | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `IBAN` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric Cannot be only numbers. Minimum three characters. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. If provided details do not match the required format, the response returns the error message: 203 'Invalid bank account holder name'. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [IBAN code](https://en.wikipedia.org/wiki/International_Bank_Account_Number). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [BIC code](https://en.wikipedia.org/wiki/ISO_9362). | ```text FH,1.0,TEST,Company,TestCompany,TestRefundWithData,1,ws@Company.TestCompany,RefundWithData,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,RefundWithData,40975 SL,1,PaymentDetails,1000,2,EUR,ShopperRef28411,test-payout@adyen.com,TESTING TX01234156XT,,,2017-01-11,123456789,NaturalPerson,NL SL,2,IBAN,Test Testing,NL,NL13TEST0123456789 BT,1 FT,1 ``` ## Optional sub-lines The `Address` sub-line described below can be optionally included in the payment request. ### Address You can use the `Address` sub-line to include information about the shopper's billing and delivery addresses.\ You need to specify billing and deliver addresses on separate `Address` sub-lines: * One `Address` sub-line containing the billing address information; * One `Address` sub-line containing the delivery address information. | **Field #** | **Format** | **Required** | **Description** | | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Address` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Allowed values:* `Billing` * `Delivery` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of address that is being submitted: either a billing or a delivery address. | | 5 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street address. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | 7 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | City. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ZIP/Post code. | | 9 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State/Province/Region. | | 10 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file.md Section: Development resources Title: StoreToken request file --- title: "StoreToken request file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # StoreToken request file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file.md) ## storeToken lines The line record \[L] holds the metadata information that applies to its corresponding sub-line \[SL] records. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `L` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`L\` line record number reference within the batch file block it belongs to. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `MerchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Account type. Defines the type of account the transactions are related to. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the merchant account name. | | 5 | Allowed values:- `storeToken` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Processing type. Defines the type of action that is required for the specified transaction.If the column shows `ValidationError`, then the file shall have the structure of the [batch result file (ValidationError)](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/modification-result-file-validationerror) instead. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A merchant reference, that is, a unique identifier associated to a specific transaction.As for modification requests, the merchant reference value can either:- Keep the same value and refer to the original payment authorisation reference. Or - Take a new reference value for the modification request in question. | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | `EchoData` In this field you can specify any data you may want to be returned with the result file. When this field is populated, its content is returned exactly as is. The Adyen payments platform does not use this data. Maximum character length: 80 characters. | ## StoreToken sub-lines The number and the type of sub-lines that you need to include. --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file/storetoken-request-for-payout.md Section: Development resources Title: StoreToken request for payout --- title: "StoreToken request for payout" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file/storetoken-request-for-payout" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file/storetoken-request-for-payout.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file/storetoken-request-for-payout" last_modified: "2019-04-30T17:37:00+02:00" language: "en" --- # StoreToken request for payout [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file/storetoken-request-file/storetoken-request-for-payout.md) ## Mandatory sub-lines The [`ShopperDetails` ](#shopperdetails)and [`Recurring` ](#recurring)sub-lines described below are mandatory when submitting a `StoreToken` request. You also need to include either a [ `Card` ](#card), [ `BankAccount` ](#bankaccount), or [ `IBAN` ](#iban) sub-line on your `StoreToken` request. * `StoreToken` enables [tokenising](https://en.wikipedia.org/wiki/Tokenization_\(data_security\)) payment details. * Only payment requests submitted after sending the `StoreToken` request are tokenised. ### ShopperDetails This sub-line specifies transaction amount and customer details.\ \ Optional fields: if you do not populate one or more non-mandatory fields and leave them blank, you need in any case to insert delimiting commas because the Adyen payments platform expects a preset, fixed number of fields per line/sub-line. | Field # | Format | Required | Description | | ------- | ----------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `ShopperDetails` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A shopper's reference, which is the unique identifier for a shopper. | | 5 | Email address | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's email address. | ### Recurring If you include this subline in your batch file, a recurring payment request is created with the provided payment details. | Field # | Format | Required | Description | | ------- | ------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Recurring` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Fixed value: `PAYOUT` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of recurring payment. | | 5 | Fixed value: `Latest` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Fixed value. | ### Card Besides the required [ `ShopperDetails` ](#shopperdetails)and [`Recurring` ](#recurring) sub-lines described above, a `StoreToken` request needs to include either a [ `Card` ](#card), [ `BankAccount` ](#bankaccount), or [ `IBAN` ](#iban) payment method. For this StoreToken, you need a [user role](/online-payments/online-payouts) with permission to store payout details. * This sub-line holds information about card payments. * In an authorisation request for card payments, the `Card` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | ------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | \`SL\` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `Card` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card number. | | 5 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month.* Format: `MM`, zero-padded (ex.: *03*) | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year.* * Format: `YYYY` (ex.: *2016*) | | 7 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [CVC code](https://www.cvvnumber.com/cvv.html). Leave this field blank. | | 8 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Card holder name. | | 9 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start month.* Format: `MM`, zero-padded (ex.: *03*)Maestro UK only. | | 10 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Start year.* Format: `YYYY` (ex.: *2016*)Maestro UK only. | | 11 | Numeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | One-digit card issue number.Maestro UK only. | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,StoreToken,MerchantReference, SL,1,ShopperDetails,test@adyen.com,test@adyen.com SL,2,Card,4444333322221111,12,2012,,J. de Tester,,, SL,3,Recurring,PAYOUT,Latest BT,1 FT,1 ``` ### BankAccount Besides the required [ `ShopperDetails` ](#shopperdetails)and [`Recurring` ](#recurring) sub-lines described above, a `StoreToken` request needs to include either a [ `Card` ](#card), [ `BankAccount` ](#bankaccount), or [ `IBAN` ](#iban) payment method. For this StoreToken, you need a [user role](/online-payments/online-payouts) with permission to store payout details. * This sub-line holds information about bank transfer payments carried out using the shopper's bank account details. * In an authorisation request for bank account payments, the `BankAccount` sub-line needs to be submitted as *sub-line 2*. | **Field #** | **Format** | **Required** | **Description** | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line. The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `BankAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account number. | | 7 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter bank location.* Format: `AA` | | 8 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter bank name.* Format: `AA` | | 9 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank code. | | 10 | Alphabetic | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Two-letter check code.* Format: `AA` | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,StoreToken,MerchantReference, SL,1,ShopperDetails,test@adyen.com,test@adyen.com SL,2,BankAccount,Simon Hopper,SE,123456789,20010020,Postbank Stockholm,3125876,Hameln SL,3,Recurring,PAYOUT,Latest BT,1 FT,1 ``` ### IBAN Besides the required [ `ShopperDetails` ](#shopperdetails)and [`Recurring` ](#recurring) sub-lines described above, a `StoreToken` request needs to include either a [ `Card` ](#card), [ `BankAccount` ](#bankaccount), or [ `IBAN` ](#iban) payment method. For this StoreToken, you need a [user role](/online-payments/online-payouts) with permission to store payout details. * This sub-line holds information about bank transfer or SEPA Direct Debit (DD) payments carried out using the shopper's IBAN details. * In an authorization request for IBAN payments, the `IBAN` sub-line needs to be submitted as *sub-line 2*. | Field # | Format | Required | Description | | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `SL` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier | | 2 | Numeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | `SL` sub-line record number reference within its parent line.The counter starts at 1, and it increments sequentially by one unit. | | 3 | Fixed value: `IBAN` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Transaction type. Defines the required field types for the specific sub-line. | | 4 | Alphanumeric Cannot be only numbers. Minimum three characters. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Bank account owner name. If provided details do not match the required format, the response returns the error message: 203 'Invalid bank account holder name'. | | 5 | Alphabetic | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Two-letter country code. The `country` value format needs to adhere to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. An invalid country code results in a transaction/request rejection. You can [look up country codes](https://www.iso.org/obp/ui/) on the ISO website. | | 6 | Alphanumeric | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [IBAN code](https://en.wikipedia.org/wiki/International_Bank_Account_Number). | | 7 | Alphanumeric | ![-x-](/user/data/smileys/emoji/x.png "-x-") | [BIC code](https://en.wikipedia.org/wiki/ISO_9362). | ```text FH,1.0,TEST,Company,TestCompany,Default,1,storeToken@Company.TestCompany,Payout,FileHeaderEchoData BH,1,BlockHeaderEchoData L,1,MerchantAccount,TestMerchant,StoreToken,MerchantReference, SL,1,ShopperDetails,test@adyen.com,test@adyen.com SL,2,IBAN,A. Klaassen,NL,NL13TEST0123456789, SL,3,Recurring,PAYOUT,Latest BT,1 FT,1 ``` --- # Source: https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file.md Section: Development resources Title: Batch result file --- title: "Batch result file" url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file" source_url: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file.md" canonical: "https://docs.adyen.com/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file" last_modified: "2023-10-20T11:42:00+02:00" language: "en" --- # Batch result file [View source](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file.md) You can get the batch result file two days after receiving the [batch acknowledgement (ACK) file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-acknowledgement-file) with a successful validation. The following fields are included in all batch result files: ### File Header \[FH] The File Header \[FH] record contains the data that was passed in the [batch request file header](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file). | Field # | Format | Description | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed value: `FH` | Record type identifier. | | 2 | Fixed value: `1.0` | Version number. This field enables version control for the release of future enhancements for batch processing. | | 3 | Allowed values:- `TEST` - `LIVE` | It specifies the environment: either test or live/production. | | 4 | Allowed values:- `MerchantAccount` - `Company` | Account type, as submitted in the [request file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file). | | 5 | Alphanumeric | The merchant or the company account name, as submitted in the [request file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file). | | 6 | Alphanumeric | The [submission platform](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure) value provided in the [request file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file). | | 7 | Numeric | The [file sequence number](/development-resources/batch-processing/advanced-sftp-batch-files/batch-file-naming-and-structure) value provided in the [request file](/development-resources/batch-processing/advanced-sftp-batch-files/batch-request-file). | | 8 | Alphanumeric | The API credential name specified to upload the file to the SFTP. For example: [strong>ws@Company.\ws@Company. **Batch modifications**. 5. Select **Upload File**, then select your CSV input file and select **Submit**. 6. Under **Review Batch** check for any errors: * If there are no errors, you'll see an overview of the batch, with the number of modifications and their total value. * "*Incomplete data*": all records in the input file are missing one or more fields.\ You can add the missing fields in the input file and then upload the file again.\ Or you can add the missing fields in the Customer Area, as described in the next step. * Other errors: fix the input file based on the error description, and upload the file again. 7. To fix an *Incomplete data* error by adding missing fields in the Customer Area: All records will get the same value for the added field. 1. Select the **+** button. A dialog appears. 2. In the **Column** field, select the field that is missing from the records. 3. In the **Fixed Value** field, select the value to assign to the field, or enter an amount in minor units. 4. Select **Add Column**. 5. Repeat as needed if more fields are missing from the records. 8. Select **Upload**.\ The batch file is QUEUED, and then PROCESSED. ## Check the result After the batch file has finished processing, the status changes to COMPLETED. You can download the batch result file to check the result messages for the individual modifications. A result message can be green or red. Green (successful) means that the modification passed the validation. However, processing the modification can still fail. The validation of modifications consists of checks like the following: * Is the amount to modify not higher than the authorised amount? * Are there remaining funds in the payment to refund, capture or cancel? * Does the merchant account have the funds to refund the transaction? If a modification passes the validation, we mark the modification as successful and try to process it. If the modification then fails, we inform you asynchronously through a webhook. ## See also * [Batch processing](/development-resources/batch-processing) --- # Source: https://docs.adyen.com/development-resources/client-side-authentication.md Section: Development resources Title: Client-side authentication Description: Learn about the client key and how to generate it. --- title: "Client-side authentication" description: "Learn about the client key and how to generate it." url: "https://docs.adyen.com/development-resources/client-side-authentication" source_url: "https://docs.adyen.com/development-resources/client-side-authentication.md" canonical: "https://docs.adyen.com/development-resources/client-side-authentication" last_modified: "2021-10-20T13:44:00+02:00" language: "en" --- # Client-side authentication Learn about the client key and how to generate it. [View source](/development-resources/client-side-authentication.md) We use your client key to authenticate requests from your payment environment. For example, [Web Drop-in](/online-payments/drop-in-web) and [Web Component](/online-payments/components-web/) integrations need the client key to: * Render input fields to securely collect and encrypt card details. * Detect the card type from the number the shopper entered in the payment form. * Do server-side barcode or QR code rendering for payment methods such as Swish or Boleto Bancário. The client key is not used when making requests to our APIs. For API requests, you need to [get an API key](/development-resources/api-credentials#generate-api-key). With the client key, you have: * A single key for all your [allowed origins](/development-resources/client-side-authentication#allowed-origins) in an environment. * Flexibility to add and remove origins without having to generate a new client key. * A human-readable prefix, **test** or **live**, so you can easily tell which environment a client key is linked to. ## Availability and compatibility The client key is available for the following: | Online payments integration | Version | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web Drop-in and Components | Available for 3.10.1 and later. Previous versions require [origin keys](/development-resources/how-to-get-an-origin-key) for client-side authentication. Starting 4.0.0 the client key is the only way to do client-side authentication. | | iOS Drop-in and Components | 3.7.0 and later. Previous versions require client encryption public keys. Starting 4.0.0 the client key is the only way to do client-side authentication. | | Android Drop-in and Components | 3.7.0 and later. Previous versions require client encryption public keys. Starting 4.0.0 the client key is the only way to do client-side authentication. | | In-person payments integration | Solutions | | ------------------------------ | ----------------------------------------- | | POS Mobile SDK for iOS | Tap to Pay on iPhone Card reader—iOS | | POS Mobile SDK for Android | Tap to Pay on Android Card reader—Android | ## How it works The client key is a public key that uniquely identifies an API credential. Each API credential has a list of allowed origins, or domains from which we expect to get your requests. We make sure data cannot be accessed by unknown parties by using [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). A client key is linked to an API credential and its environment. The client key has two parts: * A 32-character string encoding the API credential * A human-readable environment prefix For example, **test\_870be2854add4f56b86778353010f36c** is a client key for the test environment. When you switch to your live environment, you need to generate a client key in your [live Customer Area](https://ca-live.adyen.com/). The client key for your live environment will start with **live\_**. ## Allowed origins Allowed origins are domains from which we expect to get your client-side requests. The allowed origins: * Can include a wildcard, for example `https://*.example.org` includes both `https://blue.example.org` and `https://red.example.org`. * Can be a `https` domain in the test environment or a `http` if it is a secure context, such as `http://127.0.0.1`, `http://localhost`, or `http://*.localhost`. * Must have `https` in the live environment. Allowed origins are linked to the API credential, so you can [add or remove allowed origins](#manage-allowed-origins) without needing to generate a new client key. ## Get your client key 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Developers** > **API credentials**, and select the credential username for your integration, for example **ws\@Company.\[YourCompanyAccount]**. 3. Under **Client settings** > **Authentication** select the **Client key** tab. 4. Select **Generate client key**. 5. Select the copy icon **and store your client key securely in your system. 6. Under **Add allowed origins**, enter your [domains](/development-resources/client-side-authentication#allowed-origins) and select **Add**. 7. Select **Save changes**. If you generated a new client key, the old one expires after 24 hours. You now have a client key for your **ws\@Company.****\[YourCompanyAccount]** API credential, which is linked to your test environment. To get a client key for your live environment, follow the same steps in your [live Customer Area](https://ca-live.adyen.com/). ## Manage allowed origins You can add or remove allowed origins for an API credential without generating a new client key. 1. Log in to your [Customer Area](https://ca-test.adyen.com/) . 2. Go to **Developers** > **API credentials**, and select the API credential for your Web Drop-in or Web Components integration, for example **ws\@Company.****\[YourCompanyAccount]**. 3. Under **Allowed origins**, enter a [domain](#allowed-origins) and select **Add**. To remove a domain select the remove origin icon **next to it. 4. Select **Save changes**. It takes a few seconds for new allowed origins to become available for your application. ## See also * [How to get the API key](/development-resources/api-credentials) * [Web Drop-in](/online-payments/drop-in-web) * [Web Components](/online-payments/components-web) * [Migrate from origin key to client key](/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key) --- # Source: https://docs.adyen.com/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key.md Section: Development resources Title: Migrate to client key Description: Learn about how and why to switch to using the client key. --- title: "Migrate to client key" description: "Learn about how and why to switch to using the client key." url: "https://docs.adyen.com/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key" source_url: "https://docs.adyen.com/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key.md" canonical: "https://docs.adyen.com/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key" last_modified: "2020-05-29T16:11:00+02:00" language: "en" --- # Migrate to client key Learn about how and why to switch to using the client key. [View source](/development-resources/client-side-authentication/migrate-from-origin-key-to-client-key.md) If your Web integration uses the [origin key](/development-resources/how-to-get-an-origin-key) or your iOS or Android integration uses the client encryption public key, switch to the client key. In future versions the client key will be the only way to do client-side authentication. The client key makes it easier for you to manage the origins for your integration. With the client key, you have: * A single key for all your [allowed origins](/development-resources/client-side-authentication#allowed-origins) in an environment. * Flexibility to add and remove origins without having to generate a new client key. * A human-readable prefix, **test** or **live**, so you can easily tell which environment a client key is linked to. The client key also enables card type detection through [Bank Identification Number (BIN)](/get-started-with-adyen/adyen-glossary/#bank-identification-number-bin) lookup, which is not available when using the origin key. ## Availability and compatibility The client key is available for the following: | Online payments integration | Version | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web Drop-in and Components | Available for 3.10.1 and later. Previous versions require [origin keys](/development-resources/how-to-get-an-origin-key) for client-side authentication. Starting 4.0.0 the client key is the only way to do client-side authentication. | | iOS Drop-in and Components | 3.7.0 and later. Previous versions require client encryption public keys. Starting 4.0.0 the client key is the only way to do client-side authentication. | | Android Drop-in and Components | 3.7.0 and later. Previous versions require client encryption public keys. Starting 4.0.0 the client key is the only way to do client-side authentication. | | In-person payments integration | Solutions | | ------------------------------ | ----------------------------------------- | | POS Mobile SDK for iOS | Tap to Pay on iPhone Card reader—iOS | | POS Mobile SDK for Android | Tap to Pay on Android Card reader—Android | The client key is backwards compatible with the origin key and the public key. Generating a client key doesn't invalidate a pre-existing origin key or public key. ## Switch to using the client key To switch to using the client key, you must first generate your client key in your Customer Area: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 1. Go to **Developers** > **API credentials**, and select the credential username for your integration, for example **ws\@Company.\[YourCompanyAccount]**. 2. Under **Client settings** > **Authentication** select the **Client key** tab. 3. Select **Generate client key**. 4. Select the copy icon **and store your client key securely in your system. 5. Under **Add allowed origins**, enter your [domains](/development-resources/client-side-authentication#allowed-origins) and select **Add**. 6. Select **Save changes**. Once you have your client key, you need to add it to your integration. Choose your platform: ### Tab: Web You must be running [Web Drop-in](/online-payments/drop-in-web) or [Web Components](/online-payments/components-web/) version 3.10.1 or above. Replace `originKey` in your Web Drop-in or Web Components configuration object with: **Web Components** ```js const configuration = { ... clientKey: "YOUR_CLIENT_KEY", ... } ``` ### Tab: iOS You must be running [iOS Drop-in](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in) or [iOS Components](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Components) version 3.7.0 or above. 1. Create an instance of `APIContext` with the following parameters: | Parameter name | Required | Description | | -------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientKey` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your [client key](/development-resources/client-side-authentication). | | `environment` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Use **test**. When you are ready to accept live payments, change the value to one of our [live environments](https://adyen.github.io/adyen-ios/5.0.0/documentation/adyen/environment/).  | **APIContext initialization** ```swift // When you are ready to go live, change environment to Environment.live // You can also use other environment values described in https://adyen.github.io/adyen-ios/Docs/Structs/Environment.html let apiContext = APIContext(environment: Environment.test, clientKey: clientKey) ``` 2. Use `apiContext` in your iOS Drop-in or iOS Components configuration instead of `publicKey`: **iOS Drop-in** ```swift let configuration = DropInComponent.Configuration(apiContext: apiContext) let component = DropInComponent(paymentMethods: paymentMethods, configuration: configuration) ``` **iOS Components** ```swift // Replace CardComponent with the payment method Component that you want to add. let cardComponent = CardComponent(paymentMethod: cardPaymentMethod, apiContext: apiContext) ``` ### Tab: Android You must be running [Android Drop-in](/online-payments/build-your-integration/sessions-flow?platform=Android\&integration=Drop-in) or [Android Components](/online-payments/build-your-integration/sessions-flow?platform=Android\&integration=Components) version 3.7.0 or above. Pass your `clientKey` to your Android Drop-in or Android Components configuration object: **Android Drop-in** ```kotlin val dropInConfiguration = DropInConfiguration.Builder(context, YourDropInService::class.java, "YOUR_CLIENT_KEY") // ... .build() ``` **Android Components** ```kotlin val cardConfiguration = CardConfiguration.Builder(context, "YOUR_CLIENT_KEY") // ... .build() ``` ## See also * [Client-side authentication](/development-resources/client-side-authentication) * [How to get the API key](/development-resources/api-credentials) * [Web Drop-in](/online-payments/drop-in-web) * [Web Components](/online-payments/components-web) * [iOS Drop-in](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Drop-in) * [iOS Components](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Components) * [Android Drop-in](/online-payments/build-your-integration/sessions-flow/?platform=Android\&integration=Drop-in) * [Android Components](/online-payments/build-your-integration/sessions-flow?platform=Android\&integration=Components) --- # Source: https://docs.adyen.com/development-resources/currency-codes.md Section: Development resources Title: Currency codes and minor units Description: Look up currency codes, and learn about minor units and currency exchange fees. --- title: "Currency codes and minor units" description: "Look up currency codes, and learn about minor units and currency exchange fees." url: "https://docs.adyen.com/development-resources/currency-codes" source_url: "https://docs.adyen.com/development-resources/currency-codes.md" canonical: "https://docs.adyen.com/development-resources/currency-codes" last_modified: "2025-09-05T10:19:00+02:00" language: "en" --- # Currency codes and minor units Look up currency codes, and learn about minor units and currency exchange fees. [View source](/development-resources/currency-codes.md) In your API requests, you need to provide transaction amounts by specifying a currency code and a value. For most APIs the value must be specified in minor units, given the number of decimals of the currency. This page lists the supported currency codes and explains what minor units are. ## Currency codes | Code | Currency | Decimals | | ---- | ---------------------------------------- | ---------------------------------- | | AED | UAE Dirham | 2 | | ALL | Albanian Lek | 2 | | AMD | Armenian Dram | 2 | | AOA | Angolan Kwanza | 2 | | ARS | Nuevo Argentine Peso | 2 | | AUD | Australian Dollar | 2 | | AWG | Aruban Guilder | 2 | | AZN | Azerbaijani manat | 2 | | BAM | Bosnia and Herzegovina Convertible Marks | 2 | | BBD | Barbados Dollar | 2 | | BDT | Bangladesh Taka | 2 | | BHD | Bahraini Dinar | 3 | | BMD | Bermudian Dollar | 2 | | BND | Brunei Dollar | 2 | | BOB | Bolivia Boliviano | 2 | | BRL | Brazilian Real | 2 | | BSD | Bahamian Dollar | 2 | | BWP | Botswana Pula | 2 | | BYN | New Belarusian Ruble | 2 | | BZD | Belize Dollar | 2 | | CAD | Canadian Dollar | 2 | | CHF | Swiss Franc | 2 | | CLP | Chilean Peso | 2 ([differs from standard](#note)) | | CNH | Yuan Renminbi (offshore) | 2 | | CNY | Yuan Renminbi (onshore) | 2 | | COP | Colombian Peso | 2 | | CRC | Costa Rican Colon | 2 | | CUP | Cuban Peso | 2 | | CVE | Cape Verdi Escudo | 0 ([differs from standard](#note)) | | CZK | Czech Koruna | 2 | | DJF | Djibouti Franc | 0 | | DKK | Danish Krone | 2 | | DOP | Dominican Republic Peso | 2 | | DZD | Algerian Dinar | 2 | | EGP | Egyptian Pound | 2 | | ETB | Ethiopian Birr | 2 | | EUR | Euro | 2 | | FJD | Fiji Dollar | 2 | | FKP | Falkland Islands Pound | 2 | | GBP | Pound Sterling | 2 | | GEL | Georgian Lari | 2 | | GHS | Ghanaian Cedi (3rd) | 2 | | GIP | Gibraltar Pound | 2 | | GMD | Gambia Delasi | 2 | | GNF | Guinea Franc | 0 | | GTQ | Guatemala Quetzal | 2 | | GYD | Guyanese Dollar | 2 | | HKD | Hong Kong Dollar | 2 | | HNL | Honduras Lempira | 2 | | HTG | Haitian Gourde | 2 | | HUF | Hungarian Forint | 2 | | IDR | Indonesian Rupiah | 0 ([differs from standard](#note)) | | ILS | New Israeli Scheqel | 2 | | INR | Indian Rupee | 2 | | IQD | Iraqi Dinar | 3 | | ISK | Iceland Krona | 2 ([differs from standard](#note)) | | JMD | Jamaican Dollar | 2 | | JOD | Jordanian Dinar | 3 | | JPY | Japanese Yen | 0 | | KES | Kenyan Shilling | 2 | | KGS | Kyrgyzstan Som | 2 | | KHR | Cambodia Riel | 2 | | KMF | Comoro Franc | 0 | | KRW | South-Korean Won | 0 | | KWD | Kuwaiti Dinar | 3 | | KYD | Cayman Islands Dollar | 2 | | KZT | Kazakhstani Tenge | 2 | | LAK | Laos Kip | 2 | | LKR | Sri Lanka Rupee | 2 | | LYD | Libyan Dinar | 3 | | MAD | Moroccan Dirham | 2 | | MDL | Moldovia Leu | 2 | | MKD | Macedonian Denar | 2 | | MMK | Myanmar Kyat | 2 | | MNT | Mongolia Tugrik | 2 | | MOP | Macau Pataca | 2 | | MRU | Mauritania Ouguiya | 2 | | MUR | Mauritius Rupee | 2 | | MVR | Maldives Rufiyaa | 2 | | MWK | Malawi Kwacha | 2 | | MXN | Mexican Peso | 2 | | MYR | Malaysian Ringgit | 2 | | MZN | Mozambican Metical | 2 | | NAD | Namibian Dollar | 2 | | NGN | Nigerian Naira | 2 | | NIO | Nicaragua Cordoba Oro | 2 | | NOK | Norwegian Krone | 2 | | NPR | Nepalese Rupee | 2 | | NZD | New Zealand Dollar | 2 | | OMR | Rial Omani | 3 | | PAB | Panamanian Balboa | 2 | | PEN | Peruvian Nuevo Sol | 2 | | PGK | New Guinea Kina | 2 | | PHP | Philippine Peso | 2 | | PKR | Pakistan Rupee | 2 | | PLN | New Polish Zloty | 2 | | PYG | Paraguay Guarani | 0 | | QAR | Qatari Rial | 2 | | RON | New Romanian Lei | 2 | | RSD | Serbian Dinar | 2 | | RUB | Russian Ruble | 2 | | RWF | Rwanda Franc | 0 | | SAR | Saudi Riyal | 2 | | SBD | Solomon Island Dollar | 2 | | SCR | Seychelles Rupee | 2 | | SEK | Swedish Krone | 2 | | SGD | Singapore Dollar | 2 | | SHP | St. Helena Pound | 2 | | SLE | Sierra Leone Leone | 2 | | SOS | Somalia Shilling | 2 | | SRD | Surinamese dollar | 2 | | STN | Sao Tome & Principe Dobra | 2 | | SVC | El Salvador Colón | 2 | | SZL | Swaziland Lilangeni | 2 | | THB | Thai Baht | 2 | | TND | Tunisian Dinar | 3 | | TOP | Tonga Pa'anga | 2 | | TRY | New Turkish Lira | 2 | | TTD | Trinidad & Tobago Dollar | 2 | | TWD | New Taiwan Dollar | 2 | | TZS | Tanzanian Shilling | 2 | | UAH | Ukraine Hryvnia | 2 | | UGX | Uganda Shilling | 0 | | USD | US Dollars | 2 | | UYU | Peso Uruguayo | 2 | | UZS | Uzbekistani Som | 2 | | VEF | Venezuelan Bolívar | 2 | | VND | Vietnamese New Dong | 0 | | VUV | Vanuatu Vatu | 0 | | WST | Samoan Tala | 2 | | XAF | CFA Franc BEAC | 0 | | XCG | Caribbean Guilder | 2 | | XCD | East Caribbean Dollar | 2 | | XOF | CFA Franc BCEAO | 0 | | XPF | CFP Franc | 0 | | YER | Yemeni Rial | 2 | | ZAR | South African Rand | 2 | | ZMW | Zambian Kwacha | 2 | ## Minor units With the exception of [Terminal API](/point-of-sale/design-your-integration/terminal-api), our APIs expect you to submit transaction amount values in **minor units**: the smallest unit of a currency, depending on the number of decimals. Most currencies have two decimals. Some currencies do not have decimals, and some have three decimals. For example: * **GBP 10**: GBP has two decimals, so in minor units you need to submit an amount of *1000* * **JPY 10**: JPY has no decimals, so in minor units you need to submit an amount of *10* * **BHD 10**: BHD has three decimals, so in minor units you need to submit an amount of *10000* ### Different number of decimals For CLP, CVE, IDR, and ISK the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard has a different number of decimals than shown in our [currency codes table](#currency-codes). When submitting amounts in minor units, the decimals in the table on this page are leading. For example, ISK has zero decimals in the ISO 4217 standard, but to submit an ISK amount to Adyen you have to use two decimals as shown in the table. ## Currency conversion rates and fees Sometimes sums have to be converted from one currency to another, for example when the transaction currency differs from the settlement currency. When currency conversions take place, a foreign exchange (FX) reference rate and management fee apply. #### FX reference rate Adyen applies a foreign currency exchange rate when a currency conversion takes place. This is called the FX reference rate. #### FX management fee Adyen also charges a fee for managing the exchange of currency conversions. This is called the FX management fee, or spread. How this fee is calculated is included in your contract with Adyen. By default, the FX management fee differs based on the currency category: * Category one currencies: AUD, CAD, DKK, EUR, GBP, HKD, JPY, NOK, NZD, PLN, SEK, USD, ZAR. * Category two currencies: all other currencies. Your company can also choose an alternative setup, where the FX management fee is based on a scheme rate. This is currently available for Visa and Mastercard. The FX management fee for other payment methods is based on the currency category. --- # Source: https://docs.adyen.com/development-resources/data-protection-api.md Section: Development resources Title: Data Protection API Description: Use our API to comply with GDPR's right to erasure mandate. --- title: "Data Protection API" description: "Use our API to comply with GDPR's right to erasure mandate." url: "https://docs.adyen.com/development-resources/data-protection-api" source_url: "https://docs.adyen.com/development-resources/data-protection-api.md" canonical: "https://docs.adyen.com/development-resources/data-protection-api" last_modified: "2023-05-31T19:51:00+02:00" language: "en" --- # Data Protection API Use our API to comply with GDPR's right to erasure mandate. [View source](/development-resources/data-protection-api.md) Our Data Protection API allows you to process [Subject Erasure Requests](https://gdpr-info.eu/art-17-gdpr/) as mandated in General Data Protection Regulation (GDPR). Use our API to submit a request to delete a shopper's data, including payment details and other shopper-related information, for example, delivery address or shopper email. ## Submit a Subject Erasure Request 1. Send a POST `/requestSubjectErasure` request, specifying: | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchantAccount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your merchant account. | | `pspReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The PSP reference of the original payment authorisation. We will delete all shopper-related data for this payment. | | `forceErasure` | | Set this to **true** if you want to delete shopper-related data, even if the shopper has an existing recurring transaction. This only deletes the shopper-related data for the specific payment, but does not cancel the existing recurring transaction. | ```bash curl https://ca-test.adyen.com/ca/services/DataProtectionService/v1/requestSubjectErasure \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "pspReference":"9915520502347613", "forceErasure": true }' ``` 2. In the response, check the `result` value. ```json { "result": "SUCCESS" } ``` Possible `result` values are: * **SUCCESS**: the request has been received, and will be processed asynchronously. * **ACTIVE\_RECURRING\_TOKEN\_EXISTS**: data cannot be deleted because a recurring transaction is associated with the shopper's payment details. If you want to proceed with deleting shopper data, include `forceErasure`: **true** in your request. * **PAYMENT\_NOT\_FOUND**: the PSP reference doesn't exist. * **ALREADY\_PROCESSED**: we have already received a request for the same PSP reference. After we receive your request, we will delete transaction data in accordance with the Merchant Agreement and redact shopper-related data from the [Customer Area](https://ca-test.adyen.com/). 3. Optional. To verify that the data has been redacted, check the payment in your [Customer Area](https://ca-test.adyen.com/). The shopper data fields are shown as *REDACTED*, and the redaction date is shown in the **Data Protection** section. To switch to live, change the domain to `ca-live.adyen.com`. --- # Source: https://docs.adyen.com/development-resources/developer-dashboard.md Section: Development resources Title: Developer dashboard Description: Keep an eye on the technical performance of your integration. --- title: "Developer dashboard" description: "Keep an eye on the technical performance of your integration." url: "https://docs.adyen.com/development-resources/developer-dashboard" source_url: "https://docs.adyen.com/development-resources/developer-dashboard.md" canonical: "https://docs.adyen.com/development-resources/developer-dashboard" last_modified: "2024-01-29T14:34:00+01:00" language: "en" --- # Developer dashboard Keep an eye on the technical performance of your integration. [View source](/development-resources/developer-dashboard.md) The Developer dashboard shows a performance overview of your integration. We recommend that you use it for monitoring your integration's health, for example to detect increased failure rates, and to fix errors. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Integration type** | Any integration with Adyen. | | **[Customer Area roles](/account/user-roles)** | Make sure that you have one of the following roles:- **Merchant admin** - **Merchant technical integrator** | | **Limitations** | The dashboard shows only [specific APIs and webhooks](#included). | ## Integration and account information The Developer dashboard shows the activity and errors that occurred with your API requests and webhooks in the past seven days. You can select a different time range and time interval. The **Integration activity** panel shows a graph with the number of API requests from your server and webhooks that we sent to your server. The **Errors** panel shows a list of errors from your API requests and webhooks. You can select each error item to navigate to the logs with more details. The **Integration types** panel shows an overview of the different integration types that your account uses. Depending on what you use, the widget can show the following tabs: * **APIs**: The APIs that you integrated with. * **Libraries**: The [Adyen libraries](https://github.com/Adyen) that you use in your integration. * **Plugins**: The [plugin](/plugins) that you use for processing payments with Adyen. * **Checkout SDKs**: Our [client-side Drop-in and Components](https://github.com/Adyen#online-payments). ** #### Integration types The following list shows the types of payments integrations that can show up in the **Integration types** panel. **Online Payments** * [Checkout API with Client-Side Encryption](/payment-methods/cards/custom-card-integration) * [Checkout API with JSON Web Encryption](/payment-methods/cards/custom-card-integration) * [Checkout API with raw card data](/payment-methods/cards/raw-card-data) * [Checkout API - Sessions flow](/online-payments/build-your-integration/sessions-flow/) * [Checkout API - Advanced flow](/online-payments/build-your-integration/advanced-flow/) * [Checkout API with Card Component](/payment-methods/cards/web-component/) * [Hosted Checkout](/online-payments/build-your-integration/sessions-flow/?platform=Web\&integration=Hosted%2BCheckout) * [Classic API with Client-Side Encryption (deprecated)](/online-payments/classic-integrations/classic-api-integration/client-side-encryption) * [Classic API with raw card data (deprecated)](/online-payments/classic-integrations/classic-api-integration) * [Classic API (deprecated)](/online-payments/classic-integrations/classic-api-integration/): This is a catch-all for Classic API use cases that are not captured by the other listed items. **In person payments** * [Terminal API](/point-of-sale/design-your-integration/terminal-api) * [POS Mobile SDK](/point-of-sale/ipp-mobile) * [Adyen Payments App](/point-of-sale/ipp-mobile) * [Oracle Payment Interface](/plugins/oracle-xstore) * [Classic Library (deprecated)](/point-of-sale/classic-library-deprecation) * [IPP](/point-of-sale): This is a catch-all for in-person payments APIs that are not captured by the other listed items. **Omnichannel** * [Pay by Link](/unified-commerce/pay-by-link) * [MOTO Call Center](/point-of-sale/mail-and-telephone-order-moto) * [Virtual Terminal](/unified-commerce/mail-order-telephone-order/customer-area) The Developer dashboard also includes panels with: * **Live URL prefix**: The [URL prefix](/development-resources/live-endpoints#live-url-prefix) for the live URL where you send your API requests. This is only available in your live Customer Area. * **Account details**: The information that you used to set up your Adyen account, such as account ID and legal entity name. * **Company contacts**: The names and email addresses of people in your organization. For example, the Customer Area account administrator. * **Helpful resources**: Links that can help you complete, maintain, and update your integration. For example, a link to Adyen's Postman collections. ## Monitor your integration's performance To access the developer dashboard, you must have one of the following [user roles](/account/user-roles): * **Merchant admin** * **Merchant technical integrator** 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Dashboard**. 2. To track trends in the success of API requests and webhooks, in the **Integration activity** panel: * Select different time ranges and intervals. * Switch between viewing the success rate of requests and webhooks, or a count of successful and failed requests and webhooks. 3. To drill down on errors, open the relevant page in the [API logs](/development-resources/logs-resources/api-logs) or [webhook event logs](/development-resources/logs-resources/webhook-event-logs) in any of the following ways: * In the **Integration activity** panel, hold your cursor over a data point in the graph and select **View logs**. * In the **Errors** panel, select **View logs** for the error that interests you. In the logs, you can then select a log item to inspect it further. ## See also * [Webhooks](/development-resources/webhooks) * [Logs](/development-resources/logs-resources/) * [Account](/account) --- # Source: https://docs.adyen.com/development-resources/documentation-tools.md Section: Development resources Title: Documentation and knowledge tools Description: Discover, access, and get updates to Adyen documentation using AI and programmatic tools. --- title: "Documentation and knowledge tools" description: "Discover, access, and get updates to Adyen documentation using AI and programmatic tools." url: "https://docs.adyen.com/development-resources/documentation-tools" source_url: "https://docs.adyen.com/development-resources/documentation-tools.md" canonical: "https://docs.adyen.com/development-resources/documentation-tools" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Documentation and knowledge tools Discover, access, and get updates to Adyen documentation using AI and programmatic tools. [View source](/development-resources/documentation-tools.md) Adyen makes documentation accessible to developers as well as the software and AI tools they create. To support this, we have implemented features that help you index and discover our documentation, read plain text versions of the pages, and receive updates about Adyen products and APIs. ## Discover documentation ### llms.txt To help large language models (LLMs) discover and index our documentation, we provide a `/llms.txt` file. This file, located at the root of our documentation site, contains a list of all documentation pages grouped by their product category. It follows the [proposed standard](https://llmstxt.org/) to help LLMs discover documentation. It is is similar to the `sitemap` file, but is specifically designed for consumption by AI and provides additional context. This file allows you to easily get a list of all available documentation pages that you can then provide to your own custom AI models or tools, for example, to build a custom AI assistant that can answer questions about Adyen products. You can access llms.txt at `https://docs.adyen.com/llms.txt` ### Sitemap A sitemap is a file where you can get a list of all the pages on the Adyen documentation website. You can use this to programmatically get a full list of all available documentation pages. While similar to the `llms.txt` file, the sitemap is a more general-purpose tool that can be used for a wide range of applications, including: * **Web scraping:** You can use the sitemap to build a web scraper that fetches all our documentation pages. * **Search indexing:** If you are building a search engine, you can use the sitemap to index all our documentation pages. * **Content discovery:** You can use the sitemap to discover new content on our documentation site. You can access the sitemap at: `https://docs.adyen.com/sitemap` ## Access documentation ### OpenAPI Specification The Adyen OpenAPI Specification repository on GitHub contains [OpenAPI specifications](https://www.openapis.org/) for every public API Adyen offers. These specifications are the single source of truth for our APIs and can be used to: * **Generate client libraries:** You can use tools like [OpenAPI Generator](https://openapi-generator.tech/) to generate client libraries in your preferred programming language. Adyen generates [server-side libraries](https://docs.adyen.com/development-resources/libraries) using a similar technique. * **Create Postman collections:** The repository also includes Postman collections that you can import to start testing our APIs right away. Adyen provides [Postman collections](https://github.com/Adyen/adyen-postman) for some of our APIs that are also based on the OpenAPI specifications. * **Understand API functionality:** The specifications provide a detailed, machine-readable description of every endpoint, including parameters, request and response bodies, and headers. * **Provide context to LLMs:** The specification files can be used as valuable context to code assistants when working with Adyen APIs, especially when paired with [Adyen MCP](/development-resources/mcp-server). You can access the OpenAPI specifications at: `https://github.com/Adyen/adyen-openapi` ### Markdown pages Most pages on our documentation site can be rendered as a raw markdown file by simply appending `.md` to the URL. This provides a clean, machine-readable version of the content, stripped of all the website's navigation and styling. This feature is particularly useful for: * **Feeding content into LLMs:** You can fetch the raw markdown content of any page and use it as context for your AI models. * **Local development:** You can easily download and use our documentation in your local development environment. * **Content analysis:** You can programmatically analyze our documentation content. For example, if you are viewing the webhooks documentation at:\ `https://docs.adyen.com/development-resources/webhooks` You can access the raw markdown version at:\ `https://docs.adyen.com/development-resources/webhooks.md` ### Full documentation mirror Adyen provides a full documentation mirror as a compressed ZIP file. The mirror contains all documentation pages in plain markdown. Use it to access documentation offline. You can also provide the mirror to AI agents as context. If your AI agents need to frequently fetch individual markdown files over the internet, use the mirror instead. This reduces the number of network calls and improves performance. You can use the documentation mirror to: * **Develop locally:** Keep a full copy of the documentation for quick reference, without an internet connection. * **Give context to AI agents:** Provide the full documentation set to code assistants, chatbots, or other AI tools. This works well in restricted or air gapped environments. AI agents can traverse file trees and locate the right resources from a local copy. * **Analyze content in bulk:** Search, index, or analyze the full documentation set without network requests. You can download the full documentation mirror: [adyen-docs-mirror.zip](/development-resources/documentation-tools/adyen-docs-mirror.zip) ## Get updates ### Release notes The release notes are the best way to stay up-to-date with the latest changes to Adyen products and APIs. We publish release notes for all our products, including APIs, libraries, and plugins. The release notes are grouped by product area, so you can easily find the information you need. We recommend that you regularly check the release notes for the products you use to stay informed about new features, bug fixes, and other changes. You can find all release notes at: ### RSS Feed You can stay up to date with the latest changes by subscribing to our RSS feeds. RSS feeds provide a way to get updates from a website in a standardized, computer-readable format. You can use an RSS reader to subscribe to these feeds and get notified of new content. For example, you can subscribe to the RSS feed for plugin release notes to get notified of new releases for our plugins. * [Plugin release notes RSS feed](https://docs.adyen.com/plugins/release-notes.xml) We also provide release notes for other product areas. Check the specific release notes pages for those products for more information. ## See also * [Improving the developer experience with OpenAPI Specification](https://www.adyen.com/knowledge-hub/improving-the-developer-experience-with-openapi-specification) * [How Adyen does AI](https://www.adyen.com/knowledge-hub/how-adyen-does-ai) * [Building better applications with Adyen API Libraries](https://www.adyen.com/knowledge-hub/adyen-api-libraries) * [Introducing the MCP server: A smarter way to build with Adyen](https://www.adyen.com/the-latest/introducing-the-mcp-server-a-smarter-way-to-build-with-adyen) --- # Source: https://docs.adyen.com/development-resources/e2ee-p2pe-comparison.md Section: Development resources Title: Adyen's E2EE and P2PE PCI security Description: Make an informed choice between Adyen's E2EE and P2PE solutions for payment terminals. --- title: "Adyen's E2EE and P2PE PCI security" description: "Make an informed choice between Adyen's E2EE and P2PE solutions for payment terminals." url: "https://docs.adyen.com/development-resources/e2ee-p2pe-comparison" source_url: "https://docs.adyen.com/development-resources/e2ee-p2pe-comparison.md" canonical: "https://docs.adyen.com/development-resources/e2ee-p2pe-comparison" last_modified: "2025-09-10T15:43:00+02:00" language: "en" --- # Adyen's E2EE and P2PE PCI security Make an informed choice between Adyen's E2EE and P2PE solutions for payment terminals. [View source](/development-resources/e2ee-p2pe-comparison.md) Point-to-Point Encryption (P2PE) is a standard developed by the Payment Card Industry (PCI). The purpose of this standard is to protect the transmission of payment messages from payment terminals to the acquirer networks against data breaches. By default, Adyen protects such transmissions using the Adyen End-to-End Encryption (E2EE) solution. When implementing a point-of-sale integration with Adyen, you have the option to use either Adyen's E2EE or P2PE. Here, you can find a comparative overview of the P2PE standard and Adyen's E2EE with their technical differences, security characteristics, and implementation aspects to help you make an informed decision. ## Adyen's E2EE solution Compared to other acquirers, Adyen is unique because we cover the **whole payments value chain** by managing the entire payment flow from payment terminal to final settlement. Adyen's end-to-end solution protects payment messages by encrypting them at the terminal and decrypting them at the platform before sending them for authorization to the issuing bank. This prevents anyone in the middle from gaining access to sensitive data in the payment messages, such as cardholder data. The following diagrams show the exchange of payment messages in the traditional payments value chain, and in Adyen's payments value chain. [![](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/traditional-value-chain.png "Traditional payments value chain")](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/traditional-value-chain.png) [Traditional payments value chain](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/traditional-value-chain.png) [![](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-value-chain.png "Adyen payments value chain")](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-value-chain.png) [Adyen payments value chain](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-value-chain.png) By default, the payment terminals provided by Adyen are all [PTS-approved](https://www.pcisecuritystandards.org/assessors_and_solutions/pin_transaction_devices?agree=true) Point-of-Interaction (POI) devices using E2EE to protect the payment messages. [![](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-e2ee.jpg "Adyen E2EE solution - The full payment message is encrypted")](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-e2ee.jpg) [Adyen E2EE solution - The full payment message is encrypted](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-e2ee.jpg) ## Adyen's P2PE solution As an alternative to E2EE, you can opt-in to use Adyen's P2PE solution. This solution includes: * [PCI-approved](https://listings.pcisecuritystandards.org/popups/p2pe_sol_device.php?reference=2023-01213.005) P2PE payment solution. * Encryption of the Personal Account Number (PAN) and the track data (for authenticating the cardholder and/or authorizing card transactions) in the payment message. * Compliance with the P2PE Instruction Manual. The separate encryption of the PAN and track data adds an extra encryption layer. Compliance with the P2PE Instruction Manual means that both Adyen and you need to implement various operational measures, to meet logistical, monitoring, and other requirements. For example, store staff will need to inspect the terminals regularly and keep an audit trail of these inspections. [![](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-p2pe.jpg "Adyen P2PE solution - Encrypted PAN and track data inside the encrypted payment message")](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-p2pe.jpg) [Adyen P2PE solution - Encrypted PAN and track data inside the encrypted payment message](/user/pages/docs/13.development-resources/33.e2ee-p2pe-comparison/adyen-p2pe.jpg) ## Comparing Adyen P2PE and E2EE Here is an overview table comparing the two encryption solutions. | | P2PE | E2EE | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Supported terminals** | e280, e285, M400, P400 Plus, V240m, V400c Plus, V400m, UX-series, AMS1, M450, P630, S1F2, S1F2L, S1U2, and S1E2L. | All Adyen-provided terminal models. | | **Compliance** | In addition to the SAQ P2PE, you need to implement P2PE Instruction Manual requirements. | Adyen's default point-of-sale integration is designed to reduce your PCI DSS scope as much as possible. You only have to complete the SAQ B-IP, which is a relatively easy questionnaire with a limited number of requirements. | | **Security** | Because cardholder data such as the full PAN and the track data is encrypted separately, malicious actors cannot access this data. | Adyen's E2EE encrypts the complete payment message, including all cardholder data, which is transferred directly from the POI to the point of processing, with nothing in between. | | **Quality** | An independent organization "stamp" validates the security of the solution. | While E2EE is secure, it does not have the PCI P2PE-validated “stamp”. | Take a look at the following sections for a detailed comparison of P2PE and E2EE solutions covering compliance, security, and quality aspects. If you need more information, contact your Adyen account manager or sales manager. ### Supported terminals * **P2PE:** e280, e285, M400, P400 Plus, V240m Plus, V400c Plus, V400m, UX-series, AMS1, M450, P630, S1F2, S1F2L, S1U2, and S1E2L. * **E2EE:** All Adyen-provided payment terminal models. ### Compliance * **P2PE:** it is claimed that using P2PE reduces PCI DSS scope, requiring the 33-requirement SAQ P2PE. In addition to the SAQ P2PE, you need to implement all requirements of the P2PE Instruction Manual. * **E2EE:** Adyen's default point-of-sale integration is designed to reduce your PCI DSS scope as much as possible. You only have to complete the SAQ B-IP, which is a relatively easy questionnaire with a limited number of requirements. Compared to Adyen's E2EE solution, using P2PE will result in an increased operational effort because with P2PE you need to comply with both the **SAQ P2PE and the P2PE Instruction Manual**. For an integration overview and the self-assessment questionnaires, go to our [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide?tab=e2ee_1#in-person-payments). ### Security * **P2PE:** because cardholder data such as the full PAN and the track data is encrypted separately, malicious actors will not be able to access this data. * **E2EE:** the same is true for Adyen's E2EE solution. This encrypts the complete payment message, including all cardholder data.\ With many E2EE solutions there's an increased risk of fraud or hacking, because there are other systems between the point of interaction (POI) and the point of processing. With Adyen's E2EE solution, the cardholder data is transferred directly from the POI to the point of processing, with nothing in between. Because Adyen manages the whole payments value chain and encrypts the complete payment message, the default Adyen E2EE solution and the P2PE solution are equally secure. ### Quality * **P2PE:** an independent organization validates the security of the solution. * **E2EE:** E2EE is secure, but does not have an official PCI P2PE-validated 'stamp'. Ultimately, it is up to you to decide which option works best for you: Adyen E2EE or P2PE. Keep in mind that the default E2EE solution already is an end-to-end solution. Adyen's P2PE solution offers the benefit of being PCI-certified, but the tradeoff is that it requires additional operational effort. ## See also * [P2PE Instruction Manual](https://www.adyen.com/legal/p2pe-instruction-manual) * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) * [PCI DSS FAQs](https://help.adyen.com/knowledge/compliance/pci-dss-compliance) --- # Source: https://docs.adyen.com/development-resources/error-codes.md Section: Development resources Title: Error codes and messages Description: Learn about the meaning of API error codes. --- title: "Error codes and messages" description: "Learn about the meaning of API error codes." url: "https://docs.adyen.com/development-resources/error-codes" source_url: "https://docs.adyen.com/development-resources/error-codes.md" canonical: "https://docs.adyen.com/development-resources/error-codes" last_modified: "2020-04-25T16:42:00+02:00" language: "en" --- # Error codes and messages Learn about the meaning of API error codes. [View source](/development-resources/error-codes.md) When you make an API call to Adyen and there is an error, you will receive a response with [HTTP status code](/development-resources/response-handling) different from `2xx`. This response includes `errorCode` and `message` fields that help you diagnose and resolve the error. All integrations can receive generic error codes. There are also error codes specific to an integration type or a payment method. ## Requirements | Requirement | Description | | -------------------- | --------------------------------------------------------------------------- | | **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. | ## Example error response **Error details in an API response** ```json { "status" : 422, "errorCode" : "101", "message" : "Invalid card number", "errorType" : "validation", "pspReference" : "F7WCWRG6JPHR8HG2" } ``` | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Specifies the [HTTP status code](/development-resources/response-handling) for the API request. For a value of **422**, the request is well-formed (syntactically correct), but semantically incorrect: the receiving server can read it, but cannot understand it. | | `errorCode` | The Adyen code that is mapped to the error message. For a value of **101**, the request contains an incorrect card number or length. | | `message` | A short explanation of the error. For a value of **Invalid card number**, the request contains an incorrect card number or length. | | `errorType` | The category of the error: **internal**, **validation**, **security**, or **configuration**. For a value of **validation**, the request is missing required fields or contains invalid data. | ## Generic error codes ### 000 - Multiple messages The **000** error code is a generic error code with several possible messages and causes; for example: * Unknown: Unauthorised: The API key or Auth credentials are incorrect. * Unable to parse message. *** ### 010 - Not allowed **Cause**: * The API credential is missing required roles. * The user API is incorrect. * You are making a [third-party](/point-of-sale/shopper-engagement/third-party-interactions#security-and-requirements) payment or card acquisition request to your terminals. *** ### 100 - Required object 'amount' is not provided **Cause**: Missing parameter\ **Solution**: * Add the missing parameter(s) `amount` or `originalReference`. * Compare your request with a standard request for that endpoint, and identify missing parameters. *** ### 101 - Invalid card number **Cause**: * Incorrect card number or length. * Incorrect capitalization of `PaRes`. *** ### 102 - Unable to determine variant **Cause**: The card number field contains an incorrect value. *** ### 103 - CVC is not the right length **Cause**: * The Card Validation Code (CVC) is not valid. * The CVC is alphanumeric instead of numeric-only. * There are more than three digits. * (American Express) There are more than four digits. *** ### 104 - Billing address problem **Cause**: Missing a required field under `billingAddress`.\ **Solution**: Check the `billingAddress` object for missing fields. *** ### 105 - Invalid paRes from issuer * **Cause**: The issuer returns an URL-encoded `PaRes` or `MD`.\ **Solution**: URL-decode the `PaRes` and `MD` before submitting them in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. * **Cause**: The issuer returns the correct `PaRes` value, but the parameter name is different from `PaRes`, for example `PaResponse` or `paRes`\ **Solution**: Adyen only accepts this parameter as `PaRes`. If the issuer has returned something different, make sure that you change it to `PaRes` before submitting it in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request. * **Cause**: The `PaRes` parameter is empty, or some other reason different from the above.\ **Solution**: Ask your shopper to contact the issuing bank to report the error. *** ### 106 - This session was already used previously *** ### 107 - Recurring is not enabled **Cause**: Missing user permission.\ **Solution**: Add the **Merchant Recurring** role to the associated web service user. *** ### 108 - Invalid bankaccount number **Cause**: The IBAN is incorrect. *** ### 109 - Invalid variant **Cause**: Missing `txvariant` details.\ **Solution**: Check the `requestData` and pass the details correctly. *** ### 110 - BankDetails missing **Cause**: * The IBAN is missing. * The IBAN is incorrect. *** ### 111 - Invalid BankCountryCode specified **Cause**: * The parameter name is spelled incorrectly. * The value passed for `countryCode` is not following the ISO standard. **Solution**: * Confirm the parameter name spelling in the Adyen API Explorer. * Check that the `countryCode` value corresponds to a country and is spelled correctly; for example, use **DE** for Germany. *** ### 112 - This bank country is not supported **Cause**: * `countryCode` length does not follow the ISO standard. * `countryCode` does not exist. *** ### 113 - No InvoiceLines provided **Cause**: Invoice lines are missing in the `requestData`. *** ### 114 - Received an incorrect InvoiceLine **Cause**: Incorrect currency used, or the `lineReference` is **null**.\ **Solution**: Check the invoice line against the `requestData`. *** ### 115 - Total amount is not the same as the sum of the lines **Cause**: `linesTotalQuantity` is not equal to `request.getAmount().getValue()`. *** ### 116 - Invalid date of birth **Cause**: The `dateOfBirth` format is incorrect.\ **Solution**: Check the date and format in the `dateOfBirth` parameter. *** ### 117 - Invalid billing address **Cause**: The `billingAddress` object does not contain all the required fields.\ **Solution**: Check the required parameters in the API Explorer. *** ### 118 - Invalid delivery address **Cause**: * The `deliveryAddress` is **null**. * The `deliveryAddress` format is invalid. *** ### 119 - Invalid shopper name **Cause**: The `shopperName` is **null**. *** ### 120 - Required field 'shopperEmail' is not provided **Cause**: * The `shopperEmail` is missing. * The `shopperEmail` format is invalid. *** ### 121 - Required field 'shopperReference' is not provided **Cause**: * The `shopperReference` is **null**. * Recurring requires `shopperReference` *** ### 122 - Required field 'telephoneNumber' is not provided. **Cause**: The `phoneNumber` or `telephoneNumber` is **null**. *** ### 124 - Invalid PhoneNumber *** ### 125 - Invalid recurring contract specified **Cause**: The recurring object is not passed correctly.\ **Solution**: Check the `requestData` and make sure the recurring object is correct. *** ### 126 - Bank Account or Bank Location Id not valid or missing *** ### 127 - Required field 'accountHolderName' is not provided *** ### 128 - Required field 'card.holderName' is not provided *** ### 129 - Expiry Date Invalid **Cause**: * The value is not numeric. * The value contains an empty space. * The expiry month is not set. * The month value is not between **1** and **12**. **Solution**: Check the input passed into field. *** ### 130 - Reference Missing **Cause**: * The `reference` parameter is missing. * The `requestData` is missing multiple parameters. **Solution**: Check if the `reference` parameter is passed correctly. *** ### 131 - Required field 'billingAddress.city' is not provided *** ### 132 - Required field 'billingAddress.street' is not provided *** ### 133 - Required field 'billingAddress.houseNumberOrName' is not provided *** ### 134 - Billing address problem (Country) *** ### 135 - Required field 'billingAddress.stateOrProvince' is not provided *** ### 136 - Failed to retrieve OpenInvoiceLines *** ### 137 - Field 'amount' is not valid **Cause**: * The `amount` passed is greater than the limit. * The `amount` passed is not a positive number. **Solution**: Check the input. *** ### 138 - Field 'currency' is not valid **Cause**: The provided currency is not supported. *** ### 139 - Recurring requires 'shopperEmail' and 'shopperReference' **Cause**: The `shopperReference` and `shopperEmail` are missing. *** ### 140 - Invalid expiryMonth\[1..12] / expiryYear\[>2000], or before now *** ### 141 - Invalid expiryMonth\[1..12] / expiryYear\[>2000] *** ### 142 - Bank Name or Bank Location not valid or missing *** ### 143 - Submitted total iDEAL merchantReturnUrl length is {0}, but max size is {1} for this request *** ### 144 - Invalid startMonth\[1..12] / startYear\[>2000], or in the future *** ### 145 - Invalid issuer countryCode *** ### 146 - Invalid social security number *** ### 147 - Required field 'deliveryAddress.city' is not provided *** ### 148 - Required field 'deliveryAddress.street' is not provided * **Cause**: You are not sending all parameters.\ **Solution**: Pass all required parameters. * **Cause**: You are sending all parameters, but the value is empty.\ **Solution**: Make sure that you pass data in each parameter. *** ### 149 - Required field 'deliveryAddress.houseNumberOrName' is not provided *** ### 150 - Delivery address problem (Country) *** ### 151 - Required field 'deliveryAddress.stateOrProvince' is not provided **Cause**: `stateOrProvince` field is missing in delivery address and is required for the selected country. *** ### 152 - Invalid number of installments **Cause**: * Installment value is zero. * The payment method is not set up with **installment**. **Solution**: * Check the `requestData`. * Configure **installment** under the specific payment method; for example, Visa. *** ### 153 - Invalid CVC **Cause**: * The Card Validation Code (CVC) is not numeric. * The CVC contains invalid values. **Solution**: Check the CVC input. *** ### 154 - No additional data specified *** ### 155 - No acquirer specified *** ### 156 - No authorisation mid specified *** ### 157 - No fields specified *** ### 158 - Required field {0} not provided **Cause**: One of the following fields is missing: * `initialPspReference` * `orderReference` * `ownerName` * `reference` **Solution**: Supply the missing value. *** ### 159 - Invalid number of requests *** ### 160 - Not allowed to store Payout Details *** ### 161 - Invalid iban **Cause**: * The IBAN is incorrect. * There is a mismatch between IBAN and country. * The bank does not support SEPA direct debit. **Solution**: * Verify the IBAN number. * Check if IBAN is supported for the specified `countryCode`. *** ### 162 - Inconsistent iban **Cause**: * Swift Code / BIC does not exist - SEPA/Giro/Direct Debit. * Payout party/account BIC/Swift invalid. * Bank/mt940 - Invalid BIC/Swift in co-relation to `countryCode`. * Exceeded IBAN characters/digits. *** ### 163 - Invalid bic *** ### 164 - Auto capture delay invalid or out of range *** ### 165 - MandateId does not match pattern *** ### 166 - Amount not allowed for this operation *** ### 167 - Original pspReference required for this operation **Cause**: The original PSP in the `requestData` field is missing. *** ### 168 - AuthorisationCode required for this operation *** ### 170 - Generation Date required but missing *** ### 171 - Unable to parse Generation Date *** ### 172 - Encrypted data used outside of valid time period **Cause**: Your server-side date/time is not set up correctly. For example, your server side is set to 1975 when it is 2020, or the date is not within 24 hours of the current time.\ **Solution**: Check the server-side date/time configuration. *** ### 173 - Unable to load Private Key for decryption *** ### 174 - Unable to decrypt data **Cause**: * Using `HTTP GET` instead of `HTTP POST`. * Environment mismatch (LIVE or TEST). * The Origin key/Client key was not generated correctly. * API key should match the API key from the web service user, and should match the environment. **Solution**: If you are seeing this using a plugin, generate a new web service user with the relevant permissions. *** ### 175 - Unable to parse JSON data **Cause**: Make sure that the parameters sent are formatted correctly in JSON.\ **Solution**: Read through the `requestData` to find the error. *** ### 180 - Invalid shopperReference **Cause**: `shopperReference` is empty, doesn't exist, or is not found. *** ### 181 - Invalid shopperEmail **Cause**: `shopperEmail` is empty, doesn't exist, or is not found. *** ### 182 - Invalid selected brand **Cause**: The selected brand is not equal to the brand on the stored token, or empty. *** ### 183 - Invalid recurring contract **Cause**: Not found in Recharge. *** ### 184 - Invalid recurring detail name **Cause**: * Value is empty or **null**. * The name doesn't match with the `recurringDetail` name. *** ### 185 - Invalid additionalData * **Cause**: Too many fields/entries.\ **Solution**: Make sure that the number of items in the object is less than 1000. * **Cause**: The `splitPayment` is missing or invalid.\ **Solution**: Check the `additionalData` object for errors or missing data. If any `additionalData` is not valid, remove it from modification processing. For example, a payment can go through, but a split will not. * **Cause**: `adyenGivingAccount` is not specified, cannot be retrieved, or does not exist.\ **Solution**: When using Adyen for Platforms, make sure `itemReference` is unique. *** ### 186 - Missing additionalData field *** ### 187 - Invalid additionalData field **Cause**: * Too many fields/entries. * SplitPayment missing/not valid. * AdyenGivingAccount not specified, cannot be retrieved or does not exist. *** ### 188 - Invalid pspEchoData **Cause**: The previous `recurringDetail` token was not saved correctly or does not exist. *** ### 189 - Invalid shopperStatement **Cause**: Empty value passed in `requestData`. *** ### 190 - Invalid shopper IP **Cause**: The `shopperIP` is empty. *** ### 191 - No params specified *** ### 192 - Invalid field {0} **Cause**: `shopperInteraction` is invalid. *** ### 193 - Bin Details not found for the given card number **Cause**: * Not sending in correct parameters. * Not passing applicable value. *** ### 194 - Billing address missing **Cause**: Required object `billingAddress` is missing. *** ### 195 - Could not find an account with this key: {0} *** ### 196 - Invalid Mcc **Cause**: * Check MCC length. * Should be a numeric value. * An alphanumeric value is provided. *** ### 198 - Reference may not exceed 79 characters **Cause**: The reference contains more than 80 characters. *** ### 199 - The cryptographic operation could not proceed, no key configured *** ### 200 - Invalid country code **Cause**: Incorrect `countryCode`.\ **Solution**: Use ISO 3166-1 alpha-2 format. *** ### 203 - Invalid Bank account holder name **Cause**: * Account holder name is inconsistent with FATF 16 recommendations. * Name may not contain numbers. *** ### 205 - Missing or invalid networkTxReference **Cause**: * Only digits provided. * Incorrect format. * Must have an alphanumeric combination. * Can also occur if recurring value is **null**. *** ### 213 - Required field 'socialSecurityNumber' is not provided. **Cause**: The `socialSecurityNumber`, which is required for the payment method, is missing. *** ### 217 - Field 'shopperInteraction' is missing or invalid *** ### 218 - Recurring shopper lookup failed *** ### 600 - No InvoiceProject provided *** ### 601 - No InvoiceBatch provided *** ### 602 - No creditorAccount specified *** ### 603 - No projectCode specified *** ### 604 - No creditorAccount found *** ### 605 - No project found *** ### 606 - Unable to create InvoiceProject *** ### 607 - InvoiceBatch already exists *** ### 608 - Unable to create InvoiceBatch *** ### 609 - InvoiceBatch validity period exceeded *** ### 690 - Error while storing debtor *** ### 691 - Error while storing invoice *** ### 692 - Error while checking if invoice already exists for creditorAccount *** ### 693 - Error while searching invoices *** ### 694 - No Invoice Configuration configured for creditAccount *** ### 695 - Invalid Invoice Configuration configured for creditAccount *** ### 700 - No method specified *** ### 701 - Server could not process request **Cause**: * Incorrect POST / Content Type. * Might be sending XML, HTTP etc. * Using Pay by Link with incorrect `shopperReference`. * API version not specified. * RequestURL is not valid. **Solution**: * Send JSON formatted, send HTTP POST. * Pay by Link: make sure the web service user has the required permissions. *** ### 702 - Problem parsing request **Cause**: * The request contains a field that is not recognized, or the format is not valid. This validation was introduced in [API v64](/online-payments/release-notes#releaseNote=2020-08-09-checkout-api-64). * Empty input which would have resulted in a null result: you might be using `requestData` from the API Explorer without populating your merchant account details. * Internal Error. *** ### 703 - Required resource temporarily unavailable **Cause**: The [data store](/development-resources/api-idempotency/#designing-for-resilience) is not available to compare the request against.\ **Solution**: Retry your request later or do not include the `idempotency-key` HTTP header in your request. *** ### 704 - Request already processed or in progress **Cause**: The web service user is sending multiple authorised requests.\ **Solution**: Check that you send in requests only once. *** ### 705 - Rate limited **Cause**: The rate limit for API requests has been exceeded.\ **Solution**: Throttle your API requests. Wait for a short duration before retrying the request. *** ### 800 - Contract not found **Cause**: * `shopperReference` does not exist. * The `requestData` is creating a contract and using the `recurringDetailReference` at the same time. **Solution**: Check if the details were saved previously, check the `shopperReference`. *** ### 801 - Too many PaymentDetails defined **Cause**: The root cause of these timeouts is too many `paymentDetails`, or an incorrect integration for the same recurring or shopper reference. *** ### 802 - Invalid contract **Cause**: There are no valid contract types (recurring or OneClick), or the contract type is not one of RECURRING, ONECLICK, or PAYOUT.\ **Solution**: Check the data that is sent in on the PAL, and then the data that is sent in on the PAL. Check the recharge service under the recurring field. *** ### 803 - PaymentDetail not found **Cause**: * `recurringDetailReference/storedPaymentMethodId` does not exist. * It has been disabled. * `requestData` is missing; for example, open invoice `lineItems` for Klarna. * The payment method specified in your request varies from the one in your created token. **Solution**: Check if the values being passed are correct and valid. ### 803\_3 - No active payment details found for shopper reference **Cause**: * Either the shopper reference is not valid, or all details have been disabled. **Solution**: Check if the values being passed are correct and valid. *** ### 804 - Failed to disable *** ### 805 - RecurringDetailReference not available for provided recurring-contract *** ### 806 - No applicable contractTypes left for this payment-method **Cause**: The `txvariant` Maestro cannot have recurring. The scheme mandates 3D Secure for all Maestro transactions, which is why recurring transactions are not possible.\ **Solution**: Recreate the contract, check the contract creation parameters or change current `requestData`. *** ### 807 - Invalid combination of shopper interaction and recurring-contract **Cause**: Recurring contract was not set up with `shopperInteraction`. *** ### 820 - CVC is required for OneClick card payments **Cause**: The Card Validation Code (CVC) was not supplied\ **Solution**: Supply the CVC number *** ### 901 – Invalid Merchant Account **Cause**: * You sent an incorrect `merchantAccount`. * The merchant data (MD) value is incorrect when running the 3D Secure flow. * The web service is not permitted for the specified `merchantAccount`. * The company is not active. * The `merchantAccount` value is passed with incorrect casing (the value is case-sensitive). **Solution**:\ Make sure that: * The MD value is not reused. * The `merchantAccount` in the request exists and matches exactly, including casing. * The web service you are calling is enabled for the `merchantAccount`. *** ### 902 - Invalid or empty request data *** ### 903 - Internal error *** ### 904 - Unable To Process **Cause**: Error communicating with Adyen. *** ### 905 - Payment details are not supported The **905** error code is a generic error code with several possible messages and causes. These errors are visible in your Customer Area, and occur when your account is not configured to support the payment method, currency, or the country. **Cause**: * Missing `paymentMethod` in your Customer Area. * `paymentMethod` not set up for `countryCode`. **Solution**: Make sure that the `countryCode` in `requestData` matches the `paymentMethod` txvariant in your Customer Area. For example, **bankTransfer\_DE** should match with `countryCode` **DE** in `requestData`. *** ### 905\_1 - Could not find an acquirer account for the provided txvariant ({0}), currency ({1}), and action ({2}) In the context of this error code, acquirer account refers to your merchant account. **Cause**: The payment method is not set up in this merchant account. **Solution**: [Add the payment method](/payment-methods/add-payment-methods) in your Customer Area. *** ### 905\_2 - No specified acquirer account found for '{0}' for specified acquirer '{1}' with variant '{2}' for unit '{3}' for Action '{4}' In the context of this error code, acquirer account refers to your merchant account. **Cause**: You specified merchant plug-in (MPI) data without specifying an acquirer code. **Solution**: Set the `defaultToAcquirerSelectionRegardlessOfMPIData` account data property (ADP) to **true**. This defaults to an acquirer account if you have multiple configured. Contact the [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to modify ADPs. *** ### 905\_3 - Could not find an acquirer account for the provided currency ({0}) In the context of this error code, acquirer account refers to your merchant account. * **Cause**: The payment type (`shopperInteraction`) is not supported.\ **Solution**: Make sure that the payment method supports the shopper interaction that you are trying to use, and adjust the shopper interaction on your request or payment method settings. * **Cause**: The payment method is set up for a specific store, and the store was not specified in the request.\ **Solution**: Adjust the request (send the store number) or the payment method (remove the store restriction). * **Cause**: The minimum amount is set too low.\ **Solution**: Check the payment method's constraints and adjust your API request. * **Cause**: There is a transaction rule set up that does not allow this amount or payment method.\ **Solution**: Adjust your request or the transaction rules. * **Cause**: The currency is not configured or supported.\ **Solution**: Set up the payment method in the desired currency. * **Cause**: There is a `customRoutingFlag` set up in the payment method, and you are not sending it in your request body.\ **Solution**: Send the `customRoutingFlag` in the `additionalData` object. * **Cause**: The bank identification number (BIN), country, currency, or issuer is restricted.\ **Solution**: Adjust the request or the payment method; for example, prompt the customer for a different payment method, or remove the store restriction. Under certain circumstances related to this error, the payment cannot be processed. *** ### 905\_4 - Cashback and Cashout are not allowed for the configured acquirer account In the context of this error code, acquirer account refers to your merchant account. **Cause**: Your merchant account does not allow the cashback or cashout options. This functionality is specific to EFTPOS (Electronic Funds Transfer at Point Of Sale), which is a card scheme available only in Australia and New Zealand.\ **Solution**: To perform cashbacks or cashouts, contact the [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). *** ### 905\_5 - No acquirer account active and configured for Klarna In the context of this error code, acquirer account refers to your merchant account. **Cause**: You have not configured your merchant account to accept Klarna payments.\ **Solution**: [Add the payment method](/payment-methods/add-payment-methods) in your Customer Area. *** ### 905\_6 - Both 'KlarnaPayments' and 'Klarna' platforms have been configured for the merchant account. Only one of two is allowed **Cause**: You have configured both KlarnaPayments and Klarna as payment methods.\ **Solution**: Remove one of the Klarna payment methods. *** ### 906 - Invalid Request: Original pspReference is invalid for this environment **Cause**: * LIVE/TEST PSP mismatch. * Sending TEST PSP to LIVE endpoint. **Solution**: Pass the correct PSP or check environment you are testing in. *** ### 907 - Payment details are not supported for this country/ MCC combination **Cause**: * `paymentMethod` in Customer Area is missing or not configured for a specific country. * There are MCC restrictions. * Did not pass `className: TxScreening` (the transaction fails card number check on prepaid cards specifically). * There are restrictions on the issuer bank used for the payment, which is sanctioned by Adyen. **Solution**: Check `paymentMethod` configuration for logical errors. *** ### 908 - Invalid request **Cause**: * Using incorrect endpoint * Incorrect `requestData` is sent to incorrect endpoint **Solution**: Check what the goal of the request is and fix the `requestData`. Make sure that you are sending to the correct endpoint. *** ### 910 - Invalid Store **Cause**: The specified store does not match any of the store references or store IDs for the merchant account. **Solution**: Using API calls or your Customer Area, find the merchant account and the ID or reference of the store you want to use, and try again. *** ### 912 - The TX Variant does not support the redemption type *** ### 916 - The transaction amount exceeds the allowed limit for this type of card *** ### 918 - Required object 'card' is not provided *** ### 919 - The 'additionalAmount' currency should be the same currency as the payment *** ### 920 - Total payment amount should be equal or greater than zero *** ### 921\_1 - Object 'mpiData' is missing, required due to threeDReference *** ### 921\_2 - Object 'mpiData' is not valid. Reason: 'authenticationResponse' missing *** ### 921\_2 - Object 'mpiData' is not valid. Reason: 'directoryResponse' mismatch *** ### 922 - Account updater connection only supported for Visa & MasterCard *** ### 923 - No registered account for AccountUpdater *** ### 924 - Not allowed to change the shopperInteraction *** ### 926 - Invalid iDEAL issuer provided *** ### 927 - Missing payment details *** ### 928 - Invalid forex type specified *** ### 929 - Invalid base currency specified *** ### 930 - Invalid target currency specified *** ### 931 - There is no merchant with the code {0} *** ### 950 - Invalid AcquirerAccount *** ### 951 - Configuration Error (acquirerIdentification) *** ### 952 - Configuration Error (acquirerPassword) *** ### 953 - Configuration Error (apiKey) *** ### 954 - Configuration Error (redirectUrl) *** ### 955 - Configuration Error (AcquirerAccountData) *** ### 956 - Configuration Error (currencyCode) *** ### 957 - Configuration Error (terminalId) *** ### 958 - Configuration Error (serialNumber) *** ### 959 - Configuration Error (password) *** ### 960 - Configuration Error (projectId) *** ### 961 - Configuration Error (merchantCategoryCode) *** ### 962 - Configuration Error (merchantName) *** ### 963 - Invalid company registration number *** ### 964 - Invalid company name *** ### 965 - Missing company details *** ### 966 - Configuration Error (privateKeyAlias) *** ### 967 - Configuration Error (publicKeyAlias) *** ### 1000 - Card number cannot be specified for Incontrol virtual card requests *** ### 1001 - Recurring not allowed for Incontrol virtual card requests *** ### 1002 - Invalid Authorisation Type supplied *** ### 2000 - Bank account details do not meet instruction format **Cause**: * Not passing bank details required for Payout. * Using `selectedRecurringDetailReference` as LATEST which may or may not correspond to bank details. *** ### 29\_001 - Field '{0}' may not exceed {1} characters. **Cause**: * The value provided in the field exceeded the allowed number of characters. * The value is provided in the wrong field. For example, the field must be `PaReq` instead of `PaRes`. * For generated or encrypted values, something might have gone wrong in the generation process which caused the value to be too long. **Solution**: * Check the values that you are providing in the fields. * If you confirm that the fields and values are correct but the error persists, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). *** ### 29\_003 - Field 'fraudOffset' must be between -999 and 999 *** ### 29\_100 - The request is larger than the allowed maximum of {0} bytes **Cause**: * The request's body contained more bytes than the maximum allowed for that endpoint. ## Checkout error codes ### 14\_002 - paymentData has not been provided in the request *** ### 14\_003 - Invalid paymentData *** ### 14\_004 - Missing payment method details *** ### 14\_005 - Invalid payment method details **Cause**:\ One reason could be that the recurring contract on a token might be missing. For example, a payment method only supports creating a `RECURRING` contract, but you are trying to use a `ONECLICK` contract. *** ### 14\_006 - paymentMethod object has not been provided in the request *** ### 14\_007 - Invalid payment method data **Cause**:\ There is an error with information in the `paymentMethod` object. For example, the `paymentMethod.type` might be missing. *** ### 14\_008 - Session has expired *** ### 14\_010 - The request contains no sdkVersion although the channel is set to Web *** ### 14\_011 - The provided channel is conflicting the provided parameters **Solution**: Provide the correct `token` for iOS or Android, or `sdkVersion` for Web. Do not provide both `token` and `sdkVersion`. *** ### 14\_012 - The provided SDK token could not be parsed *** ### 14\_013 - For HTML Response; origin has to be provided *** ### 14\_014 - This end point requires the version to be specified *** ### 14\_015 - Token is missing *** ### 14\_016 - Invalid sdkVersion provided *** ### 14\_017 - The provided SDK Token has an invalid timestamp *** ### 14\_018 - Invalid payload provided *** ### 14\_019 - The request does not contain sdkVersion or token *** ### 14\_020 - No issuer selected *** ### 14\_022 - Missing uniqueTerminalId *** ### 14\_023 - Installments were not configured in setup request *** ### 14\_024 - Invalid open invoice request *** ### 14\_026 - The selected flow is invalid *** ### 14\_027 - The provided returnUrlQueryString is invalid *** ### 14\_028 - 3D Auth Data is incomplete **Solution**: Provide both `PaRes` and `MD` fields. *** ### 14\_029 - CVC is required for this payment but not provided *** ### 14\_030 - Return URL is missing *** ### 14\_031 - Bank account is missing *** ### 14\_032 - Provide either threeds2.fingerprint or threeds2.challengeResult *** ### 14\_033 - The provided fingerprint is invalid *** ### 14\_034 - The provided fingerprint is invalid. Field affected: **FIELD\_NAME** **Cause**: If the affected field is `threeDSCompIn`, the cause is that the device fingerprint is not forwarded to the `/payments/details` API call with the payment response.\ **Solution**: Check that you receive the device fingerprint data, and that you pass the data in the `/payments/details` API call. *** ### 14\_035 - 'origin' or 'notificationURL' must be provided *** ### 14\_036 - Missing required field 'channel' *** ### 14\_037 - Provided orderData is invalid *** ### 14\_0378 - Provided recurringExpiry format is invalid. Required format: yyyy-MM-dd'T'HH:mm:ssX, for example 2019-12-31T23:59:59+02:00 *** ### 14\_0379 - expiresAt is greater than the allowed date, max allowed: **VALUE** *** ### 14\_0380 - PaymentData and MD belong to different requests, please submit the correct MD *** ### 14\_0381 - Missing or invalid clientKey/originKey *** ### 14\_0382 - Missing or invalid checkoutAttemptId *** ### 14\_0383 - Missing or invalid shopperStage *** ### 14\_0384 - Missing or invalid details for provided shopperStage *** ### 14\_0385 - PaymentLink is expired *** ### 14\_0386 - Hosted Session is expired *** ### 14\_0387 - PaymentLink is already paid *** ### 14\_0388 - Field 'description' is too long *** ### 14\_0389 - Pos to PayByLink QR Code is expired *** ### 14\_0390 - Missing required field 'redirectResult' *** ### 14\_0391 - Invalid redirectResult provided When a shopper will be redirected for 3D Security authentication, provide a URL for where the shopper must be returned to after authentication is complete. **Cause**: * The format of the [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) value is incorrect for the applicable channel (web, iOS, or Android). **Solution**: * Make sure that the correct format for the applicable channel is used in the `returnUrl` parameter. *** ### 14\_0392 - Payment details are incomplete. Please provide both PaRes and MD. This error can only occur in the [authentication-only](/online-payments/3d-secure/standalone-authentication) flow. *** ### 14\_0393 - storingMethod.type **VALUE** is invalid *** ### 14\_0394 - Required field recurringProcessingModel is not provided **Cause**: * When creating a token to store payment details or when using stored payment details, [recurringProcessingModel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-recurringProcessingModel) is not provided. **Solution**: * Include the `recurringProcessingModel` parameter in the `/payments` request. *** ### 14\_0395 - Storing method is incomplete *** ### 14\_0396 - Push account receipt is invalid *** ### 14\_0397 - Order Data is expired *** ### 14\_0398 - Order Data Does Not Have Access To MerchantAccount *** ### 14\_0399 - Invalid field 'pushAccountData' *** ### 14\_0400 - The provisioning request was declined *** ### 14\_0401 - Authentication of a 3DS2 payment has failed *** ### 14\_0402 - Missing 3DS2 fingerprint *** ### 14\_0403 - Missing delegated authentication result *** ### 14\_0404 - Client data is not allowed to be passed during payment link creation. *** ### 14\_0405 - Donation token or Donation Original Psp Reference or Both are missing *** ### 14\_0406 - Parent PSP Ref missing for donation. *** ### 14\_0407 - Missing required field 'donationAccount' *** ### 14\_0408 - There are no payment methods available for the given parameters. *** ### 14\_0410 - Unable to generate a redirect url for the 3DS transaction. *** ### 14\_0411 - The gift card provided for the order has 0 balance. *** ### 14\_0412 - The field 'paymentMethod.type' is required for non-recurring payments. *** ### 14\_0413 - The 'paymentMethod.type' could not be retrieved from recurring details. *** ### 14\_0414 - The provided 3DS2 result is invalid. *** ### 14\_0415 - Missing required field 'threeDSResult' *** ### 14\_0416 - Unable to retrieve the total weight of a package. *** ### 14\_0417 - The carbon credit project id is not configured. *** ### 14\_0418 - Invalid response from the terminal or missing parameters *** ### 14\_0419 - Donation Token is expired. *** ### 14\_0420 - Both installmentOptions.values and installmentOptions.maxValue can't be specified in the request *** ### 14\_0421 - Invalid platform for Voucher Pass. *** ### 14\_0422 - The provided session identifier or data is invalid. *** ### 14\_0423 - The session has expired. *** ### 14\_0424 - A product has a negative quantity. *** ### 14\_0425 - Terminal with uniqueTerminalId '{0}' was not found *** ### 14\_0426 - Terminal with uniqueTerminalId '{0}' is not deployed *** ### 14\_0427 - Insufficient permissions for terminal with uniqueTerminalId '{0}' *** ### 14\_0428 - Merchant account is missing Pay by Link permission(s) *** ### 14\_0429 - Donations are not supported for this payment method. *** ### 14\_0430 - Provided merchant unknown *** ### 14\_0431 - Unknown terminal *** ### 14\_0432 - Unknown terminal *** ### 14\_0433 - A theme and terms of service must be configured to send emails to the shopper. *** ### 14\_0434 - An internal error occurred when sending the link to the shopper. *** ### 14\_0435 - The theme name is already in use. *** ### 14\_0436 - Field **FIELD\_NAME** is too long. *** ### 14\_0438 - A default theme must be configured for the account. *** ### 14\_0439 - This theme is default. Please select another default theme before deleting it. *** ### 14\_0444 - No terms and condtions were configured for this account. *** ### 14\_0445 - The specified theme does not exist. *** ### 14\_0446 - The file specified for the field **FIELD\_NAME** must be a valid JPG/JPEG image. *** ### 14\_0447 - no `bin` or `encryptedBin` provided. *** ### 14\_0448 - Provided paymentData and MD don't belong to the same payment. *** ### 14\_0449 - The field **FIELD\_NAME** is not supported when mode: **MODE**. *** ### 14\_0450 - The provided request cannot be processed as the session is in **STATE** state. *** ### 14\_0451 - Subset of options was not specified for field **FIELD\_NAME**. *** ### 14\_0452 - Subset of options was specified for field **FIELD\_NAME** but all options were selected. *** ### 14\_0453 - No options are expected when fillMode is empty for field **FIELD\_NAME**. *** ### 14\_0454 - Options mode was not specified for field **FIELD\_NAME**. *** ### 14\_0455 - The fill mode of the field **FIELD\_NAME** must be mandatory. *** ### 14\_0456 - Country **COUNTRY\_CODE** is invalid. *** ### 14\_0457 - Options mode for **FIELD\_NAME** should be subset. *** ### 14\_0458 - **FIELD\_NAME** with flexible validity should not contain quantity or unit. *** ### 14\_0459 - **FIELD\_NAME** with fixed validity should contain quantity and unit. *** ### 14\_0460 - The provided redirect data is invalid. *** ### 14\_0461 - The provided redirectId is invalid. *** ### 14\_0462 - The provided return query string is invalid. *** ### 14\_0463 - Invalid field 'recurringProcessingModel' *** ### 14\_0464 - The provided request cannot be processed as the sessionID in the returnURL is different from the current sessionID. *** ### 14\_0465 - Missing or invalid field 'sessionId' *** ### 14\_0466 - Invalid field 'sessionId' *** ### 14\_0467 - Missing or invalid field 'Forward-Url' *** ### 14\_0468 - Metadata value size exceeds limit *** ### 14\_0469 - Option not supported for new shopper field **FIELD\_NAME**. *** ### 14\_0470 - Invalid paymentMethodData. Contains both raw and encrypted card details. *** ### 14\_0471 - Field 'expireAfterRefusal' is not allowed. *** ### 14\_0472 - qrCodeExpiresAt is greater than the allowed date, max allowed: **VALUE** *** ### 14\_0473 - The details have expired. *** ### 14\_0474 - Klarna lineItems fields `taxAmount` and `amountExcludingTax` are missing or not valid *** ### 14\_0475 - shopperInteraction Moto not allowed due to PCI regulations **Error details in an API response** ```json { "status" : 403, "errorCode" : "14_0475", "message" : "shopperInteraction Moto not allowed due to PCI regulations.", "errorType" : "security", "pspReference" : "F7WCWRG6JPHR8HG2" } ``` **Cause**: * The [Mail Order/Telephone Order (MOTO)](/unified-commerce/mail-order-telephone-order) payment cannot be processed, because the PCI compliance of your MOTO integration has not been validated. **Solution**: * Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to validate your PCI compliance and enable your MOTO integration. *** ### 14\_0476 - `amount.value` cannot be less than the `amount.value` of the original request. *** ### 14\_0477 - User is not allowed to update the shipping address *** ### 14\_0478 - Sum of selected deliveryMethod amount and original offer amount does not match the total amount. *** ### 14\_0479 - Only 1 deliveryMethod should be selected. *** ### 14\_0480 - Order can only be updated if payment is still pending. *** ### 14\_0481 - The value 'amount.currency' provided in the request does not match the `amount.currency` of the original request. *** ### 14\_0482 - Invalid parameter 'returnUrl' *** ### 14\_0483 - Invalid field 'sessionResult' *** ### 14\_0484 - Missing required field 'UPI ID / VPA' *** ### 14\_0485 - Missing exchange rate token *** ### 14\_0486 - Invalid exchange rate token *** ### 14\_0487 - Exchange rate has expired *** ### 14\_0488 - Missing required field 'shopperTaxInfo.taxId' *** ### 14\_0489 - Invalid field 'shopperTaxInfo.taxId' *** ### 14\_0490 - Transaction amount exceeds the maximum allowed amount *** ### 14\_0491 - Conflicting data found on request fields and sdkData field *** ### 14\_0492 - Invalid tax-id type for the merchant *** ### 14\_0493 - Invalid field 'paymentMethod'. UPI Collect transactions using Android are no longer supported. Please use UPI Intent or UPI QR instead. *** ### 14\_0494 - The encrypted card details in 'paymentMethod' are invalid. ## 3DS2 error codes ### 15\_002 - Required field **FIELD\_NAME** missing for device channel **DEVICE\_CHANNEL\_NAME** *** ### 15\_003 - Field **FIELD\_NAME** should not be present for device channel **DEVICE\_CHANNEL\_NAME** *** ### 15\_004 - Invalid value in field **FIELD\_NAME** *** ### 15\_005 - Unexpected field **FIELD\_NAME** *** ### 15\_006 - messageCategory shall be present *** ### 15\_007 - Value of **FIELD\_NAME** is too long (**VALUE** > **MAX\_ALLOWED\_VALUE**) *** ### 15\_008 - Invalid merchant configuration for 3DS 2.0 *** ### 15\_009 - threeDS2Token is required *** ### 15\_010 - Invalid deviceChannel value. Must be 'app', 'browser' or 'TRI'. *** ### 15\_011 - pspReference is not a valid pspReference *** ### 15\_012 - Result not present *** ### 15\_013 - Cannot add 3DS2 authentication values because addRawThreeDSecureDetailsResult is not enabled *** ### 15\_014 - Invalid threeDS2Token *** ### 15\_015 - Invalid browserInfo provided *** ### 15\_016 - Language must be a valid tag according to IETF BCP47 definition *** ### 15\_017 - Cannot perform an authorisation on a 3DS2 transaction more than 12 hours after the transaction began *** ### 15\_018 - colorDepth must be 1, 4, 8, 15, 16, 24, 32 or 48 bit *** ### 15\_019 - stateOrProvince invalid *** ### 15\_020 - invalid transStatus **Cause**: Check the `requestData`. It is likely that the `transStatus` is **Null**.\ **Solution**: Check what is being passed in the request, and check with the issuer. The `transStatus` is defined by the issuer. *** ### 15\_021 - notificationURL cannot be localhost **Cause**: You are most likely using a custom browser implementation, and trying to test your implementation on your localhost.\ **Solution**: Deploy a public notification server if you are testing or using a browser-based 3D Secure flow. *** ### 15\_022 - invalid authenticationOnly field *** ### 15\_023 - threeDS2RequestData is not supported for threeDS2InMDFlow **Cause**: You are most likely using a deprecated flow: you are sending in the `threeDS2RequestData` object inside the payments request, and at the same time you request the `threeDS2InMDFlow` in the `additionalData` or via your account data settings.\ **Solution**: Either remove the `threeDS2RequestData` object from the `/payments` request, or use the native flow. Do not rely on the redirect flow. *** ### 15\_024 - Result not present - Authentication older than 60 days *** ### 15\_026 - Error during 3DS authentication process There are two possible causes for this error: * **Cause**: When [redirecting a shopper](/online-payments/classic-integrations/classic-api-integration/3d-secure-authentication/3d-secure-1/#step-2-redirect-to-the-card-issuer) to the card issuer for 3DS verification, an incorrect value is contained in the redirect form's hidden field `paReq`.\ **Solution**: Make sure that the redirect form's hidden input field `paReq` contains the correct `paRequest` value that you get from the [/authorise](https://docs.adyen.com/api-explorer/Payment/latest/post/authorise) response. * **Cause**: Incorrect value contained in the `paResponse` parameter of the [authorise3d](https://docs.adyen.com/api-explorer/Payment/latest/post/authorise3d) request.\ **Solution**: When the card issuer redirects the shopper back to the merchant's website, the HTTP call contains `paRes` data that you must pass in the `paResponse` parameter of the `/authorise3d` request. ## Amazon Pay error codes ### 5\_601 - Unknown error for Amazon Pay **Cause**: Amazon responded with errorMessage: Null. *** ### 5\_602 - Amazon Pay token doesn't exist for Amazon Pay **Cause**: The `amazonPayToken` is missing. *** ### 5\_603 - Amazon Pay signature corrupt *** ### 5\_604 - Invalid Amazon Pay value supplied: **VALUE** *** ### 5\_605 - Could not find Merchant Private Key **Cause**: The Encryption Key hasn't been set up on the web service user for your merchant account. *** ### 5\_606 - Amazon Pay token is not chargeable **Cause**: The `amazonPayToken` is not correct. *** ### 5\_607 - Invalid account *** ### 5\_608 - Invalid refund status *** ### 5\_609 - Missing header fields *** ### 5\_610 - Amazon Pay is not available *** ### 5\_611 - Rejected by Amazon *** ### 5\_612 - Amazon Pay internal error *** ### 5\_613 - Amazon Pay timeout *** ### 5\_614 - Amazon Pay sent invalid response *** ### 5\_615 - Authentication Notification to Amazon Pay failed ## Apple Pay error codes ### 5\_001 - Apple Pay token amount-mismatch **Cause**: The amount that you have configured in the Drop-in for the Apple Pay component is different from the final amount that you are sending in the `/payments` request.\ **Solution**: Make sure that the amount in the front-end mirrors the amount you send in the `/payments` request. Check that you are sending the correct [currency code and minor units](/development-resources/currency-codes#page-introduction) for that specific currency. *** ### 5\_002 - Invalid Apple Pay token **Cause**: Your web service user and/or merchant account set up is incorrect. *** ### 5\_003 - Incorrect Apple Pay token version **Cause**: There is an Apple Pay version mismatch. You may have to regenerate your token and set up your web service user again. *** ### 5\_004 - Could not find Merchant Private Key **Cause**: The CSR is not valid, you most likely provided a different certificate compared to the certificate that is registered on the Apple Pay developer portal.\ **Solution**: Do the PEM certificate exchange flow again, and provide the same certificate. *** ### 5\_005 - Could not find Merchant Public Key **Cause**: The CSR is not valid, you most likely provided a different certificate compared to the certificate that is registered on the Apple Pay developer portal.\ **Solution**: Do the PEM certificate exchange flow again, and provide the same certificate. *** ### 5\_006 - Apple Pay signature corrupt **Cause**: There is a signature mismatch, the signature cannot be read. *** ### 5\_007 - Missing certificate for Apple Pay signature **Cause**: The signature is empty, there is no certificate or the certificate is missing.\ **Solution**: Set up the web service user again, and configure the Apple Pay token. *** ### 5\_008 - Our Test system does not accept Live tokens ## Google Pay error codes ### 5\_202 - Invalid Google Pay token **Cause**: * You are not passing the correct token, or there is an incorrect merchant account in the request data. * Incorrect payment method MID setup. * Android App not registered with Google in case of Android integration. **Solution**: Make sure that you are sending in the correct token. Do not escape the stringified JSON; send it as it is. *** ### 5\_208 - Google Pay token already expired **Cause**: The token expired. Troubleshoot with Google, as the error is mapped directly with the Google response. *** ### 5\_210 - Google Pay token already used **Cause**: The data in the token that you sent has been used before and cannot be reused.\ **Solution**: Make sure that you use a new Google Pay token for each shopper initiated transaction. ## Network token error codes ### 26\_002 - The network token is suspended/deactivated *** ### 26\_003 - The detokenization request has been declined **Cause**: Adyen's request to the scheme to fetch the cryptogram for the network token was declined. *** ### 26\_004 - The network token PAN is missing **Cause**: No [Primary Account Number (PAN)](/get-started-with-adyen/adyen-glossary#card-number-pan) was found for the network token. *** ### 26\_005 - The network token is not active yet *** ### 26\_006 - The network token is not found **Cause**: No network token was found to complete the payment. This might be caused, for example, because the network token was deleted. *** ### 26\_007 - The detokenization request timed out **Cause**: Adyen's request to the scheme to fetch the cryptogram for the network token timed out. *** ### 26\_008 - **PARAMETER\_NAME** **Cause**: One or more of the required fields for the request is missing. The missing fields are returned in the error message.\ **Solution**: Add the missing fields to your request and try again. *** ### 26\_010 - Unsupported variant for network tokenization: **VALUE** *** ### 6\_012 - The tokenization request timed out *** ### 26\_017 - Operation **ACTION** is not allowed for network token **Cause**: The attempted action is not allowed for this network token. **ACTION** can be **Delete**, **Suspend**, or **Resume**. *** ### 26\_020 - The detokenization request failed **Cause**: Adyen's request to the scheme to fetch the cryptogram for the network token failed. ## See also * [HTTP status codes](/development-resources/response-handling/) --- # Source: https://docs.adyen.com/development-resources/libraries.md Section: Development resources Title: Libraries --- title: "Libraries" url: "https://docs.adyen.com/development-resources/libraries" source_url: "https://docs.adyen.com/development-resources/libraries.md" canonical: "https://docs.adyen.com/development-resources/libraries" last_modified: "2023-05-19T09:58:00+02:00" language: "en" --- # Libraries [View source](/development-resources/libraries.md) We provide server-side API libraries in several languages. Libraries are connected to managed package systems (Composer, Gradle, Maven, npm, NuGet, PyPi, RubyGems), which make them easy to include in your project. ## How it works Installing a library is not required, but will save you development time, because a library: * Uses an API version that is up to date. * Has generated models to help you construct requests. For a point-of-sale integration with Terminal API, the libraries are wrappers around Terminal API. They include the models to create Terminal API requests. * If your Terminal API integration uses cloud communications, you can use the C#, Go, Java, Node, PHP, or Ruby libraries. * If your Terminal API integration uses local communications, you can use the C#, Java, or Node libraries. These also take care of [protecting local communications](/point-of-sale/design-your-integration/choose-your-architecture/local#protect-communications). * Sends the request to Adyen using its built-in HTTP client, so you do not have to create your own. For your library of choice: 1. Make sure to comply with the requirements. 2. Install the library. 3. Make a test payment request, as described [below](#libraries). ## Available libraries ### Tab: Java ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-java-spring-online-payments#checkout-example).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-java-spring-online-payments). #### Requirements * Java 11 or later. #### Installation You can use [Maven](https://maven.apache.org), adding this dependency to your project's POM. **Add the API library** ```xml com.adyen adyen-java-api-library LATEST_VERSION ``` You can find the latest version on GitHub. Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-java-api-library/releases). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```java // Import the required classes import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.service.checkout.PaymentsApi; import com.adyen.model.checkout.*; // Setup the client and service. Client client = new Client("ADYEN_API_KEY", Environment.TEST); PaymentsApi paymentsApi = new PaymentsApi(client); // Create a payment request. PaymentRequest paymentRequest = new PaymentRequest(); paymentRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); CardDetails cardDetails = new CardDetails(); cardDetails.encryptedCardNumber("test_4111111111111111") .encryptedSecurityCode("test_737") .encryptedExpiryMonth("test_03") .encryptedExpiryYear("test_2030"); paymentRequest.setPaymentMethod(new CheckoutPaymentMethod(cardDetails)); Amount amount = new Amount().currency("EUR").value(1000L); paymentRequest.setAmount(amount); paymentRequest.setReference("My first Adyen test payment with an API library/SDK"); paymentRequest.setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy.."); // Add your idempotency key. RequestOptions requestOptions = new RequestOptions(); requestOptions.setIdempotencyKey("YOUR_IDEMPOTENCY_KEY"); // Make a request to the /payments endpoint. PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest, requestOptions); ``` ### Tab: PHP ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-php-online-payments#run-this-integration-in-seconds-using-gitpod).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-php-online-payments). #### Requirements * PHP 7.3 or later. * cURL with SSL support. * The JSON PHP extension. * The list of dependencies from the composer require list. #### Installation You can use [Composer](https://getcomposer.org/). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed. **Install the API library** ```bash composer require adyen/php-api-library ``` In your PHP script, make sure you include the autoloader: **Include the autoloader** ```php require __DIR__ . '/vendor/autoload.php'; ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-php-api-library/releases). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```php // Set up the client and service. $client = new \Adyen\Client(); $client->setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(\Adyen\Environment::TEST); $client->setTimeout(30); $service = new \Adyen\Service\Checkout\PaymentsApi($client); $requestOptions['idempotencyKey'] = "YOUR_IDEMPOTENCY_KEY"; // Create a PaymentMethod object. $paymentMethod = new CheckoutPaymentMethod(); $paymentMethod ->setType("scheme") ->setEncryptedCardNumber("test_4111111111111111") ->setEncryptedExpiryMonth("test_03") ->setEncryptedExpiryYear("test_2030") ->setEncryptedSecurityCode("test_737"); // Create an Amount object. $amount = new Amount(); $amount ->setValue(1500) ->setCurrency("EUR"); // Create the PaymentRequest object. $paymentRequest = new PaymentRequest(); $paymentRequest ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setPaymentMethod($paymentMethod) ->setAmount($amount) ->setReference("My first Adyen test payment with an API library/SDK") ->setReturnUrl("https://your-company.example.com/..."); // Make a /payments request. $result = $service->payments($paymentRequest, $requestOptions); ``` ### Tab: C\# #### Requirements * .NET standard 2.0 or later. * For Terminal API certificate validation, set the application to either of the following: * .NET core 2.1 or later * .NET framework 4.6.1 or later #### Installation You can use [NuGet](https://www.nuget.org/packages/Adyen/): **Install the API library** ```bash PM> Install-Package Adyen -Version LATEST_VERSION ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-dotnet-api-library). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```cs using Adyen; using Adyen.Model.Checkout; using Adyen.Service; using Environment = Adyen.Model.Environment; // Create a paymentRequest object. var amount = new Amount("USD", 1000); var paymentRequest = new PaymentRequest { Reference = "My first Adyen test payment with an API library/SDK", Amount = amount, ReturnUrl = @"https://your-company.example.com/...", MerchantAccount = "YOUR_MERCHANT_ACCOUNT", }; // Set up the client and service. var config = new Config { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); var checkout = new PaymentsService(client); // Add your idempotency key. var requestOptions = new RequestOptions { IdempotencyKey= "YOUR_IDEMPOTENCY_KEY" }; // Make a /payments request. var paymentResponse = checkout.Payments(paymentRequest, requestOptions); ``` ### Tab: NodeJS ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-node-online-payments#checkout-example).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-node-online-payments). #### Requirements * Node.js version 18 or later. #### Installation You can use [npm](https://www.npmjs.com/): **Install the API library** ```bash npm install --save @adyen/api-library npm update @adyen/api-library ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-node-api-library/releases). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```js // Step 1: Require the parts of the module you want to use. const { Client, CheckoutAPI} = require('@adyen/api-library'); // Step 2: Initialize the client object. const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"}); // Step 3: Initialize the API object. const checkoutApi = new CheckoutAPI(client); // Step 4: Create the request object. const paymentRequest = { amount: { currency: "USD", value: 1000 // value in minor units }, reference: "My first Adyen test payment with an API library/SDK", paymentMethod: { type: "scheme", encryptedCardNumber: "test_4111111111111111", encryptedExpiryMonth: "test_03", encryptedExpiryYear: "test_2030", encryptedSecurityCode: "test_737" }, shopperReference: "YOUR_SHOPPER_REFERENCE", storePaymentMethod: true, shopperInteraction: "Ecommerce", recurringProcessingModel: "CardOnFile", returnUrl: "https://your-company.example.com/...", merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Optional: Add your idempotency key. const requestOptions = { idempotencyKey: "YOUR_IDEMPOTENCY_KEY" }; // Step 5: Make a /payments request. checkoutApi.PaymentsApi.payments(paymentRequest, requestOptions) .then(paymentResponse => console.log(paymentResponse.pspReference)) .catch(error => console.log(error)); ``` ### Tab: Go ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-golang-online-payments#run-this-integration-in-seconds-using-gitpod).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-golang-online-payments). #### Requirements * Go 1.13 or later. #### Installation You can use [Go modules](https://github.com/golang/go/wiki/Modules): **Install the API library** ```shell go get github.com/adyen/adyen-go-api-library/v7 ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-go-api-library). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```go import ( "context" "fmt" "github.com/adyen/adyen-go-api-library/v7/src/checkout" "github.com/adyen/adyen-go-api-library/v7/src/common" "github.com/adyen/adyen-go-api-library/v7/src/adyen" ) // Create a payment object. func ExamplePaymentWithIdempotencyKey() { client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, Debug: true, }) service := client.Checkout() card := checkout.NewCardDetails() card.SetEncryptedCardNumber("test_4111111111111111") card.SetEncryptedExpiryMonth("test_03") card.SetEncryptedExpiryYear("test_2030") card.SetEncryptedSecurityCode("test_737") // Create a payment request. req := service.PaymentsApi.PaymentsInput().PaymentRequest(checkout.PaymentRequest{ Amount: *checkout.NewAmount("EUR", int64(1000)), MerchantAccount: "YOUR_MERCHANT_ACCOUNT", PaymentMethod: checkout.CardDetailsAsCheckoutPaymentMethod(card), Reference: "My first Adyen test payment with an API library/SDK", ReturnUrl: "https://your-company.example.com/...", }) // Add your idempotency key. req = req.IdempotencyKey("YOUR_IDEMPOTENCY_KEY") res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req) fmt.Println(res, httpRes, err) } ``` ### Tab: Python ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-python-online-payments#run-this-integration-in-seconds-using-gitpod).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-python-online-payments). #### Requirements * Python 3.6 or later. * (Optional) Packages: Requests or PycURL #### Installation You can use [pip](https://pip.pypa.io/en/stable/): **Install the API library** ```py pip install Adyen ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-python-api-library). #### Using the library Set up the client as a singleton resource that you use for the API requests to Adyen and make a test payment request. For example, to make a test credit card payment for **10** EUR (**1000** in minor units): **Make a test payment request using the API library** ```py import Adyen adyen = Adyen.Adyen() adyen.payment.client.xapikey = "ADYEN_API_KEY" adyen.payment.client.platform = "test" # Change the value to live for the live environment. request = { "amount": { "currency": "USD", "value": 1000 # Value in minor units. }, "reference": "My first Adyen test payment with an API library/SDK", "paymentMethod": { "type": "visa", "encryptedCardNumber": "test_4111111111111111", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737" }, "shopperReference": "YOUR_SHOPPER_REFERENCE", "returnUrl": "https://your-company.example.com/...", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" } result = adyen.checkout.payments_api.payments(request, idempotency_key="YOUR_IDEMPOTENCY_KEY") ``` ### Tab: Ruby ##### Try our example integration ![](/user/pages/reuse/development-resources/api-libraries/gitpod-icon.png)  [Run it in Gitpod](https://github.com/adyen-examples/adyen-rails-online-payments#run-this-integration-in-seconds-using-gitpod).\ ![](/user/pages/reuse/development-resources/api-libraries/github-icon.png)  [Clone the repository](https://github.com/adyen-examples/adyen-rails-online-payments). #### Requirements * Ruby 2.7 or later. #### Installation You can use [RubyGems](https://rubygems.org/): **Install the API library** ```bash gem install adyen-ruby-api-library ``` Alternatively, you can download the [release on GitHub](https://github.com/Adyen/adyen-ruby-api-library/releases). Run `bundle install` to install dependencies. #### Using the library Set up the client as a singleton resource that you use for the API requests: **Set up the API library client** ```ruby require 'adyen-ruby-api-library' adyen = Adyen::Client.new adyen.api_key = "ADYEN_API_KEY" headers = {"idempotency-key": "YOUR_IDEMPOTENCY_KEY"} response = adyen.checkout.payments_api.payments({ :amount => { :currency => "EUR", :value => 1000 }, :reference => "My first Adyen test payment with an API library/SDK", :paymentMethod => { :type => "scheme", :encryptedCardNumber => "test_4111111111111111", :encryptedExpiryMonth => "test_03", :encryptedExpiryYear => "test_2030", :encryptedSecurityCode => "test_737" }, :returnUrl => "https://your-company.example.com/checkout/", :merchantAccount => "YOUR_MERCHANT_ACCOUNT" }) ``` ## Next steps [Integrate with API](/online-payments/build-your-integration) [Read our comprehensive guide to accept payments with APIs.](/online-payments/build-your-integration) [Add payment methods](/payment-methods) [Learn about payment methods and how to integrate them.](/payment-methods) [Set up webhooks](/development-resources/webhooks) [Receive confirmation when a payment is authorised or fails.](/development-resources/webhooks) [Payment modifications](/online-payments/modify-payments) [Find out how to cancel, refund, or capture a payment using our API.](/online-payments/modify-payments) --- # Source: https://docs.adyen.com/development-resources/live-endpoints.md Section: Development resources Title: Live endpoints Description: Learn about the structure of live endpoints and additional recommendations for using live endpoints. --- title: "Live endpoints" description: "Learn about the structure of live endpoints and additional recommendations for using live endpoints." url: "https://docs.adyen.com/development-resources/live-endpoints" source_url: "https://docs.adyen.com/development-resources/live-endpoints.md" canonical: "https://docs.adyen.com/development-resources/live-endpoints" last_modified: "2024-01-18T13:03:00+01:00" language: "en" --- # Live endpoints Learn about the structure of live endpoints and additional recommendations for using live endpoints. [View source](/development-resources/live-endpoints.md) To communicate with our API, you submit HTTP requests to applicable endpoints. These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the Adyen payments platform. You can [view your live endpoints](#view-your-live-endpoints) in your Customer Area. When using our [libraries](/development-resources/libraries) or [plugins](/plugins), you also need to pass a [prefix for the live URL](#live-url-prefix). On this page, you can also read about our recommended [Maximum Transmission Unit](#maximum-transmission-unit) setting, and [connection keepalive](#connection-keepalive). ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online payments](/online-payments/) integration. | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the roles that are required for the API(s) you are using from the [roles for payments integrations](/development-resources/api-credentials/roles/#roles-for-payments). | | **Setup steps** | Before you begin:- Apply and get your [live account](/get-started-with-adyen/). - [Generate an API key](/development-resources/api-credentials/#generate-api-key) for the live environment. - Refer to the [go-live checklist](/online-payments/go-live-checklist/) to get an overview of the steps required when taking your integration live. | ## View your live endpoints Live endpoints are set up automatically. To view your live endpoints in your [live Customer Area](https://ca-live.adyen.com/), go to **Developers** > **API URLs**. On the **API URLs and Response** page, you can see the configured data centres and prefixes for your company account. ### Location-based live endpoints If you need to connect to a certain data center of the Adyen payments platform (for example, US or AU data centers), you can set up location-based live endpoints. To use location-based live endpoints, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). If you use a location-based live endpoint, and use our Drop-in/Components integrations: * For web integrations, if you embed the script and stylesheet to load the client-side resources, make sure to use the [region-specific URL](/online-payments/web-best-practices#embed-script-and-stylesheet) that matches the region of your live endpoint. * When you go live, set the `environment` for your Drop-in/Component to match your live endpoint region. Find the `environment` values for each platform in our [Sessions](/online-payments/build-your-integration/sessions-flow) and [Advanced](/online-payments/build-your-integration/advanced-flow) flow integration guides. ## Pass the URL prefix The live URL prefix is a string composed of a hex-encoded random part and your company name. When using our [libraries](/development-resources/libraries) or [plugins](/plugins) for live transactions, you need to pass the prefix for the live URL. To get your URL prefix, in your [live Customer Area](https://ca-live.adyen.com/), go to **Developers** > **API URLs** > **Prefix**. For example, if this is your prefix for your live URL: **1797a841fbb37ca7-AdyenDemo** Then your live URL for the `/payments` endpoint on Checkout API v69 is: https\://**1797a841fbb37ca7-AdyenDemo**-checkout-live.adyenpayments.com/checkout/v72/payments ## Live endpoints structure The tables below show the structure of test and live endpoints for the [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) and [Classic Payments API](https://docs.adyen.com/api-explorer/Payment/latest/overview). ### Checkout API endpoints | | | | ---- | ------------------------------------------------------------------------------------------------ | | Test | https\://checkout-**test**.adyen.com/**\[version]**/**\[method]** | | Live | https\://**\[prefix]**-checkout-**live**.adyenpayments.com/checkout/**\[version]**/**\[method]** | ### Classic Payments API endpoints | | | | ---- | ------------------------------------------------------------------------------------------------------ | | Test | https\://pal-**test**.adyen.com/pal/servlet/Payment/**\[version]**/**\[method]** | | Live | https\://**\[prefix]**-pal-**live**.adyenpayments.com/pal/servlet/Payment/**\[version]**/**\[method]** | In the live endpoint examples: * `[version]`: The version number, always starting with "v", for example, **v52**. To learn more about API versioning for classic and new APIs, see [Versioning](/development-resources/versioning). * `[method]`: The endpoint name, for example, **payments**, or **sessions**. * `[prefix]`: The [live ULR prefix](#live-url-prefix) from your Customer Area. Each [company account](/account/account-structure/#company-account) is provided with a unique hostname to communicate with Adyen's APIs. By connecting to this merchant-specific hostname, Adyen has more control over the routing of transactions. This allows Adyen to improve service robustness and availability for our merchants. By default, all transactions for a merchant-specific endpoint are routed to the same infrastructure as the standard endpoint, however in case of an infrastructure problem on the standard endpoint, especially if the cause is outside of Adyen's scope of control, alternative routing can be enabled to backup infrastructure and new infrastructure can be provisioned on demand. ## Maximum Transmission Unit We strongly recommend setting the [Maximum Transmission Unit (MTU)](https://en.wikipedia.org/wiki/Maximum_transmission_unit) to 1500 bytes on the network interfaces connecting to Adyen endpoints. The MTU defines the maximum permissible size of the packets passing through the interface. As most of the public internet assumes a maximum packet size of 1500 bytes, configuring the MTU to larger values can lead to connectivity and stability issues. ## Connection keepalive You can keep your connections to Adyen endpoints open for longer so you can continue to send or receive data as part of the same TCP session.\ You can do this in your client-side software by enabling TCP keepalive and HTTP keepalive for HTTP connections. Make sure to enable both TCP keepalive and HTTP keepalive for HTTP connections to avoid connection errors. ### Timeouts Adyen endpoints have a 60-second time-out for inactive HTTP connections with keepalive enabled. If no new data is transmitted within 60 seconds of the TCP session, we initiate closing the TCP connection. To prevent connection issues, we recommend you set the client-side HTTP keepalive timeout to be shorter than 60 seconds, for example between 30 and 50 seconds. ## See also * [Referrals API reference](/risk-management/automate-submitting-referrals/referrals-api-reference/) * [Test cards API](/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api/) * [Terminal API endpoints](/point-of-sale/design-your-integration/terminal-api#endpoints) * [Go live with Adyen for Platforms](/platforms/integration-checklist/#go-live) --- # Source: https://docs.adyen.com/development-resources/logs-resources.md Section: Development resources Title: Logs --- title: "Logs" url: "https://docs.adyen.com/development-resources/logs-resources" source_url: "https://docs.adyen.com/development-resources/logs-resources.md" canonical: "https://docs.adyen.com/development-resources/logs-resources" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Logs [View source](/development-resources/logs-resources.md) Use our [Webhook event logs](/development-resources/logs-resources/webhook-event-logs) and [API logs](/development-resources/logs-resources/api-logs) to test and troubleshoot API requests and webhook events. --- # Source: https://docs.adyen.com/development-resources/logs-resources/api-logs.md Section: Development resources Title: API logs Description: Learn how to use API logs to analyze or debug API requests. --- title: "API logs" description: "Learn how to use API logs to analyze or debug API requests." url: "https://docs.adyen.com/development-resources/logs-resources/api-logs" source_url: "https://docs.adyen.com/development-resources/logs-resources/api-logs.md" canonical: "https://docs.adyen.com/development-resources/logs-resources/api-logs" last_modified: "2023-04-13T13:37:00+02:00" language: "en" --- # API logs Learn how to use API logs to analyze or debug API requests. [View source](/development-resources/logs-resources/api-logs.md) When you are integrating with Adyen, you may want to analyze or debug API requests, for example for test payments. Using API logs, you can see information about your API requests in the Customer Area. You can troubleshoot the requests and responses, and see the metadata of your API requests. The logs show all API requests made in your test or live environment in the past thirty days. Requests older than thirty days are removed from the API logs. ## Using API logs API logs only support API requests that use JSON. To view API logs, you must have one of these [user roles](/account/user-roles): * Merchant admin * Technical integrator To view and search API logs: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). Stay on the company account or select a merchant account. API logs for APIs used in a balance platform integration are available on the company account. 2. Select **Developers > API logs**. This will show a list of every API request made in the past thirty days. 3. Select an item to see the details of that API request. You will see the timestamp, which API was called, the PSP reference or resource ID, and full details of the request and response. Type a PSP reference or request ID into the search bar, or use the various filter options to search by date, API, endpoint, or HTTP method. ## Example You can use API logs in end-to-end testing, to see details of the requests you have made to our APIs. If you are testing the checkout flow for your online payments setup and a payment fails, you can check the API logs to see details of what you sent to the API and why the payment failed. You can compare failed API requests with successful ones. Go to the API logs page. In the **PSP reference** column, select the payment reference to see details of the API request. * Under **Response status** at the top right of the page you will see the [error code](/development-resources/error-codes). * In the **Request body** section, you see the details of the request, including which endpoint the request was sent to. * In the **Response body** section, you can see details of the response. For example, when you see error code 422, the API request contained input that was not valid. The response body shows which field had the invalid input. You can then check on your side what input was sent and make changes. ## See also * [Test authorisation result codes](/development-resources/testing/result-codes) * [Error codes and messages](/development-resources/error-codes) * [Response handling](/development-resources/response-handling) --- # Source: https://docs.adyen.com/development-resources/logs-resources/webhook-event-logs.md Section: Development resources Title: Webhook event logs Description: Learn how to use webhook event logs in the test environment --- title: "Webhook event logs" description: "Learn how to use webhook event logs in the test environment" url: "https://docs.adyen.com/development-resources/logs-resources/webhook-event-logs" source_url: "https://docs.adyen.com/development-resources/logs-resources/webhook-event-logs.md" canonical: "https://docs.adyen.com/development-resources/logs-resources/webhook-event-logs" last_modified: "2023-04-12T11:17:00+02:00" language: "en" --- # Webhook event logs Learn how to use webhook event logs in the test environment [View source](/development-resources/logs-resources/webhook-event-logs.md) In your Customer Area, you can find a log of all [webhook events](/development-resources/webhooks) sent to your server. For every webhook event, we list: * Relevant timestamps and your response time. * The event code and identifier. * The relevant PSP reference or resource ID. * Request and response bodies. You can use the log for testing and [troubleshooting](/development-resources/webhooks/troubleshoot) your webhook integration. ## Viewing your webhook event log To view your webhook event log, you must have one of these [user roles](/account/user-roles): * Merchant admin * Merchant technical integrator To view and search webhook event logs: 1. Log in to your test [Customer Area](https://ca-test.adyen.com/). Stay on the company account or select a merchant account. Webhook event logs for a balance platform integration are available on the company account. 2. Go to **Developers > Event logs**. You will see a list of all your webhook events on the test environment in the past thirty days. 3. Select an item to see its details. You will see the timestamp, your webhook endpoint URL, the PSP reference or resource ID, and full details of the request and response. Additionally, you can: * Search for a specific webhook event, for example based on its PSP reference, resource ID, or your order reference. * Filter webhook events, for example based on their webhook endpoint URL, status or date. ## See also * [Webhooks](/development-resources/webhooks) * [Understand notifications](/development-resources/webhooks/understand-notifications) * [API Logs](/development-resources/logs-resources/api-logs) --- # Source: https://docs.adyen.com/development-resources/mcp-server.md Section: Development resources Title: Adyen Model Context Protocol (MCP) server Description: Integrate with our APIs using LLMs with our MCP server. --- title: "Adyen Model Context Protocol (MCP) server" description: "Integrate with our APIs using LLMs with our MCP server." url: "https://docs.adyen.com/development-resources/mcp-server" source_url: "https://docs.adyen.com/development-resources/mcp-server.md" canonical: "https://docs.adyen.com/development-resources/mcp-server" last_modified: "2025-06-11T14:59:00+02:00" language: "en" --- # Adyen Model Context Protocol (MCP) server Integrate with our APIs using LLMs with our MCP server. [View source](/development-resources/mcp-server.md) ##### Learn more Read more about the launch of our MCP server in our [tech blog](https://www.adyen.com/knowledge-hub/mcp-release). [Our Model Context Protocol (MCP) server](https://github.com/Adyen/adyen-mcp) lets you use natural language with your chosen Large Language Model (LLM) client. This allows developers to use natural language to connect with Adyen's platform more easily and build new payment solutions faster. ## How it works Use our MCP server to integrate with our APIs through function calling. This lets you integrate and interact with Adyen APIs seamlessly. The MCP contains a set of tools that lets you interact with the Adyen APIs for common use cases, using your client of choice. Currently, interactions with the following APIs are supported, we are working on adding more APIs and endpoints. * [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) * [Management API](https://docs.adyen.com/api-explorer/Management/latest/overview) For a full overview of supported endpoints, see the list on [GitHub](https://github.com/Adyen/adyen-mcp/tree/main?tab=readme-ov-file#adyen-mcp-server---alpha). To get started: 1. [Get your API credentials](#get-api-credentials) to authenticate the API requests you will make with our MCP server. 2. [Run the MCP server](#run). 3. [Use our MCP](#use) with an LLM client to interact with our APIs using natural language. ## Get your API credentials To authenticate the requests you will make using the MCP, [generate an API key](/development-resources/api-credentials#generate-api-key). You will need your API key when [running the MCP server](#run). Make sure that your API credential has the following [roles](/development-resources/api-credentials/roles), these roles are assigned to all web service users by default: * Merchant PAL webservice role * Checkout webservice role * Management API—Payment methods read * Management API—Account read * Management API - Terminals read * Management API — Assign Terminal * Management API — Terminal actions read * Management API — Terminal actions read and write * Management API — Android files read * Management API — Terminal settings read * Management API — Terminal settings read and write ## Run the MCP server Run our MCP server locally to start interacting with our APIs using natural language. You need your API key to run the server, and authenticate API requests. ### Test environment You must have the following to run the MCP server for the test environment: * Your [Adyen API key](/development-resources/api-credentials/). Run the following command: ```text npx -y @adyen/mcp --adyenApiKey=ADYEN_API_KEY --env=TEST ``` ### Live environment You must have the following to run the MCP server for the live environment: * Your [Adyen API key](/development-resources/api-credentials/). * Your [Adyen live URL prefix](/development-resources/live-endpoints/#live-url-prefix) from your [live Customer Area](https://ca-live.adyen.com/) under **Developers** > **API URLs** > **Prefix**. Run the following command: ```text npx -y @adyen/mcp --adyenApiKey=ADYEN_API_KEY --env=LIVE --livePrefix=YOUR_PREFIX_URL ``` ## Use the MCP server After you start running the MCP server locally, use an LLM client of your choice to interact with our APIs using natural language. Interactions with our MCP server consist of the following: * **Your prompt**: You provide instructions to your LLM client using natural language. For example, "Refund order #12345" or "Create a €50 payment link for order #ABC789." * **LLM client**: Your LLM client sends these instructions to the Adyen MCP server. * **The MCP server**: Our MCP server uses converts these instructions into the specific Adyen API requests needed to perform the task using function calling. * **API request**: The MCP server makes the API requests to carry out the task you asked for, like making a refund or creating a payment link. ## See also * [API credentials](/development-resources/api-credentials/) * [Adyen on GitHub](https://github.com/Adyen) --- # Source: https://docs.adyen.com/development-resources/migrating-payment-data.md Section: Development resources Title: Import data from another payment provider Description: Migrate your payments existing data to the Adyen payments platform. --- title: "Import data from another payment provider" description: "Migrate your payments existing data to the Adyen payments platform." url: "https://docs.adyen.com/development-resources/migrating-payment-data" source_url: "https://docs.adyen.com/development-resources/migrating-payment-data.md" canonical: "https://docs.adyen.com/development-resources/migrating-payment-data" last_modified: "2019-12-06T09:56:00+01:00" language: "en" --- # Import data from another payment provider Migrate your payments existing data to the Adyen payments platform. [View source](/development-resources/migrating-payment-data.md) If you have previously used a different payment provider, you may want to import your old payments data to the Adyen payments platform to maintain the history of payment activity for analysis. We do not charge for migrating payment data. Because of technical and compliance complexity, migrating payment data usually takes 10 days or more. ## Requirements Migrating payments data requires you to: 1. Adjust your technical processes so tokenization and recurring charge processes can be performed at two different payment service providers (PSP). 2. Decide on an internal shopper reference to use as the Adyen `shopperReference`. Adyen uses a reference to the shopper rather than the payment details for tokenization. 3. Contact your current PSP and check if you can use the internal shopper reference you have chosen. If not, choose one of their IDs to link with your Adyen `shopperReference`. 4. Check their preferred method of transferring files to Adyen. * If they can export the data in the required format, contact [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). We will create a custom PGP key which will speed up your card import process. For more information on required formats, see [recurring payments](/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments) details and [referral lists](/development-resources/migrating-payment-data/import-data-into-referral-lists). * Otherwise, ask your old provider to encrypt the file format with the Adyen PGP key, so that Adyen can perform custom manipulation of the file format afterwards. ## Import card details Once all the above has been done, the card import process can begin. We recommend dividing the migration into three stages: 1. Switch all new tokenizations/sign-ups to Adyen, but keep the recurring charges for old customers at your old provider. If this is not possible, you will need to migrate tokens. New tokens may still be created with your current provider while you are migrating and switching recurring to Adyen. If so, contact your provider and request the tokens created in the interim. 2. Request the export of the card details from your current provider and send them to Adyen for import.  Make sure that you format the CSV as described in [Import payment details for recurring payments](/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments) and [Import data into referral lists](/development-resources/migrating-payment-data/import-data-into-referral-lists). Import files can contain either recurring or referral data. To import both types of data, create two separate files. 3. Proceed to switch the charge process for old customers over to Adyen. Now your migration is complete, and you are ready to process payments with Adyen. --- # Source: https://docs.adyen.com/development-resources/migrating-payment-data/import-data-into-referral-lists.md Section: Development resources Title: Import data into referral lists --- title: "Import data into referral lists" url: "https://docs.adyen.com/development-resources/migrating-payment-data/import-data-into-referral-lists" source_url: "https://docs.adyen.com/development-resources/migrating-payment-data/import-data-into-referral-lists.md" canonical: "https://docs.adyen.com/development-resources/migrating-payment-data/import-data-into-referral-lists" last_modified: "2020-05-01T11:32:00+02:00" language: "en" --- # Import data into referral lists [View source](/development-resources/migrating-payment-data/import-data-into-referral-lists.md) You can import referral data into the Adyen payments platform to be placed on several [referral lists](/risk-management/configure-standard-risk-rules/referral-rules) used for fraud checks. This bulk import of referral data is different from uploading items to a block or trust list using a CSV file in the Customer Area. The CSV file that contains the referral data for the bulk import must be encrypted, and uploading the file requires our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ## Input file format 1. Create a file in CSV (Comma Separated Values) format as per RFC 4180. These are the requirements: * Prefix each line with a supported fixed value field, either the payment method or the type of referral list. See the different types of referrals on this page for the details. * Each line contains the fields for a single referral item. In other words: each referral is on a separate line. * Multi-line fields are not allowed. You can use a variable number of fields per line. * A header is not allowed. * The maximum number of lines per file is 100.000 (if file size permits). 2. Save the file in [UTF-8](https://en.wikipedia.org/wiki/UTF-8) format (to support non-western characters). 3. Encrypt the file using the PGP public key provided to you by either our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), or your Adyen contact. For more information, see our [PGP encryption documentation](/development-resources/pgp-encryption). 4. Send the file to Adyen. ## Card For card referrals the following columns are required: | Field | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `card`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `cardNumber` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The card number. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## SEPA For SEPA referral data the following columns are required: | Field | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value:** `sepa` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `iban` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | IBAN of the bank account. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper name For shopper name the following columns are required: | Field | Required | Description | | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperName`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `shopperName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Name of the shopper. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper email For shopper email referrals the following columns are required: | Field | Required | Description | | ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperEmail`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `shopperEmail` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's email address. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper IP For shopper IP referrals the following columns are required: | Field | Required | Description | | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperIp`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `shopperIP` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The IP address the shopper used to carry out the transaction. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper reference For shopper reference referrals the following columns are required: | Field | Required | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperReference`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `shopperReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A shopper's reference, which is the unique identifier for a shopper. | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper address For shopper address referrals the following columns are required: | Field | Required | Description | | --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperAddress`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-")  | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `street` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Street name. | | `houseNumberOrName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | House number or name. | | `city` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Name of the city | | `postalCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Postal code. | | `stateOrProvince` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | State or province name. | | `countryCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Country code | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Shopper phone number For shopper phone number referrals the following columns are required: | Field | Required | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Fixed value: `shopperPhoneNumber`** | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Record type identifier. | | `merchantAccountCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account name. | | `phoneNumber` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The phone number | | `description` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description of the item, for example a transaction ID of the original transaction. | | `flag` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | You can perform the following actions:- trust - block - delete | ## Example file The following is an example file with several lines of referral data: ```text card,YourMerchantOrCompanyAccount,4111111111111111,"Example description",block shopperName,YourMerchantOrCompanyAccount,"S. Hopper","Example description",trust shopperEmail,YourMerchantOrCompanyAccount,s.hopper@example.com,"Example description",trust shopperIp,YourMerchantOrCompanyAccount,8.8.8.8,"Example description",block shopperReference,YourMerchantOrCompanyAccount,YourMerchantReference,"Example description",delete shopperAddress,YourMerchantOrCompanyAccount,StreetName,58,Amsterdam,2116 E,AMS,NL,"Example description",trust shopperPhoneNumber,YourMerchantOrCompanyAccount,0123456789,"Example description",block ``` --- # Source: https://docs.adyen.com/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments.md Section: Development resources Title: Import payment details for recurring payments Description: Learn how to migrate your payment data. --- title: "Import payment details for recurring payments" description: "Learn how to migrate your payment data." url: "https://docs.adyen.com/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments" source_url: "https://docs.adyen.com/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments.md" canonical: "https://docs.adyen.com/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments" last_modified: "2026-02-04T17:01:00+01:00" language: "en" --- # Import payment details for recurring payments Learn how to migrate your payment data. [View source](/development-resources/migrating-payment-data/import-payment-details-for-recurring-payments.md) To migrate recurring payment contracts from another payment service provider to the Adyen payments platform, you need to provide us with a CSV file containing the recurring payment details. We will then import this file. After importing, we will send you an output file with the migration results. ## Input file format The files containing the data to be imported should be formatted as follows: 1. Create a file in CSV (Comma Separated Values) format as per RFC 4180, in accordance with the following requirements: * The first line contains the [names of the fields](#input-file-reference). You do not have to use all field names and you do not have to use them in the same order as listed on this page. * Each subsequent line contains the fields for a single recurring contract. In other words: Each recurring contract is on a separate line. * If a field doesn't apply to the recurring contract that the line describes, specifying a value is skipped. * Field names and values are case-sensitive. * Multi-line fields are not allowed. * The maximum file length is 1,000,000 lines. * The maximum file size is 1 GB. 2. Save the file in [UTF-8](https://en.wikipedia.org/wiki/UTF-8) format (to support non-western characters). 3. Encrypt the file using the PGP public key provided to you by either our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), or your Adyen contact. For more information, see our [PGP encryption documentation](/development-resources/migrating-payment-data/pgp). 4. Send the file to Adyen. The following is an example input file with four recurring contracts: ```csv MerchantAccount,ShopperEmail,ShopperReference,RecurringContract,EchoData,OwnerName,ExpiryMonth,ExpiryYear,ExpiryYYMM,ExpiryMMYY,ExpiryMMYYYY,ExpiryYYYYMM,CardNumber,Iban,CountryCode,BankLocation,BankName,BankLocationId,BankAccountNumber,BillingAgreementId,PayerId,BillingStreet,BillingCity,BillingStateOrProvince,BillingPostalCode,BillingCountry TestMerchant,mark1test@adyen.com,mark1,RECURRING,MasterCard Bijenkorf NL,D.N. Mater,8,2018,,,,,5100081112223332,,,,,,,,,,,,, TestMerchant,mark30test@adyen.com,mark30,"RECURRING,ONECLICK,PAYOUT",,P.Pal,,,,,,,,,,,,,,B-2308952346426,AK5HCWWRUV2KL,,,,, TestMerchant,mark75test@adyen.com,mark78,RECURRING,,B.Dalby,,,,,,,,NO6012341234561,NO,,,,,,,,,,, TestMerchant,mark2test@adyen.com,mark2,RECURRING,,B.Dalby,,,,,,,,,US,,,121000358,123456789,,,123 Test Street,San Francisco,CA,94000,US ``` ## Input file fields The fields for recurring contracts are: | Field | Required | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MerchantAccount` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The merchant account you want to process payments with. If you are unable to provide this information in your CSV file, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | `ShopperEmail` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The email address of the shopper. | | `ShopperReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system. Minimum length: three characters. Note that the value is case-sensitive. Do not include personally identifiable information (PII), such as name or email address. | | `RecurringContract` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The type of recurring contract. Possible values:- **ONECLICK** – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](/get-started-with-adyen/adyen-glossary/#card-security-code-cvc-cvv-cid). - **RECURRING** – Payment details can be used without the card security code to initiate [card-not-present transactions](/get-started-with-adyen/adyen-glossary/#card-not-present-cnp). - **PAYOUT** – Payment details can be used to [make a payout](/online-payments/online-payouts).Values can also be concatenated with a comma. But when doing so, the combined value needs to be enclosed in double quotes, for example **"RECURRING,ONECLICK"**.If you are unable to provide this information in your CSV file, contact the [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | `OwnerName` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Name of the account holder. | | `OwnerNamePostfix` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The surname of the account holder. Use this if you want to pass the First Name and Surname in two separate fields. | | `IsPreferredPaymentMethod` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | In this field you can specify if a payment method represents the preferred payment method for a shopper. | | `EchoData` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | In this field you can specify data you want to be echoed back in the output file, such as previous tokens for credit card data. The Adyen payments platform does not use this data. | | `AuxEchoData` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Same as `EchoData` , for use when you need more than one data field to be echoed back in the output file. You can ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to configure and enable this for the import result file. | Apart from the above fields, the CSV file can have fields for: * [Card data](#cards) * [Address data](#address) * [SEPA recurring payments](#sepa) * [ACH recurring payments](#ach) * [PayPal recurring payments](#paypal) * [Klarna recurring payments](#klarna) * [Shopper reference re-mapping (optional auxiliary file)](#shopper-alterations) The order of fields is not mandatory and fields can be skipped depending on the payment method. Use the first line of your CSV file to define the field names and their order on other lines. ### Card fields When specifying card data, you need to provide: * Card number. * Expiry date: month and year of expiry.\ You can use either a combination of fields (`ExpiryMonth` and `ExpiryYear`), or a single field to specify both month and year: `ExpiryMMYY`, `ExpiryMMYYYY`, `ExpiryYYMM` or `ExpiryYYYYMM`. | Data | Required | Description | | --------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CardNumber` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The card number. | | Expiry date | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Either a single field or a combination of fields is required. Choose from the following fields.* `ExpiryMMYY`: The month and year of expiry, written as a 4-digit string. For example, **0618** for June 2018. * `ExpiryMMYYYY` :The month and year of expiry, written as a 6-digit string. For example, **062018** for June 2018. `ExpiryYYMM`: The year and month of expiry, written as a 4-digit string. For example, **1806** for June 2018. * `ExpiryYYYYMM`The year and month of expiry, written as a 6-digit string. For example, **201806** for June 2018. * `ExpiryMonth`The month of expiry, written as a 1 or 2-digit string. For example, **6** or **06** for June. Use in combination with `ExpiryYear`. * `ExpiryYear`The year of expiry, written as a 4-digit string. For example, **2018**. Use this in combination with `ExpiryMonth`. | | `networkTxReference` (for Visa) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The Visa Transaction ID from the initial transaction where the shopper signed up for a series of **Subscription** or **UnscheduledCardOnFile** payments. Visa won't support the static value (Interim Transaction ID) after 31 October 2022. Not providing the Visa Transaction ID might result in soft declines and non-compliance assessment fees. | | `networkTxReference` (for Mastercard) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The Mastercard Trace ID from the initial transaction where the shopper signed up for a series of **Subscription** or **UnscheduledCardOnFile** payments. Mastercard won't support the static value (dummy Trace ID) after 19 October 2024. Not providing the Mastercard Trace ID might result in soft declines and non-compliance assessment fees. | | `transactionLinkId` (for Mastercard) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [Mastercard Transaction Link ID](https://help.adyen.com/updates/mastercard-transaction-link-identifier-tlid). Mastercard is migrating from Trace ID to Transaction Link ID. We are required to store the Mastercard Transaction Link ID together with the TRACE ID. This means that `transactionLinkId` will only be imported if `networkTxReference` is also provided. | | `networkTxReference` (for other card schemes) | ![-x-](/user/data/smileys/emoji/x.png "-x-") | For other card schemes besides Visa and Mastercard, we *recommend* that you send the `networkTxReference` from the initial transaction where the shopper signed up for a series of **Subscription** or **UnscheduledCardOnFile** payments. However, if you do not have the `networkTxReference`, we will insert a card scheme-compliant static value on your behalf. We will do that until the schemes no longer allow static values. | ### Address fields Using the following fields, you can specify a physical address. If one field below is provided, then all other fields from this section are also required. | Field | Required | Description | | -------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingHouseNumberOrName` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The number or name of the house. You can omit this and include the data in `BillingStreet`. | | `BillingStreet` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The street name. | | `BillingCity` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The city name. | | `BillingStateOrProvince` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | For USA or Canada, a valid 2-character abbreviation for the state or province respectively. For other countries/regions any abbreviation with maximum 3 characters for the state or province. | | `BillingPostalCode` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The postal code with a maximum of 5 characters for USA and a maximum of 10 characters for any other country/region. | | `BillingCountry` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | A valid value is an 2-character ISO country/region code. | ### Recurring SEPA payment fields When specifying SEPA payment details, you always need to provide the IBAN of the bank account and the account holder name. For third-party payouts, you need to provide all fields listed below, except for the fields `SepaMandateId` and `SepaMandateDateOfSignature`. For more information, refer to [Payouts to a bank account](/online-payments/online-payouts/payouts-to-a-bank-account). To optionally import SEPA Direct Debit mandates, include the mandate identifier, and the date of the mandate signature. | Field | Required | Description | | ---------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Iban` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The IBAN of the bank account. | | `OwnerName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the account holder. | | `CountryCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The code for the country/region where the bank (branch) is located. Format: the two-letter [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo). | | `BankLocation` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The location of the shopper's bank. | | `BankName` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The name of the shopper's bank. | | `BankLocationId` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The ID of the bank location of the shopper. | | `BankAccountNumber` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The account number of the bank. | | `ShopperReference` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system. | | `SepaMandateId` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The SEPA Direct Debit mandate identifier. | | `SepaMandateDateOfSignature` | Required if `SepaMandateId` is included | The date of the SEPA Direct Debit mandate signature. Format: YYYY-MM-DD. For example: **2019-02-22** | ### Recurring ACH payment fields When specifying ACH payment details, you need to provide all of the following fields: | Field | Required | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `BankLocationId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The [ABA routing transit number](https://en.wikipedia.org/wiki/ABA_routing_transit_number) of the account. | | `BankAccountNumber` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The US bank account number from which the payment will be debited. | | `OwnerName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Name on the bank account. | | `CountryCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **US** | | `BillingHouseNumberOrName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The number or name of the house. You can omit this and include the data in `BillingStreet`. | | `BillingStreet` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The street name. | | `BillingCity` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The city name. | | `BillingStateOrProvince` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A valid 2-character abbreviation for the state. | | `BillingPostalCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The postal code. | | `BillingCountry` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **US** | ### Recurring PayPal payment fields For third-party payouts, you need to provide all of the following fields. | Field | Required | Description | | -------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingAgreementId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ID of the billing agreement. Required for recurring payments and must start with 'B-'. The value depends on the type of recurring contract. If not used, should be identified as null. | | `PayPalBuyerEmailId` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | The email address of the Paypal account that set up the billing agreement ID with Paypal. | | `PayerId` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ID of PayPal account. The value depends on the type of recurring contract. If not used, should be identified as null. | ### Recurring Klarna payment fields Not all Klarna payment methods or countries/regions support recurring payments. When specifying Klarna payment details, provide all the following fields. Make sure that you enter a supported combination in the fields `KlarnaVariant` and `KlarnaCountry`. | Field | Required | Description | | --------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `KlarnaTokenId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ID of the shopper's Klarna customer token. For more information, see [Klarna's documentation](https://docs.klarna.com/klarna-payments/in-depth-knowledge/customer-token/). | | `KlarnaVariant` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The Klarna payment method variant. Possible values:- **klarna\_paynow** (for Klarna - Pay Now) - **klarna** (for Klarna - Pay later) - **klarna\_account** (for Klarna - Pay over time) | | `KlarnaCountry` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A valid 2-character ISO country code. | ### Shopper reference re-mapping (optional auxiliary file) If you want to change the shopper references upon importing, you can send an auxiliary shopper reference re-mapping file, in addition to the payment detail file.\ The format of the re-mapping file should include both of the following columns. | Field | Required | Description | | --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `oldShopperReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The old or existing shopper reference which is present in the CSV file, from your other payments vendor. | | `newShopperReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper reference under which the tokens will be stored, after they are imported into the Adyen payments platform. | For example, the file might look like this: ```csv oldShopperReference,newShopperReference ref_1,new_ref_1 ref_2,new_ref_2 ... ``` ## Output file When we have imported your CSV file, we'll send you an output file with the migration results. If you need an encrypted output file, provide your public key to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). To provide more information about the migration, we will start adding new fields to the output file. Make sure that your parsing logic can handle changes such as new headers. The output file has the following fields: | Field | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The status of the migration. Possible values:- **Success** No issues. Line is imported correctly. - **Skipped** This typically happens if there is essential data missing in the line. For example CardNumber or ExpiryYear is missing. | | `paymentMethodVariant` | Type of payment method. See more information about this field [here](/development-resources/paymentmethodvariant). | | `shopperReference` | An ID that refers uniquely to the shopper. For example, a customer ID in a shopping cart system. | | `recurringDetailReference` | The reference that uniquely identifies the recurring detail. | | `alias` | The Adyen alias of the card. Example: H167852639363479 | | `expiryMonth` | The card expiry month. Format: 1 or 2 digits. For example:- 3 = March - 11 = November | | `expiryYear` | The card expiry year. Format: 4 digits. For example: 2018. | | `bin` | The Bank Identification Number (BIN) of a card, which is the first six digits of a card number. Example: 521234 | | `cardSummary` | The last four digits of a card number. | | `issuerCountryCode` | The country/region of the issuer. Format: 2-letter ISO code. | | `echodata` | Data that you specified in the `EchoData` field of your CSV file, such as previous tokens for credit card data. | | `statusMessage` | If the card could not be imported, the reason why the import failed. | | `fundingSource` | The funding source of the card. Example: **DEBIT**, **CREDIT**, or **PREPAID******. | You can also include the following fields in the output file. To receive these fields, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auxEchodata` | Data that you specified in the `AuxEchoData` field of your CSV file. | | `isPreferredPaymentDetail` | Based on the field `IsPreferredPaymentDetail` of your CSV file. | | `networkTxReferenceStatus` | Import status of the `networkTxReference` specified in your CSV file. Possible values: **NOT\_PROVIDED**, **IMPORTED**, **NOT\_VALID** | | `transactionLinkIdStatus` | Import status of the `transactionLinkId` specified in your CSV file. Possible values: **NOT\_PROVIDED**, **IMPORTED**, **NOT\_VALID**, **NOT\_APPLICABLE\_FOR\_VARIANT**, **NETWORK\_TX\_REFERENCE\_MISSING** | | `billingAddressStatus` | Import status of the `Address fields` specified in your CSV file. Possible values: **NOT\_PROVIDED**, **IMPORTED**, **NOT\_VALID** | | `paymentDetailDifference` | The storage status of the payment details. Possible values: **created**, **updated**, **alreadyExisting** | The following is an example output file, without additional fields, with four payment details successfully migrated: ```csv status,paymentMethodVariant,shopperReference,recurringDetailReference,alias,expiryMonth,expiryYear,bin,cardSummary,issuerCountryCode,echodata,statusMessage,fundingSource Success,amex,HENSHAP,2914485358484074,H116006232956221,2,2017,374291,1002,,,,, Success,amex,LOCKL1,2914546007913217,E167970689307238,2,2020,374293,1006,,,,, Success,amex,HICKMAGP,2714583830042296,M212359999703856,8,2017,374290,1009,,,,, Success,amex,SUTHM1,2714583830042304,A129651585108480,7,2016,374297,1005,,,,, ``` --- # Source: https://docs.adyen.com/development-resources/overview-response-handling.md Section: Development resources Title: Response handling Description: Learn about how Adyen handles responses. --- title: "Response handling" description: "Learn about how Adyen handles responses." url: "https://docs.adyen.com/development-resources/overview-response-handling" source_url: "https://docs.adyen.com/development-resources/overview-response-handling.md" canonical: "https://docs.adyen.com/development-resources/overview-response-handling" last_modified: "2021-05-12T10:56:00+02:00" language: "en" --- # Response handling Learn about how Adyen handles responses. [View source](/development-resources/overview-response-handling.md) The type of response and the details of a response depend on the transaction's stage in the payment lifecycle. Some response details also depend on the entity that is returning the response. Response details are returned in the API response. ## Types of responses The following sections indicate the types of responses, how to interpret them, and recommendations on follow-up actions to take. ### HTTP status codes The HTTP status code indicates the status of the API request you sent. The status code shows whether your request is processed successfully, or whether your request encountered an error. View the list of [HTTP status codes](/development-resources/response-handling/#http-responses) to understand how to interpret these codes. ### Error codes and messages When you make an API request to Adyen and there is an error, you receive a response with a [HTTP status code](/development-resources/response-handling/#http-responses) different from `200`. In this response, you get `errorCode` and `message` fields that help you diagnose and resolve the error. Errors range from connection issues to wrong payment method setups. View the list of Adyen [error codes and messages](/development-resources/error-codes/#generic-error-codes) for an explanation of these codes and how they look in the API response. ### Raw acquirer responses A successful payment request (HTTP status code `200/OK`) does not automatically mean that the payment is successful. The transaction can also be refused or cancelled by the responding financial institution, such as an issuer or payment method. When a payment is successfully submitted a raw acquirer response is returned that indicates whether the financial institution authorized or rejected the payment. If applicable, the raw acquirer response provides reasons for a transaction that is rejected. View the list of [raw acquirer responses](/development-resources/raw-acquirer-responses/) for the most commonly used payment methods. ## How Adyen handles responses When handling responses, the raw acquirer response is mapped to a refusal reason and result code. ### Refusal reasons Every payment method has its own set of raw acquirer responses. To provide an easier interpretation, Adyen maps each raw acquirer response to a unique [refusal reason](/development-resources/refusal-reasons/). Refusal reasons are included in the API response. ### Result codes The [result code](/account/payments-lifecycle/?utm_source=bo_live\&tab=unsuccessful_payment_2#payment) summarizes the status of the response: | Result codes | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Authorised** | The payment is approved by the financial institution. | | **Refused** | The transaction is rejected by the payment method or card issuer. The payment method is received, and the request is rejected by the financial institution (e.g. payment method, card issuer). The payment is also refused by Adyen if the risk score is more than 99 points.More reasons for receiving **Refused** include:- Insufficient funds - Issuer unavailable - Suspected fraud | | **Error** | The payment is received, but an error occurred while communicating with the financial institution.Errors that are returned by Adyen can include the following reasons:- Misconfiguration of an acquirer account - Incorrect data elements were submittedThe full list of Adyen errors can be found in the Error codes and messages page.Errors can also be returned by external financial institutions, including:- Format errors - Issuer is unavailable to respondMore examples of errors returned by external financial institutions can be found on the [Raw acquirer responses](/development-resources/raw-acquirer-responses/) page. | | **Cancelled** | A cancellation request for a transaction is submitted and approved. | Result codes are included in the API response. --- # Source: https://docs.adyen.com/development-resources/paymentmethodvariant.md Section: Development resources Title: PaymentMethodVariant --- title: "PaymentMethodVariant" url: "https://docs.adyen.com/development-resources/paymentmethodvariant" source_url: "https://docs.adyen.com/development-resources/paymentmethodvariant.md" canonical: "https://docs.adyen.com/development-resources/paymentmethodvariant" last_modified: "2023-03-22T16:51:00+01:00" language: "en" --- # PaymentMethodVariant [View source](/development-resources/paymentmethodvariant.md) The `paymentMethodVariant` field returns the type of payment method used during a transaction. In addition to the values listed below, Adyen can return other payment method variants depending on your configuration. ## American Express | Payment Method Variant/Card type | Description | | -------------------------------- | ------------------------------------------- | | amex | American Express | | amex\_googlepay | Google Pay - American Express | | amex\_applepay | Apple Pay - American Express | | amex\_samsungpay | Samsung Pay - American Express | | amex\_vipps | Vipps - American Express | | amex\_mobilepay | MobilePay - American Express | | amexcommercial | American Express Commercial Credit Card | | amexconsumer | American Express Consumer Credit Card | | amexcorporate | American Express Corporate Credit Card | | amexdebit | American Express Debit Card | | amexprepaid | American Express Prepaid Card | | amexprepaidreloadable | American Express Prepaid-Reloadable Card | | amexsmallbusiness | American Express Small Business Credit Card | ## Alipay | Payment Method Variant/Card type | Description | | -------------------------------- | ------------------------ | | alipay | Alipay | | alipay\_wap | Alipay WAP | | alipay\_hk | Alipay HK | | alipay\_connect | AntFinancial OSP Offline | | alipay\_sg\_pos | Alipay SG POS | ## China UnionPay | Payment Method Variant/Card type | Description | | -------------------------------- | --------------------------- | | cup | China UnionPay card payment | | cupdebit | China UnionPay debit | | cupcredit | China UnionPay credit | | cupprepaid | China UnionPay prepaid | ## Discover | Payment Method Variant/Card type | Description | | -------------------------------- | ---------------------- | | discover | Discover | | discover\_googlepay | Google Pay - Discover | | discover\_applepay | Apple Pay - Discover | | discover\_samsungpay | Samsung Pay - Discover | ## DOKU | Payment Method Variant/Card type | Description | | -------------------------------- | ----------------- | | doku | DOKU | | doku\_alfamart | Alfamart via DOKU | | doku\_bca\_va | ID Bank Transfer | | doku\_bni\_va | ID Bank Transfer | | doku\_bri\_va | ID Bank Transfer | | doku\_cimb\_va | ID Bank Transfer | | doku\_danamon\_va | ID Bank Transfer | | doku\_indomaret | Indomaret | | doku\_mandiri\_va | ID Bank Transfer | | doku\_ovo | OVO | | doku\_permata\_lite\_atm | ID Bank Transfer | | doku\_sinarmas\_va | ID Bank Transfer | | doku\_wallet | DOKU wallet | ## Dragonpay | Payment Method Variant/Card type | Description | | -------------------------------- | ---------------------------------------- | | dragonpay | Dragonpay | | dragonpay\_otc\_banking | Dragonpay OTC/ATM Philippines | | dragonpay\_otc\_international | Dragonpay international OTC | | dragonpay\_otc\_non\_banking | Dragonpay OTC non-bank | | dragonpay\_otc\_philippines | Dragonpay convenience stores Philippines | | dragonpay\_ebanking | Dragonpay ebanking | | dragonpay\_seveneleven | 7-Eleven Philippines | ## JCB | Payment Method Variant/Card type | Description | | -------------------------------- | --------------------------- | | jcb | JCB | | jcb\_applepay | Apple Pay - JCB credit card | | jcbcredit | JCB credit | | jcbdebit | JCB debit | | jcbprepaidanonymous | JCB prepaid anonymous | | jcbprepaid | JCB prepaid | ## Maestro | Payment Method Variant/Card type | Description | | -------------------------------- | --------------------- | | maestro | Maestro | | maestro\_applepay | Apple Pay - Maestro | | maestro\_googlepay | Google Pay - Maestro | | maestro\_samsungpay | Samsung Pay - Maestro | | maestro\_vipps | Vipps - Maestro | | maestro\_mobilepay | MobilePay - Maestro | | maestrouk | Maestro UK | | maestro\_usa | Maestro USA | ## Mastercard | Payment Method Variant/Card type | Description | | -------------------------------- | ------------------------------------ | | mc | Mastercard | | mc\_googlepay | Google Pay - Mastercard | | mc\_applepay | Apple Pay - Mastercard | | mc\_samsungpay | Samsung Pay - Mastercard | | mc\_vipps | Vipps - Mastercard | | mc\_mobilepay | MobilePay - Mastercard | | mcalphabankbonus | Mastercard Alpha Bank Bonus | | mcatm | Mastercard ATM | | mccommercialcredit | Mastercard Commercial Credit | | mccommercialdebit | Mastercard Commercial Debit | | mccommercialpremiumcredit | Mastercard Commercial Premium Credit | | mccommercialpremiumdebit | Mastercard Commercial Premium Debit | | mccorporate | Mastercard Corporate | | mccorporatecredit | Mastercard Corporate Credit | | mccorporatedebit | Mastercard Corporate Debit | | mccredit | Mastercard Credit | | mcdebit | Mastercard Debit | | mcfleetcredit | Mastercard Fleet Credit | | mcfleetdebit | Mastercard Fleet Debit | | mcpremiumcredit | Mastercard Premium Credit | | mcpremiumdebit | Mastercard Premium Debit | | mcprepaidanonymous | Mastercard Prepaid Anonymous | | mcpro | Mastercard Pro | | mcpurchasingcredit | Mastercard Purchasing Credit | | mcpurchasingdebit | Mastercard Purchasing Debit | | mcstandardcredit | Mastercard Standard Credit | | mcstandarddebit | Mastercard Standard Debit | | mcsuperpremiumcredit | Mastercard Super Premium Credit | | mcsuperpremiumdebit | Mastercard Super Premium Debit | | mc\_voucher\_br | Mastercard Brazilian voucher card | ## MOLPay | Payment Method Variant/Card type | Description | | -------------------------------- | --------------------------------- | | molpay\_alipay | Alipay via MOLPay | | molpay\_bangkokbank | Online banking Thailand | | molpay\_boost | Boost via MOLPay | | molpay\_cash | 7-Eleven via MOLPay | | molpay\_ebanking\_fpx\_MY | Malaysian eBanking via FPX MOLPay | | molpay\_ebanking\_MY | Online banking Malaysia | | molpay\_ebanking\_TH | Thailand eBanking via MOLPay | | molpay\_fpx | Online banking Malaysia | | molpay\_kbank | Online banking Thailand | | molpay\_krungsribank | Online banking Thailand | | molpay\_krungthaibank | Online banking Thailand | | molpay\_points | RazerGold (by MOLPay) | | molpay\_siamcommercialbank | Online banking Thailand | ## Visa | Payment Method Variant/Card type | Description | | -------------------------------- | ------------------------------------ | | visa | Visa | | visa\_googlepay | Google Pay - Visa | | visa\_applepay | Apple Pay - Visa | | visadebit\_applepay | Apple Pay - Visa Debit | | visa\_samsungpay | Samsung Pay - Visa | | visa\_vipps | Vipps - Visa | | visa\_mobilepay | MobilePay - Visa | | visaalphabankbonus | Visa Alpha Bank Bonus | | visabusiness | Visa Business | | visacheckout | Visa Checkout | | visaclassic | Visa Classic | | visacommercialcredit | Visa Commercial Credit | | visacommercialdebit | Visa Commercial Debit | | visacommercialpremiumcredit | Visa Commercial Premium Credit | | visacommercialpremiumdebit | Visa Commercial Premium Debit | | visacommercialsuperpremiumcredit | Visa Commercial Super Premium Credit | | visacommercialsuperpremiumdebit | Visa Commercial Super Premium Debit | | visacorporate | Visa Corporate | | visacorporatecredit | Visa Corporate Credit | | visacorporatedebit | Visa Corporate Debit | | visacredit | Visa credit card | | visadebit | Visa debit card | | visafleetcredit | Visa Fleet Credit | | visafleetdebit | Visa Fleet Debit | | visagold | Visa Gold | | visahipotecario | Visa Hipotecario | | visaplatinum | Visa Platinum | | visapremiumcredit | Visa Premium Credit | | visapremiumdebit | Visa Premium Debit | | visaprepaidanonymous | Visa Prepaid Anonymous | | visaproprietary | Visa Proprietary | | visapurchasing | Visa Purchasing | | visapurchasingcredit | Visa Purchasing Credit | | visapurchasingdebit | Visa Purchasing Debit | | visasaraivacard | Visa Saraiva Card | | visasignature | Visa Signature | | visastandardcredit | Visa Standard Credit | | visastandarddebit | Visa Standard Debit | | visasuperpremiumcredit | Visa Super Premium Credit | | visasuperpremiumdebit | Visa Super Premium Debit | | visa\_voucher\_br | Visa Brazilian voucher card | | vpay | V Pay | | electron | Visa Electron | | electron\_applepay | Apple Pay - Visa Electron | | electron\_samsungpay | Samsung Pay - Visa Electron | | electron\_vipps | Vipps - Visa Electron | | electron\_mobilepay | MobilePay - Visa Electron | ## Gift card | Payment Method Variant/Card type | Description | | -------------------------------- | ------------------------------------- | | auriga | Auriga gift card | | babygiftcard | Baby gift card | | bloemengiftcard | Bloemen Giftcard | | cashcomgiftcard | Cashcom gift card | | entercard | EnterCard gift card | | expertgiftcard | Expert Cadeaukaart gift card | | fashioncheque | Fashioncheque gift card | | fijncadeau | FijnCadeau gift card | | fleuropbloemenbon | Fleurop Bloemenbon | | fonqgiftcard | fonQ Giftcard | | forbrugsforeningen | Forbrugsforeningen gift card | | gallgall | Gall & Gall gift card | | givex | Givex gift card | | hallmarkcard | Hallmark gift card | | igive | iGive gift card | | ikano | Ikano gift card | | prosodie\_illicado | Illicado gift card | | kadowereld | KadoWereld gift card | | kidscadeau | KidsCadeau gift card | | kindpas | Kindpas gift card | | leisurecard | Leisure Voucher gift card | | nationalebioscoopbon | Nationale Bioscoopbon | | netscard | Nets gift card | | oberthur | Oberthur gift card | | pathegiftcard | Pathe gift card | | payex | PayEx gift card | | podiumcard | Podium Card gift card | | resursgiftcard | Resurs gift card | | sparnord | Spar Nord gift card | | sparebank | SpareBank gift card | | svs | SVS gift card | | universalgiftcard | Universal gift card gift card | | valuelinkgiftcard | Fiserv (formerly ValueLink) gift card | | vdcadeaucard | V and D Cadeaucard | | vvvcadeaubon | VVV Cadeaubon | | vvvgiftcard | VVV gift card | | webshopgiftcard | Webshop gift card | | winkelcheque | Winkel Cheque gift card | | xponcard | XPonCard gift card | | yourgift | YourGift gift card | ## Others | Payment Method Variant/Card type | Description | | -------------------------------- | ---------------------------------------------- | | abrapetite | Abrapetite | | abrapetite\_credit | Abrapetite credit card | | abrapetite\_debit | Abrapetite debit card | | abrapetite\_prepaid | Abrapetite prepaid card | | accel | Accel | | accel\_applepay | Accel - Apple Pay | | accel\_googlepay | Accel - Google Pay | | accel\_samsungpay | Accel - Samsung Pay | | ach | ACH US Direct Debit | | affirm | Affirm | | affirm\_pos | Affirm for POS | | afterpaytouch | Afterpay | | afterpaytouch\_pos | Afterpay for POS | | alelo | Alelo | | atome | Atome | | banese\_card | Banese card | | banese\_card\_credit | Banese credit card | | banese\_card\_debit | Banese debit card | | banese\_card\_prepaid | Banese prepaid card | | bankaxept | BankAxept | | bcmc | Bancontact | | bcmc\_mobile | Bancontact app | | blik | Blik | | boleto | Boleto | | carnet | Carnet | | cartebancaire | Carte Bancaire | | cartebancaire\_applepay | Carte Bancaire - Apple Pay | | cashapp | Cash App Pay | | cellulant | Cellulant | | clearpay | Clearpay | | credtodos | CredTODOS | | credtodos\_private\_credit | CredTODOS private credit | | credtodos\_private\_debit | CredTODOS private debit | | dana | Dana payment method Indonesia | | dankort | Dankort | | dankort\_mobilepay | MobilePay - Dankort | | diners | Diners | | directdebit\_GB | BACS Direct Debit (Direct Debit Great Britain) | | ebanking\_FI | Electronic Bank Transfer Finland | | econtext\_atm | eContext Pay-easy ATM | | econtext\_online | eContext Pay-easy online banking | | econtext\_seven\_eleven | eContext 7-Eleven | | econtext\_stores | eContext convenience stores | | eftpos\_australia | eftpos Australia | | eftpos\_australia\_chq | eftpos Australia - CHQ account type | | eftpos\_australia\_sav | eftpos Australia - SAV account type | | elo | Elo | | elo\_voucher\_br | Elo Brazilian voucher card | | eps | Electronic Payment Service (EPS) | | facilypay | 3x4xOney | | gcash | GCash Payment Method Philippines | | girocard | Girocard | | girocard\_applepay | Girocard - Apple Pay | | googlepay | Google Pay | | gopay\_wallet | GoPay Wallet | | grabpay\_MY | GrabPay MY | | grabpay\_PH | GrabPay PH | | grabpay\_pos | GrabPay for POS | | grabpay\_SG | GrabPay SG | | hipercard | Hipercard | | ideal | iDeal | | interac | Interac(online banking) | | interac\_applepay | Apple Pay - Interac (in-app) | | interac\_card | Interac Debit for POS | | interac\_googlepay | Google Pay - Interac (in-app) | | kakaopay | KakaoPay payment method | | kcp\_banktransfer | Korean Bank Transfer | | kcp\_payco | PayCo | | klarna | Klarna Pay Later | | klarna\_account | Klarna Pay over time | | klarna\_paynow | Klarna Pay Now | | maestro\_usa\_applepay | Maestro USA - Apple Pay | | maestro\_usa\_googlepay | Maestro USA - Google Pay | | maestro\_usa\_samsungpay | Maestro USA - Samsung Pay | | mbway | MB WAY | | mobilepay | MobilePay | | momo\_atm | MoMo ATM | | momo\_wallet | MoMo Wallet | | multibanco | Multibanco | | nordea | Nordea | | nyce | NYCE | | nyce\_applepay | NYCE - Apple Pay | | nyce\_googlepay | NYCE - Google Pay | | nyce\_samsungpay | NYCE - Samsung Pay | | onlinebanking\_IN | Online banking India | | onlineBanking\_PL | Online banking Poland | | oxxo | Oxxo | | paymaya\_connect | PayMaya Connect | | paymaya\_wallet | PayMaya Wallet | | paypal | PayPal | | paypal\_pos | PayPal for POS | | paysafecard | PaySafeCard | | paytm | Paytm payment method India | | pix | Pix | | pulse | PULSE for in-person payments | | pulse\_applepay | PULSE - Apple Pay | | pulse\_googlepay | PULSE - Google Pay | | pulse\_pinless | PULSE for online payments | | pulse\_samsungpay | PULSE - Samsung Pay | | romcard | Romcard | | romcard\_credit | Romcard credit card | | romcard\_debit | Romcard debit card | | samsungpay | Samsung Pay | | sepadirectdebit | SEPA Direct Debit | | star | STAR | | star\_applepay | STAR - Apple Pay | | star\_googlepay | STAR - Google Pay | | star\_samsungpay | STAR - Samsung Pay | | swish | Swish | | trustly | Trustly | | twint | Twint | | twint\_pos | Twint for POS | | upi\_collect | UPI Collect | | upi\_intent | UPI Intent | | upi\_qr | UPI QR | | vale\_refeicao | Vale Refeicao | | vale\_refeicao\_prepaid | Vale Refeicao prepaid | | vipps | Vipps | | wallet\_IN | Wallets India | | wechatpay | WeChat Pay | | wechatpay\_pos | WeChat Pay for POS | | zip | Zip | | zip\_pos | Zip for POS | ## Management API The following payment methods are available when adding through [Management API](https://docs.adyen.com/api-explorer/Management/latest/overview). For some payment methods, you need to provide additional information. | Payment method | Payment method variant | Ecommerce | Point of sale | Notes | | ----------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Accel](/payment-methods/cards) | accel | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings). | | [ACH Direct Debit](/payment-methods/ach-direct-debit) | ach | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires approval, reach out to your Adyen contact. | | [Affirm](/payment-methods/affirm) | affirm | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings). | | [Afterpay](/payment-methods/afterpaytouch) | afterpaytouch | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-afterpayTouch). Send separate requests for each currency. Available currencies: AUD, CAD, EUR, GBP, NZD, USD. | | Alelo | alelo | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). | | [Alipay](/payment-methods/alipay) | alipay / alipay\_wap | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). Set to **eCommerce**. | | [Alipay+](/point-of-sale/what-we-support/payment-methods) | alipay | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). Set to **pos**. | | [American Express](/payment-methods/cards) | amex | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [currencies](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-currencies) and [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). | | [Apple Pay](/payment-methods/apple-pay) | applepay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-applePay) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") No configuration required | | | [BACS Direct Debit](/payment-methods/bacs) | directdebit\_GB | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Bancontact](/payment-methods/bancontact) | bcmc | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-bcmc). | | [BLIK](/payment-methods/blik) | blik | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Cartes Bancaires](/payment-methods/cards) | cartebancaire | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Supported only if the store is located in France. Requires [additional parameters.](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-cartesBancaires) | | [China UnionPay (CUP)](/payment-methods/cards) | cup | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). | | [Clearpay](/payment-methods/clearpay) | clearpay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-clearpay). Send separate requests for each currency. Only available for GBP. | | [Diners](/payment-methods/cards) | diners | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Discover will be automatically included in the setup. Diners Club International® is part of Discover. | | [Discover](/payment-methods/cards) | discover | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Diners will be automatically included in the setup. Diners Club International® is part of Discover. | | [eftpos Australia](/payment-methods/cards) | eftpos\_australia | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [Girocard](/payment-methods/cards) | girocard | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [Google Pay](/payment-methods/google-pay) | googlepay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-googlePay) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") No configuration required | | | [iDEAL](/payment-methods/ideal) | ideal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Interac](/payment-methods/cards) | interac\_card | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [JCB](/payment-methods/cards) | jcb | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction) and [currencies](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-currencies) for Australia, Canada, and New Zealand. | | [Klarna](/payment-methods/klarna) | klarna | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Pay later Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-klarna). | | | klarna\_account | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Pay over time Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-klarna). | | | klarna\_paynow | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Pay now Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-klarna). | | [Maestro](/payment-methods/cards) | maestro | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Not supported for the US. You can use Maestro USA instead. | | [MB WAY](/payment-methods/mb-way) | mbway | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Mastercard](/payment-methods/cards) | mc | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [MobilePay](/payment-methods/mobilepay) | mobilepay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Multibanco](/payment-methods/multibanco) | multibanco | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [NYCE](/payment-methods/cards) | nyce | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings). | | [Online banking Finland](/payment-methods/finland-online-banking) | ebanking\_FI | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Online banking Poland](/payment-methods/online-banking-poland) | onlinebanking\_Pl | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [Pay by Bank (Europe)](/payment-methods/open-banking) | paybybank | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Available currencies: EUR and GBP. | | [Pay by Bank (US)](/payment-methods/pay-by-bank-us) | paybybank\_AIS\_DD | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Available currencies: USD. | | [Pay Now](/payment-methods/paynow) | paynow | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Available currencies: SGD. | | [Pay Now POS](/payment-methods/paynow) | paynow\_pos | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Available currencies: SGD. | | [PayPal](/payment-methods/paypal) | paypal | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional configuration for marketplaces](/payment-methods/paypal/setup-paypal-marketplaces). | | [PULSE](/payment-methods/cards) | pulse | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings). | | Sodexo | sodexo | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings#request-sodexo), and [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). | | Softnex | vale\_refeicao | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | | vale\_refeicao\_prepaid | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [STAR](/payment-methods/cards) | star | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/1/post/merchants/_merchantId_/paymentMethodSettings). | | [Swish](/payment-methods/swish) | swish | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-swish). | | Ticket | ticket | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [shopper interaction](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-shopperInteraction). | | [Titres-restaurant](/payment-methods/titres-restaurant) | mealVoucher\_FR | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-mealVoucher_FR). | | [Trustly](/payment-methods/trustly) | trustly | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | | [TWINT](/payment-methods/twint) | twint | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-twint). | | | twint\_pos | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-twint). | | [Vipps](/payment-methods/vipps) | vipps | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-vipps). | | [Visa](/payment-methods/cards) | visa | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [VPay](/payment-methods/cards) | vpay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | | [WeChat Pay](/payment-methods/wechat-pay) | wechatpay | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-wechatpay_pos). | | | wechatpay\_pos | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Requires [additional parameters](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings#request-wechatpay_pos). | | | | | | | --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide.md Section: Development resources Title: PCI DSS compliance guide Description: Learn what you need to do to comply with PCI DSS v4.0.1. --- title: "PCI DSS compliance guide" description: "Learn what you need to do to comply with PCI DSS v4.0.1." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide" last_modified: "2024-02-27T10:02:00+01:00" language: "en" --- # PCI DSS compliance guide Learn what you need to do to comply with PCI DSS v4.0.1. [View source](/development-resources/pci-dss-compliance-guide.md) **PCI DSS v4.0.1 has been released** [PCI DSS v4.0.1](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf) has replaced v3.2.1. Now, when you assess your compliance, you must use PCI DSS v4.0.1 documents. If you already completed a v4.0 document, you do not need to complete the v4.0.1 document. Your v4.0 document is valid until it expires. The Payment Card Industry Data Security Standard (PCI DSS) is a set of global security standards created by the Payment Card Industry Security Standards Council (PCI SSC) to ensure that every company that collects, processes, stores, or transmits cardholder data maintains a secure cardholder data environment. PCI DSS applies to all entities that accept credit cards or are involved in payment processing, such as payment processors, acquirers, issuers, and service providers. This document should be used only for guidance purposes, and should not be taken as definitive advice. You should always consult your acquirer or a PCI DSS Qualified Security Assessor (QSA) for clarification. ## Introduction to PCI DSS PCI DSS, a global standard adopted by the major card schemes (Mastercard, Visa, JCB, Diners, and American Express), defines a set of technical and operational requirements that when implemented correctly, helps you to protect cardholder data, reduce fraud, and minimize the chances of a data breach resulting from malicious attacks. Complying with the requirements helps you to maintain your shopper's trust. As mandated by the card schemes, every merchant that accepts credit card payments has to comply with PCI DSS requirements. Even though PCI DSS is not part of any law, the standard is applied globally and it comes with significant penalties and costs for organizations that do not comply with the requirements. These financial consequences include non-compliance assessment fees, legal costs, and costs for forensic investigations, onsite QSA assessments, and security updates. Before you continue, it is important to understand that: * PCI DSS applies solely to the people, processes, and technology that collect, store, process, or transmit cardholder data, known as the Cardholder Data Environment (CDE). * PCI DSS is not a single event, but a continuous, ongoing process. Every entity has to validate their compliance with PCI DSS **annually** by completing one of the official PCI SSC validation documents. ## Adyen's role in PCI DSS compliance Implementing PCI DSS in your business can be daunting, especially if you do not have an existing framework to protect sensitive information. To help reduce the scope of PCI DSS compliance, Adyen offers integrations that handle most of the PCI DSS requirements. The simplest way for you to be PCI compliant is to use our encrypted solutions—you never see and never have access to unencrypted cardholder data. When you use our encrypted solutions, you are outsourcing most PCI DSS responsibilities to Adyen. However, because you accept credit card payments on your website, your app, or in your physical store, your integration with Adyen does not completely eliminate your PCI scope. * **Adyen's responsibility**: Adyen is solely responsible for the security of cardholder data only as soon as Adyen receives the data through the relevant payment interface. After Adyen receives your shoppers' cardholder data, the data is contained in a PCI DSS Level 1 Service Provider Cardholder Data Environment. * **Your responsibility**: You are responsible for making sure that cardholder data is secure and protected before the data reaches Adyen. Depending on your integration, you also have to comply with cardholder data storage requirements. Adyen is a PCI DSS Level 1 Service Provider, with PCI DSS compliance assessed by an independent [Qualified Security Assessor (QSA)](https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors) annually. ## Ensuring compliance with PCI DSS v4.0.1 PCI DSS v4.0.1 was released on June 11, 2024. It has updates to existing requirements and introduces expanded requirements in key security and technology areas, such as: * Mobile phones and tablets. * Contactless payments. * Cloud adaptation. * New software development practices. * Increased reliance on third-party services. To validate your compliance with v4.0.1 and review the requirements, refer to the relevant integration sections for [Online payments](#online-payments), [Mobile in-app online payments](#mobile-in-app-online-payments-integration), and [In-person payments](#in-person-payments). ## Online payments integration Select your [Web online payments](/online-payments) integration below to learn which PCI DSS requirements you must comply with and the corresponding documentation that you should provide: The following validation requirements are based on Adyen's acceptable risk profile for each integration type. These may differ from what other acquirers require. ### Tab: Drop-in / Components / Plugins **Required documents:** * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) You must [make sure that you have eligibility for SAQ A](/development-resources/pci-dss-compliance-guide/saq-a-eligibility). **Integration:** You use Drop-in, Components, or a plugin that uses Adyen's [Card Component](/payment-methods/cards/web-component/) to embed a web page within your website using an [`iframe` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe). The content of the embedded elements is isolated from your web page, and the cardholder data is encrypted on your shopper's browser. You do not have access to decryption keys, thus you do not have access to your shoppers' cardholder data. **Possible risks | Low-Medium:** This integration type may still be susceptible to data compromises by malicious actors. If an attacker gains unauthorized access to your website, they can find ways to deceive the shopper. For example, attackers can create alternative content for the Drop-in or Components, or drop an iframe over the already existing iframe. In this scenario, the payment may still be completed, but a copy of the cardholder data is sent to the attacker. **Mitigating the risks:** The risks associated with this integration can be significantly reduced by doing the following: * Making sure vendor-supplied usernames and passwords are not used within your environment. * Actively monitoring industry sources for vulnerability information and patching software according to the risk ranking of identified vulnerabilities. * Using unique user IDs and requiring strong passwords of at least 12 characters. * Implementing a security policy that includes an incident response plan and defines information security roles and responsibilities for all personnel. * Performing external vulnerability scans every 3 months. This is a new requirement in PCI DSS v4.0.1. * Ensure all other iframes loaded into your page follow security best practices, and that the entities loading them are PCI DSS compliant. Adyen iframes are designed to be isolated, which prevents browser-based malware from spreading to other elements of the webpage or network. Other iframes we load for additional payment methods or partners are vetted during our third-party onboarding process, ensuring the same level of security and PCI compliance.\ Additionally, Adyen is a qualified [PCI Secure Software Lifecycle (SLC) software vendor](https://listings.pcisecuritystandards.org/assessors_and_solutions/software_lifecycle) for the development of payment pages and components, added to its own PCI DSS Attestation of Compliance (AoC) regarding general security controls. Payment components are continuously tested for vulnerabilities and design issues, ensuring the required level of security. **Validation document and requirements:** Adyen requires that you assess your PCI DSS compliance according to the following requirements of the Self-Assessment Questionnaire A (SAQ A): * PCI DSS v4.0.1: Requirements 2, 6, 8, 11, and 12. ### Tab: Pay by Link **Required documents:** * None **Integration:** You provide a payment link to your shopper by email, SMS, or QR code. The payment link redirects your shopper to a secure Adyen-hosted payment page to complete the payment. Your responsibility is to provide the shopper with the correct link to the Adyen-hosted payment page. **Possible risks | Low:** An attacker could gain access to your system that generates the link, through API or the Customer Area, and change the payment link from an Adyen-hosted payment page to a fraudulent payment website where they try to steal your shopper's cardholder data. **Mitigating the risks:** The risks associated with this integration can be significantly reduced by making sure that vendor-supplied usernames and passwords are not used within your environment, software is patched as soon as released, and strong passwords and unique user IDs are used. Adyen is a qualified [PCI Secure Software Lifecycle (SLC) software vendor](https://listings.pcisecuritystandards.org/assessors_and_solutions/software_lifecycle) for the development of payment pages and components, added to its own PCI DSS AoC regarding general security controls. Payment pages are continuously tested for vulnerabilities and design issues, ensuring the required level of security. **Validation document and requirements:** Adyen does not require you to submit any PCI DSS documentation. However, you must be PCI DSS compliant at all times. For more information on PCI DSS requirements, refer to [PCI DSS Quick Reference Guide](https://listings.pcisecuritystandards.org/search_result/documents/pci_ssc_quick_reference_guide). Furthermore, Adyen may occasionally contact you and ask you to provide necessary PCI DSS documentation depending on your risk profile. ### Tab: Hosted Checkout **Required documents:** * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) You must make sure that you have [eligibility for SAQ A](/development-resources/pci-dss-compliance-guide/saq-a-eligibility). **Integration:** You redirect your shopper from your website to an Adyen-hosted payment page to complete the payment. After your shopper completes the payment, they return to your website with the result of the payment session. **Possible risks | Low:** An attacker could gain access to your website and change the redirect from an Adyen-hosted payment page to a fraudulent payment website where they try to steal your shopper's cardholder data. **Mitigating the risks:** The risks associated with this integration can be significantly reduced by making sure that vendor-supplied usernames and passwords are not used within your environment, software is patched as soon as released, and strong passwords and unique user IDs are used. Adyen is a qualified [PCI Secure Software Lifecycle (SLC) software vendor](https://listings.pcisecuritystandards.org/assessors_and_solutions/software_lifecycle) for the development of payment pages and components, added to its own PCI DSS AoC regarding general security controls. Payment pages are continuously tested for vulnerabilities and design issues, ensuring the required level of security. **Validation document and requirements:** Adyen requires that you assess your PCI DSS compliance according to the following requirements of the Self-Assessment Questionnaire A (SAQ A): * PCI DSS v4.0.1: Requirements 2, 6, 8, 11, and 12. ### Tab: API only This applies if you use raw card data from shoppers. **Required document:** * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire D](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-D-Merchant.pdf) If you use Adyen's [Custom Card Component](/payment-methods/cards/custom-card-integration), which includes encryption based on our [Card Component](/development-resources/pci-dss-compliance-guide?tab=drop-in__components__plugins_0_1) and securely encrypts card details, the required document is: * [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) **Integration:** You build your own UI and use only our APIs. This integration is commonly used when you want to be in full control of the payment flow. The checkout page is hosted, served, and controlled by you. You receive cardholder data from your shopper's browser, process the data, and then send the raw card data to Adyen over Transport Layer Security (TLS 1.2), according to PCI DSS requirements. **Possible risks | High:** This integration requires a wider PCI DSS scope as your system receives, transmits, and potentially stores and processes cardholder data—giving you full control of the payment flow and the payment data. A malicious actor that successfully compromises your website or your systems will potentially be able to access large amounts of cardholder data. **Mitigating the risks:** The risks associated with this integration are considered higher, since you are completely in control over the collection, transmission, and optional storage of cardholder data. Consequently, you'll have to comply with all eligible PCI DSS requirements, because these functions are not outsourced to Adyen. **Validation document and requirements:** To mitigate the risks associated with this integration, Adyen requires that you assess your PCI DSS compliance according to *Self-Assessment Questionnaire D* (*SAQ D*), the most extensive form of self-certification. Because SAQ D is the default catch-all SAQ, there may still be parts of it that are not applicable to your environment. We recommend that you ensure that you have sufficient resource and capacity to handle this level of security. **ASV Network Scan:** Because your network is included or connected to the cardholder data environment, you are also required to perform *quarterly* external vulnerability network scans. This scan has to be performed by an [Approved Scanning Vendor](https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors) ([ASV](#ASV)). The scans are conducted over the internet, as a remote service and do not require on-site presence to execute. [\* Approved Scanning Vendors Program Guide](https://www.pcisecuritystandards.org/documents/ASV_Program_Guide_v3.0.pdf) ### Tab: Client-Side Encryption ### JSON Web Encryption (JWE) Use a third-party JWE library to encrypt card details client-side. **Required document:** * [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) You must make sure that you have [eligibility for SAQ A](/development-resources/pci-dss-compliance-guide/saq-a-eligibility). **Integration:** You generate the payment form on your website where shoppers submit their payment details. Cardholder data is encrypted on your shopper's browser using a third-party JWE library, sent to your server, and then transmitted to Adyen. **Possible risks | Medium:** Because you provide the payment form, your systems are in scope for additional PCI DSS controls. The chances of your system being compromised when using Adyen's CSE integration are potentially higher because you serve the payment form to your shopper. Malicious actors could potentially change your self-hosted CSE JavaScript library and steal your shopper's cardholder data. **Mitigating the risks:** The risks associated with this integration can be significantly reduced by making sure you apply mandatory PCI DSS controls, such as not using vendor-supplied usernames and passwords, patching software as soon as released, software being developed addressing vulnerabilities, and more. **Validation document and requirements:** Although a JWE integration carries more risks than Pay by Link, Drop in, and Components, the integration could still be scoped on the Self Assessment Questionnaire A (SAQ A) for PCI DSS compliance because once encrypted, you cannot decrypt the data. ### Client-side encryption library **The Client-Side Encryption (CSE) Web integrations are being phased out**\ This means we are: * No longer developing the CSE integration. * Not accepting new CSE integrations. Switch to one of our latest [Web integrations](/online-payments/build-your-integration/sessions-flow?platform=Web), to accept payments on your website. Mobile integrations aren't affected. To comply with PCI v4.0.1, you must make a modification to your integration to [implement Subresource Integrity](/online-payments/classic-integrations/classic-api-integration/client-side-encryption#client-side). **Required document:** * [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) You must make sure that you have [eligibility for SAQ A](/development-resources/pci-dss-compliance-guide/saq-a-eligibility) **Integration**: You generate the payment form on your website where shoppers submit their payment details. Cardholder data is encrypted on your shopper's browser, sent to your server, and then transmitted to Adyen. The CSE solution works with a JavaScript library, which can be hosted by either yourself or Adyen. **Possible risks | Medium:** Because you provide the payment form and you can host the CSE library, your systems are in scope for additional PCI DSS controls. The chances of your system being compromised when using Adyen's CSE integration are potentially higher because you serve the payment form to your shopper. Malicious actors could potentially change your self-hosted CSE JavaScript library and steal your shopper's cardholder data. **Mitigating the risks**:The risks associated with this integration can be significantly reduced by making sure vendor-supplied usernames and passwords are not used within your environment, software is patched as soon as released, and strong passwords and unique user IDs are used. **Validation document and requirements**: Although a CSE integration carries more risks than Pay by Link, Drop-in, and Components, Adyen only requires you to complete Self-Assessment *Questionnaire A* (*SAQ A*) for PCI DSS compliance because you cannot decrypt cardholder data. ### Additional reading * [Infographic - Strong Passwords](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Strong-Passwords.pdf?agreement=true\&time=1565256423488) * [Infographic - Patching](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Patching.pdf?agreement=true\&time=1565256423505) * [Best Practices for Securing E-commerce](https://www.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf?agreement=true\&time=1565342137625) ## Mobile in-app online payments integration Select how you implemented your [iOS](/online-payments/ios) or [Android](/online-payments/android) integration below to learn which PCI DSS requirements you must comply with and the corresponding documentation that you should provide: ### Tab: Drop-in or Components **Required documents:** * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) You must make sure that you have [eligibility for SAQ A](/development-resources/pci-dss-compliance-guide/saq-a-eligibility). **Integration:** Your app generates the payment form using Adyen's Drop-in or Components solution, and the shopper submits their payment details. Cardholder data is encrypted in the app, sent to your server, and then transmitted to Adyen. The Drop-in or Components solution works with a native library, which is embedded in your mobile app. **Possible risks | Low:** Because the Drop-in and Components native library is implemented in your app and not on a public website, the risks associated with your integration are considerably low. While malicious actors are not able to target the majority of your app users since the app runs on individual devices, they still could potentially target security vulnerabilities of a specific mobile device. **Mitigating the risks:** The risks associated with this integration can be significantly reduced by doing the following: * Making sure vendor-supplied usernames and passwords are not used within your environment. * Actively monitoring industry sources for vulnerability information and patching software according to the risk ranking of identified vulnerabilities. * Using unique user IDs and requiring strong passwords of at least 12 characters. * Implementing a security policy that includes an incident response plan and defines information security roles and responsibilities for all personnel. * Performing external vulnerability scans every 3 months. This is a new requirement in PCI DSS v4.0.1. **Validation document and requirements:** Adyen requires that you assess your PCI DSS compliance according to the following requirements of the Self-Assessment Questionnaire A (SAQ A): * PCI DSS v4.0.1: Requirements 2, 6, 8, 11, and 12. ### Additional reading * [Infographic - Strong Passwords](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Strong-Passwords.pdf?agreement=true\&time=1565256423488) * [Infographic - Patching](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Patching.pdf?agreement=true\&time=1565256423505) * [Best Practices for Securing E-commerce](https://www.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf?agreement=true\&time=1565342137625) ### Tab: API only Required document: * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire D](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-D-Merchant.pdf) **Integration:** You build your own UI and use only our APIs. This integration is commonly used when you want to be in full control of the payment flow. The payment form is hosted, served, and controlled by you. You receive cardholder data through the app - which can be optionally stored - and then you send the raw card data to Adyen over Transport Layer Security (TLS 1.2), according to PCI DSS requirements. **Possible risks | Medium:** This integration requires a wider PCI DSS scope as your system receives, transmits, and potentially stores and processes cardholder data—giving you full control of the payment flow and the payment data. While malicious actors are not able to target the majority of your app users since the app runs on individual devices, a malicious actor that successfully compromises your systems will still potentially be able to access large amounts of cardholder data. **Mitigating the risks:** The risks associated with this integration are considered higher, since you are completely in control over the collection, transmission, and optional storage of cardholder data. Consequently, you'll have to comply with all eligible PCI DSS requirements, because these cardholder data functions are not outsourced to Adyen. **Validation document and requirements:** To mitigate the risks associated with this integration, Adyen requires that you assess your compliance using a *Self-Assessment Questionnaire D (SAQ D)*, the most extensive form of self-certification. Because SAQ D is the default catch-all SAQ, there may still be parts of it that aren't applicable to your environment. We recommend that you ensure that you have sufficient resources and capacity in order to handle this level of security. ### Additional reading * [Infographic - Strong Passwords](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Strong-Passwords.pdf?agreement=true\&time=1565256423488) * [Infographic - Patching](https://www.pcisecuritystandards.org/documents/Payment-Data-Security-Essential-Patching.pdf?agreement=true\&time=1565256423505) * [Best Practices for Securing E-commerce](https://www.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf?agreement=true\&time=1565342137625) ## In-person payments integration When implementing an [in-person payments](/point-of-sale) integration, you have the option to use payment terminals with either our default End-to-End Encryption (E2EE), or Point-to-Point Encryption (P2PE). Select the encryption standard below to learn about the PCI DSS requirements you must comply with and the corresponding documentation that you should provide. ### Tab: E2EE If you are using our [in-person payments](/point-of-sale) integration, you only have to provide Adyen with *Self-Assessment Questionnaire B-IP* if you process over 1 million card-present transactions annually. Required document: * PCI DSS v4.0.1: [v4.0 Self-Assessment Questionnaire B-IP](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-B-IP.pdf) **Integration:** The payment terminals provided by Adyen are all [PTS-approved ](https://www.pcisecuritystandards.org/assessors_and_solutions/pin_transaction_devices)Point-of-Interaction ([POI](#POI)) devices. Adyen's [in-person payments integration](/point-of-sale) has been designed to reduce your PCI DSS scope as much as possible through End-to-End Encryption (E2EE). None of your systems, including your POS system, receive cardholder data in unencrypted forms. **Possible risks | Low:** Adyen ensures End-to-End Encryption and is responsible for the security of your shoppers' cardholder data as soon as we receive the data through the payment terminal. The risks for in-person payments integrations are related to the physical security of the payment terminal. Malicious actors can tamper with or replace payment terminals. **Mitigating the risks**: Risks associated with this integration, such as skimming attacks, can be significantly reduced by doing the following: * Implementing policies and procedures to periodically inspect the security of the payment terminals, to confirm that they have not been tampered with and that tamper-evident security packing tape or seals have not been broken. * Actively monitoring industry sources for vulnerability information and patching software according to the risk ranking of the spotted vulnerabilities. This applies only if you [update your terminals manually](/point-of-sale/release-updating/#manual-updating). * Implementing a security policy which defines information security roles and responsibilities for all personnel. * Engaging and maintaining a relationship with only PCI DSS compliant third-party service providers. **Validation document and requirements:** Adyen requires you to assess your PCI DSS compliance along with any other requirements that might apply to your environment with the following requirements from the *Self-Assessment Questionnaire B-IP* (*SAQ B-IP*): * PCI DSS v4.0.1: Requirements 9.1, 9.5, and 12. ### Additional reading * [Best Practices for Merchants: Skimming Prevention](https://www.pcisecuritystandards.org/documents/Skimming_Prevention_BP_for_Merchants_Sept2014.pdf?agreement=true\&time=1574264409741) * [Comparing Adyen's E2EE and P2PE solutions](/development-resources/e2ee-p2pe-comparison) ### Tab: P2PE If you are using our [in-person payments](/point-of-sale) integration with Point-to-Point Encryption (P2PE), you are required to implement all the requirements in the [P2PE Instruction Manual (PIM)](https://www.adyen.com/legal/p2pe-instruction-manual). Required document: * PCI DSS v4.0.1: [v4.0.1 Self-Assessment Questionnaire P2PE](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-P2PE.pdf) **Integration:** The payment terminals provided by Adyen are all validated and listed P2PE-approved solutions. The cardholder data is encrypted from the point of interaction until it reaches Adyen's secure decryption environment, ensuring that you do not have access to clear-text cardholder data on any systems. **Possible risks | Low:** Adyen ensures P2PE and is responsible for the security of your shopper's cardholder data as soon as we receive the data through the payment terminal. The risks for in-person payments integrations are related to the physical security of the payment terminal. Malicious actors can tamper with or replace payment terminals. **Mitigating the risks**: Risks associated with this integration, such as skimming attacks, can be significantly reduced by doing the following: * Implementing policies and procedures to periodically inspect the security of the payment terminals, to confirm that they have not been tampered with and that tamper-evident security packing tape or seals have not been broken. * Actively monitoring industry sources for vulnerability information and patching software according to the risk ranking of the spotted vulnerabilities. This applies only if you [update your terminals manually](/point-of-sale/release-updating/#manual-updating). * Implementing a security policy which defines information security roles and responsibilities for all personnel. * Engaging and maintaining a relationship with only PCI DSS compliant third-party service providers. **Validation document and requirements:** Adyen requires you to assess your PCI DSS compliance according to the requirements in the Self-Assessment Questionnaire P2PE (SAQ P2PE): * PCI DSS v4.0.1: Requirements 9.1, 9.5, and 12. You are also required to implement all requirements in the P2PE Instruction Manual (PIM). ### Additional reading * [P2PE FAQs](https://docs-prv.pcisecuritystandards.org/P2PE/Standard/PCI-P2PE-v3.x-Technical-FAQs-04Dec2024.pdf) * [P2PE Security Program Guide](https://docs-prv.pcisecuritystandards.org/P2PE/Program%20Documents/PCI-P2PE-Program-Guide-v3.1.pdf) * [P2PE Security Requirements and Testing Procedures](https://www.pcisecuritystandards.org/documents/P2PE_v3.0_Standard.pdf) ## Service Providers Because Adyen processes your payments, Adyen is regarded as a *Service Provider*. Merchants will often engage with a number of different service providers for a variety of reasons. For example, you could engage a service provider to perform recurring payments, provide shopping cart solutions, or to facilitate subscription billing. By using service providers, you are transferring parts of your PCI DSS obligations towards them. To carry out outsourced functions, service providers need access to your shoppers' cardholder data, making their PCI DSS compliance vital. When engaging a service provider, you are responsible for: * Making sure that the service provider is PCI DSS-compliant regardless of the type of service they are providing. * Identifying the functions each service provider is performing. * Ensuring that the service providers acknowledge their PCI DSS responsibilities. Adyen has a trusted list of partners, which includes: Zuora, VTEX, and Recurly. Refer to [Adyen's partner page](https://www.adyen.com/partners/network) for our complete list of partners. ### Requirements when using a Service Provider If you are using a Service Provider who has access to your shoppers' cardholder data, you are outsourcing part of your PCI DSS responsibilities. You are required to: 1. Ask your service provider for their [Service Provider's Attestation of Compliance](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-AOC-ServiceProviders.pdf). 2. Make sure that the service provider is registered with the schemes and is listed on [Visa's Global Registry of Service Providers](https://usa.visa.com/splisting/splistingindex.html) and [Mastercard's Compliant Service Provider List](https://www.mastercard.us/en-us/merchants/safety-security/security-recommendations/service-providers-need-to-know.html). After you have collected your Service Provider's AoC and verified that they are registered with the schemes, you then need to provide Adyen with: 1. Names of the service providers, along with the corresponding outsourced functions, clearly stated in part 2F of your Self-Assessment Questionnaire (SAQ) or Attestation of Compliance (AoC). 2. The [Service Provider's Attestation of Compliance](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-AOC-ServiceProviders.pdf). The use of service providers does not relieve you of the ultimate responsibility for your own PCI DSS compliance. You must manage the relationship with the service provider as described in **PCI DSS requirement 12.8**, including listing all the service providers you use, maintaining agreements and acknowledgement of responsibilities, carrying out due diligence prior to engagement, and monitoring the service provider's PCI DSS compliance status (by requesting their AoC every year). ## PCI DSS Glossary * AOC – [Attestation of Compliance](https://www.pcisecuritystandards.org/document_library?category=saqs\&subcategory=saqs_saq_aoc) - A form to attest the results of a PCI DSS assessment, as documented in a Self-Assessment Questionnaire (SAQ) or Report on Compliance (RoC).[]() * ASV – [Approved Scanning Vendor](https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors) - A company approved by the PCI SSC to conduct external vulnerability network scanning services.[]() * CDE – Cardholder Data Environment - The people, processes and technology that collect, store, process or transmit cardholder data.[]() * CHD – Cardholder data - At minimum, cardholder data consist of the full PAN (Personal Account Number), optionally accompanied by the cardholder name, expiration date and/or service code. * PCI DSS – [Payment Card Industry Data Security Standards](https://www.pcisecuritystandards.org/documents/PCI_DSS_v3-2-1.pdf?agreement=true\&time=1577114024374).[]() * PCI SSC – [Payment Card Industry Security Standards Council](https://www.pcisecuritystandards.org/).[]() * POI - Point of Interaction - The initial point where cardholder data is read from a card, typically a payment terminal.[]() * PTS - [PIN Transaction Security](https://www.pcisecuritystandards.org/assessors_and_solutions/pin_transaction_devices) - PTS is a set of modular evaluation requirements managed by PCI Security Standards Council, for PIN acceptance POI terminals * QSA – [Qualified Security Assessor](https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors) - A company which is qualified by the PCI SSC to perform PCI DSS onsite assessments.[]() * RoC – [Report on Compliance](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-ROC-Reporting-Template.pdf?agreement=true\&time=1577114091639) - Report documenting detailed results from an entity's PCI DSS assessment.[]() * SAD – Sensitive Authentication Data - Security-related information used for authentication or authorization. SAD may refer to the 3- or 4-digit values on a card used to verify card-not-present transactions such as CAV2, CVC2, CID and CVV2. * SAQ – [Self Assessment Questionnaire](https://www.pcisecuritystandards.org/document_library?category=saqs#results) - Reporting tool used to document self-assessment results from an entity's PCI DSS assessment.[]() * TLS - Transport Layer Security - A network communications protocol designed with the goal of providing data secrecy and data integrity between two communicating applications. TLS is successor of SSL. ## See also * [PCI compliance levels](/development-resources/pci-dss-compliance-guide/merchant-levels) * [Engaging a Qualified Security Assessor](/development-resources/pci-dss-compliance-guide/pci-with-qsa) * [PCI DSS FAQs](https://help.adyen.com/knowledge/compliance/pci-dss-compliance) * [Mastercard's Compliant Service Provider List](https://www.mastercard.us/en-us/merchants/safety-security/security-recommendations/service-providers-need-to-know.html) * [Visa's Global Registry of Service Providers](https://usa.visa.com/splisting/splistingindex.html) --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide/merchant-levels.md Section: Development resources Title: PCI compliance levels Description: Know your current PCI level to determine the validation requirements for PCI DSS compliance. --- title: "PCI compliance levels" description: "Know your current PCI level to determine the validation requirements for PCI DSS compliance." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/merchant-levels" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/merchant-levels.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/merchant-levels" last_modified: "2020-02-24T11:06:00+01:00" language: "en" --- # PCI compliance levels Know your current PCI level to determine the validation requirements for PCI DSS compliance. [View source](/development-resources/pci-dss-compliance-guide/merchant-levels.md) If you are accepting card payments, you need to validate your PCI DSS compliance annually. The validation requirements that you should use to assess your compliance depends on your PCI compliance level. The PCI compliance level is determined by the number of transactions processed over a 12-month period, per acquiring region, per scheme. ## Validation requirements The validation requirements are stated in either: * A Self-Assessment Questionnaire (SAQ). * A Report on Compliance (RoC). The assessment must be completed by an external Qualified Security Assessor (QSA) or your internal security resource. If you let an Internal Security Assessor (ISA) assess your environment, you must ensure that they complete the PCI SSC ISA training and pass the annual ISA accreditation program. When using an RoC, submit only the summary of the assessment results to Adyen. This summary report is called *Attestation of Compliance (AoC)*. Because the RoC contains detailed information about the technical infrastructure of your cardholder data environment, you should never share the full RoC with Adyen. The requirements are the same for both SAQ and RoC, and the same assessment is performed. The only difference is that you complete the SAQ on your own, while the RoC is completed by a QSA or your internal security resource. Depending on your integration, you may also need to provide: * A Quarterly Network Scan performed by an Approved Scanning Vendor (ASV) ## Determine your PCI compliance level Refer to the table below for the criteria and validation requirements for each PCI compliance level. | PCI compliance level | Criteria | Validation requirements | | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -- | ------------------------------------------------------------------------------------------- | ---------------------------------- | | | | ROC | or | SAQ | Network scan | | Level 1 | You process over 6 million transactions annually per acquiring region, per scheme or if you have previously experienced a breach that resulted in an Account Data Compromise (ADC) Event. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Optional, depending on integration | | Level 2 | You process between 1 to 6 million transactions annually per acquiring region, per scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Optional, depending on integration | | Level 3 | You process between 20,000 to 1 million transactions annually per acquiring region, per scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Optional, depending on integration | | Level 4 | You process less than 20,000 transactions annually per acquiring region, per scheme. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Optional, depending on integration | ## See also * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) * [Engaging a Qualified Security Assessor](/development-resources/pci-dss-compliance-guide/pci-with-qsa) * [Self-Assessment Questionnaires (SAQ)](https://www.pcisecuritystandards.org/document_library?category=saqs#results) * [Report on Compliance (RoC)](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-ROC-Reporting-Template.pdf) * [Approved Scanning Vendors](https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors) --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide/pci-with-qsa.md Section: Development resources Title: Engaging a Qualified Security Assessor Description: Learn more about complying with PCI DSS with the help of a QSA. --- title: "Engaging a Qualified Security Assessor" description: "Learn more about complying with PCI DSS with the help of a QSA." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/pci-with-qsa" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/pci-with-qsa.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/pci-with-qsa" last_modified: "2020-02-24T11:06:00+01:00" language: "en" --- # Engaging a Qualified Security Assessor Learn more about complying with PCI DSS with the help of a QSA. [View source](/development-resources/pci-dss-compliance-guide/pci-with-qsa.md) ##### First time Level 1 Consider engaging a QSA if you are migrating from a Level 2 to a Level 1 PCI compliance status. If your [PCI compliance level](/development-resources/pci-dss-compliance-guide/merchant-levels) is **Level 1**, the compliance assessment must be done either by an external Qualified Security Assessor (QSA), or by your own Internal Security Assessor (ISA). If you choose to use your internal security resource, you must ensure that they complete the PCI SSC ISA training and pass the annual ISA accreditation program. If you choose to use a QSA and have not engaged one yet, refer to the [list of PCI SSC-approved Qualified Security Assessors](https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors). ## Assessment process by a QSA 1. **Gap analysis** The QSA performs an initial gap analysis of your PCI DSS compliance status. The analysis shows what controls you already have in place and what still needs to be implemented in order to be fully PCI DSS compliant. The QSA then shares feedback and remediation checklist items, with detailed insights of what is required. 2. **On-site assessment** The QSA performs an on-site assessment to determine how your payments security currently stands. The QSA visits your location, conducts multiple interviews, and collects evidence related to your current PCI DSS compliance status. Both technical and operational components of the business are evaluated according to PCI DSS. 3. **Remediation assistance** After the onsite assessment has been completed, your QSA provides initial feedback on your compliance status and the required remediation steps. Your QSA explains areas of non-compliance, provides guidance on how you can become compliant, and gives advice on retesting procedures. If corrective actions to address the identified issues are performed, and the requirements were reassessed during the assessment, you must document this in **Items Noted For Improvement** (INFI). 4. **Completing the Report on Compliance (RoC)** When you meet all the eligible PCI DSS requirements and the audit is complete, your QSA writes your PCI DSS compliance status in a Report on Compliance (RoC). After this document has been reviewed and finalized, your QSA provides an Attestation of Compliance (AoC), which is a summary of the results of the assessment. You should submit the AoC to Adyen. Because the ROC contains detailed information about the technical infrastructure of your cardholder data environment, you should never share the full ROC with Adyen. You should submit only your AOC. ## See also * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) * [PCI compliance levels](/development-resources/pci-dss-compliance-guide/merchant-levels) --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide/saq-a-eligibility.md Section: Development resources Title: Self-Assessment Questionnaire A eligibility Description: Determine if you are eligible for SAQ A, and learn about changed PCI DSS script security requirements for SAQ A. --- title: "Self-Assessment Questionnaire A eligibility" description: "Determine if you are eligible for SAQ A, and learn about changed PCI DSS script security requirements for SAQ A." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/saq-a-eligibility" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/saq-a-eligibility.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/saq-a-eligibility" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Self-Assessment Questionnaire A eligibility Determine if you are eligible for SAQ A, and learn about changed PCI DSS script security requirements for SAQ A. [View source](/development-resources/pci-dss-compliance-guide/saq-a-eligibility.md) This page provides information about determining if you are eligible to demonstrate the Payment Card Industry Data Security Standard (PCI DSS) compliance of your online payments integration through a Self-Assessment Questionnaire A (SAQ A). If you have previously submitted SAQ A documents, note that the PCI Security Standards Council (PCI SSC) has [removed some of the script security requirements](#changes), making it easier to be eligible for SAQ A. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for online payments integrations. | ## Eligibility requirements In accordance with PCI DSS v4.0.1, to be eligible to use the SAQ A to attest the PCI DSS compliance of your online payments integration, you must: * Confirm that all elements of the payment pages and forms delivered to the customer’s browser originate only and directly from a PCI DSS compliant Third-Party Service Provider (TPSP) or payment processor. * Confirm your site is not susceptible to attacks from scripts that could affect your e-commerce systems. This means that most of the responsibility for these controls belongs to the TPSPs or payment processors. However, as a SAQ A merchant you must ensure that the payment page elements and scripts that are loaded from your providers through different integrations are PCI DSS compliant, and apply security measures to protect from script attacks. For example, SAQ A requirement 11.3.2 mandates regular [vulnerability scans](/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation). You can [download the SAQ A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) from the PCI site. ## How Adyen can help To help you attest to the eligibility requirements for SAQ A, Adyen provides assurance for the security of its products through Adyen's annual PCI DSS Attestation of Compliance (AoC). In addition, we provide information about: * Security measures for the specific integrations you implement in our [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide/#online-payments). * [Vulnerability scanning](/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation) of your Adyen online payments integration to comply with SAQ A requirement 11.3.2. ## Changes to the SAQ A requirements In response to industry feedback, and because of the complexity of implementing new ecommerce security controls, in 2025 the PCI DSS has [updated the SAQ A eligibility criteria](https://blog.pcisecuritystandards.org/important-updates-announced-for-merchants-validating-to-self-assessment-questionnaire-a). In the new PCI DSS v4.0.1 standard, the following PCI DSS SAQ A requirements have been removed: * PCI DSS requirement 6.4.3, about payment page scripts. * PCI DSS requirement 11.6.1, about change- and tamper-detection mechanisms. [Requirements 6.4.3 and 11.6.1](/online-payments/script-security-compliance) remain applicable to merchants that are required to submit PCI DSS Self-Assessment Questionnaire D (SAQ D) and merchants that are required to present an Attestation of Compliance (AoC) for onsite assessment. The new SAQ A version has gone into effect on March 31, 2025, which is when the PCI DSS v4.0.1 requirements have also gone into effect. ## See also * [Download the SAQ A](https://docs-prv.pcisecuritystandards.org/SAQ%20\(Assessment\)/SAQ/PCI-DSS-v4-0-1-SAQ-A.pdf) * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) * [Vulnerability scanning for SAQ A](/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation) --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide/script-security.md Section: Development resources Title: Script security for ecommerce Description: Implement script security on your ecommerce payment page to comply with PCI DSS v4.0.1 requirements. --- title: "Script security for ecommerce" description: "Implement script security on your ecommerce payment page to comply with PCI DSS v4.0.1 requirements." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/script-security" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/script-security.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/script-security" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Script security for ecommerce Implement script security on your ecommerce payment page to comply with PCI DSS v4.0.1 requirements. [View source](/development-resources/pci-dss-compliance-guide/script-security.md) PCI DSS v4.0.1 includes requirements for merchants to manage the risks associated with the scripts and [iframe elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) loaded into their ecommerce payment pages. These requirements are for Web online payments integrations. This page gives a brief overview of the specific PCI DSS v4.0.1 requirements related to script security, and provides recommendations for how to comply with these requirements. When creating these recommendations, Adyen considered implementations advised by the [PCI Security Standards Council (PCI SSC)](https://www.pcisecuritystandards.org/) in their formal guidance document: [Payment Page Security and Preventing E-Skimming - Guidance for PCI DSS Requirements 6.4.3 and 11.6.1](https://blog.pcisecuritystandards.org/new-information-supplement-payment-page-security-and-preventing-e-skimming). ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant if any of the following apply to you:- You complete the Self-Assessment Questionnaire D (SAQ D). - You complete an Attestation of Compliance (AoC) for Onsite Assessment. - You are an Adyen for Platforms partner. - You are a partner that implements Adyen plugins. | | **Limitations** | The information on this page does **not apply** if you are [eligible for Self-Assessment Questionnaire A (SAQ A)](/development-resources/pci-dss-compliance-guide/saq-a-eligibility). | ## PCI DSS requirement 6.4.3 Requirement 6.4.3 mandates that all payment page scripts that are loaded and executed in the consumer’s browser are managed as follows: * A method is implemented to confirm that each script is authorized. * A method is implemented to assure the integrity of each script. * An inventory of all scripts is maintained with written justification as to why each is necessary. ### Exemption for 3D Secure authentication scripts In a typical 3D Secure implementation, the 3D Secure server fetches and stores URLs for scripts from an [EMV 3DS](https://www.emvco.com/emv-technologies/3-d-secure/) Access Control Server (ACS), EMV 3DS Directory Server (DS), or services connected to the ACS or DS, on behalf of an issuer or payment network. During checkout, your website shows a web page with an iframe using a URL provided by the EMV 3DS server with an applicable script to support 3D Secure functionality. The 3D Secure script validation process is exempted from the scope of PCI DSS requirement 6.4.3, because the trust relationship with the 3D Secure service provider is established through due diligence, onboarding, and business agreements of the entities involved. ## PCI DSS requirement 11.6.1 Requirement 11.6.1 mandates that a change- and tamper-detection mechanism is deployed as follows: * It alerts personnel about unauthorized modification (including indicators of compromise, changes, additions, and deletions) to the security impacting HTTP headers and the script contents of payment pages, as received by the consumer browser's [Document Object Model (DOM)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) throughout the payment process. * It evaluates the received HTTP headers and payment pages. * Any unauthorized changes must be investigated and resolved promptly. ## Implement a Content Security Policy for requirement 6.4.3 To comply with PCI DSS requirement 6.4.3, we recommend that you implement a [Content Security Policy (CSP)](https://en.wikipedia.org/wiki/Content_Security_Policy) on your payment page to authorize and assure the integrity of scripts. A CSP allows you to authorize scripts before loading them on your page. You can modify the CSP in your page header to do the following: * Allow all internally-loaded scripts by default. * Expressly allow scripts from non-internal domains to be loaded. Additionally, we provide guidance on the options for reporting and alerting from your implemented CSP. To ensure the integrity of scripts, we recommend implementing [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) to confirm that the files you load from Adyen have not been manipulated or tampered with by malicious actors. To build a CSP, consider the following recommendations: * [Use a report-only CSP HTTP header](#report-only-header). * [Allow scripts an iframes from external sources](#allow-external-sources). * [Create an inventory of scripts](#scripts-inventory). * [Check the integrity of scripts](#scripts-integrity). ### Use a report-only CSP HTTP header This type of header causes no issues with how your integration works because it does not block any resources from loading. By using the `Content-Security-Policy-Report-Only` header instead of the `Content-Security-Policy` header, the browser only logs the violation. It does not block any content from being loaded. Add the following HTTP header to your page. **Report-only header** ```bash Content-Security-Policy-Report-Only: default-src 'self'; font-src 'self'; img-src 'self'; script-src 'self'; style-src 'self' ``` After you implement it, you can see the violations that show up when visiting your website. The report-only policy shows you the following. | Field | Description | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | `default-src` | This [CSP directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) tells the browser which domains or subdomains scripts may be loaded from. In all of our examples, we use **'self'** as a trusted source, telling the browser to only load resources that are hosted on the same domain or subdomain. If sources are not defined in any other directives, they apply this default policy. | | | `font-src` | What fonts may be loaded. | | | `img-src` | What images may be loaded. | | | `script-src` | What scripts may be loaded. | | | `style-src` | What styles/css may be loaded. | | ### Allow scripts and iframes from external sources Your CSP header can allow either of the following: * Anything, like images, scripts, media, and more, to be loaded from an external domain or subdomain. * Only things that you specify to be loaded from an external domain or subdomain. We recommend that you implement the following blocking policy. 1. Change the header to `Content-Security-Policy`. This is a blocking policy. You can add some defined exemptions. 2. Allow specific domains and subdomains. When you define specific sources for scripts (`script-src`) and iframes (`frame-src`) they only allow loading resources from the specified domains, and everything else is blocked. For Adyen integrations, we recommend that you apply the following CSP configuration: **Recommended CSP configuration** ```bash Content-Security-Policy: default-src 'self'; script-src: *.adyen.com pay.google.com *.payments-amazon.com *.paypal.com *.ratepay.com *.cash.app font-src: cash-f.squarecdn.com style-src: *.cash.app frame-src: * img-src: * connect-src:* form-action:* ``` If you have other third party integrations loading additional scripts, you must explicitly add them to the `script-src` directive. Scripts and images that are loaded from other domains violate this policy and are included in the [report that you configure for the CSP](#report). We suggest that you use the wildcard (\*) for the iframe elements in this policy, for the following reasons: * Adyen loads only 3D Secure (3DS) authentication iframes. According to the PCI SSC, the 3DS script validation process is exempted from the scope of PCI DSS Requirement 6.4.3, because the trust relationship with the 3DS service provider is established through due diligence, onboarding, and business agreements of the entities involved. Because it is not possible to list all issuer domains loading iframes for 3DS authentication, a more stringent CSP might block 3DS iframes from loading. * Not using any `frame-src` definition might be functional but not stable. It would lead the CSP to use the default value, which is usually defined as blocking **none**. Therefore, some definition needs to be made. With our recommended CSP header setup, we make it possible to use CSP, but still allow loading all 3DS iframes which are exempted from the requirements. * This recommended implementation could allow any iframes to be loaded. However, iframes from Adyen are [sandboxed](https://en.wikipedia.org/wiki/Sandbox_\(computer_security\)) and iframes that come from 3DS issuer banks are also sandboxed. By sandboxing, issues such as [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) are prevented, not adding any additional risk. Web [Browser Sandboxing](https://www.geeksforgeeks.org/what-is-browser-sandboxing/) allows running web applications in isolation to prevent browser-based malware from spreading to the rest of the webpage or network. Most modern browsers already have a sandbox by default to enhance the protection of the user's computer. ### Create an inventory of scripts Following PCI DSS Requirement 6.4.3, all scripts added to your page must be in an inventory. This means that you must keep a list, including the ones required for Adyen integrations, with the business reason to use them. Furthermore, you must have a simple periodical authorization sign-off. Ensuring that all scripts have been explicitly authorized reduces the risk of unnecessary scripts being added to the payment page without appropriate approval. However, for some cases, it can be impractical for such authorization to occur before a script is changed or a new script is loaded to the page. In these cases, the authorization should be confirmed as soon as a [change is reported](#report). Adyen loads scripts from the following domain sources. Include them in your inventory for your Adyen integration: | Source | Description | | ---------------------- | -------------------------------------------------------------------------------------- | | \*.adyen.com | Adyen-authorized domain for scripts loaded for payment-processing-associated services. | | pay.google.com | Allows integration with the Google Pay payment method. | | \*.payments-amazon.com | Allows integration with the Amazon Pay payment method. | | \*.paypal.com | Allows integration with the PayPal payment method. | | \*.ratepay.com | Allows integration with the Ratepay payment method. | | \*.cash.app | Allows integration with the Cash App service. | | \*.mastercard.com | Allows integration with Click to Pay using Mastercard. | | \*.visa.com | Allows integration with Click to Pay using Visa. | ### Check the integrity of scripts We recommend implementing Subresource Integrity (SRI) to ensure that the files you load from Adyen have not been manipulated or tampered with by malicious actors. Use the SRI hash by doing the following. 1. To the ` ``` ## Implement detection mechanisms for requirement 11.6.1 We recommend that you use your CSP implementation to comply with PCI DSS requirement 11.6.1. A functional CSP implementation can provide authorization and alerting in case of attempts to introduce unknown scripts or changes to currently authorized scripts. These events are considered valid alerts and "indicators of compromise" for the purpose of requirement 11.6.1. You must collect all CSP alerts in a practical manner. You can do this by implementing the [`report-to` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-to), which sends you a report of alerts. This can help to meet the requirements included in 11.6.1, such as "alerting personnel of unauthorized modification". []() 1. Create an endpoint on your server you want the browser to use for reporting CSP violations. If a CSP violation occurs, a report is generated. It contains a serialized [CSPViolationReportBody](https://developer.mozilla.org/en-US/docs/Web/API/CSPViolationReportBody) object instance. Using the mechanisms of the [Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API), the browser sends the report to your endpoint URL. 2. Specify the mapping between endpoint names and URLs by adding the [`Reporting-Endpoints` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints) to your CSP. You can use any name for your endpoints. **Example of Reporting-Endpoints response header** ```bash Reporting-Endpoints: your_endpoint_name="https://example.com/csp-reports" ``` 3. Add `report-to`, specifying the endpoint URL on your server that you want the browser to use for reporting CSP violations. **Example of report-to directive** ```bash report-to your_endpoint_name ``` 4. When a CSP violation occurs, you get a [report with CSP violations](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-to#violation_report_syntax). ## See also Have a look at the following PCI DSS resources: * [Important Updates Announced for Merchants Validating to Self-Assessment Questionnaire A](https://blog.pcisecuritystandards.org/important-updates-announced-for-merchants-validating-to-self-assessment-questionnaire-a) * [How does PCI DSS Requirement 6.4.3 apply to 3DS scripts called from a merchant check-out page as part of 3DS processing?](https://www.pcisecuritystandards.org/faq/articles/Frequently_Asked_Question/how-does-pci-dss-requirement-6-4-3-apply-to-3ds-scripts-called-from-a-merchant-check-out-page-as-part-of-3ds-processing/) --- # Source: https://docs.adyen.com/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation.md Section: Development resources Title: Vulnerability scanning for ecommerce Description: Engage a scanning vendor as required under SAQ-A to identify potential vulnerabilities. --- title: "Vulnerability scanning for ecommerce" description: "Engage a scanning vendor as required under SAQ-A to identify potential vulnerabilities." url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation" source_url: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation.md" canonical: "https://docs.adyen.com/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Vulnerability scanning for ecommerce Engage a scanning vendor as required under SAQ-A to identify potential vulnerabilities. [View source](/development-resources/pci-dss-compliance-guide/vulnerability-scanning-regulation.md) Vulnerability scanning is the process of identifying potential vulnerabilities in systems, software, and network devices, so that you can promptly address any vulnerabilities found. PCI DSS v4.0.1 Self-Assessment Questionnaire A (SAQ A) requirement 11.3.2 requires a vulnerability scan of your ecommerce system every quarter or whenever a significant change is made in the network or applications. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for online payments integrations. | ## Scope of the scan In the context of an online payments integration with Adyen, it is not necessary to scan your entire ecommerce system. The scope is limited to: * The **page from which Adyen components are loaded or that re-directs to an Adyen Pay by Link page**. * In an Adyen for Platforms environment, the platform or marketplace must ensure that on the platform or marketplace the Adyen-related page mentioned above passes the vulnerability scan. With that, the ecommerce environments of the users of the platform or marketplace automatically receive a passing scan. ## Scanning vendors and scanning steps The vulnerability scans must be done by an approved scanning vendor (ASV): a [company that is approved by PCI SSC](https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors/) to provide external vulnerability scanning tools and services. A scan by an AVS consists of several steps: * Scoping * Scanning * Initial report * Disputes * Rescanning * Final report In the disputes step you can dispute any findings from the initial report that you think are incorrect, such as false positives or findings relating to exemptions. After you have fixed any remaining issues, the in-scope part of your system is scanned again, and the final report is your proof that you have passed the scan. ## See also * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) --- # Source: https://docs.adyen.com/development-resources/raw-acquirer-responses.md Section: Development resources Title: Raw responses Description: Learn the meaning of raw acquirer responses. --- title: "Raw responses" description: "Learn the meaning of raw acquirer responses." url: "https://docs.adyen.com/development-resources/raw-acquirer-responses" source_url: "https://docs.adyen.com/development-resources/raw-acquirer-responses.md" canonical: "https://docs.adyen.com/development-resources/raw-acquirer-responses" last_modified: "2024-10-16T14:06:00+02:00" language: "en" --- # Raw responses Learn the meaning of raw acquirer responses. [View source](/development-resources/raw-acquirer-responses.md) ##### Point of Sale For an in-person payments integration, see the most common [raw responses that Terminal API returns](/point-of-sale/error-scenarios/raw-acquirer-responses/). When a card scheme or issuer declines a transaction, they send us a raw response to explain why. This is also known as the "raw acquirer response". The many raw responses are slightly different between schemes and are subject to change. For that reason, we map raw responses for failed transactions to a combination of a `resultCode` field with a value of **Refused** or **Cancelled**, and a `refusalReason` field explaining why the transaction did not succeed. If you want to receive the raw response in your API responses as well, you can enable that in your Customer Area. On this page, we describe the most common raw responses related to refused or canceled transactions. In the tables, **Journal type** refers to payment details in your Customer Area. ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------- | | **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. | | **Setup steps** | Before you begin, in your Customer Area [enable receiving raw responses](#receive-raw-responses). | ## Recommendations Take the following recommendations into account with regard to handling raw responses. * The raw response provides additional information about why the transaction failed. Be aware that card schemes and issuers sometimes change the text without notice. * To prevent the malicious use of data, you must not expose the details of raw responses to shoppers. ## Receive raw responses If you want to receive the raw response for declined transactions: 1. Log in to your [Customer Area](https://ca-test.adyen.com/) and switch to your merchant account. 2. Go to **Developers** > **Additional data**. 3. Select the **Raw acquirer result** checkbox. 4. Select **Save configuration**. When a payment request is declined, the `additionalData` of the response now includes: * `refusalReasonRaw`: the full raw response. For example: **51 : Insufficient funds/over credit limit**. * `refusalCodeRaw` (only available for Visa and Mastercard transactions through our own acquiring platform): the numeric part of the raw response. For example: **51**. This represents the underlying scenario that caused the transaction to fail. ### Tab: Example additional data with `refusalReasonRaw` `{ "additionalData": { "avsResultRaw": "Y", "cvcResultRaw": "M", "refusalReasonRaw": "51 : Insufficient funds/over credit limit", "acquirerCode": "TestPmmAcquirer", "acquirerReference": "ACQUIRER_REFERENCE", ... } Tab: Example for Visa and Mastercard with own acquiring { "additionalData": { "avsResultRaw": "Y", "cvcResultRaw": "M", "refusalReasonRaw": "51 : Insufficient funds/over credit limit", "refusalCodeRaw": "51", "acquirerCode": "TestPmmAcquirer", "acquirerReference": "ACQUIRER_REFERENCE", ... }` Note that we would map the raw response from this example to `refusalReason` **Not enough balance** and `resultCode` **Refused**. ## Visa and Mastercard raw responses These are the most common raw responses from Visa and Mastercard for refused or canceled transactions. If you use your own retry logic, you can use the raw response to help avoid Visa excessive retry fees. See [Mapping to Visa system integrity fee categories](/development-resources/raw-acquirer-responses/visa-integrity-fees). | Journal type | refusalReasonRaw | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorised | 00: Approved or completed successfully | The transaction was canceled after being initially approved by the issuer. This can be due to various reasons, for example, if the shopper returns goods after purchase. | | Refused | 01: Refer to card issuer | The transaction was refused by the card issuer. The shopper should contact their bank for clarification. The shopper can try again after resolving the issue with their bank, or use another payment method. | | Refused | 03: Invalid merchant | The transaction was refused by the card issuer. The shopper should contact their bank for clarification. The shopper can try again after resolving the issue with their bank, or use another payment method. | | Refused | 04: Pickup card | The card issuer requests to retain the card. This can be due to a suspected counterfeit or stolen card. This reason is used in an ecommerce environment although it originates from an in-person payments environment. | | Refused | 05: Do not honor | This is a generic refusal that has several possible causes. The shopper should contact their issuing bank for clarification. | | Error | 06: Error | Payment could not be authorized and resulted in an error. The shopper can try again or use another payment method. | | Refused | 07: Pickup card, special conditions | The card issuer requests to retain the card. This can be due to a suspected counterfeit or stolen card. | | Cancelled | 10: Partial approval | The transaction was canceled. Some card issuers support partial-approval authorization. This approves a part of the requested transaction, leaving the remainder to be paid with another form of tender. | | Refused | 12: Invalid transaction | The card issuer does not allow this type of transaction on this card/account. For example, the card is a fleet card for which this type of transaction is not permitted. | | Refused | 13: Invalid amount | The card issuer has declined the transaction because of an invalid format or field. This response usually occurs with Cirrus or Maestro Debit and Prepaid Cards or cards that are not allowed to do online purchases. The shopper should try again or use another payment method. | | Refused | 14: Invalid Account Number (No such Number) | The card issuer is unable to validate the card/account number. | | Refused | 15: No such issuer | The card number is not within a card number range supported by the scheme. | | Refused | 19: Re-enter transaction | Applies to Visa. The transaction cannot be processed temporarily. | | Error | 30: Format error | The card issuer does not recognize the transaction details being entered. This is due to a format error. The shopper should check the transaction information and try again. | | Refused | 34: Suspect fraud | Applies to Mastercard. The transaction is refused because the card issuer suspects this payment to be fraudulent. | | Refused | 41: Pickup card (lost card) | The card was reported as lost. Validate the shopper's authenticity and refer them to their bank. | | Refused | 43: Pickup card (stolen card) | The card was reported as stolen. Validate the shopper's authenticity and refer them to their bank. | | Refused | 46: Closed Account | Applies to Visa. The account is closed. Re-validate the account number for accuracy and do not reattempt with the same PAN or token. | | Refused | 51: Insufficient funds/over credit limit / Not sufficient funds | Insufficient funds in the cardholder's account. The shopper can try again after adding funds to their bank account, or use another payment method. | | Refused | 52: No checking account | Applies to Visa. The card does not have a checking account linked to it. The shopper can use another payment method. | | Refused | 54: Expired card | The card expiration date is in the past. The shopper should correct the date or use another payment method. | | Refused | 55: Invalid PIN | The shopper has entered an incorrect PIN. The shopper should re-enter their PIN or use another payment method. | | Refused | 57: Transaction not permitted to cardholder | The card issuer does not permit the transaction on this card/account. The shopper can use another payment method. For activation or loading of prepaid cards, the Merchant, acquirer BIN, and issuer BIN are not all domestic. | | Refused | 58: Transaction not permitted to acquirer/terminal | Card issuer does not permit the transaction on this card/account. Shopper can use another payment method or contact their bank. | | Refused | 59: Suspected fraud | The transaction is refused because the card issuer suspects this payment to be fraudulent. | | Refused | 61: Exceeds withdrawal amount limit(s) / Withdrawal amount limit exceeded | The shopper has exceeded their card limit. The shopper can try again after resolving the issue with their bank, or use another payment method. | | Refused | 62: Restricted card | The card issuer has restricted where the card can be used. For example, because of embargoes. | | Refused | 63: Security violation | The card issuer indicated a security issue with this card. The shopper can use another payment method. Alternatively, the shopper can try again after they resolved the issue with their bank. | | Refused | 65: Exceeds withdrawal count limit / Withdrawal count limit exceeded | The shopper has exceeded their card usage frequency limit. The shopper can use another payment method or try again with the same card after the shopper took care of the card limit issue. | | Refused | 6P: Customer ID verification failed | Applies to Visa. Incorrect account verification (for example driving license number) related to Visa Direct. Not to be confused for cardholder verification method refusals such as CVV, for example. | | Refused | 65: Authentication required | Applies to Mastercard. Authentication is required for the transaction. If the transaction is in scope of PSD2 and did not go through 3D Secure, try again with 3D Secure. This is also referred to as a "Soft Decline". | | Refused | 70: Contact Card Issuer | Applies to Mastercard. The card issuer indicated an issue with this card and requests contact from the shopper. The shopper can use another payment method. Alternatively the shopper can try again after they resolved the issue with their bank. | | Refused | 70: PIN data required | Applies to Visa. The card issuer requests to use Secure Customer Authentication. Reattempt transaction with PIN. (European Region Only) | | Refused | 75: Allowable number of PIN tries exceeded | The shopper has entered an incorrect PIN more times than is allowed by the issuing bank. The shopper should try again or use another payment method. | | Refused | 78: Invalid/nonexistent account specified (general) | The transaction is from a new cardholder, and the card has not been properly unblocked. | | Refused | 79: Life Cycle | Applies to Mastercard. The transaction is refused due to invalid card data. View the [Merchant Advice Code](#mastercard-merchant-advice-codes) for follow-up action. | | Refused | 80: Credit issuer unavailable | The issuing bank cannot be contacted. The shopper should try again or use another payment method. | | Refused | 82: Policy | Applies to Mastercard. The transaction is refused due to a policy reason. View the [Merchant Advice Code](#mastercard-merchant-advice-codes) for follow-up action. | | Refused | 82: Negative online CAM, dCVV, iCVV, CVV, or CAVV results or Offline PIN authentication interrupted | Applies to Visa. The cardholder verification method failed for CAM, dCVV, iCVV, CVV or a service code for card present transactions. | | Refused | 83: Fraud / Security | Applies to Mastercard. The transaction is refused because the card issuer suspects this payment to be fraudulent. View the [Merchant Advice Code](#mastercard-merchant-advice-codes) for follow-up action. | | Authorised | 85: No reason to decline a request for account number verification, address verification, CVV2 verification, or a credit voucher or merchandise return | [Zero-value auth](/get-started-with-adyen/adyen-glossary/#zero-value-auth) request authorized. | | Authorised | 85: Not declined (Valid for all zero amount transactions) | [Zero-value auth](/get-started-with-adyen/adyen-glossary/#zero-value-auth) request authorized. | | Refused | 86: Cannot verify PIN | Applies to Visa. The PIN cannot be validated. If applicable, the transaction can be reattempted as a non-PIN transaction. | | Refused | 91: Authorization Platform or issuer system inoperative / Issuer not available | The issuing bank cannot be contacted. The shopper should try again or use another payment method. | | Error | 91: Issuer unavailable or switch inoperative | The issuer or issuer processor cannot authorize, for example because of downtime. | | Refused | 92: Destination cannot be found for routing / Unable to route transaction | The shopper is using a test card number on live. The shopper should use another payment method. | | Refused | 93: Transaction cannot be completed; violation of law | The issuing bank will not allow this transaction. The shopper should use another payment method. | | Refused | 96: System malfunction | The issuing bank cannot be contacted. The shopper should try again or use another payment method. | | Refused | 1A: Authentication Required | Applies to Visa. Authentication is required for the transaction. If the transaction is in scope of PSD2 and did not go through 3D Secure, try again with 3D Secure. This is also referred to as a "Soft Decline". | | Refused | 5C: Transaction not supported/blocked by issuer | Applies to Visa. The transaction was refused by the card issuer. The shopper can contact their bank or try with a different payment method. | | Refused | 9G: Blocked by cardholder/contact cardholder | Applies to Visa. The cardholder blocked this card. Ask the cardholder to use another payment method. | | Refused | R0: Stop payment order | Applies to Visa. The cardholder requested to stop a specific, single recurring payment transaction. Contact the shopper regarding cancellation of this transaction. | | Refused | R1: Revocation of authorization order | Applies to Visa. The cardholder requested to stop all recurring payment transactions. Contact the shopper regarding cancellation of all transactions. | | Refused | R3: Revocation of all authorization | Applies to Visa. All recurring payments have been canceled for the card number in the request. Contact the shopper regarding cancellation of all transactions. | | Refused | Z1: Offline-declined | Applies to Visa. Only used in non-cardholder requests such as advice. | | Refused | Z3: Unable to go online; offline-declined | Applies to Visa. Only used in non-cardholder requests such as advice. | | Error | N3: Cash service not available | Reserved for private use or Maximum online refund reached | | Error | N4: Cash request exceeds issuer limit | Reserved for private use or Maximum offline refund reached | | Declined | N7: Decline for CVV2 failure | Reserved for private use or Customer selected negative file reason | ## Adyen for Platforms raw responses Besides the issuer or card scheme, Adyen can also refuse a transaction if it fails a validation check in your balance platform. | Journal type | refusalReasonRaw | Description | | ------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Refused | 010: Insufficient funds in the source balance account | The transaction was refused by Adyen because there are insufficient funds in the balance account. | | Refused | 100 : Account holder misses required capabilities | The transaction was refused by Adyen because the account holder does not have the required capabilities. | | Refused | 101 : Account holder is not active | The transaction was refused by Adyen because the account holder is not in **active** [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/\(id\)#responses-200-status). | | Refused | 111 : Balance account is not active | The transaction was refused by Adyen because the balance account is not in **active** [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balanceAccounts/\(id\)#request-status). | | Refused | 121: Balance platform is not active | The transaction was refused by Adyen because your balance platform is not in **Active** [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balancePlatforms/\(id\)#responses-200-status). | | Error | 999: Unknown error | The transaction was refused by Adyen for unknown reasons. | ## Accel raw responses These are the raw responses from Accel for refused or canceled transactions. | Response Code | Description | | ------------- | ------------------------------------------ | | 214 | No account of type requested, capture card | ## Afterpay raw responses | Journal type | Raw Acquirer Response | Description | | ------------ | --------------------------------- | ----------------------------------------------------------------------- | | Refused | DECLINED : Payment rejected (402) | Afterpay declined the payment. | | Error | No response from ACM | Afterpay did not respond within 30 seconds which resulted in a timeout. | | Error | 500: Internal Error | Afterpay had an internal error. The shopper needs to try again later. | | Refused | INVALID\_AMOUNT | The transaction amount is above or below the limit for Afterpay. | ## Alipay raw responses | Journal type | Response | Description | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sentForSettle / SettledScheduled / settledExternally | trade\_status=TRADE\_FINISHED | The payment was successfully completed and you can expect to receive the funds. | | Refused | Field 'currency' is not valid. Reason: The provided currency is not supported. | The currency sent in the request does not match the country code. For example, sending **EUR** for Norway; the currency should be **NOK**. See supported currencies at [adyen.com](https://www.adyen.com/payment-methods/alipay). | | Refused | Payment details are not supported for this combination of country/region and MCC | The acquirer's risk rules blocked this transaction. There is usually a non-compliance issue in the payment details. | | Refused | 422: Invalid shopper interaction | The payment request includes the wrong `shopperInteraction`. For example, an Ecommerce merchant account sent a request with `shopperInteraction: POS`. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Refused | trade\_status=WAIT\_BUYER\_PAY | The shopper did not authorize the payment. The authorized funds were refunded and the offer was closed because the Adyen terminal did not receive the authorization notification. | | Refused | Shopper cancelled during PIN entry | The shopper did not enter their PIN. | | Refused | Merchant cancelled | For Alipay, this refusal only occurs for POS transactions. Usually, the merchant cancels the transaction before it completes, or refunds the transaction before it is captured. | | Refused | (NOT\_SUPPORT\_PAYMENT\_INST) | The shopper is using a version of Alipay Wallet that is not supported. Make sure that `payment_inst` is set to **Alipay\_HK**, and prompt the shopper to use the correct wallet. | | Refused | TRADE\_NOT\_EXIST | For online transactions, the shopper did not open the Alipay app from the payment URL, or did not log in to the Alipay website. For POS transactions, this refusal occurs when the merchant's MA Registration Number (RegNum) is missing. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Error | SYSTEM\_ERROR : Alipay system is currently not available, please try again later. | The Alipay system is currently not available. Ask the shopper to try again later. | | Error | ILLEGAL\_SIGN | There is a technical issue with your configuration. Contact Alipay Support. | | Error | ACCESS\_FORBIDDEN | There is a technical issue with your configuration. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | RefundFailed | MERCHANT\_BALANCE\_NOT\_ENOUGH | There is a technical issue with the refund. Try again between 21:00–23:00 SGT. | | RefundFailed | PURCHASE\_TRADE\_NOT\_EXIST | The transaction you’re attempting to refund does not exist, or does not include a PSP reference. Check the request parameters to ensure you’re sending a referenced refund. | | RefundFailed | ILLEGAL\_ARGUMENT | The API request includes an incorrect parameter. Check your request parameters according to Alipay's [API specification](https://global.alipay.com/docs/ac/hkapi/qrcode_create#1SPjz). | | RefundFailed | RETURN\_AMOUNT\_EXCEED | The total refund amount exceeds the transaction amount. Check that the amount is correct. | | RefundFailed | ISSUER\_OR\_SWITCH\_INOPERATIVE | The issuer or issuer processor temporarily cannot authorize, usually because of downtime. Try again later. | | RefundFailed | 40 : Requested function not supported | The card issuer declined the transaction. This is sometimes caused by the issuer placing a hold on the shopper's card. | ## AlipayHK raw responses | Journal type | Response | Description | | ------------ | ----------------- | ----------------------------------------------- | | RefundFailed | SYSTEM\_EXCEPTION | Alipay system error. Retry after a few seconds. | ## American Express raw responses These are the most common raw responses from American Express for refused or canceled transactions. | Journal type | refusalReasonRaw | Description | | ------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Cancelled | 000: Approved | The transaction was canceled after being initially approved by the issuer. This can be due to various reasons, for example, if the shopper returns goods after purchase. | | Cancelled | 001: Approve with ID | The transaction was canceled after the issuer requested that identification be established through telephone contact between the acquiring center's authorizer and the merchant. | | Cancelled | 002: Prepaid Card Partial Authorization | Transaction was canceled. Some card issuers support partial-approval authorization. This approves a part of the requested transaction, leaving the remainder to be paid with another form of tender. | | Refused | 100: Deny | This is a generic refusal that can have several possible reasons. Shopper should contact their issuing bank for clarification. | | Refused | 101: Expired Card / Invalid Expiration Date | The card expiration date is in the past. The shopper should correct the date or use another payment method. | | Refused | 106: PIN tries exceeded | The shopper has entered an incorrect PIN more times than is allowed by the issuing bank. The shopper should try again or use another payment method. | | Refused | 109: Invalid merchant | The transaction was refused by the card issuer. The shopper should contact their bank for clarification. The shopper can try again after resolving the issue with their bank, or use another payment method. | | Refused | 110: Invalid amount | The transaction amount was specified in an invalid format. For example, an invalid character such as a dollar sign or a space was used. The shopper should correct or use another payment method. | | Refused | 111: Invalid account | The card issuer is unable to validate the card/account number, possibly because an invalid character was used. | | Refused | 115: Requested function not supported | The card issuer does not allow this type of transaction on this card/account. | | Refused | 117: Incorrect PIN | The shopper entered an invalid PIN. The shopper should try again or use another payment method. | | Refused | 119: Transaction not permitted to Cardmember | The card issuer doesn't permit the transaction on this card/account. The shopper can use another payment method. | | Refused | 122: Invalid Keyed Printed Card Security Code (PCSC) | The card issuer indicated a security issue with this card. The shopper can use another payment method. Alternatively, the shopper can try again after they resolved the issue with their bank. | | Refused | 125: Invalid Effective Date on Card | The card expiration date provided is not a valid date format. The shopper should correct or use another payment method. | | Refused | 130: Additional customer identification required | Authentication is required for the transaction. If the transaction is in scope of PSD2 and did not go through 3D Secure, try again with 3D Secure. This is also referred to as a "Soft Decline". | | Refused | 181: Format error | The card issuer does not recognize the transaction details being entered. This is due to a format error. The shopper should check the transaction information and try again. | | Refused | 183: Invalid Currency Code | The currency code provided doesn't comply with standards. | | Refused | 187: Deny New Card Issued | The card issuer supplied the cardholder with a new card. The shopper should try again with the new card, or use another payment method | | Refused | 189: Deny Canceled or Closed Card Acceptor | The merchant has stopped operations or is no longer accepting cards from this card scheme. | | Refused | 200: Deny pick up Card | The card issuer requests to retain the card. This can be due to a suspected counterfeit or stolen card. | | Refused | 900: Advice accepted | The ExpressPay issuer is unable to respond to an ATC Synchronization Authorization Request. | | Refused | 911: Card Issuer timed out | The issuing bank cannot be contacted. The shopper should try again or use another payment method. | | Refused | 912: Host unavailable | The issuing bank cannot be contacted. The shopper should try again or use another payment method. | ## BLIK raw responses | Journal type | Response | Description | | ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Refused | ER\_WRONG\_TICKET | The BLIK code did not match any code generated within the last 180 seconds. Ask the shopper to try again and to check that they are using a valid code. | | Refused | ER\_TIC\_USED | The BLIK code was already used within the last 180 seconds. | | Refused | ER\_TIC\_EXPIRED | The BLIK code has expired. | | Refused | TIMEOUT | Timeout in communication with the mobile banking app or the issuer’s system. | | Refused | USER\_TIMEOUT | The shopper did not confirm the transaction in the mobile banking app within the time limit. | | Refused | LIMIT\_EXCEEDED | The shopper’s transaction limit is exceeded. The banking mobile app should direct the shopper to change the limit. | | Refused | USER\_DECLINED | The shopper declined the transaction in the mobile app. | | Refused | AM\_TIMEOUT | Timeout in communication with the mobile app. | | Refused | INSUFFICIENT\_FUNDS | Insufficient funds in the shopper’s bank account. The mobile app should display the reason and direct the shopper to change the limit. | | Error | NO\_RESPONSE\_WITHIN\_TIMEOUT | Adyen did not receive a response from BLIK within the time limit. | ## Diners raw responses | Response Code | Description | | ------------- | ------------------------------------------------------------------ | | 100 | Do not honor | | 101 | Expired card | | 102 | Suspected fraud (account not on positive file) | | 103 | Customer authentication required | | 104 | Restricted card | | 106 | Allowable pin tries exceeded | | 107 | Refer to card issuer | | 109 | Invalid merchant | | 110 | Invalid amount | | 111 | Invalid card number | | 115 | Requested function not supported | | 117 | Incorrect pin | | 118 | Cycle range suspended | | 119 | Transaction not permitted to cardholder | | 120 | Transaction not permitted to originator | | 122 | Card validity period exceeded | | 124 | Violation of law | | 125 | Card not effective | | 129 | Suspected counterfeit card | | 140 | Off-line declined—merchant forced acceptance | | 141 | Unable to go on line, off-line declined—merchant forced acceptance | | 163 | Security violations | | 181 | Decline given by POS participant (adjustment) | | 182 | Decline given by issuer | | 183 | Domain restriction control failure | | 184 | Decline given by Xpress, no communication with issuer | | 185 | Decline given by Xpress, card is local use only | | 188 | Xpress unable to forward request to issuer X | | 192 | Restricted merchant | | 194 | PIN change or unblock failed (EMV only) | | 195 | New PIN not accepted (EMV only) | | 196 | Chip information advice (EMV only) | | 197 | Card account verification failed | | 198 | TVR or CVR validation failed | | 201 | Expired card | | 208 | Lost card | | 209 | Stolen card | ## Discover raw responses | Response Code | Response Description | Required Action | | ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 00 | Approved or completed successfully | Approve | | 01 | Reserved for future use | Reserved | | 02 | Reserved for future use | Reserved | | 03 | Invalid merchant | Decline | | 04 | Capture card | Decline | | 05 | Do not honor | Decline | | 07 | Pick-up card, special condition | Decline | | 08 | Reserved for future use | Reserved | | 10 | Approved for partial amount | Approve | | 11 | Approved | Approve | | 12 | Invalid transaction | Decline | | 13 | Invalid amount | Decline | | 14 | Invalid card number | Decline | | 15 | Reserved for future use | Reserved | | 19 | Re-enter transaction | Decline | | 30 | Format error | Decline | | 31 | Bank not supported by switch | Decline | | 33 | Reserved for future use | Reserved | | 34 | Reserved for Future use | Reserved | | 35 | Reserved for future use | Reserved | | 36 | Reserved for future use | Reserved | | 37 | Reserved for future use | Reserved | | 38 | Allowable PIN tries exceeded | Decline | | 39 | No credit account | Decline | | 40 | Requested function not supported | Decline | | 41 | Lost card | Decline | | 43 | Stolen card | Decline | | 51 | Decline | Decline | | 53 | No savings account | Decline | | 54 | Expired card | Decline | | 55 | Invalid PIN | Decline | | 56 | No card record | Decline | | 57 | Transaction not permitted to issuer/cardholder | Decline | | 58 | Transaction not permitted to acquirer/terminal | Decline | | 59 | Suspected fraud | Decline | | 60 | Card acceptor contact acquirer | Decline | | 61 | Exceeds withdrawal amount limit | Decline | | 62 | Restricted card | Decline | | 63 | Security violation | Decline | | 64 | Original amount incorrect | Decline | | 65 | Exceeds withdrawal count limit | Decline | | 66 | Card Acceptor call acquirer’s security dept | Decline | | 67 | Hard capture (requires ATM pick-up) | Decline | | 68 | Response received too late | Decline | | 75 | Allowable number of PIN tries exceeded | Decline | | 76 | Invalid/nonexistent "to" account specified | Decline | | 77 | Invalid/nonexistent "from" account specified | Decline | | 78 | Invalid/nonexistent account specified (general) | Decline | | 83 | Domain restriction controls failure | Decline | | 85 | No reason to decline | This Response Code is only applicable to Process Code 18, Card Account Verification, 0110 Authorization Response Message. | | 87 | Network unavailable | Decline | | 91 | Authorization system or issuer system inoperative | Decline | | 92 | Unable to route transaction | Decline | | 93 | Transaction cannot be completed, violation of law | Decline | | 94 | Duplicate transmission detected | Decline | | 96 | System malfunction | Decline | | 1A | Customer authentication required | Decline | | N1 | System up | The system is up. The messages can be routed through this connection. | | N2 | Soft down | The system is soft down. This means that the system is available but messages should only be routed through this connection as a last resort. If multiple connections are available, messages should be sent to the connections that are up and available. If all connections are in a soft down state, the Messages should be routed in the same fashion as if all connections are up and available. | | N3 | System down | The system is down. No messages should be routed through this connection. An N3 is normally sent when the connection is being closed due to system maintenance. | | N7 | Decline for AVS or CID mismatch | This Response Code is only applicable to Host Capture Authorizations. | | P5 | PIN change/unblock failed | Decline | | P6 | New PIN not accepted | Decline | ## GoPay raw responses | Error Code | Description | | ---------- | ------------------------------------------------------------- | | 201 | Insufficient Balance. (HTTP 400) | | 112 | User Blocked. (HTTP 400) | | 3007 | Order not found. (HTTP 404) | | 5003 | Link not found. (HTTP 400) | | 5002 | Invalid authorisation action. (HTTP 400) | | 900 | Your request cannot be processed. (HTTP 500) | | 1604 | OTP is invalid. (HTTP 400) | | 11007 | Payment Provider Account Blocked. (HTTP 400) | | 4060 | Fraud validation error. (HTTP 403) | | 11009 | (HTTP 400) | | 2005 | Refund under process. Please try again later. (HTTP 400) | | 1610 | OTP is expired. (HTTP 429) | | 2001 | Refund amount exceeds original transaction amount. (HTTP 400) | | 6311 | Challenge Id Expired or Invalid. (HTTP 400) | | 159 | Payment option not found. (HTTP 422) | | 153 | The token is invalid for the payment. (HTTP 422) | | 202 | Excessive balance. (HTTP 422) | | 310 | Malformed data. (HTTP 400) | | 1609 | Too many OTP requests. (HTTP 429) | ## Grabpay raw responses | Journal type | Response | Description | | ------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Canceled | consent\_required : Shopper Canceled the payment before completion | The shopper’s wallet only contains SGD currency, but is trying to pay in MYR. Grabpay cancels the transaction and prompts the shopper to top up their wallet. | | Refused | insufficient\_balance : Shopper insufficient balance in wallet | The shopper did not have the funds to cover this transaction. Ask the shopper to top up their wallet or try another payment method. | | Refused | confirm\_failed : Customer Limits Exceeded/KYC check failed | The shopper has exceeded the balance limits of their wallet. Grabpay imposes lower limits on "basic users" who have not completed the KYC of their wallet. | | Refused | server\_error : GrabPay Server Error | Generic error returned by GrabPay during the redirect If you do not have a direct contract with Adyen, contact GrabPay directly. If you have a direct contract with Adyen, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Error | "{""devMessage"":""Bad Input."",""arg"":""Missing value for item0Price\n""}" | You did not specify the item price for the invoice line item. The value for `amountIncludingTax` must be greater than **0**. | | Refused | Customer has not completed KYC of wallet | The shopper's GrabPay wallet was not activated (not KYC-ed or no has balance), or the shopper attempted to bind their card or bank account to their wallet but was unsuccessful. | | Refused | invalid\_request : GrabPay Server Error | Adyen couldn’t establish a connection to GrabPay to either send the request or receive a response. Retry the payment request. If the issue continues, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Error | CONVERTER\_RESPONSE | Adyen couldn’t interpret the acquirer’s response. Retry the payment request. If the issue continues, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Error | NO\_RESPONSE\_WITHIN\_TIMEOUT | The acquirer did not return a response within the 30 seconds time limit. Retry the payment request. If the issue continues, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | Refused | Customer has not completed initial top up of wallet | There are no funds in the shopper's wallet. Ask the shopper to top up their wallet. | | Refused | kyc\_compliance\_decline : kyc\_compliance\_decline | The shopper hasn’t completed the KYC verification process. Ask the shopper to complete the KYC process to activate their wallet, and to try the payment again. | | RefundFailed | merchant\_insufficient\_balance | Your account balance is insufficient. This can happen if your funds have just been settled from GrabPay to Adyen. Processed additional volume with GrabPay and set up a reserve with Grabpay. | | RefundFailed | pending\_approval | The Grabpay system is processing modifications on the transaction. Wait for these modifications to complete, then try again. | ## Japanese issuer error codes Error codes from Japanese issuers often provide more insight than acquirer responses. When shoppers in Japan encounter a payment error, it is common for them to call their issuer to retry the transaction. When the issuer provides an error, the `additionalData` object in the payment response contains the following fields: * [domesticRefusalReasonRaw](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-additionalData-ResponseAdditionalDataDomesticError-domesticRefusalReasonRaw) * [domesticShopperAdvice](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-additionalData-ResponseAdditionalDataDomesticError-domesticShopperAdvice) **Example issuer response** ```json "additionalData": { "domesticRefusalReasonRaw": "G12: Card cannot be used (when credit card cannot be used)", "domesticShopperAdvice": "カード発行会社にご連絡し、状況をご確認ください。もしくは別カードでお取引ください。" } ``` We recommend you show the `domesticShopperAdvice` from the API response on your checkout page in Japan. This text is in the **Shopper advice** column below. The following are the most frequent error codes from domestic issuers. | Refusal reason | Shopper advice | Explanation | | ------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | G12: Card cannot be used (when credit card cannot be used) | カード発行会社にご連絡し、状況をご確認ください。もしくは別カードでお取引ください。 | The shopper's credit card cannot be used. Ask them to contact their card issuer to get approval. | | G30: Suspension (if authorization of transaction is suspended) | カード発行会社にて取引の判定を保留しています。カード発行会社にご連絡ください。 | The authorization for the transaction is suspended. Ask the shopper to inform their card issuer that they have received a G30 error. | | G42: PIN error (incorrect PIN entered) | PINが誤っています。再度入力ください。 | The shopper entered their PIN incorrectly. Ask them to enter the correct PIN. | | G44: Transaction Data Error | 正しいお支払い情報をご入力ください。 | Please re-enter your payment details. | | G45: Transaction Data Error | 正しいお支払い情報をご入力ください。 | Please re-enter your payment details. | | G54: Card used too many times (either in 1 day or when max amount is exceeded) | カード発行会社にご連絡し、状況をご確認ください。もしくは別カードでお取引ください。 | The card's usage limit has been exceeded. Ask the shopper to use a different card. | | G55: Max amount exceeded (when single day max amount is exceeded) | クレジットカードの場合はカード発行会社にご確認ください。デビットカード・プリペイドカードの場合は残高をご確認ください。 | The card's credit limit has been exceeded. Ask the shopper to use a different card or contact their card issuer. If it is a debit card, ask them to check their account balance. | | G56: Transaction Data Error | 正しいお支払い情報をご入力ください。 | Please re-enter your payment details. | | G60: Transaction Data Error | 正しいお支払い情報をご入力ください。 | Please re-enter your payment details. | | G83: Transaction Data Error | 正しいお支払い情報をご入力ください。 | Please re-enter your payment details. | | 3D Not Authenticated | カード発行会社のホームページで本人認証サービスに登録いただくか、カード発行会社にご連絡ください。 | Please register your info in your issuer's website or contact to your issuer. | ## KCP raw responses | Journal type | Response | Description | | ------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Refused | CC10 : Insufficient funds in the account (CC10 : Etc error) | The shopper doesn’t have enough funds to complete the transaction. Ask the shopper to top up their account and try again. | | Refused | CC61 : The card holder has exceeded their credit limit (CC61 : Etc error) | The shopper has exceeded their credit limit. Ask the shopper to contact their bank if they want to increase the limit. | | Refused | CC45 : Suspended credit card. (CC45 : Etc error) | The shopper’s card is suspended. Ask the shopper to contact their bank for further information. | | Refused | CC63 : Password is not correct. (CC63 : Etc error) | The shopper has entered an incorrect password. | | Refused | CC66 : Error in the social security number. (CC66 : Etc error) | The shopper entered the wrong social security number. Ask the shopper to try again with the correct number. | | Refused | CC04 : Lost or invalid card. (CC04 : Etc error) | Ask the shopper to contact their bank. | | Refused | CC54 : The expiry date has passed, or the date does not match. (CC54 : Etc error) | The shopper's card is expired. | | Refused | CC55 : Error in the expiry date of the credit card. (CC55 : Etc error) | The shopper entered the wrong expiry date. Ask the shopper to try again with the correct expiry date. | | Refused | CC69 : The transaction has been suspended since the wrong PIN is entered more than three (CC69 : Etc error) | The shopper entered the wrong PIN more than three times. Ask the shopper to contact their bank to resolve. | | Refused | CC01 : Please contact the card issuer for further assistance. (CC01 : Etc error) | A technical issue occurred with the shopper’s card. Ask the shopper to contact their bank. | | Error | CC03 : This error will occur when the status of the card used is invalid. (CC03 : Etc error) | The shopper's card is not active. Ask the shopper to confirm that they activated the card. | | Refused | 8130 : The merchant does not accept credit cards issued outside of Korea. (8130 : Etc error) | KCP only processes Korean local cards. Ask the shopper to try again using a card issued in Korea. | ## Klarna raw responses These are the most common raw acquirer responses from Klarna for successful, refused, failed or cancelled transactions. | Last journal type | Raw acquirer response | Description | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PENDING | This is an expected response for [Klarna Widget](/payment-methods/klarna/api-only) integrations. | | Authorised | ACCEPTED | The payment was authorised. | | Error | Internal error | Generic API response from Klarna. Check your [Customer Area](https://ca-live.adyen.com/) for additional information. | | Error | BAD\_VALUE : locale | The locale in your payment request is not compatible. Refer to our [Klarna documentation](/payment-methods/klarna/api-only#make-a-payment) for compatible combinations. | | Error | BAD\_VALUE : order\_lines\[X].tax\_rate | Error message on the validation criteria for the tax calculation. Refer to our [Klarna documentation](/payment-methods/klarna/invoice-lines) for more information about the tax calculation. | | Error | BAD\_VALUE : order\_lines\[X].total\_tax\_amount | There is an error in the tax amounts for order line \[X]. Tax amounts should add up over all order lines. Klarna validates this on their end. Refer to our [Klarna documentation](/payment-methods/klarna/invoice-lines) to see how to send in tax amounts in your payment request. | | Error | BAD\_VALUE : order\_tax\_amount | There is an error in the tax amounts. Tax amounts should add up over all order lines. Klarna validates this on their end. Refer to our [Klarna documentation](/payment-methods/klarna/invoice-lines) to see how to send in tax amounts in your payment request. | | Error | BAD\_VALUE : purchase\_currency | The `amount.currency` in your payment request not formatted correctly or doesn't apply for a certain locale. Refer to our [Klarna documentation](/payment-methods/klarna/api-only#make-a-payment) for compatible combinations. | | Error | BAD\_VALUE : billing\_address.postal\_code, shipping\_address.postal\_code or BAD\_VALUE : shipping\_address.postal\_code, billing\_address.postal\_code | The postal code in the `billingAddress` or the `deliveryAddress` in your payment request is not formatted correctly. Refer to our [Klarna documentation](/payment-methods/klarna/) to see how to format the shopper's address. | | Error | BAD\_VALUE : attachment.attachment | The data sent in the `additionalData.openinvoicedata.merchantData` in your payment request does not follow Klarna's requirements. Refer to [Klarna's documentation](https://docs.klarna.com/api/payments/#operation/createCreditSession) to see how to format the merchant data. | | Error | BAD\_VALUE : billing\_address.phone, shipping\_address.phone or BAD\_VALUE : shipping\_address.phone, billing\_address.phone | The `telephoneNumber` in your payment request is not formatted correctly. Refer to our [Klarna documentation](/payment-methods/klarna/) to see how to format the telephone number. | | Error | BAD\_VALUE : billing\_address.given\_name, billing\_address.family\_name, or BAD\_VALUE : shipping\_address.given\_name, shipping\_address.family\_name | Your request contains invalid characters. Make sure that you only submit UTF-8 encoded values when creating a Klarna payment. | | Error | Payment method not available (contact Klarna) | The payment method defined in the payment request is not configured correctly on Klarna's end. Verify that you have enabled Klarna in your [Customer Area](https://ca-test.adyen.com/). | | Error | Allowed category list is empty | Edit your payment request. Your payment request does not follow the guidelines defined in our [Klarna documentation](/payment-methods/klarna). For example, make sure that the country code and billing address are for the same location. | | Error | Missing returnUrl | Your payment request is missing the `returnUrl` parameter. | | Error | No InvoiceLines provided | Your payment request did not include invoice lines. Refer to our [Klarna documentation](/payment-methods/klarna/invoice-lines) to see how to send in invoice lines in your payment request. | | OfferCancelled | NOT\_FOUND : Invalid session id | The shopper has tried to make a payment for an offer that has expired. We recommend that you ask the shopper to retry the transaction. | | Not linked to a payment status, check logs. | ReadSessionResponse does not have valid authorisation token | Klarna sends this error when:- The [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) call to Adyen is made before the shopper received an authorisation from Klarna. - The shopper's authorisation token from Klarna has expired after 60 minutes.There could be multiple reasons for this to happen. | | Refused | REFUSED | Klarna's internal risk engine refused the payment. A possible reason is that the shopper has an unpaid balance towards Klarna. | | Refused | UNAVAILABLE\_PAYMENT\_METHOD or PAYMENT\_METHOD\_FAILED : Purchase for payment method failed | Klarna's internal risk engine refused the payment. A possible reason is that the shopper has an unpaid balance towards Klarna. | ## Mastercard Merchant Advice Codes The Merchant Advice Code (MAC) can be returned for both approved and refused Mastercard payments. This code provides additional information about the type of transaction or the reason why the payment failed. If the payment failed, the MAC gives guidance on if and when you can retry the payment. Not all Mastercard issuers return the MAC. When an issuer returns a MAC, you receive it automatically in the [`additionalData.merchantAdviceCode` ](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_additionalData-ResponseAdditionalDataCommon-merchantAdviceCode)of the payment response. You do not need to enable specific additional data in your Customer Area in order to receive the MAC. | **merchantAdviceCode** | Description | Recommended action | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **01 : New account information available** | There has been a change in the shopper's account information, for example a new expiry date for an expired card. | Get the updated card information. You can either use our [Account Updater](/online-payments/account-updater), or contact the shopper directly. | | **02 : Cannot approve at this time, try again later** | This can happen because of a credit limit, or insufficient funds on the card. | Try again the payment after 72 hours. | | **03 : Do not try again** | The account is closed, or the issuer suspects fraud. | Do not retry this payment. Retries can be subject to penalty fees by Mastercard. Consider reaching out directly to the shopper. | | **04 : Token requirements not fulfilled for this token type** | There is a technical issue with the payment. | Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). | | **21 : Payment Cancellation** | Shopper canceled the recurring agreement. | Do not retry this payment. Retries can be subject to penalty fees by Mastercard. | | **24 : Retry after 1 hour** | Insufficient funds. | Retry the payment after 1 hour. | | **25 : Retry after 24 hours** | Insufficient funds. | Retry the payment after 24 hours. | | **26 : Retry after 2 days** | Insufficient funds. | Retry the payment after 2 days. | | **27 : Retry after 4 days** | Insufficient funds. | Retry the payment after 4 days. | | **28 : Retry after 6 days** | Insufficient funds. | Retry the payment after 6 days. | | **29 : Retry after 8 days** | Insufficient funds. | Retry the payment after 8 days. | | **30 : Retry after 10 days** | Insufficient funds. | Retry the payment after 10 days. | | **40 : Consumer non-reloadable prepaid card** | Issuer recognizes a consumer non-reloadable prepaid card was used for this transaction. | No action required. | | **41 : Consumer single-use virtual card number** | Issuer recognized a consumer single-use virtual card was used for this transaction. | No action required. | | **42 : Score Exceeds Applicable Threshold Value** | Mastercard refused this transaction due to a sanctions match. | No action required. | | **43: Consumer multi-use virtual card number** | Transaction was carried out with a consumer multi-use virtual card number. | No action required. | | **MerchantAdviceCode unknown** | The issuer has returned a value that is not included in the Mastercard specifications. | No action possible. | ## MB WAY raw responses | Journal type | Response | Description | | ------------ | ---------------------------------------- | -------------------------------------------------------------------- | | Refused | c5: Refused/Recusado | The payment was not completed or refused in the app. | | Refused | ERROR - 102/203: Unknown phone number | The phone number provided by the shopper is unknown. | | Error | No response from ACM | The connection to MB WAY timed out before Adyen received a response. | | Refused | c2: Customer declined payment - Recusado | The shopper refused the payment in the app. | | Refused | c4: Operation rejected | The shopper should contact their bank for further information. | | Refused | Vp3: Limit exceeded | The shopper has exceeded the maximum daily amount. | ## Mexico raw responses These are the raw responses for refused or canceled domestics transactions in Mexico. | Journal type | refusalReasonRaw | Description | | -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- | | Approved | 00 : APPROVED | Approved or completed successfully | | Referral | 01 : REFERRAL | Function not available‚ Refer to card issuer | | Referral | 02 : REFERRAL | Refer to card issuer‚ special conditions | | Declined | 03 : DECLINED | Invalid merchant or terminal | | Block card | 04 : BLOCK\_CARD | Pick-up card | | Declined | 05 : DECLINED | Do not honor | | Declined | 06 : DECLINED | Decline from the issuer | | Block card | 07 : BLOCK\_CARD | Capture card, special conditions (bad debt) | | Block card | 09 : BLOCK\_CARD | Request in progress (duplicate) | | Partially approved | 10 : PARTIALLY\_APPROVED | Partial Approval | | Approved | 11 : APPROVED | Approved (VIP) | | Declined | 12 : DECLINED | Invalid transaction | | Invalid amount | 13 : INVALID\_AMOUNT | Invalid amount | | Invalid card | 14 : INVALID\_CARD | Invalid card number (no such number) | | Invalid card | 15 : INVALID\_CARD | Cardholder not on file (no such issuer) | | PIN required | 1A : PIN\_REQUIRED | PIN data required | | Error | 30 : ERROR | Format error | | Error | 31 : ERROR | Bank not supported by switch | | Card expired | 33 : CARD\_EXPIRED | Expired card, capture | | Issuer suspected fraud | 34 : ISSUER\_SUSPECTED\_FRAUD | Suspected fraud, capture | | Error | 35 : ERROR | Card acceptor contact acquirer | | Restricted card | 36 : RESTRICTED\_CARD | Restricted card | | Error | 37 : ERROR | Card acceptor call acquirer security | | PIN tries exceeded | 38 : PIN\_TRIES\_EXCEEDED | Allowable PIN tries exceeded, capture | | Not supported | 39 : NOT\_SUPPORTED | No credit account | | Block card | 41 : BLOCK\_CARD | Lost card | | Block card | 43 : BLOCK\_CARD | Stolen card, capture | | Not enough balance | 51 : NOT\_ENOUGH\_BALANCE | Insufficient funds | | Card expired | 54 : CARD\_EXPIRED | Expired card | | Invalid PIN | 55 : INVALID\_PIN | Incorrect PIN | | Invalid card | 56 : INVALID\_CARD | No card record | | Transaction not permitted | 57 : TRANSACTION\_NOT\_PERMITTED | Transaction not permitted to cardholder | | Transaction not permitted | 58 : TRANSACTION\_NOT\_PERMITTED | Transaction not permitted to terminal | | Withdrawal amount exceeded | 61 : WITHDRAWAL\_AMOUNT\_EXCEEDED | Exceeds withdrawal amount limit | | Restricted card | 62 : RESTRICTED\_CARD | Restricted card | | Withdrawal count exceeded | 65 : WITHDRAWAL\_COUNT\_EXCEEDED | Exceeds withdrawal frequency limit | | Issuer unavailable | 68 : ISSUER\_UNAVAILABLE | Response not arrived or received too late | | Error | 70 : ERROR | Decryption error Track2 | | Error | 71 : ERROR | Must initialize keys | | Error | 72 : ERROR | Problem initializing Keys | | Error | 73 : ERROR | CRC error | | PIN tries exceeded | 75 : PIN\_TRIES\_EXCEEDED | Allowable number of PIN tries exceeded | | Error | 76 : ERROR | Reserved for private use or Approved country club | | Error | 77 : ERROR | Reserved for private use or Approved pending identification (sign paper draft) | | Error | 78 : ERROR | Reserved for private use or Approved blind | | Error | 79 : ERROR | Reserved for private use or Approved administrative transaction | | Error | 80 : ERROR | Reserved for private use or Approved national negative file hit OK | | Error | 81 : ERROR | Reserved for private use or Approved commercial | | Declined | 82 : DECLINED | Reserved for private use or No security module | | Declined | 83 : DECLINED | Reserved for private use or No accounts | | Error | 84 : ERROR | Reserved for private use or No PBF | | Error | 85 : ERROR | Reserved for private use or PBF update error | | Declined | 86 : DECLINED | Reserved for private use or Invalid authorization type | | Declined | 87 : DECLINED | Reserved for private use or Bad Track Data | | Error | 88 : ERROR | Reserved for private use or PTLF error | | Error | 89 : ERROR | Reserved for private use or Invalid route service | | Error | 90 : ERROR | Cutoff in progress | | Issuer unavailable | 91 : ISSUER\_UNAVAILABLE | Issuer or switch is inoperative | | Issuer unavailable | 92 : ISSUER\_UNAVAILABLE | Financial institution or intermediate network unknown for routing | | Declined | 94 : DECLINED | Duplication transaction | | Issuer unavailable | 96 : ISSUER\_UNAVAILABLE | System malfunction | | Declined | N0 : DECLINED | Reserved for private use or Unable to authorize | | Error | N1 : ERROR | Reserved for private use or Invalid PAN length | | Declined | N2 : DECLINED | Reserved for private use or Preauthorization full | | Error | N5 : ERROR | Reserved for private use or Maximum credit per refund | | Error | N6 : ERROR | Reserved for private use or Maximum refund credit reached | | Error | N8 : ERROR | Reserved for private use or Over floor limit | | Error | N9 : ERROR | Reserved for private use or Maximum number refund credits | | Error | O0 : ERROR | Reserved for private use or Referral file full | | Error | O1 : ERROR | Reserved for private use or NEG file problem | | Error | O2 : ERROR | Reserved for private use or Advance less than minimum | | Error | O3 : ERROR | Reserved for private use or Delinquent | | Error | O4 : ERROR | Reserved for private use or Over limit table | | Error | O5 : ERROR | Reserved for private use or PIN required | | Error | O6 : ERROR | Reserved for private use or Mod 10 check | | Error | O7 : ERROR | Reserved for private use or Force post | | Error | O8 : ERROR | Reserved for private use or Bad PBF | | Error | O9 : ERROR | Reserved for private use or NEG file problem | | Error | P0 : ERROR | Reserved for private use or CAF problem | | Declined | P1 : DECLINED | Reserved for private use or Over daily limit | | Error | P2 : ERROR | Reserved for private use or CAPF not found | | Error | P3 : ERROR | Reserved for private use or Advance less than minimum | | Error | P4 : ERROR | Reserved for private use or Number of times used | | Error | P5 : ERROR | Reserved for private use or Delinquent | | Error | P6 : ERROR | Reserved for private use or Over limit table | | Error | P7 : ERROR | Reserved for private use or Advance less than minimum | | Error | P8 : ERROR | Reserved for private use or Administrative card needed | | Error | P9 : ERROR | Reserved for private use or Enter lesser amount | | Error | Q0 : ERROR | Reserved for private use or Invalid transaction date | | Declined | Q1 : DECLINED | Reserved for private use or Invalid expiration date | | Declined | Q2 : DECLINED | Reserved for private use or Invalid transaction code | | Error | Q3 : ERROR | Reserved for private use or Advance less than minimum | | Error | Q4 : ERROR | Reserved for private use or Number of times used | | Error | Q5 : ERROR | Reserved for private use or Delinquent | | Error | Q6 : ERROR | Reserved for private use or Over limit table | | Error | Q7 : ERROR | Reserved for private use or Amount over maximum | | Error | Q8 : ERROR | Reserved for private use or Administrative card not found | | Error | Q9 : ERROR | Reserved for private use or Administrative card not allowed | | Error | R0 : ERROR | Reserved for private use or Approved administrative request performed in window | | Error | R1 : ERROR | Reserved for private use or Approved administrative request performed out of window | | Error | R2 : ERROR | Reserved for private use or Approved administrative request performed anytime | | Error | R3 : ERROR | Reserved for private use or Chargeback, customer file updated | | Error | R4 : ERROR | Reserved for private use or Chargeback, customer file updated, acquirer not found | | Error | R5 : ERROR | Reserved for private use or Chargeback, incorrect prefix number | | Error | R6 : ERROR | Reserved for private use or Chargeback, incorrect response code or CPF configuration | | Error | R7 : ERROR | Reserved for private use or Administrative transactions not supported | | Error | R8 : ERROR | Reserved for private use or Card on national negative file | | Error | S4 : ERROR | PTLF full | | Error | S5 : ERROR | Reserved for private use or Chargeback approved, customer file not updated | | Error | S6 : ERROR | Reserved for private use or Chargeback approved, customer file not updated, acquirer not found | | Error | S7 : ERROR | Reserved for private use or Chargeback accepted, incorrect destination | | Error | S8 : ERROR | Reserved for private use or ADMN file problem | | Error | S9 : ERROR | Reserved for private use or Unable to validate PIN; security module is down | | Error | T1 : ERROR | Reserved for private use or Invalid credit card advance amount | | Error | T2 : ERROR | Reserved for private use or Invalid transaction date | | Error | T3 : ERROR | Reserved for private use or Card not supported | | Error | T4 : ERROR | Reserved for private use or Amount over maximum | | Declined | T5 : DECLINED | Reserved for private use or CAF status = 0 or 9 | | Error | T6 : ERROR | Reserved for private use or Bad UAF | | Error | T7 : ERROR | Reserved for private use or Cash back exceeds daily limit | | Error | T8 : ERROR | Reserved for private use or Invalid account | ## Nyce raw responses These are the raw responses from Nyce for refused or canceled transactions. | Response Code | Description | | ------------- | ------------------------------- | | 44 | Lost or stolen card, no capture | ## Oney raw responses | Journal type | Response | Description | | ------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Refused | La demande de paiement a été refusée | Oney declined the payment. | | Error | ERR\_03 : L'email n'est pas compatible avec la regex définie en base. - email\_address | The email address failed Oney’s validation. Ask the shopper to try again with another email address. | | Error | 504 : Gateway Timeout | The payment failed because of a timeout. Ask the shopper to try again later. | | Error | ERR\_04 : Le pays de livraison/facturation n'est pas accepté - customer.customer\_address | The shipping or billing address is not accepted. Check that the address is correct and matches the country/region. | | Error | ERR\_04 : Le pays de livraison/facturation n'est pas accepté - purchase.delivery.delivery | The delivery address is not accepted. Check that the delivery address is correct. | | Error | ERR\_03 : Le format du champ est invalide | The phone number format is not valid. The expected format for France is: +336 or +337 followed by eight digits. The expected format for Spain is +346 or +347 followed by eight digits. | | Error | ERR\_03 : Invalid Business\_transaction. | You don’t have permission to do this type of transaction. Contact our Support Team. | | Error | ERR\_05 : Les bornes d'une OPC sont dépassées - payment.payment\_amount | The transaction amount is above/below the required limits for Oney. | ## Online banking Czech Republic raw responses | Last journal type | refusalReasonRaw | Description | | ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Refused | provider\_error: Something went wrong on the provider's side. | Transaction is rejected by the bank (refusal to authorize the transaction). The shopper should contact their bank to clarify the reason for the transaction's rejection. | | Error | No response from ACM | PayU did not respond within 30 seconds which resulted in a timeout. | For a full list of responses, refer to PayU's [documentation](https://developers.paymentsos.com/docs/apis/payments/1.3.0/#section/Overview/Responses). ## Online banking Poland raw responses | Journal type | refusalReasonRaw | Description | | ------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | RefundFailed | 409: The amount of refund exceeds available amount for the transaction | Insufficient funds on the payment to execute the refund. Verify your request and submit another request, if applicable. | | RefundFailed | 500: Internal Server Error | Acquirer internal error. Retry the refund after 1 hour. | | RefundFailed | Error when attempting transfer : CONVERTER\_RESPONSE | Adyen couldn't interpret the acquirer's response. Retry the refund after 1 hour. | | RefundFailed | Error when attempting transfer : NO\_RESPONSE\_WITHIN\_TIMEOUT | Adyen did not receive a response from the acquirer within the time limit. Retry the refund after 1 hour. | ## Online banking Slovakia raw responses | Last journal type | refusalReasonRaw | Description | | ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Refused | provider\_error: Something went wrong on the provider's side. | Transaction is rejected by the bank (refusal to authorize the transaction). To clarify the reason for the rejection of the transaction, the shopper should contact their bank. | | Error | No response from ACM | PayU did not respond within 30 seconds which resulted in a timeout. | For a full list of responses, refer to PayU's [documentation](https://developers.paymentsos.com/docs/apis/payments/1.3.0/#section/Overview/Responses). ## Pay by Bank (US) raw responses Pay by Bank (US) relies on the ACH Direct Debit network for the funds flow. The raw refusal reasons reflect this. | Journal type | refusalReasonRaw | Description | | ------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Refused | Failed: Risk of bank-initiated ACH returns | There is a risk of a bank-initiated ACH return for this account. Ask the shopper to use another payment method. | | Refused | Failed: Risk of unauthorized returns | There is a risk of a customer-initiated ACH return for this account. Ask the shopper to use another payment method. | | Refused | Failed: Risk of insufficient balance | There is a risk of a bank-initiated ACH return for this account because of an insufficient balance. Ask the shopper to try a different bank account, or use another payment method. | | Refused | Ask the shopper to re-authenticate | The shopper needs to re-authenticate. This can happen when there is a recent password or multifactor authentication change, or when the consent to share data has expired. Initiate a new payment and ask the shopper to re-authenticate. | | Error | Plaid service is experiencing an outage. Please try again later | There is an unexpected error on the Plaid server. You can retry the transaction. | ## PayPal raw responses Adyen is moving PayPal transaction traffic away from an older PayPal API that is being deprecated, to a new PayPal API. You may notice a difference in the raw responses. The following tables show the most common raw acquirer responses from PayPal for refused, failed, or canceled transactions in the new situation, and in the old situation. These are the most common PayPal raw responses when your transaction traffic has been moved to the latest PayPal API: | Journal type | refusalReasonRaw | Description | | ------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Error | INTERNAL\_SERVER\_ERROR | Something unexpected has gone wrong on the PayPal server. You can retry the transaction. (HTTP 500) | | Error | INVALID\_RESOURCE\_ID | The specified resource ID does not exist. Check the resource ID and try again. (HTTP 404) | | Error | NOT\_AUTHORIZED | Authorization failed due to insufficient permissions. (HTTP 403) | | Error | PERMISSION\_DENIED | You do not have permission to access or perform this operation. (HTTP 403) | | Error | REFUSED\_MARK\_REF\_TXN\_NOT\_ENABLED | Your PayPal merchant account is not set up or approved to initiate recurring payments on behalf of your customers. (HTTP 403) | | Error | UNPROCESSABLE\_ENTITY | The requested action cannot be performed, is semantically incorrect, or failed. (HTTP 422) | | Refused | AGREEMENT\_ALREADY\_CANCELLED | The agreement that the payment was based on, has been cancelled. (HTTP 422) | | Refused | BILLING\_AGREEMENT\_NOT\_FOUND | The billing agreement token for this transaction was not found. (HTTP 422) | | Refused | CANNOT\_BE\_ZERO\_OR\_NEGATIVE | The amount must be greater than zero. If the currency supports decimals, only two decimal place precision is supported. (HTTP 422) | | Refused | COMPLIANCE\_VIOLATION | The transaction is declined because it is not compliant with regulations. (HTTP 422) | | Refused | INSTRUMENT\_DECLINED | The payment instrument was declined by the processor or bank, or cannot be used for this payment. In case of insufficient funds, you can retry and ask the customer to use a different payment method. (HTTP 422) | | Refused | MAX\_NUMBER\_OF\_PAYMENT\_ATTEMPTS\_EXCEEDED | You have retried the payment more times than is allowed. (HTTP 422) | | Refused | PAYER\_ACCOUNT\_LOCKED\_OR\_CLOSED | The shopper's account cannot be used for this transaction because the account is locked or closed. Do not retry this transaction with the same account details. (HTTP 422) | | Refused | PAYER\_CANNOT\_PAY | The shopper cannot pay for this transaction using PayPal. Ask the shopper to try another payment method. (HTTP 422) | | Refused | REDIRECT\_PAYER\_FOR\_ALTERNATE\_FUNDING | The transaction failed. Ask the shopper to try another payment method. (HTTP 422) | | Refused | TRANSACTION\_REFUSED | There are many possible reasons for a refused transaction, including:- An issue with the amount or currency of a partial refund - Already fully refunded - (Partial) refund not allowed or no longer allowed for the transaction type or payment method or due to regulatory restrictions - Card account closed or never existed - Suspected fraud(HTTP 422) | | CaptureFailed | AUTHORIZATION\_ALREADY\_CAPTURED | The payment has already been captured. Do not retry the same request. (HTTP 422) | | CaptureFailed | AUTHORIZATION\_EXPIRED | The payment cannot be captured because the authorization validity period has expired. (HTTP 422) | | CaptureFailed | AUTHORIZATION\_VOIDED | The payment cannot be captured or re-authorized because the authorization has been cancelled. (HTTP 422) | | CaptureFailed | DUPLICATE\_INVOICE\_ID | Duplicate invoice ID detected. This error can occur if your account has been set to use the `reference` from your payment request as the transaction ID. By default, the unique PSP reference of the transaction is used as the invoice ID. (HTTP 422) | | CaptureFailed | DUPLICATE\_TRANSACTION | Duplicate invoice ID detected. This error can occur if your account has been set to use the `reference` from your payment request as the transaction ID. By default, the unique PSP reference of the transaction is used as the invoice ID. (HTTP 422) | | CaptureFailed | PAYEE\_ACCOUNT\_RESTRICTED | The transaction failed because PayPal has put restrictions on the seller's PayPal account. (HTTP 422) | | CaptureFailed | PAYER\_ACCOUNT\_RESTRICTED | The transaction failed because PayPal has put restrictions on the shopper's PayPal account. (HTTP 422) | | RefundFailed | CAPTURE\_FULLY\_REFUNDED | It is not possible to issue a refund because the payment has already been fully refunded. (HTTP 422) | | RefundFailed | MAX\_NUMBER\_OF\_REFUNDS\_EXCEEDED | You have retried a refund for this capture more times than is allowed. (HTTP 422) | | RefundFailed | REFUND\_FAILED\_INSUFFICIENT\_FUNDS | The refund failed because the seller's PayPal account has insufficient funds, or because the bank account linked to the seller's PayPal account has not been verified or has insufficient funds. (HTTP 422). | | RefundFailed | REFUND\_NOT\_PERMITTED\_DUE\_TO\_CHARGEBACK | It is not possible to issue a refund because the payment is [disputed](/risk-management/chargeback-guidelines/paypal-chargebacks/). If you are a marketplace, contact the seller to resolve the chargeback. (HTTP 422) | | RefundFailed | REFUND\_TIME\_LIMIT\_EXCEEDED | It is not possible to refund this payment because the time period that PayPal allows for issuing a refund has passed. (HTTP 422) | | RefundFailed | TRANSACTION\_DISPUTED | Partial refunds are not possible because the transaction is [disputed](/risk-management/chargeback-guidelines/paypal-chargebacks/). (HTTP 422) | These are the most common PayPal raw responses when your transaction traffic is still on the older PayPal API: | Journal type | refusalReasonRaw | Description | | ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CaptureFailed | 10606 - Transaction rejected, please contact the buyer | The shopper cannot pay. For more information on why the capture failed, contact PayPal. | | CaptureFailed | 11607 - Duplicate request | This transaction could not be completed since it is duplicate. Check whether the shopper already attempted a transaction. | | Error | 10001: Internal Error | This indicates a technical issue on PayPal's side. For more information, contact PayPal. | | Error | 10002 : The user account is locked | Your PayPal account may be locked. For more information, contact PayPal. | | Error | 10002: Restricted account | PayPal merchant account has been restricted. Contact your PayPal account manager to resolve the issue. | | Error | 10212: Profile preference setting | Applies to subscription payments. The shopper's PayPal account is configured to automatically block certain payments. The shopper can adjust this in their PayPal account. | | Error | 10409: You're not authorized to access this info | There are multiple PayPal accounts set up on the same merchant account. | | Error | 10525: Invalid Data | The transaction cannot be processed because the amount is zero. If you want to make a zero-auth transaction to validate payment details, make sure that you are sending the [required parameters to save payment details](/payment-methods/paypal/web-component#create-a-token). | | Error | 10729: Shipping Address State Empty | For transactions in the US and Canada, the [deliveryAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress) has to include a `stateOrProvince`. | | Error | 10730: Shipping Address Postal Code Empty | The [deliveryAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress) has to include a `postalCode`. | | Error | 11451: Billing Agreement Id or transaction Id is not valid | The transaction failed because the token used for the recurring transaction was created from a different merchant account. Make sure to use the recurring details created on the same merchant account. | | Error | 11452: Merchant not enabled for reference transactions | You tried to either [create or use a token](/online-payments/tokenization), but do not have the [recurring feature enabled](/payment-methods/paypal/web-component#enable-recurring-payments) on your PayPal account. Contact PayPal to resolve the issue. | | Error | 11547: Recurring payments feature is not currently available; try again later | You tried to either [create or use a token](/online-payments/tokenization), but do not have the [recurring feature enabled](/payment-methods/paypal/web-component#enable-recurring-payments) on your PayPal account. Contact PayPal to resolve the issue. | | Error | 11547: Permission denied | Your PayPal account does not have the required API permissions. For instructions, see [Set up PayPal for marketplaces](/payment-methods/paypal/setup-paypal-marketplaces#marketplace-account). If the problem persists, contact PayPal. | | Error | 11601: Request for billing address failed | The **Request billing address** feature is not enabled on your PayPal account. Contact PayPal to have it enabled. | | Refused/Error | XXXXX: Transaction refused because of an invalid argument. See additional error message | No specific reason provided. For more information, refer to [PayPal's API Error Codes](https://developer.paypal.com/docs/nvp-soap-api/errors/). | | Refused | 10201: Agreement cancelled | The billing agreement of a recurring payment has been canceled on PayPal's side. You can either retry the payment with another token, or [create a new token](/online-payments/tokenization). | | Refused | 10204: Denied | The shopper's PayPal account is closed or restricted. The shopper should contact PayPal to resolve the issue. | | Refused | 13122: Transaction refused | This transaction cannot be completed because it violates the PayPal User Agreement. For more information, contact PayPal. | | Refused | 10417: Transaction cannot complete | This payment failed. PayPal recommends that you ask the shopper to retry the payment using another payment method from their PayPal wallet. | | Refused | 10486: This transaction could not be completed | The transaction failed due to a bad funding source; for example, the payment exceeded the shopper's card limit. | | RefundFailed | 10002: You do not have permission to make this API call | Your PayPal does not have the required API permissions. See [Set up PayPal](/payment-methods/paypal/setup-paypal-direct-merchants) or [Set up PayPal for marketplaces](/payment-methods/paypal/setup-paypal-marketplaces/) If the problem persists, contact PayPal. | | RefundFailed | 10007: Permission denied - You do not have permission to refund this transaction | This issue is related to the permissions you have on PayPal's side. For more information, refer to [PayPal documentation](https://www.paypal.com/au/smarthelp/article/why-did-i-get-api-error-code-10007-ts1124). | | RefundFailed | 10009: You do not have a verified ACH | You can receive this response in the following scenarios:- Your PayPal account does not have enough funds for the refund. - You haven't verified the bank account associated to your PayPal account. - Your PayPal account doesn't have a bank account associated to it.Contact PayPal to resolve the issue. | ## Pix raw responses | Error Code | Reject Reasons for Refund Failed | Error description | Action suggestion | | ---------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | AB03 | Settlement aborted due to timeout. | The waiting time for the ISPB/Shopper bank to get back to us was very long. | It is suggested that a new refund attempt be made. | | ED05 | Settlement of the transaction has failed. | There has been an Unexpected Failure at the ISPB/Shopper bank. (This failure encompasses situations such as timeouts and other forms of refusal that are not specifically mapped by the shopper bank). | It is suggested that a new refund attempt be made. | | AC07 | Creditor account number closed. | The bank account associated with the shopper is in a state of permanent cancellation or temporary blocking. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | DS04 | The order was rejected by the Bank side (for reasons concerning content). | Refund rejected due to internal ISPB/Receiving bank issues. | It is suggested that a new refund attempt be made after the hopper has made contact with their bank. | | AC06 | Account specified is blocked, prohibiting posting of transactions against it. | The bank account associated with the shopper is in a state of permanent cancellation or temporary blocking. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | AB09 | Transaction stopped due to error at the Creditor Agent. | There has been an Unexpected Failure at the ISPB/Shopper bank. (This failure encompasses situations such as timeouts and other forms of refusal that are not specifically mapped by the shopper bank). | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | - | Creditor account number and/or branch is invalid or missing. | The bank account associated with the shopper is in a state of permanent cancellation or temporary blocking. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | AG03 | Transaction type not supported/authorized on this account. | ISPB/Shopper bank has not authorized transactions to that bank account. Example: Transfer to salary account. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | AM09 | Amount received is not the amount agreed or expected. | ISPB/Shopper bank rejected the full or partial reversal of the transaction. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | AM02 | Specific transaction/message amount is greater than allowed maximum. | ISPB/Shopper bank rejected the full or partial reversal of the transaction. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | AC14 | Creditor account type missing or invalid. | Película account associated with the shopper is in a state of permanent cancellation or temporary blocking. | It is suggested that a new refund attempt be made after the shopper has made contact with their bank. | | DT05 | Associated message, payment information block or transaction was received after agreed cut-off date. | Refund request made after 90 days. | The refund operation will not be successful through the standard flow, in accordance with the rules established by the Central Bank of Brazil (BACEN). | ## Ratepay raw responses | Journal type | refusalReasonRaw | Description | | ------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CaptureFailed | 2307 : Invalid item quantity/amount in request (150) | A technical error occurred. Ensure that you are sending correct information in the `modificationAmount` and `additionalData.openinvoicedata` fields of your [capture request](/payment-methods/ratepay/api-only/#capture-the-payment), and retry the capture. The information in `additionalData.openinvoicedata` must be the same as what you provided in `lineItems` in your authorization request. | | CaptureFailed | 2300 : Request basket not valid {message} unknown item (150) | A technical error occurred. Ensure that you are sending correct information in the `modificationAmount` and `additionalData.openinvoicedata` fields of your [capture request](/payment-methods/ratepay/api-only/#capture-the-payment), and retry the capture. The information in `additionalData.openinvoicedata` must be the same as what you provided in `lineItems` in your authorization request. | | CaptureFailed | 1000 : technical error (150) | A technical error has occurred on Ratepay's end. Retry the capture after a short period of time. | | CaptureFailed | 102 : Risk management processing error (150) | The processing of the capture request was not successful. Check your request and retry after a short period of time. | ## Sepa Direct Debit raw responses | Journal type | refusalReasonRaw | Description | | ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------ | | Error | 400 | Bad Request - A parameter is missing or invalid. | | Error | 00\_400 | Bad Request - A parameter is missing or invalid. | | Refused | 29\_001 | Request Data Could Not Be Processed - The request is missing required fields or contains invalid data. | | Refused | 30\_005 | Request Data Could Not Be Processed - Balance account closed. | | Refused | 30\_014 | Request Data Could Not Be Processed - Account holder closed. | | Refused | 30\_016 | Request Data Could Not Be Processed - Account misses capabilities. | | Refused | 30\_081 | Request Data Could Not Be Processed - Invalid transfer information provided. | | Refused | 422 | Request Data Could Not Be Processed - Declined by acquirer. | | Error | 161 | Invalid IBAN. | | Error | 907 | Payment details are not supported for this country/ MCC combination. | | Error | 500 | Internal Server Error. | | CaptureFailed | 400 | Bad Request - A parameter is missing or invalid. | | CaptureFailed | 00\_400 | Bad Request - A parameter is missing or invalid. | | CaptureFailed | 29\_001 | Request Data Could Not Be Processed - The request is missing required fields or contains invalid data. | | CaptureFailed | 30\_005 | Request Data Could Not Be Processed - Balance account closed. | | CaptureFailed | 30\_014 | Request Data Could Not Be Processed - Account holder closed. | | CaptureFailed | 30\_016 | Request Data Could Not Be Processed - Account misses capabilities. | | CaptureFailed | 30\_081 | Request Data Could Not Be Processed - Invalid transfer information provided. | | CaptureFailed | 422 | Request Data Could Not Be Processed - Declined by acquirer. | | CaptureFailed | NO\_RESPONSE\_WITHIN\_TIMEOUT | Error when attempting transfer : NO\_RESPONSE\_WITHIN\_TIMEOUT. | ## Star raw responses These are the raw responses from Star for refused or canceled transactions. | Response Code | Description | | ------------- | ------------------------ | | 34 | Suspected fraud, capture | | 42 | No universal account | | 52 | No checking account | ## Swish raw responses | Journal type | refusalReasonRaw | Description | | ------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RefundFailed | DBER : Internal error | Internal error on Swish side. Retry the refund after 1 hour. | | RefundFailed | TM01 : Swish timed out before the payment was started | Issuer or Swish timeout. Retry the refund after 1 hour. | | RefundFailed | UNKW : Unknown error | Unknown error from Swish. Retry the refund after 1 hour. | | RefundFailed | RF07 : Transaction declined | Retry the refund after 1 hour. If the problem persists contact the merchant bank. | | RefundFailed | Error when attempting transfer : IOEXCEPTION\_RECEIVED | Failure to connect to Swish. Retry the refund after 1 hour. | | RefundFailed | 429 : Too many requests | Too many requests. Retry the refund after 1 hour. | | RefundFailed | RF09 : Refund already in progress | Refund already in progress. Retry the refund after 1 hour. | | RefundFailed | Error when attempting transfer : CONVERTER\_RESPONSE | Adyen couldn’t interpret the acquirer’s response. Retry the refund after 1 hour. | | RefundFailed | Error when attempting transfer : NO\_RESPONSE\_WITHIN\_TIMEOUT | Swish server is not reachable. Retry the refund after 1 hour. | | RefundFailed | TA01 : Technical error | Technical error in settlement. It could be that the banks did not respond on time or had an issue during settlement. Retry the refund after 1 hour. | | RefundFailed | ACMT07 : Payee not Enrolled | The payee (shopper) is not enrolled to Swish. Refund outside Adyen platform. | | RefundFailed | FF10 : Bank system processing error | Bank system processing error. Retry the refund after 1 hour. | | RefundFailed | RF08 : Amount value is too large, or amount exceeds the amount of the original payment | Amount value is too large or amount exceeds the amount of the original payment minus any previous refunds. | | RefundFailed | RF02 : Original Payment not found or original payment is more than 13 months old | Original payment not found or original payment is more than 13 months old. Refund outside Adyen platform. | | RefundFailed | PA01 : Unprocessable entity | Reasons for this error could be that parameter is incorrect in the request, or something is wrong with the certificate, or the merchant is not connected to Adyen as a technical supplier. Get in touch with Adyen support to determine the root cause. | | RefundFailed | AG09 : The payee is not enrolled to Swish | The shopper must contact their bank and check their agreement. | | Refused | RF07 : Transaction declined | Decline in bank validation. For more information have the shopper contact their bank. | | Refused | DECLINED : The payer declined to make the payment | The payer declined to make the payment. | | Refused | BANKIDCL : Payer cancelled BankId signing | The payer cancelled the BankId signing. | | Refused | BANKIDONGOING : BankID already in use | The payer’s BankID is already in use. | | Refused | BANKID : BankID timed out | The payer's BankID has timed out. | | Refused | UNKW : Unknown error. | Unknown error from Swish. | | Refused | AM21 : Transaction amount exceeds Swish limit agreed between bank and payer for given period | Transaction amount exceeds Swish limit agreed between bank and payer for given period. Please inform the payer to contact their bank for more information on how to adjust the Swish limits. | | Refused | No response from ACM | Swish did not respond within 30 seconds which resulted in a timeout. | | Refused | TA01 : Technical error | Technical error. | | Refused | AM02 : Amount value is too large | Amount value is too large. | | Refused | NARR : Reason is provided as narrative details in the additional reason information | Error in settlement. It could be that the banks did not respond on time or had an issue during settlement. | | Refused | AB06 : Settlement status unknown. Credit step will not happen to creditor | Rejected by the banks during the settlement step. | | Refused | FF10 : Bank system processing error | Bank system processing error. | | Refused | BANKIDUNKN : BankID is not able to authorize the payment | BankID is not able to authorize the payment. | | Refused | RR04 : Regulatory Reason | Regulatory Reason. Sent by debtor/creditor bank due to regulatory reasons e.g. fraud. | | Error | No response from ACM | Swish did not respond within 30 seconds which resulted in a timeout. | | Error | PA01 : Unprocessable entity | Reasons for this error could be that a parameter is incorrect in the request, or something is wrong with the certificate, or the merchant is not connected to Adyen as a technical supplier. Get in touch with Adyen support to determine the root cause. | | Error | ACMT07 : Payee not Enrolled | The payee (shopper) is not enrolled to Swish. | | Error | RP06 : A payment request already exist for that payer. Only applicable for Swish e-commerce | A payment request already exists for that payer. Only applicable for Swish e-commerce. | ## TWINT raw responses | Journal type | Response | Description | | ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Refused | 103: Declined by the issuer | The transaction was declined by the issuer. Ask the shopper to contact their bank for more information. | | Refused | 1301/1302 Shopper removed the recurring agreement | The shopper has canceled their recurring payment. | | Refused | 103:Payment aborted by the customer | The shopper did not complete the payment. | | Error | No response from ACM | Adyen was not able to connect with TWINT, which resulted in a timeout. | ## See also * [Refusal reasons](/development-resources/refusal-reasons/) * [Mapping to Visa system integrity fee categories](/development-resources/raw-acquirer-responses/visa-integrity-fees/) * [Terminal API raw responses](/point-of-sale/error-scenarios/raw-acquirer-responses) --- # Source: https://docs.adyen.com/development-resources/raw-acquirer-responses/visa-integrity-fees.md Section: Development resources Title: Mapping to Visa system integrity fee categories Description: For your retry logic, map raw responses to Visa fee categories related to excessive retries and data quality. --- title: "Mapping to Visa system integrity fee categories" description: "For your retry logic, map raw responses to Visa fee categories related to excessive retries and data quality." url: "https://docs.adyen.com/development-resources/raw-acquirer-responses/visa-integrity-fees" source_url: "https://docs.adyen.com/development-resources/raw-acquirer-responses/visa-integrity-fees.md" canonical: "https://docs.adyen.com/development-resources/raw-acquirer-responses/visa-integrity-fees" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Mapping to Visa system integrity fee categories For your retry logic, map raw responses to Visa fee categories related to excessive retries and data quality. [View source](/development-resources/raw-acquirer-responses/visa-integrity-fees.md) To encourage businesses to comply with certain processing standards, Visa charges system integrity fees. These fees are related to excessive retries of failed transactions, and excessive numbers of transactions that failed due to incorrect payment details. The Adyen risk engine helps to avoid such fees. If you have built your own retry logic, in order to avoid Visa system integrity fees, you need to identify if you can or cannot retry a failed Visa transaction. To do this, you can use the raw response from your transaction responses. The raw response maps to categories that Visa uses to determine the fees. ## Requirements | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. | | **Setup steps** | Before you begin, in your Customer Area [enable receiving raw responses](/development-resources/raw-acquirer-responses#receive-raw-responses). | ## Categories of system integrity fees The Visa system integrity fees consist of two fee types: * An **excessive retry fee** for failed transactions that are retried too many times. * A **data quality fee** that is applied if the number of transactions that failed because you provided incorrect data exceeds a monthly threshold. To calculate those fees, Visa divides failed transactions into four categories. Each category has specific rules for the type of fee that is applied and how many retries are allowed. The category that a failed transaction belongs to, is indicated using the raw response. * **Category 1: Issuer will not approve**\ Transactions are declined with a raw response in category 1 if a retry will never succeed. This is the case, for example, when the card is blocked, lost, or stolen, or never existed. Do not retry the transaction. Visa charges an excessive retry fee if you retry the transaction. * **Category 2: Issuer cannot approve at this time**\ Transactions are declined with a raw response in category 2 if it is possible that a retry will succeed later. This is the case, for example, if there was a system failure or if the cardholder had insufficient funds. You can retry the transaction up to 15 times in a 30-day period. Visa charges excessive retry fees if you exceed this limit. * **Category 3: Issuer cannot approve with these details**\ Transactions are declined with a raw response in category 3 if there was something wrong with the provided card details. This is the case, for example, if the account number, CVV, or expiry date is incorrect. You can retry the transaction up to 15 times in a 30-day period. Visa charges excessive retry fees and data quality fees if you exceed this limit. * **Category 4: Generic response codes**\ This category is for transactions that are declined with a raw response that does not belong to any of the other categories. The most frequent refusal reason, **05: Do not honor**, falls into this category. You can retry the transaction up to 15 times in a 30-day period. Visa charges excessive retry fees if you exceed this limit. ## Mapping of raw responses to categories When receiving raw responses is enabled in your Customer Area, the transaction responses contain: * `refusalCodeRaw` (only available for Visa and Mastercard transactions through our own acquiring platform): the numeric part of the raw response. This represents the underlying scenario that caused the transaction to fail. * `refusalReasonRaw`: the full raw response including the raw refusal code. The following table shows the mapping of raw refusal codes and reasons to the four categories of Visa system integrity fees. | `refusalCodeRaw` | `refusalReasonRaw` | Retry? | | ---------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------- | | **Category 1: Issuer will not approve** | | | | 04 | 04: Pickup card | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 07 | 07: Pickup card, special conditions | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 12 | 12: Invalid transaction | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 14 | 14: Invalid Account Number (No such Number) | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 15 | 15: No such issuer | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 41 | 41: Pickup card (lost card) | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 43 | 43: Pickup card (stolen card) | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 46 | 46: Closed Account | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | 57 | 57: Transaction not permitted to cardholder | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | R0 | R0: Stop payment order | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | R1 | R1: Revocation of authorization order | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | R3 | R3: Revocation of all authorization | ![-x-](/user/data/smileys/emoji/x.png "-x-") | | **Category 2: Issuer cannot approve at this time** | | | | 03 | 03: Invalid merchant | Max 15x in 30 days | | 19 | 19: Re-enter transaction | Max 15x in 30 days | | 51 | 51: Insufficient funds | Max 15x in 30 days | | 59 | 59: Suspected fraud | Max 15x in 30 days | | 61 | 61: Exceeds withdrawal amount limits | Max 15x in 30 days | | 62 | 62: Restricted card | Max 15x in 30 days | | 65 | 65: Exceeds withdrawal frequency | Max 15x in 30 days | | 75 | 75: Allowable number of PIN-entry tries exceeded | Max 15x in 30 days | | 78 | 78: Blocked, First Used | Max 15x in 30 days | | 86 | 86: ATM malfunction | Max 15x in 30 days | | 91 | 91: Issuer or switch is inoperative | Max 15x in 30 days | | 93 | 93: Transaction cannot be completed | Max 15x in 30 days | | 96 | 96: System malfunction | Max 15x in 30 days | | N3 | N3: Cash service not available | Max 15x in 30 days | | N4 | N4: Cash request exceeds issuer limit | Max 15x in 30 days | | **Category 3: Issuer cannot approve with these details** | | | | 14 | 14: Invalid account number (No such Number) | Max 15x in 30 days | | 54 | 54: Expired card | Max 15x in 30 days | | 55 | 55: Incorrect PIN | Max 15x in 30 days | | 82 | 82: Negative Online CAM, dCVV, iCVV, or CVV results | Max 15x in 30 days | | N7 | N7: Decline for CVV2 failure | Max 15x in 30 days | | 1A | 1A: Additional customer authentication required | Max 15x in 30 days | | 70 | 70: PIN data required | Max 15x in 30 days | | **Category 4: Generic response codes** | | | | Any failed transaction with a raw refusal code not listed in the other categories. | | Max 15x in 30 days | ## See also * [What are Non-Transactional scheme fees?](https://help.adyen.com/en_US/knowledge/finance/invoices/what-are-non-transactional-scheme-fees?target=_blank) * [Raw responses](/development-resources/raw-acquirer-responses/) * [Risk management](/risk-management/) --- # Source: https://docs.adyen.com/development-resources/refusal-reasons.md Section: Development resources Title: Refusal reasons Description: Learn about the reasons why a payment authorisation can be refused. --- title: "Refusal reasons" description: "Learn about the reasons why a payment authorisation can be refused." url: "https://docs.adyen.com/development-resources/refusal-reasons" source_url: "https://docs.adyen.com/development-resources/refusal-reasons.md" canonical: "https://docs.adyen.com/development-resources/refusal-reasons" last_modified: "2023-08-07T09:31:00+02:00" language: "en" --- # Refusal reasons Learn about the reasons why a payment authorisation can be refused. [View source](/development-resources/refusal-reasons.md) ##### Test refusal reasons You can trigger these refusal reasons in our test environment by [their refusalReasonCode values](/development-resources/testing/result-codes#values-for-testing-result-reasons?target=_blank). When your payment authorization request is not successful, the response returns [HTTP status code](/development-resources/response-handling) `200` with a message of **OK**. Although an HTTP response status code of `200` means that the request was submitted correctly and Adyen processed it successfully, it does not necessarily mean that the payment or modification request was successfully executed. When the payment or modification request is unsuccessful, the `resultCode`, `refusalReason`, and `refusalReasonCode` describe the issue. To prevent malicious use, do not expose the details of the refusal reason to shoppers. ## Requirements | Requirement | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. | | **[Webhooks](/development-resources/webhooks)** | You will receive refusal reasons with the [Standard webhook](/development-resources/webhooks/webhook-types#event-codes?target=_blank). You don't need to subscribe to additional webhooks. | ## Example refusal reason **Refusal reason object** ```json { "pspReference": "851563882585825A", "refusalReason": "Expired Card", "resultCode": "Refused", "refusalReasonCode": "6" } ``` | Parameter | Description | | ------------------- | ------------------------------------------------------------------------------- | | `refusalReason` | A short explanation for why the payment was refused. | | `resultCode` | The category for the refused payment: **Refused**, **Error**, or **Cancelled**. | | `refusalReasonCode` | A numeral corresponding to the refusal reason. | ## Refusal responses The following are all the possible `refusalReasonCode` and `refusalReason` values: | refusalReasonCode | refusalReason | Description | | ----------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | (none) | Sometimes `refusalReasonCode` **0** is returned along with `resultCode` **Authorised**. When this happens, ignore the refusal reason code. The transaction succeeded. | | 2 | Refused | The transaction was refused. | | 3 | Referral | Referrals. | | 4 | Acquirer Error | The transaction did not go through due to an error that occurred on the acquirer's end. | | 5 | Blocked Card | The card used for the transaction is blocked, therefore unusable. | | 6 | Expired Card | The card used for the transaction has expired. Therefore it is unusable. | | 7 | Invalid Amount | An amount mismatch occurred during the transaction process. | | 8 | Invalid Card Number | The specified card number is incorrect or invalid. | | 9 | Issuer Unavailable | It is not possible to contact the shopper's bank to authorize the transaction. | | 10 | Not supported | The shopper's bank does not support or does not allow this type of transaction. | | 11 | 3D Not Authenticated | 3D Secure authentication was not executed, or it did not execute successfully. | | 12 | Not enough balance | The card does not have enough money to cover the payable amount. | | 14 | Acquirer Fraud | Possible fraud. | | 15 | Cancelled | The transaction was cancelled. | | 16 | Shopper Cancelled | The shopper cancelled the transaction before completing it. | | 17 | Invalid Pin | The specified PIN is incorrect or invalid. | | 18 | Pin tries exceeded | The shopper specified an incorrect PIN more that three times in a row. | | 19 | Pin validation not possible | It is not possible to validate the specified PIN number. | | 20 | FRAUD | The pre-authorization risk checks resulted in a [fraud score](https://help.adyen.com/knowledge/risk/fraud-score/how-does-the-fraud-score-work) of 100 or more. Therefore, the transaction was flagged as fraudulent, and was refused. | | 21 | Not Submitted | The transaction was not submitted correctly for processing. | | 22 | FRAUD-CANCELLED | The sum of pre-authorization and post-authorization risk checks resulted in a [fraud score](https://help.adyen.com/knowledge/risk/fraud-score/how-does-the-fraud-score-work) of 100 or more. Therefore, the transaction was flagged as fraudulent, and was refused. | | 23 | Transaction Not Permitted | The following declined codes are mapped to this refusal reason:- "**57: Transaction not permitted to issuer/cardholder**" - "**57: Transaction not allowed for this merchant**" - "**58: Transaction not permitted to acquirer/terminal**" | | 24 | CVC Declined | The specified CVC ([card security code](/get-started-with-adyen/adyen-glossary/#card-security-code-cvc-cvv-cid)) is invalid. | | 25 | Restricted Card | The following decline codes are mapped to this refusal reason:- "**62: Restricted Card**" - "**62: Invalid card in this country**" | | 26 | Revocation Of Auth | Indicates that the shopper requested to stop a subscription.Decline codes such as the following are mapped to this refusal reason:- "**R1: Revocation of Authorization Order**" - "**R3: Revocation of All Authorizations Order**" - "**R0: Stop Payment Order**" | | 27 | Declined Non Generic | This response maps all those response codes that cannot be reliably mapped. This makes it easier to tell generic declines (for example, Mastercard "[05: Do not honor](https://developer.mastercard.com/repower/documentation/sandbox/#non-approved-transactions)" response) from more specific ones. | | 28 | Withdrawal amount exceeded | The transaction amount was higher than the withdrawal amount permitted for the shopper's card. | | 29 | Withdrawal count exceeded | The shopper exceeded the number of withdrawals that is permitted for the shopper's card. | | 31 | Issuer Suspected Fraud | Issuer reported the transaction as suspected fraud. | | 32 | AVS Declined | The address data the shopper entered is incorrect. | | 33 | Card requires online pin | The shopper's bank requires the shopper to enter the PIN. | | 34 | No checking account available on Card | The shopper's bank requires a checking account to complete the purchase. | | 35 | No savings account available on Card | The shopper's bank requires a savings account to complete the purchase. | | 36 | Mobile pin required | The shopper's bank requires the shopper to enter a mobile PIN. | | 37 | Contactless fallback | The shopper abandoned the transaction after they attempted a contactless payment and were prompted to try a different card entry method (PIN or swipe). | | 38 | Authentication required | The issuer declined the authentication exemption request and requires authentication for the transaction. Retry with 3D Secure. | | 39 | RReq not received from DS | The issuer or the scheme wasn't able to communicate the outcome via RReq. | | 40 | Current AID is in Penalty Box | The payment network cannot be reached. Retry the transaction with a different payment method. | | 41 | CVM Required Restart Payment | A PIN or signature is required. Retry the transaction. | | 42 | 3DS Authentication Error | The 3D Secure authentication failed due to an issue at the card network or issuer. Retry the transaction, or retry the transaction with a different payment method. | | 46 | Transaction blocked by Adyen to prevent excessive retry fees | Adyen's excessive retry prevention service blocked the transaction to make sure that you are not charged penalty fees. | | 50 | Token Revoked | The token granted to the merchant for recurring charges was disabled by the shopper. | ## See also * [Result codes](/online-payments/payment-result-codes) * [POS refusal reasons](/point-of-sale/error-scenarios/refusal-reasons-pos) * [Values for testing refusal reasons](/development-resources/testing/result-codes#values-for-testing-result-reasons) --- # Source: https://docs.adyen.com/development-resources/response-handling.md Section: Development resources Title: HTTP status codes Description: Learn how to handle HTTP responses. --- title: "HTTP status codes" description: "Learn how to handle HTTP responses." url: "https://docs.adyen.com/development-resources/response-handling" source_url: "https://docs.adyen.com/development-resources/response-handling.md" canonical: "https://docs.adyen.com/development-resources/response-handling" last_modified: "2021-05-12T10:56:00+02:00" language: "en" --- # HTTP status codes Learn how to handle HTTP responses. [View source](/development-resources/response-handling.md) After submitting an API call to Adyen, you receive a response to inform you that your request was received and processed. Depending on the HTTP status code of the response, you can build logic to handle errors. ## Requirements | Requirement | Description | | -------------------- | --------------------------------------------------------------------------- | | **Integration type** | An [online payments](/online-payments/build-your-integration/) integration. | ## HTTP responses | HTTP status code | HTTP status message | Description | | ------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | OK | Request processed normally. The request message was successfully processed and produced a response. The response message varies, depending on the request method and the requested data. | | [201](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) | Created | The request was successful and a new resource was created. | | [202](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202) | Accepted | The request was accepted, but has not been processed yet. This is not a guarantee that the request will be completed. | | [204](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204) | No Content | The server successfully fulfilled the request, and there is no additional content to send in the response. | | [301](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) | Moved Permanently | The resource you requested moved to a different location. | | [400](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400) | Bad Request | Problem reading or understanding request. The receiving server cannot understand the request because of malformed syntax. Do not repeat the request without first modifying it. Check the request for errors, fix them, and then retry the request. | | [401](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) | Unauthorized | Authentication required. You need to provide valid authentication credentials (username/password) to access the resource. | | [403](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) | Forbidden | Insufficient permission to process request. You do not have the appropriate user rights to access the request. Do not repeat the request. | | [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | Not Found | File not found. The server could not retrieve the resource you requested at the specified location. It is possible that the resource becomes available in the future. Usually, this happens when the URL you pass with the request is incorrect. You can make subsequent calls. | | [405](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405) | Method Not Allowed | The target resource does not support this method. | | [406](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406) | Not Acceptable | The server could not produce an acceptable response. | | [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) | Request Timeout | The server did not receive a complete request message within a certain amount of time. You can retry the request. | | [409](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409) | Conflict | Resource is locked. A conflict occurred because the request was already processed or is in progress. Identify the reason for the conflict and resolve it. You can retry the request if the API returns a transient error header with value **true**. | | [413](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) | Payload too large | The body of your request was too large. The maximum request size is 10 MB. Send the request again with a size of less than 10 MB. | | [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | Unprocessable Entity | Request validation error. The request is well-formed (syntactically correct), but semantically incorrect: the receiving server can read the request, but cannot understand it. | | [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) | Too Many Requests | You have sent too many requests in a short period. To handle this issue, implement a retry mechanism that uses [exponential backoff](https://www.rfc-editor.org/rfc/rfc2988#section-5) with [jitter](https://datatracker.ietf.org/doc/html/rfc4689#section-3.2.5). | | [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) | Internal Server Error | Server could not process request. The receiving server encountered an unexpected condition that prevents it from fulfilling the request. You can also receive a 500 status code when the request is incorrect, for example because of a missing or empty mandatory field. | | [501](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501) | Not Implemented | The server does not support the functionality required to complete the request. | | [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) | Gateway Timeout | The server, acting as a gateway or proxy, did not get a response from the upstream server in time. | ## Handle 200 responses Although an HTTP response status code of `200` means that the request was submitted correctly and Adyen processed it successfully, it does not necessarily mean that the payment or modification request was successfully executed. When the payment response includes a `resultCode` with a value of **Refused** or **Error**, a `refusalReason` field is added. Check the [refusal reason messages](/development-resources/refusal-reasons) to learn more about the possible issues with payment or modification requests. For example: * You send a [capture payment request](/online-payments/modify-payments). * The response to your capture request returns an HTTP response status code of `200`. This means: * We received your request. * We will execute a payment capture. * We still do not know if the capture operation will be successful or not. * We will let you know in the corresponding webhook event. * If the capture operation fails, for example, because the acquirer declines to accept the shopper's card, the payable amount for the transaction is not collected. * Based on your settings, you'll receive a [webhook](/development-resources/webhooks) message that includes the information about this capture example: * The  `pspReference` in this notification is the same as the  `pspReference` in the capture modification response. * The `success` field value is **false**, and the `reason` field includes a short message to explain the cause of the failure. ## Handle 4xx and 5xx responses In the following scenarios, the Adyen payments platform does not accept or store submitted requests: * The request does not pass validation. * The request violates a security constraint. * The request violates a configuration constraint. * An internal error occurs on the Adyen payments platform. In these cases, you receive an error message with an error code containing a description of the problem.\ In general, you should handle it as an exception. There is no charge for rejected payment requests accompanied by an error message. ## Debugging APIs While building your integration into the Adyen APIs, you can reach out to us if you need additional help. If you contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other), provide the `pspReference` returned in the header of the API response. The `pspReference` is a unique ID for that specific API request, and can be used by our Support Team to identify specific API calls. ## Error response fields In case of an error, the response object contains the following fields: | Field | Type | Required | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | Integer | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Returns the [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status). | | `errorCode` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The Adyen code that is mapped to the error message. | | `message` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A short explanation of the issue. | | `errorType` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Returns the type of error that was encountered. The following are allowed error types:- `internal` - `validation` - `security` - `configuration` | | `pspReference` | String | ![-x-](/user/data/smileys/emoji/x.png "-x-") | Returns the PSP reference associated with this error. If the `pspReference` is not present in the response body, check the HTTP headers of the response. | **Example error response** ```json { "status" : 403, "errorCode" : "901", "message" : "Invalid Merchant Account", "errorType" : "security" } ``` For the complete list of error codes and corresponding messages, see [Error codes and messages](/development-resources/error-codes). ## See also * [HTTP status codes on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) * [RFC 2616, section 6.1.1](https://tools.ietf.org/html/rfc2616) --- # Source: https://docs.adyen.com/development-resources/security.md Section: Development resources Title: Security resources Description: Keep your payment environment secure with our security resources. --- title: "Security resources" description: "Keep your payment environment secure with our security resources." url: "https://docs.adyen.com/development-resources/security" source_url: "https://docs.adyen.com/development-resources/security.md" canonical: "https://docs.adyen.com/development-resources/security" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Security resources Keep your payment environment secure with our security resources. [View source](/development-resources/security.md) In this part of the documentation, you ca find the essential resources, guidelines, and best practices to keep your applications and integrations secure. From API security to data encryption, the information aims to assist you in implementing robust security measures, maintaining compliance, and protecting your data. The following sections give an overview of the topics in this part of the documentation. ## Protect your integration with Adyen Learn how to keep your online payments integration or in-person payments integration secure. ## Identity and Access Management (IAM) Manage access to your applications using IAM practices such as: * Role-based access control (RBAC): implement RBAC for detailed access control. * Single sign-on (SSO): integrate SSO for streamlined and secure authentication. * Multifactor authentication (MFA): enhance security with MFA solutions. ## Secure coding guidelines Enhance the security of your applications by adhering to secure coding guidelines. * Avoiding common vulnerabilities: prevent threats such as SQL injection and cross-site scripting. * Secure development lifecycle: integrate security throughout your development process. * Code analysis tools: use static and dynamic analysis tools to identify vulnerabilities. ## API security best practices Protect your digital infrastructure by ensuring secure API usage. * Authentication: authenticate API requests to prevent unauthorized access. * Rate limiting and throttling: implement strategies to prevent misuse and ensure equitable access. ## Protecting sensitive data In your Adyen integration, protect sensitive information by implementing encryption good practices. * Encryption in transit: implement TLS/SSL to secure data during transmission. * PGP encryption: learn how to generate and upload a PGP key for the exchange of sensitive card data with Adyen. ## Incident detection and response Prepare for and respond to security incidents with our guidelines, including: * Monitoring and logging: establish effective monitoring and logging systems. * Alerting and incident response: develop workflows for responding to security alerts. * Forensic analysis: conduct thorough post-incident investigations and reviews. ## Next steps [Protecting your integration](/development-resources/security/integration-security) [Keep your online or in-person payments integration safe.](/development-resources/security/integration-security) [Identity and Access Management](/development-resources/security/iam) [Authentication best practices for a secure implementation.](/development-resources/security/iam) [Secure coding](/development-resources/security/secure-coding) [Enhance application security using secure development practices.](/development-resources/security/secure-coding) [API security](/development-resources/security/api-security) [Best practices for a secure use of API endpoints.](/development-resources/security/api-security) [Protecting sensitive data](/development-resources/security/sensitive-data) [Implement encryption good practices.](/development-resources/security/sensitive-data) [Handling incidents](/development-resources/security/incidents) [Best practices for incident detection and response.](/development-resources/security/incidents) --- # Source: https://docs.adyen.com/development-resources/security/api-security.md Section: Development resources Title: API security Description: Best practices for a secure use of APIs. --- title: "API security" description: "Best practices for a secure use of APIs." url: "https://docs.adyen.com/development-resources/security/api-security" source_url: "https://docs.adyen.com/development-resources/security/api-security.md" canonical: "https://docs.adyen.com/development-resources/security/api-security" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # API security Best practices for a secure use of APIs. [View source](/development-resources/security/api-security.md) The information in this page is for guidance only. It is not a complete list of all security measures you should take, and should not be taken as definitive advice. A critical aspect of protecting your digital infrastructure is ensuring secure API usage. The best practices discussed here focus on: * **API authentication**, to prevent unauthorized access. * **API rate limiting and throttling**, to prevent misuse and ensure equitable access. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## API authentication APIs enable applications to exchange data and services. But such an exchange can only happen after authentication: the client application trying to access another application must prove that it is a legitimate user of the API. API authentication acts as a gatekeeper that grants access to authentic users and keeps cybercriminals out. To implement authentication for your own APIs, consider the following. * **API keys**: you let client applications authenticate their API requests by specifying an API key in the request header. You must make sure that API keys are protected, rotated, and not exposed in client-side code. * **OAuth 2.0**: this is a protocol for token-based authentication. Third-party applications get access to a user's resources without exposing the user's password, API key, or other credential. * **Multifactor authentication (MFA)**: you can encourage or require MFA to access your application, especially if the application handles sensitive data. The same principles are used for the authentication of your requests to Adyen APIs. * [API credentials](/development-resources/api-credentials): you create an API key or a basic authentication username and password in your Customer Area, and then specify this in the relevant [HTTP request header](/development-resources/api-authentication#api-key-authentication). * [OAuth for partners](/partners/oauth/): a partner is an organization that builds integrations, such as plugins, that enable merchants to accept payments with Adyen. If you are a partner, you can implement OAuth to request access to specific account resources of your customer (the merchant). When your customer authorizes your access request, you get a token that you can use to authorize API requests on their behalf. ## Rate limiting and throttling Rate limiting and throttling are ways to control the flow of traffic, in this case API calls. These techniques are crucial for protecting APIs from malicious use, such as Denial of Service (DoS) attacks, brute-force attacks, and scraping. Consider implementing the following. * **Distributed rate limiting**: limit the number of API requests per time period, and synchronize keeping track of the number of request per user between the various parts of your entire system. Use shared counters across API gateways. * **Dynamic throttling**: control the rate of API requests based on real-time traffic and user behavior. For example, for a trusted user you slow down the rate of requests less than when you are dealing with a new or suspicious user. * **Encryption of communications**: transmit data over HTTPS to encrypt the data during transit to protect it from eavesdropping and tampering. Also ensure you use the correct [Transport Layer Security (TLS)](/development-resources/security/sensitive-data/tls) configuration. * **Regular audits and tests**: carry out systematic security audits and penetration tests to discover weaknesses that could lead to vulnerabilities, and actual vulnerabilities. If any issues are found, address them immediately. ## See also * [API authentication types](/development-resources/api-authentication) * [Client-side authentication](/development-resources/client-side-authentication) --- # Source: https://docs.adyen.com/development-resources/security/iam.md Section: Development resources Title: Identity and access management Description: Authentication best practices for a secure implementation. --- title: "Identity and access management" description: "Authentication best practices for a secure implementation." url: "https://docs.adyen.com/development-resources/security/iam" source_url: "https://docs.adyen.com/development-resources/security/iam.md" canonical: "https://docs.adyen.com/development-resources/security/iam" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Identity and access management Authentication best practices for a secure implementation. [View source](/development-resources/security/iam.md) The information in this page is for guidance only. It is not a complete list of all security measures you should take, and should not be taken as definitive advice. Manage access to your applications with appropriate Identity and Access Management (IAM) practices: * **Role-based access control** to define access permissions based on user roles or functions. * **Single sign-on** for streamlined and secure authentication. * **Multifactor authentication** to enhance authentication by requiring an additional form of verification. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## Role-based access control Role-based access control (RBAC) is a security model that assigns permissions to users based on their roles within an organization. Roles can broadly relate to functions, job profiles, or departments. Or roles can relate to a [segregation of duties](https://en.wikipedia.org/wiki/Separation_of_duties) based on access permissions. Implementing RBAC ensures that users only have access to what is necessary for their role. This aligns with the "need to know" and "least privilege" principle of various compliance standards. You should document and regularly review your RBAC implementation. In the Adyen Customer Area you can set up your [account structure](/account/account-structure) with accounts, roles, and user permissions in accordance with RBAC. ## Single sign-on Single sign-on (SSO) is a user authentication process that allows a user to access multiple applications with a single set of login credentials. The Customer Area supports SSO based on the [Security Assertion Markup Language (SAML) 2.0 protocol](https://en.wikipedia.org/wiki/SAML_2.0). SSO solutions that use the SAML 2.0 protocol include Okta, Azure, and Microsoft AD FS. Extending your SSO solution to the Customer Area provides improved security for your Adyen integration through controlled user access. For example, when an employee leaves, you can remove their Customer Area access through the SSO solution. ## Multifactor authentication Multifactor authentication (MFA) adds an extra layer of security on top of login credentials, by requiring an additional form of verification, for example through SMS, email, or biometrics. This helps prevent unauthorized users from accessing an account, even if they have obtained the username and password. The Customer Area supports MFA with an authenticator app or with SMS. Each user can set up one authentication method per device and register two devices through MFA. ## See also * [Defining your account structure](/account/define-account-structure) * [Set up single sign on](/account/single-sign-on/set-up-sso) * [Set up multifactor authentication](/account/multifactor-authentication) --- # Source: https://docs.adyen.com/development-resources/security/incidents.md Section: Development resources Title: Handling incidents Description: Best practices for incident detection and response. --- title: "Handling incidents" description: "Best practices for incident detection and response." url: "https://docs.adyen.com/development-resources/security/incidents" source_url: "https://docs.adyen.com/development-resources/security/incidents.md" canonical: "https://docs.adyen.com/development-resources/security/incidents" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Handling incidents Best practices for incident detection and response. [View source](/development-resources/security/incidents.md) The information in this page is for guidance only. It is not a complete list of all security measures you should take, and should not be taken as definitive advice. To prepare for and respond to security incidents, you should implement: * **Effective monitoring and logging systems**, to collect extensive logs of system events, network traffic, and user activities, and to detect security events in real time. * **Workflows to alert and respond to security incidents**, including thorough post-incident investigations and reviews. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## Monitoring and logging A monitoring and logging system should detect security events in real time, enable a quick response to any security incidents, and offer a comprehensive forensic analysis of incidents. Security events should be detected across the entire IT environment. For guidelines, see the monitoring and logging resources of\ [NIST 800-94](https://csrc.nist.gov/pubs/sp/800/94/final), [ISO/IEC 27001](https://www.iso.org/standard/27001), and [PCI-DSS](https://www.pcisecuritystandards.org/document_library/?document=aily_log_monitoring). ### Comprehensive logging and data collection Logging is the cornerstone of security monitoring. Best practices are to collect extensive logs of system events, network traffic, and user activities, making sure to log both successful and unsuccessful attempts to gain access. This is especially\ relevant when critical assets like databases, apps, and admin accounts are involved. Some important aspects of an efficient logging strategy are: * **Detailed audit logs**: collect logs from applications, network devices, databases, and system events. In other words, collect logs from all layers. Make sure the logs include user authentication attempts, privilege escalations, configuration changes, and abnormal data access patterns. * **Centralized log management**: use a solution such as a **Security Information and Event Management (SIEM)** system to consolidate logs from various sources. A SIEM system simplifies the analysis and also ensures the logs are secure and remain available for later use. Log management also means encrypting the logs both in transit and at rest. Make sure the SIEM system can work with encrypted logs. * **Event correlation and analysis**: to identify complex attack patterns or persistent threats, you need to correlate log data across multiple systems. A SIEM system can help with that. It integrates log data from intrusion detection systems, firewalls, and user behavior analytics, and thus provides real-time insights into potential threats. ### Real-time monitoring and intrusion detection In addition to logging, real-time monitoring plays a crucial role in the early detection of security incidents. You can use an **Intrusion Detection and Prevention System (IDPS)** to monitor network traffic and host-based events, and flag suspicious behavior. In some cases, an IDPS can also automatically prevent attacks. Some important aspects of an IDPS-based monitoring strategy are: * **Diverse detection capabilities**: for full coverage, you should combine a network-based IDPS with a host-based IDPS. A network-based IDPS monitors traffic and flags unusual patterns, such as port scanning or unauthorized access attempts. A host-based IDPS detects unusual events at the system level, such as unauthorized file changes or abnormal processes. * **Anomaly- and signature-based detection**: a combination of flagging unusual activities and identifying known threats using predefined "signatures". * **Automation and alerting**: automated alerts for critical incidents, prioritized by severity. Automated preventive measures in response to critical incidents should also be part of this. ### Log management and retention for compliance To ensure compliance with regulations and to make incident response and post-incident investigation easier, good log management is vital. Some important aspects of log management are: * **Retention policies**: logs must be retained in accordance with legal, regulatory, and operational requirements. PCI-DSS suggests retaining logs for at least a year. Regular archiving ensures older logs remain accessible. * **Secure storage**: log data should be protected from data loss and tampering through encryption, access controls, and regular backups. The backup logs should be stored separately and securely. * **Continuous monitoring of log integrity**: by applying checksums or other cryptographic methods you can regularly verify that the logs have not been tampered with. ### Integration of SANS monitoring guidelines The [SysAdmin, Audit, Network, Security (SANS) Institute](https://www.sans.org/information-security-policy) recommends a layered approach to continuous monitoring that involves not just known attack paths but also unusual behaviors that can indicate a security breach. Some important SANS recommendations are: * **Comprehensive asset coverage**: logging and monitoring should cover all critical assets, including assets in the cloud and third-party services. * **Behavioral baselines**: these help to identify anomalies that do not match known attack methods or signatures. * **Proactive incident response**: integrating automation with regard to responses and workflows into the monitoring systems helps security teams respond to incidents in real-time. ## Alerting and incident response To mitigate the impact of security incidents, it is vital to detect, prioritize, and respond to alerts. Building effective alerting mechanisms and response workflows requires a combination of automation, predefined processes, and expertise. ### Setting up an effective alerting system Alerting is the bridge between detection and response. To avoid "alert fatigue" your system should also prioritize alerts. Some important aspects of an effective alerting system are: * **Automated threat detection**: the SIEM and IDPS systems that have been mentioned before are instrumental in generating automated alerts based on predefined thresholds. These systems filter out false positives and focus on high-fidelity alerts that require immediate investigation. * **Risk-based prioritization**: not all threats warrant the same level of response. According to [ISO/IEC 27001](https://www.iso.org/standard/27001) you should define risk categories for assets, for example, based on attack vector, system vulnerability, and potential business impact. This allows you to rank threats and ensure that high-priority incidents are escalated first. * **Real-time notifications**: make sure alerts are delivered through multiple channels, like email, SMS, or integrated communication tools. For high-severity cases, you can set up alerts to trigger immediate automatic containment actions such as blocking IP addresses or isolating network segments. ### Developing incident response workflows An incident response workflow is a series of coordinated actions to contain, eradicate, and recover from security incidents. You should set up, document, and test such a workflow. Some important aspects of an incident response workflow are: * **Preparation**: this involves developing and maintaining an incident response plan (IRP), training staff, and establishing communication channels. The plan should outline the roles and responsibilities of the key stakeholders including the incident response team (IRT). The IRT can consist of representatives from IT, legal, compliance, and business units, and must be equipped with forensic analysis software, containment mechanisms, and other necessary tools.\ To minimize confusion during high-stress incidents, make sure your plan includes playbooks, which are step-by-step guides to handle specific types of incidents. You should test these playbooks regularly. * **Detection and analysis**: after an alert is triggered, you need to determine if there is an actual security incident. Complex threats like advanced persistent threats can require deep analysis of event logs, traffic patterns, and system behavior.\ If an incident is confirmed, it must be categorized in terms of severity and possible impact on business operations. Such a categorization helps in activating the correct response protocols and escalating when necessary. * **Containment, eradication, and recovery**: you must contain a confirmed incident as fast as possible, to prevent further damage.\ First, you take temporary containment measures, such as blocking malicious IP addresses or compromised user accounts. Then, you identify and fix the root cause. This can involve patching vulnerabilities, removing malware, or deactivating accounts. And finally, you restore the systems to normal operation. You should do this in phases, while monitoring for any lingering threats. * **Post-incident review and lessons learned**: after an incident is resolved, you need to thoroughly review it for ways to improve your incident response workflow and training programs.\ All stakeholders should be involved in a formal debriefing of what worked, what did not work, and how the incident could have been handled better. This enables you to refine the playbooks and the detection systems.\ If there are any follow-up actions, these should be formally assigned to teams, to ensure accountability for addressing all aspects of the incident.\ You should also make sure that timelines, actions taken, and outcomes related to the incident are documented, for sharing with the key stakeholder, compliance, and future reference. ### Automating incident response While human oversight remains essential, automating certain incident response aspects enhances your ability to react to threats in real-time. Opportunities or automation include: * **Automated playbook execution**: for routine incidents, automated playbooks can initiate predefined containment actions and notify relevant personnel. This reduces both the pressure on the security teams, and the likelihood of human error in the early stages of incident response. * **Incident escalation and collaboration tools**: you can use an automated system to prioritize incidents and route them to the correct response team. Ideally, the whole incident response flow is integrated with collaboration tools so that all stakeholders are informed and aligned. For this, you can use an incident management platform. Such platforms track the progress of the response and provide real-time updates. ## See also * [ISO/IEC 27001](https://www.iso.org/standard/27001) * [NIST 800-94](https://csrc.nist.gov/pubs/sp/800/94/final) --- # Source: https://docs.adyen.com/development-resources/security/integration-security.md Section: Development resources Title: Protecting your Adyen integration Description: Best practices to mitigate security risks in your integration with Adyen. --- title: "Protecting your Adyen integration" description: "Best practices to mitigate security risks in your integration with Adyen." url: "https://docs.adyen.com/development-resources/security/integration-security" source_url: "https://docs.adyen.com/development-resources/security/integration-security.md" canonical: "https://docs.adyen.com/development-resources/security/integration-security" last_modified: "2022-05-23T10:52:00+02:00" language: "en" --- # Protecting your Adyen integration Best practices to mitigate security risks in your integration with Adyen. [View source](/development-resources/security/integration-security.md) The information in this page is for guidance only. It is not a complete list of all security measures you should take, and should not be taken as definitive advice. Attackers can try to steal card data by exploiting weaknesses in your systems. To protect your data, and that of your customers, make sure that you implement the security measures described on this page. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations with online payments or in-person payments. | ## Protect your online payments integration Most online attacks are related to security flaws in your checkout or payment pages. The security of your own webpages and apps is your responsibility, because Adyen has limited ability to prevent attacks in environments we do not control. * Read more about your responsibilities, and those of Adyen, in our [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide). * To make sure you grant access to your webpages and apps securely, check our guidance for [identity and access management](/development-resources/security/iam). ### Third-party components If you have vulnerable third-party components (scripts) in your webpage, attackers might be able to steal data in various ways, for example by making your website execute their own code. * The Payment Card Industry Data Security Standard (PCI DSS) v4.0.1 includes requirements related to script security in ecommerce. To help you comply with these requirements, we have several [script security recommendations](/development-resources/security/secure-coding). ## Protect your in-person payments integration Security risks with in-person payments are related to the payment terminals: physical tampering, and replacing terminals with tampered terminals. * Maintain an inventory of active and inactive terminals, and review it regularly. See the point-of-sale documentation for [what to do when a payment terminal is lost or stolen](/point-of-sale/managing-terminals/security-inspection#lost-or-stolen). * Update your terminals to the latest software as soon as possible. We strongly suggest you use [automatic updating](/point-of-sale/release-updating/). * Read the [PCI SSC guide on skimming prevention](https://www.pcisecuritystandards.org/documents/Skimming_Prevention_BP_for_Merchants_Sept2014.pdf?agreement=true\&time=1626706849342), which explains all forms of skimming, risk profiles, and the impact of skimming. It covers all the points listed below in depth. ### Prevent tampering To keep the data of your customers safe, make sure that malicious actors cannot access your payment terminals. * Place the terminals in a monitored environment, both during and outside of business hours. Be aware of suspicious activity around the terminal. * [Inspect your payment terminals](/point-of-sale/managing-terminals/security-inspection) to make sure they have not been tampered with. You must do this when you receive a new terminal and also at regular intervals after. * Verify the identity of anyone who requests access to the terminal, for example individuals claiming to be repair or maintenance personnel. Adyen terminal maintenance staff will never arrive without prior arrangement, so check that maintenance is planned. ### In-store measures * Make sure that the location of the payment terminal does not allow the PIN to be observed while the customer is entering it. Pay special attention to reflective surfaces nearby, cameras, or the position of the cashier with respect to the payment terminal. * Train your staff to instruct customers to hide their PIN while entering it on the payment terminal. ### Point to point encryption If you are using our [Point-to-Point Encryption (P2PE) solution](/development-resources/pci-dss-compliance-guide?tab=p2pe_2), implement all the advice described. You must also implement all the requirements in the [P2PE Instruction Manual (PIM)](https://www.adyen.com/legal/p2pe-instruction-manual). ## See also * [Allowlisting IP addresses](/development-resources/security/integration-security/allowlisting) * [Comparing E2EE and P2PE](/development-resources/e2ee-p2pe-comparison) * [PCI DSS compliance guide](/development-resources/pci-dss-compliance-guide) --- # Source: https://docs.adyen.com/development-resources/security/integration-security/allowlisting.md Section: Development resources Title: Allowlisting IP addresses Description: Best practices to manage IP addresses. --- title: "Allowlisting IP addresses" description: "Best practices to manage IP addresses." url: "https://docs.adyen.com/development-resources/security/integration-security/allowlisting" source_url: "https://docs.adyen.com/development-resources/security/integration-security/allowlisting.md" canonical: "https://docs.adyen.com/development-resources/security/integration-security/allowlisting" last_modified: "2026-02-03T11:35:00+01:00" language: "en" --- # Allowlisting IP addresses Best practices to manage IP addresses. [View source](/development-resources/security/integration-security/allowlisting.md) Allowlisting, formerly known as whitelisting, is the practice of allowing systems to only connect to specific other machines and blocking all other connections. If no security tooling is in place, all outbound requests to Adyen are allowed. This behavior is fully compatible with the Adyen platform. If you are implementing or planning to implement IP allowlisting, it can affect your integration with our platform. This page discusses our suggestions with regard to allowlisting implementations and managing outgoing and incoming IP addresses. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## Overview of allowlisting implementations Besides [Domain Name System (DNS)](https://www.cloudflare.com/learning/dns/what-is-dns/) resolution and domain-based allowlisting, any other form requires you to actively maintain and update Adyen’s IP addresses in your network configurations, which is why we recommend against it. The following table shows an overview of allowlisting implementations and how they can affect your integration. | Implementation | Effect | Our suggestion | | -------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------- | | [DNS resolution and domain-based allowlist](#dns-resolution-and-domain-base-allowlist) | Future-proof integration | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") Recommended | | [DNS resolution and IP allowlist](#dns-resolution-and-ip-allowlist) | Potentially failing connections | - Not recommended | | [Custom DNS record](#custom-dns-record) | Failing connections | ![-x-](/user/data/smileys/emoji/x.png "-x-") Do not use | | [Hardcoded IP addresses](#hardcoded-ip-addresses) | Failing connections. | ![-x-](/user/data/smileys/emoji/x.png "-x-") Do not use | ## DNS resolution and domain-based allowlist We recommend that you use this, because it makes your integration future-proof and is compatible with dynamic infrastructure changes. Your integration resolves domains and filters based on hostnames. DNS-based allowlisting allows access only to a predefined list of trusted domain names, blocking all others. You can do this by either: * Creating a domain allowlist in your web proxy. * Creating an object that automatically updates your firewall rules. By adding our top-level domains **adyen.com** and **adyenpayments.com** to your allowlist, you can connect to our platform, regardless of underlying IP address changes. ## DNS resolution and IP allowlist We do not recommend this, because it only works if you keep your lists of our IP addresses updated. If the allowlist is stale, and IP addresses change, your integration can break. Your integration resolves Adyen domains using DNS, but filters by IP address. You add specific IP addresses to your static allowlist, instead of relying on domains. This method requires more maintenance because you do not rely on DNS. You must keep the IP addresses in your allowlist up to date yourself. If Adyen introduces new IP addresses for a service, your infrastructure blocks all requests to the new IP addresses, and your requests fail. Adyen does not take responsibility for connection failures that result from expired IP address lists. ## Custom DNS record Do not use this, because multiple factors can lead to connection failures. If you use internal DNS records (for example, **adyen-proxy.internal.example.com**) or proxies, you will encounter the following issues: * Your request will contain an SNI header for your custom DNS record (**adyen-proxy.internal.example.com**) instead of our platform (**checkout-live.adyen.com**), which can cause our platform or intermediate services to drop the request. * Your custom DNS record will highly likely contain a single, hardcoded IP address. This will result in the same issues described for [hardcoded IP addresses](#hardcoded-ip-addresses). ## Hardcoded IP addresses Do not use this, because Adyen frequently changes or retires IP addresses during infrastructure updates or DDoS protection service activation. Using hardcoded IP addresses in your application code is highly likely to cause failures in your system. If you do not update the hardcoded list of IP addresses any time Adyen changes IP addresses, your connections fail. Depending on your development lifecycle, it can take you a significant period of time to resolve your connection failures. ## Manage outgoing and incoming IP addresses This section provides the outgoing IP addresses to allowlist, recommendations for incoming IP addresses, and guidance on how Geo-IP-based firewalling can affect your connection. ### Outgoing IP allowlisting (from you to Adyen) 1. Use the following list of outgoing IP addresses. These are the IP addresses to our endpoints. * 82.199.87.128/26 * 82.199.90.136/29 * 82.199.90.160/27 * 213.52.172.0/25 * 62.146.248.0/21 * 85.184.228.0/22 * 91.212.42.0/24 * 135.84.148.0/22 * 147.12.16.0/20 * 185.101.196.0/22 * 145.63.64.0/18 2. Make sure that you **always rely on DNS** to provide you with the IP address information for the endpoint you are trying to connect to. We can change IP addresses that certain endpoints listen to within our IP ranges, so you can allowlist the ranges provided to accommodate for that. ### Incoming IP allowlisting (from Adyen to you) Adyen’s platform initiates outbound connections to your systems, such as sending webhooks. If your firewall restricts inbound traffic, you may need to allowlist Adyen’s outgoing IP addresses. We strongly recommend using dynamic DNS-based allowlisting to avoid breakages when IP addresses change due to scaling, failover, or DDoS mitigation. To dynamically resolve the current IPs Adyen uses for outbound traffic: 1. Run the following command: ```bash dig +short out.adyen.com ``` 2. Use the result as the latest, up-to-date list of IPs Adyen can use to connect to your endpoints. ### Geo-IP-based firewalls and regional blocking Some enterprise security products enforce policies that block connections to certain regions. These products use [Geo-IP mapping](https://en.wikipedia.org/wiki/Geolocation_software#Data_sources) to link destination IP addresses to geographic locations. To determine the physical location of a server by its IP address, Geo-IP mapping uses various sources such as registration records and routing data. However, the resulting mappings are inherently unreliable. Because internet routing constantly changes, they do not accurately reflect the current state of the network. As a result, your security policy can block connections when the destination is incorrectly identified as a restricted location. To avoid false positives, ask your IT team to explicitly allowlist [Adyen's domains and IP ranges](#outgoing-ip-allowlisting-from-you-to-adyen). Allowing these domains and IP ranges bypasses the Geo-IP lookup and ensures reliable connectivity. ## See also * [Transport Layer Security (TLS)](/development-resources/security/sensitive-data/tls) * [Security resources](/development-resources/security) --- # Source: https://docs.adyen.com/development-resources/security/secure-coding.md Section: Development resources Title: Secure coding Description: Enhance the security of your applications through secure development practices. --- title: "Secure coding" description: "Enhance the security of your applications through secure development practices." url: "https://docs.adyen.com/development-resources/security/secure-coding" source_url: "https://docs.adyen.com/development-resources/security/secure-coding.md" canonical: "https://docs.adyen.com/development-resources/security/secure-coding" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Secure coding Enhance the security of your applications through secure development practices. [View source](/development-resources/security/secure-coding.md) The information in this page is for guidance only. It is not a complete list of all security measures you should take, and should not be taken as definitive advice. Attackers can try to steal card data by exploiting weaknesses in your systems. To protect your data, and that of your customers, make sure that you implement the security measures described on this page. Secure coding practices are essential for protecting your applications and systems from attackers and ensuring the integrity of your data. The most important secure coding practices are to: * **Avoid common vulnerabilities** to prevent threats such as SQL injection and cross-site scripting. * **Implement a secure development lifecycle** to integrate security throughout your development process. * **Use code analysis tools** to identify vulnerabilities through static and dynamic analysis. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## Common vulnerabilities Vulnerabilities in applications can be exploited by attackers to steal data or disrupt services. Here are some of the most frequently seen vulnerabilities and how to avoid them. * **SQL injection**: an attacker is able to execute SQL code by manipulating input fields. To prevent SQL injection, use parameterized queries or prepared statements to ensure that user input is treated as data, not executable code. Validate and sanitize all input to ensure the input conforms to expected formats. * **Cross-site scripting (XSS)**: an attacker injects malicious scripts into web pages that users are viewing. To prevent XSS, encode output data to ensure that content provided by the user is treated as text, not executable code. Use secure frameworks that automatically handle encoding. * **Cross-site request forgery (CSRF)**: after users have authenticated with an application, an attacker tricks the users into performing actions they did not intend to do. To prevent CSRF, implement anti-CSRF tokens that validate requests and ensure they originate from legitimate sources. Require re-authentication for sensitive actions. * **Insecure direct object references (IDOR)**: an application exposes internal implementation objects like files or database keys, enabling an attacker to gain access. To prevent IDOR, implement access controls and authorization checks. Avoid exposing internal object references in URLs or form parameters. ## Secure development lifecycle Secure development lifecycle refers to integrating security into every phase of the software development process. The following table gives examples of what you can do in the main software development phases. | Development phase | Security actions | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Planning | Define security requirements based on business needs and regulatory compliance. Use threat modeling to identify potential threats and attack vectors. | | Design | Create a secure architecture based on principles such as least privilege and secure defaults. Perform security design reviews. | | Implementation | Follow secure coding guidelines to avoid vulnerabilities. Perform code reviews. | | Testing | Use static analysis tools to identify vulnerabilities in the source code without executing it. Use dynamic analysis tools and penetration testing to evaluate the security of the running application. | | Deployment | Ensure a secure configuration of the deployment environment, including servers, databases, and network components. Implement monitoring and logging to detect and respond to security incidents in real-time. | | Maintenance | Set up patch management to address newly discovered security issues. Set up and maintain an incident response plan to quickly address security breaches. | ## Code analysis tools Code analysis tools are intended to identify security vulnerabilities, ensure code quality, and maintain compliance with secure coding standards. Reasons to use code analysis tools are: * **Early detection**: code analysis tools help detect vulnerabilities early in the development process, reducing the cost and effort it takes to fix security issues later. * **Consistency**: code analysis tools provide a consistent and automated way to enforce security policies. * **Comprehensive coverage**: code analysis tools can analyse a large codebase more thoroughly and quickly than a human reviewer. To benefit the most from code analysis tools, you should: * Integrate the tools into your development environment and CI/CD pipeline. * Customize the tools to match your security requirements and coding standards, and to focus on the most critical issues for your application. * Perform regular scans, for example during commits, build processes, and pre-release stages, to catch new vulnerabilities introduced during development. * Use the reporting features to review the results of code scans, and prioritize fixing any identified vulnerabilities. ## See also * [OWASP top ten security risks and mitigations](https://owasp.org/www-project-top-ten/) * [OWASP's cheat sheets](https://cheatsheetseries.owasp.org/Glossary.html) * [NIST Secure Software Development Foundation](https://csrc.nist.gov/Projects/ssdf) --- # Source: https://docs.adyen.com/development-resources/security/sensitive-data.md Section: Development resources Title: Protecting sensitive data Description: Protect sensitive information by implementing encryption good practices. --- title: "Protecting sensitive data" description: "Protect sensitive information by implementing encryption good practices." url: "https://docs.adyen.com/development-resources/security/sensitive-data" source_url: "https://docs.adyen.com/development-resources/security/sensitive-data.md" canonical: "https://docs.adyen.com/development-resources/security/sensitive-data" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Protecting sensitive data Protect sensitive information by implementing encryption good practices. [View source](/development-resources/security/sensitive-data.md) Adyen implements many security practices to protect the confidentiality and integrity of merchant data and systems. However, in your Adyen integration, you too need to protect sensitive information, by implementing encryption good practices. * **Encryption in transit**: implement TLS/SSL to secure data during transmission. * **PGP encryption**: learn how to generate and upload a PGP key for the exchange of sensitive card data with Adyen ## Next steps [Transport Layer Security (TLS)](/development-resources/security/sensitive-data/tls) [Protect data during transmission using TLS.](/development-resources/security/sensitive-data/tls) [PGP encryption](/development-resources/security/sensitive-data/pgp-encryption) [Register your PGP key with Adyen.](/development-resources/security/sensitive-data/pgp-encryption) --- # Source: https://docs.adyen.com/development-resources/security/sensitive-data/pgp-encryption.md Section: Development resources Title: PGP encryption Description: Register your PGP key with Adyen. --- title: "PGP encryption" description: "Register your PGP key with Adyen." url: "https://docs.adyen.com/development-resources/security/sensitive-data/pgp-encryption" source_url: "https://docs.adyen.com/development-resources/security/sensitive-data/pgp-encryption.md" canonical: "https://docs.adyen.com/development-resources/security/sensitive-data/pgp-encryption" last_modified: "2023-08-29T11:24:00+02:00" language: "en" --- # PGP encryption Register your PGP key with Adyen. [View source](/development-resources/security/sensitive-data/pgp-encryption.md) PGP keys are used to sign, encrypt, and decrypt files and communications. To protect sensitive information, Adyen uses PGP encryption for: * [Batch processing files](/development-resources/batch-processing/advanced-sftp-batch-files#pgp-encryption). * Reports (if [encrypted](/reporting/automatically-get-reports#encrypt-report-files)). * Other files that contain sensitive card data, such as [payment data migration files](/development-resources/migrating-payment-data) or [Account Updater result files](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/accountupdater-result-file). For those use cases you need to: 1. [Generate](#step-1-generate-new-pgp-key) a PGP key. 2. [Register the PGP key with Adyen](#step-2-register-pgp-key-with-adyen). It is also important to [update your PGP key](#update-pgp-key-expiry) before it expires. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | A payments integration with Adyen. | | **Limitations** | For a merchant account you can only register PGP keys for encrypted reports and Account Updater. | | **Setup steps** | To receive PGP expiry messages by email and/or in the Notification center **in the Customer Area, [subscribe to **Encryption events** notifications](/account/notification-center/#configure-notification-settings). | ## GnuPG command line tools There are several tools available for managing PGP keys. In this tutorial, we explain how to generate or update a PGP key using the [GnuPG](https://www.gnupg.org/) command line tools. These are available for Windows, Mac, and Linux. Before using this tutorial, make sure you have GnuPG command line tools installed on your computer. To check if the GnuPG command line tools are installed: 1. Open a command line application (such as *Terminal* or *PowerShell*). 2. Run the command `gpg --version`.\ If you get a **command not found** error message, [download and install GnuPG](https://www.gnupg.org/download/). ## 1. Generate a new PGP key To generate a PGP key using the [GnuPG](https://www.gnupg.org/) command line tools: 1. Open a command line application, such as *Terminal* or *PowerShell*. 2. Use the following command to create a GPG key pair. ```bash $ gpg --full-generate-key ``` 3. When asked which kind of key you want, press **Enter** to accept the default (RSA and RSA). 4. Enter a key size. We recommend entering at least **4096** (4096 bits). 5. Enter the key validity. This is the length of time before the key expires. For example, to set the expiry period to 5 years, enter `5y`. We recommend setting an expiry period for your PGP key. 6. Enter your user ID information, including your name and email address. 7. Enter **o** (indicating "okay") to confirm your user ID. 8. Enter a secure passphrase for your key, then press **Enter**. Your key is generated. 9. Enter the following command to list your keys. ```bash $ gpg --list-secret-keys --keyid-format LONG ``` 10. Copy the ID of the new key you generated. In the example below, the key ID is **ABC123DEF456789O**: ```bash $ gpg --list-secret-keys --keyid-format LONG /Users/YOUR_USER/.gnupg/secring.gpg ------------------------------------ sec 4096R/{hint:This is the key ID}ABC123DEF456789O{/hint} 2020-01-01 [expires: 2025-01-01] uid YOUR_USER_ID sub 4096R/456789OABC123DEF 2020-01-01 ``` 11. Enter the following command, specifying the ID of the new key, to show your public key.\ For example, if this key ID is **ABC123DEF456789O** you would enter: ```bash $ gpg --armor --export ABC123DEF456789O ``` 12. Copy your public key, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `-----END PGP PUBLIC KEY BLOCK-----`. The next step is to register this key with Adyen, in your Customer Area. ## 2. Register the PGP key with Adyen To register your generated key with Adyen: 1. Log in to your [Customer Area](https://ca-live.adyen.com/). 2. [Switch to the company or merchant account](/account/manage-account-structure#switching-between-accounts) for which you want to register PGP keys.\ On a merchant account you can only register keys for the purposes **Reports** or **AccountUpdater**. 3. Select **Settings** > **Account settings**. 4. Select **Manage PGP Keys**. A list of all the PGP keys you have previously registered with Adyen is shown, including the ID of each key (**Key ID**) and its expiry date (**Expires**). []() 5. Under **Upload a new PGP Key**: * Select the **Purpose** of your new PGP key. For example, if you will use this key to encrypt and decrypt [batch files](/development-resources/batch-processing/advanced-sftp-batch-files#pgp-encryption), select **Batch files**. * Paste the **PGP Key** you generated earlier, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `-----END PGP PUBLIC KEY BLOCK-----`. Make sure this is your *public* key. **Do not** upload your *private* key. 6. Select **Upload key** to register the PGP key with Adyen. Files that match the selected [**Purpose** ](#purpose)will be encrypted with this PGP key. ## Handle an expiring PGP key If a PGP key you have registered with Adyen expires, this can impact your ability to process transactions or to decrypt important information. You are responsible for ensuring that the PGP keys you have registered with Adyen are valid and up to date. Two weeks before a [PGP key you have registered](#step-2-register-pgyp-key-with-adyen) is due to expire, we show a message in the **Notification center** of your Customer Area, and/or we send a message by email. This message indicates the ID of the PGP key, and when the key will expire. When you get this message, you can either: * **Recommended:** [Generate a new PGP key](#step-1-generate-new-pgp-key), and [register the new key with Adyen](#step-2-register-pgp-key-with-adyen). We recommend this approach, because it is theoretically more secure. * [Update the expiry date of you existing PGP key](#update-pgp-key-expiry) and [register your updated key with Adyen](#step-2-register-pgp-key-with-adyen). ### Update PGP key expiry To update the expiry of a PGP key using the [GnuPG](https://www.gnupg.org/) command line tools: 1. Open a command line application, such as *Terminal* or *PowerShell*. 2. Enter the following command, specifying the ID of the expiring key. Use the key ID mentioned in the **System Message** or email you received from Adyen.\ For example, if this key ID is **ABC123DEF456789G**: ```bash $ gpg --edit-key ABC123DEF456789G ``` This opens the GnuPG console (`gpg>`). 3. Use the `expire` command to edit the expiry date of the key. ```bash gpg> expire ``` 4. Enter the key validity. This is the length of time before the PGP key expires.\ For example, to extend the key's expiry by 5 years, enter `5y`: ```bash gpg> 5y ``` We recommend setting an expiry period for your PGP key. 5. Use the `save` command to save the changes to your PGP key, and return to the command line. ```bash gpg> save ``` 6. Enter the following command to list your keys. ```bash $ gpg --list-secret-keys --keyid-format LONG ``` 7. Copy the ID of the key you updated. In the example below, the key ID is **ABC123DEF456789G**: ```bash $ gpg --list-secret-keys --keyid-format LONG /Users/YOUR_USER/.gnupg/secring.gpg ------------------------------------ sec 4096R/{hint:This is the key ID}ABC123DEF456789G{/hint} 2020-01-01 [expires: 2025-01-01] uid YOUR_USER_ID sub 4096R/456789OABC123DEH 2020-01-01 ``` 8. Enter the following command, specifying the ID of the updated key, to show your public key.\ For example, if this key ID is **ABC123DEF456789G**: ```bash $ gpg --armor --export ABC123DEF456789G ``` 9. Copy your public key, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `-----END PGP PUBLIC KEY BLOCK-----`. 10. [Register your updated PGP key with Adyen](#step-2-register-pgp-key-with-adyen). ## See also * [GnuPG - GNU Privacy Guard](https://www.gnupg.org/) * [Adyen batch processing](/development-resources/batch-processing) * [Encrypting Adyen reports](/reporting/automatically-get-reports#encrypt-report-files) * [Account Updater result files](/development-resources/batch-processing/advanced-sftp-batch-files/batch-result-file/accountupdater-result-file) * [Migrating payment data](/development-resources/migrating-payment-data) --- # Source: https://docs.adyen.com/development-resources/security/sensitive-data/tls.md Section: Development resources Title: Transport Layer Security (TLS) Description: Use the correct TLS configuration to protect data during transmission. --- title: "Transport Layer Security (TLS)" description: "Use the correct TLS configuration to protect data during transmission." url: "https://docs.adyen.com/development-resources/security/sensitive-data/tls" source_url: "https://docs.adyen.com/development-resources/security/sensitive-data/tls.md" canonical: "https://docs.adyen.com/development-resources/security/sensitive-data/tls" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Transport Layer Security (TLS) Use the correct TLS configuration to protect data during transmission. [View source](/development-resources/security/sensitive-data/tls.md) The Transport Layer Security (TLS) protocol is essential for maintaining secure communications. Adyen uses TLS and TLS certificates to make sure of the following: * The connection between your system and our platform is secure. * You can verify that you are communicating with our platform. Different TLS versions support different cipher suites (encryption algorithms) to encrypt the data that is transported. In accordance with PCI DSS requirements, Adyen supports specific TLS versions and ciphers that the industry considers as strong. If you do not use the correct TLS version and cipher suite, it is possible that we cannot receive your API requests. ## Requirements Before you begin, check if the information on this page applies to you. | Requirement | Description | | -------------------- | -------------------------------------------------------------------- | | **Integration type** | The information on this page is relevant for all Adyen integrations. | ## Supported TLS versions and ciphers Different TLS versions support different cipher suites (encryption algorithms) to encrypt the data that is transported. In accordance with PCI DSS requirements, we support specific TLS versions and ciphers that the industry considers as strong. Cipher suites that are considered strong today may be considered weak in the future. Adyen continuously monitors which versions and cipher suites are used to connect to our platform. If you are using cipher suites or versions that we no longer consider secure, we notify you through [Customer Area notifications](/account/notification-center). Make sure that you use a supported TLS version and cipher suite, otherwise it is possible that we cannot receive your API requests. | TLS version | Version support | Supported ciphers | | ----------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TLS 1.2 | Only supported for existing merchants using strong ciphers | ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-RSA-CHACHA20-POLY1305 ECDHE-RSA-AES128-GCM-SHA256 | | TLS 1.3 | Supported New integrations must use TLS 1.3 | TLS\_AES\_256\_GCM\_SHA384 TLS\_CHACHA20\_POLY1305\_SHA256 | Make sure your TLS connections use SNI. New integrations must use TLS 1.3 with the TLS\_AES\_256\_GCM\_SHA384 or TLS\_CHACHA20\_POLY1305\_SHA256 cipher suite. If you are currently using TLS 1.2, we encourage you to **update to TLS 1.3** because TLS 1.3 offers significant improvements: * Stronger encryption algorithms, including support for modern cipher suites like AES-GCM and ChaCha20-Poly1305. This makes data transmissions more resistant to attacks. * Faster handshake: the performance is improved because establishing a secure connection is a lot faster. * Forward secrecy: if a private key becomes compromised, encrypted communications and sessions recorded in the past cannot be retrieved and decrypted. * Removal of outdated and less secure cryptographic algorithms and features. ## Certificate pinning We strongly recommend that you do not use [certificate pinning](https://www.ssl.com/blogs/what-is-certificate-pinning/). If you use certificate pinning, your platform only accepts the certificate that you pinned for Adyen. When we change our TLS certificate and present a different certificate during the TLS handshake, your application refuses to connect to our platform, even when the updated TLS certificate is issued by a trusted [Certificate Authority (CA)](https://www.ssl.com/article/what-is-a-certificate-authority-ca/). Why Adyen does not support certificate pinning of any kind: * Outside of Adyen's control: your system handles certificate pinning. We do not know if you do it or which certificates you pin. * Risk of failing connections: when we update our TLS certificate, and your system still expects the previous one, your connection to our platform breaks. ### Certificate changes When Adyen changes TLS certificates, no issues occur if you do not use certificate pinning. However, some organizations have policies that require certificate pinning, which can cause issues and broken connections with our platform. If you must use certificate pinning, do the following to reduce the risk of issues. * Only pin the root certificates: instead of pinning the leaf certificates or the entire certificate chain, you must pin all of the following root certificates: * [DigiCert Global Root CA]() * [DigiCert Global Root G2]() * [DigiCert Global Root G3]() * Keep track of TLS certificate updates: even if you pin all the root certificates, Adyen can add a new Root Certificate Authority (Root CA) to our trust store in the following cases: * Regular business practice: we send a [system message](/account/notification-center#service-status-messages) to notify you 30 days before we make the change. * Emergency cases: the notice period can be shorter before we make the change. It is your responsibility to ensure your applications (for example, web or mobile) can handle any certificate changes. ## See also * [Read more about Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) --- # Source: https://docs.adyen.com/development-resources/surcharge-compliance.md Section: Development resources Title: Surcharge compliance guide Description: Comply with general and regional requirements for applying surcharges. --- title: "Surcharge compliance guide" description: "Comply with general and regional requirements for applying surcharges." url: "https://docs.adyen.com/development-resources/surcharge-compliance" source_url: "https://docs.adyen.com/development-resources/surcharge-compliance.md" canonical: "https://docs.adyen.com/development-resources/surcharge-compliance" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Surcharge compliance guide Comply with general and regional requirements for applying surcharges. [View source](/development-resources/surcharge-compliance.md) The information in this page does **not** constitute legal advice. It only provides an overview of general and regional compliance guidelines for surcharges. You should consult your own legal advisors on compliance with regulatory requirements and review the card network rules for the latest information. This page provides high-level global guidelines for surcharging, as well as high-level guidelines for surcharging in different regions. It is important to understand that the Adyen surcharge feature does not enforce compliance with card network requirements and local regulations. It remains your responsibility to ensure compliance with the requirements and regulations that apply to you as a merchant or to the users of your platform. As a rule of thumb, local regulations supersede requirements from the card networks. ## Informing the card schemes A requirement from the card schemes is that the surcharge amount is reported to them. Adyen takes care of this reporting requirement on your behalf, but to be able to do that we need to get the details from you. * For ecommerce payments, the surcharge feature is only supported with an API only integration. In your `/payments` request, you must specify the surcharge amount in the `surcharge` object, and the `amount.value` field must be the sum of the original transaction amount and the surcharge amount. * With an in-person payments integration, the payment terminal or Mobile SDK calculates the surcharge based on how you configured surcharges. Your Terminal API payment request only needs to contain the original transaction amount, and we get the surcharge details through the terminal or SDK. ## Disclosure and signage If surcharges are applied, this must be disclosed to customers beforehand. You should: * Inform the customer that a surcharge is calculated and applied to the transaction. * Inform the customer of the surcharge amount or rate. * Not describe the surcharge in any way (in writing or verbally) as calculated and applied by a specific card network or a financial institution. * Clearly show or communicate the surcharge disclosure (the ["signage"](#signage)) in the transaction environment or process, including (if there is a physical point of sale) at the payment terminal or cashier’s desk. ### Signage Card networks require posting clear signs both at entry points and at the points of sale or interaction: * Entry points: at the outside of the location, for example, on or near the doors. * Points of sale or interaction: next to the cash register, on the menu, on the ordering kiosk or online ordering website, and so on. These signs must inform customers about the payment methods that are subject to surcharges, and the related costs such as the surcharge percentage. The Adyen surcharge feature does not include signage and disclosure templates. It is your responsibility to obtain signage materials and show these correctly, and to ensure that the signage is relevant for your country or region and complies with local regulations. On their websites, the card networks provide dedicated surcharge pages with guidance and signage templates, such as Visa's [page](https://usa.visa.com/support/small-business/regulations-fees.html) and [template](https://usa.visa.com/content/dam/VCOM/download/merchants/sample-surcharge-disclosure-signage.pdf) for the US. Here are some example disclosure statements from the card networks: > *We impose a surcharge on credit cards that is not greater than our cost of acceptance.* > > *We impose a surcharge of \_\_ % on the total transaction amount on {card network brand} credit card products, which is not greater than our cost of acceptance. We do not surcharge Debit {card network brand} cards.* You can mention multiple card networks or card network products in such statements. ## Acceptance or cancellation Customers must have the option to cancel their purchase, or choose an alternative payment method (such as cash or a different type of card) before the surcharge is applied. ## Receipts Customer receipts must include a separate line item that represents the surcharge and specifies the surcharge amount. Depending on local regulations, additional or different requirements for disclosing surcharges on the receipt may apply. ## Fines for non-compliance Through mystery shopping, card networks check if surcharges are applied in accordance with regulations. In case of non-compliance, the card network imposes a fine, which Adyen passes on to the responsible merchant or platform. Platforms are liable for fines incurred by their users, and thus the fines can accumulate if multiple users are found to be non-compliant. Here are some examples of non-compliance that can incur a fine. In all cases the initial fine assessment can range from $1,000 to $25,000 per merchant or platform user, depending on the card network. All non-compliance fines are passed on to the merchant or platform. * Correct signage to disclose surcharging has not been set up. * Receipt is not compliant.\ In case of a platform user, note that usually the platform determines the receipt configuration. * Wrong card type is surcharged.\ This violation can have regulatory implications and fines. * Surcharge caps are exceeded.\ This violation can have regulatory implications and fines. In case of a platform, exceeding surcharge caps can be due to an incorrect configuration on the platform side, or to platform users being allowed to set their own surcharges even when those exceed the relevant caps. ## Australia and New Zealand These are the regulations from the card networks for Australia and New Zealand: * Both debit and credit cards can be surcharged. However, if the "reasonable cost of acceptance" differs between debit and credit transactions, the surcharge amount must reflect this difference. * Businesses can charge a surcharge for paying by card, but the surcharge must not be more than what it costs the business to use that payment type. * Businesses must be able to prove the costs that the surcharge is based on. * If there is no way for a consumer to pay without paying a surcharge, businesses must include the surcharge in the displayed price. * EftPOS also allows surcharging. The Reserve Bank of Australia (RBA) has announced a ban on surcharging effective 1 October 2026. From this date, you will no longer be able to surcharge EftPOS, Visa, and Mastercard debit, credit, and prepaid cards in Australia. American Express is exempted at this time, subject to a review set to occur mid-year 2026. ### Surcharging caps Businesses can charge a surcharge for paying by card, but the surcharge must not be more than what it costs the business to use that payment type. ### Local regulations Surcharging regulations can include state-specific caps or other requirements. Adyen strongly recommends that you contact your legal counsel to ensure compliance with all applicable laws including state requirements. ## Canada These are the regulations from the card networks for Canada: * Surcharging is only allowed on Visa, Mastercard, and Discover credit cards. * Debit cards or prepaid cards cannot be subjected to surcharges under any circumstances. This includes payments with a debit or prepaid card that are processed as a credit transaction because a signature was used instead of a PIN.\ The Adyen surcharge feature does not automatically decline attempts to apply a surcharge to debit or prepaid card payments. It is your responsibility to provide the correct surcharge settings. * If you choose to add a surcharge to credit card payments, you must apply the same surcharge rate uniformly across all the credit card brands you accept. Additionally, the terms of the surcharge must be consistent for all credit cards. * It is not allowed to apply surcharges on **Interac** transactions because of Canada's regulatory prohibition of debit card surcharging. Also refer to the [Visa surcharge FAQ](https://www.visa.ca/content/dam/VCOM/regional/na/canada/Support/Documents/surcharging-faq-consumers-en.pdf) and the [Mastercard surcharge information](https://www.mastercard.ca/en-ca/business/overview/get-support/merchant-surcharge-rules.html) for Canada. ### Surcharging caps Surcharges are capped at the current discount rate charged by the card network (for example the blend rate) or at the percentage cap for the card network, whichever is lower. * Mastercard caps surcharges at 2.4%. * Visa caps surcharges at 3%. * For Discover the amount of the surcharge must not exceed the merchant fee paid to Discover for the card transaction. The Adyen surcharge feature does not automatically decline attempts to apply surcharges that exceed these caps. It is your responsibility to provide the correct surcharge settings. ### Notification requirements Mastercard requires that you/your platform's users notify Mastercard of the intent to implement surcharging at least 30 days before starting to apply surcharges to transactions. If you are a platform, meeting this requirement is your responsibility. To notify Mastercard, use the [Mastercard Surcharge Disclosure Form](https://www.mastercard.ca/en-ca/surcharge-disclosure-webform.html). ### Local regulations In addition to card network regulations, you/your platform's users must comply with: * Federal and state laws related to surcharging and avoiding deceptive disclosures. These laws differ per state and frequently change. * Province-specific regulations related to caps or other surcharging requirements. Ensure you/your platform's users understand, stay up to date, and comply with all surcharging regulations including regional nuances. Adyen strongly recommends that you contact your legal counsel to ensure compliance with all applicable laws. ## Europe These are the regulations from the card networks for the European Economic Area (EEA): * Cards issued outside of the EEA: no restrictions with regard to surcharging. * Consumer cards issued in the EEA: surcharging is prohibited. * Commercial cards issued in the EEA: regulations vary depending on the country. * SEPA transactions: surcharging is prohibited. ### Local regulations Surcharging regulations can include country-specific caps or other requirements. Adyen strongly recommends that you contact your legal counsel to ensure compliance with all applicable laws. ## United States These are the regulations from the card networks for the US: * Debit cards or prepaid cards cannot be subjected to surcharges under any circumstances. This includes payments with a debit or prepaid card that are processed as a credit transaction because a signature was used instead of a PIN. The Adyen surcharge feature does not automatically decline attempts to apply a surcharge to debit or prepaid card payments. It is your responsibility to provide the correct surcharge settings. * If you choose to add a surcharge to credit card payments, you must apply the same surcharge rate uniformly across all the credit card brands you accept. Additionally, the terms of the surcharge must be consistent for all credit cards. Also refer to the [Visa Surcharge Q & A](https://usa.visa.com/content/dam/VCOM/global/support-legal/documents/merchant-surcharging-qa-for-web.pdf) and the [Mastercard Surcharge FAQ](https://www.mastercard.us/content/dam/public/mastercardcom/na/us/en/documents/Merchant_Surcharge_FAQ.pdf) for more information. ### Surcharging caps Surcharges are capped at the current discount rate charged by the card network (for example the blend rate) or at the percentage cap for the card network, whichever is lower. * Mastercard caps surcharges at 4%. * Visa caps surcharges at 3%. * For Discover the amount of the surcharge cannot be greater than the Cost of Acceptance. The Adyen surcharge feature does not automatically decline attempts to apply surcharges that exceed these caps. It is your responsibility to provide the correct surcharge settings. ### Notification requirements You currently do not have to register your intent to surcharge credit cards using the [Mastercard Surcharge Disclosure Form](https://www.mastercard.us/en-us/surcharge-disclosure-webform.html). Mastercard is in the process of updating its rules around surcharging. We will update this page when the new rules are announced later in 2026. Mastercard requires that you/your platform's users notify Mastercard of the intent to implement surcharging at least 30 days before starting to apply surcharges to transactions. If you are a platform, meeting this requirement is your responsibility. To notify Mastercard, use the [Mastercard Surcharge Disclosure Form](https://www.mastercard.us/en-us/surcharge-disclosure-webform.html). To meet card network requirements, some platforms may need to provide Adyen with quarterly reports assessing the surcharges applied by their users. Whether this is required depends on the platform setup. ### Local regulations In addition to card network regulations, you/your platform's users must comply with federal and state laws related to surcharging and avoiding deceptive disclosures. These laws differ per state and frequently change. Surcharging is prohibited in several states, and regulations can include state-specific caps or other requirements. For example, in specific states it is not allowed to apply surcharges to gratuities. Also, state-specific or other laws with different or additional **disclosure rules** may apply. For example, it may be required to include surcharges in how pricing is shown. Ensure you/your platform's users understand, stay up to date, and comply with all surcharging regulations. Adyen strongly recommends that you contact your legal counsel to ensure compliance with all applicable laws. ## See also * [Surcharge feature for in-person payments](/point-of-sale/surcharge) * [Surcharge feature for platform in-person payments](/platforms/in-person-payments/surcharge) --- # Source: https://docs.adyen.com/development-resources/test-cards-and-credentials.md Section: Development resources Title: Test cards and credentials Description: Use test credentials to test your integration. --- title: "Test cards and credentials" description: "Use test credentials to test your integration." url: "https://docs.adyen.com/development-resources/test-cards-and-credentials" source_url: "https://docs.adyen.com/development-resources/test-cards-and-credentials.md" canonical: "https://docs.adyen.com/development-resources/test-cards-and-credentials" last_modified: "2023-11-23T09:56:00+01:00" language: "en" --- # Test cards and credentials Use test credentials to test your integration. [View source](/development-resources/test-cards-and-credentials.md) When testing your integration, use our test card numbers and other test credentials. You can also create your own test cards. [![](/user/pages/docs/13.development-resources/08.test-cards-and-credentials/stack-of-credit-cards-2.svg?decoding=auto\&fetchpriority=auto)](/development-resources/test-cards-and-credentials/test-card-numbers) [**Card numbers**](/development-resources/test-cards-and-credentials/test-card-numbers) [Test your integration with our test card numbers.](/development-resources/test-cards-and-credentials/test-card-numbers) [![](/user/pages/docs/13.development-resources/08.test-cards-and-credentials/local-payment-methods.svg?decoding=auto\&fetchpriority=auto)](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials) [**Alternative payment methods**](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials) [Test your integration with our test credentials for alternative payment methods.](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials) [![](/user/pages/docs/13.development-resources/08.test-cards-and-credentials/stack-of-credit-cards.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/create-test-cards) [**Creating test cards**](/development-resources/testing/create-test-cards) [Create your own test cards for testing your integration.](/development-resources/testing/create-test-cards) ## See also * [Testing online payments](/development-resources/testing) --- # Source: https://docs.adyen.com/development-resources/test-cards-and-credentials/alternative-payment-method-credentials.md Section: Development resources Title: Alternative payment methods test credentials Description: Test your integration with test credentials for other payment methods. --- title: "Alternative payment methods test credentials" description: "Test your integration with test credentials for other payment methods." url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/alternative-payment-method-credentials" source_url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/alternative-payment-method-credentials.md" canonical: "https://docs.adyen.com/development-resources/test-cards-and-credentials/alternative-payment-method-credentials" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Alternative payment methods test credentials Test your integration with test credentials for other payment methods. [View source](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials.md) Test alternative payment methods with the test credentials provided on this page. ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------- | | **Integration type** | Use test credentials to test your existing [online payments](/online-payments) integration. | ## ACH | Account Owner's Name | Bank account number | Bank routing number | Account Owner's Address | | -------------------- | ---------------------------------------------------------- | ---------------------- | ----------------------------------- | | Any name | Any correctly formatted account number. Example: 123456789 | 011000138 or 121000358 | Any correctly formatted US address. | ## Alipay | Username | PIN | Payment PIN | | --------------------------------- | ------ | ----------- | | | 111111 | 111111 | ### Alipay Hong Kong | Username | PIN | Payment PIN | | -------------------------- | ------- | ----------- | | | a111111 | b111111 | ## Apple Pay For a full list of test cards and instructions how to add these to your test device, see [Sandbox testing](https://developer.apple.com/apple-pay/sandbox-testing/) on Apple's Developer website. ## BACS | Account name | Account Number | Sort Code | | ------------ | -------------- | --------- | | David Archer | 40308669 | 560036 | ## BillDesk For card payments processed through BillDesk, use the following details to test different responses. | Card number | Static OTP | Expiry | CVV | Response | Type | Country/region | 3DS enrolled | Allows create mandate | Allows create network token | | ---------------- | ---------- | ------- | ---- | --------------------------- | ------------------- | -------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | 4622943127237569 | 123456 | 12/2024 | 744 | Success | Visa | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | 4000000000000002 | 123456 | 12/2029 | 123 | Success | Visa | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | 5400000000000005 | 123456 | 12/2029 | 123 | Success | Mastercard | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | 370000000000002 | 123456 | 12/2029 | 1234 | Success | American Express | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | 6522000000000006 | 123456 | 12/2029 | 123 | Success | Rupay | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | 5252520200034065 | 112223 | 12/2029 | 123 | PBE10002 Insufficient funds | Mastercard - Credit | IN | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ## BLIK To test BLIK in the TEST environment, use the following 6-digit BLIK codes to simulate different scenarios: | BLIK Code | Error code | Error description | | --------- | ----------------------- | --------------------------------------------------- | | 999 000 | **AUTHORIZED** | Regular authorisation. | | 912 111 | **ALIAS\_DECLINED** | Issuer declined due to security. | | 927 111 | **TAS\_DECLINED** | The transaction has been declined. | | 934 111 | **USER\_DECLINED** | Shopper declined the transaction in the Issuer app. | | 969 111 | **SEC\_DECLINED** | Declined due to security. | | 956 111 | **SYSTEM\_ERROR** | System error. | | 961 111 | **GENERAL\_ERROR** | General error. | | 960 111 | **INSUFFICIENT\_FUNDS** | Insufficient funds. | | 989 111 | **TIMEOUT** | Timeout on the Issuer end. | | 990 111 | **LIMIT\_EXCEEDED** | BLIK transaction limit exceeded. | | 949 111 | **USER\_TIMEOUT** | Shopper did not approve the transaction in time. | | 902 111 | **ISSUER\_DECLINED** | Issuer declined. | ### Testing One-Click payments For specific One-Click scenarios, use the following amounts: * x.02 PLN (for example 10.02 PLN): regular transaction, shopper is not tokenized. * x.12 PLN: shopper is tokenized, can be used for One-Click (for example transactions without a BlikCode). * x.42 PLN: use for One-Click transactions, payment is authorized, but shopper is de-tokenized, so cannot be used again for One-Click. ### Testing refusal reasons The following amounts can be used for specific refusal reasons: | Amount | Error code | Error description | | ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 288.00 | **ALIAS\_DECLINED** | The Issuer declines to process the Transaction with the Alias for security reasons. | | 192.00 | **TAS\_DECLINED** | Ticket Authorisation System declined. | | 144.00 | **USER\_DECLINED** | Declined by the user in Mobile Application. | | 216.00 | **SEC\_DECLINED** | Declined for security reasons. | | 264.00 | **SYSTEM\_ERROR** | The system error. | | 360.00 | **GENERAL\_ERROR** | The general error, must be applied in the case of unspecified error in the remaining items on this list. | | 120.00 | **INSUFFICIENT\_FUNDS** | Insufficient funds. | | 312.00 | **TIMEOUT** | It is returned in the case of the timeout in the Issuer’s systems except for the communication with the Mobile Application. | | 96.00 | **LIMIT\_EXCEEDED** | The limit exceeded. | | 336.00 | **USER\_TIMEOUT** | It is returned in the case of the timeout in the Mobile Application of the Issuer. | ## Boku Format: Country Code + Resultcode Example success: "GB00" Example refusal: "DE11". ## Boleto Bancário | Shopper Name | Social security number | Billing address | Delivery date | Shopper statement | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Any name | Any [CPF](https://en.wikipedia.org/wiki/Cadastro_de_Pessoas_Físicas) or [CNPJ](https://en.wikipedia.org/wiki/CNPJ) number, for example, 56861752509 | Any correctly formatted BR address | Any ISO 8601 date and time in UTC format, for example, 2023-12-31T23:00:00.000Z | Any. If left blank, the statement will be populated with [default Portuguese text](/payment-methods/boleto-bancario/api-only). | ## Brazil vouchers | Card type | Card number | Expiry date | CVC | | ------------------------------ | ------------------- | ----------- | --- | | Ticket (Edenred - Alimentação) | 6033 4225 5384 5003 | Any | 418 | | Ticket (Edenred - Refeição) | 6026 5145 1530 4787 | Any | 265 | | Pluxee (Alimentação) | 6033 8902 5703 4050 | 11/2034 | 164 | | Pluxee (Refeição) | 6060 7101 0440 1649 | 11/2032 | 507 | | Vale Refeição | 6370 3671 0000 0993 | 01/2032 | 520 | | Elo voucher | 5067 2300 0000 0002 | 03/2030 | 737 | | Visa voucher | 4058 8600 0000 0000 | 03/2030 | 737 | | Mastercard voucher | 2340 6300 0000 0009 | 03/2030 | 737 | ## Cash Ticket | Card Number | | ------------------- | | 0000 0000 0990 3188 | ## Doku Use the following simulators to test payment completion via Indonesian bank transfers and convenience stores. * [Alfamart](#alfamart) * [BCA](#bca) * [BNI](#bni) * [BRI](#bri) * [CIMB Bank Transfer](#cimb-bank-transfer) * [Danamon Bank Transfer](#danamon-bank-transfer) * [Indomaret](#indomaret) * [Mandiri Bank Transfer](#mandiri-bank-transfer) * [Permata Bank Transfer](#permata-bank-transfer) ### Alfamart The Alfa Simulator allows you to test the part of the payment flow where the shopper completes the payment in cash, at a convenience store. When you create a test payment for Alfamart, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [Alfa Simulator](https://staging.doku.com/VASimulator/AlfaAction_show.doku). 2. Select the **Inquiry** tab. 3. Append `00000002` to the 16-digit reference code and enter the new value in the **Customer** field. 4. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired. 5. Make a note of the value for the **Agent Trx ID** in the response. You will need this in the next steps. #### Complete the test payment 1. Go to the [Alfa Simulator](https://staging.doku.com/VASimulator/AlfaAction_show.doku). 2. Select the **Payment** tab and enter: * **Customer** — the **vaNumber**. * **Amount** — the value of the payment in [minor units](/development-resources/currency-codes). * **Transaction Id** — the **Agent Trx ID**. 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. Continue to the **Commit** tab below to get a webhook event from us for when the shopper completed the payment. #### Get a webhook event for the completed payment This step simulates the webhook event for when the shopper completed the payment. 1. Go to the [Alfa Simulator](https://staging.doku.com/VASimulator/AlfaAction_show.doku). 2. Select the **Commit** tab and enter: * **Customer** — the 16-digit `action.reference` value. * **Transaction Id** — the **Agent Trx ID**. 3. Select **Submit**. A **Commit Success** response means you can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### BCA The BCA Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for BCA, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [BCA Simulator](https://staging.doku.com/VASimulator/BCAAction_show.doku). 2. Select the **Inquiry** tab and enter: * **Company code** — the first 5 digits of the `action.reference` value. * **Customer number** — the last 11 digits of the `action.reference` value. 3. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired. 4. Make a note of the value for the **Agent Trx ID** in the response. You will need this in the next steps. #### Complete the test payment 1. Go to the [BCA Simulator](https://staging.doku.com/VASimulator/BCAAction_show.doku). 2. Select the **Payment** tab and enter: * **Company code** — the first 5 digits of the `action.reference` value. * **Customer number** — the last 11 digits of the `action.reference` value. * **Request ID** — value of the **Agent Trx ID** from the Inquiry tab response. * **Name** — shopper's first and last name. * **Amount** - the value of the payment in [minor units](/development-resources/currency-codes). 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### BNI The BNI Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for BNI, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [BNI Simulator](https://portalbeta.bni-ecollection.com/partner/simulator/payment-simulator/index). 2. In the **VA Number** field, enter the 16-digit `action.reference` value. 3. Select the search icon. 4. In the **Payment Amount** field, enter the value of the payment in [minor units](/development-resources/currency-codes). 5. In the **Direction** field, select **Credit**. 6. Select **Flag**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### BRI The BRI Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for BRI, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [BRI Simulator](https://staging.doku.com/VASimulator/BriAction_show.doku). 2. Select the **Inquiry** tab. 3. Enter the 16-digit `action.reference` value. 4. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired. #### Complete the test payment 1. Go to the [BRI Simulator](https://staging.doku.com/VASimulator/BriAction_show.doku). 2. Select the **Payment** tab and enter: * **Customer** — the 16-digit `action.reference` value. * **Amount** — the value of the payment in [minor units](/development-resources/currency-codes). * **Transaction Id** — any value. 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### CIMB Bank Transfer The CIMB Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for CIMB Bank Transfer, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [CIMB Simulator](https://staging.doku.com/VASimulator/CimbAction_show.doku). 2. Select the **Inquiry** tab and enter: * **Company Code** — the first 5 digits of the `action.reference` value. * **Customer Key 1** — the last 11 digits of the `action.reference` value. 3. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired.. #### Complete the test payment 1. Go to the [CIMB Simulator](https://staging.doku.com/VASimulator/CimbAction_show.doku). 2. Select the **Payment** tab and enter: * **Company Code** — the first 5 digits of the `action.reference` value. * **Customer Key 1** — the last 11 digits of the `action.reference` value. * **Amount** — the value of the payment in [minor units](/development-resources/currency-codes). 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### Danamon Bank Transfer The Danamon Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for Danamon Bank Transfer, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [Danamon Simulator](https://staging.doku.com/VASimulator/DanamonAction_show.doku). 2. Select the **Inquiry** tab and enter: * **BIN NUMBER** — any 7-digit number. * **VIRTUAL ACCOUNT NUMBER** — the 16-digit `action.reference` value. 3. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired.. 4. Make a note of the following values you get in the response: * **User Reference Number** * **Virtual Account Name** #### Complete the test payment 1. Go to the [Danamon Simulator](https://staging.doku.com/VASimulator/DanamonAction_show.doku). 2. Select the **Payment** tab and enter: * **BIN NUMBER** — any 7-digit number. * **VIRTUAL ACCOUNT NUMBER** — the 16-digit `action.reference` value. * **USER REFERENCE NUMBER** — the value from the **Inquiry** tab. * **VIRTUAL ACCOUNT NAME** — the value from the **Inquiry** tab. * **PAYMENT AMOUNT** — the value of the payment in [minor units](/development-resources/currency-codes). * **PAYMENT ACCOUNT** — any number. 3. Select **Submit** A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### Indomaret The Indomaret simulator allows you to test the part of the payment flow where the shopper completes the payment in cash, at a convenience store. When you create a test payment for Indomaret, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [Indomaret simulator](https://staging.doku.com/VASimulator/IndomartAction_show.doku). 2. Select the **Inquiry** tab and enter: * **PAYMENT CODE** — the 16-digit `action.reference` value. * **PRODUCT CODE** — 6588. * **STORE ID** — 97865123. * **SHARE KEY** — 66PXUFvr1jp7. 3. Select **Submit**. 4. Make a note of the **TRACKING REF** you get in response. #### Complete the test payment 1. Go to the [Indomaret simulator](https://staging.doku.com/VASimulator/IndomartAction_show.doku). 2. Select the **Payment** tab and enter: * **PAYMENT CODE** — the 16-digit `action.reference` value. * **AMOUNT** — the value of the payment, with two decimal places (add .00 to the end of the sum). * **STORE ID** — 97865123. * **TRACKING REF** — the value from the **Inquiry** tab, with no spaces. * **PRODUCT CODE** — 6588. * **SHARE KEY** — 66PXUFvr1jp7. 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### Mandiri Bank Transfer The Mandiri Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for Mandiri Bank Transfer, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [Mandiri Simulator](https://staging.doku.com/VASimulator/MandiriAction_show.doku). 2. Select the **Inquiry** tab and enter: * **Company Code** — any 5-digit number. * **Virtual Account Number** — the 16-digit `action.reference` value. 3. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired. #### Complete the test payment 1. Go to the [Mandiri Simulator](https://staging.doku.com/VASimulator/MandiriAction_show.doku). 2. Select the **Payment** tab and enter: * **Company Code** — the 5-digit number you used before. * **Amount** — the value of the payment in [minor units](/development-resources/currency-codes). * **Virtual Account Number** — the 16-digit `action.reference` value. 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### Permata Bank Transfer The Permata Simulator allows you to test the part of the payment flow where the shopper completes the payment using an ATM, online banking or mobile banking. When you create a test payment for Permata Bank Transfer, the response will have an `action.reference` value which is the 16-digit reference code you need below. #### Check the status of the payment This step checks if the payment has expired or not. The shopper cannot make the payment if it expired. 1. Go to the [Permata Simulator](https://staging.doku.com/VASimulator/PermataAction_show.doku) 2. Select the **Inquiry** tab and enter: * **INST CODE** — any 3-digit number. * **VIRTUAL ACCOUNT NUMBER** — the voucher code. * **TRACE NUMBER** — any 6-digit number. * **Date** — the transaction date, in the MMDDHHmmss format. 3. Select **Submit**. An **Inquiry Success** response confirms the payment has not expired. #### Complete the test payment 1. Go to the [Permata Simulator](https://staging.doku.com/VASimulator/PermataAction_show.doku) 2. Select the **Inquiry** tab and enter: * **INST CODE** — any 3-digit number. * **VIRTUAL ACCOUNT NUMBER** — the voucher code. * **TRACE NUMBER** — any 6-digit number. * **Date** — the transaction date, in the MMDDHHmmss format. * **Amount** — the value of the payment in [minor units](/development-resources/currency-codes). * **CURRENCY** — IDR. * **CHANNEL CODE** — your Doku Mall ID. 3. Select **Submit**. A **Payment Success** response confirms you successfully simulated the shopper completing a payment. You can expect a [webhook event](/development-resources/webhooks/webhook-types#event-codes) with `eventCode` set to **AUTHORISATION** and `success` set to **true**. ### Doku Wallet | Doku id | Password | PIN | | ---------- | ---------- | ---- | | 1790586273 | doKU\*\*88 | 1234 | ## EPS Before accepting live EPS payments, test your integration by making payments using the following EPS issuer (**paymentMethod.issuer**). | Bank name | Issuer ID | | -------------- | ------------------------------------ | | PSA Bank Group | b631e29a-097e-4400-be52-762b6d772b38 | ## Gift cards | Type | Number | Security code | Expiry month and yearOptional | | ------------------------------------- | ------------------- | ------------- | ----------------------------- | | Givex gift card | 6036280000000000000 | ANY | 12 2222 | | Generic gift card | 6364530000000000 | ANY | 12 2222 | | SVS gift card | 6006490000000000 | ANY | 12 2222 | | Fiserv (formerly ValueLink) gift card | 7777182708544835 | ANY | 12 2222 | If the simulator asks for a Fiserv (formerly ValueLink) promo code, enter any value. To test the balance check, make a test payment for an amount higher than EUR 50. ### Intersolve test gift cards | Card Type | Card Holder Name | Card Number | PIN | | -------------------- | ---------------- | ------------------- | ------ | | Gall & Gall Card | Any | 6064365010000000000 | 73737 | | Baby Gift Card | Any | 6064362200000000000 | 73737 | | Gift Card | Any | 6280501100000000000 | 73737 | | Kado Wereld | Any | 6064362510000000000 | 73737 | | Entertainment Card | Any | 6064361100000000000 | 73737 | | Plastix | Any | 4010100000000000000 | 73737 | | Webshop Giftcard | Any | 6064362070000000000 | 73737 | | Leasure Giftcard | Any | 6064362280000000000 | 73737 | | VVV Giftcard | Any | 6064364295385017427 | 737373 | | GiftForYou (Bloemen) | Any | 6064364710330000000 | 737373 | ## Google Pay To start testing Google Pay, log in to a Google account and create a Google Pay wallet. There are two approaches to using this wallet for testing: * **Enroll in test card suite** Enroll your wallet in Google's [test card suite](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). Test card suite pre-populates your wallet with a group of cards to use in the TEST environment. These are related to Adyen's collection of test cards, and cover scenarios including: * Cards stored as FPAN * Cards stored as DPAN (only when testing through native Android and Chrome on Android) * Cards enabled for 3DS2 When you start the payment flow and open the list of test cards, each card is marked with the applicable scenario. * **Without test card suite** You upload real credit cards to your wallet, which are mapped to one of Adyen's [test cards](/development-resources/test-cards-and-credentials/test-card-numbers) of the same brand. Your card is not charged. To test 3D Secure 2, you must use American Express or Discover cards, which trigger 3D Secure 2 challenge flows in the test environment. You cannot use any other card brands. You can check the status of a Google Pay test payment in your [Customer Area](https://ca-test.adyen.com/) > **Transactions** > **Payments**, whether you used a card from the test card suite or or not. Remember that cards outside the test card suite are mapped to an Adyen test card of the same brand. ## iDEAL The iDEAL test environment is unreliable and may not always work to test your changes. We recommend doing live penny tests to verify your integration. ### Request iDEAL for the live environment Before you can accept live payments, you need to [add iDEAL](/payment-methods/add-payment-methods) in your [live Customer Area](https://ca-live.adyen.com/). ### Live Penny Testing 1. Get a live bank account from one of the iDEAL issuers. 2. Create an iDEAL payment on live and redirect to the iDEAL Payment Page. 3. Scan the QR code on the iDEAL Payment Page or Click **Select your bank** to navigate to a list of issuers. 4. Authorise the payment. 5. Check the status of test payments in your [live Customer Area](https://ca-live.adyen.com/) > **Transactions** > **Payments**. ### Testing on the Test environment In case the iDEAL test environment is up and running, it may be possible to test using your test account. You are always redirected to a test payment page where you can simulate different iDEAL result codes. On the payment page: 1. Click **Select your bank** to navigate to a list of issuers. 2. Select the **TESTNL2A** issuer. 3. Select the test simulation you want to run according to the following table: | Test simulation | `resultCode` produced | | ------------------------- | --------------------- | | Success | Authorised | | Cancellation | Canceled | | Cancellation before login | Canceled | | Expiration | Pending or Received | | Failure | Refused | When possible, we recommend that you test each scenario before you go live, otherwise you should perform a **Live Penny Test** to verify your integration. Check the status of test payments in your [Customer Area](https://ca-test.adyen.com/) > **Transactions** > **Payments**. ## Interac For Interac any email address can be provided, but the amount of the test transaction must be 1.00 CAD. ## Klarna Use the [test environment and sample data provided by Klarna](https://docs.klarna.com/resources/test-environment/). ## MobilePay MobilePay cannot be tested in the test environment. You must make penny test (low-amount) payments in the live environment. 1. Submit a request for MobilePay in your [live Customer Area](https://ca-live.adyen.com/). 2. After MobilePay is added to your live Customer Area, do the following for each test payment: 1. Make a MobilePay payment for a low amount. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. 3. In your live Customer Area, go to **Transactions** > **Payments** to see the status of the payment. ### Test payouts to MobilePay wallets The MobilePay payout feature is experimental, and supported only with the `/payments` endpoint. Do the following to test MobilePay payouts: 1. Get a test app following the instructions in the [VippsMobilePay documentation](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment/#app-installation). When prompted for a phone number and NIN (national identity number), use one of the following sets: * NIN 0407640091\ Phone +45 22105837 * NIN 0702860109\ Phone +45 34817154 * NIN 0111500196\ Phone +45 73920021 2. Test your integration end-to-end: * Make a test payment that generates a payout token, using the Vipps MobilePay test app to simulate the customer side. * Check that you receive and process the recurring lifecycle webhook. * Make a [Transfers API](https://docs.adyen.com/api-explorer/transfers/latest/overview) request using the token that you receive in the webhook. ## Oney 3x 4x You must use different test credentials for France and Spain. ### France | Test card number | Expiry date | CVV | | ------------------- | ----------------------------------- | --------- | | 4970 1015 5874 4789 | Any date less than 3 years from now | Any value | | 4970 1090 4680 2374 | Any date less than 3 years from now | Any value | | 4970 1090 0325 6200 | Any date less than 3 years from now | Any value | You can test the different responses by changing the amount to be paid: * **Authorised**: Between EUR 150.00 and EUR 999.99 * **Pending**: Between EUR 1000.00 and EUR 1499.99 * **Refused**: Between EUR 1500.00 and EUR 2000.00 ### Spain | Test card number | Expiry date | CVV | | ------------------- | ----------------------------------- | --------- | | 4907 2720 1107 2841 | Any date less than 3 years from now | Any value | | 5410 0800 0888 8005 | Any date less than 3 years from now | Any value | You can test the different responses using different Documento Nacional de Identidad (DNI, Spanish ID card) numbers: * **Authorised**: DNI 05696340E * **Refused**: DNI 75914068S ## Pay by Bank (Europe) You can test payments in the following supported regions: Use the relevant test credentials and test issuer IDs, where available. #### UK For the UK, where you can show the issuer list in the payment form, use the following test issuer IDs: | Bank name | Issuer ID | | -------------- | -------------------------------------------- | | Tink Demo Bank | **uk-demobank-open-banking-handoff** | | Tink Demo Bank | **uk-demobank-open-banking-redirect** | | Tink Demo Bank | **uk-demobank-open-banking-redirect-aispis** | When you send a test payment and are redirected to our open banking partner Tink, log in with the following test credentials for the UK: | Scenario | Username | Password | | -------------------- | --------- | -------- | | Approved | u83646180 | rlf446 | | Authentication error | u92721594 | nbs589 | | Temporary error | u91902655 | jtx720 | For an Approved test scenario, you will see two checking accounts. Select the first checking account (ending in 285) for payment amounts greater than GBP 150, or the second checking account (ending in 327) for amounts less than GBP 150. #### Germany When you send a test payment and are redirected to our open banking partner Tink, log in with the following test credentials for Germany: | Scenario | Username | Password | | -------------------- | --------- | -------- | | Approved | u83188312 | zhx571 | | Authentication error | u92721594 | nbs589 | | Temporary error | u91902655 | jtx720 | #### France When you send a test payment and are redirected to our open banking partner Tink, log in with the following test credentials for France: | Scenario | Username | Password | | -------------------- | --------- | -------- | | Approved | u77894411 | mzw990 | | Authentication error | u92721594 | nbs589 | | Temporary error | u91902655 | jtx720 | #### Finland When you send a test payment and are redirected to our open banking partner Tink, log in with the following test credentials for Finland: | Scenario | Username | Password | | -------------------- | --------- | -------- | | Approved | u06516046 | kam413 | | Authentication error | u92721594 | nbs589 | | Temporary error | u91902655 | jtx720 | ## PayPal For PayPal test payments use the personal account email of your PayPal sandbox account. ## PaySafeCard | Card Number | | ------------------- | | 0000 0000 0990 3417 | ## SEPA Direct Debit | Account Name | IBAN | Country/region | | ------------ | ---------------------------- | -------------- | | A. Klaassen | NL13TEST0123456789 | NL | | B. Klaassen | NL36TEST0236169114 | NL | | C. Klaassen | NL26TEST0336169116 | NL | | D. Klaassen | NL16TEST0436169118 | NL | | E. Klaassen | NL81TEST0536169128 | NL | | F. Klaassen | NL27TEST0636169146 | NL | | G. Klaassen | NL39TEST0736169237 | NL | | H. Klaassen | NL82TEST0836169255 | NL | | I. Klaassen | NL72TEST0936169257 | NL | | J. Klaassen | NL46TEST0136169112 | NL | | K. Klaassen | NL70TEST0736160337 | NL | | L. Klaassen | NL18TEST0736162437 | NL | | M. Klaassen | NL92TEST0736163433 | NL | | A. Schneider | DE87123456781234567890 | DE | | B. Schneider | DE92123456789876543210 | DE | | C. Schneider | DE14123456780023456789 | DE | | D. Schneider | DE36444488881234567890 | DE | | E. Schneider | DE41444488889876543210 | DE | | F. Schneider | DE60444488880023456789 | DE | | G. Schneider | DE89888888881234567890 | DE | | H. Schneider | DE94888888889876543210 | DE | | I. Schneider | DE16888888880023456789 | DE | | A. Pacini | IT60X0542811101000000123456 | IT | | A. Grand | FR1420041010050500013M02606 | FR | | A. Martin | ES9121000418450200051332 | ES | | W. Hurth | AT151234512345678901 | AT | | H. Gasser | CH4912345123456789012 | CH | | R. Paulsen | DK8612341234567890 | DK | | B. Dalby | NO6012341234561 | NO | | A. Bak | PL20123123411234567890123456 | PL | | A. Andersson | SE9412312345678901234561 | SE | ## Trustly Use the [test credentials provided by Trustly](https://test.trustly.com/testing/). When prompted for a one-time passcode, copy the one-time passcode provided in the form. When testing Trustly, we recommend that you specify the [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-countryCode) in your payment request. If you omit this field, the Trustly test environment will estimate your country/region using your IP address. If your country/region is not [supported by Trustly](/payment-methods/trustly), this can lead to errors. ## Vipps ### Test Vipps in the test environment Before you test Vipps, follow the instructions in the [Vipps developer documentation](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment#app-installation) to download and set up the test app. After you download and install the app, use the credentials below to log in: * `NIN`: **14103524416** * `Phone`: **+47 99985255** * `Code`: **1236** After you finish the test app setup, follow these steps to test your Vipps integration on the test environment: 1. Add Vipps to your merchant account in the [test Customer Area](https://ca-test.adyen.com/). 2. Create a payment request with Vipps. 3. Check the notification on the test app and authorize the payment. ### Request for Vipps in the live environment Before you can accept live Vipps payments, you must submit a request for Vipps in your [live Customer Area](https://ca-live.adyen.com/). After Adyen adds Vipps to your live Customer Area, do the following for each test payment: 1. Make a Vipps payment for a low amount. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. 3. In your live Customer Area, go to **Transactions** > **Payments** to see the status of the payment. ## See also * [Payment methods](/payment-methods) * [Currency codes](/development-resources/currency-codes) * [Live endpoints](/development-resources/live-endpoints) --- # Source: https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards.md Section: Development resources Title: Create test cards Description: Create custom card numbers to test your integration with Adyen. --- title: "Create test cards" description: "Create custom card numbers to test your integration with Adyen." url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards" source_url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards.md" canonical: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards" last_modified: "2026-02-27T16:35:00+01:00" language: "en" --- # Create test cards Create custom card numbers to test your integration with Adyen. [View source](/development-resources/test-cards-and-credentials/create-test-cards.md) Adyen provides [generic test card numbers](/development-resources/testing/test-card-numbers), but you can also generate your own. On the Adyen test platform, you can use your generated test payment cards to simulate real-life payment scenarios and to verify the correct integration of your systems. Transactions carried out with these test cards do not result in actual credits or debits to live accounts. If your goal is to test failure scenarios, there is no need to generate your own test card. Instead, refer to [Testing result codes and refusal reasons](/development-resources/testing/result-codes/). ## Requirements | Requirement | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Customer Area roles** | You must have the **Manage test cards** role. For more information, see [user roles](/account/user-roles#developer). | ## Test card requirements Generated test cards should meet the following requirements: * Test card numbers should be between 6-19 digits long. * All test card numbers in a generated test card range need to have the same number of digits. * The first six digits of the test card numbers in any generated range need to be valid BIN numbers. * Test card numbers should comply with standard payment card number constraints. For example, to test a system with Visa you should create a test card range with a valid Visa BIN. * Although the created test card start and end range numbers are not checked for Luhn compliance, if you carry out a test payment the test card is handled like a standard payment card. It undergoes the standard card checks that take place in live environments, including Luhn verification. * The billing address details you define for a test card range need to be AVS (Address Verification Service) compliant, i.e. you always need to include at least the street address. Zip code is optional. * The billing address check verifies only the numeric characters in the street address and Zip code (if available). ## Generating test cards in Customer Area To generate ranges of test card numbers using the UI, do the following: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Account** > **Test cards**. 3. Select **Add new range**. 4. Enter the necessary details in the **Test Card Range** form. 5. Select **Save**. ## Generating test cards via API To create test card ranges using the API, send a request to the `/createTestCardRanges` endpoint. ### Request #### JSON ```json { "accountCode":"TestMerchant", "accountTypeCode":"MerchantAccount", "testCardRanges":[ { "TestCardRange":{ "rangeStart":"5232492669190772", "rangeEnd":"5232492670020681", "expiryMonth":"JANUARY", "expiryYear":"2020", "cvc":"123", "cardHolderName":"S Hopper", "address":{ "streetAddress":"1 Infinite Loop, Cupertino", "zip":"CA 95014" }, "threeDUsername":"simonhopper", "threeDPassword":"mypassword", "threeDDirectoryServerResponse":"Y" } }, { "TestCardRange":{ "rangeStart":"4596123423450871", "rangeEnd":"4596123434560780", "expiryMonth":"MARCH", "expiryYear":"2021", "cvc":"321", "cardHolderName":"T Anderson", "address":{ "streetAddress":"42, End of the Universe Rd., Los Alamos", "zip":"NM 87544" }, "threeDUsername":"thomasanderson", "threeDPassword":"mypassword", "threeDDirectoryServerResponse":"Y" } } ] } ``` #### Soap ```xml TestMerchant MerchantAccount 5232492670020681 5232492669190772 JANUARY 2020 123 S Hopper
1 Infinite Loop, Cupertino CA 95014
simonhopper mypassword Y 4596123434560780 4596123423450871 MARCH 2021 321
42, End of the Universe Rd., Los Alamos NM 87544
T Anderson thomasanderson mypassword Y ``` ### Response #### JSON ```json { "rangeCreationResults":[ { "TestCardRangeCreationResult":{ "cardNumberRangeStart":"5232492669190772", "cardNumberRangeEnd":"5232492670020681", "creationResultCode":"ALREADY_EXISTS" } }, { "TestCardRangeCreationResult":{ "cardNumberRangeStart":"4596123423450871", "cardNumberRangeEnd":"4596123434560780", "creationResultCode":"ALREADY_EXISTS" } } ] } ``` #### Soap ```xml 5232492669190772 5232492670020681 ALREADY_EXISTS 4596123423450871 4596123434560780 ALREADY_EXISTS ``` ### Response with an error #### JSON ```json { "errorType" : "security", "errorCode" : "901", "message" : "Invalid Merchant Account", "status" : "403" } ``` #### Soap ```xml soap:Server security 901 Invalid Merchant Account ``` If the operation does not complete successfully, a service exception is thrown. See Error handling for more details. ## Error handling After submitting a call, you receive a confirmation that the message was received, and if it was correctly processed. The API returns HTTP status codes and the response message. For a list of request and response fields, see [Response handling](/development-resources/response-handling). ### Test card response handling Test card generation fails, with a 4XX or 5XX HTTP response, in the following cases: * The range start test card number is larger than the end one. * The range start and the end test card numbers have different lengths, i.e. they do not have the same amount of digits. * The test card numbers are shorter than 6 digits or longer than 19 digits. * The test card numbers do not observe BIN code and AVS constraints (see Requirements). * If you use a generated test card number to carry out an actual payment, the test card number needs to be Luhn compliant because this check is part of standard behavior in a live environment. A Luhn compliance error is returned as a 101 Invalid card number fault code. When this happens, you receive a fault response with a description of the problem. In general, your toolkit handles this situation as an exception. Payment requests that are rejected with an error message are not charged. ### Service exceptions | Exception | Error Message | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Invalid test card range | The length of the start of the card range needs to be between 6 and 19 digits long but was {specified\_start\_range\_length\_value}. | | Invalid test card range | The length of the end of the card range needs to be between 6 and 19 digits long but was {specified\_end\_range\_length\_value}. | | Invalid test card range | The length of the start of the card range ({specified\_start\_range\_length\_value}) needs to match the length of the end of the card range ({specified\_end\_range\_length\_value}). | | Invalid test card range | The specified range start value {specified\_start\_value} does not represent a valid number. | | Invalid test card range | The specified range end value {specified\_end\_value} does not represent a valid number. | | Invalid test card number | The specified card {specified\_test\_card\_number} number is invalid. | --- # Source: https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api.md Section: Development resources Title: Test cards API reference --- title: "Test cards API reference" url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api" source_url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api.md" canonical: "https://docs.adyen.com/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api" last_modified: "2020-09-06T22:30:00+02:00" language: "en" --- # Test cards API reference [View source](/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api.md) To communicate with our API, you submit HTTP requests to applicable endpoints. These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the Adyen payments platform. This document lists all endpoints that are available for you to integrate with the test platform and run QA checks. ## Requirements | Requirement | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------ | | **API credentials** | You must have valid [API credentials](/development-resources/api-credentials) to make requests to endpoints. | ## SOAP endpoints For the SOAP messaging protocol, all test payment requests must be posted to the following endpoint: * The data schema for corresponding SOAP objects is available at: * ## JSON and FORM endpoints This is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an HTTP POST URL). * ### AvsAddress | Field | Type | Required | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `streetAddress` |  String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Billing address of the cardholder.Example: 1 Infinite Loop, Cupertino | | `zip` |  String | | Zip code associated with the billing address of the cardholder.Example: CA 95014 | ### CreateTestCardRangesRequest   | Field | Type | Required | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `accountCode` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account details used to log in and access the account. | | `accountTypeCode` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of account used to make the call.Possible values:- Company - MerchantAccountThese values are case-sensitive. | | `testCardRanges` | Array of [TestCardRange](/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api/#test-card-range) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains one or more test card range objects. | ### CreateTestCardRangesResult | Field | Type | Required | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `rangeCreationResults` | Array of [TestCardRangeCreationResult](/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api/#test-card-range-creation-result) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains one or more test card range result outputs. | ### TestCardRange Defines the properties of a test card range. | Field | Type | Required | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `address` | [AvsAddress](/development-resources/test-cards-and-credentials/create-test-cards/test-cards-api/#avs-address) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Contains the billing address of the cardholder. The address details need to be AVS (Address Verification Service) compliant, i.e. you need to define at least streetAddress. | | `cardHolderName` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The name of the cardholder, as it appears on the card, for the test card range.Example: S Hopper | | `cvc` | String | | The test card range security code.Example: 123 | | `expiryMonth` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry month for the test card range.Allowed values:- JANUARY - FEBRUARY - MARCH - APRIL - MAY - JUNE - JULY - AUGUST - SEPTEMBER - OCTOBER - NOVEMBER - DECEMBER | | `expiryYear` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Expiry year for the test card range.Example: 2020 | | `rangeEnd` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The last test card number in the test card range:- Min 6, max 19 digits - BIN compliantExample: 5432123412344321 | | `rangeStart` | String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The first test card number in the test card range:- Min 6, max 19 digits - BIN compliantExample: 5432123412341234 | | `threeDUserName` | String | | 3D Secure user name details of the cardholder.Example: simonhopper | | `threeDPassword` | String | | 3D Secure password details of the cardholder.Example: myPa$$w0rd | | `threeDDirectoryServerResponse` | String | | 3D Secure server response. It notifies whether the specified cardholder is enrolled in a 3D Secure service. Possible values:- Y (Authentication available) - N (Card holder not enrolled/not participating) - U (Unable to authenticate) | ### TestCardRangeCreationResult Contains a test card range result output. | Field | Type | Required | Description | | ----------------------- | ------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | |  `cardNumberRangeStart` |  String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The first test card number in the generated test card range.Example: 5432123412341234 | |  `cardNumberRangeEnd` |  String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The last test card number in the generated test card range.Example: 5432123412344321 | |  `creationResultCode` |  String | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Notification message. It informs about the outcome of the operation. Possible values:- CREATED - ALREADY\_EXISTS - ERROR | --- # Source: https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers.md Section: Development resources Title: Test card numbers Description: Use our test card numbers to test your integration. --- title: "Test card numbers" description: "Use our test card numbers to test your integration." url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers" source_url: "https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers.md" canonical: "https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers" last_modified: "2024-10-21T14:20:00+02:00" language: "en" --- # Test card numbers Use our test card numbers to test your integration. [View source](/development-resources/test-cards-and-credentials/test-card-numbers.md) ##### Testing POS payments We provide physical test cards to use with our test payment terminals. For more information, see our [point-of-sale test cards](/point-of-sale/testing-pos-payments/#testing-card-payments). To test your integration before accepting live payments, use the card details that are provided on this page. Refer to [Testing your online payments integration](/development-resources/testing) to learn about the flows we recommend you to test. ## Requirements | Requirement | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Use the test cards on this page to test your [online payments](/online-payments) integration. | | **Limitations** | * These test card numbers only work with Adyen's test platform. They do not work on other platforms. * If you use [RevenueProtect](/risk-management/), test payments can be blocked if they appear fraudulent. For testing, you can temporarily add the test card and shopper details to a [trust list](/risk-management/configure-manual-risk/referral-rules). | ## Tools for testing ![GitHub icon](/images/c/1/1/b/8/c11b8c32a1c3eb901a5d83455cfb5266df81a8dc-github-mark.png) **Open-source** [Adyen Test Cards browser extension GitHub repository](https://github.com/adyen-examples/adyen-testcards-extension).\ [Adyen Test Cards Android app GitHub repository](https://github.com/Adyen/adyen-testcards-android). We provide useful web and Android tools to help you test your integrations. ### Chrome extension Install the [Adyen Test Cards extension from the Chrome Web Store](https://chrome.google.com/webstore/detail/adyen-test-cards/icllkfleeahmemjgoibajcmeoehkeoag) to access our test cards and test your Web Drop-in or Components integration in your browser. ### Android test cards app Install the [Adyen Test Cards Android app from GitHub](https://github.com/Adyen/adyen-testcards-android/releases/latest/download/adyen-test-cards.apk) to access our test cards and test your Android Drop-in or Components integration on your Android device. ## Encrypted card details To test API calls from your server when your client-side integration is not ready yet, add a prefix of `test_` to the test card credentials. For example, to use the Mastercard test card with card number 5555555555554444, specify the following in your `/payments` request: ```json { ... "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_5555555555554444", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737" } } ``` ## American Express (Amex) | Card Number | Issuing Country/region | Expiry Date | CID | | ----------------------------------------- | ---------------------- | ----------- | ---- | | 3700 0000 0000 002 | NL | 03/2030 | 7373 | | 3700 0000 0100 018 Security code optional | NL | 03/2030 | 7373 | ## Bancontact (BCMC) | Card number | Card type | CVV2/CVC2 | Username | Password | Issuing country/region | Expiry date | | --------------------------------- | ----------------------- | -------------------------- | -------- | -------- | ---------------------- | ----------- | | 5127 8809 9999 9990 | BCMC / Mastercard Debit | BCMC: None Mastercard: 737 | user | password | BE | 03/2030 | | 6703 4444 4444 4449 | BCMC / Maestro | None | user | password | BE | 03/2030 | | 4871 0499 9999 9910 [1](#routing) | BCMC / Visa Debit | BCMC: None Visa: 737 | user | password | BE | 03/2030 | []()1 Depending on your payment method setup, transactions with this test card are routed to Bancontact or Visa. ## Cartes Bancaires | Card Number | Card Type | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------- | ----------------------------- | ---------------------- | ----------- | --------- | | 4360 0000 0100 0005 | Cartes Bancaires | FR | 03/2030 | 737 | | 4035 5010 0000 0008 | Visa | FR | 03/2030 | 737 | | 4035 5014 2814 6300 | Visa Debit / Cartes Bancaires | FR | 03/2030 | 737 | ## China UnionPay **ExpressPay Credit Card** (`cup`) | Card Number | Expiry Date | CVC | Issuing Country/region | | ----------------------- | ----------- | --- | ---------------------- | | 8171 9999 2766 0000 | 10/2030 | 737 | CN | | 8171 9999 0000 0000 021 | 10/2030 | 737 | CN | | 6243 0300 0000 0001 | 12/2029 | 737 | CN | SMS verification codes: | Channel | Verification code | | ------- | ----------------- | | Mobile | 123456 | | Desktop | 111111 | ## Dankort | Card Number | Card Type | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------- | -------------- | ---------------------- | ----------- | --------- | | 5019 5555 4444 5555 | Dankort | DK | 03/2030 | 737 | | 4571 0000 0000 0001 | Visa / Dankort | DK | 03/2030 | 737 | ## Diners | Card Number | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ---------------------------------------- | ---------------------- | ----------- | --------- | | 3600 6666 3333 44 | US | 03/2030 | 737 | | 3607 0500 0010 20 Security code optional | NL | 03/2030 | 737 | ## Discover | Card Number | Issuing Country/region | Expiry Date | CVD/CID | | ------------------- | ---------------------- | ----------- | ------- | | 6011 6011 6011 6611 | US | 03/2030 | 737 | | 6445 6445 6445 6445 | GB | 03/2030 | 737 | ## Eftpos | Card Number | Card Type | Issuing Country/region | Expiry Date | CVC | | ------------------- | ------------------- | ---------------------- | ----------- | --- | | 4687 3801 0001 0006 | Mastercard / Eftpos | AU | 03/2030 | 737 | | 4089 6700 0000 0014 | Eftpos | AU | 03/2030 | 737 | ## Elo | Card Number | Issuing Country/region | Expiry Date | CVE | | ------------------- | ---------------------- | ----------- | --- | | 5066 9911 1111 1118 | BR | 03/2030 | 737 | ## Hipercard | Card Number | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------- | ---------------------- | ----------- | --------- | | 6062 8288 8866 6688 | BR | 03/2030 | 737 | ## JCB | Card Number | Card Type | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------- | --------- | ---------------------- | ----------- | --------- | | 3569 9900 1009 5841 | Consumer | US | 03/2030 | 737 | ## Maestro For online Maestro payments, 3D Secure is mandatory. See [Test 3D Secure 2 authentication](/development-resources/testing/3d-secure-2-authentication). | Card Number | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------------------------------ | ---------------------- | ----------- | --------- | | 6771 7980 2100 0008 | US | 03/2030 | 737 | | 6771 7980 2100 0016 Security code optional | US | 03/2030 | | ## Mastercard | Card Number | Card Type | Issuing Country/region | Expiry Date | CVC3 | | ----------------------------------------- | ----------------- | ---------------------- | ----------- | ---- | | 2222 4000 7000 0005 | Commercial Debit | CA | 03/2030 | 737 | | 5555 3412 4444 1115Security code optional | Consumer | NL | 03/2030 | 737 | | 5577 0000 5577 0004 | Consumer | PL | 03/2030 | 737 | | 5555 4444 3333 1111 | Consumer | GB | 03/2030 | 737 | | 2222 4107 4036 0010 | Corporate | NL | 03/2030 | 737 | | 5555 5555 5555 4444 | Credit | GB | 03/2030 | 737 | | 2222 4107 0000 0002 | Corporate Credit | NL | 03/2030 | 737 | | 2222 4000 1000 0008 | Credit | CA | 03/2030 | 737 | | 2223 0000 4841 0010 | Credit | NL | 03/2030 | 737 | | 5130 2900 0000 0009 | Credit | FR | 03/2030 | 737 | | 2222 4000 6000 0007 | Debit | CA | 03/2030 | 737 | | 2223 5204 4356 0010 | Debit | NL | 03/2030 | 737 | | 2222 4000 3000 0004 | Fleet Credit | CA | 03/2030 | 737 | | 5100 0600 0000 0002 | Premium Credit | US | 12/2029 | 737 | | 2222 4000 5000 0009 | Purchasing Credit | CA | 03/2030 | 737 | | 5103 2219 1119 9245 | Prepaid | BR | 03/2030 | 737 | ## UATP | Card Number | Card Type | Expiry Date | CVV2/CVC3 | | ------------------ | --------- | ----------- | --------- | | 1354 1001 4004 955 | UATP | 03/2030 | None | ## US Debit | Card Number | Card Type | Issuing Country | Expiry Date | CVV2/CVC3 | | ------------------- | --------------------------------------------- | --------------- | ----------- | --------- | | 4400 0020 0000 0004 | Visa Debit / Accel / STAR / Maestro USA | US | 03/30 | 737 | | 4000 0330 0330 0335 | Visa Debit / PULSE / NYCE | US | 03/30 | 737 | | 5002 5100 0000 0013 | Mastercard Debit / Accel / STAR / Maestro USA | US | 03/30 | 737 | | 5413 3300 3300 3303 | Mastercard Debit / PULSE / NYCE | US | 03/30 | 737 | | 6011 6099 0000 0003 | Discover Debit / Accel / STAR / Maestro USA | US | 03/30 | 737 | | 6445 6450 0000 0002 | Discover Debit / PULSE / NYCE | US | 03/30 | 737 | ## Visa | Card Number | Card Type | Issuing Country/region | Expiry Date | CVV2 | | ------------------------------------------ | ------------------------- | ---------------------- | ----------- | ---- | | 4111 1111 4555 1142 Security code optional | Classic | NL | 03/2030 | 737 | | 4111 1120 1426 7661 eight-digit BIN | Debit | FR | 12/2030 | 737 | | 4988 4388 4388 4305 | Classic | ES | 03/2030 | 737 | | 4166 6766 6766 6746 | Classic | NL | 03/2030 | 737 | | 4646 4646 4646 4644 | Classic | PL | 03/2030 | 737 | | 4000 6200 0000 0007 | Commercial Credit | US | 03/2030 | 737 | | 4000 0600 0000 0006 | Commercial Debit | US | 03/2030 | 737 | | 4293 1891 0000 0008 | Commercial Premium Credit | AU | 03/2030 | 737 | | 4988 0800 0000 0000 | Commercial Premium Debit | IN | 03/2030 | 737 | | 4111 1111 1111 1111 | Consumer | NL | 03/2030 | 737 | | 4444 3333 2222 1111 | Corporate | GB | 03/2030 | 737 | | 4001 5900 0000 0001 | Corporate Credit | IL | 03/2030 | 737 | | 4000 1800 0000 0002 | Corporate Debit | IN | 03/2030 | 737 | | 4000 0200 0000 0000 | Credit | US | 03/2030 | 737 | | 4000 1600 0000 0004 | Debit | IN | 03/2030 | 737 | | 4002 6900 0000 0008 | Debit | AU | 03/2030 | 737 | | 4400 0000 0000 0008 | Debit | US | 03/2030 | 737 | | 4484 6000 0000 0004 | Fleet Credit | US | 03/2030 | 737 | | 4607 0000 0000 0009 | Fleet Debit | MX | 03/2030 | 737 | | 4977 9494 9494 9497 | Gold | FR | 03/2030 | 737 | | 4000 6400 0000 0005 | Premium Credit | AZ | 03/2030 | 737 | | 4003 5500 0000 0003 | Premium Credit | TW | 03/2030 | 737 | | 4000 7600 0000 0001 | Premium Debit | MU | 03/2030 | 737 | | 4017 3400 0000 0003 | Premium Debit | RU | 03/2030 | 737 | | 4005 5190 0000 0006 | Purchasing Credit | US | 03/2030 | 737 | | 4131 8400 0000 0003 | Purchasing Debit | GT | 03/2030 | 737 | | 4151 5000 0000 0008 | Visa Credit | US | 03/2030 | 737 | | 4199 3500 0000 0002 | Visa Proprietary | FR | 03/2030 | 737 | ## Visa Electron | Card Number | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ------------------- | ---------------------- | ----------- | --------- | | 4001 0200 0000 0009 | BR | 03/2030 | 737 | ## V Pay | Card Number | Issuing Country/region | Expiry Date | CVV2/CVC3 | | ----------------------- | ---------------------- | ----------- | --------- | | 4013 2500 0000 0000 006 | PL | 03/2030 | 737 | ## 3D Secure 2 The following cards are enrolled in 3D Secure 2. You can use them to [test 3D Secure 2 authentication scenarios](/development-resources/testing/3d-secure-2-authentication). | Card Type | Card Number | Expiry Date | Security Code (CVC/CVV/CID) | | ----------------------------- | ------------------- | ----------- | --------------------------- | | American Express | 3714 4963 5398 431 | 03/2030 | 7373 | | Bancontact / Maestro | 6703 4444 4444 4449 | 03/2030 | Not applicable | | Bancontact / Visa | 4871 0499 9999 9910 | 03/2030 | 737 | | Cartes Bancaires / Visa Debit | 4035 5014 2814 6300 | 03/2030 | 737 | | Cartes Bancaires | 4360 0000 0100 0005 | 03/2030 | 737 | | China UnionPay (Credit) | 6250 9470 0000 0014 | 03/2030 | 123 | | China UnionPay (Debit) | 6250 9460 0000 0016 | 03/2030 | 123 | | Diners | 3056 9309 0259 04 | 03/2030 | 737 | | Discover | 6011 1111 1111 1117 | 03/2030 | 737 | | JCB / Mastercard | 3566 1111 1111 1113 | 03/2030 | 737 | | Maestro | 5000 5500 0000 0029 | 03/2030 | Not applicable | | Mastercard | 5454 5454 5454 5454 | 03/2030 | 737 | | Mastercard Credit | 2222 4000 1000 0008 | 03/2030 | 737 | | Visa | 4917 6100 0000 0000 | 03/2030 | 737 | | Visa Classic | 4166 6766 6766 6746 | 03/2030 | 737 | ## See also * [AVS test cards](/development-resources/testing/risk-features#address-verification-system-avs) * [Payment methods](/payment-methods) * [Currency codes](/development-resources/currency-codes) * [Live endpoints](/development-resources/live-endpoints) --- # Source: https://docs.adyen.com/development-resources/testing.md Section: Development resources Title: Testing your online payments integration Description: Troubleshoot issues with your online payment integration before it goes live. --- title: "Testing your online payments integration" description: "Troubleshoot issues with your online payment integration before it goes live." url: "https://docs.adyen.com/development-resources/testing" source_url: "https://docs.adyen.com/development-resources/testing.md" canonical: "https://docs.adyen.com/development-resources/testing" last_modified: "2023-11-23T09:56:00+01:00" language: "en" --- # Testing your online payments integration Troubleshoot issues with your online payment integration before it goes live. [View source](/development-resources/testing.md) We recommend testing your full integration, including the client-side and server-side parts, in your test environment before accepting live payments. ## Requirements 1. From your [test Customer Area](https://ca-test.adyen.com/), get your test API key and test client key. 2. Configure your test Customer Area with all the functionality you will support when you go live. 3. [Build an integration](/online-payments/build-your-integration/) for accepting online payments. 4. Set up your [webhook server](/development-resources/webhooks). Getting test webhooks is an important part of making sure that your integration can handle many scenarios. ## Test your integration Test the different types of transactions with Adyen that your integration handles using [test credentials](/development-resources/test-cards-and-credentials). Test all the payment methods that you will offer. For each payment method, test your payment request with all the `countryCode` values for the shopper countries/regions you will accept. For example, in your client-side app's test environment, enter a test card number in your payment form and submit it. Then, check that your server-side setup makes the corresponding request and that your webhook server gets the corresponding webhook. [![](/user/pages/docs/13.development-resources/07.testing/cash-back.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/payments-and-modifications) [**Payments and modifications**](/development-resources/testing/payments-and-modifications) [Make payments and modify payments after they are completed.](/development-resources/testing/payments-and-modifications) [![](/user/pages/docs/13.development-resources/07.testing/account-updater.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/tokenization) [**Tokenization**](/development-resources/testing/tokenization) [Store payment methods for your shoppers.](/development-resources/testing/tokenization) [![](/user/pages/docs/13.development-resources/07.testing/risk-danger.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/risk-features) [**Risk features**](/development-resources/testing/risk-features) [Use Adyen's risk features to protect and improve your integration.](/development-resources/testing/risk-features) [![](/user/pages/docs/13.development-resources/07.testing/credit-card-lock.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/3d-secure-2-authentication) [**3D Secure 2 authentication**](/development-resources/testing/3d-secure-2-authentication) [Handle card transactions that require 3D Secure 2 authentication.](/development-resources/testing/3d-secure-2-authentication) [![](/user/pages/docs/13.development-resources/07.testing/webhooks.svg?decoding=auto\&fetchpriority=auto)](/development-resources/testing/result-codes) [**Result codes**](/development-resources/testing/result-codes) [Get the result codes and handle them with your integration.](/development-resources/testing/result-codes) ## See also * [Test cards and credentials](/development-resources/test-cards-and-credentials) --- # Source: https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication.md Section: Development resources Title: Testing 3D Secure 2 authentication Description: Test 3D Secure 2 authentication with your integration and troubleshoot issues before it goes live. --- title: "Testing 3D Secure 2 authentication" description: "Test 3D Secure 2 authentication with your integration and troubleshoot issues before it goes live." url: "https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication" source_url: "https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication.md" canonical: "https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Testing 3D Secure 2 authentication Test 3D Secure 2 authentication with your integration and troubleshoot issues before it goes live. [View source](/development-resources/testing/3d-secure-2-authentication.md) Test your integration to make sure that you can handle [3D Secure 2 authentication](/online-payments/3d-secure) scenarios. If you configured [Dynamic 3D Secure](/risk-management/dynamic-3d-secure/) and your default rule is set to **Prefer Not** do either of the following to trigger 3D Secure 2 scenarios while testing: * Set your default Dynamic 3D Secure rule to **Always**. * Include `authenticationData.attemptAuthentication` in your API request. * Use an amount that triggers authentication. When prompted for 3D Secure 2 text challenges: * For web and mobile browser integrations, use password: **password**. * For native mobile (app-based) integrations, use password: **1234**. If you want to test failed scenarios, use the wrong password (any value other than password provided) to fail the authentication challenge. To view the details and results of your test payments, do either of the following: * In your [test Customer Area](https://ca-test.adyen.com/), go to **Transactions** > **Payments**. * Check the **AUTHORISATION** [webhook](/development-resources/webhooks/webhook-types/#transaction-events) you received. The `success` field informs you of the outcome of a payment request. ## Test cards These cards are enrolled in 3D Secure. Make test payments with the following cards to make sure your integration can handle 3D Secure 2 authentication scenarios. | Card Type | Card Number | Expiry Date | Security Code (CVC/CVV/CID) | | ----------------------------- | ------------------- | ----------- | --------------------------- | | American Express | 3714 4963 5398 431 | 03/2030 | 7373 | | Bancontact / Maestro | 6703 4444 4444 4449 | 03/2030 | Not applicable | | Bancontact / Visa | 4871 0499 9999 9910 | 03/2030 | 737 | | Cartes Bancaires / Visa Debit | 4035 5014 2814 6300 | 03/2030 | 737 | | Cartes Bancaires | 4360 0000 0100 0005 | 03/2030 | 737 | | China UnionPay (Credit) | 6250 9470 0000 0014 | 03/2030 | 123 | | China UnionPay (Debit) | 6250 9460 0000 0016 | 03/2030 | 123 | | Diners | 3056 9309 0259 04 | 03/2030 | 737 | | Discover | 6011 1111 1111 1117 | 03/2030 | 737 | | JCB / Mastercard | 3566 1111 1111 1113 | 03/2030 | 737 | | Maestro | 5000 5500 0000 0029 | 03/2030 | Not applicable | | Mastercard | 5454 5454 5454 5454 | 03/2030 | 737 | | Mastercard Credit | 2222 4000 1000 0008 | 03/2030 | 737 | | Visa | 4917 6100 0000 0000 | 03/2030 | 737 | | Visa Classic | 4166 6766 6766 6746 | 03/2030 | 737 | When you make a payment request with these cards, you receive the following result codes depending on your integration: * **RedirectShopper**: you receive this result code if you use [Redirect authentication](/online-payments/3d-secure/redirect-3ds2/). * **IdentifyShopper**: you receive this result code if you use [Native authentication](/online-payments/3d-secure/native-3ds2/). * **ChallengeShopper**: you get this result code after you submit the 3D Secure 2 device fingerprinting result for Native authentication, unless you specify a frictionless flow. ## 3D Secure 2 challenge action If your integration uses the [Advanced flow](/online-payments/build-your-integration), test this scenario. This does not apply to integrations using the Sessions flow. Test a payment that requires handling the action object included in a payment response that includes the **ChallengeShopper** [result code](/online-payments/build-your-integration/payment-result-codes#3d-secure-authentication). Use the following payment details: | Card type | Card number | Expiry date | Security code (CVC/CVV/CID) | | --------- | ------------------- | ----------- | --------------------------- | | Visa | 4212 3456 7891 0006 | 03/2030 | 737 | If the payment was not successful, check that your client-side and server-side integration handles the required action from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response. ## Frictionless flow If your integration uses the [Advanced flow](/online-payments/build-your-integration), test this scenario. This does not apply to integrations using the Sessions flow. Test a payment that goes through [frictionless flow](/online-payments/3d-secure/#frictionless-flow), where your integration must provide a device fingerprint. No further authentication interaction with the client-side UI is required. Use the following payment details: | Card type | Card number | Expiry date | Security code (CVC/CVV/CID) | | ---------- | ------------------- | ----------- | --------------------------- | | Mastercard | 5201 2815 0512 9736 | 03/2030 | 737 | If the payment was not successful, check that your client-side and server-side integration handles the required action from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response. ## Mobile app integration On mobile, shoppers can get different types of 3D Secure 2 authentication challenges. Use the following payment details to make test payments and test specific scenarios. When prompted for 3D Secure 2 text challenge for native mobile (app-based) integrations, use password: **1234**. If you want to test failed scenarios, use the wrong password (any value other than **1234**) to fail the authentication challenge. | Card type | Card number | Expiry date | Security code (CVC/CVV/CID) | Scenario | | ---------- | ------------------- | ----------- | --------------------------- | ----------------------------------------- | | Mastercard | 5201 2855 6567 2311 | 03/2030 | 737 | Basic text authentication | | Mastercard | 5201 2874 9905 2008 | 03/2030 | 737 | Basic single select | | Mastercard | 5201 2815 9233 1633 | 03/2030 | 737 | Basic multi select | | Mastercard | 5201 2888 2269 6974 | 03/2030 | 737 | Basic out-of-band (OOB) authentication | | Mastercard | 5201 2895 0084 3268 | 03/2030 | 737 | HTML out-of-band (OOB) authentication | | Mastercard | 5201 2861 5377 1465 | 03/2030 | 737 | App single select and text authentication | To test advanced 3D Secure 2 authentication scenarios for native mobile (app-based) integrations, use the following test cards: | Card type | Card number | Expiry Date | Security Code (CVC/CVV/CID) | Scenario | | --------- | ------------------- | ----------- | --------------------------- | ----------------------------------------------------------------------------------- | | Visa | 4917 6100 0000 0042 | 03/2030 | 737 | ACS sends an empty Challenge Response (`CRes`) | | Visa | 4917 6100 0000 0067 | 03/2030 | 737 | Invalid content in the `acsSignedContent` field in Authentication Response (`ARes`) | | Visa | 4917 6100 0000 0059 | 03/2030 | 737 | Challenge Response (`CRes`) timeout | To test the scenario where a payment is routed to the [Redirect 3D Secure 2](/online-payments/3d-secure/redirect-3ds2) flow for your native mobile (app-based) integration, make a test payment without the [paymentMethod.threeDS2SdkVersion](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-CardDetails-threeDS2SdkVersion) parameter. ## Standalone authentication flow If your integration uses the [standalone authentication flow](/online-payments/3d-secure/standalone-authentication/), test that your integration can handle the possible outcomes using our [test cards](#test-cards). In this flow, you receive an **AUTHENTICATION** webhook, instead of the **AUTHORISATION** webhook to inform you of the payment request outcome. ## Authentication without liability shift Test a payment that goes through 3D Secure 2 authentication without [liability shift](/online-payments/3d-secure-for-regulation-compliance/#3dsecurechargebackliabilityshiftrules), use the following payment details. When prompted for a 3D Secure 2 text challenge, use password: **NoLiabilityShift**. | Card type | Card number | Expiry date | Security code (CVC/CVV/CID) | | --------- | ------------------- | ----------- | --------------------------- | | Visa | 4917 6100 0000 0000 | 03/2030 | 737 | ## Advanced scenarios Test the following scenarios to make sure your integration can handle advanced 3D Secure 2 flows. Use the following test cards to test scenarios returning `ARes` (Authentication Response) with different `transStatus` values: * **Y**: Authentication / account verification successful. * **N**: Not Authenticated / account not verified. Transaction denied. * **A**: Authentication / verification was attempted but could not be verified. * **U**: Authentication / account verification could not be performed. * **R**: Authentication / account verification rejected by the Issuer. | Card type | Card number | Expiry date | Security Code (CVC/CVV/CID) | Scenario | | ---------- | ------------------- | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Mastercard | 5201 2815 0512 9736 | 03/2030 | 737 | Return `ARes` with `transStatus`=**Y** | | Mastercard | 5201 2812 6243 5268 | 03/2030 | 737 | Return `ARes` with `transStatus`=**N** | | Mastercard | 5201 2850 9382 3592 | 03/2030 | 737 | Return `ARes` with `transStatus`=**A** | | Mastercard | 5201 2828 2836 6351 | 03/2030 | 737 | Return `ARes` with `transStatus`=**U** | | Mastercard | 5201 2864 9681 6589 | 03/2030 | 737 | Return `ARes` with `transStatus`=**R** | | Mastercard | 5201 2846 7071 7533 | 03/2030 | 737 | Return `ARes` with `transStatus`=**U** and [`transStatusReason` ](/online-payments/3d-secure/api-reference/#possible-transstatusreason-values)=**06** | Use the following test cards to test other advanced 3D Secure 2 scenarios. | Card type | Card number | Expiry date | Security Code (CVC/CVV/CID) | Scenario | | ---------- | ------------------- | ----------- | --------------------------- | ---------------------------------- | | Mastercard | 5201 2829 9900 5515 | 03/2030 | 737 | Timeout error | | Mastercard | 5201 2886 9531 5843 | 03/2030 | 737 | Connection failure error | | Mastercard | 5201 2858 9491 2800 | 03/2030 | 737 | Version number not supported error | | Mastercard | 5201 2852 4062 4612 | 03/2030 | 737 | Access denied error | | Mastercard | 5201 2859 4986 5169 | 03/2030 | 737 | MCC not valid error | | Mastercard | 5201 2829 4084 9714 | 03/2030 | 737 | Invalid endpoint error | --- # Source: https://docs.adyen.com/development-resources/testing/payments-and-modifications.md Section: Development resources Title: Testing payments and modifications Description: Test payments and modifications with your integration and troubleshoot issues before it goes live. --- title: "Testing payments and modifications" description: "Test payments and modifications with your integration and troubleshoot issues before it goes live." url: "https://docs.adyen.com/development-resources/testing/payments-and-modifications" source_url: "https://docs.adyen.com/development-resources/testing/payments-and-modifications.md" canonical: "https://docs.adyen.com/development-resources/testing/payments-and-modifications" last_modified: "2024-09-02T12:55:00+02:00" language: "en" --- # Testing payments and modifications Test payments and modifications with your integration and troubleshoot issues before it goes live. [View source](/development-resources/testing/payments-and-modifications.md) It is important to test that your integration can handle payments and [payment modifications](/get-started-with-adyen/adyen-glossary/#payment-modifications-definition). This page describes how to test: * Payments in general and payments with encrypted card details, third-party authentication data, or Level 2/3 data. * Modifications like manual, partial, and failed captures; full, partial, and failed refunds; reversals; and authorization adjustments. We recommend that you: * Use our [test card numbers](/development-resources/test-cards-and-credentials/test-card-numbers/) for different brands and use [test credentials for other payment methods](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials) that support it. * Start each test with a test payment with the amount of **100**. * Test each modification below to make sure your integration can handle different payment scenarios: * [Payment](#payment) * [Payment with encrypted card details](#payment-with-encrypted-card-details) * [Payment with third-party authentication data](#payment-with-third-party-authentication-data) * [Manual capture](#manual-capture) * [Partial manual capture](#partial-manual-capture) * [Multiple partial capture](#multiple-partial-manual-capture) * [Failed capture](#failed-capture) * [Cancel](#cancel) * [Full refund](#full-refund) * [Partial refund](#partial-refund) * [Multiple partial refund](#multiple-partial-refund) * [Reversal](#reversal) * [Pre-authorization and adjustment](#pre-authorization-and-adjustment) * [Payment with Level 2/3 data](#payments-with-level-2-3-data) ## Payment Test making a payment. After selecting the **Pay** button: 1. On your client-side, if you were redirected to another page or app, get redirected to your website or app after completing the payment. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. ## Payment with encrypted card details If your client-side integration is not complete yet, you can test your server with encrypted card details in your API request. Add the prefix `test_` to the test card credentials. For example, to use the Mastercard test card with the number **5555555555554444**, use the following in your API request: **Test encrypted card details** ```json { ... "paymentMethod": { "type": "scheme", "encryptedCardNumber": "test_5555555555554444", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737" } } ``` ## Payment with third-party authentication data If you use a third-party 3D Secure provider to get authentication data and use Adyen to authorise payments, you can test the [authorisation-only flow](/online-payments/3d-secure/other-3ds-flows/authorize-mpidata/) using the following payment details: | Card number | Expiry date | Security code (CVC/CVV/CID) | | ------------------- | ----------- | --------------------------- | | 4917 6100 0000 0000 | 03/2030 | 737 | 1. From your server, make a test [payment request with the information required for the authorisation-only flow](/online-payments/3d-secure/other-3ds-flows/authorize-mpidata/#make-a-payment-with-third-party-authentication-data). 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. ## Manual capture Test [manually capturing](/online-payments/capture/#manual-capture) a full payment amount. After making the test payment: 1. [Capture the full (**100**) test payment manually](/online-payments/capture/#capture-a-payment). 2. Get the **CAPTURE** webhook on your server. ## Partial manual capture Test [manually capturing](/online-payments/capture/#manual-capture) a partial payment amount. In a partial manual capture, you manually capture less than the full payment amount. After making the test payment: 1. [Capture part (less than **100**) of the test payment manually](/online-payments/capture/#capture-a-payment). 2. Get the **CAPTURE** webhook on your server. The remaining amount of the payment is automatically cancelled. ## Multiple partial manual capture Test [manually capturing](/online-payments/capture/#manual-capture) multiple partial payment amounts. In multiple partial manual captures, you manually capture less than the full payment amount. Then, you manually capture another amount, until you have captured the full payment amount. You must contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable this. After making the test payment: 1. [Manually capture part (less than **100**) of the test payment](/online-payments/capture/#capture-a-payment). 2. Get the **CAPTURE** webhook on your server. The `amount.value` in the webhook is the amount you captured. 3. Manually capture the remaining amount of the test payment. 4. Get the **CAPTURE** webhook on your server. ## Failed capture Rarely, a [capture can fail](/online-payments/capture/#failed-capture) even after you receive a successful **CAPTURE** webhook. To test a failed capture scenario: 1. Make a [card payment](/payment-methods/cards), specifying: * `holderName`: **capture failed**. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. 3. [Capture](/online-payments/capture) this payment, using either automatic or manual capture. 4. Get the **CAPTURE\_FAILED** webhook on your server. It can take up to 24 hours for the failed modification simulation to finish. ## Cancel Test [canceling](/online-payments/cancel/) an authorized payment. You can only cancel a payment if it is set for [delayed automatic capture](/online-payments/capture/#delayed-automatic-capture) or [manual capture](/online-payments/capture/#manual-capture). After making the test payment: 1. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. 2. [Cancel the test payment](/online-payments/cancel/#cancel-api). 3. Get the **CANCELLATION** webhook on your server. ## Full refund Test [refunding](/online-payments/refund/) a full payment amount. After making the test payment: 1. [Refund the full (**100**) test payment](/online-payments/refund/#refund-a-payment). 2. Get the **REFUND** webhook on your server. ## Partial refund Test [refunding](/online-payments/refund/) a partial payment amount. After making the test payment: 1. [Refund part (less than **100**) of the test payment](/online-payments/refund/#refund-a-payment). 2. Get the **REFUND** webhook on your server. ## Multiple partial refund Test [refunding](/online-payments/refund/) a [partially captured](/online-payments/capture/#partial-capture) payment amount. After making the test payment: 1. [Capture part (less than **100**) of the test payment manually](/online-payments/capture/#capture-a-payment). 2. Get the **CAPTURE** webhook on your server. 3. [Refund the partially captured amount](/online-payments/refund/#refund-a-payment), using the PSP reference of the original test payment in the request. 4. Get the **REFUND** webhook on your server. ## Failed refund Rarely, a [refund can fail](/online-payments/refund#refund-failed) even after you receive a successful **REFUND** webhook. To test a failed refund scenario: 1. Make a [card payment](/payment-methods/cards), specifying: * `holderName`: **refund failed**. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. 3. [Refund](/online-payments/refund) this payment, either in your [Customer Area](/account/manage-payments#refund-a-payment), or with an [API request](/online-payments/refund#refund-a-payment). 4. Get the **REFUND\_FAILED** webhook on your server. It can take up to 24 hours for the failed modification simulation to finish. ## Reversal Test [reversing](/online-payments/reversal/) a payment amount to return funds to a shopper. After making the test payment: 1. [Reverse the test payment](/online-payments/reversal/#reverse), using the PSP reference of the PSP reference of the original test payment in the request. 2. Get the **CANCEL\_OR\_REFUND** webhook on your server. ## Pre-authorization and adjustment Test [pre-authorization](/online-payments/adjust-authorisation/#authorisation-types) of a payment amount. This is only available for cards and Klarna. 1. [Pre-authorize](/online-payments/adjust-authorisation/adjust-with-preauth/#pre-authorize) a payment with the amount of **100**. 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. Test an authorisation adjustment where you change the authorized amount. 1. [Modify the authorization](/online-payments/adjust-authorisation/adjust-with-preauth/#adjust-auth) with the new amount of **175**. 2. Get the **ADJUST\_AUTHORISATION** webhook on your server. ## Payment with level 2/3 data Test payments that include [level 2 or level 3 data](/payment-methods/cards/enhanced-scheme-data). You must contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable the setting to include enhanced scheme data in your [Customer Area](https://ca-live.adyen.com/). Use the following test card numbers. Each card number corresponds to a different response: | Card number | Expiry Date | CVC | Response | | ------------------- | ----------- | --- | -------- | | 4444 3333 2222 1111 | 03/2030 | 737 | VGIS | | 2222 4107 4036 0010 | 03/2030 | 737 | L2 | | 5555 5555 5555 4444 | 03/2030 | 737 | L3 | 1. Submit a payment request with one of the following card numbers. 2. In the response, get the `additionalData` field that includes the level 2/3 data you submitted. 3. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. --- # Source: https://docs.adyen.com/development-resources/testing/result-codes.md Section: Development resources Title: Testing result codes and refusal reasons Description: Test getting result codes and refusal reasons with your integration and troubleshoot issues before going live. --- title: "Testing result codes and refusal reasons" description: "Test getting result codes and refusal reasons with your integration and troubleshoot issues before going live." url: "https://docs.adyen.com/development-resources/testing/result-codes" source_url: "https://docs.adyen.com/development-resources/testing/result-codes.md" canonical: "https://docs.adyen.com/development-resources/testing/result-codes" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Testing result codes and refusal reasons Test getting result codes and refusal reasons with your integration and troubleshoot issues before going live. [View source](/development-resources/testing/result-codes.md) ##### Test your in-person payments integration See [Simulating declined payments](/point-of-sale/testing-pos-payments/test-card-v3/#testing-declines) to learn about triggering refusal reasons with an in-person payments integration. You can test how your integration can handle different responses to make sure your integration can handle failure scenarios. In such scenarios, you receive a result code and a refusal reason that tells you why a payment request did not succeed. You can trigger specific refusal reasons in your payment requests to test how your integration handles failure scenarios. ## Benefits of testing refusal reasons This page describes how to trigger specific refusal reasons in your payment requests and test unhappy scenarios. There are several benefits to making sure your integration can handle unhappy flows, for example: * Presenting your shoppers with specific error messages per refusal reason. * Ensuring that you have a retry logic to handle refused payments. * Building your order management system logic to make sure unhappy scenarios are handled correctly. ## Trigger a refusal reason in a payment request To get a specific result code and refusal reason in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response, you need to include a specific value either in the `holderName` or `RequestedTestAcquirerResponseCode` field. You can find the values to use in the [Values for testing refusal reasons](#values-for-testing-result-reasons) table. 1. In the table, select the refusal reason that you want to trigger. 2. Make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, setting either of the following fields to the value corresponding to the refusal reason you want to trigger: * `paymentMethod.holderName` Some card-related payment methods, for example Alipay, redirect you to a simulator where you can select the payment result. In this case, the value provided as the cardholder name will be ignored. * `additionalData.RequestedTestAcquirerResponseCode` For example, to test getting `resultCode`: **Refused** with `refusalReason`: **ExpiredCard**, make one of the following requests. ### Tab: Request using holder name **Test request using holder name** ```json curl https://checkout-test.adyen.com/v72/payments \ -H'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount": { "currency": "USD", "value": 1000 }, "reference": "YOUR_REFERENCE", "paymentMethod": { "type": "scheme", "number": "4111111111111111", "expiryMonth": "03", "expiryYear": "2030", "holderName": "CARD_EXPIRED", "cvc": "737" }, "returnUrl": "https://your-company.example.com/...", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" }' ``` ### Tab: Request using acquirer response code **Test request using acquirer response code** ```json curl https://checkout-test.adyen.com/v72/payments \ -H'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount": { "currency": "USD", "value": 1000 }, "reference": "YOUR_REFERENCE", "paymentMethod": { "type": "scheme", "number": "4111111111111111", "expiryMonth": "03", "expiryYear": "2030", "holderName": "John Smith", "cvc": "737" }, "returnUrl": "https://your-company.example.com/...", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "additionalData": { "RequestedTestAcquirerResponseCode":6 } }' ``` 3. Make sure that the response contains the `resultCode` and `refusalReason` you triggered, and that your integration handles the response as expected. **Response with refusal reason** ```json { "pspReference": "851563882585825A", "refusalReason": "Expired Card", "resultCode": "Refused", "refusalReasonCode": "6" } ``` ## Values for testing refusal reasons The following table provides the values you need to specify in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) to trigger specific refusal reasons in the response: * The **refusalReason** and **resultCode** columns indicate the responses you can trigger. * The **holderName** column provides the value to use if you want to trigger the response using the `paymentMethod.holderName` field. * The **RequestedTestAcquirerResponseCode** column provides the value to use if you want to trigger the response using the `additionalData.RequestedTestAcquirerResponseCode` field. | **refusalReason** | **resultCode** | `holderName` | `RequestedTestAcquirerResponseCode` | | ------------------------------------------------------------ | -------------- | ------------------------------------------ | ----------------------------------- | | Unknown | Error | UNKNOWN | 0 | | - | Authorised | APPROVED | 1 | | Refused | Refused | DECLINED | 2 | | Referral | Refused | REFERRAL | 3 | | Acquirer Error | Error | ERROR | 4 | | Blocked Card | Refused | BLOCK\_CARD | 5 | | Expired Card | Refused | CARD\_EXPIRED | 6 | | Invalid Amount | Refused | INVALID\_AMOUNT | 7 | | Invalid Card Number | Refused | INVALID\_CARD\_NUMBER | 8 | | Issuer Unavailable | Refused | ISSUER\_UNAVAILABLE | 9 | | Not supported | Refused | NOT\_SUPPORTED | 10 | | 3D Not Authenticated | Refused | NOT\_3D\_AUTHENTICATED | 11 | | Not enough balance | Refused | NOT\_ENOUGH\_BALANCE | 12 | | - | Received | PENDING | 13 | | Acquirer Fraud | Refused | ACQUIRER\_FRAUD | 14 | | Cancelled | Refused | CANCELLED | 15 | | Shopper Cancelled | Refused | SHOPPER\_CANCELLED | 16 | | Invalid Pin | Refused | INVALID\_PIN | 17 | | Pin tries exceeded | Refused | PIN\_TRIES\_EXCEEDED | 18 | | Pin validation not possible | Refused | PIN\_VALIDATION\_NOT\_POSSIBLE | 19 | | FRAUD | Refused | FRAUD | 20 | | Not Submitted | Refused | NOT\_SUBMITTED | 21 | | FRAUD-CANCELLED | Cancelled | FRAUD\_CANCELLED | 22 | | Transaction Not Permitted | Refused | TRANSACTION\_NOT\_PERMITTED | 23 | | CVC Declined | Refused | CVC\_DECLINED | 24 | | Restricted Card | Refused | RESTRICTED\_CARD | 25 | | Revocation Of Auth | Refused | REVOCATION\_OF\_AUTH | 26 | | Declined Non Generic | Refused | DECLINED\_NON\_GENERIC | 27 | | Withdrawal amount exceeded | Refused | WITHDRAWAL\_AMOUNT\_EXCEEDED | 28 | | Withdrawal count exceeded | Refused | WITHDRAWAL\_COUNT\_EXCEEDED | 29 | | Issuer Suspected Fraud | Refused | ISSUER\_SUSPECTED\_FRAUD | 31 | | AVS Declined | Refused | AVS\_DECLINED | 32 | | Card requires online pin | Refused | PIN\_REQUIRED | 33 | | No checking account available on Card | Refused | NO\_CHECKING\_ACCOUNT\_AVAILABLE\_ON\_CARD | 34 | | No savings account available on Card | Refused | NO\_SAVINGS\_ACCOUNT\_AVAILABLE\_ON\_CARD | 35 | | Mobile PIN required | Refused | MOBILE\_PIN\_REQUIRED | 36 | | Contactless fallback | Refused | CONTACTLESS\_FALLBACK | 37 | | Authentication required | Refused | AUTHENTICATION\_REQUIRED | 38 | | RReq not received from DS | Refused | RREQ\_NOT\_RECEIVED | 39 | | Current AID is in Penalty Box. | Refused | BAN\_CURRENT\_AID | 40 | | CVM Required Restart Payment | Refused | CVM\_REQUIRED\_RESTART\_PAYMENT | 41 | | 3DS Authentication Error | Refused | THREED\_SECURE\_AUTHENTICATION\_ERROR | 42 | | Online PIN required | Refused | ONLINE\_PIN\_REQUIRED | 43 | | Try another interface | Refused | TRY\_ANOTHER\_INTERFACE | 44 | | Chip downgrade mode | Refused | CHIP\_DOWNGRADE\_MODE | 45 | | Transaction blocked by Adyen to prevent excessive retry fees | Refused | ERPS\_BLOCK | 46 | ## See also * [Refusal reasons](/development-resources/refusal-reasons/) * [Result codes](/online-payments/build-your-integration/payment-result-codes/) * [Response handling](/development-resources/overview-response-handling/) --- # Source: https://docs.adyen.com/development-resources/testing/result-codes/cvc-cvv-cid-result-codes.md Section: Development resources Title: Testing card CVC/CVV/CID result codes Description: Test getting card CVC/CVV/CID result codes with your integration and troubleshoot issues before it goes live. --- title: "Testing card CVC/CVV/CID result codes" description: "Test getting card CVC/CVV/CID result codes with your integration and troubleshoot issues before it goes live." url: "https://docs.adyen.com/development-resources/testing/result-codes/cvc-cvv-cid-result-codes" source_url: "https://docs.adyen.com/development-resources/testing/result-codes/cvc-cvv-cid-result-codes.md" canonical: "https://docs.adyen.com/development-resources/testing/result-codes/cvc-cvv-cid-result-codes" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Testing card CVC/CVV/CID result codes Test getting card CVC/CVV/CID result codes with your integration and troubleshoot issues before it goes live. [View source](/development-resources/testing/result-codes/cvc-cvv-cid-result-codes.md) You can test this if your integration uses the following: * Advanced flow * Sessions flow with additional methods Issuers may check the [card security code](/get-started-with-adyen/adyen-glossary/#card-security-code-cvc-cvv-cid) (CVC/CVV/CID) for online transactions. Based on the check, the transaction can be approved or declined. The result of the check may also be used in [post-authorization risk rules](/risk-management/configure-your-risk-profile/post-auth-rules). ## Requirements Enable `additionalData.cvcResult` field in your API response: 1. In your [test Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Additional data**. 2. Under **Acquirer**, select the checkbox for **Acquirer result**. ## Step 1: Make a test payment request For testing, you must use unencrypted [test card details](/development-resources/test-cards-and-credentials/test-card-numbers/). In your live environment, if you only use encrypted card details, the API response includes the same information. Make a test [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request and set `paymentMethod.cvc` to one of the [result codes values](#result-code-values). Add **00** to the beginning of the value. For example, to make a test payment request that gets the result code **4**, specify `paymentMethod.cvc`: **004**: **Test payment request to get the CVC/CVV/CID result code 4** ```json { "amount": { "currency": "EUR", "value": 2000 }, "paymentMethod":{ "type": "scheme", "number": "4111111111111111", "cvc": "004", "expiryMonth": "03", "expiryYear": "2030", "holderName": "Adyen Test" }, "reference":"YOUR_ORDER_NUMBER", "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "returnUrl": "https://your-company.example.com/" } } ``` ## Step 2: Get the result code in the response The API response includes the `cvcResult` that you specified in the request: **Response that includes the CVC/CVV/CID result code 4** ```json { "additionalData":{ "cvcResult":"4 No CVC/CVV provided, but was required", "cvcResultRaw":"S", "refusalReasonRaw":"DECLINED CVC Incorrect" }, "pspReference":"9914613171800003", "refusalReason":"Refused", "resultCode":"Refused" } } ``` ## Result code values | | CVC/CVV result code | Result | | - | ------------------------------------- | -------- | | 0 | Unknown | Approval | | 1 | Matches | Approval | | 2 | Doesn't match | Decline | | 3 | Not checked | Approval | | 4 | No CVC/CVV provided, but was required | Decline | | 5 | Issuer not certified for CVC/CVV | Approval | | 6 | No CVC/CVV provided | Approval | --- # Source: https://docs.adyen.com/development-resources/testing/risk-features.md Section: Development resources Title: Testing risk features Description: Test risk features with your integration and troubleshoot issues before it goes live. --- title: "Testing risk features" description: "Test risk features with your integration and troubleshoot issues before it goes live." url: "https://docs.adyen.com/development-resources/testing/risk-features" source_url: "https://docs.adyen.com/development-resources/testing/risk-features.md" canonical: "https://docs.adyen.com/development-resources/testing/risk-features" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Testing risk features Test risk features with your integration and troubleshoot issues before it goes live. [View source](/development-resources/testing/risk-features.md) ## Chargebacks If a shopper disputes a transaction, it can become a chargeback. To test the dispute flow, you can simulate a chargeback to [test chargeback scenarios](/risk-management/disputes-api/test-applicable-dispute-reasons/).\ You can then use your Customer Area or the Disputes API to handle the simulated dispute. ## Risk management When you use RevenueProtect, and have turned on and configured risk rules, you can [test if the risk rule triggers](/risk-management/configure-manual-risk/#test-risk-rules). ## Address Verification System (AVS) You have to include billing address details in the payment request to enable and test [AVS](/risk-management/avs-checks#enable-and-test-avs). To test AVS, you can use the following AVS test cards and billing addresses: | Card Number | Card Type | House Number | Address | ZIP Code | Country/region | Expiry Date | Security Code (CVV/CVC/CID) | | ---------------- | ---------- | ------------ | ----------------------------------- | -------- | -------------- | ----------- | --------------------------- | | 5555555555554444 | Mastercard | 10 | Downing Street, London. | SW1A 2AA | GB | 03/2030 | 737 | | 374251018720018 | Amex | 1600 | Pennsylvania Ave NW Washington, DC. | 20500 | US | 03/2030 | 7373 | | 374251021090003 | Amex | 1 | Infinite Loop Cupertino, CA. | 95014 | US | 03/2030 | 7373 | | 374101012180018 | Amex | 10 | Downing Street, London. | SW1A 2AA | GB | 03/2030 | 7373 | | 374251033270007 | Amex | 8-10 | Broadway, Westminster, London. | SW1H 0BG | GB | 03/2030 | 7373 | | 4400000000000008 | Visa | 1 | Infinite Loop Cupertino, CA. | 95014 | US | 03/2030 | 737 | | 4444333322221111 | Visa | 8-10 | Broadway, Westminster, London. | SW1H 0BG | GB | 03/2030 | 737 | 1. Make a test card payment. 2. Get the AVS result in your API response or webhook for the corresponding PSP reference.\ For an overview of the different AVS responses and codes, see: * [AVS responses](/risk-management/avs-checks/#avs-mapping-table) for online payments. * [AVS responses](/point-of-sale/mail-and-telephone-order-moto/avs-responses-pos) for in-person payments. ## Auto Rescue For shopper-not-present transactions, like subscription renewal payments, the [Auto Rescue](/online-payments/auto-rescue/) feature determines when to automatically retry failed payments. Test it by enabling it in your test Customer Area and triggering the following scenarios. ### Retry attempts In these test scenarios, the payment is refused, so Auto Rescue makes retry attempts. To trigger specific retry scenarios, include the following values in the `merchantReference` field when making a test [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request: | Scenario | Merchant order reference value | | ---------------------------------------------------------------------- | ------------------------------ | | The first retry attempt succeeds. | **AutoRescueSuccessfulFirst** | | The first retry attempt fails. The second retry attempt is successful. | **AutoRescueSuccessfulSecond** | | All retry attempts fail. | **AutoRescueFailed** | | The payment is refused because of fraud, so there's no retry attempt. | **AutoRescueFraud** | For scenarios where Auto Rescue is triggered, you get an **AUTHORISATION** webhook for each payment retry. The `success` field in the webhook shows if the retry was successful. ### Failed retry attempt that sends a payment link If you enabled sending a Pay by Link payment link if Auto Rescue retry attempts fail. In this scenario, the payment is refused, so Auto Rescue makes retry attempts. All retry attempts fail, so a [Pay By Link payment link is sent](/online-payments/auto-rescue/cards/#send-a-payment-link). 1. Make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request including `merchantReference`: **AutoRescueFailed**. 2. Get the **AUTORESCUE** webhook on your server. 3. Go to the payment link URL from `paymentLink.url` from the webhook. 4. Complete the Pay by Link test payment. 5. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. --- # Source: https://docs.adyen.com/development-resources/testing/tokenization.md Section: Development resources Title: Testing tokenization Description: Test the tokenization with your integration and troubleshoot issues before it goes live. --- title: "Testing tokenization" description: "Test the tokenization with your integration and troubleshoot issues before it goes live." url: "https://docs.adyen.com/development-resources/testing/tokenization" source_url: "https://docs.adyen.com/development-resources/testing/tokenization.md" canonical: "https://docs.adyen.com/development-resources/testing/tokenization" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Testing tokenization Test the tokenization with your integration and troubleshoot issues before it goes live. [View source](/development-resources/testing/tokenization.md) You can use our [Tokenization feature](/online-payments/tokenization) to store payment details for transactions like automatic subscription renewal payments. Test your integration with Adyen's tokenization features, using our [test card numbers](/development-resources/test-cards-and-credentials/test-card-numbers/). The following steps take you through the different steps for storing, using, updating, and removing payment details. 1. [Store payment details for one-off payments](#store-payment-details-for-one-off-payments) 2. [Make a test one-off payment with stored payment details](#make-a-test-one-off-payment) 3. [Store payment details for subscription payments](#store-payment-details-for-subscription-payments) 4. [Make a test subscription payment with stored payment details](#make-a-test-subscription-payment) 5. [Update stored payment details](#update-stored-payment-details) 6. [Remove stored payment details](#remove-stored-payment-details) Additionally, you can optionally test [Real Time Account Updater scenarios](#real-time-account-updater) if you use the feature. ## Step 1: Store payment details for one-off payments Test storing payment details for [one-off payments](/online-payments/tokenization#recurring-payment-types). 1. Create a token with an amount of **0** (zero-auth transaction). In your API request, set the following parameters: | Parameter | Value | | -------------------------- | -------------- | | `shopperInteraction` | **Ecommerce** | | `recurringProcessingModel` | **CardOnFile** | 2. Get the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook. 3. Store the token from the webhook and the shopper reference for test one-off payments. ## Step 2: Make a test one-off payment Test making a one-off payments with stored payment details. 1. Make a test one-off payment with the [token you created for testing](#store-payment-details-for-one-off-payments). In your API request, set the following parameters: | Parameter | Value | | Parameter | Value | | -------------------------- | -------------- | - | --------- | ----- | | `shopperInteraction` | **ContAuth** | | | | | `recurringProcessingModel` | **CardOnFile** | | | | 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. ## Step 3 (optional): Store payment details for subscription payments If you accept subscription payments, test storing payment details for [subscription payments](/online-payments/tokenization#recurring-payment-types). 1. Create a token with an amount of **0** (zero-auth transaction). In your API request, set the following parameters: | Parameter | Value | | -------------------------- | ---------------- | | `shopperInteraction` | **Ecommerce** | | `recurringProcessingModel` | **Subscription** | 2. Get the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook. 3. Store the token from the webhook and the shopper reference for test subscription payments. ## Step 4 (optional). Make a test subscription payment If you accept subscription payments, test making a subscription payment with stored payment details. 1. Make a test one-off payment with the token you [created for testing](#store-payment-details-for-subscription-payments). In your API request, set the following parameters: | Parameter | Value | | -------------------------- | ---------------- | | `shopperInteraction` | **ContAuth** | | `recurringProcessingModel` | **Subscription** | 2. Get the [**AUTHORISATION** webhook](/development-resources/webhooks/webhook-types/#default-event-codes) on your server. It includes the status of the payment. ## Step 5. Update stored payment details Test [updating stored payment details](/online-payments/tokenization/managing-tokens/#update-stored-details). 1. [Make a request to update](/online-payments/tokenization/managing-tokens/#update-stored-details) stored payment details for one of the tokens you created for testing. 2. [Get the stored](/online-payments/tokenization/managing-tokens/#list-stored-details) for the shopper reference you stored the token with. ## Step 6. Remove stored payment details Test [deleting stored payment details](/online-payments/tokenization/managing-tokens/#delete-stored-details). Make a request to delete stored payment details for one of the tokens you created for testing. ## Real Time Account Updater scenarios To test how different Real Time Account Updater scenarios work for your integration, use the following test card numbers and expiry dates in your payment request. The response will contain the corresponding status in the `additionalData.realtimeAccountUpdaterStatus` field. | Card number | Expiry month/year | Status | | ------------------- | ----------------------- | ---------------------------- | | 5454 5476 9908 4950 | 03/2030 | **CardChanged** | | 5454 5418 5840 6567 | Any date except 03/2030 | **CardExpiryChanged** | | 5454 5415 8031 1093 | 03/2030 | **CloseAccount** | | 4111 1131 5971 2925 | 03/2030 | **ContactCardAccountHolder** | If you are not fully PCI compliant and thus unable to process raw card data, add a prefix of `test_` to the credentials. For example, use `"encryptedCardNumber": "test_5454547699084950"`. This allows you to [test using encrypted card details](/development-resources/test-cards-and-credentials/test-card-numbers#test-encrypted-card-details). --- # Source: https://docs.adyen.com/development-resources/versioning.md Section: Development resources Title: Versioning Description: Find out how Adyen applies versioning to APIs and server-side libraries. --- title: "Versioning" description: "Find out how Adyen applies versioning to APIs and server-side libraries." url: "https://docs.adyen.com/development-resources/versioning" source_url: "https://docs.adyen.com/development-resources/versioning.md" canonical: "https://docs.adyen.com/development-resources/versioning" last_modified: "2022-01-18T16:03:00+01:00" language: "en" --- # Versioning Find out how Adyen applies versioning to APIs and server-side libraries. [View source](/development-resources/versioning.md) We constantly improve our products and add new functionalities on our platform. Usually these improvements and functionalities result in new product versions. ##### API Diff Tool Use our [API Diff Tool](https://docs.adyen.com/api-explorer/api-diff-tool) to compare any two versions of an API. On this page, we describe the versioning of our APIs and server-side libraries. ## APIs When we introduce changes to our APIs, we follow best practices to have the least disruption on existing integrations. For example, for our REST APIs, we follow the [API expand-contract](https://www.thoughtworks.com/radar/techniques/api-expand-contract) pattern to add new elements without changing the version. While we strive to reduce impact to existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience. When we introduce a breaking or incompatible change, we release a new API version to accommodate the change. The definition of a breaking change depends on the [type of API](#new-vs-classic). ### Checking the API version Most integrations use multiple Adyen APIs (see our [API Explorer](https://docs.adyen.com/api-explorer/). Each API has a different version. Depending on how you are making the API calls, you can check the versions of the APIs that you are using from: * Direct calls from your server: you can see the API version in the URLs that you use to reach the Adyen platform. * Server-side libraries: when a [server-side library version](/development-resources/versioning#server-side-libraries) is released, the API version is included in the release notes. For example, see [Adyen Java API library 17.2.0](https://github.com/Adyen/adyen-java-api-library/releases/tag/17.2.0). Each API URL contains a version suffix starting with either "v" or "V" character followed by a whole number to indicate the API version. We increment the number for every version, but [we may skip numbers](#new-version-without-changes) when needed. Here are some examples of different API versions: ```bash https://checkout-test.adyen.com/v68/payments // version 68 https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder // version 6 https://balanceplatform-api-test.adyen.com/bcl/v1/balanceAccounts // version 1 ``` To check if you are using the latest API version, refer to the version in our [API Explorer](https://docs.adyen.com/api-explorer/). ### New vs classic APIs We categorize our APIs into two types: *new* or *classic* APIs. The type determines whether a change is compatible with an existing API version. For example, in new Adyen APIs, adding an optional field to a response body is a non-breaking change, while in classic APIs this change is considered breaking and therefore requires a new API version. The following are classic APIs: * [Payment](https://docs.adyen.com/api-explorer/#/Payment/latest/overview) * [Recurring](https://docs.adyen.com/api-explorer/Recurring/latest/overview) * [Payout](https://docs.adyen.com/api-explorer/Payout/latest/overview) * [BinLookup](https://docs.adyen.com/api-explorer/#/BinLookup/latest/overview) All other APIs that are not in the list above are new APIs, such as [Checkout](https://docs.adyen.com/api-explorer/Checkout/latest/overview) and [Balance Platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/overview). ### Non-breaking changes A *non-breaking* or *backward-compatible* change is an API change that allows your integration to continue using the API without any additional changes on your side. When we introduce new functionalities and changes to our APIs, we do our best to implement them in a backward-compatible way. We implement non-breaking changes in all versions of an API, so that you benefit from it without having to upgrade your API version. We consider the following changes as non-breaking, depending on the [API type](#new-vs-classic). | Non-breaking changes | New APIs | Classic APIs | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Adding a new endpoint | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Adding an optional field to a request body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Adding any field to a response body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | [Breaking change](#breaking-changes) | | Adding an optional header to a request | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Adding a header to a response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the case of a header name | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the value of a header | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing a field from required to optional in a request body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing a field from optional to required in a response body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the text of an error message in a response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Add a new HTTP status code for the response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Deprecating a request or response field (for documentation) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### Breaking changes A *breaking change* is an API change that makes your current integration incompatible with the API. To avoid disrupting existing integrations, we introduce breaking changes in a new API version. You can continue to use existing API versions until you are ready to upgrade to the new version. We consider the following changes as breaking, depending on the [API type](#new-vs-classic). | Breaking change | New APIs | Classic APIs | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Adding a required field to a request body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Adding any field to a response body | [Non-breaking change](#non-breaking-changes) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Adding a required header to a request | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Removing an existing endpoint | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Removing a field from a request body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Removing a field from a response body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Removing a header from a request | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Removing a header from a response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the HTTP status code of a response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing error codes for an existing error | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing a field from optional to required in a request body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing a field from required to optional in a response body | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Renaming a field in a request or response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the type of a field in a request or response | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Changing the behavior in a way that requires API consumers to change their integration for it to work properly. For example, if an API was ignoring some errors and now starts returning a validation error, the change is a breaking change. | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | ### New API version without changes In some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future. For the same reason, we sometimes skip numbers in a versioning of specific APIs. ### Upgrading to a new API version In general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our platform. However, if you decide stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade. To prepare for an API upgrade, refer to the release notes to find out about changes. For example, [Checkout API](/online-payments/release-notes?integration_type=api). ## Server-side libraries Our [server-side API libraries](/development-resources/libraries) provide you with a convenient way to integrate without the need to directly connect to our APIs from your server-side code. Each library provides classes and methods that lets you use multiple Adyen APIs without needing to know the API versions. Instead, you need to consider the library version, which you specify when you include a library into your project. ### Versioning Adyen server-side API libraries use [semantic versioning](https://semver.org/), which is based on the *MAJOR.FEATURE.MINOR* format: * A *MAJOR* version release includes breaking changes to older usages of endpoints, such as changes in declarations and parameters. * A *FEATURE* version release includes new, non-breaking features. * A *MINOR* version release includes bug fixes or small non-breaking changes to endpoints. ### Upgrading to a new version of a server-side library We recommend that you upgrade to the latest version to benefit from new API releases and bug fixes. Check the latest releases from our [GitHub repository](https://github.com/Adyen). ## See also * [API Explorer](https://docs.adyen.com/api-explorer/?classes=codeLabel?classes=codeLabel/) * [Server-side libraries on GitHub](https://github.com/Adyen) --- # Source: https://docs.adyen.com/development-resources/webhooks.md Section: Development resources Title: Webhooks Description: Receive important updates related to events. --- title: "Webhooks" description: "Receive important updates related to events." url: "https://docs.adyen.com/development-resources/webhooks" source_url: "https://docs.adyen.com/development-resources/webhooks.md" canonical: "https://docs.adyen.com/development-resources/webhooks" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Webhooks Receive important updates related to events. [View source](/development-resources/webhooks.md) ##### Webhooks webinar ![](/user/pages/docs/13.development-resources/06.webhooks/help.svg?decoding=auto\&fetchpriority=auto) [Watch our on-demand webinar](https://help.adyen.com/academy/webinars/webhooks#join-live) to learn how to use Adyen webhooks for your integration. A webhook is a lightweight mechanism that allows an Adyen service to push event-driven messages using HTTP POST calls to an endpoint that you define. You need to accept webhooks that you receive with a 2xx HTTP status code, store the message, and process the contents of the message. When you configure a subscription to an Adyen webhook, you are requesting to be notified when an event has occurred. With webhooks, you can avoid having to continuously poll an API endpoint, waiting for a change in status for an asynchronous process, or for updates that your account holders make. Webhooks are great for long-running processes, where a change in a resource or its status may not occur for many seconds, minutes, hours, or days. In this way, you can make an API call, move on to other processes, and then act upon the status change when you receive a notification from Adyen that an event has occurred. ## Why you need to configure webhooks Should you configure webhooks to integrate with Adyen services? Yes, absolutely. Webhooks are an essential feature of a successful integration with Adyen. Here are some of the main benefits of using webhooks in your integration. ### Handling asynchronous flows Many flows in Adyen integrations are asynchronous, meaning the final status of a resource is not known immediately after you make an API request. For example, with payment methods like [iDEAL](/payment-methods/ideal), it can take time to get a confirmation that the payment was completed. Webhooks solve this by sending you a message with the final outcome as soon as it is available. You can also tie payment events to other updates in your backend, such as for order management and inventory control. For example, if a payment is successfully authorized, you can update the order status to "paid" and start the shipping process. ### State management You can use webhook messages to confirm or update the state of a resource in your own system. Some Adyen integrations need to manage several connected resources. For example, an [Adyen for Platforms](/platforms) integration requires you to manage account holders and their associated balance accounts, capabilities, and balances. Webhook messages contain a snapshot of the resource so your system can update its state accordingly. ### Reacting to external events Some important events come from external systems and are not a direct result of an API request you made. Webhooks are the only way to be automatically notified of these events. For example: * **[Onboarding verification](/issuing/onboard-users/onboarding-steps?location=nl\&legal_entity=individual#get-verification-updates)**: For [Adyen for Platform](/adyen-for-platforms-model) integrations, receive webhook messages when Adyen verifies your users and enables capabilities, or when more information is required to complete verification. * **[Dispute management](/risk-management/disputes-api/dispute-notifications)**: When a shopper initiates a [chargeback](/get-started-with-adyen/adyen-glossary#chargeback), Adyen sends a webhook message. This allows you to start the dispute resolution process immediately by gathering evidence and submitting a defense. * **[Report generation](/reporting/automatically-get-reports#get-notifications)**: Receive webhook messages when new reports become available, so you can [download reports](/reporting/automatically-get-reports#download-reports) for accounting and reconciliation purposes. * **[Relayed authorisation](/issuing/authorisation/relayed-authorisation)**: For integrations using Adyen Issuing, receive a webhook message when a cardholder of an Adyen-issued card makes a payment. For a list of webhook events that Adyen supports, see [Webhook structure & types](/development-resources/webhooks/webhook-types). ## Next steps [required](/development-resources/webhooks/configure-and-manage) [Configure and manage webhooks](/development-resources/webhooks/configure-and-manage) [Learn how to configure and manage subscriptions to Adyen webhooks.](/development-resources/webhooks/configure-and-manage) [required](/development-resources/webhooks/secure-webhooks) [Secure your webhooks](/development-resources/webhooks/secure-webhooks) [Learn about best practices for securing your webhooks.](/development-resources/webhooks/secure-webhooks) [required](/development-resources/webhooks/handle-webhook-events) [Handle webhook events](/development-resources/webhooks/handle-webhook-events) [Learn how to handle a webhook message you receive for an event.](/development-resources/webhooks/handle-webhook-events) [Webhook structure and types](/development-resources/webhooks/webhook-types) [Learn which webhook types are sent for each event.](/development-resources/webhooks/webhook-types) [Troubleshoot webhooks](/development-resources/webhooks/troubleshoot) [Find, diagnose, and resolve webhook delivery failures using the tools in your Customer Area.](/development-resources/webhooks/troubleshoot) --- # Source: https://docs.adyen.com/development-resources/webhooks/configure-and-manage.md Section: Development resources Title: Configure and manage webhooks Description: Learn how to configure and manage subscriptions to Adyen webhooks. --- title: "Configure and manage webhooks" description: "Learn how to configure and manage subscriptions to Adyen webhooks." url: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage" source_url: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage.md" canonical: "https://docs.adyen.com/development-resources/webhooks/configure-and-manage" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Configure and manage webhooks Learn how to configure and manage subscriptions to Adyen webhooks. [View source](/development-resources/webhooks/configure-and-manage.md) You can configure webhook subscriptions for your [company account](/account/account-structure/#company-account), [merchant account](/account/account-structure/#merchant-accounts), and [merchant account groups](/account/account-structure#account-groups). We strongly recommend that you configure your webhook subscriptions on the company account level. To configure a webhook subscription for a specific merchant account, create a webhook for your company account, and [configure merchant accounts](#configuring-merchant-accounts) to include or exclude specific merchant accounts from that webhook subscription. This ensures that you do not have duplicate webhook configurations, and improves performance. For improved performance, we also recommend that you limit the number of webhooks you configure for each company account. ## Requirements Before you begin to configure and manage webhooks, take into account the following requirements and preparations. | Requirement | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Integration type** | All integrations. | | **[Customer Area roles](/account/user-roles)** | Make sure that you have one of the following roles- **Merchant admin** - **Merchant technical integrator** | | **Setup steps** | Before you begin:- Read the section on [securing your webhooks](/development-resources/webhooks/secure-webhooks). | ## How it works To process webhooks, you need to: 1. [Expose an endpoint on your server](#expose-an-endpoint-on-your-server). 2. [Set up webhooks in your Customer Area](#set-up-webhooks-in-your-customer-area). 3. [Accept webhook events](#accept-webhooks). Embedded video (Vimeo): ## 1. Expose an endpoint on your server Webhooks are HTTP callbacks sent to an endpoint on your server. Adyen requires you to use HTTPS endpoints with TLSv1.2 or TLSv1.3. To receive webhook events, you need a server that has the following: * An endpoint that can receive a JSON or a SOAP call, or an HTTP POST.\ **Note:** If you plan to implement OAuth 2.0 for your webhook server, configure this endpoint to accept messages with an access token that has the correct permission scope. * For test environments: an open TCP port for HTTP traffic (must be 80, 8080, or 8888) or HTTPS traffic (must be 443, 8443, or 8843) with TLSv1.2 or TLSv1.3. * For live environments: an open TCP port for HTTPS traffic (must be 443, 8443, or 8843) with TLSv1.2 or TLSv1.3. * Authentication * If you plan to use basic authentication, you need the following for the webhook server: * username * password * If you plan to set up OAuth 2.0 for the **Standard webhook** type, you need the following: * Client ID * Client secret * URL * Scope (optional) You need to enter these in your Customer Area in [Step 2](#set-up-webhooks-in-your-customer-area). Depending on your network and security requirements, you might also need to [add our network to your firewall's allowlist](/development-resources/webhooks/secure-webhooks#domain-and-ip-addresses). ## 2. Set up webhooks in your Customer Area In your [Customer Area](https://ca-test.adyen.com/), enable and configure webhooks for your [company account](/account/account-structure/#company-account), [merchant account](/account/account-structure/#merchant-accounts), and [merchant account groups](/account/account-structure/#account-groups). However, we [recommend to configure webhooks for your company account](/development-resources/webhooks/configure-and-manage). To set up a webhook for a specific merchant account, create a webhook for your company account, and [configure merchant accounts](/development-resources/webhooks/configure-and-manage) for that webhook. * You can configure [Payments webhooks](/development-resources/webhooks/webhook-types#payments-webhooks) on the company, merchant account, and merchant account groups. * You can configure [Platforms webhooks](/development-resources/webhooks/webhook-types#platforms-webhooks) on the company account level only. **To configure a webhook:** 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Webhooks**.\ If you have a Balance Platform integration, select **Payments** or **Platforms** to view the webhooks available to you based on your integration. 2. Select ****Create new webhook**.\ If you are adding a webhook for your platform and have multiple platforms set up to run on Adyen, select the balance platform where you want to configure your new webhook. 3. From the list of webhooks, select **Add** for the one to add. 4. Under **General**, configure the following: | Setting | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Enabled** | Select the toggle to enable or disable the webhook. | | **Version** | The webhook version. | | **Description** | Your description of the webhook. | | **Merchant accounts** | You can apply the webhook to all merchant accounts for a company account, include only specific merchant accounts, or exclude specific merchant accounts for your company account. | 5. Under **Server configuration**, configure the following: | Setting | Description | | ----------------------- | --------------------------------------------------- | | **URL** | Your webhook server's URL. It must be a public URL. | | **Method** | JSON, HTTP POST, or SOAP | | **Encryption protocol** | TLSv1.2 or TLSv1.3 | 6. Under **Security**, configure the following: | Setting | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **OAuth 2.0** | **Note:** OAuth 2.0 support is available for the **Standard webhook** type only. If you want to use OAuth 2.0 for access to your webhook endpoint, enter the following for your Identity Provider's OAuth 2.0 server:- **Client ID** - **Client secret** - **URL**: The location of your Identity Provider's OAuth 2.0 authorization server, where Adyen should request new access tokens. The time-to-live (TTL) setting of your access tokens must be 3599 seconds, at a minimum. - **Scope**: The **Scope** is optional. The permission level Adyen's webhook service needs to access to your webhook endpoint. | | **Basic authentication** | Enter the following for your webhook server:- **username** - **password** | | **HMAC Key** | Generate a new HMAC Key or use an existing HMAC key. | 7. Under **Events** settings, select the [event types](/development-resources/webhooks/webhook-types/#event-codes) for this webhook. Some webhook types do not support more than one event type, so this setting does not appear. 8. If the **Additional settings** section is available, optionally select the additional information you want to receive in this webhook. Some webhook types do not support more than one event type, so this section does not appear. 9. Select **Save configuration**. ## 3. Accept webhooks We require you to acknowledge every webhook event with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), for example **200** or **202**. If we do not receive this response within 10 seconds for an reason, such as your server is down or your service is unavailable, all webhook events to your endpoint go to the [retry queue](/development-resources/webhooks/troubleshoot#retry-queue). In addition to accepting the webhook, there are other steps you should take to [handle your webhooks](/development-resources/webhooks/handle-webhook-events). For information about the structure and content of webhooks, refer to [Webhook structure and types](/development-resources/webhooks/webhook-types). ## 4. Test and go live Embedded video (Vimeo): ### Test your webhooks server Your server must [acknowledge webhooks with a successful HTTP response status code (like **202**)](#accept-webhooks). 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Select **Developers** > **Webhooks**. 3. Select the webhook to test.\ The **Webhook details** panel includes information about the configuration. Under **Events**, you can find the configured event types that you can test for this webhook. 4. Select the edit **icon 5. Select **Test configuration**. 6. If you are on a [company account](/account/account-structure#company-account), select a **Merchant account** from the dropdown list. 7. In the **Event** dropdown list, select the [event type](/development-resources/webhooks/webhook-types#event-codes) to test webhooks for. If the test webhook failed, you get an error message with the reason. [Troubleshoot the problem](/development-resources/webhooks/troubleshoot). ### End-to-end testing We recommend you create a test payment and test the webhooks associated with it. Match the test payment to the webhook you receive with the `pspReference` or `merchantReference` within the [webhook message](/development-resources/webhooks/webhook-types#webhook-structure). ### Go live 1. Follow the instructions in [Set up webhooks in your Customer Area](#set-up-webhooks-in-your-customer-area) from the [live Customer Area](https://ca-live.adyen.com/) to create webhook subscriptions on the live environment.\ **Note:** Adyen does not provide a "copy" function for moving your webhook configurations from the test environment to the live environment. You need to configure all of your webhook subscriptions in the live environment. 2. Test webhooks in your [live Customer Area](https://ca-live.adyen.com/). 3. If you are verifying HMAC signatures, make sure that you use the HMAC key from your [live Customer Area](https://ca-live.adyen.com/), which is different from the HMAC key from your [test Customer Area](https://ca-test.adyen.com/). ## Configure webhooks for multiple merchant accounts If you are on your company account, you can configure webhook settings for all merchant accounts, or for a group of merchant accounts you decide to include/exclude. 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Webhooks**. 2. From the list of webhooks, select the one to configure. 3. Select either **Edit webhook** or the edit icon **. 4. Under **General**, select one of the following options from the **Merchant Accounts** dropdown menu: * **All merchant accounts** to apply the webhook settings to all merchant accounts. * **Include only specific merchant accounts** and select the merchant accounts to include. * **Exclude specific merchant accounts** and select the merchant accounts to exclude. 5. Select **Save configuration**. ## Configure your existing webhook endpoint You can change the endpoint of your existing webhook. Adyen requires you to use HTTPS endpoints with a [compatible TLS configuration](/development-resources/integration-security-guide/#use-the-correct-tls-configuration) to receive Adyen webhook events. Before you configure your endpoint to receive Adyen webhook events, you need to make sure it supports connections using the correct TLS version and cipher suite. ### Update your endpoint URL 1. Log in to your [Customer Area](https://ca-test.adyen.com/).\ If you are updating an endpoint for a platforms webhook, make sure you have your company account selected. 2. Go to **Developers** > **Webhooks**. 3. From the list of webhooks, select the one to configure. 4. Select **Edit webhook** or the edit icon **. 5. Under **Server configuration**, configure the following: | Setting | Description | | ----------------------- | --------------------------------------------------------------------- | | **URL** | Your webhook server's HTTPS URL. The URL must be publicly accessible. | | **Method** | JSON, HTTP POST, or SOAP | | **Encryption protocol** | TLSv1.2 or TLSv1.3 | 6. Select **Save configuration**. #### If you want to change your endpoint and disable the old endpoint for receiving webhooks: 1. [Add a new endpoint in your Customer Area](#set-up-webhooks-in-your-customer-area). 2. [Disable the old endpoint](#disabling-webhooks). ## Disable and delete webhook configurations You may want to disable webhooks when: * Your webhook endpoint is temporarily unable to receive webhooks, for example during server maintenance. * You have set up a new webhook endpoint for webhooks. To disable a webhook configuration: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Select the account for which you want disable your webhook configuration. 3. Go to **Developers** > **Webhooks**. 4. From the list of webhook configurations, select the webhook you want to disable. 5. Under **General**, clear the **Enabled** toggle to disable the webhook. 6. Select **Save configuration**. In the list of webhook configurations, you will see the status **Disabled** next to the webhook. We will then queue all webhook events to this endpoint. You will receive the queued webhook events when you reactivate this endpoint configuration by selecting the **Active** checkbox. Webhook configurations that have been inactive for more than six months are automatically deleted. To delete a webhook configuration: 1. Log in to your [Customer Area](https://ca-test.adyen.com/). 2. Select the account for which you want to delete your webhook configuration. 3. Go to **Developers** > **Webhooks**. 4. Next to the webhook configuration you want to delete, select the delete icon **. 5. Select **Delete** to confirm your choice to delete the webhook configuration. --- # Source: https://docs.adyen.com/development-resources/webhooks/handle-webhook-events.md Section: Development resources Title: Handle webhook events Description: Learn how to handle Adyen webhook events. --- title: "Handle webhook events" description: "Learn how to handle Adyen webhook events." url: "https://docs.adyen.com/development-resources/webhooks/handle-webhook-events" source_url: "https://docs.adyen.com/development-resources/webhooks/handle-webhook-events.md" canonical: "https://docs.adyen.com/development-resources/webhooks/handle-webhook-events" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Handle webhook events Learn how to handle Adyen webhook events. [View source](/development-resources/webhooks/handle-webhook-events.md) Webhooks are important for keeping your system synchronized with events that happen on the Adyen side, such as payment status changes or user onboarding. Your webhook endpoint needs to handle these messages properly to prevent missed events and to ensure that your system is up-to-date with the latest information from Adyen. This involves [securing](#secure-webhooks), [accepting](#accept-webhooks), and [processing webhook](#process-webhooks) messages as you receive them. This page guides you through best practices for each of these steps. ## How it works To begin receiving webhook messages, you need to [configure a webhook](/development-resources/webhooks/configure-and-manage/#configuring-a-webhook) in your Customer Area. Adyen then sends webhook messages to the webhook endpoint you configured. The endpoint needs to be publicly accessible without any redirects and have high availability to incoming requests. When your endpoint receives a webhook message: 1. [Verify the webhook message](#verify-webhooks) by confirming that it was sent by Adyen, and was not modified during transmission. If the webhook message is not secure, we do not recommend accepting it. 2. Store the webhook message in your database or a queue so you can process it later. 3. [Accept the webhook message](#accept-webhooks) by responding with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), such as **200** or **202**. 4. [Process the data](#process-webhooks) and apply your business logic. Make sure that you acknowledge the webhook before applying any business logic, because errors in your business logic could lead to [failing webhooks](/development-resources/webhooks/troubleshoot/#retry-queue). ## Verify webhooks You must verify that the webhook is a genuine message from Adyen and was not modified in transit. Methods like [domain and IP allowlisting](/development-resources/webhooks/secure-webhooks#domain-and-ip-addresses), or basic authentication provide a layer of security. Verifying message integrity using [HMAC signature verification](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures) is another strong security measure. Always verify the HMAC signature before processing the payload and using its data. This ensures the data is authentic and allows you to discard any fraudulent or corrupt messages. If the webhook message is not secure, we do not recommend accepting it. For more information about webhook security, see [Secure webhooks](/development-resources/webhooks/secure-webhooks). ## Accept webhooks When you receive a webhook message from Adyen, you need to respond with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), such as **202**, to indicate successful delivery of the webhook message. Do not validate or process the data at this step. If Adyen does not receive this response within 10 seconds, for example because your server is down, we mark the webhook as Failing and put it in a [retry queue](/development-resources/webhooks/troubleshoot/#retry-queue). ## Process webhooks After you accept and secure the webhook message, you can begin processing the data in the payload. This involves parsing the payload and using the data to update your systems. ### Webhook payload A webhook consists of headers and a JSON body. The body contains the event data, including an `eventCode` or `type` describing what happened, and a timestamp that identifies when the event occurred. To ensure you are processing events in the correct chronological order, always check the timestamp. Some webhooks also contain unique identifiers such as `sequenceNumber` that you can also use to handle the data in the correct order. ### Using an Adyen library to parse the payload One of the benefits of using the [Adyen server libraries](https://github.com/Adyen#server-side) is that you get access to tools that help you deserialize, verify, and parse data from webhook messages. This saves you from writing boilerplate code to parse the webhooks yourself, and gives you the benefit of type safety and auto-completion in your IDE. The library also includes a validator to [verify the HMAC signature](#secure-webhooks), which is an important step in [securing your webhooks](#secure-webhooks). Our libraries are available for several popular programming languages. To get started, find the library for your preferred language on our [Adyen GitHub page](https://github.com/Adyen#server-side) and go to **Supported webhook versions**. ### Handling duplicates In some cases it is possible that you receive the same webhook event twice, so make sure that your system is able to deal with duplicates. These duplicate webhook events have the same values in the `eventCode` and `pspReference` fields, while the `eventDate` and other fields can be different. Your server should use the details from the latest webhook event. ## See also * [Webhook structure and types](/development-resources/webhooks/webhook-types) * [Verify HMAC signatures](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures) --- # Source: https://docs.adyen.com/development-resources/webhooks/secure-webhooks.md Section: Development resources Title: Secure webhooks Description: Learn about best practices for securing your webhooks. --- title: "Secure webhooks" description: "Learn about best practices for securing your webhooks." url: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks" source_url: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks.md" canonical: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Secure webhooks Learn about best practices for securing your webhooks. [View source](/development-resources/webhooks/secure-webhooks.md) When configuring webhooks for your Adyen implementation, consider our security recommendations to ensure the messages you receive about events are from Adyen, and were not modified during transmission to you. ## Securing webhooks in the Customer Area The following video explains ways to secure your webhook in the Customer Area. Embedded video (Vimeo): ## Authentication / Authorization We also recommend that you use an authentication mechanism for access to your webhook endpoints to ensure the webhook events you receive were sent by Adyen. You can use one of the following authentication mechanisms for webhook endpoint access: * **Open Authorization (OAuth 2.0)**: strongly recommended and supported for the **Standard webhook** type * **Basic Authentication**: supported for all Adyen webhook types ### Open Authorization (OAuth 2.0) **Note:** OAuth 2.0 support is available for the **Standard webhook** type only. We strongly recommend that you use OAuth 2.0 for the **Standard webhook** type. OAuth 2.0 is a much safer option than basic authentication, ensuring that your server credentials are not compromised. With an OAuth 2.0 implementation, Adyen requests an OAuth 2.0 access token for sending webhook events to your webhook endpoint. After Adyen obtains an access token from your OAuth 2.0 Identity Provider's authorization server, we send the access token in the header of each webhook event, so you can authenticate the request with your webhook server endpoint. To [set up OAuth 2.0 for the Standard webhook type](/development-resources/webhooks/configure-and-manage#set-up-webhooks-in-your-customer-area/) in your [Customer Area](https://ca-test.adyen.com/), you must provide the following: * **Client ID** * **Client secret** - Make sure to protect your client secret and never embed it in client-side code, as this would expose it to potential misuse. * **URL**: The location of your OAuth 2.0 Identity Provider's authorization server where Adyen should request new access tokens.\ At a minimum, the time-to-live (TTL) setting of your access tokens must be one hour (3599 seconds). * **Scope**: The permission level that Adyen's webhook service needs to access your webhook endpoint.\ We strongly encourage you to follow the principle of least privilege when creating scopes. Only grant the permissions that are absolutely necessary for your integration. We recommend that you rotate your OAuth 2.0 client credentials periodically to proactively reduce risk and maintain the highest level of security. ### Basic authentication over HTTPS For all webhooks types other than the **Standard webhook** type, we recommend that you use basic authentication over HTTPS. **Note:** You can use basic authentication over HTTPS instead of OAuth 2.0 for the **Standard webhook** type. However, basic authentication can leave your server more vulnerable to compromise. After you have [set up a username and password for basic authentication](/development-resources/webhooks/configure-and-manage/#set-up-webhooks-in-your-customer-area) in your [Customer Area](https://ca-test.adyen.com/), we include these in the header of the webhook event, so you can authenticate the request with your server. To ensure basic authentication is secure, you must use HTTPS for your webhook endpoint; otherwise your basic authentication credentials can be compromised. Basic authentication only guarantees that the webhook event was sent by Adyen, not that it wasn't modified during transmission. ## Hash-based message authentication code (HMAC) signatures To protect your server from unauthorized webhooks, we strongly recommend that you use [Hash-based message authentication code](https://en.wikipedia.org/wiki/HMAC) (HMAC) signatures. By verifying the signature included in a webhook event, you confirm that the event was sent by Adyen, and was not modified during transmission. For more information, refer to [Verify HMAC signatures](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures). ### Changing your HMAC key If you need to change the secret HMAC key used to sign webhook events, it is enough to [generate a new HMAC key](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures#enable-hmac-signatures) in your [Customer Area](https://ca-test.adyen.com/). If you generate a new HMAC key, it can take some time to propagate this in our infrastructure, so make sure that you can still accept webhook events signed with your previous HMAC key for some time. ## Domain and IP addresses Depending on your network and security requirements, you might need to add Adyen's network to your firewall's allowlist to receive [webhook events](/development-resources/webhooks/webhook-types/) from us. We do not provide a list of IP addresses. IP addresses change over time due to various reasons, such as ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded. To make sure you can communicate with our network, you can either: * **Use a domain allowlist**. Include our domain `out.adyen.com` if your network configuration allows domain allowlisting. * **Systematically resolve our IP addresses**. Perform DNS lookup for `out.adyen.com`. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval. --- # Source: https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures.md Section: Development resources Title: Verify HMAC signatures Description: Verify the integrity of webhook events using HMAC signatures. --- title: "Verify HMAC signatures" description: "Verify the integrity of webhook events using HMAC signatures." url: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures" source_url: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures.md" canonical: "https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Verify HMAC signatures Verify the integrity of webhook events using HMAC signatures. [View source](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures.md) To protect your server from unauthorised webhook events, we strongly recommend that you use [Hash-based message authentication code](https://en.wikipedia.org/wiki/HMAC) (HMAC) signatures for our webhooks that support it. For the ones that support [enabling HMAC signatures](#enable-hmac-signatures), each webhook event will include a signature calculated using a secret HMAC key and a payload from the webhook. By verifying this signature, you confirm that the webhook was sent by Adyen, and was not modified during transmission. To verify HMAC signatures, you can either: * [Use one of our libraries](#verify-using-our-libraries). * [Build your own custom solution](#verify-using-your-own-solution). ## Enable HMAC signatures Each secret HMAC key is linked to one webhook endpoint. If you have multiple endpoints for receiving webhooks, generate an HMAC key for each of them. You also need to generate a new HMAC key when you [switch from test to live](/development-resources/webhooks/configure-and-manage#test-and-go-live). To start receiving HMAC signed webhooks, if the option is available: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Webhooks**. 2. From the list of webhooks, select the one to configure. 3. Select **Edit webhook** or the edit icon **. 4. Under **Security**, generate a new HMAC key or enter an existing HMAC key.\ If you generate a new HMAC key, copy it and store it securely in your system. 5. Select **Save configuration**. The HMAC key will now be used to sign webhook events that we send to your server. For our [Standard webhooks](/development-resources/webhooks/webhook-types), the signature is included in the `additionalData` field. For [other types of webhooks](/development-resources/webhooks/webhook-types#other-webhooks), although rare, the signature can be included in the request header. When the HMAC signature is included in the header, the steps to follow to verify the signature is different. See [Verify HMAC keys returned in the header](#verify-hmac-in-header). ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData":{ "hmacSignature":"+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw=" }, ... } } ] } ``` ### Changing your HMAC key If you need to change the secret HMAC key used to sign webhook events, it is enough to [generate a new HMAC key](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures#enable-hmac-signatures) in your [Customer Area](https://ca-test.adyen.com/). If you generate a new HMAC key, it can take some time to propagate this in our infrastructure, so make sure that you can still accept webhook events signed with your previous HMAC key for some time. ## Verify using our libraries You can verify HMAC signatures using Adyen's packaged HMAC validator libraries: * [Java library](https://github.com/Adyen/adyen-java-api-library/blob/master/src/main/java/com/adyen/util/HMACValidator.java) * [PHP library](https://github.com/Adyen/adyen-php-api-library/blob/9c351e93d0ac7000524f70f31c164f682dbf7492/src/Adyen/Util/HmacSignature.php) * [C# library](https://github.com/Adyen/adyen-dotnet-api-library/blob/fc3301c13db828ac9d3ff4054eac2f4dcaecf208/Adyen/Util/HMACValidator.cs) * [JavaScript library](https://github.com/Adyen/adyen-node-api-library/blob/7e76d1b4c87d334f98a1ddc70b4e30a225244d2e/src/utils/hmacValidator.ts) * [Ruby Library](https://github.com/Adyen/adyen-ruby-api-library/blob/develop/lib/adyen/utils/hmac_validator.rb) * [Python Library](https://github.com/Adyen/adyen-python-api-library/blob/develop/Adyen/util.py) #### Java ```java // YOUR_HMAC_KEY from the Customer Area String hmacKey = "YOUR_HMAC_KEY"; // Notification Request JSON String notificationRequestJson = "NOTIFICATION_REQUEST_JSON"; HMACValidator hmacValidator = new HMACValidator(); WebhookHandler webhookHandler = new WebhookHandler(); NotificationRequest notificationRequest = webhookHandler.handleNotificationJson(notificationRequestJson); // Handle multiple notificationRequests List notificationRequestItems = notificationRequest.getNotificationItems(); for ( NotificationRequestItem notificationRequestItem : notificationRequestItems ) { // Handle the notification if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) { // Process the notification based on the eventCode String eventCode = notificationRequestItem.getEventCode(); } else { // Non valid NotificationRequest System.out.print("Non valid NotificationRequest"); } } ``` #### PHP ```php // YOUR_HMAC_KEY from the Customer Area $hmacKey = "YOUR_HMAC_KEY"; // Notification Request JSON $jsonRequest = "NOTIFICATION_REQUEST_JSON"; $notificationRequest = json_decode($jsonRequest, true); $hmac = new \Adyen\Util\HmacSignature(); // Handling multiple notificationRequests foreach ( $notificationRequest["notificationItems"] as $notificationRequestItem ) { $params = $notificationRequestItem["NotificationRequestItem"]; // Handle the notification if ( $hmac->isValidNotificationHMAC($hmacKey, $params) ) { // Process the notification based on the eventCode $eventcode = $params['eventCode']; print_r($eventcode); } else { // Non valid NotificationRequest } } ``` #### C\# ```cs // YOUR_HMAC_KEY from the Customer Area string hmacKey = "YOUR_HMAC_KEY"; // Notification Request JSON string notificationRequestJson = "NOTIFICATION_REQUEST_JSON"; var hmacValidator = new HmacValidator(); var notificationHandler = new NotificationHandler(); var handleNotificationRequest = notificationHandler.HandleNotificationRequest(notificationRequestJson); // Handle multiple notificationRequests List notificationRequestItemContainers = handleNotificationRequest.NotificationItemContainers; foreach ( var notificationRequestItemContainer in notificationRequestItemContainers ) { var notificationItem = notificationRequestItemContainer.NotificationItem; // Handle the notification if ( hmacValidator.IsValidHmac(notificationItem, hmacKey) ) { // Process the notification based on the eventCode string eventCode = notificationItem.EventCode; } else { // Non valid NotificationRequest } } ``` #### NodeJS (JavaScript) ```js const { hmacValidator } = require('@adyen/api-library'); // YOUR_HMAC_KEY from the Customer Area const hmacKey = "YOUR_HMAC_KEY"; const validator = new hmacValidator() // Notification Request JSON const notificationRequest = NOTIFICATION_REQUEST_JSON; const notificationRequestItems = notificationRequest.notificationItems // Handling multiple notificationRequests notificationRequestItems.forEach(function(notificationRequestItem) { // Get the notification const notification = notificationRequestItem.NotificationRequestItem // Handle the notification if( validator.validateHMAC(notification, hmacKey) ) { // Process the notification based on the eventCode const eventCode = notification.eventCode; } else { // Non valid NotificationRequest console.log("Non valid NotificationRequest"); } }); ``` ## Verify using your own solution To build your own solution for verifying HMAC signatures, follow these steps: ### Step 1: Construct the payload The values used below are from an [example webhook](#example). To test your solution, replace the values with actual values that you receive in a webhook event. Concatenate the following values from the webhook event, in the given order: | Key | Value | | --------------------- | ----------------------------- | | `pspReference` | **7914073381342284** | | `originalReference` | | | `merchantAccountCode` | **TestMerchant** | | `merchantReference` | **TestPayment-1407325143704** | | `value` | **1130** | | `currency` | **EUR** | | `eventCode` | **AUTHORISATION** | | `success` | **true** | Assign an empty string to any fields that are empty, and use a colon (":") to delimit the values. For the above values, with an empty `originalReference`, you get: ```bash 7914073381342284::TestMerchant:TestPayment-1407325143704:1130:EUR:AUTHORISATION:true ``` ### Step 2: Calculate the HMAC signature For **hints** about how to calculate the signature, have a look at the [library code samples](#verify-using-our-libraries) above. 1. Convert the [payload that you constructed](#construct-the-payload) to a binary representation, given the UTF-8 charset. 2. Convert the hexadecimal HMAC key that you [generated in your Customer Area](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures/#enable-hmac-signatures) from a hexadecimal string to a binary representation, given the UTF-8 charset. 3. Calculate an HMAC using: * The [SHA256](https://en.wikipedia.org/wiki/SHA-2) function. * The binary representation of the payload. * The binary representation of the HMAC key. 4. To get the final signature, [Base64](https://en.wikipedia.org/wiki/Base64)-encode the result. ### Step 3: Compare signatures If the signature that you calculated in [Step 2](#calculate-the-hmac-signature) matches the `hmacSignature` that you received, you'll know that the webhook event was sent by Adyen and was not modified during transmission. ### Example Sample HMAC key: ```bash 44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056 ``` Sample webhook event signed using the above HMAC key: ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData":{ "hmacSignature":"coqCmt/IZ4E3CzPvMY8zTjQVL5hYJUiBRg8UU+iCWo0=" }, "amount":{ "value":1130, "currency":"EUR" }, "pspReference":"7914073381342284", "eventCode":"AUTHORISATION", "eventDate":"2019-05-06T17:15:34.121+02:00", "merchantAccountCode":"TestMerchant", "operations":[ "CANCEL", "CAPTURE", "REFUND" ], "merchantReference":"TestPayment-1407325143704", "paymentMethod":"visa", "success":"true" } } ] } ``` ## Verify HMAC keys returned in the header For non-standard webhooks, Adyen can sign the webhook with an HMAC signature in the request header, instead of including it in the `additionalData` field. If you enabled [other webhooks](/development-resources/webhooks/webhook-types#other-webhooks) that follow this pattern, for example, the **Recurring tokens life cycle events** webhook, there are different steps to verify the HMAC signature. 1. For every webhook that you receive, get the values from the following headers: * `hmacsignature`: Contains the signature. * `protocol`: The protocol used to create the signature, **HmacSHA256**. 2. Calculate the signature using: * [SHA256](https://en.wikipedia.org/wiki/SHA-2). * The binary representation of the payload. * The binary representation of the HMAC key. * Make sure that the request body is as it is—do not deserialize it. 3. To get the final signature, [Base64](https://en.wikipedia.org/wiki/Base64)-encode the result. 4. Compare the `hmacsignature` received from the header and the calculated signature. If the signatures match, then the webhook was sent by Adyen and was not modified during transmission. Below is an examples HMAC signature validation. #### Java ```java import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Arrays; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.DecoderException; import org.apache.commons.codec.binary.Base64; import org.apache.commons.codec.binary.Hex; import org.junit.Assert; import org.junit.Test; public class NotificationHmacExampleTest { @Test public void testNotificationHmac(){ Base64 base64 = new Base64(); // Example HEX Key (submitted at the moment of subscription) String hmacSignatureKey = "6D5BADA576A73109D879220DCB793FFD67DEF7AA18C74CCC0AB66FD87AC8AEEA"; // Signature: retrieved from HTTP header under the name HmacSignature. String hmacSignature = "nvsZjQiHBuscSdtcA2cl1E+PSLJfgjPeRdd0pSaRiA0="; // Protocol: retrieved from HTTP header under the name Protocol. String protocol = "HmacSHA256"; // Payload: body of the notification String payload = "{\"createdAt\":\"2024-01-14T18:10:49+01:00\",\"environment\":\"test\",\"type\":\"recurring.token.disabled\",\"data\":{\"merchantAccount\":\"YOUR_MERCHANT_ACCOUNT\",\"shopperReference\":\"YOUR_SHOPPER_REFERENCE\",\"storedPaymentMethodId\":\"M5N7TQ4TG5PFWR50\",\"type\":\"visa\"},\"eventId\":\"QBQQ9DLNRHHKGK38\"}"; try { // decode HEX Key into bytes byte[] keyBytes = Hex.decodeHex(hmacSignatureKey.toCharArray()); // get payload in bytes byte[] payloadBytes = payload.getBytes("UTF-8"); // instantiate the MAC object using HMAC / SHA256 Mac hmacSha256 = Mac.getInstance(protocol); // create a key object using the secret key and MAC object SecretKey secretKey = new SecretKeySpec(keyBytes, hmacSha256.getAlgorithm()); // initialise the MAC object hmacSha256.init(secretKey); // finalize the MAC operation byte[] signedPayload = hmacSha256.doFinal(payloadBytes); // encode the signed payload in Base64 byte[] encodedSignedPayload = base64.encode(signedPayload); System.out.println("original HMAC signature: " + hmacSignature); System.out.println("computed HMAC signature: " + new String(encodedSignedPayload, "ASCII")); // assert the calculated Base64 encoded HMAC is equal to the received Base64 encoded HMAC Assert.assertTrue(Arrays.equals(encodedSignedPayload, hmacSignature.getBytes("UTF-8"))); } catch (NoSuchAlgorithmException e) { // HmacSHA256 should be supported } catch (UnsupportedEncodingException e) { // UTF-8 should be supported } catch (DecoderException e) { // Check key for odd number or characters outside of HEX (base16) } catch (InvalidKeyException e) { // The key is invalid } } } ``` #### Python ```py import hmac import hashlib import base64 def checkHmac(payload, hmac_key, hmac_sig): # payload is the request body as it is # hmac_key is the secret # hmac_sig is the signature from the header hmac_key = binascii.a2b_hex(hmac_key) # Calculate signature calculatedHmac = hmac.new(hmac_key, payload.encode('utf-8'), hashlib.sha256).digest() calculatedHmac_b64 = base64.b64encode(calculatedHmac) receivedHmac_b64 = hmac_sig.encode('utf-8') validSignature = hmac.compare_digest(receivedHmac_b64, calculatedHmac_b64) if not validSignature: print('HMAC is invalid: {} {}'.format(receivedHmac_b64, calculatedHmac_b64)) return False return True ``` ## See also * [Webhooks](/development-resources/webhooks) --- # Source: https://docs.adyen.com/development-resources/webhooks/troubleshoot.md Section: Development resources Title: Troubleshoot webhooks Description: Find, diagnose, and resolve webhook delivery failures using the tools in your Customer Area. --- title: "Troubleshoot webhooks" description: "Find, diagnose, and resolve webhook delivery failures using the tools in your Customer Area." url: "https://docs.adyen.com/development-resources/webhooks/troubleshoot" source_url: "https://docs.adyen.com/development-resources/webhooks/troubleshoot.md" canonical: "https://docs.adyen.com/development-resources/webhooks/troubleshoot" last_modified: "2026-06-05T13:33:05+02:00" language: "en" --- # Troubleshoot webhooks Find, diagnose, and resolve webhook delivery failures using the tools in your Customer Area. [View source](/development-resources/webhooks/troubleshoot.md) If Adyen cannot reach your server to deliver a webhook message, the webhook is placed in a [retry queue](#retry-queue) to give you time to resolve the issue. Use this guide to [troubleshoot](#troubleshoot) and [resolve webhook delivery failures](#resolve-failures) using the tools in your Customer Area. ## Retry queue If you do not [accept a webhook message](/development-resources/webhooks/handle-webhook-events#accept-webhooks) by responding with a successful HTTP status code, we consider the webhook delivery a failure and set the webhook status to **Failing**. Adyen retries sending the webhook message three times before placing the webhook into a retry queue. The initial delivery attempts are sent at 9 seconds, 18 seconds, and again at 27 seconds. Retry queues are separate for each webhook endpoint. If you have multiple endpoints, you must troubleshoot them individually. From the queue, we automatically retry sending the webhook for up to 30 days. After the first three failed retries, we retry sending the webhook in the following intervals: * 2 minutes * 5 minutes * 10 minutes * 15 minutes * 30 minutes * 1 hour * 2 hours * 4 hours * 8 hours If a retry is successful, we continue with the next webhook in the queue. ## Troubleshoot failures 1. In your [Customer Area](https://ca-live.adyen.com/), go to **Developers** > **Webhooks**. 2. Find the webhook endpoint with a **Failing** status and select it. 3. Select **Troubleshoot** to view the list of failed webhook messages for that endpoint. Each failed event includes an error message and a timestamp. This video shows how to find and troubleshoot failing webhooks: Embedded video (Vimeo): The error message can help you diagnose the issue. The exact meaning depends on your server setup, but here are some common errors based on standard HTTP response codes: | HTTP Error | Potential Cause | Recommended Action | | ------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **401: Unauthorized** | Your server is refusing the connection due to invalid credentials. | Check that your [webhook security](/development-resources/webhooks/secure-webhooks) (basic authentication or HMAC) is set up correctly. Consider rotating credentials if they have been compromised. | | **404: Not found** | The webhook URL could not be reached. | Ensure the endpoint URL is correct, publicly accessible, and not blocked by a firewall. | | **422: Unprocessable content** | Your server received the webhook but your business logic rejected it. | This can be due to validation logic on your endpoint. We recommend acknowledging receipt with `[200 OK]` first, and performing business logic separately. | | **429: Too many requests** | Your server is rate-limiting requests from Adyen. | This can happen after you fix a failing endpoint, as the queued webhooks are sent in a short timeframe. Ensure your server can handle the load. | | **500: Internal server error** | A generic error occurred on your server. | Check your server logs to identify the root cause. Ensure the endpoint is available and the application is running correctly. | Multiple Adyen products use webhooks. Successfully receiving one type of webhook (for example, for a payment authorisation) does not guarantee successful delivery of all types. Always use the **Troubleshoot** tool for reliable diagnostics. ## Resolve failures From the **Troubleshoot** page for a failing webhook, you can manually intervene: * **Retry**: After you deploy a fix, manually send the webhook message to your server again. * **Ignore**: If a webhook is no longer needed, permanently remove it from the queue. After you have identified the cause of the failure and deployed a fix to your server: 1. Navigate to the failed webhook event as shown in [Step 1](#find-and-diagnose-failures). 2. Select **Retry** to send the webhook to your endpoint again. A success message indicates your endpoint has accepted it. If it fails, you will get a new error message. 3. If the webhook event is outdated or no longer relevant, select **Ignore**. The event is permanently removed from the queue and cannot be retried. ## Set up failure alerts You can receive alerts by email or in the Customer Area notification center when webhooks fail. Adyen sends the following types of alerts: * **Initial Failure**: Receive an alert when we detect that your webhook endpoint is consistently failing to accept events. Adyen sends an alert after 5 retry attempts. * **Ongoing Failure**: Get notified if a failing endpoint remains unresponsive for an extended period. Adyen sends an alert after 7 days of a webhook failing. * **Recovery**: Adyen informs you when a previously failing webhook endpoint successfully starts accepting events again. To configure alerts: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Notification center** **> **Settings**. 2. Under **Developers and Integrations**, find the topic **Webhooks**. 3. Use the toggles to enable or disable **Email** or **Notification center** alerts. When the **Email** toggle is enabled, email notifications are sent to the email address linked to your user. ## See also * [Webhook event logs](/development-resources/logs-resources/webhook-event-logs/) * [Handle webhook events](/development-resources/webhooks/handle-webhook-events) * [Webhooks overview](/development-resources/webhooks/) * [Secure webhooks](/development-resources/webhooks/secure-webhooks/) --- # Source: https://docs.adyen.com/development-resources/webhooks/webhook-types.md Section: Development resources Title: Webhook structure and types Description: Learn which webhook types are sent for each event. --- title: "Webhook structure and types" description: "Learn which webhook types are sent for each event." url: "https://docs.adyen.com/development-resources/webhooks/webhook-types" source_url: "https://docs.adyen.com/development-resources/webhooks/webhook-types.md" canonical: "https://docs.adyen.com/development-resources/webhooks/webhook-types" last_modified: "2023-10-27T13:18:00+02:00" language: "en" --- # Webhook structure and types Learn which webhook types are sent for each event. [View source](/development-resources/webhooks/webhook-types.md) When you configure a webhook, Adyen offers different webhook types to choose from. Each webhook type has its own corresponding [events](#event-codes) that you can subscribe to. For example, the [Standard webhook type](#standard-webhooks) subscribes your endpoint to a set of [default event types](#default-event-codes). This page provides you with a list of webhook types, and which event types Adyen offers for each. There are two main categories of webhooks: * [Payments webhooks](#webhook-structure) * [Platforms webhooks](#platforms-webhooks) ## Event types Every webhook message contains an event type. The event type lets your server know what kind of information a webhook message contains. The event types your server receives depends on which webhooks you configured in your Customer area. For example, if you configure a Configuration webhook, you will receive webhook messages with its [corresponding event types](#configuration-webhook). Use the event type to inform the business logic in your system. For example, if you receive a webhook message with an `eventCode` of **CAPTURED**, you can update your order management system and start the shipping process. The event type is indicated by different fields, depending on the webhook type. * In [Payments webhooks](#webhook-structure), the event type is typically in the `eventCode` field. * In [Platforms webhooks](#platforms-webhook-structure), the event type is typically in the `type` field. ## Payments webhooks ### Payments webhook structure Each payments webhook payload contains the following fields. * `live`: Specifies whether the event happened on the test or live environment. * `notificationItems`: An array of `NotificationRequestItem` objects. JSON and HTTP POST webhooks contain only one `NotificationRequestItem` object in the `notificationItems` array. SOAP webhooks may contain up to six `NotificationRequestItem` objects, in case the events happen within a very short period of time. The `notificationItems` object contains information about the event: * `additionalData`: Additional information about the shopper or the transaction. For more information about the fields that you can receive in `additionalData`, refer to [Additional settings](/development-resources/webhooks/webhook-types/additional-settings). * `eventCode`: The [event type](#event-codes). * `success`: The outcome of the event, set to either **true** or **false**. For some event codes, such as **REPORT\_AVAILABLE**, the `success` field is always set to **true**. * `eventDate`: The time of the event. Format: [ISO 8601](http://www.w3.org/TR/NOTE-datetime); YYYY-MM-DDThh:mm:ssTZD #### JSON ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData": { ... }, "eventCode":"AUTHORISATION", "success":"true", "eventDate":"2019-06-28T18:03:50+01:00", "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT", "pspReference": "7914073381342284", "merchantReference": "YOUR_REFERENCE", "amount": { "value":1130, "currency":"EUR" } } } ] } ``` #### Soap ```xml false ... EUR 1130 AUTHORISATION 2019-06-28T18:03:50+01:00 YOUR_MERCHANT_ACCOUNT YOUR_TRANSACTION_REFERENCE visa 7914073381342284 true ``` Some fields included in the `NotificationRequestItem` object depend on the type of event triggered. For example, webhook events triggered by a request to [refund](/online-payments/refund) a payment include: * `originalReference`: The `pspReference` of the original payment. ### Standard webhooks For most payment integrations, you need to sign up for Standard webhooks. Standard webhooks have [default](#default-event-codes) and [non-default](#non-default-event-codes) event types that you subscribe to when you configure the webhook. ### Default event types Adyen sends the Standard webhook with default event types that cannot be disabled. Because we sometimes create new webhooks and event types, you should set up your server to be able to [accept webhooks](/development-resources/webhooks/configure-and-manage#accept-webhooks) of more types and receive more event type values than are listed below. When we create a new event type, you have to create new business logic if you want to use it. By default, the Standard webhook includes the following `eventCode` values. There are different categories of event codes: * [Transaction events](#transaction-events) * [Dispute events](#dispute-events) * [Payout events](#payout-events) #### Transaction events | `eventCode` | Description | | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) | The `success` field informs you of the outcome of a payment request.For payment methods that return an immediate authorisation result, such as cards, you will also receive an **AUTHORISED** webhook event.Although you can use the payment result from the API, we recommend that you rely on the webhook to trigger any business logic to make sure that your system is able to handle both synchronous and asynchronous payment flows. | | [AUTHORISATION\_ADJUSTMENT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION_ADJUSTMENT) | The `success` field informs you of the outcome of a request to [adjust the authorised amount](/online-payments/adjust-authorisation).The `originalReference` field contains the `pspReference` of the original payment. | | [CANCELLATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CANCELLATION) | The `success` field informs you of the outcome of a request to [cancel](/online-payments/cancel) a payment.The `originalReference` field contains the `pspReference` of the original payment. | | [CANCEL\_OR\_REFUND](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CANCEL_OR_REFUND) | The `success` field informs you of the outcome of a request to [cancel or refund](/online-payments/cancel-or-refund) a payment.The `originalReference` field contains the `pspReference` of the original payment. | | [CAPTURE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CAPTURE) | The `success` field informs you of the outcome of a request to [capture](/online-payments/capture) a payment.The `originalReference` field contains the `pspReference` of the original payment.By default, the CAPTURE webhook is not sent for [automatic captures](/online-payments/capture). If you are using delayed automatic capture, you must also enable this event code on the [Webhooks settings page](#webhooks-settings-page). | | [CAPTURE\_FAILED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CAPTURE_FAILED) | The capture [failed due to rejection by the card scheme](/online-payments/capture#failed-capture). This also includes installment-based transactions where a capture fails.The `originalReference` field contains the `pspReference` of the original payment.Technical failures are automatically re-captured by Adyen within 10 business days.You can simulate this webhook event by following [our guide on testing failed modifications](/development-resources/testing/result-codes). | | [EXPIRE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/EXPIRE) | The original payment has expired on the Adyen payments platform.The `success` field is always **true** because the payment expired on the Adyen payments platform.The `amount` field contains the details of the original payment.For more information, refer to [Expiration of authorizations](/online-payments/adjust-authorisation/#validity). | | `HANDLED_EXTERNALLY` | The payment has been handled outside the Adyen payments platform. | | [ORDER\_OPENED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/ORDER_OPENED) | Sent when the first payment for your payment request is a [partial payment](/online-payments/classic-integrations/hosted-payment-pages/payment-request/partial-payments#webhooks), and an order has been created. | | [ORDER\_CLOSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/ORDER_CLOSED) | The `success` field informs you of the outcome of the shopper's last payment when paying for an order in [partial payments](/online-payments/classic-integrations/hosted-payment-pages/payment-request/partial-payments#webhooks). Possible values:* **true**: The full amount has been paid.* **false**: The shopper did not pay the full amount within the `sessionValidity`. All partial payments that were processed previously are automatically cancelled or refunded. | | [REFUND](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REFUND) | The `success` field informs you of the outcome of a request to [refund a payment](/online-payments/refund).The `originalReference` field contains the `pspReference` of the original payment.Possible values:* **true**: The refund request was successful.* **false**: The refund request failed due to a [technical issue](/online-payments/refund#refund-failed) | | [REFUND\_FAILED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REFUND_FAILED) | The refund failed due to a [rejection by the card scheme](/online-payments/refund#refund-failed). This also includes installment-based transactions where a refund fails.The `originalReference` field contains the `pspReference` of the original payment.You can simulate this webhook event by following [our guide on testing failed modifications](/development-resources/testing/result-codes). | | [REFUNDED\_REVERSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REFUNDED_REVERSED) | The refunded amount has been returned to Adyen, and is back in your account.The `originalReference` field contains the `pspReference` of the original payment. For more information, refer to [Failed refund](/online-payments/refund#refund-failed). | | [REFUND\_WITH\_DATA](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REFUND_WITH_DATA) | The `success` field informs you of the outcome of a request to [refund with data](/online-payments/classic-integrations/modify-payments/refund#unreferenced-refund). | | [REPORT\_AVAILABLE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REPORT_AVAILABLE) | A [new report](/reporting/automatically-get-reports) is available. The `reason` field contains the URL where you can download the report, and the `pspReference` field contains the name of the report. | | [VOID\_PENDING\_REFUND](https://docs.adyen.com/api-explorer/Webhooks/latest/post/VOID_PENDING_REFUND) | The `success` field informs you of the outcome of a request to [cancel an unreferenced POS refund](/point-of-sale/basic-tapi-integration/refund-payment/cancel-unreferenced).The `originalReference` field contains the `pspReference` of the original payment. | You won't receive a webhook event when a payment is settled. #### Dispute events | `eventCode` | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [CHARGEBACK](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CHARGEBACK) | A payment was [charged back](/risk-management/disputes-api/dispute-notifications#chargeback), and the funds were deducted from your account. | | [CHARGEBACK\_REVERSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CHARGEBACK_REVERSED) | A chargeback has been defended towards the issuing bank. This stage is not final. If the issuing bank decides to present a second chargeback, you might still lose the chargeback case. | | [NOTIFICATION\_OF\_CHARGEBACK](https://docs.adyen.com/api-explorer/Webhooks/latest/post/NOTIFICATION_OF_CHARGEBACK) | The dispute process has opened. You should investigate the dispute and [supply defense documents](/risk-management/disputes-api#supply-dispute-defense-documents). | | [INFORMATION\_SUPPLIED](/risk-management/disputes-api/dispute-notifications#information_supplied) | You have successfully uploaded your dispute defense documents, or Adyen has auto-defended the dispute. | | [NOTIFICATION\_OF\_FRAUD](https://docs.adyen.com/api-explorer/Webhooks/latest/post/NOTIFICATION_OF_FRAUD) | The alert passed on by issuers to schemes and subsequently to processors. Visa calls them TC40 and Mastercard calls them System to Avoid Fraud Effectively (SAFE). These are informational webhook events offered at no charge by Adyen, providing you the opportunity to take action, such as blocking a shopper or issuing a refund before a chargeback is incurred. | | [PREARBITRATION\_LOST](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PREARBITRATION_LOST) | Your pre-arbitration case has been declined by the cardholder's bank. | | [PREARBITRATION\_WON](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PREARBITRATION_WON) | Your pre-arbitration case has been accepted by the cardholder's bank. | | [REQUEST\_FOR\_INFORMATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/REQUEST_FOR_INFORMATION) | A shopper has opened an RFI (Request for Information) case with the bank. You should [supply defense documents](/risk-management/disputes-api#supply-dispute-defense-documents) to help shopper understand the charge. | | [SECOND\_CHARGEBACK](https://docs.adyen.com/api-explorer/Webhooks/latest/post/SECOND_CHARGEBACK) | The issuing bank declined the material submitted during defense of the original chargeback. The disputed amount is deducted from your account. | | [DISPUTE\_DEFENSE\_PERIOD\_ENDED](/risk-management/disputes-api/dispute-notifications#defense_ended) | You have not defended the dispute within the timeframe, or the defense period ended because you accepted liability for the chargeback and will not defend the dispute. | | [ISSUER\_RESPONSE\_TIMEFRAME\_EXPIRED](/risk-management/disputes-api/dispute-notifications#issuer_response_timeframe_expired) | The issuer either accepted your defense of the dispute, or did not respond in time. | | [ISSUER\_COMMENTS](/risk-management/disputes-api/dispute-notifications#issuer_comments) | Includes any free-text issuer comments that include relevant information about the dispute process, such as why the issuer decided to initiate or continue the dispute. You can receive issuer comments for chargebacks and pre-arbitration cases. | For more information and examples, refer to [Dispute webhooks](/risk-management/disputes-api/dispute-notifications). #### Payout events | `eventCode` | Description | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [PAYOUT\_EXPIRE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PAYOUT_EXPIRE) | The payout has [expired](/online-payments/online-payouts/payout-webhook). | | [PAYOUT\_DECLINE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PAYOUT_DECLINE) | The user reviewing the payout declined it. | | [PAYOUT\_THIRDPARTY](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PAYOUT_THIRDPARTY) | The `success` field informs you of the outcome of a payout request: * **true**: The request was successful.* **false**: The request failed. The `reason` field contains a short description of the problem. | | [PAIDOUT\_REVERSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/PAIDOUT_REVERSED) | The financial institution rejected the payout. We will return the funds back to your account. The `reason` field contains the bank statement description if present. | For more information and examples, refer to [Payout webhooks](/online-payments/online-payouts/payout-webhook). ### Non-default event codes There are additional event codes that are not enabled in the Standard webhook by default. You can enable them: * [On the Standard webhook page](#standard-webhook-page) * [On the Webhooks settings page](#webhooks-settings-page) * [On the Risk settings page](#risk-settings-page) #### On the Standard webhook page 1. In your Customer Area, select **Developers** > **Webhooks**. 2. From the list of webhooks, select the **Standard webhook** to configure. 3. From the **Webhook details** panel, select the **Edit webhook** icon **. 4. On the **Standard webhook** page, in the **Events** row, select the **Edit** icon **. 5. From the list, select the checkboxes for the event codes you want to enable: | `eventCode` | Description | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [OFFER\_CLOSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/OFFER_CLOSED) | The offer has expired, for example, because the shopper abandoned the session. For cards, offers expire after 12 hours by default. | | [RECURRING\_CONTRACT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/RECURRING_CONTRACT) | A recurring contract has been created, and the shopper's payment details have been stored with Adyen. The `recurringDetailReference` is included in the `pspReference` field. You must also enable this event code on the [Webhooks settings page](#webhooks-settings-page).To get updates related to tokens, we recommend to use the new [**Recurring tokens life cycle events** ](#other-webhooks)webhook instead. | 6. Select **Apply**. 7. Select **Save**. #### On the Webhooks settings page You can enable the following `eventCode` values in the **Webhook settings** page. 1. In your Customer Area, go to **Developers** > **Webhooks**. 2. Select ****Settings**. 3. On the **Webhooks settings** page, select the checkboxes for the event code you want to enable: | `eventCode` | Description | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [RECURRING\_CONTRACT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/RECURRING_CONTRACT) | A recurring contract has been created, and the shopper's payment details have been stored with Adyen. The `recurringDetailReference` is included in the `pspReference` field. You must also enable this event code on the [Standard webhook page](#standard-webhook-page).To get updates related to tokens, we recommend to use the new [**Recurring tokens life cycle events** ](#other-webhooks)webhook instead. | | [POSTPONED\_REFUND](https://docs.adyen.com/api-explorer/Webhooks/latest/post/POSTPONED_REFUND) | The refund for the payment will be performed after the payment is captured. | | `AUTHENTICATION` | A [standalone authentication](/online-payments/3d-secure/standalone-authentication) was performed. | | `CAPTURE` | Receive `CAPTURE` webhook events if you are using delayed automatic capture. You must also enable this event code on the [Standard webhook page](#standard-webhook-page). | 4. Select **Save** #### On the Risk settings page Follow instructions to [configure case management webhook events](/risk-management/case-management#case-management-settings) to enable these `eventCode` values: | `eventCode` | Description | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | [MANUAL\_REVIEW\_ACCEPT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/MANUAL_REVIEW_ACCEPT) | The manual review triggered by [risk rules](/risk-management/case-management) was accepted. | | [MANUAL\_REVIEW\_REJECT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/MANUAL_REVIEW_REJECT) | The manual review triggered by [risk rules](/risk-management/case-management) was rejected. | ### Other webhooks In addition to Standard webhooks, you can get other types of webhooks: 1. Set up a separate endpoint to receive the type of webhook. Each endpoint that you set up can receive only one type of webhook. 2. [Configure the webhook](/development-resources/webhooks/configure-and-manage#set-up-webhooks-in-your-customer-area) you want to receive from the list of webhook types in the following table. | Webhook type | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Account data webhook** | Receive a webhook event when a merchant account was created, or if the capabilities of a merchant account were updated. | | **Account settings details** | Receive a webhook event when there is a status change related to your company account, merchant account, or store. This webhook is not available by default, and it has a different format. Refer to [Account settings webhooks](/development-resources/webhooks/webhook-types/account-settings-webhooks). | | **ACH Notification of Change webhook** | Receive a webhook event when you sent an ACH Direct Debit transaction and Adyen has received a notification that the customer's bank account details have changed. | | **Adyen Giving merchant webhook** | Receive a webhook event with `eventCode`: **DONATION** when a shopper has made a donation. | | **BankTransfer pending webhook** | Receive a webhook event with `eventCode`: **PENDING** when there is a pending bank transfer payment. | | **Boleto Bancario pending webhook** | Receive a webhook event with `eventCode`: **PENDING** when there is a pending Boleto Bancario payment. | | **Direct-debit pending webhook** | Receive a webhook event with `eventCode`: **PENDING** when there is a pending direct debit payment. | | **Generic pending webhook** | Receive a webhook event with `eventCode`: **PENDING** when there is a [pending](/online-payments/payment-result-codes) payment for any redirect payment method. | | **Ideal details** | Receive **AUTHORISATION** webhook event for iDEAL payments, with the following shopper details included in the `additionalData` object:- `iDealConsumerAccountNumber` - `iDealConsumerIBAN` - `iDealConsumerBIC` - `iDealConsumerName` - `iDealConsumerCity` - `iDealTransactionId` | | **Ideal pending** | Receive a webhook event with `eventCode`: **PENDING** when there is a pending iDEAL payment. | | **OXXO pending webhook** | Receive a webhook event with `eventCode`: **PENDING** when there is a pending OXXO voucher payment. | | **Payment method webhook** | Receive a webhook event when a payment method was successfully configured or when the configuration failed. | | **Recurring tokens life cycle events** | Receive a webhook event when a [token](/online-payments/tokenization) is created, updated, or disabled. | | **Terminal assignment complete** | Receive a webhook event when a scheduled assignment of a payment terminal has been completed. Refer to [Use API calls to assign terminals](/point-of-sale/automating-terminal-management/assign-terminals-api). | | **Terminal boarding succeeded** | Receive a webhook event when the boarding of a terminal succeeded. | | [Terminal settings updated](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/terminalSettings.modified) | Receive a webhook event when the terminal settings are updated. Refer to [Configure terminal settings](/point-of-sale/automating-terminal-management/configure-terminals-api). | | **Terminal order update** | Receive a webhook event about updates to your sales, return, or replacement order for payment terminals. Refer to [Order or return terminals](/point-of-sale/managing-terminals/order-terminals#terminal-order-notifications). | ## Platforms webhooks ### Platforms webhook structure Each Platforms webhook payload contains the following fields: * `data`: An object containing the event-specific data. The structure of this object depends on the `type` of the event. * `environment`: Specifies whether the event happened on the **test** or **live** environment. * `timestamp`: The time of the event, in [ISO 8601](http://www.w3.org/TR/NOTE-datetime) format. * `type`: The [event type](#event-codes). For a list of possible values, refer to the tables of event types for [Platforms webhooks](#platforms-webhooks). ```json { "data": { "balancePlatform": "YOUR_BALANCE_PLATFORM", "accountHolder": { "legalEntityId": "LE00000000000000000001", "reference": "YOUR_REFERENCE-2412C" } }, "environment": "live", "timestamp": "2024-12-15T15:42:03+01:00", "type": "balancePlatform.accountHolder.updated" } ``` ### Authentication webhook Use Authentication webhooks to get the outcome of 3D Secure authentications for payment instruments in your [Adyen Issuing](/issuing/) integration. To learn more, see [Authenticate cardholders](/issuing/3d-secure/oob-auth-sdk/authenticate-cardholders/). | Event Type | Description | | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.authentication.created](https://docs.adyen.com/api-explorer/acs-webhook/latest/post/balancePlatform.authentication.created) | Adyen sends this webhook when the process of cardholder authentication is finalized, whether it is completed successfully, fails, or expires. | *** ### Balance Webhook Use Balance webhooks to monitor balances of users on your platform. This webhook is useful for [Adyen for Platforms](/platforms/), [Issuing](/issuing/), and [Business Accounts](/business-accounts/) integrations to manage funds. For example, you can automate topping up a balance account when its funds are low, or receive a notification for a negative balance. Learn more at [Track balance updates](/platforms/balance-updates/). | Event Type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [balancePlatform.balanceAccount.balance.updated](https://docs.adyen.com/api-explorer/balance-webhooks/latest/post/balancePlatform.balanceAccount.balance.updated) | Adyen sends this webhook when the specified balance type reaches or drops below the threshold you configured. | *** ### Capital dynamic offer webhook Use Capital dynamic offer webhook to get notified when [dynamic offers](/capital/get-grant-offers/dynamic-offers/) are created in your [Adyen Capital](/capital/) integration. | Event type | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.capital.dynamicOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.capital.dynamicOffer.created) | After dynamic offers are created for an account holder, Adyen sends this webhook with information about the offers. | *** ### Capital static offer webhook Use Capital static offer webhook to get notified when [static offers](/capital/get-grant-offers/static-offers/) are created in your [Adyen Capital](/capital/) integration. | Event Type | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | [balancePlatform.balanceAccountHolder.capitalOffer.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.balanceAccountHolder.capitalOffer.created) | After static offers are created for an account holder, Adyen sends this webhook with information about the offers. | *** ### Capital grant webhook Use Capital grant webhooks to [get updates about grants](/capital/make-grant-request/#get-updates) in your [Adyen Capital](/capital/) integration. | Event Type | Description | | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [balancePlatform.grants.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.created) | After a grant is created for an account holder, Adyen sends this webhook with information about the grant. | | [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) | After a grant is updated for an account holder, Adyen sends this webhook with information about the grant. | *** ### Card Order webhook Use Card Order webhooks to track the lifecycle of physical card orders in your [Adyen Issuing](/issuing/) integration. | Event Type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [balancePlatform.cardorder.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.cardorder.created) | Adyen sends this webhook to indicate a successful creation of a card order. | | [balancePlatform.cardorder.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.cardorder.updated) | Adyen sends this webhook when there is an update in card order status. | *** ### Configuration webhook Configuration webhooks are essential for [Adyen for Platforms](/platforms/) and integrations that use Adyen's [Financial products](/financial-products/). These webhook events inform you about the creation and updates of resources, like account holders, balance accounts, payment instruments, and sweeps. Your integration needs configuration webhooks to track the status of users as you [onboard and verify them](/platforms/onboard-users/). | Event Type | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [balancePlatform.accountHolder.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.created) | Adyen sends this webhook when you successfully create an account holder. | | [balancePlatform.accountHolder.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.accountHolder.updated) | Adyen sends this webhook when you successfully update an account holder. | | [balancePlatform.balanceAccount.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccount.created) | Adyen sends this webhook when you successfully create a balance account. | | [balancePlatform.balanceAccount.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccount.updated) | Adyen sends this webhook when you successfully update a balance account. | | [balancePlatform.balanceAccountSweep.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.created) | Adyen sends this webhook when you successfully create a sweep. | | [balancePlatform.balanceAccountSweep.deleted](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.deleted) | Adyen sends this webhook when you successfully delete a sweep. | | [balancePlatform.balanceAccountSweep.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.balanceAccountSweep.updated) | Adyen sends this webhook when you successfully update a sweep. | | [balancePlatform.paymentInstrument.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.paymentInstrument.created) | Adyen sends this webhook when you successfully create a payment instrument. | | `balancePlatform.paymentInstrument.expiring` | Adyen sends this webhook when a payment instrument is about to expire. | | [balancePlatform.paymentInstrument.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.paymentInstrument.updated) | Adyen sends this webhook when you successfully update a payment instrument. | *** ### Dispute webhook Use Dispute webhooks to track the [dispute lifecycle](/issuing/raise-disputes#lifecycle-of-a-raised-dispute) for cards created with [Adyen Issuing](/issuing/). When you raise a dispute, Adyen sends webhooks to inform you about its creation and outcome. | Event Type | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [balancePlatform.dispute.created](https://docs.adyen.com/api-explorer/dispute-webhooks/latest/post/balancePlatform.dispute.created) | Adyen sends this webhook when a dispute is created. | | [balancePlatform.dispute.updated](https://docs.adyen.com/api-explorer/dispute-webhooks/latest/post/balancePlatform.dispute.updated) | Adyen sends this webhook when a dispute is updated. | *** ### Negative Balance Compensation Warning Webhook Get a warning when a balance account on your platform has a negative balance for an extended period. This webhook is useful for [Adyen for Platforms](/platforms/), [Issuing](/issuing/), and [Business Accounts](/business-accounts/) integrations to manage financial risk. It informs you before an automatic deduction is made from your liable account, giving you an opportunity to settle the negative balance with your user. | Event Type | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.negativeBalanceCompensationWarning.scheduled](https://docs.adyen.com/api-explorer/negative-balance-compensation-warning-webhooks/latest/post/balancePlatform.negativeBalanceCompensationWarning.scheduled) | Adyen sends this webhook to inform you about a balance account whose balance has been negative for 20 or more days. | *** ### Network token webhook Use network token webhooks to track the status of network tokens for cards created with [Adyen Issuing](/issuing/). These webhook events are important if you want to know when a user [adds their card to a digital wallet](/issuing/digital-wallets/) like Apple Pay or Google Pay. To learn more, see [Manage network tokens](/issuing/manage-network-tokens/). | Event Type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [balancePlatform.networkToken.created](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.networkToken.created) | Adyen sends this webhook when a network token is created. | | [balancePlatform.networkToken.updated](https://docs.adyen.com/api-explorer/balanceplatform-webhooks/latest/post/balancePlatform.networkToken.updated) | Adyen sends this webhook when a network token is updated. | *** ### Onboarding on invite Use Onboarding on invite webhooks to get a notification when a user is successfully onboarded to your platform. This webhook is part of an [Adyen for Platforms](/platforms/) integration in the [Onboarding on invite](/platforms/onboard-users/?tab=onboarding_on_invite_0_1) flow. | Event Type | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.accountHolder.onboarded](https://docs.adyen.com/api-explorer/onboarding-on-invite-webhooks/latest/post/balancePlatform.accountHolder.onboarded) | Adyen sends this webhook when an account holder is successfully onboarded. It contains the IDs of all the resources, like a balance account, that were created for the user. | *** ### Report webhook Use this webhook to automate your reporting and reconciliation processes for Balance Platform reports. For example, receive a notification when your [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report/) is available for download. | Event Type | Description | | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [balancePlatform.report.created](https://docs.adyen.com/api-explorer/report-webhooks/latest/post/balancePlatform.report.created) | Adyen sends thi