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

FieldDescriptionNotes
workflow.codeWorkflow of beneficiary verification directoryOnly pay-uk supported as a directory for now, available value is client.pay-uk.cop
data.beneficiaryBeneficiary details object
data.beneficiary.clientIdClient id for charging the verification request
data.beneficiary.identityIdentity details of beneficiaryTwo type of identity is available;
individual: requires givenName & familyName
corporate: requires legalName
data.beneficiary.bankAccountBank account details of beneficiary
data.beneficiary.bankAccount.routingCodesRouting codes for beneficiary's bank accountIt is an extendible routing code details, sort-code is required for pay-uk verifications
data.beneficiary.bankAccount.accountNumberAccount number of beneficiary
attributes.secondaryIdentificationFor any additional information to specify the beneficiary, such as credit card number, building number etc.(Optional)
connectIt 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

FieldDescription
data.beneficiaryVerificationIncludes name check result and beneficiary details which are provided in the verification request
data.beneficiaryVerification.idUnique ID of the request
data.beneficiaryVerification.resultResult object of name check
data.beneficiaryVerification.result.matchedIndicates result of name check as boolean value
data.beneficiaryVerification.result.reasonReason code of result, only provided if matched field is false
data.beneficiaryVerification.result.accountHolderNameBeneficiary 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.

CodeDescription
close-matchThe name provided is similar to the beneficiary name. The actual beneficiary name is provided in accountHolderName field usually.
corporate-account-name-matchedThe beneficiary name matches the name provided but the account is a corporate account, not an individual account.
individual-account-name-matchedThe beneficiary name matches the name provided but the account is an individual account, not a corporate account.
corporate-account-close-matchThe 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-matchThe 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-numberThe account number provided is not matched with the beneficiary name. You should not proceed without checking account number.
account-type-not-supportedThe account does not support beneficiary verification requests. You should check the account details carefully.
account-switchedThe account has been switched. You should not proceed with the beneficiary name provided in request.
sort-code-not-supportedThe sort code does not support beneficiary verification requests. You should check the account details carefully.
invalid-secondary-identifiersecondaryIdentification provided in the request does not belong to beneficiary. You should check the secondary identifier or try without secondaryIdentification field.
opted-outBeneficiary has been opted out by the directory provider.