APIs
/
Parties
/
Parties
/
Create a party

Parties (2025-01-01)

Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.

Authentication

Set your headers

Authorization: {your_credentials}
WP-Api-Version: 2025-01-01

Replace {your_credentials} with your base64-encoded Basic Auth username and password.

DNS Whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting.

API Collection

A full set of API examples based on different scenarios.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License Worldpay
Languages
Servers
Live
http://access.worldpay.com/
Try
http://try.access.worldpay.com/

Parties

Create and maintain parties.

Operations

Create a party

Request

Headers
WP-Api-Versionstring(date)required

The API version.

Example: 2025-01-01
Bodyapplication/jsonrequired
One of:

A party represents the overall party record of your beneficiary (seller, vendor, provider). You can use this to store information about the party, to perform either an identity verification checks, a split payment, or a payout.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 36 ] characters[a-zA-Z0-9- ]*required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
partyReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this party, must be unique within an entity.

Example: "Hosaka27384910"
partyTypestringrequired

The type of this party.

beneficiary - the person or business that will receive funds.

payer - a transmitter of funds to a third party.

Enum"beneficiary""payer"
typestringrequired

What the party represents:

person - an individual

soleTrader - a single person enterprise

company - a corporation or partnership with multiple owners

Enum"company""person""soleTrader"
emailstring

An email address for this party.

phonesArray of objects

A list of phone numbers associated with this party.

prefixstring^[0-9]{1,3}$required

The dialing prefix for the phone number.

Example: "44"
numberstring[0-9]{1,20}required

The phone number, without dashes.

Example: "4281234"
identityDocumentsArray of objects

A list of identity documents for this party.

typestringrequired

The type of the identity document.

Enum"passport""nationalId""driverLicence""workPermit""employmentPass""studentPass""permanentResidentCard""companyRegistrationNumber""companyVATNumber""citizenshipCard"
numberstringnon-emptyrequired
issuingInstitutionstring

The name of the institution that issued this document.

Example: "State Department"
issuingCountrystringnon-emptyrequired
Example: "JP"
validFromstring

The ISO 8601 date since when this document is valid from.

Example: "2023-11-22"
validTostring

The ISO 8601 date until which this document is valid to.

Example: "2023-11-22"
balanceAccountsArray of objects

A list of balance accounts that have been set up for this party.

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
overallAccountStatusstring

The overallStatus provides an complete view of the parties identityVerificationState.

payoutInstrumentsArray of objects
payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

An ID generated by us to identify a payout instrument. You receive this in the response after successfully creating a payout instrument.

Example: "parOk0YlPtQogrqQdz7_fKXs0"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject

Object containing details about the address.

branchCodestring
performIdentityVerificationbooleanwrite-only
companyDetailsobjectrequired

Object containing details about a company. Required for company.

merchantCategoryCodestring= 4 characters^\d{4}$

A 4-digit code to represent the merchant category. Only provide this where typeCode is soleTrader or company.

Example: "5411"
merchantCategoryCodeDescriptionstring[ 1 .. 255 ] characters

A description to describe the merchant category code. Only provide this where typeCode is soleTrader or company.

Example: "Grocery Stores"
websitestring

The URL of the merchant's website.

