Update account holders

After an account holder is created, you can update its details and provide more information about the address, bank account, shareholders, and other data required for KYC verification.

In addition, you can change the status of the account holder or set up a new beneficiary for one of its accounts, as shown in this document.

Update account holder details

When you get more information about a sub-merchant or want to change some of the details submitted previously, pass new values along with the /updateAccountHolder request. In this request, provide the accountHolderCode value to specify the account holder to be updated.

Request

{
   "accountHolderCode":"TestAccountHolder414261",
   "accountHolderDetails":{
      "address":{
         "city":"Amsterdam",
         "country":"NL",
         "postalCode":"12345",
         "stateOrProvince":"NH",
         "street":"Teststreet 1"
      },
      "bankAccountDetails":[

      ],
      "email":"test@adyen.com",
      "individualDetails":{
         "name":{
            "firstName":"First name",
            "gender":"MALE",
            "lastName":"Last Name"
         },
         "personalData":{
            "dateOfBirth":"1970-01-01",
            "idNumber":"1234567890",
            "nationality":"NL"
         }
      },
      "merchantCategoryCode":"7999",
      "phoneNumber":{
         "phoneCountryCode":"NL",
         "phoneNumber":"0612345678",
         "phoneType":"Mobile"
      },
      "webAddress":"http://www.accountholderwebsite.com"
   }
}

Response

{
   "pspReference":"9914762676580105",
   "submittedAsync":"false",
   "accountHolderCode":"TestAccountHolder414261",
   "accountHolderDetails":{
      "address":{
         "city":"Amsterdam",
         "country":"NL",
         "postalCode":"12345",
         "stateOrProvince":"NH",
         "street":"Teststreet 1"
      },
      "bankAccountDetails":[

      ],
      "email":"test@adyen.com",
      "individualDetails":{
         "name":{
            "firstName":"First name",
            "gender":"MALE",
            "lastName":"Last Name"
         },
         "personalData":{
            "dateOfBirth":"1970-01-01",
            "idNumber":"1234567890",
            "nationality":"NL"
         }
      },
      "merchantCategoryCode":"7999",
      "phoneNumber":{
         "phoneCountryCode":"NL",
         "phoneNumber":"0612345678",
         "phoneType":"Mobile"
      },
      "webAddress":"http://www.accountholderwebsite.com"
   },
   "accountHolderStatus":{
      "status":"Active",
      "processingState":{
         "processedFrom":{
            "currency":"GBP",
            "value":0
         },
         "processedTo":{
            "currency":"GBP",
            "value":9999
         }
      },
      "payoutState":{
         "allowPayout":"true",
         "payoutLimit":{
            "currency":"GBP",
            "value":49999
         }
      }
   },
   "invalidFields":[

   ],
   "verification":{
      "accountHolder":{
         "checks":[
            {
               "type":"PASSPORT_VERIFICATION",
               "status":"AWAITING_DATA",
               "requiredFields":[
                  "AccountHolderDetails.Document.passport"
               ]
            },
            {
               "type":"IDENTITY_VERIFICATION",
               "status":"PASSED",
               "summary":{
                  "code":1602,
                  "description":"Passed"
               }
            }
         ]
      },
      "bankAccounts":[
         {
            "bankAccountUUID":"2f11df0b-a265-47ae-89c0-3d892066e7f5",
            "checks":[
               {
                  "type":"BANK_ACCOUNT_VERIFICATION",
                  "status":"PASSED"
               }
            ]
         }
      ]
   },
   "updatedFields":[

   ]
}

Update business details 

The following example demonstrates how to change business details of an account holder using the /updateAccountHolder request.

Request

