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": "2319876543210",
      "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
}
Response
application/json

Party for a person (orchestrated)

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

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

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

Update party of a person (orchestrated)

{
  "identityVerificationState": "pending",
  "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": "2319876543210",
      "accountType": "checking",
      "iban": "GB892019000123456789",
      "bankName": "HSBC UK BANK PLC",
      "address": {
        "address1": "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"
    }
  ]
}

You can view 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