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.

br
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](/products/parties/create-party#orchestrated-party-creation), you can use the `https://access.worldpay-bsh.securedataplatform.com/parties` endpoint.

## Create a payout instrument

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

br
`POST` `https://access.worldpay-bsh.securedataplatform.com/parties/{partyId}/payoutInstrument`

br
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](/products/marketplaces/coverage/bank).

### Request/response example

### Schema


```json
{
  "$ref": "#/components/schemas/BankAccount",
  "components": {
    "schemas": {
      "Address": {
        "type": "object",
        "description": "Object containing details about the address.",
        "properties": {
          "address1": {
            "type": "string",
            "description": "The address.\n\n 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"
        ]
      },
      "BankAccount": {
        "type": "object",
        "properties": {
          "payoutInstrumentReference": {
            "type": "string",
            "description": "A reference of the `payoutInstrument` created by you. This\nfield holds the beneficiary bank details. Use this to direct payouts to\nthe relevant beneficiary. This must be unique within an entity.\n",
            "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"
        ]
      }
    }
  }
}
```

## 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-bsh.securedataplatform.com/parties/{partyId}/payoutInstrument/{payoutInstrumentId}`

br
### Request/response example

See full [schema](/products/parties/openapi/payout-instruments/getpayoutinstrument) 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-bsh.securedataplatform.com/parties/parTH82wexHglhnBbzd6iJ7P0/payoutInstrument/{payoutInstrumentId}`

### Request/response example

See full [schema](/products/parties/openapi/payout-instruments/updatepayoutinstruments) to modify your payout instrument.

## Delete a payout instrument

**Coming soon**

**Next steps**

[Manage beneficial owners](/products/parties/beneficial-owners)
[Add balance accounts](/products/parties/balance-accounts) or 
[Verify a party](/products/parties/verify-parties)