Example: "https://example.com/"
legalNamestring[ 2 .. 140 ] characters^(?: *[\p{L}\p{N}+&\/\-.()])*+(?: *[\p{L}\p{N...required

The legal name of the company.

Example: "Tessier-Ashpool Systems Ltd."
tradingNamestring[ 2 .. 140 ] characters^(?: *[\p{L}\p{N}+&\/\-.()])*+(?: *[\p{L}\p{N...

The trading common name of the company.

Example: "TASynth.com"
registrationNumberstring[ 1 .. 15 ] characters[a-zA-Z0-9-]*required

The registration number for the company. What should be supplied in this field may differ by country, for instance in the United States it will be a Tax ID. Number (TIN).

Example: "7564389201"
vatNumberstring[ 1 .. 15 ] characters[a-zA-Z0-9-]*required

The Value Added Tax (VAT) number of the company.

Example: "JP987654321"
companyTypestring[ 1 .. 50 ] characters

A description of the type of company.

Example: "Public Limited"
dateOfIncorporationstring

The incorporation date for the company.

Example: "1977-07-04"
legalAddressobjectrequired

The legal address of this company.

tradingAddressobject

The trading address of this company.

customerReferencestring[ 1 .. 255 ] characters

Unique reference provided by the payee. Only required for certain payout destinations.

Example: "7564389201"
countryOfIncorporationstring
Example: "GB"
beneficialOwnersArray of objects
beneficialOwnerReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this beneficial owner, must be unique within an entity.

Example: "Hosaka27384910"
personalDetailsobjectrequired
relationshipToBusinessobjectrequired
emailstring
phonesArray of objects
identityDocumentsArray of objects
application/json

Create a party for a person (orchestrated)

{
  "merchant": {
    "entity": "default"
  },
  "partyReference": "VuzvLew4y7",
  "partyType": "beneficiary",
  "type": "person",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "residentialStatus": "resident",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "1847 Kingsbury Court",
      "address2": "Unit 42",
      "type": "home",
      "city": "Manchester",
      "countryCode": "GB",
      "postalCode": "M1 1AA"
    }
  },
  "email": "case.mitchell@example.com",
  "phones": [
    {
      "number": "02079461234",
      "prefix": "44"
    }
  ],
  "balanceAccounts": [
    {
      "currency": "GBP",
      "scheduledPayoutDay": "tuesday",
      "payoutInstrumentReference": "MyPayoutInstrument1"
    }
  ],
  "payoutInstruments": [
    {
      "accountHolderName": "Case H. Mitchell",
      "payoutInstrumentType": "bankAccount",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "branchCode": "Taunton Branch",
      "accountNumber": "23198765",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "HSBC UK BANK PLC",
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "currency": "GBP",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "type": "business",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB"
      }
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "NEO456789",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2022-08-01",
      "validTo": "2032-08-01"
    },
    {
      "type": "nationalId",
      "number": "ZAIBATSU-00792",
      "issuingInstitution": "Zaibatsu Holding HR Dept.",
      "issuingCountry": "GB",
      "validFrom": "2025-01-01",
      "validTo": "2030-12-31"
    }
  ],
  "performIdentityVerification": true
}

Responses

Created

Bodyapplication/json
One of:

A party represents the overall party record of your beneficiary (seller, vendor, provider). You can use this to store information about the party, to perform either an identity verification checks, a split payment, or a payout.

identityVerificationStatestringread-only
Enum"verified""notVerified""pending""rejected""notApplicable""started""startedAction""pendingStepUpAction""pendingManualReview"
identityVerificationMethodstringread-only
Enum"merchantCompliant""identityVerificationService"
identityVerificationDatestring(date)read-only

A valid date as YYYY-MM-DD

Example: "2033-11-22"
urlstringread-only

The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 36 ] characters[a-zA-Z0-9- ]*required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
partyReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this party, must be unique within an entity.

Example: "Hosaka27384910"
partyTypestringrequired

The type of this party.

beneficiary - the person or business that will receive funds.

payer - a transmitter of funds to a third party.

Enum"beneficiary""payer"
typestringrequired

What the party represents:

person - an individual

soleTrader - a single person enterprise

company - a corporation or partnership with multiple owners

Enum"company""person""soleTrader"
partyIdstringread-only

A unique identifier for the party generated by us.

emailstring

An email address for this party.

phonesArray of objects

A list of phone numbers associated with this party.

prefixstring^[0-9]{1,3}$required

The dialing prefix for the phone number.

Example: "44"
numberstring[0-9]{1,20}required

The phone number, without dashes.

Example: "4281234"
identityDocumentsArray of objects

A list of identity documents for this party.

typestringrequired

The type of the identity document.

Enum"passport""nationalId""driverLicence""workPermit""employmentPass""studentPass""permanentResidentCard""companyRegistrationNumber""companyVATNumber""citizenshipCard"
numberstringnon-emptyrequired
issuingInstitutionstring

The name of the institution that issued this document.

Example: "State Department"
issuingCountrystringnon-emptyrequired
Example: "JP"
validFromstring

The ISO 8601 date since when this document is valid from.

Example: "2023-11-22"
validTostring

The ISO 8601 date until which this document is valid to.

Example: "2023-11-22"
balanceAccountsArray of objects

A list of balance accounts that have been set up for this party.

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
balanceAccountIdstringread-only

Unique ID created by us to identify a balance account. This sent in the response after balanceAccount creation.

dateTimeCreatedstringread-only

The date and time that the balance account was created, as an ISO 8601 zoned date time.

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the balance account was last updated, as an ISO 8601 zoned date time.

Example: "2025-01-25T02:43:499.202Z"
versioninteger(int32)read-only
overallAccountStatusstring

The overallStatus provides an complete view of the parties identityVerificationState.

dateTimeCreatedstringread-only

The date and time that the party was created, as an ISO 8601 zoned date time

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the party was last updated, as an ISO 8601 zoned date time

Example: "2025-01-25T14:57:012.302Z"
versioninteger(int32)read-only
payoutInstrumentsArray of objects
payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

An ID generated by us to identify a payout instrument. You receive this in the response after successfully creating a payout instrument.

Example: "parOk0YlPtQogrqQdz7_fKXs0"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
dateTimeCreatedstringread-only

The date and time the payoutInstrument was created, as an ISO 8601 zoned date time.

dateTimeUpdatedstringread-only

The date and time the payoutInstrument was updated, as an ISO 8601 zoned date time.

versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject

Object containing details about the address.

branchCodestring
personalDetailsobjectrequired
titlestringrequired

The title for this person/soleTrader.

Enum"Mr""Mrs""Miss""Ms""Dr""Mx""Misc"
Example: "Mr"
firstNamestring[ 2 .. 35 ] characters^[\p{L}\-.,'()&]{2,}$required

The person's/soleTrader's first name.

Example: "Case"
middleNamestring[ 1 .. 35 ] characters^(?:\p{L}\.?)*+$required

The person's/soleTrader's middle name or initial.

Example: "Henry"
lastNamestring[ 2 .. 35 ] characters^(?:[\p{L}\-.,'()&]{2,} *)*+$required

The person's/soleTrader's last name.

Example: "Mitchell"
dateOfBirthstring

The date the person/soleTrader was born.

Example: "1983-10-12"
addressobjectrequired

The address of the person/soleTrader.

residentialStatusstring

The residential status of the person/soleTrader.

Enum"resident""nonResident""other"
customerReferencestring[ 1 .. 255 ] characters

Unique reference provided by the payee. Only required for certain payout destinations.

Example: "7564389201"
nationalitystring

The nationality of the person/soleTrader.

currentAddressLessThanThreeYearsboolean
previousHomeAddressobject

The previous home address of the person/soleTrader.

websitestring

The URL of the merchant's website.

Example: "https://example.com/"
Response
application/json

Party for a person (orchestrated)

{
  "identityVerificationState": "started",
  "identityVerificationMethod": "identityVerificationService",
  "merchant": {
    "entity": "default"
  },
  "partyReference": "Heidi197",
  "partyType": "beneficiary",
  "type": "person",
  "partyId": "parMbuHucAsLeLL0BhDpWdjE0",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "1847 Kingsbury Court",
      "address2": "Unit 42",
      "city": "Manchester",
      "countryCode": "GB",
      "postalCode": "M1 1AA",
      "type": "home"
    },
    "residentialStatus": "resident",
    "currentAddressLessThanThreeYears": false
  },
  "email": "case.mitchell@example.com",
  "phones": [
    {
      "prefix": "44",
      "number": "02079461234"
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "NEO456789",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2022-08-01",
      "validTo": "2032-08-01"
    },
    {
      "type": "nationalId",
      "number": "ZAIBATSU-00792",
      "issuingInstitution": "Zaibatsu Holding HR Dept.",
      "issuingCountry": "GB",
      "validFrom": "2025-01-01",
      "validTo": "2030-12-31"
    }
  ],
  "balanceAccounts": [
    {
      "currency": "GBP",
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "scheduledPayoutDay": "tuesday",
      "balanceAccountId": "par3GymZO5MtP18qe5NFaaPp0",
      "dateTimeCreated": "2025-04-16T20:46:24.122Z",
      "version": 0
    }
  ],
  "dateTimeCreated": "2025-04-16T20:46:24.122Z",
  "version": 0,
  "payoutInstruments": [
    {
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "payoutInstrumentId": "parclOAFlaOX-H_2UBp9tWbd0",
      "payoutInstrumentType": "bankAccount",
      "currency": "GBP",
      "dateTimeCreated": "2025-04-16T20:46:24.122Z",
      "version": 0,
      "accountHolderName": "Case H. Mitchell",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "accountNumber": "23198765",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "HSBC UK BANK PLC",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB",
        "type": "business"
      },
      "branchCode": "Taunton Branch"
    }
  ]
}

View a party

Request

Retrieve information about a party.

Path
partyIdstring= 25 characters^par[a-zA-Z0-9-_]*0$required

A unique identifier for the party generated by us. This is sent in the response of your party creation call.

Example: parV1StGXR8_Z5jdHi6B-myF0
Headers
WP-Api-Versionstring(date)required

The API version.

Example: 2025-01-01
No request payload

Responses

OK

Bodyapplication/json
One of:

A party represents the overall party record of your beneficiary (seller, vendor, provider). You can use this to store information about the party, to perform either an identity verification checks, a split payment, or a payout.

identityVerificationStatestringread-only
Enum"verified""notVerified""pending""rejected""notApplicable""started""startedAction""pendingStepUpAction""pendingManualReview"
identityVerificationMethodstringread-only
Enum"merchantCompliant""identityVerificationService"
identityVerificationDatestring(date)read-only

A valid date as YYYY-MM-DD

Example: "2033-11-22"
urlstringread-only

The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 36 ] characters[a-zA-Z0-9- ]*required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
partyReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this party, must be unique within an entity.

Example: "Hosaka27384910"
partyTypestringrequired

The type of this party.

beneficiary - the person or business that will receive funds.

payer - a transmitter of funds to a third party.

Enum"beneficiary""payer"
typestringrequired

What the party represents:

person - an individual

soleTrader - a single person enterprise

company - a corporation or partnership with multiple owners

Enum"company""person""soleTrader"
partyIdstringread-only

A unique identifier for the party generated by us.

emailstring

An email address for this party.

phonesArray of objects

A list of phone numbers associated with this party.

prefixstring^[0-9]{1,3}$required

The dialing prefix for the phone number.

Example: "44"
numberstring[0-9]{1,20}required

The phone number, without dashes.

Example: "4281234"
identityDocumentsArray of objects

A list of identity documents for this party.

typestringrequired

The type of the identity document.

Enum"passport""nationalId""driverLicence""workPermit""employmentPass""studentPass""permanentResidentCard""companyRegistrationNumber""companyVATNumber""citizenshipCard"
numberstringnon-emptyrequired
issuingInstitutionstring

The name of the institution that issued this document.

Example: "State Department"
issuingCountrystringnon-emptyrequired
Example: "JP"
validFromstring

The ISO 8601 date since when this document is valid from.

Example: "2023-11-22"
validTostring

The ISO 8601 date until which this document is valid to.

Example: "2023-11-22"
balanceAccountsArray of objects

A list of balance accounts that have been set up for this party.

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
balanceAccountIdstringread-only

Unique ID created by us to identify a balance account. This sent in the response after balanceAccount creation.

dateTimeCreatedstringread-only

The date and time that the balance account was created, as an ISO 8601 zoned date time.

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the balance account was last updated, as an ISO 8601 zoned date time.

Example: "2025-01-25T02:43:499.202Z"
versioninteger(int32)read-only
overallAccountStatusstring

The overallStatus provides an complete view of the parties identityVerificationState.

dateTimeCreatedstringread-only

The date and time that the party was created, as an ISO 8601 zoned date time

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the party was last updated, as an ISO 8601 zoned date time

Example: "2025-01-25T14:57:012.302Z"
versioninteger(int32)read-only
payoutInstrumentsArray of objects
payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

An ID generated by us to identify a payout instrument. You receive this in the response after successfully creating a payout instrument.

Example: "parOk0YlPtQogrqQdz7_fKXs0"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
dateTimeCreatedstringread-only

The date and time the payoutInstrument was created, as an ISO 8601 zoned date time.

dateTimeUpdatedstringread-only

The date and time the payoutInstrument was updated, as an ISO 8601 zoned date time.

versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject

Object containing details about the address.

branchCodestring
personalDetailsobjectrequired
titlestringrequired

The title for this person/soleTrader.

Enum"Mr""Mrs""Miss""Ms""Dr""Mx""Misc"
Example: "Mr"
firstNamestring[ 2 .. 35 ] characters^[\p{L}\-.,'()&]{2,}$required

The person's/soleTrader's first name.

Example: "Case"
middleNamestring[ 1 .. 35 ] characters^(?:\p{L}\.?)*+$required

The person's/soleTrader's middle name or initial.

Example: "Henry"
lastNamestring[ 2 .. 35 ] characters^(?:[\p{L}\-.,'()&]{2,} *)*+$required

The person's/soleTrader's last name.

Example: "Mitchell"
dateOfBirthstring

The date the person/soleTrader was born.

Example: "1983-10-12"
addressobjectrequired

The address of the person/soleTrader.

residentialStatusstring

The residential status of the person/soleTrader.

Enum"resident""nonResident""other"
customerReferencestring[ 1 .. 255 ] characters

Unique reference provided by the payee. Only required for certain payout destinations.

Example: "7564389201"
nationalitystring

The nationality of the person/soleTrader.

currentAddressLessThanThreeYearsboolean
previousHomeAddressobject

The previous home address of the person/soleTrader.

websitestring

The URL of the merchant's website.

Example: "https://example.com/"
Response
application/json

Get a party for person

{
  "identityVerificationState": "pending",
  "identityVerificationMethod": "identityVerificationService",
  "merchant": {
    "entity": "default"
  },
  "partyReference": "Heidi197",
  "partyType": "beneficiary",
  "type": "person",
  "partyId": "parMbuHucAsLeLL0BhDpWdjE0",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "1847 Kingsbury Court",
      "address2": "Unit 42",
      "city": "Manchester",
      "countryCode": "GB",
      "postalCode": "M1 1AA",
      "type": "home"
    },
    "residentialStatus": "resident",
    "currentAddressLessThanThreeYears": false
  },
  "email": "case.mitchell@example.com",
  "phones": [
    {
      "prefix": "44",
      "number": "02079461234"
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "NEO456789",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2022-08-01",
      "validTo": "2032-08-01"
    },
    {
      "type": "nationalId",
      "number": "ZAIBATSU-00792",
      "issuingInstitution": "Zaibatsu Holding HR Dept.",
      "issuingCountry": "GB",
      "validFrom": "2025-01-01",
      "validTo": "2030-12-31"
    }
  ],
  "balanceAccounts": [
    {
      "currency": "EUR",
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "scheduledPayoutDay": "friday",
      "balanceAccountId": "pareBH4YMkUx7MA2X7bnS4750",
      "dateTimeCreated": "2025-04-16T20:46:26.727Z",
      "version": 0
    },
    {
      "currency": "GBP",
      "payoutInstrumentReference": "MyPayoutInstrument2",
      "scheduledPayoutDay": "tuesday",
      "balanceAccountId": "par3GymZO5MtP18qe5NFaaPp0",
      "dateTimeCreated": "2025-04-16T20:46:24.122Z",
      "version": 0
    }
  ],
  "dateTimeCreated": "2025-04-16T20:46:24.122Z",
  "version": 0,
  "payoutInstruments": [
    {
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "payoutInstrumentId": "parclOAFlaOX-H_2UBp9tWbd0",
      "payoutInstrumentType": "bankAccount",
      "currency": "GBP",
      "dateTimeCreated": "2025-04-16T20:46:24.122Z",
      "version": 0,
      "accountHolderName": "Case H. Mitchell",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "accountNumber": "23198765",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "HSBC UK BANK PLC",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB",
        "type": "business"
      },
      "branchCode": "Taunton Branch"
    },
    {
      "payoutInstrumentReference": "MyPayoutInstrument2",
      "payoutInstrumentId": "parKsh3dSA_VRckwEDRHLzOR0",
      "payoutInstrumentType": "bankAccount",
      "currency": "EUR",
      "dateTimeCreated": "2025-04-16T20:46:26.235Z",
      "version": 0,
      "accountHolderName": "Case H. Mitchell",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "accountNumber": "2319876543210",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "Metro Bank",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB",
        "type": "business"
      },
      "branchCode": "Barclays Branch"
    }
  ]
}

