1. TRU Security   
  2. EMV 3-D Secure

Visa Secure Data Field Mandate: Required Data Fields

​  Last updated: 

 

visa-secure_blu_2021.png

Visa Secure is Visa's EMV 3-D Secure authentication product that facilitates Strong Customer Authentication (SCA) for electronic payments.

Learn more about SCA and EMV 3-D Secure

  Merchants and partners using Trust Payments shopping cart plugins do not need to take any action because these plugins are already configured to provide this data.

  To support the payments ecosystem in realising the full benefits of EMV 3-D Secure authentication, Visa has mandated that merchants update their authentication requests (AReq/THREEDQUERY) messages to include the fields described below by 12 August 2024.

Failure to comply with this mandate may result in authentication failure, downgrades and the loss liability shift protection from Visa.

 

Please expand your solution from the list below for further info on how to update your requests:

Payment Pages

The steps you need to follow depends on how customer data is obtained for the transaction. Please refer to the solutions below:

  Walkthrough

How are the customer's billing details shared with Trust Payments?

I'm posting the billing details to Payment Pages  The customer enters billing details on Payment Pages

You will need to update your processes to obtain the new required fields on your side and have these included in the POST to the Payment Pages. The updated POST would look similar to this:

  Please be aware that billingemail AND/OR billingtelephone are required - you are welcome to submit either of these fields or both.
<html>
  <body>
    <form method="POST" action="<DOMAIN>/process/payments/choice">
      <input type="hidden" name="sitereference" value="test_site12345">
      <input type="hidden" name="stprofile" value="default">
      <input type="hidden" name="currencyiso3a" value="USD">
      <input type="hidden" name="mainamount" value="100.00">

      <!-- Posting the required billing fields -->
      <input type="hidden" name="billingfirstname" value="Jay">
      <input type="hidden" name="billinglastname" value="Doe">

      <!-- Post billingemail, billingtelephone or both -->
      <input type="hidden" name="billingemail" value="customer@email.com">
      <input type="hidden" name="billingtelephone" value="01234567890">

      <input type="hidden" name="version" value="2">
      <input type="submit" value="Pay">
    </form>
  </body>
</html>

Replace <DOMAIN> with a supported domain. Click here for a full list.

  Info on specifying required fields     Let's try something else

Please update your POST to Trust Payments to include strequiredfields as shown in the example below.

  The strequiredfields submitted ensure the customer cannot proceed to 3-D Secure authentication without including values for the fields required as part of this mandate.
<html>
  <body>
    <form method="POST" action="<DOMAIN>/process/payments/choice">
      <input type="hidden" name="sitereference" value="test_site12345">
      <input type="hidden" name="stprofile" value="default">
      <input type="hidden" name="currencyiso3a" value="USD">
      <input type="hidden" name="mainamount" value="100.00">

      <!-- Enforcing the required billing fields -->
      <input type="hidden" name="strequiredfields" value="billingfirstname">
      <input type="hidden" name="strequiredfields" value="billinglastname">

      <!-- Enforcing billing email and/or telephone fields -->
      <!-- Choose billingemail, billingtelephone or both -->
      <input type="hidden" name="strequiredfields" value="billingemail">
      <input type="hidden" name="strequiredfields" value="billingtelephone">

      <input type="hidden" name="version" value="2">
      <input type="submit" value="Pay">
    </form>
  </body>
</html>

