New service | Last updated: 14 May 2025
This documentation is for preview purposes only.
Manage beneficial owners
A beneficial owner record is used to store the details about a specific beneficial owner. The purpose is to be able to perform identity verification checks for companies.
Who is a beneficial owner?
A beneficial owner can be anyone with ownership percentage of the company, managing directors, or any person with in a managing and/or controlling role, as stated in public records for the company. This record is very important from an identity verification perspective of a company and should match publicly stated records for that company. This is to ensure highest probability of a successful identity verification process.
You can add details of people (person
in the API) that are beneficial owners of the company to your party
record.
If your company additionally has beneficial owners that are also companies, please contact your Implementation Manager to manually process this application.
The ability to add details for beneficial owners that are companies is coming soon.
You can add a beneficial owner in two ways. Either during or after the creation of a party. This guide focuses on adding a beneficial owner after the party creation call.
To add a beneficial owner during orchestrated party creation call, you can use the https://access.worldpay.com/parties
endpoint.
Add beneficial owners
After a party of type company is created, you can add beneficial owner details by using following endpoint:
POST
https://access.worldpay.com/parties/{partyId}/beneficialOwner
Request/Response example
- Live http://access.worldpay.com/parties/{partyId}/beneficialOwners
- Try http://try.access.worldpay.com/parties/{partyId}/beneficialOwners
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
Create beneficial owner for existing company (modular)
{ "beneficialOwnerReference": "xdl12goH60", "personalDetails": { "title": "Dr", "firstName": "John", "middleName": "Illusionet", "lastName": "Bailey", "residentialStatus": "nonResident", "dateOfBirth": "1972-05-22", "nationality": "GB", "address": { "address1": "200 Downing Street", "address2": "Flat 404", "city": "London", "type": "home", "countryCode": "GB", "postalCode": "SW1A 2AA" }, "currentAddressLessThanThreeYears": true, "previousHomeAddress": { "address1": "425 Oxford Street", "address2": "Flat 101", "city": "London", "type": "home", "countryCode": "GB", "postalCode": "W1D 1LP" } }, "relationshipToBusiness": { "ownershipPercentage": 10, "director": false, "position": "partner" }, "identityDocuments": [ { "type": "passport", "number": "B98765432", "issuingInstitution": "UK Passport Office", "issuingCountry": "GB", "validFrom": "2018-05-15", "validTo": "2028-05-15" } ], "email": "John.bailey@example.com", "phones": [ { "number": "0205556789", "prefix": "44" } ] }
Beneficial owner for existing party type company (modular)
{ "identityVerificationState": "pending", "identityVerificationMethod": "identityVerificationService", "beneficialOwnerReference": "owner28", "beneficialOwnerId": "parNtJbNC8_fd_HRKyQRekiN0", "personalDetails": { "title": "Dr", "firstName": "John", "middleName": "Illusionet", "lastName": "Bailey", "dateOfBirth": "1972-05-22", "address": { "address1": "200 Downing Street", "address2": "Flat 404", "city": "London", "countryCode": "GB", "postalCode": "SW1A 2AA", "type": "home" }, "residentialStatus": "nonResident", "nationality": "GB", "currentAddressLessThanThreeYears": true, "previousHomeAddress": { "address1": "425 Oxford Street", "address2": "Flat 101", "city": "London", "countryCode": "GB", "postalCode": "W1D 1LP", "type": "home" } }, "relationshipToBusiness": { "ownershipPercentage": 10, "director": false, "position": "partner" }, "email": "John.bailey@example.com", "phones": [ { "prefix": "44", "number": "0205556789" } ], "identityDocuments": [ { "type": "passport", "number": "B98765432", "issuingInstitution": "UK Passport Office", "issuingCountry": "GB", "validFrom": "2018-05-15", "validTo": "2028-05-15" } ], "dateTimeCreated": "2025-03-20T18:33:41.480Z", "version": 1 }
See full schema to create a beneficial owner.
View a beneficial owner
View information of a beneficial owner, previously created.
GET
https://access.worldpay.com/parties/{partyId}/beneficialOwner/{beneficialOwnerId}
beneficialOwnerId
- you have received this in the beneficial owner creation response. It uniquely identifies your payout instrument in our system.
Request example
- Live http://access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Try http://try.access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
No request payload
Get a beneficial owner
{ "identityVerificationState": "pending", "identityVerificationMethod": "identityVerificationService", "beneficialOwnerReference": "Santino227", "beneficialOwnerId": "parNKRss9vllWyX1MUVOj7b-0", "personalDetails": { "title": "Dr", "firstName": "John", "middleName": "Illusionet", "lastName": "Bailey", "dateOfBirth": "1972-05-22", "address": { "address1": "200 Downing Street", "address2": "Flat 404", "city": "London", "countryCode": "GB", "postalCode": "SW1A 2AA", "type": "home" }, "residentialStatus": "nonResident", "nationality": "GB", "currentAddressLessThanThreeYears": true, "previousHomeAddress": { "address1": "425 Oxford Street", "address2": "Flat 101", "city": "London", "countryCode": "GB", "postalCode": "W1D 1LP", "type": "home" } }, "relationshipToBusiness": { "ownershipPercentage": 10, "director": false, "position": "partner" }, "email": "John.bailey@example.com", "phones": [ { "prefix": "44", "number": "0205556789" } ], "identityDocuments": [ { "type": "passport", "number": "B98765432", "issuingInstitution": "UK Passport Office", "issuingCountry": "GB", "validFrom": "2018-05-15", "validTo": "2028-05-15" } ], "dateTimeCreated": "2025-04-07T20:47:59.479Z", "version": 1 }
See full schema to view a beneficial owner.
Modify a beneficial owner
You can modify certain beneficial owner information previously created by calling the following endpoint:
PUT
https://access.worldpay.com/parties/{partyId}/beneficialOwner/{beneficialOwnerId}
beneficialOwnerId
- you have received this in the beneficial owner creation response. It uniquely identifies your payout instrument in our system.partyId
- you have received this in the party creation response. It uniquely identifies your payout instrument in our system.
Request/Response example
- Live http://access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Try http://try.access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
Update a Beneficial Owner
{ "beneficialOwnerReference": "uWBzL2nzx3", "personalDetails": { "title": "Dr", "firstName": "John", "middleName": "Illusionet", "lastName": "Bailey", "residentialStatus": "nonResident", "dateOfBirth": "1972-05-22", "nationality": "GB", "address": { "address1": "200 Downing Street", "address2": "Flat 404", "city": "London", "type": "home", "countryCode": "GB", "postalCode": "SW1A 2AA" }, "currentAddressLessThanThreeYears": true, "previousHomeAddress": { "address1": "200 Oxford Street", "address2": "Flat 101", "city": "London", "type": "home", "countryCode": "GB", "postalCode": "W1D 1LP" } }, "relationshipToBusiness": { "ownershipPercentage": 10, "director": false, "position": "partner" }, "identityDocuments": [ { "type": "passport", "number": "B98765432", "issuingInstitution": "UK Passport Office", "issuingCountry": "GB", "validFrom": "2018-05-15", "validTo": "2028-05-15" } ], "email": "John.bailey@example.com", "phones": [ { "number": "0205556789", "prefix": "44" } ] }
Update the beneficial owner for a party company (modular)
{ "identityVerificationState": "notVerified", "identityVerificationMethod": "identityVerificationService", "beneficialOwnerReference": "Gerson337", "beneficialOwnerId": "pardPhiwdlp8VcnS8U7LHVbE0", "personalDetails": { "title": "Dr", "firstName": "John", "middleName": "Illusionet", "lastName": "Bailey", "dateOfBirth": "1972-05-22", "address": { "address1": "200 Downing Street", "address2": "Flat 404", "city": "London", "countryCode": "GB", "postalCode": "SW1A 2AA", "type": "home" }, "residentialStatus": "nonResident", "nationality": "GB", "currentAddressLessThanThreeYears": true, "previousHomeAddress": { "address1": "200 Oxford Street", "address2": "Flat 101", "city": "London", "countryCode": "GB", "postalCode": "W1D 1LP", "type": "home" } }, "relationshipToBusiness": { "ownershipPercentage": 10, "director": false, "position": "partner" }, "email": "John.bailey@example.com", "phones": [ { "prefix": "44", "number": "0205556789" } ], "identityDocuments": [ { "type": "passport", "number": "B98765432", "issuingInstitution": "UK Passport Office", "issuingCountry": "GB", "validFrom": "2018-05-15", "validTo": "2028-05-15" } ], "dateTimeCreated": "2025-04-10T15:45:06.349Z", "version": 2, "dateTimeUpdated": "2025-04-10T15:45:09.389Z" }
See full schema to modify a beneficial owner.
Delete a beneficial owner
You can delete a beneficial owner from the company record:
DELETE
https://access.worldpay.com/parties/{partyId}/beneficialOwner/{beneficialOwnerId}
Request/Response example
- Live http://access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Try http://try.access.worldpay.com/parties/{partyId}/beneficialOwners/{beneficialOwnerId}
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
No request payload
No content
See full schema to delete a beneficial owner.
Next Steps
Add a payout instrument
Add balance accounts or
Verify a party