Update a party

Request

Path
partyIdstring= 25 characters^par[a-zA-Z0-9-_]*0$required

A unique identifier for the party generated by us. This is sent in the response of your party creation call.

Headers
WP-Api-Versionstring(date)required

The API version.

Example: 2025-01-01
Bodyapplication/jsonrequired
One of:

A party represents the overall party record of your beneficiary (seller, vendor, provider). You can use this to store information about the party, to perform either an identity verification checks, a split payment, or a payout.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 36 ] characters[a-zA-Z0-9- ]*required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
partyReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this party, must be unique within an entity.

Example: "Hosaka27384910"
partyTypestringrequired

The type of this party.

beneficiary - the person or business that will receive funds.

payer - a transmitter of funds to a third party.

Enum"beneficiary""payer"
typestringrequired

What the party represents:

person - an individual

soleTrader - a single person enterprise

company - a corporation or partnership with multiple owners

Enum"company""person""soleTrader"
emailstring

An email address for this party.

phonesArray of objects

A list of phone numbers associated with this party.

prefixstring^[0-9]{1,3}$required

The dialing prefix for the phone number.

Example: "44"
numberstring[0-9]{1,20}required

The phone number, without dashes.

Example: "4281234"
identityDocumentsArray of objects

A list of identity documents for this party.

