API Overview

Recent Revisions to This Document

Payer Authentication Developer Guide
- VISA Platform Connect: Specifications and Conditions for Resellers/Partners

Introduction to Payer Authentication
- Why Payer Authentication Is Needed
- EMV 3-D Secure 2.0
- Payer Authentication Customer Workflow
- Payer Authentication Merchant Workflow
- Acquirer Information
- Enable Merchant Account for EMV 3-D Secure
- Payer Authentication Configuration Testing
- Request Endpoints
- Payer Authentication Integrations

Implementing Direct API for Payer Authentication
- Prerequisites
- After Implementation and Before Go Live

Step 1: Setup Service
- Request Fields
- Important Response Fields

Step 2: Device Data Collection
- Which Device Data is Collected
- Building the Iframe
- Initiating the Device Data Collection Iframe
- Submitting the Device Data Collection Iframe
- Receiving the Device Data Collection URL Response

Step 3: Payer Authentication Check Enrollment Service
- Request Fields
- Interpreting the Check Enrollment Response
- Important Response Fields

Step 4: Step-Up Iframe
- Building the Iframe Parameters
- Creating the Iframe
- Invoking the Iframe
- Receiving the Step-Up Results

Step 5: Payer Authentication Validation Service
- Request Fields
- Interpreting the Validation Response
- Redirecting Customers to Pass or Fail Message Page

Combining the Authentication and the Authorization Services
- Combining Check Enrollment and the Authorization Services
  - Check Enrollment Response Fields and Their Equivalent Authorization Request Fields
- Combining the Validation and the Authorization Services
  - Validation Fields and their Equivalent Authorization Fields

Implementing SDK Payer Authentication
- Implementation Overview
- Process Flow for SDK Integration
- Prerequisites for SDK Implementation
  - Credentials/API Keys
    - Generating your API Key:
- What Mobile Device Data is Collected
- Using the Android SDK
  - Updating the Gradle Build Properties
  - Configuring the Android SDK
  - Setting Up the Initial Call
- Using the iOS SDK
  - Downloading and Importing the SDK
  - Configuring Your Build Environment
  - Configuring the iOS SDK
  - Setting Up the Initial Call
- Running Payer Authentication with SDK
  - Requesting the Check Enrollment Service (SDK)
  - Interpreting the Response
  - Authenticating Enrolled Cards
    - Calling Cardinal.cca_continue (Android SDK)
    - Calling Cardinal session continue (iOS SDK)
    - Receiving the Authentication Results
  - Requesting the Validation Service
    - Interpreting the Response
    - Redirecting Customers to the Message Page

Payer Authentication Examples
- Setting Up Device Data Collection
  - Required Fields for Device Data Collection
  - Optional Fields for Device Data Collection
  - REST Example: Setting Up Data Collection
- Setting Up Device Data Collection Using Digital Payment (Google Pay)
  - Required Fields for Device Data Collection
  - Optional Fields for Device Data Collection
  - REST Example: Setting Up Device Data Collection When Using Digital Payment (Google Pay)
- Checking Enrollment in Payer Authentication
  - Required Fields for Checking Enrollment in Payer Authentication
  - Optional Fields for Checking Enrollment in Payer Authentication
  - REST Example: Checking Enrollment
- Checking Enrollment in Payer Authentication Using Digital Payment (Google Pay)
  - Required Fields for Checking Enrollment in Payer Authentication
  - Optional Fields for Checking Enrollment in Payer Authentication
  - REST Example: Checking Enrollment in Payer Authentication Using Google Pay
- Validating a Challenge
  - Required Fields for Validating a Challenge
  - Optional Fields for Validating a Challenge
  - REST Example: Validating a Challenge
- Validating a Challenge Using Digital Payment (Google Pay)
  - Required Fields for Validating a Challenge
  - Optional Fields for Validating a Challenge
  - REST Example: Validating a Challenge When Using Google Pay
- Validating and Authorizing a Transaction
  - Required Fields for Processing an Authorization Using Visa Secure
  - Optional Fields for Validating a Challenge
  - REST Example: Validating and Authorizing a Transaction
- Non-Payment Authentication
  - Required Fields for Checking Enrollment in Payer Authentication
  - REST Example: Checking Enrollment for Non-Payment Authentication
- Authentication with TMS Tokens
  - Setting Up Device Data Collection with a TMS Token
    - Required Fields for Setting Up Data Collection When Using a TMS Token
    - REST Example: Setting Up Device Data Collection When Using a TMS Token
  - Checking Enrollment When Using a TMS Token
    - Required Fields for Checking Enrollment in Payer Authentication While Using a TMS Token
    - REST Example: Checking Enrollment When Using a TMS Token (Frictionless)
    - REST Example: Checking Enrollment When Using a TMS Token (Challenge)
  - Validating a Challenge When Using a TMS Token
    - Required Fields for Validating a Challenge When Using a TMS Token
    - REST Example: Validating a Challenge When Using a TMS Token
