Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Marketpay icon

Legal arrangements check

Include information about an account holder's legal arrangements.

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.

The information that account holders provide will be part of the KYC checks. Failing to declare legal arrangements can result in blocked payouts and account suspensions.

If you built your own onboarding flow, you need to collect documents and additional information in your UI and then send the information to Adyen. But if you are using the Adyen-hosted onboarding page, you don't have to do anything as the page handles collecting requirements by default.

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.

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.
  • A document that proves the association.
  • Information about other associates.
    • Their legal entity type. Can be individual, business, nonprofit, or public company.
    • Their name, birthdate, and address.
    • Their ID number.

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 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.
  • A document that proves the partnership.
  • Information about other partners.
    • Their legal entity type. Can be individual, business, nonprofit, or public company.
    • Their name, birthdate, and address.
    • Their ID number.

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.
  • A document that proves the sole proprietorship.

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 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.
  • 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 perform the corresponding KYC 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.

Step 2: Update the account holder

Legal arrangements are supported from API version 6 and later.

Update an existing account holder and send the information that you received from them in the legalArrangements array.

Below is an example of how you would update an existing account holder to include information about their association.

In your POST /updateAccountHolder request, specify:

Add information about an association
curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
-H "x-API-key: YOUR_X-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"
                }
              ]
            }
          }
        ]
      }
    ]
  }
}'

Below is an example of how you would update an existing account holder to include information about their partnership.

In your POST /updateAccountHolder request, specify:

Add information about a partnership
curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
-H "x-API-key: YOUR_X-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"
                }
              ]
            }
          }
        ]
      }
    ]
  }
}'

Below is an example of how you would update an individual account holder to include details about their sole proprietorship.

In your POST /updateAccountHolder request, specify:

Add information for sole proprietor
curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
-H "x-API-key: YOUR_X-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"
       }
     ]
   }
}'

Below is an example of how you would 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 request, specify:

Add information about a trust
curl https://cal-test.adyen.com/cal/services/Account/v6/updateAccountHolder \
-H "x-API-key: YOUR_X-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 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 or ACCOUNT_HOLDER_UPDATED webhook: Informs you when the account holder has been successfully updated. You'll get the status of KYC checks in the verification object under the legalArrangements and legalArrangementsEntities arrays.
  • 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
{
  "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": "KYC check summary description"
      },
      "requiredFields": [
        "field.missing"
      ]
    },
    "shareholderCode": "SH00000001",
    "legalArrangementEntityCode": "ADYEN-UUID-LAEC-1234-5678",
    "legalArrangementCode": "ADYEN-UUID-LA-1234-5678"
  }
}

Legal arrangements are supported from API version 6 and later.

Adyen requires account holders to provide a document that proves their contractual agreement such as a registration or a constitutional document.

When you have collected the document from the account holder, make a POST /uploadDocument request specifying:

  • 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
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...VcdCB=",
     "documentDetail":{
      "accountHolderCode":"ACCOUNT_HOLDER_CODE",
      "documentType":"CONSTITUTIONAL_DOCUMENT",
      "filename": "constitutionalDocument.pdf"
     }
   }'

Requests using /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: 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