New service | Last updated: 14 May 2025

Important

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.

Note

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

application/json

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"
    }
  ]
}
Response
application/json

Beneficial owner for existing party type company (modular)

{
  "identityVerificationState": "notVerified",
  "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}


Request example

No request payload
Response
application/json

Get a beneficial owner

{
  "identityVerificationState": "started",
  "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}


Request/Response example

application/json

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"
    }
  ]
}
Response
application/json

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

No request payload
Response
No content

See full schema to delete a beneficial owner.

Next Steps

Add a payout instrument
Add balance accounts or
Verify a party