openapi: 3.0.1
info:
  title: Beneficiary Account Verifications (BAV)
  version: '2025-10-01'
  description: >-

    Verify that the bank details of your beneficiary are valid before sending a
    payout.<br><br>

    __Authentication Header__
      ```
        Authorization: {your_credentials}
        WP-Api-Version: 2025-10-01
      ```
      Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.
      <br /> <br />
      You **must** use the `Authorization` header for any request you send to our Beneficiary Account Verifications API, unless you are using client certificate [authenticating with SSL/TLS](/products/reference/security).
      <br /><br />


    __DNS Whitelisting__


    Whitelist the following URLs:

    * `https://try.access.worldpay.com/`

    * `https://access.worldpay.com/`


    Please ensure you use DNS whitelisting, not explicit IP whitelisting. When
    you make a request within Access Worldpay, you should always cache the
    response returned.
  x-metadata:
    category:
      - Verifications
    business:
      - Enterprise
      - Marketplaces
    catalog-list: true
servers:
  - url: https://try.access.worldpay.com
    description: testing
  - url: https://access.worldpay.com
    description: live
paths:
  /accountVerifications:
    post:
      summary: Verify a beneficiary account
      operationId: postAccountVerifications
      parameters:
        - name: WP-Api-Version
          in: header
          required: true
          schema:
            type: string
          example: '2025-10-01'
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postRequestItems'
            examples:
              Validate an account:
                value:
                  merchant:
                    entity: default
                  instructions:
                    - party:
                        type: beneficiary
                        payoutInstrument:
                          type: bankAccount
                          currency: GBP
                          iban: GB41CITI18500818404062
                          accountHolderName: John Smith
                          accountNumber: '123456'
                          bankCode: '184758'
                          bankName: Demo Bank
                          branchCode: '1234'
                          swiftBic: DBbic01
                          accountType: checking
                          address:
                            type: personal
                            address1: Main Bvd
                            address2: No 1
                            city: London
                            postalCode: '012345'
                            countryCode: GB
                        personalDetails:
                          type: personal
                          title: Mr
                          firstName: John
                          middleName: ''
                          lastName: Smith
                          dateOfBirth: '2000-01-01'
                          companyName: Co Name
                          dateOfIncorporation: '2025-01-01'
                          email: john@domain.com
                          phones:
                            - number: '7777777777'
                              prefix: '44'
                      expandableKeyValuePairs:
                        key: value
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BAV200response'
              examples:
                fullMatch:
                  value:
                    outcome: fullMatch
                    message: Account Details Matched
                    actualAccountHolderName: ''
                partialMatch:
                  value:
                    outcome: partialMatch
                    message: Close match found
                    actualAccountHolderName: John Smith
                noMatch:
                  value:
                    outcome: noMatch
                    message: Account name and account type do not match
                    actualAccountHolderName: John Smith
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BAV400response'
              examples:
                AccountType is not provided:
                  value:
                    validationErrors:
                      - jsonPath: $.instructions[0].party.payoutInstrument.accountType
                        errorName: fieldHasInvalidValue
                        message: Invalid AccountType value.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                IBAN or AccountNumber is not provided:
                  value:
                    validationErrors:
                      - jsonPath: $.instructions[0].party.payoutInstrument.iban
                        errorName: fieldIsMissing
                        message: >-
                          The identified field is missing. Iban is a mandatory
                          element of the request body when accountNumber is
                          missing.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                Party.Type is not provided:
                  value:
                    validationErrors:
                      - jsonPath: $.instructions[0].party.type
                        errorName: fieldIsMissing
                        message: >-
                          The identified field is missing. This field is a
                          mandatory element of the request body.
                    errorName: bodyDoesNotMatchSchema,
                    message: The json body provided does not match the expected schema
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: User is not authorized to access this resource
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: User is not entitled to access this resource
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: An unexpected error occured while processing the request
components:
  schemas:
    postRequestItems:
      required:
        - merchant
        - instructions
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/merchantItems'
        instructions:
          $ref: '#/components/schemas/instructionsItems'
    merchantItems:
      required:
        - entity
      type: object
      properties:
        entity:
          type: string
          description: >-
            Your entity reference created as part of on-boarding. Used to route
            the request in Access Worldpay.
          example: default
    instructionsItems:
      required:
        - party
      type: object
      properties:
        party:
          type: object
          properties:
            items: null
          $ref: '#/components/schemas/partyItems'
        expandableKeyValuePairs:
          type: object
          properties:
            items: null
          $ref: '#/components/schemas/expandableKeyValuePairsItems'
    partyItems:
      required:
        - type
        - payoutInstrument
        - personalDetails
      type: object
      properties:
        type:
          type: string
          description: The type of this party. Only `beneficiary` type is accepted.
          example: beneficiary
        payoutInstrument:
          type: object
          properties:
            items: null
          $ref: '#/components/schemas/payoutInstrumentItems'
        personalDetails:
          type: object
          properties:
            items: null
          $ref: '#/components/schemas/personalDetailsItems'
    payoutInstrumentItems:
      required:
        - accountType
        - address
      type: object
      description: >-
        A object that holds details of your payout instrument. <br> {%
        admonition type="info" name="Note" %} View our [bank coverage
        guide](/products/account-verifications/coverage) for country specific
        requirements.{% /admonition %}
      properties:
        type:
          type: string
          description: The type of the `payoutInstrument`.
          example: bankAccount
        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]*$
        iban:
          type: string
          description: Beneficiary IBAN. You must either provide `iban` or `accountNumber`.
          example: GB41CITI18500818404062
        accountNumber:
          type: number
          example: 123456
        accountHolderName:
          type: string
          description: >-
            Full name of the beneficiary. `accountHolderName` is a mandatory
            element of the request body when `firstName` and `lastName` are
            missing.
          example: John Smith
        accountType:
          type: string
          description: Type of the account bank.
          enum:
            - checking
            - savings
            - moneyMarket
            - certificateOfDeposit
            - vista
            - other
        bankCode:
          type: string
          description: The code of the bank which must be exactly six digits.
          example: '184758'
        bankName:
          type: string
          example: Demo Bank
        branchCode:
          type: string
          example: 1234
        swiftBic:
          type: string
          example: DBbic01
        address:
          type: object
          properties:
            items: null
          $ref: '#/components/schemas/payoutInstrumentAddressItems'
    payoutInstrumentAddressItems:
      required:
        - countryCode
      type: object
      properties:
        type:
          type: string
          description: Identifies the type of this address.
          enum:
            - home
            - business
            - poBox
            - other
        address1:
          type: string
          description: >-
            The address. Must consist of at least two letters, two words, and
            one number.
        address2:
          type: string
          description: Line two of the address.
        city:
          type: string
          description: The city of this address.
        postalCode:
          type: string
          description: The postal code of this address.
        countryCode:
          maxLength: 2
          minLength: 2
          type: string
          description: >-
            The country code specified in <a
            href="/products/reference/supported-countries-currencies">ISO 3166-1
            Alpha-2 country code</a>.
          example: GB
    personalDetailsItems:
      type: object
      properties:
        type:
          type: string
          description: |-
            What the party represents:
            `personal` - an individual 
            `company` - a corporation     or partnership with multiple owners..
          example: personal
        title:
          type: string
          description: The title for this person.
          enum:
            - mr
            - mrs
            - miss
            - ms
            - dr
            - mx
            - misc
          example: mr
        firstName:
          type: string
          description: >-
            First name of the beneficiary. `firstName` and `lastName` are
            mandatory elements of the request body when `accountHolderName` is
            missing.
          example: John
        middleName:
          type: string
          description: Middle name name of the beneficiary.
        lastName:
          type: string
          description: Last name name of the beneficiary.
          example: Smith
        dateOfBirth:
          type: string
          description: The date the `person` was born.
        companyName:
          type: string
          description: >-
            Company name. `companyName` must be provided if `accountHolderName`
            is not present and `type` is `company`.
        dateOfIncorporation:
          type: string
          description: The incorporation date for the company.
        email:
          type: string
          description: An email address for this party.
        phones:
          type: array
          description: A list of phone numbers associated with this party.
          items:
            $ref: '#/components/schemas/phoneItems'
    phoneItems:
      type: object
      description: Object containing phone information.
      properties:
        number:
          type: string
          description: The phone number, without dashes.
          example: '4281234'
          pattern: '[0-9]{1,20}'
        prefix:
          type: string
          description: The dialing prefix for the phone number.
          example: '44'
          pattern: ^[0-9]{1,3}$
    expandableKeyValuePairsItems:
      type: object
      properties:
        key:
          type: string
          description: Additional information.
    BAV200response:
      required:
        - outcome
      type: object
      properties:
        outcome:
          description: >
            All possible outcomes and description can be found in the below
            table: <br>

            |**outcome**|**message**| 

            |---|---|

            |fullMatch|Account Details Matched|

            |businessAccountNameMatched|Account name matches but the account is
            a business account, not a personal account|

            |partialMatch|Close match found|

            |businessAccountCloseMatch|Close match found for account name but
            the account is a business account, not a personal account|

            |noMatch|Account name and account type do not match|

            |accountDoesNotExist|Account does not exist|

            |noResponse|The bank did not respond to the account name check
            request. Try again later.|

            ||Unexpected system error occurred. Try again later.|

            |accountNotSupported|Account does not support account name check
            requests|

            |accountSwitched|The account has been switched using the Current
            Account Switching Service|

            |notEnrolled|The account name check could not be completed as the
            bank does not accept account name check requests|

            |wrongParticipant|The account name check cannot be completed for the
            account number and sort code provided|

            |secondaryAccountIdNotFound|The secondary account id is not valid|

            |personalAccountNameMatched|The account name matches but the account
            is a personal account, not a business account|

            |personalAccountCloseMatch|Close match found for account name but
            the account is a personal account, not a business account|

            |accountActive|Account is active but Name match unavailable for this
            account|

            |cannotValidate|Unable to Validate the Account Details|

            |accountClosed|The Account is either Closed or Unavailable to
            receive payments|
          type: string
        message:
          description: Description message.
          type: string
        actualAccountHolderName:
          description: >-
            Account owner name after the payload is processed. Availability is
            subject to market standard.
          type: string
    ErrorResponse:
      type: object
      required:
        - errorName
        - message
      properties:
        errorName:
          description: The unique error name.
          type: string
        message:
          description: Error description message.
          type: string
    BAV400response:
      type: object
      required:
        - validationErrors
        - errorName
        - message
      properties:
        validationErrors:
          description: Object containing details of validation errors occurred
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse400Item'
        errorName:
          description: The unique error name.
          type: string
        message:
          description: Error description message.
          type: string
    ErrorResponse400Item:
      type: object
      required:
        - queryParameter
        - errorName
        - message
      properties:
        queryParameter:
          description: Parameter for which the error occurred.
          type: string
        errorName:
          description: Unique name of the validation error.
          type: string
        message:
          description: Error description message.
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
