API Overview

Recent Revisions to This Document

Payer Authentication Developer Guide

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:
- Mobile Device Data Collected
- Using the Android SDK
  - Updating the Gradle Build Properties
  - Configuring the Android SDK
  - Setting Up the Initial Request
- Using the iOS SDK
  - Downloading and Importing the SDK
  - Configuring Your Build Environment
  - Configuring the iOS SDK
  - Setting Up the Initial Request
- 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

Authentication Examples Using Primary Account Numbers
- Setting Up Device Data Collection
  - Required Fields for Device Data Collection
  - Optional Fields for Device Data Collection
  - Simple Order Example: Setting Up Device Data Collection
- Checking Enrollment in Payer Authentication
  - Required Fields for Checking Enrollment in Payer Authentication
  - Optional Fields for Checking Enrollment in Payer Authentication
  - Simple Order Example: Checking Enrollment
- Checking Enrollment and Authorizing in Payer Authentication
  - Required Fields for Checking Enrollment in Payer Authentication
- Validating a Challenge
  - Required Fields for Validating a Challenge
  - Optional Fields for Validating a Challenge
  - Simple Order Example: Validating a Challenge
- Validating and Authorizing a Transaction
  - Required Fields for Processing an Authorization Using Visa Secure
  - Optional Fields for Validating a Challenge
  - Simple Order Example: Validating and Authorizing an Authorization
- Non-Payment Authentication
  - Required Fields for Checking Enrollment in Payer Authentication

Examples Using 3-D Secure Data Only
- Visa Data Only
  - Required Fields for Visa Data Only
  - Simple Order Example: Testing Visa Data Only
  - Simple Order Example: Bundled Authentication and Authorization with Visa Data Only
- Mastercard Data Only
  - Required Fields for Mastercard Data Only
  - Simple Order Example: Mastercard Data Only
  - Simple Order Example: Bundled Authentication and Authorization with Mastercard Data Only

Authentication Examples Using Digital Payment (Google Pay)
- Setting Up Device Data Collection Using Digital Payment (Google Pay)
  - Required Fields for Device Data Collection
  - Optional Fields for Device Data Collection
  - Simple Order Example: Setting Up Device Data Collection When Using Google Pay
- 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
  - Simple Order Example: Checking Enrollment in Payer Authentication Using Google Pay
- Validating a Challenge Using Digital Payment (Google Pay)
  - Required Fields for Validating Payer Authentication
  - Optional Fields for Validating a Challenge
  - Simple Order Example: Validating a Challenge When Using Google Pay

Authentication Examples Using TMS Tokens
- Setting Up Device Data Collection with a TMS Token
  - Required Fields for Setting Up 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
- Validating a Challenge When Using a TMS Token
  - Required Fields for Validating a Challenge When Using a TMS Token

Authentication Examples Using 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
- Checking Enrollment When Using a Flex Microform Token
  - Required Fields for Checking Enrollment When Using a Flex Microform Token
- Validating a Challenge When Using a Flex Microform Token
  - Required Fields for Validating a Challenge When Using a Flex Microform Token

Authentication Examples Using Network Token/Tokenized Cards
- Setting Up Device Data Collection with a Network Token/Tokenized Card
  - Required Fields for Setting Up Device Data Collection with a Network Token/Tokenized Card
- Checking Enrollment with a Network Token/Tokenized Card
  - Required Fields for Checking Enrollment When Using a Network Token/Tokenized Card

Authentication Examples of 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
- 1b: Recurring Payments - Subsequent Transaction (Mastercard)
  - Required Fields for 3RI 1b: Recurring Payments - Subsequent Transaction (Mastercard)
- 2a: Installment - Customer Initiated Transaction (Mastercard)
  - Required Fields for 3RI 2a: Installment - Customer Initiated Transaction (Mastercard)
- 3a: Split/Partial Shipment (Mastercard)
  - Required Fields for 3RI 3a: Split/Partial Shipment (Mastercard)
- 3b: Split/Delayed Shipment (Visa)
  - Required Fields for 3RI 3b: Split/Delayed Shipment (Visa)
- 4a: Multi-Party Commerce or OTA (Visa)
  - Required Fields for 3RI 4a: Multi-Party Commerce or OTA (Visa)
- 4b: Multi-Party Commerce or OTA (MasterCard)
  - Required Fields for 3RI 4b: Multi-Party Commerce or OTA (MasterCard)
- 4c: Multi-Party Commerce or OTA (MasterCard)
  - Required Fields for 3RI 4c: Multi-Party Commerce or OTA (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
  - 2.7: Check Enrollment Error
  - 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
- Additional Test Cases
  - 1a: 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: TRA Exemption—Low Value: Mastercard EMV 3-D Secure 2.1 and 2.2
  - 3b: TRA—Low Value: Visa
  - 3c: TRA—Low Value: Discover
  - 4a: Trusted Beneficiary Prompt for Trustlist
  - 4b: Utilize Trusted Beneficiary Exemption
  - 5a: Visa Data Only
  - 5b: Identity Check Insights (ScoreRequest = Y)
- HTTP Status Codes

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

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

Finding Payer Authentication Transaction Details in the Smartpay Fuse Portal
- Searching for Transactions
- Storing Payer Authentication Data
- Searching for Payer Authentication Details
  - Enrolling a Card
    - Checking Enrollment
    - Authentication Validation
  - Card Not Enrolled
    - Transaction Details

Payer Authentication Reports
- Payer Authentication Summary Report
  - Download 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
  - PAReq Element
  - PARes Element
  - AuthInfo Element
  - Report Examples

Reason Codes

Glossary

On This Page

Setting Up Device Data Collection

The Setup service identifies the customer's bank and prepares for collecting data about the device that the customer is using to place the order.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.

Country-Specific Requirements

These fields are required for transactions in specific countries.

billTo_state: This field is required for transactions in the US, Canada, and Mainland China.
billTo_postalCode: This field is required when the
billTo_country
field value is
US
or
CA
.
invoiceHeader_ merchantDescriptorCountry: For Meeza transactions, this value must be set to
EG
if Egypt was not set as the country in the merchant configuration during merchant boarding.

Endpoint

Set the

payerAuthSetupService_run

field to

true

.

Send the request to:

Production:

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

Test:

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Back to top