typestringrequired

The type of the identity document.

Enum"passport""nationalId""driverLicence""workPermit""employmentPass""studentPass""permanentResidentCard""companyRegistrationNumber""companyVATNumber""citizenshipCard"
numberstringnon-emptyrequired
issuingInstitutionstring

The name of the institution that issued this document.

Example: "State Department"
issuingCountrystringnon-emptyrequired
Example: "JP"
validFromstring

The ISO 8601 date since when this document is valid from.

Example: "2023-11-22"
validTostring

The ISO 8601 date until which this document is valid to.

Example: "2023-11-22"
balanceAccountsArray of objects

A list of balance accounts that have been set up for this party.

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
overallAccountStatusstring

The overallStatus provides an complete view of the parties identityVerificationState.

payoutInstrumentsArray of objects
payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

An ID generated by us to identify a payout instrument. You receive this in the response after successfully creating a payout instrument.

Example: "parOk0YlPtQogrqQdz7_fKXs0"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject

Object containing details about the address.

branchCodestring
performIdentityVerificationbooleanwrite-only
companyDetailsobjectrequired

Object containing details about a company. Required for company.

merchantCategoryCodestring= 4 characters^\d{4}$

A 4-digit code to represent the merchant category. Only provide this where typeCode is soleTrader or company.

