Documentation
Documentation
https://docs.worldpay.com/access/products/payments
Documentation
https://docs.worldpay.com/access/apis
OpenAPI Specification
openapi: 3.0.1
info:
title: 3DS 3DS actions Parties API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Parties
description: Create and maintain parties.
paths:
/parties:
post:
tags:
- Parties
summary: Create a party
operationId: createAccount
parameters:
- 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:
oneOf:
- $ref: '#/components/schemas/Company'
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/SoleTrader'
examples:
Create a party for a person (modular):
$ref: '#/components/examples/Create_Party_Person_modular'
Create a party for a person with previous home address (orchestrated):
$ref: '#/components/examples/Create_Party_Person_orchestrated'
Create a party for a sole trader with trading address (modular):
$ref: '#/components/examples/Create_Party_SoleTrader_with_TradingAddress_modular'
Create a party for a sole trader without trading address (orchestrated):
$ref: '#/components/examples/Create_Party_SoleTrader_without_TradingAddress_orchestrated'
Create a party for a company with trading address different than legal address (orchestrated):
$ref: '#/components/examples/Create_Party_Company_with_TradingAddress_orchestrated'
Create a party for a company without trading address (modular):
$ref: '#/components/examples/Create_Party_Company_without_TradingAddress_modular'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
oneOf:
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/SoleTrader'
- $ref: '#/components/schemas/Company'
examples:
Create a party for a person (modular):
$ref: '#/components/examples/Person_created_201_modular'
Create a party for a person with previous home address (orchestrated):
$ref: '#/components/examples/Person_created_201_orchestrated'
Create a party for a sole trader with trading address (modular):
$ref: '#/components/examples/SoleTrader_with_TradingAddress_created_201_modular'
Create a party for a sole trader without trading address (orchestrated):
$ref: '#/components/examples/SoleTrader_without_TradingAddress_created_201_orchestrated'
Create a party for a company with tradingAddress different than legalAddress (orchestrated):
$ref: '#/components/examples/Company_with_TradingAddress_created_201_orchestrated'
Create a party for a company without trading address (modular):
$ref: '#/components/examples/Company_without_TradingAddress_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'
get:
tags:
- Parties
summary: Browse parties
description: Browse parties and optionally filtered by criteria. Results are paginated.
operationId: browseParties
parameters:
- name: page
in: query
description: Positive whole number indicating which page of the selected parties to return. Greater than 0.
required: false
schema:
type: integer
format: int32
default: 0
description: Positive whole number indicating which page of the selected parties to return. Greater than 0.
example: 5
minimum: 0
example: 5
- name: size
in: query
description: Number of items listed per page.
required: false
schema:
type: integer
format: int32
default: 10
description: Number of items listed per page.
example: 10
maximum: 100
minimum: 1
example: 10
- name: entity
in: query
description: Entity or entities to filter parties by.
required: false
schema:
type: array
description: entity or entities to filter parties by
items:
type: string
description: entity or entities to filter parties by
example: Entity123
example:
- Entity123
- Entity456
- name: active
in: query
description: Returns parties that are active when set to `true`.
required: false
schema:
type: boolean
description: Return parties that are active when set to `true`.
example: true
- name: type
in: query
description: Type of parties to return.
required: false
schema:
type: string
enum:
- person
- soleTrader
- company
description: Type of parties to return.
example:
- soleTrader
- company
- 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/BrowsePartiesPage'
examples:
Browse parties:
$ref: '#/components/examples/Browse_Parties_200'
'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'
/parties/{partyId}:
get:
tags:
- Parties
summary: View a party
description: Retrieve information about a party.
operationId: partyQuery
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$
example: parV1StGXR8_Z5jdHi6B-myF0
- 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:
type: object
oneOf:
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/SoleTrader'
- $ref: '#/components/schemas/Company'
title: party
examples:
'Get a party for a person ':
$ref: '#/components/examples/Get_Party_Person_200_orchestrated'
Get a party for a sole trader:
$ref: '#/components/examples/Get_Party_SoleTrader_200_orchestrated'
Get a party for a company:
$ref: '#/components/examples/Get_Party_Company_200_orchestrated'
'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:
- Parties
summary: Update a party
operationId: updateParty
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:
oneOf:
- $ref: '#/components/schemas/Company'
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/SoleTrader'
examples:
Update a party for a person:
$ref: '#/components/examples/Update_Party_Person_orchestrated'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
oneOf:
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/SoleTrader'
- $ref: '#/components/schemas/Company'
title: party
examples:
Update Party:
$ref: '#/components/examples/Update_Party_Person_200_orchestrated'
'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}/deactivation:
post:
tags:
- Parties
summary: Deactivate a party
operationId: deactivateParty
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/DeactivateParty'
examples:
Deactivate a party:
$ref: '#/components/examples/Deactivate_Party_Person_modular'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeactivateParty'
examples:
Deactivate a party:
$ref: '#/components/examples/Deactivate_Party_Person_200_modular'
'400':
description: Bad Request
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal error occurred:
$ref: '#/components/examples/500'
/parties/{partyId}/activation:
post:
tags:
- Parties
summary: Reactivate a party
operationId: reactivateParty
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/ReactivateParty'
examples:
Reactivate a party:
$ref: '#/components/examples/Reactivate_Party_Person_modular'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReactivateParty'
examples:
Reactivate a party:
$ref: '#/components/examples/Reactivate_Party_Person_200_modular'
'400':
description: Bad Request
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal error occurred:
$ref: '#/components/examples/500'
components:
examples:
Company_without_TradingAddress_created_201_modular:
description: party for a company without trading address (modular)
value:
identityVerificationState: notVerified
identityVerificationMethod: identityVerificationService
merchant:
entity: default
partyReference: Genesis829
partyType: beneficiary
type: company
partyId: par1Gya_pV7rRYUMI3Ep_ssX0
companyDetails:
merchantCategoryCode: '5734'
merchantCategoryCodeDescription: Computer Software Stores
isTradingAddressSameAsPrimary: true
website: https://www.example.com
legalName: Tessier-Ashpool Systems Ltd.
tradingName: Example.co.uk
registrationNumber: '7564389201'
taxIdentifier: GB-987654321
companyType: publicLimitedCompany
dateOfIncorporation: '1977-07-04'
legalAddress:
address1: 7 Straylight Complex
address2: Corporate District, Level 99
city: London
countryCode: GB
postalCode: EC1A 1BB
type: business
customerReference: CustRefZA98765
email: info@example.com
phones:
- prefix: '81'
number: '8475932'
identityDocuments: []
balanceAccounts: []
dateTimeCreated: '2025-04-24T18:05:40.908Z'
version: 0
active: true
dateTimeActivated: '2025-04-24T18:05:40.908Z'
payoutInstruments: []
beneficialOwners: []
Create_Party_Person_modular:
value:
merchant:
entity: default
partyReference: 5htNU0XQ7V
partyType: beneficiary
type: person
personalDetails:
title: Mr
firstName: Case
middleName: Henry
lastName: Mitchell
alias: Henry Smith
socialSecurityNumber: 333-75-6666
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'
Deactivate_Party_Person_modular:
value:
deactivationReason: partyDormant
dispositionOfFunds: payoutToParty
Create_Party_Company_with_TradingAddress_orchestrated:
value:
merchant:
entity: default
partyReference: BGy1nSxvSw
partyType: beneficiary
type: company
companyDetails:
legalName: Tessier-Ashpool Systems Ltd.
tradingName: Example.co.uk
customerReference: CustRefZA98765
registrationNumber: '7564389201'
taxIdentifier: GB-987654321
companyType: publicLimitedCompany
dateOfIncorporation: '1977-07-04'
merchantCategoryCode: '5734'
merchantCategoryCodeDescription: Computer Software Stores
isTradingAddressSameAsPrimary: false
website: https://www.example.com
legalAddress:
address1: 7 Straylight Complex
address2: Corporate District, Level 99
type: business
city: London
countryCode: GB
postalCode: EC1A 1BB
tradingAddress:
address1: 789 Freeside Blvd
address2: Villa Straylight
city: Manchester
countryCode: GB
postalCode: M1 1AA
type: poBox
email: info@example.com
phones:
- number: '8475932'
prefix: '81'
balanceAccounts:
- currency: GBP
- currency: EUR
scheduledPayoutDay: thursday
frequency: monthly
recurrence: third
payoutInstrumentReference: primaryBusinessAccount2
payoutInstruments:
- accountHolderName: Tessier-Ashpool Systems Ltd.
payoutInstrumentType: bankAccount
swiftBic: FSFCGB33
bankCode: '045110'
branchCode: Barclays Branch
accountNumber: '12345678'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
payoutInstrumentReference: primaryBusinessAccount2
currency: EUR
address:
address1: 3 Villa Straylight
address2: Freeside
type: business
city: London
countryCode: GB
postalCode: EC1A 1BB
beneficialOwners:
- beneficialOwnerReference: 39XaAW8hCf
personalDetails:
title: Dr
firstName: Peter
middleName: Illusionet
lastName: Riviera
alias: Peter Smith
socialSecurityNumber: 383-55-6666
residentialStatus: nonResident
dateOfBirth: '1972-03-22'
nationality: GB
address:
address1: 789 Downing Street
address2: Flat 404
city: London
type: home
countryCode: GB
postalCode: SW1A 2AA
currentAddressLessThanThreeYears: true
previousHomeAddress:
address1: 123 Oxford Street
address2: Flat 101
city: London
type: home
countryCode: GB
postalCode: W1D 1LP
relationshipToBusiness:
ownershipPercentage: 10
director: false
position: partner
identityDocuments:
- type: passport
number: B98765432
issuingInstitution: UK Passport Office
issuingCountry: GB
validFrom: '2018-05-15'
validTo: '2028-05-15'
email: peter.riviera@example.com
phones:
- number: 0205556789
prefix: '44'
- beneficialOwnerReference: A9CuJNpryM
personalDetails:
title: Ms
firstName: Molly
middleName: Puppet
lastName: Millions
alias: Molly Smith
socialSecurityNumber: 313-55-6666
residentialStatus: resident
dateOfBirth: '1980-05-15'
nationality: GB
address:
address1: 456 Sprawl Street
address2: Flat 101
city: Burbank
countryCode: GB
postalCode: RM1 4PL
currentAddressLessThanThreeYears: true
previousHomeAddress:
address1: 789 Night City Blvd
address2: Flat 303
city: Night City
countryCode: GB
postalCode: RM2 3PL
relationshipToBusiness:
ownershipPercentage: 25
director: false
position: officeManager
identityDocuments:
- type: passport
number: A12345678
issuingInstitution: UK Passport Office
issuingCountry: GB
validFrom: '2020-01-01'
validTo: '2030-01-01'
email: molly.millions@example.com
phones:
- number: 02079461234
prefix: '44'
Reactivate_Party_Person_modular:
value:
active: true
Create_Party_Company_without_TradingAddress_modular:
value:
merchant:
entity: default
partyReference: BGy1nSxvSw
partyType: beneficiary
type: company
companyDetails:
legalName: Tessier-Ashpool Systems Ltd.
tradingName: Example.co.uk
customerReference: CustRefZA98765
registrationNumber: '7564389201'
taxIdentifier: GB-987654321
companyType: publicLimitedCompany
dateOfIncorporation: '1977-07-04'
merchantCategoryCode: '5734'
merchantCategoryCodeDescription: Computer Software Stores
isTradingAddressSameAsPrimary: true
website: https://www.example.com
legalAddress:
address1: 7 Straylight Complex
address2: Corporate District, Level 99
type: business
city: London
countryCode: GB
postalCode: EC1A 1BB
email: info@example.com
phones:
- number: '8475932'
prefix: '81'
Create_Party_Person_orchestrated:
value:
merchant:
entity: default
partyReference: VuzvLew4y7
partyType: beneficiary
type: person
personalDetails:
title: Mr
firstName: Case
middleName: Henry
lastName: Mitchell
alias: Case Smith
socialSecurityNumber: 333-55-9666
residentialStatus: resident
dateOfBirth: '1983-10-12'
currentAddressLessThanThreeYears: true
address:
address1: 1847 Kingsbury Court
address2: Unit 42
type: home
city: Manchester
countryCode: GB
postalCode: M1 1AA
previousHomeAddress:
address1: 1847 Morrison Court
address2: Unit 55
type: home
city: Manchester
countryCode: GB
postalCode: M1 1AA
email: case.mitchell@example.com
phones:
- number: 02079461234
prefix: '44'
balanceAccounts:
- currency: GBP
scheduledPayoutDay: thursday
frequency: weekly
payoutInstrumentReference: personalCheckingAccount
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: personalCheckingAccount
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
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
Person_created_201_modular:
description: Create a party for a person (modular)
value:
identityVerificationState: notVerified
identityVerificationMethod: identityVerificationService
merchant:
entity: default
partyReference: Frank118
partyType: beneficiary
type: person
partyId: parpI1tAL2bK8Lb-52Rfblg30
personalDetails:
title: Mr
firstName: Case
middleName: Henry
lastName: Mitchell
alias: Case Smith
socialSecurityNumber: 353-55-6666
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: []
balanceAccounts: []
dateTimeCreated: '2025-04-07T20:42:17.292Z'
version: 0
active: true
dateTimeActivated: '2025-04-07T20:42:17.292Z'
payoutInstruments: []
Update_Party_Person_orchestrated:
value:
merchant:
entity: default
partyReference: 8X87XwQ7Fv
partyType: beneficiary
type: person
personalDetails:
title: Mr
firstName: Case
middleName: Henry
lastName: Mitchell
alias: Case Smith
socialSecurityNumber: 393-55-6666
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'
'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
Reactivate_Party_Person_200_modular:
description: Activate an deactivated party (modular)
value:
active: true
dateTimeActivated: '2025-07-29T17:34:01.621Z'
Browse_Parties_200:
description: Browse parties
value:
parties:
- identityVerificationState: notVerified
identityVerificationMethod: identityVerificationService
merchant:
entity: default
partyReference: ts6SfP8eNv
partyType: beneficiary
type: person
partyId: parJnf1XbmhV6j2cizaFQ54L0
email: zH5O.V20XrO71@yWPtULl.cl4
phones:
- prefix: '44'
number: km86YWLfjyL
identityDocuments:
- type: passport
number: zuggHJuTi
issuingInstitution: UK Passport Office
issuingCountry: GB
validFrom: '1901-03-20'
validTo: '1931-07-31'
- type: nationalId
number: f1wlKPlz-8mXmh
issuingInstitution: Zaibatsu Holding HR Dept.
issuingCo
# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-parties-api-openapi.yml