Beneficiary Verifications
Beneficiary verification service is provided to check the name of the beneficiary. Main goal of this service is to help reduce the incidences of misdirected payments. For given directory, 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 is the only supported integration. CoP service can be consumed from either Clearbank, Modulr, Railsr or Tell Money.
POST /beneficiary-verifications
Request Fields
Field | Description | Notes |
---|---|---|
workflow.code | Workflow of beneficiary verification directory | Only pay-uk supported as a directory for now, available value is client.pay-uk.cop |
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 |
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.accountNumber | Account number of 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 the serviceProvider 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 check |
data.beneficiaryVerification.result.matched | Indicates result of name 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": "clearbank"
},
"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": {}
}
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 |
---|---|
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. |
Updated 7 months ago