{
   "accountHolderCode":"TestAccountHolder142860",
   "accountHolderDetails":{
      "bankAccountDetails":[

      ],
      "businessDetails":{
         "doingBusinessAs":"Test company B.V.",
         "legalBusinessName":"Test company",
         "shareholders":[
            {
               "ShareholderContact":{
                  "address":{
                     "city":"Amsterdam",
                     "country":"NL",
                     "houseNumberOrName":"1",
                     "postalCode":"1111AA",
                     "stateOrProvince":"NH",
                     "street":"Teststreet"
                  },
                  "email":"testShareholder@adyen.com",
                  "name":{
                     "firstName":"TestFirstName",
                     "gender":"MALE",
                     "lastName":"TestLastName"
                  }
               }
            }
         ],
         "taxId":"BV123456789"
      },
      "email":"test@adyen.com",
      "phoneNumber":{
         "phoneCountryCode":"NL",
         "phoneNumber":"0612345678",
         "phoneType":"Mobile"
      },
      "webAddress":"http://www.accountholderwebsite.com"
   }
}

Response

{
   "pspReference":"9914762677410120",
   "submittedAsync":"false",
   "accountHolderCode":"TestAccountHolder142860",
   "accountHolderDetails":{
      "bankAccountDetails":[

      ],
      "businessDetails":{
         "doingBusinessAs":"Test company B.V.",
         "legalBusinessName":"Test company",
         "shareholders":[
            {
               "ShareholderContact":{
                  "name":{
                     "firstName":"TestFirstName",
                     "gender":"MALE",
                     "lastName":"TestLastName"
                  },
                  "shareholderCode":"8adb06bb-12bd-4a4d-811d-c5e61d93dd10"
               }
            },
            {
               "ShareholderContact":{
                  "address":{
                     "city":"Amsterdam",
                     "country":"NL",
                     "houseNumberOrName":"1",
                     "postalCode":"1111AA",
                     "stateOrProvince":"NH",
                     "street":"Teststreet"
                  },
                  "email":"testShareholder@adyen.com",
                  "name":{
                     "firstName":"TestFirstName",
                     "gender":"MALE",
                     "lastName":"TestLastName"
                  },
                  "shareholderCode":"f3d76e56-8b8f-4350-89f7-5d166609645c"
               }
            }
         ],
         "taxId":"BV123456789"
      },
      "email":"test@adyen.com",
      "merchantCategoryCode":"7999",
      "phoneNumber":{
         "phoneCountryCode":"NL",
         "phoneNumber":"0612345678",
         "phoneType":"Mobile"
      },
      "webAddress":"http://www.accountholderwebsite.com"
   },
   "accountHolderStatus":{
      "status":"Active",
      "processingState":{
         "processedFrom":{
            "currency":"GBP",
            "value":0
         },
         "processedTo":{
            "currency":"GBP",
            "value":9999
         }
      },
      "payoutState":{
         "allowPayout":"true",
         "payoutLimit":{
            "currency":"GBP",
            "value":49999
         }
      }
   },
   "invalidFields":[

   ],
   "verification":{
      "accountHolder":{
         "checks":[
            {
               "type":"COMPANY_VERIFICATION",
               "status":"INVALID_DATA",
               "summary":{
                  "code":1201,
                  "description":""
               }
            }
         ]
      },
      "shareholders":[
         {
            "shareholderCode":"687a3ce4-7b0e-400e-8d36-77b7318c5bff",
            "checks":[
               {
                  "type":"IDENTITY_VERIFICATION",
                  "status":"PASSED",
                  "summary":{
                     "code":1602,
                     "description":"Passed"
                  }
               },
               {
                  "type":"PASSPORT_VERIFICATION",
                  "status":"PASSED"
               }
            ]
         }
      ],
      "bankAccounts":[
         {
            "bankAccountUUID":"c1dfc48c-489e-4434-8758-3620dd9d8adc",
            "checks":[
               {
                  "type":"BANK_ACCOUNT_VERIFICATION",
                  "status":"INVALID_DATA",
                  "summary":{
                     "code":1001,
                     "description":"The name of the bank account owner does not appear to be present on the provided bank statement. Please upload a statement that does contain the bank account owner that matches the account holder."
                  }
               }
            ]
         }
      ]
   },
   "updatedFields":[

   ]
}

