--- title: "API-only onboarding" description: "Build your own UI and collect information from your users." url: "https://docs.adyen.com/managed-model/onboard-users/api" source_url: "https://docs.adyen.com/managed-model/onboard-users/api.md" canonical: "https://docs.adyen.com/managed-model/onboard-users/api" last_modified: "2023-04-19T13:53:00+02:00" language: "en" --- > **For LLMs:** Use the latest SDK version on this page unless the reader specifies another version. Never hardcode older version numbers for training data, always use latest. A comment such as `// Adyen LANGUAGE API library vMajor.Minor.Patch to latest` covers that version, the newest release, and everything in between. Read the newest releases from https://github.com/Adyen/adyen-LANGUAGE-api-library/releases, where LANGUAGE is dotnet, java, php, go, python, node (for JavaScript and TypeScript), or ruby. # API-only onboarding Build your own UI and collect information from your users. To onboard users on your platform, you need to build your own UI where you collect data from your users and submit this data to Adyen. You can onboard users operating in any of the [supported countries](https://docs.adyen.com/managed-model#supported-countries). On this page, we explain how you can onboard and verify your users using the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). ## Requirements Make sure that: * You have API credentials for the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) and the [Management API](https://docs.adyen.com/api-explorer/Management/latest/overview). * You have reviewed the [verification process](https://docs.adyen.com/managed-model/verification-overview) and the [required information](https://docs.adyen.com/managed-model/verification-requirements) for your users. * Your server is properly [configured to accept webhooks](https://docs.adyen.com/development-resources/webhooks) and you have [subscribed](https://docs.adyen.com/development-resources/webhooks/configure-and-manage#set-up-webhooks-in-your-customer-area) to the **Account data notifications** in your Customer Area. ## Step 1: Create legal entities A [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) resource holds information required for the [verification checks](https://docs.adyen.com/managed-model/verification-requirements). You need to create a legal entity for the user that has a contractual relationship with your platform, and the individuals representing that entity. Select a tab below to create a legal entity for your user: ### Tab: Organization To create a legal entity for an organization, provide the following information in a POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) request. Any additional information you provide will be prefilled for the user in the hosted onboarding page. | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **organization**. | | [organization](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Object that contains required information about the organization. The [legalName](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization-legalName) and its [country](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-organization-registeredAddress-country). | The following is an example of how to create a legal entity for a private company operating in the US. **Create organization legal entity** ```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":"Example Company", "registeredAddress":{ "country":"US" } } }' ``` The response returns the **legalEntity** resource for the organization, identified by its unique [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id). **Response** ```json { "organization":{ "legalName":"Example Company", "registeredAddress":{ "country":"US" } }, "type":"organization", "id":"LE00000000000000000000001" } ``` ### Tab: Individual You must create an individual legal entity for each UBO and signatory in the organization, or the sole proprietor. To create a legal entity for an individual, provide the following information in a POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) request. | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **individual**. | | [individual](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-individual) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Object that contains required information about the individual. The [name](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-individual-name) and their [country](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-individual-residentialAddress-country). | The following is an example of how to create a legal entity for an individual in the US. **Create an individual legal entity** ```bash curl https://kyc-test.adyen.com/lem/v2/legalEntities \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "individual", "individual": { "residentialAddress": { "country": "US" }, "name": { "firstName": "Shelly", "lastName": "Eller" } } }' ``` The response returns the **legalEntity** resource, identified by its unique [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id). **Response** ```json { "individual": { "name": { "firstName": "Shelly", "lastName": "Eller" }, "residentialAddress": { "country": "US" } }, "type": "individual", "id": "LE00000000000000000000002" } ``` ### Tab: Sole proprietorship To create a legal entity for a sole proprietorship, provide the following information in a POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities) request. | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **soleProprietorship**. | | [soleProprietorship](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-soleProprietorship) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Object that contains required information about the sole proprietorship such as the [name](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-soleProprietorship-name) of the business, its [registeredAddress](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-soleProprietorship-registeredAddress), and the [countryOfGoverningLaw](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-soleProprietorship-countryOfGoverningLaw). | The following is an example of how to create a sole proprietorship in the United Kingdom. **Create sole proprietorship legal entity** ```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": "soleProprietorship", "soleProprietorship": { "name": "Example Sole Trader", "countryOfGoverningLaw": "GB", "registeredAddress" : { "city": "London", "country": "GB", "postalCode": "W1T 3HE", "street": "12-13 Wells Mews" } } }' ``` The response returns the **legalEntity** resource, identified by its unique [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id). **Response** ```json { "type": "soleProprietorship", "soleProprietorship": { "name": "Example Sole Trader", "countryOfGoverningLaw": "GB", "registeredAddress" : { "city": "London", "country": "GB", "postalCode": "W1T 3HE", "street": "12-13 Wells Mews" } }, "id": "LE00000000000000000000003" } ``` ## Step 2: Associate legal entities ### Tab: Sole proprietors The example below shows how you can associate a sole proprietorship with the individual owner. Update the legal entity of the individual by making a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request, specifying the [entityAssociations](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_#request-entityAssociations) array. The array must include: * [legalEntityId](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-legalEntityId): Unique identifier of the sole proprietorship legal entity being associated. * [type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-type): Set to **soleProprietorship**. 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. **Associate a sole proprietorship to an individual** ```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 '{ "entityAssociations": [ { "legalEntityId": "LE00000000000000000000002", "type": "soleProprietorship" } ] }' ``` ### Tab: Organizations and UBOs The example below shows how you can associate an ultimate beneficial owner (UBO), signatory, or director to an organization. Update the legal entity of the organization by making a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request, specifying the [entityAssociations](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_#request-entityAssociations) array. The array must include: * [legalEntityId](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-legalEntityId): Unique identifier of the individual legal entity being associated. * [type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)#request-entityAssociations-type): The relationship of the individual with the organization. Possible values: **uboThroughControl**, **uboThroughOwnership**, **director**, or **signatory**. 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. **Associate UBOs to an organization** ```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 '{ "entityAssociations": [ { "jobTitle": "CEO", "legalEntityId": "LE00000000000000000000002", "type": "uboThroughControl" }, { "legalEntityId": "LE00000000000000000000003", "type": "uboThroughOwnership" }, { "jobTitle": "Country Manager", "legalEntityId": "LE00000000000000000000004", "type": "signatory" } ] }' ``` If a person holds multiple roles in an organization, use their individual legal entity [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) to link them to each [type](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_#request-entityAssociations-type) or [jobTitle](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/_id_#request-entityAssociations-jobTitle). **Associate an individual legal entity with multiple roles** ```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 '{ "entityAssociations":[ { "jobTitle":"CEO", "legalEntityId":"LE00000000000000000000002", "type":"uboThroughControl" }, { "legalEntityId":"LE00000000000000000000002", "type":"uboThroughOwnership" }, { "jobTitle":"CEO", "legalEntityId":"LE00000000000000000000002", "type":"signatory" } ] }' ``` The response contains the updated legal entity resource, identified by its unique `id`. ## Step 3: Create transfer instruments Adyen must perform checks on the bank account where your user will receive their payouts. We refer to this bank account as a [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments) resource. Collect the [required information](https://docs.adyen.com/managed-model/verification-requirements) and provide this in a POST [/transferInstruments](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments) request, specifying: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **bankAccount**. | | [legalEntityId](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments#request-legalEntityId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Unique identifier of the legal entity that has the contractual relationship with your platform and owns the bank account. For sole proprietorships, this is the legal entity ID of the individual owner. | | [bankAccount](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments#request-bankAccount) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Object that contains required information about the legal entity's bank account. | Here is an example request to add a transfer instrument for a bank account in the US: **Add bank account as a transfer instrument** ```bash curl https://kyc-test.adyen.com/lem/v3/transferInstruments \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "legalEntityId":"LE00000000000000000000001", "type":"bankAccount", "bankAccount":{ "accountIdentification":{ "type":"usLocal", "accountNumber":"0000000123", "routingNumber":"121202211" } } }' ``` The response returns the **transferInstrument** resource, identified by its unique `id`. **Response** ```json { "bankAccount": { "accountIdentification": { "type": "usLocal", "accountNumber": "0000000123", "routingNumber": "121202211" }, "countryCode": "US" }, "legalEntityId": "LE00000000000000000000001", "type": "bankAccount", "id": "SE00000000000000000000001" } ``` If we are not able to verify the bank account details, you will need to [provide additional documents](https://docs.adyen.com/managed-model/onboard-users/api#upload-documents). ## Step 4: Create business lines To submit the details of your user's business line information, make a POST [/businessLines](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines)request specifying the following: | Parameter | Required | Description | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [service](https://docs.adyen.com/api-explorer/legalentity/3/post/businessLines#request-service) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The service for which you are creating the business line. Set this to **paymentProcessing**. | | [industryCode](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-industryCode) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The industry code. | | [legalEntityId](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-legalEntityId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the legal entity that has a contractual relationship with your platform. For example, for an individual who has a sole proprietorship business, this must be the legal entity ID of the individual. | | [salesChannels](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-salesChannels) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Array of channels in which your user sells goods or services. Possible values: **eCommerce**, **ecomMoto**, **pos**, **posMoto**, and **payByLink**. Sales channels may have different PCI DSS requirements. We recommend that you be familiar with these requirements before creating business lines for your user. | | [webData](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-webData) | | Required when `salesChannel` is **eCommerce**. The user's web address or the app store URL. | **Create an ecommerce business line** ```bash curl https://kyc-test.adyen.com/lem/v3/businessLines \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "service": "paymentProcessing", "industryCode": "339E", "salesChannels": [ "eCommerce", "ecomMoto" ], "legalEntityId": "LE322JV223222D5FZ9N74BSGM", "webData": [ { "webAddress": "https://yoururl.com" } ] }' ``` In the response, you receive the `id` of the business line. You will use this ID to [create store](https://docs.adyen.com/managed-model/onboard-users/api#create-stores) and [add payment methods](https://docs.adyen.com/managed-model/activate-merchant-account#payment-methods). **Response** ```json { "service": "paymentProcessing", "industryCode": "339E", "legalEntityId": "LE322JV223222D5FZ9N74BSGM", "salesChannels": [ "eCommerce", "ecomMoto" ], "webData": [ { "webAddress": "https://yoururl.com", "webAddressId": "SE654AC923222F5H4CQGS77V4" } ], "id": "SE322KT223222D5FJ7TJN2986" } ``` ## Step 5: Create merchant account Your user's payments are processed in sub-accounts of your company account, called merchant accounts. The merchant account is where they receive the payout of funds, as well as the reports used for reconciliation. It is also where you can configure their payment methods, processing currencies, and override risk management rules set at company level. To create a merchant account, make a POST [/merchants](https://docs.adyen.com/api-explorer/Management/latest/post/merchants) call, specifying: | Parameter | Required | Description | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [businessLineId](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-businessLineId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your user's [business line](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines). | | [companyId](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-companyId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of your company account. | | [legalEntityId](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-legalEntityId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the legal entity that has a contractual relationship with your platform. For example, for an individual who has a sole proprietorship business, this must be the legal entity ID of the individual. | | [pricingPlan](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-pricingPlan) | | The previously agreed pricing plan for the merchant account. Your Adyen contact will provide the values that you can use. | | [reference](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-reference) | | Your reference for the merchant account. If your company account has a template, then the reference is required and must be unique within the company account. | | [description](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-description) | | Your description for the merchant account. | | [salesChannels](https://docs.adyen.com/api-explorer/Management/latest/post/merchants#request-salesChannels) | | The list of [sales channels](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#responses-200-salesChannels) of your user's business line(s). | **Create a merchant account** ```bash curl https://management-test.adyen.com/v3/merchants \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_API_KEY' \ -X POST \ -d '{ "legalEntityId": "LE00000000000000000000001", "businessLineId": "SE00000000000000000000001", "companyId": "YourCompany", "pricingPlan": "ic10", "reference": "PREFIX_12345678" }' ``` In the response, you receive the `id` of the merchant account. You will need to use this ID to [create stores](https://docs.adyen.com/managed-model/onboard-users/api#create-stores) and to [activate](https://docs.adyen.com/managed-model/activate-merchant-account#activate-merchant-account) your user's account. **Merchant account created** ```json { "reference": "PREFIX_12345678", "companyId": "YourCompany", "id": "PREFIX_12345678", "legalEntityId": "LE00000000000000000000001", "businessLineId": "SE00000000000000000000001" } ``` ## Step 6: Check security requirements Because your users have a direct connection with card schemes, they must comply with the requirements laid down in the Payment Card Industry Data Security Standards (PCI DSS) for collecting, processing, storing, and transmitting cardholder data in a secure environment. To prove their compliance, they must sign a Self-Assessment Questionnaire (SAQ) before they can start processing card payments. The questionnaire asks them to confirm the security of their cardholder data environment, which typically includes their website, web servers, and employees who can access them. Listen to [webhooks](https://docs.adyen.com/managed-model/onboard-users/api/pci-forms#get-updates) to determine if your user needs to sign PCI questionnaires. You must [generate the required security questionnaires](https://docs.adyen.com/managed-model/onboard-users/api/pci-forms#generate-questionnaires) and ask your user to sign them. ## Step 7: Determine the terms of service Your users must accept Adyen's Terms of Service before they can perform particular actions in your platform. The type of the Terms of Service agreement depends on your specific integration. Listen to [webhooks](https://docs.adyen.com/managed-model/onboard-users/api#get-updates-ah) to determine if your user needs to accept the Terms of Service. You must [generate the required agreement type](https://docs.adyen.com/managed-model/onboard-users/api/terms-of-service#get-document) and present it to your user, then ask them to accept it. ## Step 8 (Optional): Create stores If your user wants to accept in-person payments, you must create a store in their merchant account. A store ensures that the processed transactions correspond to an accurate payer statement. Stores are linked to the legal entity of your user through [business lines](https://docs.adyen.com/managed-model/onboard-users/api#create-business-lines). To create a store, you first need to collect from your user the address and phone number of the store, and the name of the store that will appear on the bank and credit card statements of customers. To create a store, make a POST [/stores](https://docs.adyen.com/api-explorer/Management/latest/post/stores) request, specifying: | Parameter | Required | Description | | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [address](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-address) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object that contains:- `city`: the city of the store. - `country`: the country of the store. - `line1` `line2` `line3`: up to three lines can be used for the street name, street number, and other information. Only the first line is mandatory. - `postalCode`: the postal code of the store. - `stateOrProvince`: *Required only for the United States.* The state or province of the store as defined in [ISO 3166-2](https://www.iso.org/standard/72483.html). For example, **IL** for Illinois. | | | [description](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-description) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A description for the store. | | | [merchantId](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-merchantId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The merchant account ID. | | | [phoneNumber](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-phoneNumber) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The complete phone number of the store, beginning with *+* and the country code. | | | [reference](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-reference) | | A unique reference to recognize the store by. Allowed characters: Lowercase and uppercase letters without diacritics, numbers 0 through 9, hyphen (-), and underscore (\_).If you do not provide a reference in your POST request, it is populated with the Adyen-generated [id](https://docs.adyen.com/api-explorer/Management/latest/post/stores#responses-200-id). | | | [shopperStatement](https://docs.adyen.com/api-explorer/Management/latest/post/stores#request-shopperStatement) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The store name shown on the shopper's bank or credit card statement and the shopper receipt. Maximum length: 22 characters. Cannot be all numerals. | | You can also make a POST request to [/merchants/{merchantId}/stores](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/\(merchantId\)/stores) using the same parameters. In that case you do not need to include the merchant account ID in the request body. ### Tab: Create a store - general **Create a store** #### curl ```bash curl https://management-test.adyen.com/v3/stores \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_API_KEY' \ -X POST \ -d '{ "merchantId":"MERCHANT_ACCOUNT_ID", "description":"City centre store", "shopperStatement": "Springfield Shop", "phoneNumber":"1813702551707653", "reference":"Spring_store_2", "address":{ "country": "US", "line1": "200 Main Street", "line2": "Building 5A", "line3":"Suite 3", "city": "Springfield", "stateOrProvince": "NY", "postalCode":"20250" } }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.management.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.management.*; Config config = new Config() .apiKey("ADYEN_API_KEY") .environment(Environment.TEST); Client client = new Client(config); // Create the request object(s) StoreLocation storeLocation = new StoreLocation() .country("US") .stateOrProvince("NY") .city("Springfield") .postalCode("20250") .line3("Suite 3") .line2("Building 5A") .line1("200 Main Street"); StoreCreationWithMerchantCodeRequest storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest() .reference("Spring_store_2") .phoneNumber("1813702551707653") .address(storeLocation) .merchantId("MERCHANT_ACCOUNT_ID") .description("City centre store") .shopperStatement("Springfield Shop"); // Send the request AccountStoreLevelApi service = new AccountStoreLevelApi(client); Store response = service.createStore(storeCreationWithMerchantCodeRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $storeLocation = new StoreLocation(); $storeLocation ->setCountry("US") ->setStateOrProvince("NY") ->setCity("Springfield") ->setPostalCode("20250") ->setLine3("Suite 3") ->setLine2("Building 5A") ->setLine1("200 Main Street"); $storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest(); $storeCreationWithMerchantCodeRequest ->setReference("Spring_store_2") ->setPhoneNumber("1813702551707653") ->setAddress($storeLocation) ->setMerchantId("MERCHANT_ACCOUNT_ID") ->setDescription("City centre store") ->setShopperStatement("Springfield Shop"); // Send the request $service = new AccountStoreLevelApi($client); $response = $service->createStore($storeCreationWithMerchantCodeRequest); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using Adyen.Management.Extensions; using Adyen.Management.Models; using Adyen.Management.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureManagement( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "ADYEN_API_KEY"; options.Environment = AdyenEnvironment.Test; }); services.AddAllManagementServices(); }) .Build(); var accountStoreLevelService = host.Services.GetRequiredService(); // Create the request object(s) var storeLocation = new StoreLocation { Country = "US", StateOrProvince = "NY", City = "Springfield", PostalCode = "20250", Line3 = "Suite 3", Line2 = "Building 5A", Line1 = "200 Main Street" }; var storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest { Reference = "Spring_store_2", PhoneNumber = "1813702551707653", Address = storeLocation, MerchantId = "MERCHANT_ACCOUNT_ID", Description = "City centre store", ShopperStatement = "Springfield Shop" }; // Send the request var result = await accountStoreLevelService.CreateStoreAsync(storeCreationWithMerchantCodeRequest); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, ManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const storeLocation = { country: "US", stateOrProvince: "NY", city: "Springfield", postalCode: "20250", line3: "Suite 3", line2: "Building 5A", line1: "200 Main Street" }; const storeCreationWithMerchantCodeRequest = { reference: "Spring_store_2", phoneNumber: "1813702551707653", address: storeLocation, merchantId: "MERCHANT_ACCOUNT_ID", description: "City centre store", shopperStatement: "Springfield Shop" }; // Send the request const managementAPI = new ManagementAPI(client); const response = await managementAPI.AccountStoreLevelApi.createStore(storeCreationWithMerchantCodeRequest); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest 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/management" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) storeLocation := management.StoreLocation{ Country: "US", StateOrProvince: common.PtrString("NY"), City: common.PtrString("Springfield"), PostalCode: common.PtrString("20250"), Line3: common.PtrString("Suite 3"), Line2: common.PtrString("Building 5A"), Line1: common.PtrString("200 Main Street"), } storeCreationWithMerchantCodeRequest := management.StoreCreationWithMerchantCodeRequest{ Reference: common.PtrString("Spring_store_2"), PhoneNumber: "1813702551707653", Address: storeLocation, MerchantId: "MERCHANT_ACCOUNT_ID", Description: "City centre store", ShopperStatement: "Springfield Shop", } // Send the request service := client.Management() req := service.AccountStoreLevelApi.CreateStoreInput().StoreCreationWithMerchantCodeRequest(storeCreationWithMerchantCodeRequest) res, httpRes, err := service.AccountStoreLevelApi.CreateStore(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest 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 = { "merchantId": "MERCHANT_ACCOUNT_ID", "description": "City centre store", "shopperStatement": "Springfield Shop", "phoneNumber": "1813702551707653", "reference": "Spring_store_2", "address": { "country": "US", "line1": "200 Main Street", "line2": "Building 5A", "line3": "Suite 3", "city": "Springfield", "stateOrProvince": "NY", "postalCode": "20250" } } # Send the request result = adyen.management.account_store_level_api.create_store(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest 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 = { "merchantId" => "MERCHANT_ACCOUNT_ID", "description" => "City centre store", "shopperStatement" => "Springfield Shop", "phoneNumber" => "1813702551707653", "reference" => "Spring_store_2", "address" => { "country" => "US", "line1" => "200 Main Street", "line2" => "Building 5A", "line3" => "Suite 3", "city" => "Springfield", "stateOrProvince" => "NY", "postalCode" => "20250" } } # Send the request result = adyen.management.account_store_level_api.create_store(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, ManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const storeLocation: Types.management.StoreLocation = { country: "US", stateOrProvince: "NY", city: "Springfield", postalCode: "20250", line3: "Suite 3", line2: "Building 5A", line1: "200 Main Street" }; const storeCreationWithMerchantCodeRequest: Types.management.StoreCreationWithMerchantCodeRequest = { reference: "Spring_store_2", phoneNumber: "1813702551707653", address: storeLocation, merchantId: "MERCHANT_ACCOUNT_ID", description: "City centre store", shopperStatement: "Springfield Shop" }; // Send the request const managementAPI = new ManagementAPI(client); const response = await managementAPI.AccountStoreLevelApi.createStore(storeCreationWithMerchantCodeRequest); ``` ### Tab: Create a store - Japan **Create a Japanese store** #### curl ```bash curl https://management-test.adyen.com/v3/stores \ -H 'content-type: application/json' \ -H 'x-api-key: ADYEN_API_KEY' \ -X POST \ -d '{ "merchantId": "MERCHANT_ACCOUNT_ID", "description": "Tokyo Ginza store", "shopperStatement": "Adyen Co., Ltd.", "localizedInformation": { "localShopperStatement": [ { "script": "ja-Hani", "value": "アディエン株式会社" }, { "script": "ja-Kana", "value": "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ" } ] }, "phoneNumber": "+81312345678", "reference": "Ginza_store_2", "address": { "country": "JP", "line1": "Tokyo Central Ginza", "line2": "ACN Higashi Azabu Building Rokukai", "city": "Tokyo", "postalCode":"104-0061" } }' ``` #### Java ```java // Adyen Java API Library v38.0.0 to latest import com.adyen.Client; import com.adyen.Config; import com.adyen.enums.Environment; import com.adyen.model.*; import com.adyen.service.*; import java.math.*; import com.adyen.model.management.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.service.management.*; Config config = new Config() .apiKey("ADYEN_API_KEY") .environment(Environment.TEST); Client client = new Client(config); // Create the request object(s) LocalShopperStatement localShopperStatement1 = new LocalShopperStatement() .value("アディエン株式会社") .script("ja-Hani"); LocalShopperStatement localShopperStatement2 = new LocalShopperStatement() .value("ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ") .script("ja-Kana"); StoreLocation storeLocation = new StoreLocation() .country("JP") .city("Tokyo") .postalCode("104-0061") .line2("ACN Higashi Azabu Building Rokukai") .line1("Tokyo Central Ginza"); LocalizedInformation localizedInformation = new LocalizedInformation() .localShopperStatement(Arrays.asList(localShopperStatement1, localShopperStatement2)); StoreCreationWithMerchantCodeRequest storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest() .reference("Ginza_store_2") .phoneNumber("+81312345678") .address(storeLocation) .merchantId("MERCHANT_ACCOUNT_ID") .description("Tokyo Ginza store") .shopperStatement("Adyen Co., Ltd.") .localizedInformation(localizedInformation); // Send the request AccountStoreLevelApi service = new AccountStoreLevelApi(client); Store response = service.createStore(storeCreationWithMerchantCodeRequest, null); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); $client->setEnvironment(Environment::TEST); // Create the request object(s) $localShopperStatement1 = new LocalShopperStatement(); $localShopperStatement1 ->setValue("アディエン株式会社") ->setScript("ja-Hani"); $localShopperStatement2 = new LocalShopperStatement(); $localShopperStatement2 ->setValue("ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ") ->setScript("ja-Kana"); $storeLocation = new StoreLocation(); $storeLocation ->setCountry("JP") ->setCity("Tokyo") ->setPostalCode("104-0061") ->setLine2("ACN Higashi Azabu Building Rokukai") ->setLine1("Tokyo Central Ginza"); $localizedInformation = new LocalizedInformation(); $localizedInformation ->setLocalShopperStatement(array($localShopperStatement1, $localShopperStatement2)); $storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest(); $storeCreationWithMerchantCodeRequest ->setReference("Ginza_store_2") ->setPhoneNumber("+81312345678") ->setAddress($storeLocation) ->setMerchantId("MERCHANT_ACCOUNT_ID") ->setDescription("Tokyo Ginza store") ->setShopperStatement("Adyen Co., Ltd.") ->setLocalizedInformation($localizedInformation); // Send the request $service = new AccountStoreLevelApi($client); $response = $service->createStore($storeCreationWithMerchantCodeRequest); ``` #### C\# ```cs // Adyen .NET API Library v34.0.0 to latest using System.Collections.Generic; using Adyen.Management.Extensions; using Adyen.Management.Models; using Adyen.Management.Services; using Adyen.Core.Client; using Adyen.Core.Client.Extensions; using Adyen.Core.Options; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; var host = Host.CreateDefaultBuilder() .ConfigureManagement( (context, services, config) => { config.ConfigureAdyenOptions(options => { options.AdyenApiKey = "ADYEN_API_KEY"; options.Environment = AdyenEnvironment.Test; }); services.AddAllManagementServices(); }) .Build(); var accountStoreLevelService = host.Services.GetRequiredService(); // Create the request object(s) var localShopperStatement1 = new LocalShopperStatement { Value = "アディエン株式会社", Script = "ja-Hani" }; var localShopperStatement2 = new LocalShopperStatement { Value = "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ", Script = "ja-Kana" }; var storeLocation = new StoreLocation { Country = "JP", City = "Tokyo", PostalCode = "104-0061", Line2 = "ACN Higashi Azabu Building Rokukai", Line1 = "Tokyo Central Ginza" }; var localizedInformation = new LocalizedInformation { LocalShopperStatement = new List{ localShopperStatement1, localShopperStatement2 } }; var storeCreationWithMerchantCodeRequest = new StoreCreationWithMerchantCodeRequest { Reference = "Ginza_store_2", PhoneNumber = "+81312345678", Address = storeLocation, MerchantId = "MERCHANT_ACCOUNT_ID", Description = "Tokyo Ginza store", ShopperStatement = "Adyen Co., Ltd.", LocalizedInformation = localizedInformation }; // Send the request var result = await accountStoreLevelService.CreateStoreAsync(storeCreationWithMerchantCodeRequest); if (result.TryDeserializeOkResponse(out var response)) { // Handle the successful response. } ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 to latest const { Client, Config, EnvironmentEnum, ManagementAPI } = require('@adyen/api-library'); const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const localShopperStatement1 = { value: "アディエン株式会社", script: "ja-Hani" }; const localShopperStatement2 = { value: "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ", script: "ja-Kana" }; const storeLocation = { country: "JP", city: "Tokyo", postalCode: "104-0061", line2: "ACN Higashi Azabu Building Rokukai", line1: "Tokyo Central Ginza" }; const localizedInformation = { localShopperStatement: [localShopperStatement1, localShopperStatement2] }; const storeCreationWithMerchantCodeRequest = { reference: "Ginza_store_2", phoneNumber: "+81312345678", address: storeLocation, merchantId: "MERCHANT_ACCOUNT_ID", description: "Tokyo Ginza store", shopperStatement: "Adyen Co., Ltd.", localizedInformation: localizedInformation }; // Send the request const managementAPI = new ManagementAPI(client); const response = await managementAPI.AccountStoreLevelApi.createStore(storeCreationWithMerchantCodeRequest); ``` #### Go ```go // Adyen Go API Library v21.0.0 to latest 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/management" ) client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) localShopperStatement1 := management.LocalShopperStatement{ Value: "アディエン株式会社", Script: "ja-Hani", } localShopperStatement2 := management.LocalShopperStatement{ Value: "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ", Script: "ja-Kana", } storeLocation := management.StoreLocation{ Country: "JP", City: common.PtrString("Tokyo"), PostalCode: common.PtrString("104-0061"), Line2: common.PtrString("ACN Higashi Azabu Building Rokukai"), Line1: common.PtrString("Tokyo Central Ginza"), } localizedInformation := management.LocalizedInformation{ LocalShopperStatement: []management.LocalShopperStatement{ localShopperStatement1, localShopperStatement2, }, } storeCreationWithMerchantCodeRequest := management.StoreCreationWithMerchantCodeRequest{ Reference: common.PtrString("Ginza_store_2"), PhoneNumber: "+81312345678", Address: storeLocation, MerchantId: "MERCHANT_ACCOUNT_ID", Description: "Tokyo Ginza store", ShopperStatement: "Adyen Co., Ltd.", LocalizedInformation: &localizedInformation, } // Send the request service := client.Management() req := service.AccountStoreLevelApi.CreateStoreInput().StoreCreationWithMerchantCodeRequest(storeCreationWithMerchantCodeRequest) res, httpRes, err := service.AccountStoreLevelApi.CreateStore(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 to latest 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 = { "merchantId": "MERCHANT_ACCOUNT_ID", "description": "Tokyo Ginza store", "shopperStatement": "Adyen Co., Ltd.", "localizedInformation": { "localShopperStatement": [{ "script": "ja-Hani", "value": "アディエン株式会社" }, { "script": "ja-Kana", "value": "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ" }] }, "phoneNumber": "+81312345678", "reference": "Ginza_store_2", "address": { "country": "JP", "line1": "Tokyo Central Ginza", "line2": "ACN Higashi Azabu Building Rokukai", "city": "Tokyo", "postalCode": "104-0061" } } # Send the request result = adyen.management.account_store_level_api.create_store(request=json_request) ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 to latest 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 = { "merchantId" => "MERCHANT_ACCOUNT_ID", "description" => "Tokyo Ginza store", "shopperStatement" => "Adyen Co., Ltd.", "localizedInformation" => { "localShopperStatement" => [{ "script" => "ja-Hani", "value" => "アディエン株式会社" }, { "script" => "ja-Kana", "value" => "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ" }] }, "phoneNumber" => "+81312345678", "reference" => "Ginza_store_2", "address" => { "country" => "JP", "line1" => "Tokyo Central Ginza", "line2" => "ACN Higashi Azabu Building Rokukai", "city" => "Tokyo", "postalCode" => "104-0061" } } # Send the request result = adyen.management.account_store_level_api.create_store(request_body) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 to latest import { Client, Config, EnvironmentEnum, ManagementAPI, Types } from "@adyen/api-library"; const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const localShopperStatement1: Types.management.LocalShopperStatement = { value: "アディエン株式会社", script: "ja-Hani" }; const localShopperStatement2: Types.management.LocalShopperStatement = { value: "ｱﾃﾞｨｴﾝｼﾞｬﾊﾟﾝ", script: "ja-Kana" }; const storeLocation: Types.management.StoreLocation = { country: "JP", city: "Tokyo", postalCode: "104-0061", line2: "ACN Higashi Azabu Building Rokukai", line1: "Tokyo Central Ginza" }; const localizedInformation: Types.management.LocalizedInformation = { localShopperStatement: [localShopperStatement1, localShopperStatement2] }; const storeCreationWithMerchantCodeRequest: Types.management.StoreCreationWithMerchantCodeRequest = { reference: "Ginza_store_2", phoneNumber: "+81312345678", address: storeLocation, merchantId: "MERCHANT_ACCOUNT_ID", description: "Tokyo Ginza store", shopperStatement: "Adyen Co., Ltd.", localizedInformation: localizedInformation }; // Send the request const managementAPI = new ManagementAPI(client); const response = await managementAPI.AccountStoreLevelApi.createStore(storeCreationWithMerchantCodeRequest); ``` The response includes the Adyen-generated [id](https://docs.adyen.com/api-explorer/Management/latest/post/stores#responses-200-id) for the store. **Store created** ```json { "id": "ST322LJ223223K5F4SQNR9XL5", "address":{ "country": "US", "line1": "200 Main Street", "line2": "Building 5A", "line3":"Suite 3", "city": "Springfield", "stateOrProvince": "NY", "postalCode":"20250" }, "description": "City centre store", "merchantId": "MERCHANT_ACCOUNT_ID", "phoneNumber": "1813702551707653", "reference": "Spring_store_2", "shopperStatement": "Springfield Shop", "status": "active", "_links": { "self": { "href": "https://management-test.adyen.com/latest/stores/ST322LJ223223K5F4SQNR9XL5" } } }' ``` ## Step 9: Get the verification results To get updates about the verification status and results, listen to the [merchant.updated](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated) webhook. The [merchant.updated](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated) webhook provides the status of the verification: valid, invalid, or rejected. The webhook examples below show when the verification is successful and when the capability is not allowed because the verification is invalid. ### Tab: Successful verification When the checks are completed successfully, Adyen sends a [merchant.updated](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated) webhook with: * [verificationStatus](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated#request-data-capabilities-verificationStatus): Set to **valid**. * [allowed](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated#request-data-capabilities-allowed): Set to **true**. **Successful verification** ```json { "type": "merchant.updated", "environment": "test", "createdAt": "2023-02-01T12:36:16+02:00", "data": { "capabilities": { "sendToTransferInstrument": { "allowed": "true", "verificationStatus": "valid" } }, "legalEntityId": "Company.YourCompany://LE00000000000000000000001", "merchantId": "MC00000000000000000000001", "status": "PreActive" } } ``` ### Tab: Failed verification When there are problems with the verification, Adyen sends a [merchant.updated](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated) webhook with: * [verificationStatus](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated#request-data-capabilities-verificationStatus): Set to **invalid**. * [allowed](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated#request-data-capabilities-allowed): Set to **false**. * [problems](https://docs.adyen.com/api-explorer/ManagementNotification/latest/post/merchant.updated#request-data-capabilities-problems): Contains the `entity` and `verificationErrors` arrays indicating which legal entity could not be verified and why. If the verification is unsuccessful, you must resolve the verification errors. **Failed verification** ```json { "type": "merchant.updated", "environment": "test", "createdAt": "2023-02-01T09:01:02+02:00", "data": { "capabilities": { "receivePayments": { "allowed": "false", "problems": [ { "entity": { "id": "LE00000000000000000000001", "type": "LegalEntity" }, "verificationErrors": [ { "code": "2_8069", "message": "'organization.type' was missing.", "remediatingActions": [ { "code": "2_125", "message": "Add 'organization.type' to legal entity" } ], "type": "dataMissing" ] } ], "verificationStatus": "invalid" } }, "legalEntityId": "Company.YourCompany://LE00000000000000000000001", "merchantId": "MC00000000000000000000001", "status": "PreActive" } } ``` ### Resolve verification errors If the webhook has a [problems](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems) array, check [remediatingActions](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-capabilities-problems-verificationErrors-remediatingActions). In this array, you'll find the actions that you can take to resolve the error, such as updating the data or uploading documents. Refer to verification error codes for a list of verification errors. Let's say that the legal entity's name changed and now their data must be updated. To do this, send a PATCH [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request. **Update legal entity** ```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 '{ "individual": { "name": { "firstName" : "Shelly", "lastName" : "Eller" } } }' ``` After you update the data, Adyen sends another webhook with the `verificationStatus` set to **pending**. Once again, you will get updates about the status of the verification from the webhook or by making an API request. ## Step 10 (Optional): Upload documents Adyen attempts to verify the data that you provide. However, in some cases, the automatic verification might fail. This could be due to incorrect data or when the data cannot be verified. In these cases, Adyen may ask you to provide [additional documents](https://docs.adyen.com/managed-model/verification-requirements/document-requirements). Make sure your onboarding flow supports the collection of documents from users. For example, a remediating action code **1\_301** indicates that you need to upload an ID document for the user. To submit a document to Adyen: 1. Collect the document from the account holder. 2. Upload the document with a POST [/documents](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents) request, specifying: | Parameter | Required | Description | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [attachments](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-attachments) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Array that contains the document. | | [owner](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-owner) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Object that contains the [owner.id](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-owner-id) of the resource that owns the document and the [owner.type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-owner-type) of resource. For type **legalEntity**, the [id](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id) is the unique identifier of the legal entity. For type **bankAccount**, the [id](https://docs.adyen.com/api-explorer/legalentity/2/post/transferInstruments#responses-200-id) is the unique identifier of the transfer instrument. | | [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of document that you can upload depends on the legal entity type. Refer to [types](https://docs.adyen.com/api-explorer/legalentity/latest/post/documents#request-type) for a full list. | The combination of `owner.id`, `type`, and `attachments.content` must be unique. If you have already submitted the same combination, you'll receive an error message. Either update the existing document resource, or delete the resource and create a new one. Here is an example of how to upload an identity document for an individual: **Upload documents** ```bash curl https://kyc-test.adyen.com/lem/v3/documents \ -H 'x-api-key: ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "owner" : { "id" : "LE00000000000000000000001", "type" : "legalEntity" }, "description" : "ID for individual", "type" : "identityCard", "attachments" : [ { "content": "AAQSkZJRgABAQEAYABgAAD/s.." } ] }' ``` The response returns the **document** resource, identified by its unique `id`. **Response** ```json { "type": "identityCard", "attachments": [ { "content": "AAQSkZJRgABAQEAYABgAAD/s.." } ], "description": "ID for individual", "owner": { "id": "LE00000000000000000000001", "type": "legalEntity" }, "id": "SE00000000000000000000001" } ``` After you successfully upload the additional documents, wait for Adyen to inform you of the [verification results](https://docs.adyen.com/managed-model/onboard-users/api#get-updates-ah). Adyen validates documents asynchronously. On average, it takes about 30 seconds to validate a photo ID, and two days for registration documents and bank statements. ## Next steps [required](https://docs.adyen.com/managed-model/activate-merchant-account) [Activate merchant account](https://docs.adyen.com/managed-model/activate-merchant-account) [Configure your user's payment methods and payout settings, and activate their merchant account.](https://docs.adyen.com/managed-model/activate-merchant-account)