- Authentication with Flex Microform Tokens
  - Setting Up Device Data Collection When Using a Flex Microform Token
    - Required Fields for Setting Up Device Data Collection When Using a Flex Microform Token
    - REST Example: Setting Up Device Data Collection When Using a Flex Microform Token
  - Checking Enrollment When Using a Flex Microform Token
    - Required Fields for Checking Enrollment When Using a Flex Microform Token
    - REST Example: Checking Enrollment When Using a Flex Microform Token (Challenge)
  - Validating a Challenge When Using a Flex Microform Token
    - Required Fields for Validating a Challenge When Using a Flex Microform Token
    - REST Example: Validating a Challenge When Using a Flex Microform Token
- Authentication with Tokenized Cards
  - Setting Up Device Data Collection with a Tokenized Card
    - Required Fields for Setting Up Device Data Collection with a Tokenized Card
    - REST Example: Setting Up Device Data Collection When Using a Tokenized Card
  - Checking Enrollment with a Tokenized Card
    - Required Fields for Checking Enrollment When Using a Tokenized Card
    - REST Example: Checking Enrollment When Using a Tokenized Card (Frictionless)
- Merchant-Initiated Transactions
  - Challenge Reponses to 3RI Transactions
  - Network-Specific Values for 3RI
  - 1a: Initial Recurring Transaction
    - Required Fields for 3RI 1a: Initial Recurring Transaction
    - REST Example: Checking Enrollment for a 3RI Initial Recurring Transaction
    - REST Example: Validating the Challenge for a 3RI Initial Recurring Transaction
  - 1b: Recurring Payments - Subsequent Transaction (Mastercard)
    - Required Fields for 3RI 1b: Recurring Payments - Subsequent Transaction (Mastercard)
    - REST Example: Validating the Challenge for 3RI Subsequent Installment Transactions
  - 2a: Installment - Customer Initiated Transaction (Mastercard)
    - Required Fields for 3RI 2a: Installment - Customer Initiated Transaction (Mastercard)
    - REST Example: Checking Enrollment for a 3RI Customer Initiated Total Installments (Mastercard)
    - REST Example: Validating the Challenge for a 3RI Customer Initiated Total Installments (Mastercard)
  - 3a: Split/Partial Shipment (Mastercard)
    - Required Fields for 3RI 3a: Split/Partial Shipment (Mastercard)
    - REST Example: Checking Enrollment for 3RI Split Shipment Transaction (Mastercard)
  - 3b: Split/Delayed Shipment (Visa)
    - Required Fields for 3RI 3b: Split/Delayed Shipment (Visa)
    - REST Example: Checking Enrollment for 3RI Split Shipment Transaction (Visa)
  - 4a: Multi-Party Commerce or OTA (Visa)
    - Required Fields for 3RI 4a: Multi-Party Commerce or OTA (Visa)
    - REST Example: Checking Enrollment for 3RI Multi-Party Commerce Transaction (Visa)
  - 4b: Multi-Party Commerce or OTA (MasterCard)
    - Required Fields for 3RI 4b: Multi-Party Commerce or OTA (MasterCard)
    - REST Example: Checking Enrollment for 3RI Multi-Party Commerce Transaction (Mastercard)
    - REST Example: Validating the Challenge for 3RI Multi-Party Commerce Transaction (Mastercard)
  - 4c: Multi-Party Commerce or OTA (MasterCard)
    - Required Fields for 3RI 4c: Multi-Party Commerce or OTA (MasterCard)
    - REST Example: Checking Enrollment for 3RI Multi-Party Commerce Transaction (Mastercard)

Testing Payer Authentication
- Testing Process
  - Enrollment Check Response Fields
  - Authentication Validation Response Fields
- Test Cases for 3-D Secure 2.x
  - 2.1: Frictionless Authentication Is Successful
  - 2.2: Frictionless Authentication Is Unsuccessful
  - 2.3: Stand-In Frictionless Authentication is Attempted
  - 2.4: Frictionless Authentication Is Unavailable
  - 2.5: Frictionless Authentication Is Rejected
  - 2.6: Authentication Is Not Available when Checking Enrollment
  - 2.7: Error Occurs when Checking Enrollment
  - 2.8: Time Out
  - 2.9: Step-Up Authentication Is Successful
  - 2.10: Step-Up Authentication Is Unsuccessful
  - 2.11: Step-Up Authentication Is Unavailable
  - 2.12: Error During Authentication
  - 2.13: Authentication Is Bypassed
  - 2.14: Require Method URL