Update bank account details

The following example demonstrates how to change bank account details of an account holder using the /updateAccountHolder request.

Request

{
   "accountHolderCode":"TimGreen",
   "accountHolderDetails":{
      "email":"tim@green.com",
      "individualDetails":{
         "name":{
            "firstName":"Tim",
            "gender":"MALE",
            "lastName":"Green"
         }
      },
      "bankAccountDetails":[
         {
            "BankAccountDetail":{
               "accountNumber":"1678116852",
               "branchCode":"053101273",
               "countryCode":"US",
               "currencyCode":"USD",
               "ownerName":"Tim Green",
               "ownerHouseNumberOrName":"100",
               "ownerStreet":"Main Street",
               "ownerPostalCode":"02894",
               "ownerCity":"Springfield",
               "ownerState":"AZ",
               "ownerCountryCode":"US"
            }
         }
      ]
   },
   "createDefaultAccount":"true",
   "legalEntity":"Individual"
}

Response

{
   "pspReference":"8515214647931806",
   "submittedAsync":"false",
   "accountHolderCode":"TimGreen",
   "accountHolderDetails":{
      "bankAccountDetails":[
         {
            "BankAccountDetail":{
               "accountNumber":"1678116852",
               "bankAccountUUID":"cc29b0d2-4716-4feb-ae68-3fd6bcb5cc3f",
               "branchCode":"053101273",
               "countryCode":"US",
               "currencyCode":"USD",
               "ownerCity":"Springfield",
               "ownerCountryCode":"US",
               "ownerHouseNumberOrName":"100",
               "ownerName":"Tim Green",
               "ownerPostalCode":"02894",
               "ownerState":"AZ",
               "ownerStreet":"Main Street",
               "primaryAccount":"false"
            }
         }
      ],
      "email":"tim@green.com",
      "individualDetails":{
         "name":{
            "firstName":"Tim",
            "gender":"MALE",
            "lastName":"Green"
         }
      },
      "merchantCategoryCode":"7999"
   },
   "accountHolderStatus":{
      "status":"Active",
      "processingState":{
         "disabled":"false",
         "processedFrom":{
            "currency":"EUR",
            "value":0
         },
         "processedTo":{
            "currency":"EUR",
            "value":9999
         },
         "tierNumber":0
      },
      "payoutState":{
         "allowPayout":"false",
         "disabled":"false"
      }
   },
   "invalidFields":[

   ],
   "legalEntity":"Individual",
   "updatedFields":[

   ],
   "verification":{
      "accountHolder":{
         "checks":[
            {
               "type":"IDENTITY_VERIFICATION",
               "status":"AWAITING_DATA",
               "requiredFields":[
                  "AccountHolderDetails.PersonalData.personalData",
                  "AccountHolderDetails.Address.address"
               ]
            }
         ]
      },
      "bankAccounts":[
         {
            "bankAccountUUID":"cc29b0d2-4716-4feb-ae68-3fd6bcb5cc3f",
            "checks":[
               {
                  "type":"BANK_ACCOUNT_VERIFICATION",
                  "status":"DATA_PROVIDED"
               }
            ]
         }
      ]
   }
}

Add shareholders

To add or update shareholders for a business account holder, pass their details in the /updateAccountHolder request. When updating the details of an existing shareholder, ensure to provide the shareholderCode value.

Request

{
   "accountHolderCode":"TestAccountHolder947393",
   "accountHolderDetails":{
      "bankAccountDetails":[

      ],
      "businessDetails":{
         "legalBusinessName":"legalBusinessName",
         "shareholders":[
            {
               "ShareholderContact":{
                  "email":"testEmail@gmail.com",
                  "personalData":{
                     "idNumber":"12345"
                  }
               }
            }
         ],
         "taxId":"taxid"
      }
   }
}

Response

