Skip to content

New service | Last updated: 14 May 2025

Important

This documentation is for preview purposes only.

Add payout instrument

A payout instrument represents a single reference to store the details for a payout to your party.

Note

We currently only support bank account details.
Cards and e-wallets are coming soon.


A payoutInstrument is created in two ways. Either during or after the creation of a party. This guide focuses on the creation of a payout instrument after the party creation call.

To add a payout instrument during orchestrated party creation call, you can use the https://access.worldpay.com/parties endpoint.

Create a payout instrument

After a party is created, you can add a payoutInstrument to it.


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


Note

We verify the details sent against a template for a particular country-currency pair. You can view the specific country requirements in our coverage guide.

Request/response example

application/json

Create a payoutInstrument for a party of person (modular)

{
  "accountHolderName": "Case H. Mitchell",
  "payoutInstrumentType": "bankAccount",
  "swiftBic": "BUKBGB22",
  "bankCode": "045110",
  "branchCode": "Barclays Branch",
  "accountNumber": "23198765",
  "accountType": "checking",
  "iban": "GB892019000123456789",
  "bankName": "Metro Bank",
  "payoutInstrumentReference": "MyPayoutInstrument1",
  "currency": "EUR",
  "address": {
    "address1": "17 Neo-London Financial Tower",
    "address2": "Suite 1288",
    "type": "business",
    "city": "London",
    "countryCode": "GB",
    "postalCode": "EC1A 1BB"
  }
}

Schema

payoutInstrumentReferencestring[ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$

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: "MyPayoutInstrument1"
payoutInstrumentIdstring= 25 characters^par[a-zA-Z0-9-_]*0$

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"
payoutInstrumentTypestring

The type of the payout instrument.

Enum"bankAccount""wallet""card"
currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
dateTimeCreatedstringread-only

The date and time the payoutInstrument was created, as an ISO 8601 zoned date time.

dateTimeUpdatedstringread-only

The date and time the payoutInstrument was updated, as an ISO 8601 zoned date time.

versioninteger(int32)
accountHolderNamestring
swiftBicstring
bankCodestring

The bankCode must be exactly 6 digits.

Example: "184758"
accountNumberstring
accountTypestring
Enum"checking""savings""moneyMarket""certificateOfDeposit""vista""other"
ibanstring
bankNamestring
addressobject(Address)

Object containing details about the address.

branchCodestring

View a payout instrument

View information of a payout instrument, previously created, using the payoutInstrumentId received in your payout instrument creation response.

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


Request/response example

No request payload

See full schema to view your payout instrument.

Modify a payout instrument

You can modify certain payout instrument information previously created. Data entered will again be verified and saved if verification is successful.

PUT https://access.worldpay.com/parties/parTH82wexHglhnBbzd6iJ7P0/payoutInstrument/{payoutInstrumentId}

Request/response example

application/json

Update payout instrument for existing party of a company (modular)

{
  "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": "MyPayoutInstrument1",
  "currency": "EUR",
  "address": {
    "address1": "9105 Villa Straylight",
    "address2": "Freeside",
    "type": "business",
    "city": "York",
    "state": "NA",
    "countryCode": "GB",
    "postalCode": "L502 MK54"
  }
}

See full schema to modify your payout instrument.

Delete a payout instrument

Coming soon

Next steps

Manage beneficial owners
Add balance accounts or
Verify a party