Worldpay Beneficial owners API

openapi: 3.2.0
info:
  title: Parties Beneficial owners API
  description: Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.
  contact:
    name: Team Fusion
  version: '2025-01-01'
  x-metadata:
    catalog-list: true
    business:
    - Marketplaces
    category:
    - Parties
    generated: true
servers:
- url: https://try.access.worldpay.com
  description: Test (Try)
- url: https://access.worldpay.com
  description: Live
security:
- basicAuth: []
tags:
- name: Beneficial owners
  description: Create and maintain beneficial owners.
paths:
  /parties/{partyId}/beneficialOwners:
    post:
      tags:
      - Beneficial owners
      summary: Create a beneficial owner
      operationId: createBeneficialOwner
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwners'
            examples:
              Create beneficial owner for existing company (modular):
                $ref: '#/components/examples/Create_Beneficial_Owner_modular'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwners'
              examples:
                Create beneficial owner for existing company (modular):
                  $ref: '#/components/examples/Beneficial_owner_created_201_modular'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
  /parties/{partyId}/beneficialOwners/{beneficialOwnerId}:
    get:
      tags:
      - Beneficial owners
      summary: View a beneficial owner
      operationId: getBeneficialOwner
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: beneficialOwnerId
        in: path
        description: A unique identifier for the beneficialOwner generated by us. This is sent in the response of your beneficialOwner creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: par.*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwners'
              examples:
                Get a Beneficial Owner:
                  $ref: '#/components/examples/Get_Beneficial_Owner_200_modular'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
    put:
      tags:
      - Beneficial owners
      summary: Update a beneficial owner
      operationId: updateBeneficialOwner
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: beneficialOwnerId
        in: path
        description: A unique identifier for the beneficialOwner generated by us. This is sent in the response of your beneficialOwner creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: par.*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwners'
            examples:
              Update a Beneficial Owner:
                $ref: '#/components/examples/Update_Beneficial_Owner_modular'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwners'
              examples:
                Update Beneficial Owner:
                  $ref: '#/components/examples/Update_Beneficial_Owner_200_modular'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
    delete:
      tags:
      - Beneficial owners
      summary: Delete a beneficial owner
      operationId: deleteBeneficialOwner
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: beneficialOwnerId
        in: path
        description: A unique identifier for the beneficialOwner generated by us. This is sent in the response of your beneficialOwner creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: par.*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      responses:
        '204':
          description: No Content
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
components:
  examples:
    '500':
      value:
        errorName: internalErrorOccurred
        message: An error occurred within the service (potentially due to an interaction with a downstream service).
    Create_Beneficial_Owner_modular:
      value:
        beneficialOwnerReference: xdl12goH60
        personalDetails:
          title: Dr
          firstName: John
          middleName: Illusionet
          lastName: Bailey
          alias: John Smith
          socialSecurityNumber: 333-55-6666
          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
          isPrincipalOwner: 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'
    '400':
      value:
        errorName: bodyDoesNotMatchSchema
        message: There were field validation errors. The errors that occurred are within the validationErrors array.
        validationErrors:
        - errorName: fieldIsNotAllowed
          message: The identified field is present when it is explicitly not allowed in the request.
          jsonPath: $.additionalData
    Update_Beneficial_Owner_modular:
      value:
        beneficialOwnerReference: uWBzL2nzx3
        personalDetails:
          title: Dr
          firstName: John
          middleName: Illusionet
          lastName: Bailey
          alias: John bailey
          socialSecurityNumber: 333-55-6566
          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
          isPrincipalOwner: true
          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_Beneficial_Owner_200_modular:
      description: Update the beneficial owner for a party company (modular)
      value:
        identityVerificationState: notVerified
        identityVerificationMethod: identityVerificationService
        beneficialOwnerReference: Gerson337
        beneficialOwnerId: pardPhiwdlp8VcnS8U7LHVbE0
        personalDetails:
          title: Dr
          firstName: John
          middleName: Illusionet
          lastName: Bailey
          alias: John Bailey
          socialSecurityNumber: 393-55-6666
          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
          isPrincipalOwner: true
          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'
    400_Invalid_Url:
      value:
        errorName: urlContainsInvalidValue
        message: The URL contains a value or values that are invalid.
        validationErrors:
        - errorName: fieldHasInvalidValue
          message: Party 'parDgfhD9O5lWVjWiUOo3Cdf0' was not found.
          jsonPath: $.partyId
    Beneficial_owner_created_201_modular:
      description: Beneficial owner for existing party type company (modular)
      value:
        identityVerificationState: notVerified
        identityVerificationMethod: identityVerificationService
        beneficialOwnerReference: owner28
        beneficialOwnerId: parNtJbNC8_fd_HRKyQRekiN0
        personalDetails:
          title: Dr
          firstName: John
          middleName: Illusionet
          lastName: Bailey
          alias: John bailey
          socialSecurityNumber: 333-55-1666
          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
          isPrincipalOwner: 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: 0
    Get_Beneficial_Owner_200_modular:
      description: Get a beneficial owner
      value:
        identityVerificationState: started
        identityVerificationMethod: identityVerificationService
        beneficialOwnerReference: Santino227
        beneficialOwnerId: parNKRss9vllWyX1MUVOj7b-0
        personalDetails:
          title: Dr
          firstName: John
          middleName: Illusionet
          lastName: Bailey
          alias: John bailey
          socialSecurityNumber: 373-55-6666
          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
          isPrincipalOwner: 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'
        dateTimeUpdated: '2025-04-08T20:47:59.479Z'
        version: 1
    '503':
      value:
        errorName: serviceUnavailable
        message: Service cannot fulfil the request even though service functions witout internal errors.
  schemas:
    BeneficialOwners:
      type: object
      properties:
        identityVerificationState:
          type: string
          enum:
          - verified
          - notVerified
          - pending
          - rejected
          - notApplicable
          - started
          - startedAction
          - pendingStepUpAction
          - pendingManualReview - stepUpReceived
          readOnly: true
        identityVerificationMethod:
          type: string
          enum:
          - merchantCompliant
          - identityVerificationService
          readOnly: true
        identityVerificationDate:
          type: string
          format: date
          description: A valid date as YYYY-MM-DD
          example: '2033-11-22'
          readOnly: true
        url:
          type: string
          description: The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.
          readOnly: true
        message:
          type: string
          description: The message associated with link returned from Identity Verification Status (IVS).
          readOnly: true
        beneficialOwnerReference:
          type: string
          description: 'Your reference for this beneficial owner, must be unique within an entity.


            '
          example: Hosaka27384910
          maxLength: 64
          minLength: 3
          pattern: ^[A-Za-z0-9\-_ ]*$
        beneficialOwnerId:
          type: string
          description: A unique identifier for the beneficial owner generated by us.
          readOnly: true
        personalDetails:
          $ref: '#/components/schemas/PersonalDetailsForBeneficialOwner'
        relationshipToBusiness:
          $ref: '#/components/schemas/RelationshipToBusiness'
        email:
          type: string
          format: email
        phones:
          type: array
          items:
            $ref: '#/components/schemas/Phone'
        identityDocuments:
          type: array
          items:
            $ref: '#/components/schemas/IdentityDocument'
        dateTimeCreated:
          type: string
          description: The date and time that the beneficial owner was created, as an ISO 8601 zoned date time.
          example: 2025-01-23T12:23:445.222Z
          readOnly: true
        version:
          type: integer
          format: int32
          readOnly: true
        dateTimeUpdated:
          type: string
          description: 'The date and time that the beneficial owner was last updated, as an ISO 8601 zoned date time.


            '
          example: 2025-01-25T14:57:012.302Z
          readOnly: true
      required:
      - beneficialOwnerReference
      - personalDetails
      - relationshipToBusiness
    ErrorResponse:
      type: object
      properties:
        errorName:
          type: string
          description: An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
          example: bodyDoesNotMatchSchema
        message:
          type: string
          description: A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseItem'
        pathParameter:
          type: string
        queryParameter:
          type: string
        jsonPath:
          type: string
      readOnly: true
      title: Error Response
    RelationshipToBusiness:
      type: object
      properties:
        ownershipPercentage:
          type: number
          description: Percentage of the ownership of the beneficial owner over the company.
          format: double
          maximum: 100
        director:
          type: boolean
          description: 'A flag indicating if the beneficial owner is also a director for the company.

            '
        isPrincipalOwner:
          type: boolean
          description: 'A flag indicating if the beneficial owner is also a principal owner for the company.<br>

            **Note:** You can set no more than **one** beneficial owner per party record of type `company`, as principal owner.

            '
          example: true
        position:
          type: string
          description: Type of position of the beneficial owner within the company.
          enum:
          - soleTrader
          - accountant
          - bursar
          - chairman
          - chairwoman
          - chiefExecutiveOfficer
          - clerk
          - companySecretary
          - creditController
          - deputyLeader
          - generalManager
          - leader
          - manager
          - managingDirector
          - master
          - guarantor
          - mayor
          - officeManager
          - operationsManager
          - president
          - principal
          - proprietor
          - townClerk
          - director
          - apportionmentAndOversight
          - chiefExecutive
          - complianceOversight
          - directorUnincorporatedAssociate
          - nonExecutiveDirector
          - significantManagement
          - smallFriendlySociety
          - chairperson
          - designatedMember
          - secretary
          - trustee
          - treasurer
          - businessRepresentative
          - authorisedSignatory
          - signatory
          - technicalContact
          - contractSignatory
          - publicOfficer
          - controller
          - beneficialOwner
          - partner
          - shareholder
          - chiefFinancialOfficer
          - chiefOperatingOfficer
          - beneficiary
          - charitySecretary
          - member
          - protector
          - settlor
          - soleProprietor
          - nonDesignatedMember
      required:
      - director
      - ownershipPercentage
      - position
    IdentityDocument:
      type: object
      description: An identity document.
      properties:
        type:
          type: string
          description: The type of the identity document.
          enum:
          - passport
          - nationalId
          - driverLicence
          - workPermit
          - employmentPass
          - studentPass
          - permanentResidentCard
          - companyRegistrationNumber
          - companyVATNumber
          - citizenshipCard
          - taxId
          - nationalInsurance
          - other
          - legalIdentityCard
          - taxRegistrationCode
        number:
          type: string
          minLength: 1
        issuingInstitution:
          type: string
          description: The name of the institution that issued this document.
          example: State Department
        issuingCountry:
          type: string
          description: The country code of the issuing country specified in [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) format.
          example: JP
          minLength: 1
        validFrom:
          type: string
          description: The ISO 8601 date since when this document is valid from.
          example: '2023-11-22'
        validTo:
          type: string
          description: The ISO 8601 date until which this document is valid to.
          example: '2023-11-22'
      required:
      - issuingCountry
      - number
      - type
      title: identityDocument
    Address:
      type: object
      description: Object containing details about the address.
      properties:
        address1:
          type: string
          description: 'The address.


            Must consist of at least two letters, two words, and one number.'
          example: 1847 Kingsbury Court
          maxLength: 35
          minLength: 2
        address2:
          type: string
          description: Line two of the address.
          example: Unit 42
          maxLength: 35
          minLength: 2
        city:
          type: string
          description: The city of this address.
          example: London
          maxLength: 35
          minLength: 1
        state:
          type: string
          description: The state of this address.
          example: Greater London
          maxLength: 35
          minLength: 2
        countryCode:
          type: string
          description: The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
          example: GB
          maxLength: 2
          minLength: 2
        postalCode:
          type: string
          description: The postal code of this address.
          example: NW9 0RR
          maxLength: 20
          minLength: 1
        type:
          type: string
          description: Identifies the type of this address.
          enum:
          - home
          - business
          - poBox
          - other
          example: home
      required:
      - address1
      - city
      - countryCode
    Phone:
      type: object
      description: Object containing phone information.
      properties:
        prefix:
          type: string
          description: The dialing prefix for the phone number.
          example: '44'
          pattern: ^[0-9]{1,3}$
        number:
          type: string
          description: The phone number, without dashes.
          example: '4281234'
          pattern: '[0-9]{1,20}'
      required:
      - number
      - prefix
    ErrorResponseItem:
      type: object
      properties:
        errorName:
          type: string
        message:
          type: string
        path:
          type: string
        jsonPath:
          type: string
        queryParameter:
          type: string
        pathParameter:
          type: string
    PersonalDetailsForBeneficialOwner:
      type: object
      properties:
        title:
          type: string
          description: The title for this `person`/`soleTrader`.
          enum:
          - Mr
          - Mrs
          - Miss
          - Ms
          - Dr
          - Mx
          - Misc
          example: Mr
        firstName:
          type: string
          description: 'The `person`''s/`soleTrader`''s first name.

            '
          example: Case
          maxLength: 35
          minLength: 2
          pattern: ^[\p{L}\-.,'()&]{2,}$
        middleName:
          type: string
          description: 'The `person`''s/`soleTrader`''s middle name or initial.


            '
          example: Henry
          maxLength: 35
          minLength: 1
          pattern: ^(?:\p{L}\.?)*+$
        lastName:
          type: string
          description: 'The `person`''s/`soleTrader`''s last name.


            '
          example: Mitchell
          maxLength: 35
          minLength: 2
          pattern: ^(?:[\p{L}\-.,'()&]{2,} *)*+$
        alias:
          type: string
          description: An alternative or commonly-used name for the individual (e.g., preferred or informal name). Does not replace the legal name.
          example: Junior Case
          maxLength: 35
          minLength: 2
          pattern: ^[\p{L}\-.,'()&]++(?:\s++[\p{L}\-.,'()&]++)*+$
        socialSecurityNumber:
          type: string
          description: The individual’s U.S. Social Security Number (SSN), required for U.S.-based tax or identity checks.
          example: 004-54-6578
          pattern: ^\d{3}-\d{2}-\d{4}$
        dateOfBirth:
          type: string
          description: 'The date the `person`/`soleTrader` was born.


            '
          example: '1983-10-12'
        address:
          $ref: '#/components/schemas/Address'
          description: The address of the `person`/`soleTrader`.
        residentialStatus:
          type: string
          description: The residential status of the `person`/`soleTrader`.
          enum:
          - resident
          - nonResident
          - other
        customerReference:
          type: string
          description: Unique reference provided by the payee. Only required for certain payout destinations.
          example: '7564389201'
          maxLength: 255
          minLength: 1
        nationality:
          type: string
          description: The nationality of the `person`/`soleTrader`.
        currentAddressLessThanThreeYears:
          type: boolean
        previousHomeAddress:
          $ref: '#/components/schemas/Address'
          description: The previous home address of the `person`/`soleTrader`.
        website:
          type: string
          description: The URL of the merchant's website.
          example: https://example.com/
      required:
      - address
      - firstName
      - lastName
      - title
  securitySchemes:
    basicAuth:
      type: http
      description: Basic authentication with user name and password
      scheme: basic