Example: "5411"
merchantCategoryCodeDescriptionstring[ 1 .. 255 ] characters

A description to describe the merchant category code. Only provide this where typeCode is soleTrader or company.

Example: "Grocery Stores"
websitestring

The URL of the merchant's website.

Example: "https://example.com/"
legalNamestring[ 2 .. 140 ] characters^(?: *[\p{L}\p{N}+&\/\-.()])*+(?: *[\p{L}\p{N...required

The legal name of the company.

Example: "Tessier-Ashpool Systems Ltd."
tradingNamestring[ 2 .. 140 ] characters^(?: *[\p{L}\p{N}+&\/\-.()])*+(?: *[\p{L}\p{N...

The trading common name of the company.

Example: "TASynth.com"
registrationNumberstring[ 1 .. 15 ] characters[a-zA-Z0-9-]*required

The registration number for the company. What should be supplied in this field may differ by country, for instance in the United States it will be a Tax ID. Number (TIN).

Example: "7564389201"
vatNumberstring[ 1 .. 15 ] characters[a-zA-Z0-9-]*required

The Value Added Tax (VAT) number of the company.

Example: "JP987654321"
companyTypestring[ 1 .. 50 ] characters

A description of the type of company.

Example: "Public Limited"
dateOfIncorporationstring

The incorporation date for the company.

Example: "1977-07-04"
legalAddressobjectrequired

The legal address of this company.

tradingAddressobject

The trading address of this company.

customerReferencestring[ 1 .. 255 ] characters

Unique reference provided by the payee. Only required for certain payout destinations.

Example: "7564389201"
countryOfIncorporationstring
Example: "GB"
beneficialOwnersArray of objects
beneficialOwnerReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this beneficial owner, must be unique within an entity.

Example: "Hosaka27384910"
personalDetailsobjectrequired
relationshipToBusinessobjectrequired
emailstring
phonesArray of objects
identityDocumentsArray of objects
application/json

Update a party for a person

{
  "merchant": {
    "entity": "default"
  },
  "partyReference": "8X87XwQ7Fv",
  "partyType": "beneficiary",
  "type": "person",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "residentialStatus": "resident",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "2025 Kingsbury Court",
      "address2": "Unit 42",
      "type": "home",
      "city": "Manchester",
      "countryCode": "GB",
      "postalCode": "M1 1AA"
    }
  },
  "email": "case.mitchell@example.com",
  "phones": [
    {
      "number": "02079461234",
      "prefix": "44"
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "NEO456789",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2022-08-01",
      "validTo": "2032-08-01"
    },
    {
      "type": "nationalId",
      "number": "ZAIBATSU-00792",
      "issuingInstitution": "Zaibatsu Holding HR Dept.",
      "issuingCountry": "GB",
      "validFrom": "2025-01-01",
      "validTo": "2030-12-31"
    }
  ]
}

Responses

OK

Bodyapplication/json
One of:

A party represents the overall party record of your beneficiary (seller, vendor, provider). You can use this to store information about the party, to perform either an identity verification checks, a split payment, or a payout.

identityVerificationStatestringread-only
Enum"verified""notVerified""pending""rejected""notApplicable""started""startedAction""pendingStepUpAction""pendingManualReview"
identityVerificationMethodstringread-only
Enum"merchantCompliant""identityVerificationService"
identityVerificationDatestring(date)read-only

A valid date as YYYY-MM-DD

Example: "2033-11-22"
urlstringread-only

The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 36 ] characters[a-zA-Z0-9- ]*required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
partyReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this party, must be unique within an entity.

Example: "Hosaka27384910"
partyTypestringrequired

The type of this party.

beneficiary - the person or business that will receive funds.

payer - a transmitter of funds to a third party.

Enum"beneficiary""payer"
typestringrequired

What the party represents:

person - an individual

soleTrader - a single person enterprise

company - a corporation or partnership with multiple owners

Enum"company""person""soleTrader"
partyIdstringread-only

A unique identifier for the party generated by us.

emailstring

An email address for this party.

phonesArray of objects

A list of phone numbers associated with this party.

prefixstring^[0-9]{1,3}$required

The dialing prefix for the phone number.

Example: "44"
numberstring[0-9]{1,20}required

The phone number, without dashes.

Example: "4281234"
identityDocumentsArray of objects

A list of identity documents for this party.

typestringrequired

The type of the identity document.

Enum"passport""nationalId""driverLicence""workPermit""employmentPass""studentPass""permanentResidentCard""companyRegistrationNumber""companyVATNumber""citizenshipCard"
numberstringnon-emptyrequired
issuingInstitutionstring

The name of the institution that issued this document.

Example: "State Department"
issuingCountrystringnon-emptyrequired
Example: "JP"
validFromstring

The ISO 8601 date since when this document is valid from.

Example: "2023-11-22"
validTostring

The ISO 8601 date until which this document is valid to.

Example: "2023-11-22"
balanceAccountsArray of objects

A list of balance accounts that have been set up for this party.

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
balanceAccountIdstringread-only

Unique ID created by us to identify a balance account. This sent in the response after balanceAccount creation.

dateTimeCreatedstringread-only

The date and time that the balance account was created, as an ISO 8601 zoned date time.

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the balance account was last updated, as an ISO 8601 zoned date time.

Example: "2025-01-25T02:43:499.202Z"
versioninteger(int32)read-only
overallAccountStatusstring

The overallStatus provides an complete view of the parties identityVerificationState.

dateTimeCreatedstringread-only

The date and time that the party was created, as an ISO 8601 zoned date time

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the party was last updated, as an ISO 8601 zoned date time

Example: "2025-01-25T14:57:012.302Z"
versioninteger(int32)read-only
payoutInstrumentsArray of objects
payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

An ID generated by us to identify a payout instrument. You receive this in the response after successfully creating a payout instrument.

Example: "parOk0YlPtQogrqQdz7_fKXs0"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
dateTimeCreatedstringread-only

The date and time the payoutInstrument was created, as an ISO 8601 zoned date time.

dateTimeUpdatedstringread-only

The date and time the payoutInstrument was updated, as an ISO 8601 zoned date time.

versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject

Object containing details about the address.

branchCodestring
personalDetailsobjectrequired
titlestringrequired

The title for this person/soleTrader.

Enum"Mr""Mrs""Miss""Ms""Dr""Mx""Misc"
Example: "Mr"
firstNamestring[ 2 .. 35 ] characters^[\p{L}\-.,'()&]{2,}$required

The person's/soleTrader's first name.

Example: "Case"
middleNamestring[ 1 .. 35 ] characters^(?:\p{L}\.?)*+$required

The person's/soleTrader's middle name or initial.

Example: "Henry"
lastNamestring[ 2 .. 35 ] characters^(?:[\p{L}\-.,'()&]{2,} *)*+$required

The person's/soleTrader's last name.

Example: "Mitchell"
dateOfBirthstring

The date the person/soleTrader was born.

Example: "1983-10-12"
addressobjectrequired

The address of the person/soleTrader.

residentialStatusstring

The residential status of the person/soleTrader.

Enum"resident""nonResident""other"
customerReferencestring[ 1 .. 255 ] characters

Unique reference provided by the payee. Only required for certain payout destinations.

Example: "7564389201"
nationalitystring

The nationality of the person/soleTrader.

currentAddressLessThanThreeYearsboolean
previousHomeAddressobject

The previous home address of the person/soleTrader.

websitestring

The URL of the merchant's website.

Example: "https://example.com/"
Response
application/json

Update party of a person (orchestrated)

{
  "identityVerificationState": "notVerified",
  "identityVerificationMethod": "identityVerificationService",
  "merchant": {
    "entity": "default"
  },
  "partyReference": "Lela300",
  "partyType": "beneficiary",
  "type": "person",
  "partyId": "par4733xO8y2YI9HSOTG-kba0",
  "personalDetails": {
    "title": "Mr",
    "firstName": "Case",
    "middleName": "Henry",
    "lastName": "Mitchell",
    "dateOfBirth": "1983-10-12",
    "address": {
      "address1": "2025 Kingsbury Court",
      "address2": "Unit 42",
      "city": "Manchester",
      "countryCode": "GB",
      "postalCode": "M1 1AA",
      "type": "home"
    },
    "residentialStatus": "resident",
    "currentAddressLessThanThreeYears": false
  },
  "email": "case.mitchell@example.com",
  "phones": [
    {
      "prefix": "44",
      "number": "02079461234"
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "NEO456789",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2022-08-01",
      "validTo": "2032-08-01"
    },
    {
      "type": "nationalId",
      "number": "ZAIBATSU-00792",
      "issuingInstitution": "Zaibatsu Holding HR Dept.",
      "issuingCountry": "GB",
      "validFrom": "2025-01-01",
      "validTo": "2030-12-31"
    }
  ],
  "balanceAccounts": [
    {
      "currency": "GBP",
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "scheduledPayoutDay": "tuesday",
      "balanceAccountId": "parXRSh-RDDLU5NyGZpQhyNb0",
      "dateTimeCreated": "2025-04-21T20:11:08.699Z",
      "version": 0
    },
    {
      "currency": "EUR",
      "payoutInstrumentReference": "MyPayoutInstrument2",
      "scheduledPayoutDay": "friday",
      "balanceAccountId": "parBTwBk8J3s3nhgbo1vNyvJ0",
      "dateTimeCreated": "2025-04-21T20:11:12.991Z",
      "version": 0
    }
  ],
  "dateTimeCreated": "2025-04-21T20:11:08.695Z",
  "dateTimeUpdated": "2025-04-21T20:11:15.341Z",
  "version": 1,
  "payoutInstruments": [
    {
      "payoutInstrumentReference": "MyPayoutInstrument1",
      "payoutInstrumentId": "paru47L8iaV-cm7doWxO7oWm0",
      "payoutInstrumentType": "bankAccount",
      "currency": "GBP",
      "dateTimeCreated": "2025-04-21T20:11:08.698Z",
      "version": 0,
      "accountHolderName": "Case H. Mitchell",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "accountNumber": "23198765",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "HSBC UK BANK PLC",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB",
        "type": "business"
      },
      "branchCode": "Taunton Branch"
    },
    {
      "payoutInstrumentReference": "MyPayoutInstrument2",
      "payoutInstrumentId": "parbQkpoZT3adRASZB9Zp9e-0",
      "payoutInstrumentType": "bankAccount",
      "currency": "EUR",
      "dateTimeCreated": "2025-04-21T20:11:11.251Z",
      "version": 0,
      "accountHolderName": "Case H. Mitchell",
      "swiftBic": "BUKBGB22",
      "bankCode": "045110",
      "accountNumber": "2319876543210",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "Metro Bank",
      "address": {
        "address1": "17 Neo-London Financial Tower",
        "address2": "Suite 1288",
        "city": "London",
        "countryCode": "GB",
        "postalCode": "EC1A 1BB",
        "type": "business"
      },
      "branchCode": "Barclays Branch"
    }
  ]
}

Payout instruments

Create and maintain payout instruments.

Operations

Balance accounts

Create and maintain balance accounts.

Operations

Beneficial owners

Create and maintain beneficial owners.

Operations

Identity Verification

Enable Identity Verification check on a party.

Operations