New service | **Last updated**: 09 October 2025

# Beneficiary Account Verifications API

New

Verify a beneficiary's bank details to ensure the payout is going to the intended account.

## Verify an account

`POST` `https://try.access.worldpay-bsh.securedataplatform.com/accountVerifications`

### Request example

### Schema


```json
{
  "$ref": "#/components/schemas/postRequestItems",
  "components": {
    "schemas": {
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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}$"
          }
        }
      },
      "personalDetailsItems": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "What the party represents:\n`personal` - an individual \n`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"
            }
          }
        }
      },
      "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"
          }
        }
      },
      "instructionsItems": {
        "required": [
          "party"
        ],
        "type": "object",
        "properties": {
          "party": {
            "type": "object",
            "properties": {
              "items": null
            },
            "$ref": "#/components/schemas/partyItems"
          },
          "expandableKeyValuePairs": {
            "type": "object",
            "description": "JSON object of key-value pairs used to supply additional data. The keys and values that you might need to process an account payout to a specific destination, are communicated during the on-boarding process. Duplicate key names are not allowed.",
            "nullable": true
          }
        }
      },
      "postRequestItems": {
        "required": [
          "merchant",
          "instructions"
        ],
        "type": "object",
        "properties": {
          "merchant": {
            "$ref": "#/components/schemas/merchantItems"
          },
          "instructions": {
            "items": {
              "$ref": "#/components/schemas/instructionsItems"
            },
            "description": "{% admonition type=\"info\" name=\"Note\" %} Currently only one instruction is accepted.{% /admonition %}"
          }
        }
      }
    }
  }
}
```

### Response example

fullMatch

```
{
  "outcome": "fullMatch",
  "message": "Account Details Matched",
  "actualAccountHolderName": ""
}
```

Example error

```
{
  "errorName": "forbidden",
  "message": "User is not entitled to access this resource"
}
```

For a full list of outcomes and errors see our [API Reference](/products/account-verifications/openapi).

**Next steps**

[Make a payout](/products/account-payouts/)