Beneficiary Verifications

The beneficiary verification check begins when a payer begins setting up a new beneficiary to make a payment to. The payer provides the account name, sort code, account number and indicates the account type (corporate, individual). The information given is then checked. The main goal of this service is to help reduce the incidences of misdirected payments. For given directory (corporate or individual), the provided information is compared against the real account holder name of the beneficiary bank account.

Currently, Confirmation of Payee (CoP) service of Pay.UK and Verification of Payee(VoP) service of European Payments Council are supported integration. CoP service can be consumed from either Clearbank, Currency Cloud, Griffin, Modulr, Railsr or Tell Money and VoP service can be consumed from either Clearbank, Tell Money.

POST /beneficiary-verifications

Request Fields

Field	Description	Notes
workflow.code	Workflow of beneficiary verification directory	pay-ukandepc*supported as a directory for now, available value is `client.pay-uk.cop` `client.epc.vop`
data.beneficiary	Beneficiary details object
data.beneficiary.clientId	Client id for charging the verification request
data.beneficiary.identity	Identity details of beneficiary	Two type of identity is available; individual: requires givenName & familyName corporate: requires legalName for CoP, requires one of legalName or identifications for VoP
data.beneficiary.identity.identifications	Identification numbers of beneficiary
data.beneficiary.bankAccount	Bank account details of beneficiary
data.beneficiary.bankAccount.routingCodes	Routing codes for beneficiary's bank account	It is an extendible routing code details, sort-code is required for pay-uk verifications
data.beneficiary.bankAccount.iban	IBAN of beneficiary
data.beneficiary.bankAccount.accountNumber	Account number of beneficiary
data.beneficiary.bankAccount.country	Two letter code of country in which the beneficiary's bank account is held	It is required if service provider is CurrencyCloud
data.beneficiary.attributes.secondaryIdentification	For any additional information to specify the beneficiary, such as credit card number, building number etc.	(Optional)
connect	It is used for specifying service provider	Two type of connect is available; implicit: it means the configured default service provider will be used to verify beneficiary explicit: it requires theserviceProvider** which will be used for verification

Response Fields

Field	Description
data.beneficiaryVerification	Includes name check result and beneficiary details which are provided in the verification request
data.beneficiaryVerification.id	Unique ID of the request
data.beneficiaryVerification.result	Result object of name and account check
data.beneficiaryVerification.result.matched	Indicates result of name and account check as boolean value
data.beneficiaryVerification.result.reason	Reason code of result, only provided if matched field is `false`
data.beneficiaryVerification.result.accountHolderName	Beneficiary name which returns from service provider, only provided if matched field is `false`

