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