Replace <DOMAIN> with a supported domain. Click here for a full list.

  Info on specifying required fields     Let's try something else

  1. You will need to update your CSS to remove the code that specifically hides those fields and upload the updated CSS using the File Manager.

  2. Then update your POST to Trust Payments to include strequiredfields as shown in the example below.

      The strequiredfields submitted ensure the customer cannot proceed to 3-D Secure authentication without including values for the fields required as part of this mandate.
    <html>
      <body>
        <form method="POST" action="<DOMAIN>/process/payments/choice">
          <input type="hidden" name="sitereference" value="test_site12345">
          <input type="hidden" name="stprofile" value="default">
          <input type="hidden" name="currencyiso3a" value="USD">
          <input type="hidden" name="mainamount" value="100.00">

          <!-- Enforcing the required billing fields -->
          <input type="hidden" name="strequiredfields" value="billingfirstname">
          <input type="hidden" name="strequiredfields" value="billinglastname">

          <!-- Enforcing billing email and/or telephone fields -->
          <!-- Choose billingemail, billingtelephone or both -->
          <input type="hidden" name="strequiredfields" value="billingemail">
          <input type="hidden" name="strequiredfields" value="billingtelephone">

          <input type="hidden" name="version" value="2">
          <input type="submit" value="Pay">
        </form>
      </body>
    </html>

    Replace <DOMAIN> with a supported domain. Click here for a full list.

  Info on the File Manager     Info on specifying required fields     Let's try something else

  1. If you are using one of the following stdefaultprofile configurations, the billing fields are hidden:

    CP25-EN.png

    st_paymentcardonly

    CP26-EN.png

    st_cardonly

    CP27-EN.png

    st_iframe_cardonly

    To ensure the billing fields are displayed, you should update your configuration to one of the following alternatives:

    CP23-EN.png

    default

    CP24-EN.png

    st_paymentcard

      Depending on how your site reference has been configured, changing your stdefaultprofile may require you to contact our Support Team. Please contact us if you're not sure.

  2. Then update your POST to Trust Payments to include strequiredfields as shown in the example below.

      The strequiredfields submitted ensure the customer cannot proceed to 3-D Secure authentication without including values for the fields required as part of this mandate.
    <html>
      <body>
        <form method="POST" action="<DOMAIN>/process/payments/choice">
          <input type="hidden" name="sitereference" value="test_site12345">
          <input type="hidden" name="stprofile" value="default">
          <input type="hidden" name="currencyiso3a" value="USD">
          <input type="hidden" name="mainamount" value="100.00">

          <!-- Enforcing the required billing fields -->
          <input type="hidden" name="strequiredfields" value="billingfirstname">
          <input type="hidden" name="strequiredfields" value="billinglastname">

          <!-- Enforcing billing email and/or telephone fields -->
          <!-- Choose billingemail, billingtelephone or both -->
          <input type="hidden" name="strequiredfields" value="billingemail">
          <input type="hidden" name="strequiredfields" value="billingtelephone">

          <input type="hidden" name="version" value="2">
          <input type="submit" value="Pay">
        </form>
      </body>
    </html>

    Replace <DOMAIN> with a supported domain. Click here for a full list.

  Info on stdefaultprofile     Info on specifying required fields     Let's try something else

  1. You will need to add either of the following to your HTML markup on the [stprofile]details.html page and re-upload to your site reference using the File Manager:

    Display required billing fields individually 
    {{st.billingfirstname.textfield}}
{{st.billinglastname.textfield}}
{{st.billingemail.textfield}}
{{st.billingtelephone.textfield}}
      Because billingemail OR billingtelephone fields are required, you can omit one of these fields if preferred.
    Display block of all billing fields 
    {{st.block.billingdetailsdiv}}

  2. Then update your POST to Trust Payments to include strequiredfields as shown in the example below.

      The strequiredfields submitted ensure the customer cannot proceed to 3-D Secure authentication without including values for the fields required as part of this mandate.
    <html>
      <body>
        <form method="POST" action="<DOMAIN>/process/payments/choice">
          <input type="hidden" name="sitereference" value="test_site12345">
          <input type="hidden" name="stprofile" value="default">
          <input type="hidden" name="currencyiso3a" value="USD">
          <input type="hidden" name="mainamount" value="100.00">

          <!-- Enforcing the required billing fields -->
          <input type="hidden" name="strequiredfields" value="billingfirstname">
          <input type="hidden" name="strequiredfields" value="billinglastname">

          <!-- Enforcing billing email and/or telephone fields -->
          <!-- Choose billingemail, billingtelephone or both -->
          <input type="hidden" name="strequiredfields" value="billingemail">
          <input type="hidden" name="strequiredfields" value="billingtelephone">

          <input type="hidden" name="version" value="2">
          <input type="submit" value="Pay">
        </form>
      </body>
    </html>

    Replace <DOMAIN> with a supported domain. Click here for a full list.

  Info on fields and blocks     Info on the File Manager     Info on specifying required fields     Let's try something else

 

  Please make changes on your test site reference and check they work before updating your live site reference!