{
   "pspReference":"9914762680690221",
   "submittedAsync":"false",
   "accountHolderCode":"TestAccountHolder947393",
   "accountHolderDetails":{
      "bankAccountDetails":[

      ],
      "businessDetails":{
         "legalBusinessName":"legalBusinessName",
         "shareholders":[
            {
               "ShareholderContact":{
                  "name":{
                     "firstName":"TestFirstName",
                     "gender":"MALE",
                     "lastName":"TestLastName"
                  },
                  "shareholderCode":"51060d51-871a-4150-9cef-5ce4e1835259"
               }
            },
            {
               "ShareholderContact":{
                  "email":"testEmail@gmail.com",
                  "personalData":{
                     "idNumber":"12345"
                  },
                  "shareholderCode":"8a791b17-1af7-427e-9526-2c8377ae3e41"
               }
            }
         ],
         "taxId":"taxid"
      },
      "email":"testEmail@gmail.com",
      "merchantCategoryCode":"7999"
   },
   "accountHolderStatus":{
      "status":"Active",
      "processingState":{
         "processedFrom":{
            "currency":"GBP",
            "value":0
         },
         "processedTo":{
            "currency":"GBP",
            "value":9999
         }
      },
      "payoutState":{
         "allowPayout":"true",
         "payoutLimit":{
            "currency":"GBP",
            "value":49999
         }
      }
   },
   "invalidFields":[

   ],
   "verification":{
      "accountHolder":{
         "checks":[
            {
               "type":"PASSPORT_VERIFICATION",
               "status":"AWAITING_DATA",
               "requiredFields":[
                  "AccountHolderDetails.Document.passport"
               ]
            },
            {
               "type":"IDENTITY_VERIFICATION",
               "status":"PASSED",
               "summary":{
                  "code":1602,
                  "description":"Passed"
               }
            }
         ]
      },
      "bankAccounts":[
         {
            "bankAccountUUID":"2f11df0b-a265-47ae-89c0-3d892066e7f5",
            "checks":[
               {
                  "type":"BANK_ACCOUNT_VERIFICATION",
                  "status":"PASSED"
               }
            ]
         }
      ]
   },
   "updatedFields":[

   ]
}

Update account holder state

To update an account holder's state, make a request to the /updateAccountHolderState endpoint and specify the accountHolderCode value to identify the account holder. In this request, pass the state to be modified (Processing or Payout) using the stateType parameter, and the new state value using the disable parameter.

Request

{
   "accountHolderCode":"TestAccountHolder215394",
   "disable":"true",
   "reason":"test reason payout",
   "stateType":"Payout"
}

Response

{
   "pspReference":"9914779157560083",
   "submittedAsync":"false",
   "accountHolderCode":"TestAccountHolder215394",
   "accountHolderStatus":{
      "status":"Active",
      "processingState":{
         "processedFrom":{
            "currency":"GBP",
            "value":0
         },
         "processedTo":{
            "currency":"GBP",
            "value":9999
         }
      },
      "payoutState":{
         "allowPayout":"true",
         "disabled": "true",
         "disableReason": "test reason payout",
         "payoutLimit":{
            "currency":"GBP",
            "value":49999
         }
      }
   }
}

Set up a beneficiary

With the /setupBeneficiary call you can set up a beneficiary for an existing account, which means that all the balance and transactions will be transferred to the beneficiary. After this operation, no transactions are booked on the source account, but all are forwarded to the new beneficiary instead.

When you make the /setupBeneficiary call for a source account that was already used as a destination account, the number of subsequent beneficiary transfers is limited to 2.

For example:
account1 → account2 → account3 is OK.
account1 → account2 → account3 → account4 is not allowed.

By default, the /setupBeneficiary call is disabled for your marketplace. To enable it, contact Support Team.

Request

{
    "destinationAccountCode": "128952522",
    "merchantReference": "Test",
    "sourceAccountCode": "134498192"
}

Response

{
    "pspReference": "9914860354282596",
    "submittedAsync": "false",
    "resultCode": "Success"
}