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.

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

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