Skip to content

New service | Last updated: 14 May 2025

Important

This documentation is for preview purposes only.

Manage a party

There are two ways to create a party:

  • orchestrated - add all details in one call
  • modular - create a basic party and add details like payout instruments, balance accounts or beneficial owners later

Additionally, at any point when creating a party, you can request an identity verification check to be performed.

Create a party

POST https://access.worldpay.com/parties



Orchestrated party creation

Add all the details of a party in one API call. Add personal or company details, payout instruments, balance accounts, and beneficial owners (companies only).

Request an identity verification check, to be performed on that party, in the same call.

Request/response example

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
}

You can see the full schema in our API reference.

Browse parties

Retrieve and explore information about all parties (persons, sole traders or companies) that you have previously created. This endpoint is essential for viewing all existing parties and their status and filtering parties based on their type and status. Results are paginated.

Browse previously created parties by sending a request to:

GET https://access.worldpay.com/parties

optionally add filtering parameters:

  • active - return parties that are active (true or false)

  • type - type of parties to return (person, soleTrader or company)

or pagination options:

  • page - positive whole number indicating which page of the selected parties to return. Greater than 0

  • size - number of items listed per page

You can see the full schema in our API reference.

View a party

View information of a party, previously created, using the partyId received in your party creation response.

GET https://access.worldpay.com/parties/{partyId}

Request/response example

No request payload

You can see the full schema in our API reference.

Modify a party

You can modify certain party information.

PUT https://access.worldpay.com/parties/{partyId}

Recommendation

We suggest fetching party information with a GET request and providing all the fields to our PUT endpoint, including changes for fields that need updating.

Request/response example

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",
      "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"
    }
  ]
}

You can view the full schema in our API reference.

Deactivate a party

Parties are created as active by default. You can deactivate an active party by using the partyId on our dedicated endpoint:

POST https://access.worldpay.com/parties/{partyId}/deactivation

You must provide the deactivationReason (possible values: "partyDormant", "partyClosed", "partySanctioned") and optionally dispositionOfFunds (default: "payoutToParty").

Request/response example

No request payload

In the response, you receive a dateTimeDeactivated field with the date and time when party was deactivated.

You can see the full schema in our API reference.

Reactivate a party

Parties are created as active by default. You can reactivate a previously deactivated party by using the partyId on our dedicated endpoint:

POST https://access.worldpay.com/parties/{partyId}/activation

And setting the active flag to "true".

Request/response example

No request payload

In the response, you receive a dateTimeActivated field with the date and time when party was activated.

You can see the full schema in our API reference.

Delete a party

Coming soon

In this current version you will only be able to mark a party as inactive.

Next steps

Add a payout instrument
Manage beneficial owners
Add balance accounts or
Verify a party