Following any modifications, please perform a few test transactions to ensure that you are unable to complete the transaction unless the required fields are entered during the Payment Pages session. If successful, there are no further additional steps needed. Please ensure these changes are now made to your live site reference.

JavaScript Library

You will need to ensure the payload includes the following fields mandated by Visa (refer to the examples below):

Fields shown as "Required" below for this specific mandate may be subject to different requirements in our other documentation.
  Field Format Description
X2-EN.png billingemail Email (255)

The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).

Required if billingtelephone is NOT submitted, otherwise optional.
X1-EN.png billingfirstname Alphanumeric including
symbols (127)

The customer’s billing first name.
X1-EN.png billinglastname Alphanumeric including
symbols (127)

The customer’s billing last name.
X2-EN.png billingtelephone Alphanumeric including
symbols (20) 		The customer’s telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )

Required if billingemail is NOT submitted, otherwise optional.

  Open the field specification

 

(Payload)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "billingfirstname":"Jay",
    "billinglastname":"Doe",
    "billingemail":"customer@email.com",
    "billingtelephone":"01234567890",
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "sitereference":"test_site12345"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}
Android SDK / iOS SDK

You will need to ensure the payload includes the following fields mandated by Visa (refer to the examples below):

Fields shown as "Required" below for this specific mandate may be subject to different requirements in our other documentation.
  Field Format Description
X2-EN.png billingemail Email (255)

The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).

Required if billingtelephone is NOT submitted, otherwise optional.
X1-EN.png billingfirstname Alphanumeric including
symbols (127)

The customer’s billing first name.
X1-EN.png billinglastname Alphanumeric including
symbols (127)

The customer’s billing last name.
X2-EN.png billingtelephone Alphanumeric including
symbols (20) 		The customer’s telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )

Required if billingemail is NOT submitted, otherwise optional.

  Android SDK field specification      iOS SDK field specification

 

(Payload)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "billingfirstname":"Jay",
    "billinglastname":"Doe",
    "billingemail":"customer@email.com",
    "billingtelephone":"01234567890",
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "sitereference":"test_site12345",
    "termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}
3DS API

You will need to ensure the THREEDQUERY request includes the following fields:

  • billingfirstname
  • billinglastname
  • EITHER billingemail OR billingtelephone
  • browserscreenheight
  • browserscreenwidth
  • customerip
  Please be aware that billingemail AND/OR billingtelephone are required - you are welcome to submit either of these fields or both.

  We recommend that you review the full field specification for the THREEDQUERY request and check that all required fields are being submitted.

  Open the field specification

 

