Name validation

Validate the cardholder name provided by a shopper.

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.

Requirement	Description
Integration type	An online payments integration using the Advanced flow with Checkout API v69 or later.
API credential roles	You need an API credential with an API key and the Checkout webservice role.
Limitations	This feature is dependent on issuer readiness, and is only supported for: Zero-value auth transactions. Visa and Mastercard payments in the United States, United Kingdom, and Europe.

How it works

Learn more

Our name validation feature uses the validation services offered by card schemes.

To validate a cardholder's name:

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.
Adyen forwards the validation request to Visa or Mastercard.
The cardholder's issuing bank checks if the name the shopper provided matches the name they have on file.
Adyen receives the result and forwards it to you in the paymentValidations object within the synchronous API response.
You monitor the result object to get the outcome of the name validation.
You build your own validation logic. For example, depending on the match results, you can proceed to authorize the payment or request additional verification.

We are currently working on expanding the paymentValidations field to add support for additional validation types, such as Address Verification System, to simplify requesting validations.

Request a name validation

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

Field	Description
`amount.value`	The transaction amount. Set to 0 when performing a name validation.
`paymentMethod`	The payment details. For cards, set `type` to scheme, and send the encrpyted card fields. If you are fully PCI compliant, send the unencrypted card fields.
shopperName	The name of the card holder, consisting of `firstName` and `lastName`. If you do not include this field when requesting a name validation, we will fallback to the `paymentMethod.holderName`.
`paymentValidations.name.status`	Set to requested to request a name validation.

Apple Pay and Google Pay do not return the shopper name. For these payment methods, you must build your own logic to pass the details your shopper enters at checkout from your front-end to the /payments request.

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, we return the raw status value we received from the scheme in the paymentValidations.name.rawResponse.status field.

Mastercard does not return a status, so you do not receive a raw status value for Mastercard.

Adyen `status` values	Description	Visa `rawResponse.status` values
performed	Name validation was performed.	00
notPerformed	Name validation was not performed.	01
notSupported	Name validation is not supported by the issuer for this card, you will not be charged for name validation.	02

Outcome

The paymentValidations.name object in the response includes the name validation results in the following objects:

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.

Adyen `result` values	Visa `rawResponse` values	Mastercard `rawResponse` values	Description
`match`	01	A	The name matches the name on file at the issuing bank.
`partialMatch`	50	B	The name partially matches the name on file. For example, the first name matches but the last name does not, or there is a typo.
`noMatch`	99	C	The name does not match the name on file.

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