Documentation for a newer release is available. View Latest

Name Matching

Overview

Name matching refers to the way the Verification of Payee (VoP) Responder service matches names using the IPF Identity Resolution service, which is running embedded in VoP Responder.

The name matching logic provides a way to configure the thresholds used for name matching in the Verification of Payee Responder service. The thresholds determine how closely names need to match to be considered a match, a close match, or no match.

How It Works

The Name Matching functionality allows the VoP Responder service to:

  1. Map processing entities to different account types and ultimately scoring thresholds

  2. Map different account types to scoring thresholds

  3. Send name comparison requests for scoring and receive scored response

  4. Determine a match result based on a provided scoring of the names. This could either be no match, close match or match.

  5. When scoring against multiple names, in the case of joint accounts, the name scoring the highest score will be used for determining the match result.

  6. Scoring against a Name Type which could either be FULL_ORGANISATION or INDIVIDUAL as defined in the Account Management API. Providing better accuracy depending on if this is an individual or corporate name.

Default Processing Entity

Every scheme needs a default processing entity, marked with processing-entity = "default". This ensures that if a request doesn’t specify a processing entity, or it does not match, the system automatically falls back to this default.

Default Account Type

Every scheme needs a default account type, marked with scorings.type = "default". This ensures that if a request doesn’t specify an account type, or it does not match, the system automatically falls back to this default.

Configuration

VoP Responder requires scoring threshold configuration to be set up before the application is started. This configuration is expected under the ipf.verification-of-payee.responder.name-match path.

Example Configuration

Name Matching thresholds are configured as follows:

Property Grouping: ipf.verification-of-payee.responder.name-match

Key Description Example Value

ipf.verification-of-payee.responder.name-match.thresholds

Thresholds are configured per processing entity

 
[
    {
        "processing-entity" : "default",
        "scorings" : [
            {
                "lowerbound" : 0.2,
                "type" : "default",
                "upperbound" : 0.4
            },
            {
                "lowerbound" : 0.5,
                "type" : "individual",
                "upperbound" : 0.7
            },
            {
                "lowerbound" : 0.8,
                "type" : "corporate",
                "upperbound" : 0.9
            }
        ]
    }
,
    {
        "processing-entity" : "processing entity A",
        "scorings" : [
            {
                "lowerbound" : 0.1,
                "type" : "default",
                "upperbound" : 0.3
            },
            {
                "lowerbound" : 0.4,
                "type" : "individual",
                "upperbound" : 0.6
            },
            {
                "lowerbound" : 0.8,
                "type" : "corporate",
                "upperbound" : 0.8
            }
        ]
    }

]

Additional Details

Further details of fields underneath ipf.verification-of-payee.responder.name-match.thresholds are below:

Field Name Description

processing-entity

The processing entity the list of scorings applies to. A default processing entity is required when the Account Management response contains no processing entity, in which case the default entry will be used. This field should match what is returned in the Account Management API processingEntity field.

scorings

A list of scores for the processing entity.

scorings.type

The account type this scoring applies to. A default type is required when the Account Management response contains no account type, in which case the default entry will be used. This should match what is returned in the Account Management API accountType field.

scorings.lowerbound

The minimum score used to determine a no match or close match result. A score lower than this value will result in a no match. A score between the scorings.lowerbound and scorings.upperbound will result in a close match. The configured value must be of type Double and between the range of [0.0, 1.0].

scorings.upperbound

The maximum score used to determine a match or close match result. A score equal to or greater than this value will result in a match. A score between the scorings.lowerbound and scorings.upperbound will result in a close match. The configured value must be of type Double and between the range of [0.0, 1.0].
If scorings.lowerbound is set to the same value as scorings.upperbound this effectively eliminates close matches, and you can only get a match or no match result back.

Examples

Below are some examples of how scoring would work given the sample configuration above:

Processing Entity

Account Type

Score

Result

Description

-

corporate

1.0

Match

Default processing entity used

processing entity A

-

0.9

Match

Default account type used

processing entity A

individual

0.8

Match

No defaults used - individual account

processing entity A

corporate

0.8

Match

No defaults used - corporate account

processing entity A

individual

0.5

Close Match

Close match result

processing entity A

corporate

0.4

No Match

No match result

"-" represents no data provided

Error Handling

Startup Errors

Name Matching performs startup validations and adopts a fail-fast strategy halting application startup if any of the following configuration validations fail:

  • Config under the following path ipf.verification-of-payee.responder.name-match.thresholds is required

  • A default processing entity is required

  • A default threshold type is required

  • Duplicate processing entities are not allowed.

  • Duplicate scoring types are not allowed.

  • Config items scorings.lowerbound and scorings.upperbound must be between [0.0, 1.0] and of type Double

  • Config item scorings.lowerbound must be less than or equal to scorings.upperbound

Runtime Errors

The following errors may occur at runtime. When an error occurs, the service responds with the corresponding HTTP error code, as outlined in the table below.

Error HTTP Return Code

Errors encountered accessing Name Matching will return the following

Error message: Could not retrieve a response because the Name Matching service is unavailable.

500

All other errors related to name matching e.g. if a request with a nameType not present

Error message: Unknown error occurred. Please check logs for more details

500