{
    "workflow": {
        "code": "client.pay-uk.cop"
    },
    "data": {
        "beneficiary": {
            "clientId": "fbb25321-97a3-4914-a189-b581c214c5c7",
            "identity": {
                "type": "individual",
                "givenName": "Betty",
                "familyName": "Morris"
            },
            "bankAccount": {
                "routingCodes": {
                    "sort-code": "040568"
                },
                "accountNumber": "10006132"
            },
            "attributes": {
                "secondaryIdentification": null
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "service-provider-code"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.pay-uk.cop"
    },
    "data": {
        "beneficiaryVerification": {
            "id": "0953775e-b635-473c-a111-bb606417e3d8",
            "clientId": "fbb25321-97a3-4914-a189-b581c214c5c7",
            "directory": "pay-uk",
            "serviceProvider": "clearbank",
            "beneficiaryIdentity": {
                "type": "individual",
                "givenName": "Betty",
                "familyName": "Morris"
            },
            "beneficiaryBankAccount": {
                "routingCodes": {
                    "sort-code": "040568"
                },
                "accountNumber": "10006132"
            },
            "attributes": {
                "secondaryIdentification": null
            },
            "result": {
                "matched": true,
                "reason": null,
                "accountHolderName": null
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "clearbank"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.pay-uk.cop"
    },
    "data": {
        "beneficiary": {
            "clientId": "3f1ee4ae-8c1f-45a5-a147-93a1f169a37a",
            "identity": {
                "type": "corporate",
                "legalName": "ABCDEFG Inc"
            },
            "bankAccount": {
                "routingCodes": {
                    "sort-code": "123456"
                },
                "accountNumber": "12345678"
            },
            "attributes": {
                "secondaryIdentification": "London"
            }
        }
    },
    "connect": {
        "type": "implicit"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.pay-uk.cop"
    },
    "data": {
        "beneficiaryVerification": {
            "id": "5ffe1892-f0a1-4afb-8501-7e2283dffe32",
            "clientId": "3f1ee4ae-8c1f-45a5-a147-93a1f169a37a",
            "directory": "pay-uk",
            "serviceProvider": "modulr",
            "identity": {
                "type": "corporate",
                "legalName": "ABCDEFG Inc"
            },
            "bankAccount": {
                "routingCodes": {
                    "sort-code": "123456"
                },
                "accountNumber": "12345678"
            },
            "attributes": {
                "secondaryIdentification": "London"
            },
            "result": {
                "matched": true,
                "reason": null,
                "accountHolderName": null
            }
        }
    },
    "connect": {
        "type": "implicit"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.epc.vop"
    },
    "data": {
        "beneficiary": {
            "clientId": "23afa781-351d-45e9-be82-be969fc01307",
            "identity": {
                "type": "individual",
                "givenName": "Jean",
                "familyName": "Dupont"
            },
            "bankAccount": {
                "iban": "NL88CLRB0078802134"
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "tell-money-confirm-eu"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.epc.vop"
    },
    "data": {
        "beneficiaryVerification": {
            "id": "8a4a4b1a-5969-43b3-8215-9ffb50213367",
            "clientId": "23afa781-351d-45e9-be82-be969fc01307",
            "directory": "epc",
            "serviceProvider": "tell-money-confirm-eu",
            "beneficiaryIdentity": {
                "type": "individual",
                "givenName": "Jean",
                "familyName": "Dupont"
            },
            "beneficiaryBankAccount": {
                "iban": "NL88CLRB0078802134"
            },
            "result": {
                "matched": false,
                "reason": null,
                "accountHolderName": null
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "tell-money-confirm-eu"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.epc.vop"
    },
    "data": {
        "beneficiary": {
            "clientId": "23afa781-351d-45e9-be82-be969fc01307",
            "identity": {
                "type": "corporate",
                "legalName": "ABC Corporate"
            },
            "bankAccount": {
                "iban": "NL88CLRB0078802134",
                "routingCodes": {
                    "bic": "MIDLGB22XXX"
                }
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "tell-money-confirm-eu"
    },
    "metadata": {}
}

{
    "workflow": {
        "code": "client.epc.vop"
    },
    "data": {
        "beneficiaryVerification": {
            "id": "2709211b-a9c7-422f-beb9-1e00ad3db900",
            "clientId": "23afa781-351d-45e9-be82-be969fc01307",
            "directory": "epc",
            "serviceProvider": "tell-money-confirm-eu",
            "beneficiaryIdentity": {
                "type": "corporate",
                "legalName": "ABC Corporate"
            },
            "beneficiaryBankAccount": {
                "iban": "NL88CLRB0078802134",
                "routingCodes": {
                    "bic": "MIDLGB22XXX"
                }
            },
            "result": {
                "matched": false,
                "reason": null,
                "accountHolderName": null
            }
        }
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "tell-money-confirm-eu"
    },
    "metadata": {}
}

Reason Codes

Reason code which is returned in data.beneficiaryVerification.result.reason field to specify the reason why beneficiary name does not match.

Code	Description
not-match	The name provided does not match.
close-match	The name provided is similar to the beneficiary name. The actual beneficiary name is provided in `accountHolderName` field usually.
corporate-account-name-matched	The beneficiary name matches the name provided but the account is a corporate account, not an individual account.
individual-account-name-matched	The beneficiary name matches the name provided but the account is an individual account, not a corporate account.
corporate-account-close-match	The name provided is similar to the beneficiary name and the account is a corporate account, not an individual account. The actual beneficiary name is provided in `accountHolderName` field usually.
individual-account-close-match	The name provided is similar to the beneficiary name and the account is an individual account, not a corporate account. The actual beneficiary name is provided in `accountHolderName` field usually
incorrect-account-number	The account number provided is not matched with the beneficiary name. You should not proceed without checking account number.
account-type-not-supported	The account does not support beneficiary verification requests. You should check the account details carefully.
account-switched	The account has been switched. You should not proceed with the beneficiary name provided in request.
sort-code-not-supported	The sort code does not support beneficiary verification requests. You should check the account details carefully.
invalid-secondary-identifier	`secondaryIdentification` provided in the request does not belong to beneficiary. You should check the secondary identifier or try without `secondaryIdentification` field.
opted-out	Beneficiary has been opted out by the directory provider.
not-applicable	Provided beneficiary information cannot be verified with given directory.