- Payer Authentication Exemption Test Cases
  - 1a: Initial/First Recurring Transaction: Fixed Amount
  - 2a: Card Authentication Failed
  - 2b: Suspected Fraud
  - 2c: Cardholder Not Enrolled in Service
  - 2d: Transaction Timed Out at the ACS
  - 2e: Non-Payment Transaction Not Supported
  - 2f: 3RI Transaction Not Supported
  - 3a: Transaction Risk Analysis Exemption: Low Value: Mastercard EMV 3-D Secure 2.1 and 2.2
  - 3b: Transaction Risk Analysis: Low Value: Visa
  - 3c: Transaction Risk Analysis: Low Value: Discover
  - 3d: Acquirer Transaction Risk Analysis: Cartes Bancaires
  - 4a: Trusted Beneficiary Prompt for Trustlist
  - 4b: Utilize Trusted Beneficiary Exemption
  - 5a-1: Identity Check Insights (ScoreRequest = N)
  - 5a-2: Identity Check Insights (ScoreRequest = Y)
- HTTP Status Codes

Website Modification Reference
- Website Modification Checklist
- EMV 3-D Secure Services Logos
- Informational Message Examples

Alternate Methods for Device Data Collection
- Device Data Collection Overview
  - Prerequisites
  - Endpoints
- Collecting Device Data
  - Card BIN in JWT
  - Card BIN as a POST Parameter Plus JWT

Upgrading Your Payer Authentication Implementation
- Benefits
- PSD2 Impact
  - Mandates
- Recommended Integration
- Migrating from EMV 3-D Secure 1.x to 2.x FAQ

Payer Authentication Transaction Details in the Business Center
- Payer Authentication Search
- Storing Payer Authentication Data
- Searching for Payer Authentication Details
  - Enrolled Card
    - Enrollment Check
    - Authentication Validation
  - Card Not Enrolled
    - Transaction Details

Payer Authentication Reports
- Payer Authentication Summary Report
  - Downloading the Report
  - Matching the Report to the Transaction Search Results
  - Interpreting the Report
  - Comparing Payer Authentication and Payment Reports
- Payer Authentication Detail Report
  - Report Element
  - PayerAuthDetail Element
  - ProofXML Element
  - VEReq Element
  - VERes Element
  - PAReq Element
  - PARes Element
  - AuthInfo Element
  - Report Examples

Glossary

REST Example: Validating a Challenge When Using Google Pay

Request

{ 
  "orderInformation": {
      "amountDetails": {
      "currency": "USD",
      "totalAmount": "200.00
      }, 
   "lineItems": [ {         
      "unitPrice": "10",
      "quantity": "2", 
      "taxAmount": "32.40"       
      } ]  
 }, "paymentInformation": {
      "card": {      
         "type": "002",       
         "expirationMonth": "12",       
         "expirationYear": "2025",
         "number": "5200000000000007"     
         },     
     "fluidData": {      
         "value":"XFx1MDAzZFwiLFwia2V5RXhwaXJhdGlvblwiOlwiMTYzMDUxNjYyODA0OVwifSIsInNpZ25hdHVyZXMiOlsiTUV
                  VQ0lRRHlTQTV1T2t5UXQ5cFoyQlEzaXBmcGNWT0F5ZmIzM2ozUEZPQUw3K1o5S3dJZ2FjWWp2YWJpTEUyWHFkNU1
                  xNGphNStEVldoREttVHpoMmk1RGlnbllFQndcdTAwM2QiXX0sInByb3RvY29sVmVyc2lvbiI6IkVDdjIiLCJzaWduZW
                  RNZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwiWG5qOGxSSWhGMDVEWWdRK3hwNEE5YUhsVGE1U
                  2ljdUJac2w1L2NNRkJlclBBY1RzaE4zRFlOb1MvdEVkRkRYRzZJRXBpVlcxVnV6OUprejNWWGdpMzJrT21EVk9aakJ
                  NWTFvVHdTQnA5WG53ejlLYUtOekYvRFBSTy9jbStobW9iZ2dSdmxGSStOekN5U1VNWW1hbTJjZFUyZGRZWmZH
                  ck9nZWNSc3FrdW1tNmlMa0xGQTFJcDFrNWFRV21EUElEdTh1SnNmbWs4bzMyMlpteVdMMVVWenE0WHFkNT
                  ZScXZoL1VFeEp3RC9HZXU5SW00M0pmblZqckVkeDE0Ykx1OUpm"     
         }   
      },
      "consumerAuthenticationInformation": {     
         "authenticationTransactionId": "PYffv9G3sa1e0CQr5fV0"   
      } 
 }

Response to a Successful Request

{    
   "clientReferenceInformation": {
     "code": "1675288043120"
   },
   "consumerAuthenticationInformation": {
     "indicator": "internet",
     "ucafCollectionIndicator": "0",
     "strongAuthentication": {
     "OutageExemptionIndicator": "0"
     },
   "token": "AxjzbwSTbhMKrRswWTYSABECT9u+QBvfSB84gL2IZNJMvRiyubWAOAAA+Qxb"
    },
   "id": "6752880430346470503954",
   "status": "AUTHENTICATION_SUCCESSFUL",
   "submitTimeUtc": "2023-02-01T21:47:23Z"
}

Back to top