Configuring the cardholder document field
Learn how anti-fraud providers use the cardholderDocument field in the manifest to define whether the checkout requests an identification document from the cardholder.
When a customer pays with a credit or debit card, the store may request an identification document from the cardholder, such as the Social Security Number (SSN) in the United States or the Cadastro de Pessoas Físicas (CPF) in Brazil, in addition to the card number, cardholder name, expiration date, and CVV. Some payment providers use this document to authorize the transaction, and some anti-fraud providers use it to analyze the risk of fraud.
This document isn't always necessary. Some anti-fraud providers analyze transactions without it, the legislation of some countries discourages collecting this data, and some customers don't have a document that proves they own the card.
To give anti-fraud providers and merchants control over this behavior, the Anti-fraud Provider Protocol offers the cardholderDocument field in the provider manifest. This field defines whether the checkout requests the cardholder document and whether merchants can change this behavior.
Configuring this field involves two roles:
- Anti-fraud providers declare
cardholderDocumentin the connector manifest, as described in this guide. - Merchants choose whether to display the field at checkout, when the provider allows it. See Merchant-side cardholder document setting in the VTEX Admin.
Before you begin
Your connector must be integrated through the Anti-fraud Provider Protocol, so that you can edit the manifest returned by the List anti-fraud provider manifest endpoint.
When the manifest doesn't declare
cardholderDocument, VTEX requires the cardholder document in card transactions. If this is the behavior you want, you don't need to follow this guide.
Declaring the cardholder document field
To define how the checkout handles the cardholder document, follow these instructions:
- In the connector manifest, add the
cardholderDocumentfield with one of the values described in Accepted values. - Open a ticket with VTEX Support to request an update of your connector.
The following example declares a manifest that requires the cardholder document:
_10{_10 "cardholderDocument": "required",_10 "customFields": [_10 {_10 "name": "AnalysisMode",_10 "type": "text"_10 }_10 ]_10}
The manifest requires the
customFieldsarray, so keep it in the response even when your connector has no custom fields to declare.
Accepted values
| Value | Behavior at checkout and in My Cards | Merchants can change it |
|---|---|---|
required | The cardholder document field is displayed, and the customer must enter the document to place the order. | No |
optional | The cardholder document field is displayed according to the merchant configuration. Your connector uses the document in the analysis when the customer provides it. | Yes |
unused | The cardholder document field isn't displayed, and your connector analyzes transactions without this document. | No |
Only the optional value gives merchants the Cardholder document field option in the VTEX Admin. With required and unused, the behavior you declare in the manifest applies to every store that uses your connector.
Next steps
After VTEX updates your connector, validate the result:
- Confirm that the List anti-fraud provider manifest endpoint returns the expected
cardholderDocumentvalue. - Place a test order in a store that uses your connector and confirm that the checkout requests the cardholder document as expected. Changes may take up to 10 minutes to appear at checkout.
- If you declared
optional, ask the merchant to configure the Cardholder document field option, as described in Merchant-side cardholder document setting in the VTEX Admin.