Name validation

Name validation allows you to verify if the cardholder name provided by a shopper matches the cardholder name on file at the issuing bank. The service is offered by Visa and Mastercard, and requires you to pay a fee for each transaction where name validation is performed.

You can request this validation with a zero-value auth transaction to:

• Reduce fraud and chargeback losses.
• Comply with Know Your Customer (KYC) requirements.
• Improve the reliability of payouts by making sure funds are sent to the right person.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

To validate a cardholder's name:

1. You make a /payments request for a zero-value auth transaction. In the request, you include the cardholder's name and the paymentValidations object to request a name validation.
2. Adyen forwards the validation request to Visa or Mastercard.
3. The cardholder's issuing bank checks if the name the shopper provided matches the name they have on file.
4. Adyen receives the result and forwards it to you in the paymentValidations object within the synchronous API response.
5. You monitor the result object to get the outcome of the name validation.
6. You build your own logic based on the validation outcome. For example, depending on the match results, you can proceed to authorize the payment or request additional verification.

Request a name validation

To request a name validation, use your online payments integration to make a /payments request, and include:

The following example shows how to request a name validation for John Smith.

Fallback logic

If you do not include the shopperName when requesting a name validation, we use the paymentMethod.holderName field to populate the shopper name fields. We take the characters until the first space or period(.) to populate the first name.

To ensure accuracy and get the best validation results, we strongly recommend to include the shopperName field instead of relying on the paymentMethod.holderName fallback.

Validation results

When you make a /payments request to validate a cardholder's name, Adyen forwards the information you provide to the schemes to perform the name validation. The API response includes:

• The status of the name validation.
• The outcome of the name validation.

Status

The paymentValidations.name.status field in the response informs you if name validation was performed. For Visa, you also receive the raw status value that Adyen receives in the paymentValidations.name.rawResponse.status field. Mastercard does not return a rawResponse.status.

Outcome

The paymentValidations.name object in the response includes the following objects that inform you of the name validation results.

• result: the scheme-agnostic match values returned by Adyen.
• rawResponse: the raw response(s) we receive from the scheme.
  For example, the result.fullName contains the Adyen value, and rawResponse.fullName contains the value we received from Visa or Mastercard.

For Visa, the response includes match values for the full name, along with first name, middle name, and last name. For Mastercard, the response only includes the full name match value.

The following response examples show the name validation responses for Visa and Mastercard.

Testing

To test different name validation responses and match results:

1. In your test /payments request, request a name validation.

2. Use our Visa and Mastercard test cards.

3. Set the shopperName field to the following test shopper names to test different match statuses. If you do not provide the name in this field, we fall back to the holder name you provide in the paymentMethod object.

   Match status	First name	Middle name	Last name
   Match	John	Maria	Smith
   Partial match	Jon	Mariah	Smyth
   No match	Alice	Peter	Brown

   Keep in mind that the logic to determine the full name match is based on the combination of the first, middle, and last name values are maintained by the schemes and not transparent to Adyen. The following section shows some example test scenarios and the results they are expected to trigger per scheme.

4. Test that your implementation correctly handles the match statuses you receive in the name validation outcome.

The following table contains example scenarios and the results they are expected to trigger per scheme.

Test the unhappy flow

To trigger the scenario where name validation is not supported, or not performed:

1. In your test /payments request, request a name validation.
2. Use our Visa and Mastercard test cards.
3. To test the scenario where the name validation is not performed, use any combination of the test shopper name values and set the reference to NotPerformed.
4. To test the scenario where name validation is not supported, use any combination of the test shopper name values and set the reference to NotSupported.
   Alternatively, you can also use a shopper name that's not part of the test shopper names.
5. Test that your integration can correctly handle scenarios where name validation is not successful.

For example, if you set the reference to NotSupported, with any combination of the test shopper names, the response will contain:

• paymentValidations.name.status: notSupported
• Only for Visa, paymentValidations.name.rawResponse.status: 02

See also

• Cards
• Risk management