Worldpay Payout instruments API
Create and maintain payout instruments.
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 Payout instruments 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: Payout instruments
description: Create and maintain payout instruments.
paths:
/parties/{partyId}/payoutInstruments:
post:
tags:
- Payout instruments
summary: Create a payout instrument
operationId: createPayoutInstruments
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
- 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/BankAccount'
examples:
Create a payout instrument for existing party of person (modular):
$ref: '#/components/examples/Create_PayoutInstrument_Person_modular'
Create a payout instrument for existing party of sole trader (modular):
$ref: '#/components/examples/Create_PayoutInstrument_SoleTrader_modular'
Create a payout instrument for existing party of company (modular):
$ref: '#/components/examples/Create_PayoutInstrument_Company_modular'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
oneOf:
- $ref: '#/components/schemas/BankAccount'
- $ref: '#/components/schemas/Wallet'
- $ref: '#/components/schemas/Card'
title: payout instrument
examples:
Create a payout instrument for existing party of person (modular):
$ref: '#/components/examples/PayoutInstrument_Person_created_201_modular'
Create a payout instrument for existing party of sole Trader (modular):
$ref: '#/components/examples/PayoutInstrument_SoleTrader_created_201_modular'
Create a payout instrument for existing party of company (modular):
$ref: '#/components/examples/PayoutInstrument_Company_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'
/parties/{partyId}/payoutInstruments/{payoutInstrumentId}:
get:
tags:
- Payout instruments
summary: View a payout instrument
operationId: getPayoutInstrument
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: payoutInstrumentId
in: path
description: A unique identifier for the payoutInstrument generated by us. This is sent in the response of your payoutInstrument creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: par.*0$
- 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/BankAccount'
- $ref: '#/components/schemas/Wallet'
- $ref: '#/components/schemas/Card'
title: payout instrument
examples:
Get a payout instrument for existing party of person (modular):
$ref: '#/components/examples/Get_PayoutInstrument_Person_200_modular'
Get a payout instrument for existing party of sole trader (modular):
$ref: '#/components/examples/Get_PayoutInstrument_SoleTrader_200_modular'
Get a payout instrument for existing party of company (modular):
$ref: '#/components/examples/Get_PayoutInstrument_Company_200_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'
put:
tags:
- Payout instruments
summary: Update a payout instrument
operationId: updatePayoutInstruments
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: payoutInstrumentId
in: path
description: A unique identifier for the payoutInstrument generated by us. This is sent in the response of your payoutInstrument creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: par.*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/BankAccount'
examples:
Update a payout instrument for existing party of company (modular):
$ref: '#/components/examples/Update_PayoutInstrument_Company_modular'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
oneOf:
- $ref: '#/components/schemas/BankAccount'
- $ref: '#/components/schemas/Wallet'
- $ref: '#/components/schemas/Card'
title: payout instrument
examples:
Update a payout instrument for existing party of company (modular):
$ref: '#/components/examples/Update_PayoutInstrument_Company_200_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'
components:
schemas:
Wallet:
type: object
properties:
payoutInstrumentReference:
type: string
description: '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: personalCheckingAccount
maxLength: 64
minLength: 3
pattern: ^[A-Za-z0-9\-_ ]*$
payoutInstrumentId:
type: string
description: 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
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
payoutInstrumentType:
type: string
description: The type of the payout instrument.
enum:
- bankAccount
- wallet
- card
currency:
type: string
description: The currency in [ISO 4217 currency format](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
maxLength: 3
minLength: 3
pattern: ^[A-Z]*$
dateTimeCreated:
type: string
description: The date and time the `payoutInstrument` was created, as an ISO 8601 zoned date time.
readOnly: true
dateTimeUpdated:
type: string
description: The date and time the `payoutInstrument` was updated, as an ISO 8601 zoned date time.
readOnly: true
version:
type: integer
format: int32
required:
- currency
ErrorResponseItem:
type: object
properties:
errorName:
type: string
message:
type: string
path:
type: string
jsonPath:
type: string
queryParameter:
type: string
pathParameter:
type: string
BankAccount:
type: object
properties:
payoutInstrumentReference:
type: string
description: '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: primaryBusinessAccount
maxLength: 64
minLength: 3
pattern: ^[A-Za-z0-9\-_ ]*$
payoutInstrumentId:
type: string
description: 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
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
payoutInstrumentType:
type: string
description: The type of the payout instrument.
enum:
- bankAccount
- wallet
- card
currency:
type: string
description: The currency in [ISO 4217 currency format](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
maxLength: 3
minLength: 3
pattern: ^[A-Z]*$
dateTimeCreated:
type: string
description: The date and time the `payoutInstrument` was created, as an ISO 8601 zoned date time.
readOnly: true
dateTimeUpdated:
type: string
description: The date and time the `payoutInstrument` was updated, as an ISO 8601 zoned date time.
readOnly: true
version:
type: integer
format: int32
accountHolderName:
type: string
swiftBic:
type: string
bankCode:
type: string
description: The bankCode must be exactly 6 digits.
example: '184758'
accountNumber:
type: string
accountType:
type: string
enum:
- checking
- savings
- moneyMarket
- certificateOfDeposit
- vista
- other
iban:
type: string
bankName:
type: string
address:
$ref: '#/components/schemas/Address'
branchCode:
type: string
required:
- currency
ErrorResponse:
type: object
properties:
errorName:
type: string
description: An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
example: bodyDoesNotMatchSchema
message:
type: string
description: A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.
validationErrors:
type: array
items:
$ref: '#/components/schemas/ErrorResponseItem'
pathParameter:
type: string
queryParameter:
type: string
jsonPath:
type: string
readOnly: true
title: Error Response
Card:
type: object
properties:
payoutInstrumentReference:
type: string
description: '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: primaryBusinessAccount
maxLength: 64
minLength: 3
pattern: ^[A-Za-z0-9\-_ ]*$
payoutInstrumentId:
type: string
description: 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
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
payoutInstrumentType:
type: string
description: The type of the payout instrument.
enum:
- bankAccount
- wallet
- card
currency:
type: string
description: The currency in [ISO 4217 currency format](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
maxLength: 3
minLength: 3
pattern: ^[A-Z]*$
dateTimeCreated:
type: string
description: The date and time the `payoutInstrument` was created, as an ISO 8601 zoned date time.
readOnly: true
dateTimeUpdated:
type: string
description: The date and time the `payoutInstrument` was updated, as an ISO 8601 zoned date time.
readOnly: true
version:
type: integer
format: int32
id:
$ref: '#/components/schemas/NanoId'
token:
type: string
required:
- currency
NanoId:
type: object
properties:
nanoPrefix:
type: string
nanoId:
type: string
Address:
type: object
description: Object containing details about the address.
properties:
address1:
type: string
description: 'The address.
Must consist of at least two letters, two words, and one number.'
example: 1847 Kingsbury Court
maxLength: 35
minLength: 2
address2:
type: string
description: Line two of the address.
example: Unit 42
maxLength: 35
minLength: 2
city:
type: string
description: The city of this address.
example: London
maxLength: 35
minLength: 1
state:
type: string
description: The state of this address.
example: Greater London
maxLength: 35
minLength: 2
countryCode:
type: string
description: The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
example: GB
maxLength: 2
minLength: 2
postalCode:
type: string
description: The postal code of this address.
example: NW9 0RR
maxLength: 20
minLength: 1
type:
type: string
description: Identifies the type of this address.
enum:
- home
- business
- poBox
- other
example: home
required:
- address1
- city
- countryCode
examples:
Get_PayoutInstrument_Company_200_modular:
description: Get a payoutInstrument for a party of company (modular)
value:
payoutInstrumentReference: primaryBusinessAccount
payoutInstrumentId: parRI-eYCnF_sOAK59-38hUF0
payoutInstrumentType: bankAccount
currency: USD
dateTimeCreated: '2025-04-24T18:22:16.393Z'
dateTimeUpdated: '2025-04-25T18:22:16.393Z'
version: 1
accountHolderName: Tessier-Ashpool Systems Ltd.
swiftBic: FSFCUS33
bankCode: '045110'
accountNumber: '22765819'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
address:
address1: 3 Villa Straylight
address2: Freeside
city: York
state: NA
countryCode: GB
postalCode: L502 MK54
type: business
branchCode: Muswell Hill Branch
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
'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
PayoutInstrument_Company_created_201_modular:
description: PayoutInstrument for a company (modular)
value:
payoutInstrumentReference: primaryBusinessAccount
payoutInstrumentId: parbLmHCft8cLP8XXsay63fQ0
payoutInstrumentType: bankAccount
currency: USD
dateTimeCreated: '2025-04-24T18:05:41.525Z'
version: 0
accountHolderName: Tessier-Ashpool Systems Ltd.
swiftBic: FSFCUS33
bankCode: '045110'
accountNumber: '22765819'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
address:
address1: 3 Villa Straylight
address2: Freeside
city: York
state: NA
countryCode: GB
postalCode: L502 MK54
type: business
branchCode: Muswell Hill Branch
Create_PayoutInstrument_SoleTrader_modular:
value:
accountHolderName: Case H. Mitchell
payoutInstrumentType: bankAccount
swiftBic: BUKBGB22
bankCode: '045110'
branchCode: Barclays Branch
accountNumber: '23198765'
accountType: checking
iban: GB892019000123456789
bankName: Metro Bank
payoutInstrumentReference: primaryBusinessAccount
currency: USD
address:
address1: 17 Neo-London Financial Tower
address2: Suite 1288
type: business
city: London
countryCode: GB
postalCode: EC1A 1BB
'500':
value:
errorName: internalErrorOccurred
message: An error occurred within the service (potentially due to an interaction with a downstream service).
Get_PayoutInstrument_Person_200_modular:
description: Get a payoutInstrument for a party of person (modular)
value:
payoutInstrumentReference: personalCheckingAccount
payoutInstrumentId: parVID57-ep4PqX6J-25AkZk0
payoutInstrumentType: bankAccount
currency: EUR
dateTimeCreated: '2025-04-07T20:48:00.227Z'
version: 0
accountHolderName: Case H. Mitchell
swiftBic: BUKBGB22
bankCode: '045110'
accountNumber: '23198765'
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
PayoutInstrument_SoleTrader_created_201_modular:
description: PayoutInstrument for a soleTrader (modular)
value:
payoutInstrumentReference: primaryBusinessAccount
payoutInstrumentId: parC_x1lzotG7wnqx1_Den9E0
payoutInstrumentType: bankAccount
currency: USD
dateTimeCreated: '2025-04-07T20:42:24.759Z'
version: 0
accountHolderName: Case H. Mitchell
swiftBic: BUKBGB22
bankCode: '045110'
accountNumber: '23198765'
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_PayoutInstrument_Company_200_modular:
description: Update payout instrument for existing party of a company (modular)
value:
payoutInstrumentReference: primaryBusinessAccount
payoutInstrumentId: parWm7eF6Dfwry4EYQdpXSSB0
payoutInstrumentType: bankAccount
currency: EUR
dateTimeCreated: '2025-04-22T19:24:07.680Z'
dateTimeUpdated: '2025-04-22T19:24:11.462Z'
version: 2
accountHolderName: Tessier-Ashpool Systems Ltd.
swiftBic: FSFCUS33
bankCode: '045110'
accountNumber: '2276581'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
address:
address1: 9105 Villa Straylight
address2: Freeside
city: York
state: NA
countryCode: GB
postalCode: L502 MK54
type: business
branchCode: Muswell Hill Branch
'503':
value:
errorName: serviceUnavailable
message: Service cannot fulfil the request even though service functions witout internal errors.
Get_PayoutInstrument_SoleTrader_200_modular:
description: Get a payoutInstrument for a party of soleTrader (modular)
value:
payoutInstrumentReference: primaryBusinessAccount
payoutInstrumentId: partA3SpNddFfGPV0fYk_zI-0
payoutInstrumentType: bankAccount
currency: USD
dateTimeCreated: '2025-04-07T20:48:00.660Z'
version: 0
accountHolderName: Case H. Mitchell
swiftBic: BUKBGB22
bankCode: '045110'
accountNumber: '23198765'
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
Create_PayoutInstrument_Company_modular:
value:
accountHolderName: Tessier-Ashpool Systems Ltd.
payoutInstrumentType: bankAccount
swiftBic: FSFCUS33
bankCode: '045110'
branchCode: Muswell Hill Branch
accountNumber: '22765819'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
payoutInstrumentReference: primaryBusinessAccount
currency: USD
address:
address1: 3 Villa Straylight
address2: Freeside
type: business
city: York
state: NA
countryCode: GB
postalCode: L502 MK54
Create_PayoutInstrument_Person_modular:
value:
accountHolderName: Case H. Mitchell
payoutInstrumentType: bankAccount
swiftBic: BUKBGB22
bankCode: '045110'
branchCode: Barclays Branch
accountNumber: '23198765'
accountType: checking
iban: GB892019000123456789
bankName: Metro Bank
payoutInstrumentReference: personalCheckingAccount
currency: EUR
address:
address1: 17 Neo-London Financial Tower
address2: Suite 1288
type: business
city: London
countryCode: GB
postalCode: EC1A 1BB
Update_PayoutInstrument_Company_modular:
value:
accountHolderName: Tessier-Ashpool Systems Ltd.
payoutInstrumentType: bankAccount
swiftBic: FSFCUS33
bankCode: '045110'
branchCode: Muswell Hill Branch
accountNumber: '2276581'
accountType: savings
iban: GB33TASS12345678901234
bankName: Freeside Financial Corporation
payoutInstrumentReference: primaryBusinessAccount
currency: EUR
address:
address1: 9105 Villa Straylight
address2: Freeside
type: business
city: York
state: NA
countryCode: GB
postalCode: L502 MK54
PayoutInstrument_Person_created_201_modular:
description: PayoutInstrument for a person (modular)
value:
payoutInstrumentReference: personalCheckingAccount
payoutInstrumentId: parF4BlVTN_zIcADcyBpXK6J0
payoutInstrumentType: bankAccount
currency: EUR
dateTimeCreated: '2025-04-07T20:42:24.408Z'
version: 0
accountHolderName: Case H. Mitchell
swiftBic: BUKBGB22
bankCode: '045110'
accountNumber: '23198765'
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
securitySchemes:
BasicAuth:
type: http
scheme: basic