{
"openapi": "3.0.1",
"info": {
"title": "Beneficiary Account Verifications (BAV)",
"version": "2025-01-01",
"description": "\nVerify that the bank details of your beneficiary are valid before sending a payout.
\n__Authentication header__\n ```\n Authorization: {your_credentials}\n WP-Api-Version: 2025-01-01\n ```\n Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Worldpay Implementation Manager.\n
\n 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).\n
\n\n\n__DNS whitelisting__\n\nWhitelist the following URLs:\n* `https://try.access.worldpay-bsh.securedataplatform.co.uk/`\n* `https://access.worldpay-bsh.securedataplatform.co.uk/`\n\nPlease 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-bsh.securedataplatform.co.uk",
"description": "Test (Try)"
},
{
"url": "https://access.worldpay-bsh.securedataplatform.co.uk",
"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-01-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": {
"items": {
"$ref": "#/components/schemas/instructionsItems"
},
"description": "**Note:** Currently only one instruction is accepted."
}
}
},
"merchantItems": {
"required": [
"entity"
],
"type": "object",
"description": "**Note:** View our [bank coverage guide](/products/account-verifications/coverage) for country specific requirements.",
"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": {
"$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
}
}
},
"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": {
"$ref": "#/components/schemas/payoutInstrumentItems"
},
"personalDetails": {
"$ref": "#/components/schemas/personalDetailsItems"
}
}
},
"payoutInstrumentItems": {
"required": [
"accountType",
"address"
],
"type": "object",
"description": "An object that holds details of your payout instrument.\n\n",
"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": {
"$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 ISO 3166-1 Alpha-2 country code.",
"example": "GB"
}
}
},
"personalDetailsItems": {
"required": [
"type"
],
"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",
"maxLength": 35,
"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",
"maxLength": 35,
"description": "Middle name name of the beneficiary."
},
"lastName": {
"type": "string",
"maxLength": 35,
"description": "Last name name of the beneficiary.",
"example": "Smith"
},
"dateOfBirth": {
"type": "string",
"description": "The date the `person` was born."
},
"companyName": {
"type": "string",
"maxLength": 70,
"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}$"
}
}
},
"BAV200response": {
"required": [
"outcome"
],
"type": "object",
"properties": {
"outcome": {
"description": "All possible outcomes and description can be found in the below table:
\n|**outcome**|**message**| \n|---|---|\n|fullMatch|Account Details Matched|\n|businessAccountNameMatched|Account name matches but the account is a business account, not a personal account|\n|partialMatch|Close match found|\n|businessAccountCloseMatch|Close match found for account name but the account is a business account, not a personal account|\n|noMatch|Account name and account type do not match|\n|accountDoesNotExist|Account does not exist|\n|noResponse|The bank did not respond to the account name check request. Try again later.|\n||Unexpected system error occurred. Try again later.|\n|accountNotSupported|Account does not support account name check requests|\n|accountSwitched|The account has been switched using the Current Account Switching Service|\n|notEnrolled|The account name check could not be completed as the bank does not accept account name check requests|\n|wrongParticipant|The account name check cannot be completed for the account number and sort code provided|\n|secondaryAccountIdNotFound|The secondary account id is not valid|\n|personalAccountNameMatched|The account name matches but the account is a personal account, not a business account|\n|personalAccountCloseMatch|Close match found for account name but the account is a personal account, not a business account|\n|accountActive|Account is active but Name match unavailable for this account|\n|cannotValidate|Unable to Validate the Account Details|\n|accountClosed|The Account is either Closed or Unavailable to receive payments|\n",
"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": []
}
]
}