Frictionless - JSON Challenge - JSON Frictionless - XML Challenge - XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accept": "text/html,*/*",
    "accounttypedescription": "ECOM",
    "acquirerbin": "408912",
    "baseamount": "1050",
    "billingemail": "customer@email.com",
    "billingfirstname": "Jay",
    "billinglastname": "Doe",
    "billingtelephone": "01234567890",
    "browsercolordepth": "24",
    "browserjavaenabled": "false",
    "browserjavascriptenabled": "true",
    "browserlanguage": "en",
    "browserscreenheight": "864",
    "browserscreenwidth": "1536",
    "browsertz": "120",
    "cachetoken": "eyJkYXRhY2VudGVydXJsIjogImh0dHBzOi8vd2Vic2VydmljZXMuc2VjdXJldHJhZGluZy5uZXQiLCAiY2FjaGV0b2tlbiI6ICI1Ny04Y2RmNmY5MmZkY2MwMmZjZTY4YTUxYjc2NGQ5NTQxZDgzNDY5ZTFjMDIxMDJjNmM0NThmYWY5M2Q2MGQ1NWYyIn0=",
    "challengewindowsize": "02",
    "currencyiso3a": "GBP",
    "customerip": "1.2.3.4",
    "expirydate": "01/2038",
    "merchantnumber": "9990000001",
    "pan": "4900490000000501",
    "requesttypedescription": "THREEDQUERY",
    "sitereference": "test_3dsapi12345",
    "termurl": "https://webhook.site/8543eb65-e5c7-40fc-a475-a862a825a562",
    "threedscompind": "U",
    "threedstransactionid":"733ab129-1126-4b80-97a4-f3d8fee9c564",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36"
  }]
}

 

Visa has provided the following guidance regarding this mandate:

Consistent and high-quality data helps enhance business outcomes for merchants, cardholders and issuers

When merchants leverage authentication through Visa Secure, issuers are trusted to detect fraudulent transactions. Key data elements in every AReq/THREEDQUERY message are critical to supporting an issuer in making accurate risk assessments for successful authentications.

When merchants provide the below referenced fields in their AReq/THREEDQUERY messages, the following benefits can be achieved across the entire EMV 3DS ecosystem globally:

  • Merchants see an authentication success rate lift of +4% and an approval rate lift of +6%. (4,5)
  • Issuers can see a +65% fraud detection rate (FDR) lift. (6)

Visa Secure is designed to provide a frictionless experience for Visa cardholders. Enhanced data quality may deliver more seamless experiences, increased security confidence and fewer false declines to cardholders.

  • Cardholders receive a better experience through a +57% frictionless rate lift. (5)

(4) The dataset for these calculations contains 95% of Visa Secure global transactions that occurred during the months of February–March 2022. The uplift figures were generated by merchants based on the rate at which they populate the priority data elements and averaging their product performance. For more information, please refer to the global business cases in the Global—Better Data Best Practices Guide for Visa Secure, available in the Merchant Resources section of the Visa Secure Services Library.
(5) Based on merchants that populate more than 50% of the priority data elements.
(6) The dataset for this analysis contains Visa global transactions that were reported as fraud during the month of August 2021. The FDR performance uplift was calculated by comparing the performance of a Visa fraud detection model in the scenario when priority data elements were present versus when they were replaced by null or default values used in the risk-based authentication (RBA) model.

 

Required fields

Please ensure your system is updated to adhere to the following field specification:

  Merchants and partners that use external payment gateways and 3DS providers must contact their chosen payment gateways and 3DS providers to confirm how to ensure this data is provided.

Trust Payments
THREEDQUERY
Field name 		Visa
AReq
Field name 		Requirement Status Description
billingfirstname
XPath: /billing/name/first 		Cardholder Name Required (Browser / In-App) The customer’s billing first name.
billinglastname
XPath: /billing/name/last 		Cardholder Name Required (Browser / In-App) The customer’s billing last name.
billingemail
XPath: /billing/email 		Cardholder Email Address Conditional (Browser / In-App)

The customer’s billing email address.

Maximum length of 255 (maximum of 64 characters before the ”@” symbol).

Required when billingtelephone is not submitted.
billingtelephone
XPath: /billing/telephone 		Cardholder Phone Number Conditional (Browser / In-App)

The customer’s telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )

Required when billingemail is not submitted.
customerip
XPath: /customer/ip 		Browser IP Address Required (Browser)

Payment Pages & JS Library: Trust Payments collects and provides this data.

3DS API: Must be collected and provided by merchant or partner.
N/A Device IP Address Required (In-App)

Common Device Identification Parameters

Mobile SDK: Trust Payments collects and provides this data
browserscreenheight
XPath: /customer/browserscreenheight 		Browser Screen Height Recommended (Browser)

Payment Pages & JS Library: Trust Payments collects and provides this data.

3DS API: Must be collected and provided by merchant or partner.
browserscreenwidth
XPath: /customer/browserscreenwidth 		Browser Screen Width Recommended (Browser)

Payment Pages & JS Library: Trust Payments collects and provides this data.

3DS API: Must be collected and provided by merchant or partner.
billingpremise
XPath: /billing/premise 		N/A Recommended The first line of the customer's billing address.
billingstreet
XPath: /billing/street 		N/A Recommended The second line of the customer's billing address.
billingtown
XPath: /billing/town 		N/A Recommended The town entered for the customer’s billing address.
billingcounty
XPath: /billing/county 		N/A Recommended

The county entered for the customer’s billing address. For US addresses, the state would be entered in this field. Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
billingpostcode
XPath: /billing/postcode 		N/A Recommended The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
billingcountryiso2a
XPath: /billing/country 		N/A Recommended

The country for the customer’s billing address. This will need to be in ISO2A format.

Click here for a full list of country codes.
Was this article helpful?
0 out of 0 found this helpful
Avatar
Michael Buckley

 

Further reading on this topic