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.