Worldpay Balance accounts API

openapi: 3.0.1
info:
  title: 3DS 3DS actions Balance accounts 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: Balance accounts
  description: Create and maintain balance accounts.
paths:
  /parties/{partyId}/balanceAccounts:
    post:
      tags:
      - Balance accounts
      summary: Create a balance account
      operationId: createBalanceAccount
      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/BalanceAccount'
            examples:
              Create a balance account for existing party of person (modular with a weekly payout):
                $ref: '#/components/examples/Create_BalanceAccount_Person_modular'
              Create a balance account for existing party of sole trader (modular with a monthly payout):
                $ref: '#/components/examples/Create_BalanceAccount_SoleTrader_modular'
              Create a balance account for existing party of company (modular with a daily payout):
                $ref: '#/components/examples/Create_BalanceAccount_Company_modular'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAccount'
              examples:
                Create a balance account for existing party of person (modular with a weekly payout):
                  $ref: '#/components/examples/BalanceAccount_Person_created_201_modular'
                Create a balance account for existing party of sole trader (modular with a monthly payout):
                  $ref: '#/components/examples/BalanceAccount_SoleTrader_created_201_modular'
                Create a balance account for existing party of company (modular with a daily payout):
                  $ref: '#/components/examples/BalanceAccount_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}/balanceAccounts/{balanceAccountId}:
    get:
      tags:
      - Balance accounts
      summary: View a balance account
      operationId: getBalanceAccount
      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: balanceAccountId
        in: path
        description: A unique identifier for the balanceAccount generated by us. This is sent in the response of your balanceAccount 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:
                $ref: '#/components/schemas/BalanceAccount'
              examples:
                Get a balance account for existing party of company (modular with a daily payout):
                  $ref: '#/components/examples/Get_BalanceAccount_Company_200_modular'
                Get a balance account for existing party of person (modular with a weekly payout):
                  $ref: '#/components/examples/Get_BalanceAccount_Person_200_modular'
                Get a balance account for existing party of sole trader (modular with a monthly payout):
                  $ref: '#/components/examples/Get_BalanceAccount_SoleTrader_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:
      - Balance accounts
      summary: Update a balance account
      operationId: updateBalanceAccount
      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: balanceAccountId
        in: path
        description: A unique identifier for the balanceAccount generated by us. This is sent in the response of your balanceAccount 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/UpdateBalanceAccountRequest'
            examples:
              Update a balance account:
                $ref: '#/components/examples/Update_Balance_Account_SoleTrader_modular'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAccount'
              examples:
                Update balance account:
                  $ref: '#/components/examples/Update_Balance_Account_SoleTrader_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:
  examples:
    Create_BalanceAccount_Person_modular:
      value:
        currency: EUR
        payoutInstrumentReference: personalCheckingAccount2
        scheduledPayoutDay: friday
        frequency: weekly
    Create_BalanceAccount_SoleTrader_modular:
      value:
        currency: USD
        scheduledPayoutDay: friday
        frequency: monthly
        recurrence: first
        payoutInstrumentReference: primaryBusinessAccount
    BalanceAccount_Person_created_201_modular:
      description: Balance account for a party of an existing person (modular)
      value:
        currency: EUR
        payoutInstrumentReference: personalCheckingAccount2
        scheduledPayoutDay: friday
        frequency: weekly
        balanceAccountId: pareBH4YMkUx7MA2X7bnS4750
        dateTimeCreated: '2025-04-16T20:46:26.727Z'
        version: 0
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    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
    BalanceAccount_Company_created_201_modular:
      description: Balance account for a party of an existing company (modular)
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        frequency: daily
        balanceAccountId: parGWfE__Xr1F-AmY0v72fwR0
        dateTimeCreated: '2025-04-16T20:46:27.014Z'
        version: 0
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    BalanceAccount_SoleTrader_created_201_modular:
      description: Balance account for a party of an existing soleTrader (modular)
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        scheduledPayoutDay: friday
        frequency: monthly
        recurrence: first
        balanceAccountId: parApcraCq1bmBuCotAMoyss0
        dateTimeCreated: '2025-04-16T20:46:26.852Z'
        version: 0
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    '500':
      value:
        errorName: internalErrorOccurred
        message: An error occurred within the service (potentially due to an interaction with a downstream service).
    '503':
      value:
        errorName: serviceUnavailable
        message: Service cannot fulfil the request even though service functions witout internal errors.
    Update_Balance_Account_SoleTrader_200_modular:
      description: Update balance account for existing party of a sole trader (modular)
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        scheduledPayoutDay: thursday
        frequency: weekly
        balanceAccountId: parApcraCq1bmBuCotAMoyss0
        dateTimeCreated: '2025-04-16T20:46:26.852Z'
        dateTimeUpdated: '2025-04-18T20:46:29.901Z'
        version: 2
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    Get_BalanceAccount_Person_200_modular:
      description: Balance account for a party of type person (modular)
      value:
        currency: EUR
        payoutInstrumentReference: personalCheckingAccount
        scheduledPayoutDay: friday
        frequency: weekly
        balanceAccountId: pareBH4YMkUx7MA2X7bnS4750
        dateTimeCreated: '2025-04-16T20:46:26.727Z'
        version: 0
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    Update_Balance_Account_SoleTrader_modular:
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        scheduledPayoutDay: thursday
        frequency: weekly
        balanceAccountId: parApcraCq1bmBuCotAMoyss0
        dateTimeCreated: '2025-04-16T20:46:26.852Z'
        dateTimeUpdated: '2025-04-16T20:46:29.901Z'
        version: 1
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    Get_BalanceAccount_SoleTrader_200_modular:
      description: Balance account for a party of type sole trader (modular)
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        scheduledPayoutDay: friday
        frequency: monthly
        recurrence: first
        balanceAccountId: parApcraCq1bmBuCotAMoyss0
        dateTimeCreated: '2025-04-16T20:46:26.852Z'
        version: 0
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    Get_BalanceAccount_Company_200_modular:
      description: Balance account for a party of type company (modular)
      value:
        currency: USD
        payoutInstrumentReference: primaryBusinessAccount
        frequency: daily
        balanceAccountId: parGWfE__Xr1F-AmY0v72fwR0
        dateTimeCreated: '2025-04-16T20:46:27.014Z'
        dateTimeUpdated: '2025-04-17T20:46:27.014Z'
        version: 1
        accountNumber: '12345678'
        nextPayoutDate: '2026-03-19'
    Create_BalanceAccount_Company_modular:
      value:
        currency: USD
        frequency: daily
        payoutInstrumentReference: primaryBusinessAccount
  schemas:
    ErrorResponseItem:
      type: object
      properties:
        errorName:
          type: string
        message:
          type: string
        path:
          type: string
        jsonPath:
          type: string
        queryParameter:
          type: string
        pathParameter:
          type: string
    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
    BalanceAccount:
      type: object
      properties:
        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]*$
        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
        scheduledPayoutDay:
          type: string
          description: The scheduled payout day for this `balanceAccount`. You must provide this for "weekly" and "monthly" `frequency`.
          enum:
          - monday
          - tuesday
          - wednesday
          - thursday
          - friday
          example: friday
        frequency:
          type: string
          description: 'Scheduled payout frequency for this `balanceAccount`:\

            **daily** - payouts are processed every business day\

            **weekly** - you must include `scheduledPayoutDay`\

            **monthly** - you must include `scheduledPayoutDay` and `recurrence`

            '
          enum:
          - daily
          - weekly
          - monthly
          example: weekly
        recurrence:
          type: string
          description: The week of the month the payout is paid out. You must provide this for "monthly" `frequency`.
          enum:
          - first
          - second
          - third
          - fourth
          example: first
        nextPayoutDate:
          type: string
          description: The next scheduled payout date for this balance account.
          example: '2025-02-14'
          readOnly: true
        balanceAccountId:
          type: string
          description: Unique ID created by us to identify a balance account. This is sent in the response after `balanceAccount` creation.
          readOnly: true
        accountNumber:
          type: string
          description: The number of your balanceAccount.
          readOnly: true
        dateTimeCreated:
          type: string
          description: The date and time that the balance account was created, as an ISO 8601 zoned date time.
          example: 2025-01-23T12:23:445.222Z
          readOnly: true
        dateTimeUpdated:
          type: string
          description: The date and time that the balance account was last updated, as an ISO 8601 zoned date time.
          example: 2025-01-25T02:43:499.202Z
          readOnly: true
        version:
          type: integer
          format: int32
          readOnly: true
      required:
      - currency
    UpdateBalanceAccountRequest:
      type: object
      description: Request payload for updating a balance account.
      properties:
        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]*$
        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
        scheduledPayoutDay:
          type: string
          description: The scheduled payout day for this `balanceAccount`. You must provide this for "weekly" and "monthly" `frequency`.
          enum:
          - monday
          - tuesday
          - wednesday
          - thursday
          - friday
          example: friday
        frequency:
          type: string
          description: 'Scheduled payout frequency for this `balanceAccount`:\

            **daily** - payouts are processed every business day\

            **weekly** - you must include `scheduledPayoutDay`\

            **monthly** - you must include `scheduledPayoutDay` and `recurrence`

            '
          enum:
          - daily
          - weekly
          - monthly
          example: weekly
        recurrence:
          type: string
          description: The week of the month the payout is paid out. You must provide this for "monthly" `frequency`.
          enum:
          - first
          - second
          - third
          - fourth
          example: first
        balanceAccountId:
          type: string
          description: Unique ID created by us to identify a balance account. This is sent in the response after `balanceAccount` creation.
        dateTimeCreated:
          type: string
          description: The date and time that the balance account was created, as an ISO 8601 zoned date time.
          example: 2025-01-23T12:23:445.222Z
        dateTimeUpdated:
          type: string
          description: The date and time that the balance account was last updated, as an ISO 8601 zoned date time.
          example: 2025-01-25T02:43:499.202Z
        version:
          type: integer
          format: int32
        accountNumber:
          type: string
          description: The number of your balanceAccount.
        nextPayoutDate:
          type: string
          format: date
          description: The upcoming payout date of the existing schedule for this `balanceAccountId`. You can retrieve this via our GET endpoint.
          example: '2025-02-14'
      required:
      - currency
      - nextPayoutDate
      - payoutInstrumentReference
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic