On This Page

Recent Revisions to This Document

25.09.02

Updated XID Values
The Test Cases for
3-D Secure
 2.x section were updated to better reflect which card schemes returned XID values during Enrollment and Validation. See Test Cases for
3-D Secure
 2.x.
Updated ECI String and ECI Raw Values for ITMX
The Test Cases for
3-D Secure
 2.x section were updated to include ECI string and raw values for ITMX. See Test Cases for
3-D Secure
 2.x

25.09.01

This revision contains only editorial changes and no technical updates.

25.07.01

Updated Content
Removed the section
Upgrading Your Payer Authentication Implementation
 that was no longer needed.
eftpos
 Test Card Numbers
Added eftpos card numbers for the
3-D Secure
 2.x test cases. These new card numbers are in addition to the existing co-badged eftpos card numbers. See Test Cases for 3-D Secure 2.x.
Reason Codes for Payer Authentication Transactions
Added reason codes that pertain to payer authentication. See Reason Codes.

25.05.01

Updated China UnionPay References
Consolidated references to China UnionPay and UnionPay International to "China UnionPay."

25.04.01

New Data Only Examples
Added a section with examples for Visa Data Only and Mastercard Data Only. See Examples Using 3-D Secure Data Only.
New Visa Data Only Test Case
Added a Visa Data Only test case to the Additional Test Cases section. See 5a: Visa Data Only.
Removed Outdated Report Elements
Removed references from the Payer Auth Detail Report section to elements from
3-D Secure
 1.0. See PayerAuthDetail Element.
11 Browser Elements Listed
Added a list of the 11 browser elements required to ensure a liability shift. See Step 3: Payer Authentication Check Enrollment Service.
Updated ECI Check Enrollment Values
Updated the Check Enrollment ECI values tables for the Additional Test Cases. See Additional Test Cases.

25.03.01

Updated UnionPay test card numbers
Card numbers were added for testing authentication with China UnionPay. See Test Cases for 3-D Secure 2.x.
Documentation Hub Link Fix
Fixed spacing error for documentation hub link. See the introduction.
Broken Links Fixed
Several dead links were fixed.
Reorganized Use Case Examples
Some of the use case examples were reorganized to fix a spacing issue occurring in the HTML version. See Authentication Examples Using Primary Account Numbers.

24.08

New Test Case
A 3-D Secure test case for verifying system behavior when a system error prevents authentication. See 2.13: Authentication Is Bypassed.
New Card Type Added for Test Card Numbers
The eftpos card type was added to the 3-D Secure test cases. See Test Cases for 3-D Secure 2.x.

Payer Authentication Developer Guide

This section describes how to use this guide and where to find further information.
Audience and Purpose
This guide is written for merchant application developers who want to use the
Simple Order
 API to integrate payer authentication services into their system. It describes the tasks you must perform in order to complete this integration.
Implementing payer authentication services requires software development skills.
Scope
This guide describes how to use the
Simple Order
 API to integrate payer authentication services with your order management system. It does not describe how to get started using the
Simple Order
 API nor does it explain how to use services other than payer authentication. For that information, see the
Related Documentation
 section.
Conventions
These special statements are used in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
A
Warning
 contains information or instructions, which, if not followed, can result in a security risk, irreversible loss of data, or significant cost in time or revenue.
Related Documentation
Visit the Technical Documentation Hub to find additional documentation.
Customer Support
For support information about any service, visit the Support Center:
Cybersource customer support.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for
Visa Platform Connect
 (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE
Visa Platform Connect
 ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT
Visa Platform Connect
 ACQUIRER.

Introduction to Payer Authentication

Cybersource
 has a variety of products to manage and minimize the risk of fraud that merchants face in their daily transactions. While these risk management products can operate independently to address specific areas of risk, the best results are achieved when the entire suite of products works in concert to detect patterns of fraud in a business’s online activity.
  • Payer Authentication: Uses the
    3-D Secure
     protocol in online transactions to verify that payment is coming from the actual cardholder. Most transactions can be authenticated without the customer being aware of the process, but higher risk transactions might require an exchange of one-time passwords (OTPs) during authentication. This authentication of the payer before the transaction is authorized benefits the merchant by shifting chargeback liability from the merchant to the card issuer.
    You can use Decision Manager with payer authentication services so that the risk level of an order determines when to invoke payer authentication. For example, low-risk orders can be set to skip payer authentication and proceed directly to authorization.
  • Decision Manager: Uses AI to help large enterprises analyze the vast amount of data from their online transactions to detect known patterns of fraudulent behavior. Each potential transaction can be compared to past patterns and automatically assigned a risk score before authorizing a transaction. Behavior analysis of past transaction data enables you to recommend rules that identify risky transactions and to suggest how to handle them. Machine learning capabilities in Decision Manager enable you to create hypothetical environments to test strategies for dealing with risky scenarios so that you can either reject them or require payer authentication.
  • Fraud Management Essentials: helps small-to-medium businesses monitor their online transactions using AI and preconfigured rules to spot and avoid fraudulent transactions. You can adjust the fraud detection settings to match your risk tolerance and manually review transactions flagged for risk review.
  • Account Takeover Protection: monitors customer account activity to detect compromised accounts. You create account events and define rules to determine the types and levels of activity in a customer account that trigger a manual review for potential fraud. The activity data that happens within a customer account can be easily integrated into Decision Manager and used to assess risky payment behavior.
This guide documents the payer authentication aspect of fraud management and how payer authentication can be used to satisfy the Strong Customer Authentication (SCA) requirement of the Payment Services Directive (PSD2) that applies to the European Economic Area (EEA) and the United Kingdom. SCA requires banks to perform additional verification when customers make payments to confirm their identity. Access to the documentation for other aspects of the risk management portfolio requires a
Cybersource
 support license for that product.
Transactions where the card is not present have a high risk of fraud, so authenticating a payer before processing a transaction greatly reduces the merchant risk for chargebacks. Payer authentication is a way of verifying that a customer making an e-commerce purchase is the owner of the payment card being used. The protocol that is followed to authenticate customers during online transactions is called EMV 3-D Secure.
This EMV
3-D Secure
 protocol is used by all major payment cards to implement payer authentication, but payment companies usually brand it under a different name:
  • Visa: Visa Secure
  • Mastercard: Mastercard Identity Check
  • American Express: American Express SafeKey
  • JCB: J/Secure
  • Discover/Diners: ProtectBuy
  • Elo: Compra Segura (Secure Shopping)
  • Cartes Bancaires: FAST’R
  • China UnionPay:
    3-D Secure

Supported Card Networks

These card networks support using EMV
3-D Secure
 during transactions:
  • Amex
  • Cartes Bancaires
  • China UnionPay
  • Discover/Diners
  • eftpos
  • Elo
  • JCB
  • Mada
  • Mastercard
  • Visa

Why Payer Authentication Is Needed

As e-commerce developed, the number of fraudulent transactions also grew, taking advantage of the difficulty authenticating a cardholder during a transaction when the card is not present. To create a standard for secure payment card processing, Europay, Mastercard, and Visa collaborated as EMV. Other card providers wanted input on creating new payment standards, so a consortium called EMVCo was formed to enable equal input from Visa, Mastercard,
JCB,
China UnionPay,
Discover,
 and American Express.
EMVCo developed
3-D Secure
 as the protocol to provide customer authentication during an online transaction. EMV
3-D Secure
 reduced chargebacks to merchants, and when the buyer was authenticated, the issuing bank assumed any liability when a chargeback occurred.
The same need to reduce fraud prompted Europe to develop a standard called Strong Customer Authentication (SCA) to regulate authentication during electronic payments. The use of SCA is mandated by the European Banking Authority in the Payment Services Directive (PSD2) that took effect in 2018 to promote and regulate the technical aspects of financial transactions between merchants and their customers in Europe. SCA requires two-factor authentication. A customer must be able to authenticate by providing two of these three factors:
  • Something the customer knows (such as a password, PIN, or challenge questions)
  • Something the customer has (such as a phone or hardware token)
  • Something the customer is (biometric data, such as fingerprint or face recognition)
Although SCA is required for almost all online transactions, some exceptions are allowed. If a payment is considered low risk, you can request an exemption from SCA to bypass authentication of the customer. The issuing bank must approve the exemption before the transaction can be exempted from SCA. Although an exemption from SCA results in a frictionless transaction, liability is not shifted to the issuing bank, and the merchant assumes responsibility for any chargeback that occurs. An exemption from SCA might apply to these types of transactions:
  • Payer authentication is unavailable because of a system outage.
  • Payment cards used specifically for business-to-business transactions are exempt.
  • Payer authentication is performed outside of the authorization workflow.
  • Follow-on installment payments of a fixed amount are exempt after the first transaction.
  • Follow-on recurring payments of a fixed amount are exempt after the first transaction.
  • Fraud levels associated with this type of transaction are considered a low risk.
  • Low transaction value does not warrant SCA.
  • Merchant-initiated transactions (MITs) are follow-on transactions that are also exempt.
  • Stored credentials were authenticated before they were stored, so stored credential transactions are exempt.
  • Trusted merchants registered as trusted beneficiaries, are exempt.
For additional information about transactions that are exempt from SCA, see the Payments Developer Guide.
EMV
3-D Secure
 meets the SCA mandate for authenticating the customer during e-commerce transactions.

EMV
3-D Secure
 2.0

To improve the customer experience, a new version of
3-D Secure
 was developed. EMV
3-D Secure
 2.x uses a less intrusive process to authenticate a buyer, which provides a better customer experience.
Enhancements to
3-D Secure
 2.x include:
  • More robust device data collection to improve risk analysis by the issuing bank.
  • Small screens that pop up on your webpage to avoid full-page redirects.
  • SDK version for mobile devices like phones and tablets.
  • Streamlined shopping experience.
On September 25, 2024, support for EMV
3-D Secure
 2.1.0 ended. Merchants and their acquirers must support EMV
3-D Secure
 2.2.0 or a later version before that date so that transactions can continue without any interruption in service. Contact support for additional information on updating your system to use EMV
3-D Secure
 2.2.0.

Payer Authentication Customer Workflow

During authentication for each transaction, data is collected about the customer's device, and the shipping and billing information is compared with transaction history. The workflow in payer authentication can go one of two possible ways: frictionless and challenge (also known as
step-up
).

Figure:

Payer Authentication Workflow
Payer Authenticatiion Workflow Diagram

Frictionless Workflow

With frictionless flow, the authentication process is not visible to the customer. The data collected during the transaction matches the data collected from past transactions with the customer. The risk for fraud is calculated to be low enough that further authentication is unnecessary. The transaction can continue to authorization.
  1. The customer enters card information at checkout. Information about the device being used by the customer and shopping behavior is collected and relayed from the merchant to the issuing bank. A delay of about 10 seconds is built into the process to ensure that the device data can be transmitted and assessed before the
    Buy
     option is enabled.
  2. The customer selects
    Buy
    .
  3. The issuing bank verifies the information it receives against previous transactions. If the device data correlates with the information, the transaction is approved without the buyer having to provide any additional information.

Challenge Workflow

A challenge flow occurs when the data collected during the transaction does not match the information on file from previous transactions with the customer. This process occurs for multiple reasons and does not necessarily mean that the customer has fraudulent intent. For example, it could occur because the customer got a new device that has not been registered yet or because they bought something while traveling. The issuer of the card decides whether further authentication of the customer is required and if necessary, requests that the customer prove their identity by returning a passcode to the issuer. This sequence describes the interaction from the customer viewpoint.
  1. The customer enters card information at checkout. Information about the customer's device is collected and sent from the merchant to the issuing bank.
  2. The customer selects
    Buy
    .
  3. The issuing bank assesses risk by comparing the information it receives to information on file from previous transactions with the customer. If the device data does not match the information collected previously, the issuer requests further authentication.
  4. A small window opens on the checkout page where a message from the bank asks if the customer wants to use email or text message to receive a one-time password (OTP) from the bank.
  5. The customer chooses how the password is sent.
  6. The issuer sends an OTP to the account on file for the customer.
  7. A window opens on the checkout page on the customer device prompting the customer to enter the OTP sent by the issuer.
  8. The customer enters the password that they received and sends it back to the issuer.
  9. If the password entered by the customer matches the password sent by the issuer, the customer is authenticated, and the transaction can proceed to authorization. If the password does not match the password that the bank sent, the customer receives a message that the transaction is declined and that they should attempt another form of payment.

Payer Authentication Merchant Workflow

Transaction circumstances might result in differences to the more detailed payer authentication process described below.
  1. Before the
    Buy
     button is selected at checkout, the Setup service is called. The full card number identifies how to contact the issuing bank. The issuing bank sends an access token and a URL (called the
    DCC URL
    ) to use for the data collected about the device where the transaction is occurring.
  2. The merchant collects data about the device and includes billing and shipping information. The merchant posts this data to a hidden 10 pixel x 10 pixel iframe to send to the DDC URL provided by the card issuer for comparision with past transactions. After the data points are collected and sent, the issuing bank confirms that data collection ended and the
    Buy
     button is enabled. An 8-10 second delay ensures enough time for data collection.
  3. Clicking
    Buy
     triggers the Check Enrollment service sending the order data (and session ID) to the issuer. If the bank is not part of an EMV
    3-D Secure
     program, the payer authentication process stops. If the issuing bank is part of an EMV
    3-D Secure
     program, the device data is compared to information on file collected at the bank during previous transactions with the cardholder.
    • The issuer's risk analysis software determines whether enough data points collected by the merchant match the data in the bank's files. If the data matches well, no further interaction is needed. This is called
      frictionless flow
       because no challenge to the buyer is necessary. The response returned to the merchant includes a payload with values like the
      ECI
      ,
      CAVV
      ,
      DS Transaction Id
      , and the
      PARes Status
      . These values must be passed on during the request for authorization. It is important to note that while frictionless flow can occur because the payer is authenticated, it can also occur for other reasons. For example, the issuing bank does not participate in payer authentication. Therefore, response values must be verified to determine why no step-up is needed.
    • If a significant discrepancy occurs between the transaction data and the data on file with the bank, the bank requests that the payer authenticate. This is a friction workflow and is called a
      step up
       or
      challenge
      . The response from the bank contains the same values returned for a frictionless workflow but also includes additional values like the
      Access Control Server (ACS) URL
      , the
      PAReq
       payload, a
      Pares Status
       = C, a
      Step Up URL
      , a new
      JWT
      , and a
      Transaction Id
      .
  4. The JWT and the step up URL received in the check enrollment response are returned to the customer. Using the step up URL with the JWT as a POST parameter, a challenge screen opens in a viewable iframe on the buyer's device so that the cardholder can view and respond to the bank challenge. The challenge consists of the bank sending a pass code that the customer returns to the bank. The challenge asks how the customer wants to receive a pass code, by text or email. After the customer chooses, they receive a pass code that they must enter into the challenge screen.
  5. After the cardholder enters and sends the passcode, the response is sent to the merchant's return URL contained in the JWT. This response causes the merchant to make a validation call to the bank to obtain the final authentication outcome. The response to this validation request contains the final authentication results including these values:
    ECI
    ,
    CAVV
     (if successful),
    DSTransactionId
    ,
    ThreeDSVersion
    , and PARes Status (
    Y
     or
    A
     = successful or
    N
    ,
    U
    ,
    R
     = failed, unavailable, or rejected).
  6. The next action depends on the outcome:
    • Successful: proceed to authorization, and append the EMV
      3-D Secure
       data points to the authorization message.
    • Failed, unavailable, or rejected: display a message to prompt the customer to try payment with a different card.

Acquirer Information

To properly configure payer authentication,
Cybersource
 uses three items of information
that your acquiring bank uses
 to manage payments for your account.
If you do not know this information, contact your acquiring bank
Cybersource
.
  • Acquiring
    Merchant ID
     (MID): This unique identifier for your business account is assigned by your acquiring bank or payment processor. A MID consists of 8-24 alpha-numeric characters. The MID can be different than the business deposit identifier used in settlements.
  • Acquiring
    Bank Identification Number
     (BIN): This unique number is assigned to the acquiring bank by a payment card network to identify that bank when settling transactions. Each payment card assigns its own BIN for an acquiring bank, and the BINs have their own unique characteristics. For example, all Visa BINs start with a 4, Mastercard BINs start with a 2 or 5
    , and Discover BINs start with a 3 or 6
    .
  • Merchant Category Code (MCC): This four-digit numeric value is assigned by the acquirer to the merchant to classify the merchandise or services provided by the business. The MCC indicates the kind of business transaction that the merchant processes.

Enable Merchant Account for EMV
3-D Secure

Partners and merchants use the
Business Center
 to go online and view transaction activity and to generate reports about their transactions.
For each partner, an account is created, and a portfolio merchant ID (MID) is assigned. For each of the merchants within the partner's portfolio, an account is also created and assigned a merchant ID (MID). Access to the various functions in the
Business Center
 is managed by the partner through the MID.
When the MID account is created, the various services that the merchant needs must be enabled. For more information about configuring your account in the
Business Center
 for payer authentication and other services, see the Merchant User Boarding Guide. Payer authentication is a service that might need to be turned on by support. To set up an account for payer authentication, you need this information:
  • MID.
  • Merchant website URL.
  • Two-character ISO code for your country.
  • Merchant category code.
  • EMV
    3-D Secure
     requestor ID (optional).
  • EMV
    3-D Secure
     requestor name (optional).
  • Name of merchant's bank.
  • Name, address, and email address of bank contact.
For each payment card that you accept, your acquirer must provide you with this information:
  • Eight-digit BIN number.
  • Merchant ID assigned by your acquirer.
  • List of all of the currencies that you can process.

Payer Authentication Configuration Testing

After the payer authentication functionality is enabled for your account and you have installed and configured the software, you must run tests to ensure that payer authentication is working properly. You must ensure that the proper data is being collected and sent to the issuer and that the proper status for a particular circumstance is returned. To ensure that the proper statuses are returned under all possible circumstances, extensive testing is required before you go live with payer authentication.
A sandbox testing environment is provided to resolve any bugs in your system. In this testing environment, you can simulate various transaction scenarios with the types of payment cards that you accept. Test card numbers for the various types of payment cards are provided so that you can run transaction simulations. You can verify that the values generated during the simulations are the correct values that should occur during that transaction scenario.
When your test results are correct, contact customer support and request to go live. When you go live, you will use the production host name to process transactions instead of the test host name that you used when processing transactions in the test environment.
The host name for the testing environment:
POST
https://apitest.cybersource.com
The host name for the production environment:
POST
https://api.cybersource.com
Details about testing your payer authentication configuration are available in the Testing Payer Authentication Services section.

Request Endpoints

When posting a request for payer authentication, you must add an endpoint to each hostname, whether you are using the test environment or the production environment. These endpoints are used with payer authentication.
/risk/v1/authentications
: use when verifying that a card is enrolled in a card authentication program or requesting authentication from the issuer.
/risk/v1/authentication-results
: use when retrieving and validating authentication results from the issuer so that the merchant can process the payment.
/pts/v2/payments
: use when bundling multiple payments together.
For example, a test request might look like this:
POST
https://apitest.cybersource.com
/risk/v1/authentications

Payer Authentication Integrations

Payer authentication was designed to authenticate buyers during online transactions. During the early growth of internet transactions, e-commerce was conducted only on computers. Mobile phones had limited capabilities. When mobile phones (and tablets) could access the internet, online transactions quickly grew, and now they comprise almost half of all e-commerce transactions. A key part of updating the EMV
3-D Secure
 protocol from 1.0 to 2.0 was to ensure that payer authentication became available for e-commerce done on mobile devices.
Two types of payer authentication integration are available for merchants:
  • API for browser authentication from a computer.
  • SDK for authentication from mobile devices (available for Android and iOS). Contact support to obtain the SDK.
Payer Authentication supports message-level encryption. For more information, see Message Level Encryption.
Merchants should integrate payer authentication for online shopping on both types of devices. The next sections in this guide describe how to integrate payer authentication into those shopping experiences.

Implementing Direct API for Payer Authentication

The Direct API integrates EMV
3-D Secure
 2.x into your business's website. This integration uses an iframe to complete the device profiling and EMV
3-D Secure
 authentication requirements without including third-party JavaScript directly on your site.
This implementation requires the use of JavaScript to leverage the authentication. The JavaScript is hosted and contained inside the iframe and does not directly access your web page.
Payer Authentication uses Cardinal Centinel as the technology platform to manage all EMV
3-D Secure
 authentication processes. Any references to Cardinal in this document refer to the underlying services that are provided by Cardinal technology.
A website that provides a demo tool to help users understand how payer authentication works is available:
You can complete the steps required to implement payer authentication on their website and examine the code underlying the process. Use test card numbers to walk through the process and enter
123
 as the security code.

Prerequisites

Notify your account representative that you want to implement payer authentication (3-D Secure) using the Direct API integration. Provide the merchant ID that you will use for testing. For more information, see Required Merchant Information.
Before you can implement payer authentication services, your business team must contact
your acquirer and
Cybersource
 to establish the service. Your software development team should become familiar with the API fields and technical details of this service.

After Implementation and Before Go Live

Use the test cases to test your preliminary code and make appropriate changes. See Testing Payer Authentication. Testing ensures that your account is configured for production and that your transactions are processed quickly and correctly.

Step 1: Setup Service

Request the Setup service before selecting the button to submit payment. Request the Setup service separately without including other services. The Setup service response will include a JSON Web Token (JWT) that contains credentials to create a secure channel with you. The Setup response also includes a reference ID to use during the authentication and a URL to use when transferring the device data that is collected in the next step.
The Setup service is used only in the Direct API integration. The SDK integration does not use this step.
Run the Setup service as soon as the customer enters their card number to avoid any delay in the customer experience. The next step in the process, device data collection, cannot start until the Setup response is received because the response has the URL where the device data will be sent.

Figure:

Process Flow for Setup for Payer Authentication
Process Flow Diagram for Setup for Payer Authentication

Best Practices

This practice should be followed so that this step achieves optimal performance and to minimize potential operating issues.
After the customer credit card is entered, immediately begin device data collection.

Request Fields

When requesting the Setup service, you must send the customer’s payment information. This can be either the actual encrypted card information or a token associated with the payment data. Besides the required fields, the request might also include any of these fields:
  • card_accountNumber
  • card_accountNumber
  • recurringSubscriptionInfo_subscriptionID
  • tokenSource_transientToken
The
card_cardType
 field is required when the card type is
JCB
, Cartes Bancaires, or China UnionPay
.

Important Response Fields

The response from the issuing bank might include these API fields.
For further details on examples, see Simple Order Example: Setting Up Device Data Collection

Step 2: Device Data Collection

Device data collection starts on the merchant end after you receive the server-side Setup service response as described in Step 1: Setup Service and pass the access token and the device data collection URL to the front end. When device data gets to the data collection URL, a Method URL stipulated in the
3-D Secure
 protocal captures the entire card number to identify the issuing bank.
A hidden 10 x 10 pixel iframe is rendered in the browser, and using the access token, you send the customer device data to the device data collection URL. The device data collection can take up to 10 seconds. If you proceed with the check enrollment service as described in Step 3: Payer Authentication Check Enrollment Service before a response is received, the collection process is short-circuited and an error occurs. Despite the error, as long as you include the data from the eleven browser fields as explained in Step 3: Payer Authentication Check Enrollment Service, you can still proceed with the EMV authentication.
It is recommended that the device data collection start immediately after you receive the customer card number to ensure that the data collection runs in the background while the customer continues with the checkout process, ensuring a minimum of waiting. When a customer changes to a different card number, begin the Setup and device data collection process again as soon as the new card number is entered.

Figure:

Process Flow for Device Data Collection
Process Flow diagram for Device Data Collection

Best Practices

These practices should be followed for this step in order to achieve optimal performance and to minimize potential operating issues.
  • After the customer credit card number is entered, immediately begin the device data collection.
  • Device data collection must complete before the enrollment check begins.
  • While not required, it is highly recommended to pass the values from the 11 browser-based fields in the request. The information from these fields serves as a backup, in case the device data collection does not complete correctly.
  • As much billing data as possible (unless restricted by regional mandates) should be supplied to the issuing bank to ensure that the issuer's risk assessment software has the most comprehensive data.
  • The billing data such as state and country must be formatted according to ISO 3166-2 format specifications to ensure that the network can properly validate the data.

Which Device Data is Collected

One of the key components to authenticating a cardholder during an online transaction is to compare information about the device that the customer is currently using to the information in the bank's database about devices the customer used in past transactions. This information is maintained in the acess control server (ACS) at the issuing bank. This device information focuses on the web browser and includes these types of data:
  • IP address
  • Browser language
  • Browser type
  • Browser version
  • Computer operating system
  • System time zone
  • Screen dimensions
  • Color depth
A successful device data collection process that includes the 11 browser fields listed in the check enrollment step increases the chances of a frictionless authentication. See Step 3: Payer Authentication Check Enrollment Service for the list of 11 browser fields. Business rules evaluate whether a transaction is risky enough to require the buyer to authenticate their identity. These business rules are configured in the issuer's risk analysis software that evaluates each transaction.

Building the Iframe

The iframe has these parameters:
  • Form POST Action: The POST goes to the URL that is opened within an iframe. This URL is the value provided by the
    payerAuthSetupReply_deviceDataCollectionURL
     response field discussed in Step 1: Setup Service.
  • JWT POST Parameter: Use the value from the
    payerAuthSetupReply_accessToken
     response field discussed in Step 1: Setup Service.

Initiating the Device Data Collection Iframe

Initiate a form POST in a hidden 10 x 10 pixel iframe and send it to the device data collection URL (
payerAuthSetupReply_deviceDataCollectionURL
).
Place the HTML anywhere inside the
<body>
 element of the checkout page. Dynamically replace the value of the form action attribute and JWT POST parameter with the response values discussed in Step 1: Setup Service. See this example.
Initiate the Device Data Collection Iframe
<iframe id="cardinal_collection_iframe" name="collectionIframe" height="10" width="10" style="display: none;"></iframe>
<form id="cardinal_collection_form" method="POST" target="collectionIframe" action=https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect>
  <input id="cardinal_collection_form_input" type="hidden" name="JWT" value="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJSZWZlcmVuY2VJZCI6ImE0NjVlYzU1LTMwNTEtN GYwZC05MGE0LWZjMDNlMGE2MWQxOSIsIlJldHVyblVybCI6Imh0dHA6XC9cL2xvY2FsaG9zdDo4MDgyXC9yZXF1ZX N0LWNhdGNoZXJcL2NhdGNoLXJlcXVlc3QucGhwIiwianRpIjoianRpXzVmMDVkM2VkY2U0MjYzLjc5MjQwNzMzIi wiaWF0IjoxNTk0MjE3NDUzLCJpc3MiOiI1YjIzZjhjMGJmOWUyZjBkMzQ3ZGQ1YmEiLCJPcmdVbml0SWQiOiI1 NWVmM2YwY2Y3MjNhYTQzMWM5OWI0MzgifQ.Yw9cB9Hdrg71GPL40oAC0g3CVKYElNGe0uvN9JAaw2E">
</form>

Submitting the Device Data Collection Iframe

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body>
 element as shown in this example. The JavaScript invokes the iframe form POST automatically when the window loads. You must submit it before requesting the Check Enrollment service.
JavaScript to Invoke the Iframe Form POST
 
 <script>
window.onload = function() { 
var cardinalCollectionForm = document.querySelector('#cardinal_collection_form'); 
if(cardinalCollectionForm) // form exists 
cardinalCollectionForm.submit();
}
</script>

Receiving the Device Data Collection URL Response

Receiving the response indicates that the device data collection URL completed its processing. The response is an event callback that contains a message with the status of the device data collection process.
Use the
event.origin
 URL that corresponds to your environment:
  • Test:
    https://centinelapistag.cardinalcommerce.com
  • Production:
    https://centinelapi.cardinalcommerce.com
Study the example below to understand how to subscribe to the event. Add JavaScript to receive the response from the device data collection iframe. Place the JavaScript after the closing
</body>
 element.
Listen for Device Data Collection Response
window.addEventListener("message", function(event) {
  if (event.origin === https://centinelapistag.cardinalcommerce.com) {
    console.log(event.data);
  }
}, false);
This example shows a response payload from the event. None of the returned data needs to be stored for future use.
Event Listener Callback Payload
{
  "MessageType": "profile.completed",
  "Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",
  "Status": true
}

Step 3: Payer Authentication Check Enrollment Service

Request the Check Enrollment service only after you receive the device data collection response. Checking enrollment before receiving the device data collection response stops the data collection process. Data collection can take up to 10 seconds. The merchant should set a timer that expires after 10 seconds of waiting for a response to the data collection so that the check enrollment service starts even when the device data collection response was not received.
You must include these 11 browser field values in the check enrollment request. These fields provide the information that that ensures a transaction qualifies as an EMV
3-D Secure
 transaction. The information in these fields provides a backup for the occasions when the device data collection fails to complete.
  • billTo_httpBrowserColorDepth
  • billTo_httpBrowserJavaEnabled
  • billTo_httpBrowserJavaScriptEnabled
  • billTo_httpBrowserLanguage
  • billTo_httpBrowserScreenHeight
  • billTo_httpBrowserScreenWidth
  • billTo_httpBrowserTimeDifference
  • billTo_ipAddress
  • payerAuthEnrollService_httpUserAccept
  • payerAuthEnrollService_httpUserAgent
  • payerAuthEnrollService_deviceChanne
With the device data collected, the issuer runs a risk assesment that results in one of these outcomes:
  • Frictionless success (low risk)
  • Challenge required (moderate risk)
  • Frictionless failure or decline (high risk)

Figure:

Process Flow for Checking Enrollment in Payer Authentication
Process flow diagram for checking enrollment in Payer Authentication

Best Practices

Follow these practices for this step to achieve optimal performance:
  • Do not start checking enrollment until the device data collection is complete.
  • Notifiy cardholders to contact their bank for instructions if a problem occurs. Information about additional action required of the cardholder should be displayed on the checkout page. Providing instructions to the customer avoids multiple attempts to resubmit the same card.

Request Fields

The
payerAuthEnrollService_referenceID
 field is mapped from the
payerAuthSetupReply_referenceID
 field as discussed in Step 1: Setup Service.
The
payerAuthEnrollService_returnURL
 value is set to the URL to which the issuing bank redirects the customer as discussed in Step 4: Step-Up Iframe.
To request the Check Enrollment service, you must send the encrypted payment data or a token or some other equivalent of card data used by your integration. The request fields can include any of these:
  • card_accountNumber
  • encryptedPayment_data
  • encryptedPayment_descriptor
  • recurringSubscriptionInfo_subscriptionID
  • tokenSource_transientToken
These fields are required (merchant ID is in the header):
  • billTo_country
  • billTo_email
  • billTo_firstName
  • billTo_ipAddress
  • billTo_lastName
  • billTo_phoneNumber
    (if no other phone number is available)
  • billTo_postalCode
  • billTo_state
  • billTo_street1
  • card_cardType
  • card_expirationMonth
  • card_expirationYear
  • merchantID
  • payerAuthEnrollService_mobilePhone
    (if no other phone number is available)
  • payerAuthEnrollService_referenceID
  • payerAuthEnrollService_returnURL
  • payerAuthEnrollService_workPhone
    (if no other phone number is available)
  • purchaseTotals_currency
  • purchaseTotals_grandTotalAmount
You can send additional request data to reduce your issuer step-up authentication rates. Send all available fields. As a backup, if device data collection fails, include the 11 device information fields listed among the optional fields for the Check Enrollment service in your request. If a failure does occur, adding these device information fields ensures a transaction is not downgraded. If you do not have data for a field, do not send dummy data.
The size of the step-up iframe discussed in Step 4: Step-Up Iframe can vary depending on the EMV
3-D Secure
 version of the transaction. You can request the size of the challenge window in the
payerAuthEnrollService_acsWindowSize
 request field.
Requesting a specific window size does not guarantee this size. Parsing the PAReq as described in Step 4: Step-Up Iframe determines the actual size.
For further details on individual API fields, refer to the . The field values should use the ISO 3166-2 format.

Interpreting the Check Enrollment Response

It is important to check the status values in the response. These possible statuses are the same for all card types.

Reason Code 475

  • VERes enrolled =
    Y
  • PARes status =
    C
The account number is enrolled in payer authentication. The cardholder is challenged to authenticate. Authenticate the cardholder before authorizing the transaction.

Reason Code 100

Frictionless authentication was successful/Stepup authentication is not required.
  • VERes enrolled =
    Y
  • PARes status =
    Y
The account is enrolled in payer authentication, and the cardholder was successfully authenticated. If enrollment and authorization are made in separate calls, the payer authentication data must be included in the authorization request to receive liability shift protection.

Attempt Stand-in Frictionless Authentication

  • VERes enrolled =
    Y
  • PARes status =
    A
This status indicates that the account is enrolled in payer authentication, but the issuer does not support the program. This is called
stand-in authentication
. If check enrollment and authorization are made in separate calls, the payer authentication data must be included in the authorization request to receive liability shift protection.

Card Not Enrolled

  • VERes enrolled =
    B
     or
    U
This status indicates that the account is not eligible for a payer authentication program, authentication was bypassed, or an error or timeout occurred. If enrollment and authorization are made in separate calls, you can request authorization, but there is no liability shift protection.

Unavailable Frictionless Authentication

  • VERes enrolled =
    Y
  • PARes status =
    U
This status indicates that the account is enrolled in payer authentication, but authentication is currently unavailable. The merchant can attempt to retry authentication or proceed with authorization. If enrollment and authorization are made in separate calls, you can continue and request authorization, but there is no liability shift protection. Without authentication of the customer, the merchant remains liable for any chargeback.

Reason Code 476

Failed Frictionless Authentication

  • VERes enrolled =
    Y
  • PARes status =
    N
This status indicates that the account is enrolled in payer authentication but frictionless authentication failed. Merchants cannot submit this transaction for authorization. Instead, ask for another form of payment.

Rejected Frictionless Authentication

  • VERes enrolled =
    Y
  • PARes status =
    R
This status indicates that the account is enrolled in payer authentication but frictionless authentication was rejected by the issuing bank without requiring a challenge. Merchants cannot submit this transaction for authorization. Instead, ask for another form of payment.
When
a 476
 status occurs, the merchant should display a message from the card issuer to the cardholder using the
payerAuthEnrollReply_cardholderMessage
 field. The text of the message is provided by the ACS/issuer during a frictionless or decoupled transaction to convey information to the cardholder. An message example might be, “Additional authentication is needed for this transaction, contact (issuer name) at xxx-xxx-xxxx.” An example of the entry that would appear in the log for such an occurrence is: "cardholderInfo":"You cannot complete this purchase right now. For help, call CommBank at (111) 555-2222"

Important Response Fields

When you receive a
reason code
475
 response, you also receive these fields:
These fields contain values that are used in the Step-Up service, which runs when a customer is challenged to authenticate.

Step 4: Step-Up Iframe

Initiate step-up authentication on the front end after you receive the response as discussed in Step 3: Payer Authentication Check Enrollment Service. Note that frictionless authentication does not require this step-up iframe step. This step is only for step-up authentication when the issuing bank wants to challenge the cardholder.
When a challenge is needed to prove a customer's identity, a JSON Web Token is returned to you that contains a step-up URL. You open an iframe where the access token to the step-up URL (also known as the endpoint) is posted. The iframe must be sized appropriately to enable the cardholder to complete the challenge. The iframe manages customer interaction with the card-issuing bank’s access control server. The bank asks the customer to provide identifying information. Once the customer completes the challenge, the process moves to validating the information that the customer sent.

Figure:

Process Flow for Step-Up Authentication
Process Flow Diagram for Step-up Authentication

Best Practices

These practices should be followed for this step to achieve optimal performance and to minimize potential operating issues.
  • When a transaction requires a challenge, according to EMVCo protocol, the challenge must be issued within 30 seconds of the Enrollment Check response. When more than 30 seconds elapses, the ACS times out.

Building the Iframe Parameters

The iframe that you display should be sized to enable the customer bank to exchange authentication information between itself and the customer. Because a bank can use various methods to authenticate, the iframe has four size options. The bank will request that you ensure that the iframe size provides room to display the bank logo and the card network being used, the amount of the transaction, and a brief explanation of what the customer needs to do. You manage the size of the challenge window to ensure that the challenge window matches with your presentation screen. You choose the iframe parameters and pass the window size to the issuer.
  • Use the JWT POST Parameter value from the
    payerAuthEnrollReply_accessToken
     response field and do a form POST within the iframe to the step up Url value that is passed by the
    payerAuthEnrollReply_stepUpUrl
     response field.
  • MD POST Parameter: Merchant-defined data returned in the response. This field is optional.
  • Iframe height and width: EMV
    3-D Secure
     2.x offers multiple size options:
    • Use the
      payerAuthEnrollService_acsWindowSize
       request field to request a specific window size.
    • Use the
      payerAuthEnrollReply_paReq
       response field to determine iframe dimensions by Base64 decoding the string and cross-referencing a Challenge Window Size value with its corresponding size.
This table lists the possible values for iframe size and the sizes associated with the value.
Challenge Window Size Value and Corresponding Size
Challenge Window Size Value
Step-Up Iframe Dimensions (Width x Height in pixels)
01
250 x 400
02
390 x 400
03
500 x 600
04
600 x 400
05
Full screen
This is an example for the decoded value.
Challenge Window Size Decoded Value
{
    "messageType":"CReq","messageVersion":"2.2.0",
    "threeDSServerTransID":"c4b911d6-1f5c-40a4-bc2b-51986a98f991",
    "acsTransID":"47956453-b477-4f02-a9ef-0ec3f9f779b3",
    "challengeWindowSize":"02"
}

Creating the Iframe

Create an iframe that is the same size as the Challenge Window Size to send a POST request to the step-up URL. Study this example.
Send a POST Request to the Step-Up URL
<iframe name=”step-up-iframe" height="400" width="400"></iframe>
<form id="step-up-form" target=”step-up-iframe" method="post" action=" https://centinelapistag. cardinalcommerce.com/V2/Cruise/StepUp"> <input type="hidden" name="JWT" value="eyJhbGciOiJIUz I1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmNmFmMTRmOS04YWRjLTRiNzktOGVkYS04YWVlMTI2NTkzZTEiLCJp YXQiOjE1OTYwNTEyNzYsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5NjA1NDg3NiwiT3Jn VW5pdElkIjoiNTVlZjNmNTZmNzIzYWE0MzFjOTlkNTRiIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBt ZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2 FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3 aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUpsTkdKaVpqazNNeTFqTW1FeUxUUTNOREF0T1RWak5 DMWpNVGhoTVRNeE16TmlPRFFpTENKaFkzTlVjbUZ1YzBsRUlqb2lNVGMzT0RFM016SXROREk1TVMwME1HUmlMVG xoTkRndE1ESm1OREpoTlRZd1lqYzVJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcm Fuc2FjdGlvbklkIjoiQnh5a0hYVEp4M1JuNHBGWnF1bjAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0 dXJuVXJsIjoiaHR0cHM6Ly9taWNoYWVsdGF5bG9yLmlvL2N5YnMvc3RvcmVEZW1vL3B1YmxpYy9saXN0ZW5lci5 weSJ9.H8j-VYCJK_7ZEHxGz82_IwZGKBODzPaceJNNC99xZRo" /> <input type="hidden" name="MD" value="optionally_include_custom_data_that_will_be_returned_as_is”/> </form>

Invoking the Iframe

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body>
 tag as shown in the example below. The JavaScript invokes the iframe form POST automatically when the window loads. While you can submit the form at a different time, you must submit the form before requesting the validation service.
<script>
window.onload = function() {   
    var stepUpForm = document.querySelector('#step-up-form');
    if(stepUpForm) // Step-Up form exists
    stepUpForm.submit();
}
</script>

Receiving the Step-Up Results

After the customer interacts with the issuing bank, the customer is returned to the
payerAuthEnrollService_returnURL
 within the iframe as specified in Step 3: Payer Authentication Check Enrollment Service. The payload sent to the return URL is URL-encoded and Base64-encoded (see the example below). Since you host the return URL, you can then close the iframe after redirection.
The response sent back to the return URL contains these values:
  • Transaction ID: (
    payerAuthEnrollReply_authenticationTransactionID
     response field). This value is used in Step 5: Payer Authentication Validation Service.
  • MD: merchant data returned if present in the POST to step-up URL; otherwise, null.
POST to Return URL
TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null

Step 5: Payer Authentication Validation Service

When you receive the step-up response as discussed in Step 4: Step-Up Iframe, verify that the customer was successfully authenticated. Note that frictionless authentication does not require this validation step. Validation is required only for step-up authentication.

Figure:

Process Flow for Validation of the Cardholder
Process Flow Diagram for Validation of the Payer

Request Fields

The
payerAuthValidateService_authenticationTransactionID
 field in this step is mapped from the
payerAuthEnrollReply_authenticationTransactionID
 field in Step 4: Step-Up Iframe.
These fields are required:
  • card_cardType
  • card_expirationMonth
  • card_expirationYear
  • card_accountNumber
  • merchantReferenceCode
  • payerAuthValidateService_authenticationTransactionID
  • purchaseTotals_currency
  • purchaseTotals_grandTotalAmount
     or
    item_#_unitPrice
For examples, see Validating a Challenge.
For further details on individual API fields, refer to the .

Interpreting the Validation Response

If the authentication is rejected (TransStatus R), Visa,
China UnionPay, Elo,
JCB,
Diners Club, Discover,
 and American Express recommend not proceeding to authorization. Instead, ask the customer to use another payment method.
Proceed with the order according to the validation response that you receive. The possible validation response statuses are the same for all of the card types.

Reason Code 100

Successful Step-Up Authentication
  • PARes status =
    Y
Step-up authentication of the customer was successful. If you request the Validate Authentication and Authorization services separately, you must add the required payer validate payload values to your authorization request before you can receive chargeback protection that shifts the liability to the issuer.
Unavailable Step-up Authentication
  • PARes status =
    U
Step-up authentication was unavailable and the customer could not be authenticated. This status does not necessarily indicate any fraudulent intent from the customer. Merchants can either attempt to retry authentication or continue to authorization. If you are making separate validatation and authorization calls, you can still proceed with the authorization request but there is no liability shift. Without authentication, the merchant remains liable for any chargeback if it should occur with the transaction.

Reason Code 476

Unavailable Step-up Authentication
  • PARes status =
    N
The customer could not be authenticated. Do not submit this transaction for authorization. Instead ask the customer for another form of payment.
Error
If you receive an error from the payment card company, process the order according to your business rules. If the error occurs frequently, report it to customer supportcustomer supportcustomer support. If you receive a system error, determine the cause of the error and proceed with card authorization only when appropriate.

Redirecting Customers to Pass or Fail Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. You must ensure that the messages that display to customers are accurate and complete, and that the message addresses all possible scenarios for enrolled and non-enrolled cards. For example, if the authentication fails, display a message such as this to the customer:
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.

Combining the Authentication and the Authorization Services

After the customer is successfully authenticated, you must get authorization from the issuing bank to proceed with the transaction. While these are separate processes, it is recommended that you link these services by immediately passing the returned values into a request to authorize the transaction. The two services can be linked when:
  • Checking enrollment determines that no challenge is required. Pass the values returned from checking enrollment to the authorization request.
  • Validating a challenge authenticates the cardholder. Pass the values returned from validating the challenge to the authorization request.
With the same request transactions, a different endpoint must be referenced for the authorization, and an additional element must be added to the JSON. When step-up authentication is required, transaction processing stops to allow completion of authentication, and authorization is not called until after the challenge response is validated. This integration method is recommended.
Depending on your card type, you might not receive the XID value. If you receive this field under a frictionless scenario, it is required for authorization.

Combining Check Enrollment and the Authorization Services

Receiving certain responses from checking enrollment allows the authorization to be requested immediately afterwards. The possible checking enrollment responses are:
  • Successful frictionless authentication
  • Attempted stand-in frictionless authentication
  • Issuer does not support the payer authentication program
  • Account is not eligible for a payer authentication program
  • Unavailable frictionless authentication
  • Failed frictionless authentication
  • Rejected frictionless authentication
In all checking enrollment scenarios, it is recommended that you integrate these services by combining the checking enrollment and authorization services into a single transaction. When the services are combined, one of these conditions occurs:
  • No additional integration work is required to manually map the appropriate check enrollment results to the corresponding authorization request fields.
  • If further authentication is needed, the authorization cannot happen until after authentication completes and you can proceed to the next steps for challenging.
With same request transactions, a different endpoint must be referenced for the authorization, and an additional element must be added to the JSON. Depending on your card type, you might not receive the XID value. If you receive this field under a frictionless scenario, it is required for authorization.

Check Enrollment Response Fields and Their Equivalent Authorization Request Fields

When a customer is authenticated without a challenge, the transaction can be authorized either in the same request or in a separate authorization request. Whether authorization occurs in the same request or a separate request, the values from the check enrollment response must be passed to the authorization request to qualify for a liability shift. This table matches the check enrollment fields with their equivalent authorization fields. Sometimes a check enrollment response field is the same field used in the authorization request.
Be sure to include the following card-specific information in your authorization request:
  • For Visa,
    JCB,
    China UnionPay, Elo,
    Diners Club, Discover,
     and American Express include the
    CAVV
    .
  • For Mastercard only, include the collection indicator and the
    AAV
     (also known as
    UCAF
    ).
Enrollment Check and Response Fields
Identifier
Enrollment Check Response Field
Card Authorization Request Field
E-commerce indicator
payerAuthEnrollReply_commerceIndicator
ccAuthService_commerceIndicator
Collection indicator
payerAuthEnrollReply_ucaf CollectionIndicator
ucaf_collectionIndicator
CAVV
payerAuthValidateReply_cavv
ccAuthService_cavv
AAV
payerAuthValidateReply_ucafAuthenticationData
ucaf_authenticationData
XID
payerAuthEnrollReply_xid
ccAuthService_xid
Result of the enrollment check for Asia, Middle East, and Africa Gateway
payerAuthEnrollReply_veresEnrolled
3-D Secure
 version
payerAuthEnrollReply_specificationVersion
ccAuthService_paSpecificationVersion
Directory server transaction ID
payerAuthEnrollReply_direc toryServerTransactionID
ccAuthService_directorySer verTransactionID

Combining the Validation and the Authorization Services

After the customer is successfully authenticated, you must get authorization from the issuing bank to proceed with the transaction. While these are separate processes, you should integrate these two services into a single process whenever possible. When you do so, no additional integration work is required on your part to manually map the appropriate validation results to corresponding authorization request fields.
With the same request transactions, a different endpoint must be referenced for the authorization, and an additional element must be added to the JSON. When step-up authentication is required, transaction processing stops to allow authentication to complete, and authorization is not called until after the challenge response is validated. This integration method is highly recommended. Depending on your card type, you might not receive the XID value. If you receive this field under a frictionless scenario, it is required for authorization.

Validation Fields and their Equivalent Authorization Fields

When a customer is authenticated after a challenge, the transaction can be authorized in the same request or in a separate authorization request. Whether authorization is combined with validation or occurs in a separate request, the values from the validation response must be passed to the authorization request to qualify for a liability shift to the issuing bank. This table pairs the Validation field with its equivalent Authorization API field.
Be sure to include the following card-specific information in your authorization request:
  • For Visa,
    JCB,
    China UnionPay, Elo,
    Diners Club, Discover,
     and American Express include the CAVV.
  • For Mastercard only, include the collection indicator and the AAV (also known as UCAF).
Validation Check and Response Fields
Identifier
Validation Check Response Field
Card Authorization Request Field
E-commerce indicator
payerAuthValidateReply_commerceIndicator
e_commerce_indicator
Collection indicator
payerAuthValidateReply_ucafCollectionIndicator
ucaf_collection_indicator
CAVV
payerAuthValidateReply_cavv
ccAuthService_cavv
AAV
payerAuthValidateReply_ucafAuthenticationData
ucaf_authenticationData
XID
payerAuthValidateReply_xid
ccAuthService_xid
3-D Secure
 version
payerAuthValidateReply_specificationVersion
ccAuthService_paSpecificationVersion
Directory server transaction ID
payerAuthValidateReply_directory ServerTransactionID
ccAuthService_directoryServerTransactionID

Implementing SDK Payer Authentication

This chapter summarizes the process of integrating SDK Payer Authentication services into your mobile application. Payer authentication services use the Mobile SDK for iOS or Android to facilitate the authentication. New SDK versions are frequently released and you should ensure that you stay current with the latest release. One way to stay informed on about new releases is to subscribe to a distribution list to be informed of updates and other product announcements. You can subscribe by going to this link: Cardinal SDK Notifications.
Implementing the SDK in your mobile application requires either Android or iOS platform application programming skills. Android API 21 or iOS 9 and XCode 8 are required.
The SDK is only designed to handle EMV
3-D Secure
 2.x transactions.

Implementation Overview

Notify your account representative that you want to implement payer authentication (EMV
3-D Secure
). Give the representative the merchant ID that you will use for testing. For more information, see Payer Authentication Merchant Workflow.
The SDK integration operates in a similar manner to the Direct API integration, but SDK does not have a Setup service step.
Implementation tasks include:
  • Download, import, and configure the Mobile SDK for either iOS or Android.
  • For each purchase request:
    • Build the authentication request.
    • Invoke the authentication.
    • Handle declines.
    • Make another back-end, server-to-server call to request these services:
      payerAuthValidateService
      : Payer Authentication Validation
      ccAuthService
      : Card Authorization service (optional)
  • Use the test cases to test your preliminary code and make appropriate changes. See Testing Payer Authentication.
  • Ensure that your account is configured for production.
Note that calling the Payer Authentication Setup Service is not required with the SDK mobile version.

Process Flow for SDK Integration

The steps required to integrate payer authentication into an SDK mobile application are described below.
  1. Contact customer support to register for an API key.
  2. Download and import the Mobile SDK for either iOS or Android.
  3. Set up your build environment.
  4. Configure your SDK.
  5. Setup the initial request to Cardinal.
  6. Create an API request to your merchant server to request the Enrollment Check service, passing in transaction details and the
    payerAuthEnrollService_referenceID
     request field.
  7. If the issuing bank does not require authentication, you receive this information in the Enrollment Check response:
    • E-commerce indicator (
      payerAuthEnrollReply_commerceIndicator
      )
    • CAVV (all card types except Mastercard) (
      payerAuthEnrollReply_cavv
      )
    • AAV (Mastercard only) (
      payerAuthEnrollReply_ucafCollectionIndicator
      )
    • Transaction ID (
      payerAuthEnrollReply_xid
      )
    • 3-D Secure
       version (
      payerAuthEnrollReply_specificationVersion
      )
    • Directory server transaction ID (
      payerAuthEnrollReply_directoryServerTransactionID
      )
  8. If the issuing bank requires authentication, you receive a response with the payload and the transaction ID that you include in the
    Cardinal.continue
     call from your SDK.
  9. The Mobile SDK displays an authentication window, and the customer enters the authentication information into that window.
  10. The bank validates the customer credentials and a JSON Web Token (JWT) is returned by the SDK in the onValidated callback that the merchant is required to validate server-side for security reasons.
  11. Create an API call to your merchant server to request the Validate Authentication service, extracting the processor transaction ID value from the JWT and sending it in the
    payerAuthValidateService_authenticationTransactionID
     request field. You receive the e-commerce indicator, CAVV or AAV, transaction ID,
    3-D Secure
     version, and directory server transaction ID.
Verify that the authentication was successful and continue processing your order.
You must pass all pertinent data for the card type and processor in your authorization request. For more information, see Requesting the Validation Service.

Prerequisites for SDK Implementation

Before you can implement payer authentication services, your business team must contact your acquirer and
Cybersource
 to establish the service. Your software development team should become familiar with the API fields and technical details of this service.
Creating a mobile application with the SDK implementation, requires that you perform some preliminary procedures before the starting the actual payer authentication implementation process. These processes involving JWTs are described in this section.

Credentials/API Keys

API keys are required to create the JSON Web Token (JWT). For further information, contact customer support .
You will receive an email with your username and a temporary password. Your username will be in this format:
cybersource_merchant name_contact name
For example:
cybersource_petairways_peter
Once you receive your credentials, log in to your JFrog account and update your temporary password. Follow the process below to generate your API key.

Generating your API Key:

  1. Log in to your JFrog account.
  2. In the top-right of the JFrog Platform, select the Welcome drop-down menu and click
    Edit Profile
    .
  3. Enter your password and click
    Unlock
    .
  4. Under Authentication Settings, click
    Generate API Key
    .

Mobile Device Data Collected

One of the key components to authenticating a cardholder during an online transaction is to compare information about the mobile device that the buyer is using to the information about mobile devices that the buyer used in past transactions. This information is maintained in the access control server (ACS) at the issuing bank.
In mobile device transactions, information collected about the buyer device can include:
  • Device ID
  • Device model
  • Operating system version
  • System language
  • Country
  • Time zone
  • Screen dimensions
A successful device data collection process that includes the eleven browser fields listed in the check enrollment step, increases the chances of a frictionless authentication. The decision to escalate a transaction to a level of risk high enough to require challenging the buyer to authenticate their identity is managed by business rules that are configured in the issuer's risk analysis software that evaluates each transaction.

Using the Android SDK

A mobile SDK is available for integrating payer authentication services into mobile applications running on the Android platform.

Updating the Gradle Build Properties

In Android Studio, open the app directory (which can also be labeled Module: app) and open the
build.gradle
 file. Edit the Gradle file located in the app directory. Add the contents shown in the example below to the Gradle file.

    repositories {
       ...
       maven {
               url  "https://cardinalcommerceprod.jfrog.io/artifactory/android"
               credentials {
                       username Artifactory username
                       password Artifactory user API Key
                }
        }
    }
    dependencies {
        ...
        //Cardinal Mobile SDK
        implementation 2.5-1
    }
If your project uses Progurad, add the lines shown below to the
proguard-rules.pro
 file. 

    -keep class com.cardinalcommerce.dependencies.internal.bouncycastle.**
    -keep class com.cardinalcommerce.dependencies.internal.nimbusds.**

Configuring the Android SDK

Get the instance of the Cardinal object by running the
Cardinal.getInstance()
 process. Use the default configuration options. See the example below to understand how to run the
Cardinal.configure()
 process.
For more details on configuration, refer to the configuration options table after the example. 
private Cardinal cardinal = Cardinal.getInstance();
@Override
protected void onCreate(Bundle savedInstanceState) {

CardinalConfigurationParameters cardinalConfigurationParameters = new CardinalConfigurationParameters();
        cardinalConfigurationParameters.setEnvironment(CardinalEnvironment.STAGING);
        cardinalConfigurationParameters.setTimeout(8000);
        JSONArray rType = new JSONArray();
        rType.put(CardinalRenderType.OTP);
        rType.put(CardinalRenderType.SINGLE_SELECT);
        rType.put(CardinalRenderType.MULTI_SELECT);
        rType.put(CardinalRenderType.OOB);
        rType.put(CardinalRenderType.HTML);
        cardinalConfigurationParameters.setRenderType(rType);

        cardinalConfigurationParameters.setUiType(CardinalUiType.BOTH);

        UiCustomization yourUICustomizationObject = new UiCustomization();
cardinalConfigurationParameters.setUICustomization(yourUICustomizationObject);

        cardinal.configure(this,cardinalConfigurationParameters);
}
Android Configuration Options
Method
Description
Default Values
setEnableDFSync (boolean enableDFSync)
On setting true, onSetupCompleted is called after the collected device data is sent to the server.
False
setEnableQuickAuth (boolean enableQuickAuth)
Sets enable quick auth false.
False
setEnvironment(Setting up mobile SDK - Android- V 2.1#CardinalEnvironment environment)
Sets the environment to which the SDK must connect.
CardinalEnvironment.
PRODUCTION
setProxyAddress(java.lang. String proxyAddress)
Sets the proxy to which the SDK must connect.
“ “
setRenderType(org.json. JSONArray renderType)
Sets renderLists all user interface types that the device supports for displaying specific challenge user interfaces within the SDK.
JSONArray rType = new JSONArray();
rType.put(Cardinal
RenderType.OTP);
rType.put(Cardinal
RenderType.SINGLE_SELECT);
rType.put(Cardinal
RenderType.MULTI_SELECT);
rType.put(Cardinal
RenderType.OOB);
rType.put(Cardinal
RenderType.HTML);
setTimeout(int timeout)
Sets the maximum amount of time (in milliseconds) for all exchanges.
8000
setUICustomization (UiCustomization UI Customization)
Sets UICustomization
Device Default Values
setUiType(CardinalUiType uiType)
Sets all user interface types that the device supports for displaying specific challenge user interfaces within the SDK.
CardinalUiType.BOTH

Setting Up the Initial Request

Run the
Cardinal.init()
 process to:
  • Begin the communication process with Cardinal.
  • Authenticate your credentials (server JWT).
  • Complete the data collection process.
By the time the customer is ready to check out, all necessary preprocessing is complete.
Each time a user begins a mobile transaction, Cardinal assigns a unique identifier to the consumer session called a
consumerSessionId
. This
consumerSessionId
 ensures that Cardinal matches the correct device data collection results to a request.
Cybersource
 calls this session identifier
payerAuthEnrollService_referenceID
. You must assign the value of the
consumerSessionId
 field to the
payerAuthEnrollService_referenceID
 field so that
Cybersource
 can also track the calls for each user session.
Study the code example shown below for completing the
cardinal.init()
 process.
Cardinal.init() (Android SDK) 
cardinal = Cardinal.getInstance();
String serverJwt = "INSERT_YOUR_JWT_HERE";
cardinal.init(serverJwt ,
new CardinalInitService() {
    /**
    * You may have your Submit button disabled on page load. Once you are 
    * set up for CCA, you may then enable it. This will prevent users 
    * from submitting their order before CCA is ready.
    */
    @Override
    public void onSetupCompleted(String consumerSessionId) {
  
    }
    /**
    * If there was an error with set up, Cardinal will call this function
    * with validate response and empty serverJWT
    * @param validateResponse
    * @param serverJwt will be an empty
    */
    @Override
    public void onValidated(ValidateResponse validateResponse, String serverJwt) {
  
    }
});

Using the iOS SDK

A mobile SDK is available for integrating payer authentication services into mobile applications running on the iOS platform.

Downloading and Importing the SDK

Download the
CardinalMobile.framework
 file using the cURL program in this example.
Download CardinalMobile.framework 
curl -L -u <USER_NAME>
        :<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip
        -o <LOCAL_FILE_NAME.EXT>

#Example: 
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-1.zip
Download the
CardinalMobile.xcframework
 file using the cURL in this example.
Download CardinalMobile.xcframework
curl -L -u <USER_NAME>
        :<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/<VERSION>-<BUILD_NUMBER>/CardinalMobileiOSXC.zip
        -o <LOCAL_FILE_NAME.EXT>

#Example: 
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/artifactory/ios/2.2.5-1/CardinalMobileiOSXC.zip" -o cardinalmobile2.2.5-1.zip
In your XCode project, drag the
CardinalMobile.framework
 file into the Frameworks group in your Xcode Project. (Create the group if it does not already exist.) In the import dialog box, check the box to Copy items into the destinations group folder (or Destination: Copy items if needed). The iOS SDK files are now available for linking in your project.

Configuring Your Build Environment

Follow these to configure your build environment:
  1. Open Xcode, and in the source list to the left of the main editor area, choose your project.
  2. Under the Targets section, select your application and open the
    General
     tab.
  3. Expand the Embedded Binaries section and click the small plus (
    +
    ) at the bottom of the list.
  4. From the list, add the
    CardinalMobile.framework
     file.

Configuring the iOS SDK

Use
CardinalSession new
 to create a new instance of the cardinal object. Use the default configuration options. Study these examples to complete the iOS SDK configuration.
For more details on configuration options, refer to the table after the examples.
CardinalSession new (iOS SDK - Objective-C)
#import <CardinalMobile/CardinalMobile.h>

CardinalSession *session;

//Setup can be called in viewDidLoad
- (void)setupCardinalSession {
    session = [CardinalSession new]; 
    CardinalSessionConfiguration *config = [CardinalSessionConfiguration new];
    config.deploymentEnvironment = CardinalSessionEnvironmentProduction;
    config.timeout = CardinalSessionTimeoutStandard;
    config.uiType = CardinalSessionUITypeBoth;

    UiCustomization *yourCustomUi = [[UiCustomization alloc] init];
    //Set various customizations here. See "iOS UI Customization" documentation for detail.
    config.uiCustomization = yourCustomUi;
 
    CardinalSessionRenderTypeArray *renderType = [[CardinalSessionRenderTypeArray alloc] initWithObjects:
                               CardinalSessionRenderTypeOTP,
                               CardinalSessionRenderTypeHTML,
                               nil];
    config.renderType = renderType;
 
    config.enableQuickAuth = false;
    [session configure:config];
}
CardinalSession new (iOS SDK - Swift) 
import CardinalMobile

var session : CardinalSession!
 
//Setup can be called in viewDidLoad
func setupCardinalSession{
    session = CardinalSession()
    var config = CardinalSessionConfiguration()
    config.deploymentEnvironment = .production
    config.timeout = 8000
    config.uiType = .both
 
    let yourCustomUi = UiCustomization()
    //Set various customizations here. See "iOS UI Customization" documentation for detail.
    config.uiCustomization = yourCustomUi
 
    config.renderType = [CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML]
    config.enableQuickAuth = true
    session.configure(config)
}
iOS Configuration Options
Method
Description
Default Values
Possible Values
deploymentEnviron ment
The environment to which the SDK connects.
CardinalSessionEnviron mentProduction
CardinalSession Environment
Staging
CardinalSessionEnvi ronment
Production
timeoutInMilli seconds
Maximum amount of time (in milliseconds) for all exchanges.
8000
uiType
Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
CardinalSessionUIType Both
CardinalSessionUIT ypeBoth
CardinalSessionUIT ypeNative
CardinalSessionUIT ypeHTML
renderType
List of all the render types that the device supports for displaying specific challenge user interfaces within the SDK.
[CardinalSessionRend erTypeOTP,
CardinalSessionRend erTypeHTML,
CardinalSessionRend erTypeOOB,
CardinalSessionRend erTypeSingleSelect,
CardinalSessionRend erTypeMultiSelect]
CardinalSessionRen derType
OTP
CardinalSessionRen derType
HTML
CardinalSessionRen derType
OOB
CardinalSessionRen derType
SingleSelect
CardinalSessionRen derType
MultiSelect
proxyServerURL
Proxy server through which the Cardinal SDK Session operates.
nil
enableQuickAuth
Enable Quick Authentication
false
uiCustomization
Set Custom UICustomization for SDK-Controlled Challenge UI.
nil
enableDFSync
Enable DF Sync to get onSetupCompleted called after collected device data is sent to the server.
false

Setting Up the Initial Request

Requesting the
cardinal session setup
 process begins the communication process, authenticates your credentials (server JWT), and completes the data collection process. By the time the customer is ready to check out, all necessary preprocessing is complete.
Each time a user begins a mobile transaction, a unique value is assigned to the
consumerSessionId
 API field to identify the session. This value ensures that the correct device data collection results are matched to each user request.
Cybersource
 uses its
payerAuthEnrollService_referenceID
 field to contain Cardinal's
consumerSessionId
 value. You must assign the value of the
consumerSessionId
 field to the
payerAuthEnrollService_referenceID
 field so that
Cybersource
 can also track the requests for each user session.
Study these code examples to understand how to complete setting up the cardinal session process. The function request must be placed in your Checkout ViewController.
Cardinal session setup (iOS SDK - Objective-C)
NSString *accountNumberString = @"1234567890123456";
NSString *jwtString = @"INSERT_YOUR_JWT_HERE";
 
[session setupWithJWT:jwtString 
          didComplete:^(NSString * _Nonnull consumerSessionId){
//
    // You may have your Submit button disabled on page load. Once you are 
    // setup for CCA, you may then enable it. This will prevent users 
    // from submitting their order before CCA is ready.
    //
} didValidate:^(CardinalResponse * _Nonnull validateResponse) {
    // Handle failed setup
    // If there was an error with setup, cardinal will call this 
    // function with validate response and empty serverJWT
}];
Cardinal session setup (iOS SDK - Swift)
let accountNumberString = "1234567890123456"
let jwtString = "INSERT_YOUR_JWT_HERE"

session.setup(jwtString: jwtString, completed: { (consumerSessionId: String) in
    //
    // You may have your Submit button disabled on page load. Once you 
    // are setup for CCA, you may then enable it. This will prevent 
    // users from submitting their order before CCA is ready.
    //
}) { (validateResponse: CardinalResponse) in
    // Handle failed setup
    // If there was an error with setup, cardinal will call this 
    // function with validate response and empty serverJWT
}

Running Payer Authentication with SDK

The payer authentication process in SDK requires checking whether a customer is participating in a card authentication program. If the customer is enrolled in payer authentication, you validate their current status in the program and authorize the transaction. The following procedures describe how to ensure the correct data values are passed during the payer authentication process.

Requesting the Check Enrollment Service (SDK)

After the SDK completes the device collection from your mobile application, and after the customer clicks the Buy button, you must make a back-end, server-to-server call to request the Enrollment Check service.
The Check Enrollment service verifies that the card is enrolled in a card authentication program. The merchant ID is included as part of the header, but these fields are required in the request:
  • billTo_city
  • billTo_country
  • billTo_email
  • billTo_firstName
  • billTo_lastName
  • billTo_postalCode
  • billTo_state
  • billTo_street1
  • card_accountNumber
  • card_cardType
  • card_expirationMonth
  • card_expirationYear
  • merchantID
  • merchantReference Code
  • payerAuthEnrollService_referenceID
  • payerAuthEnrollService_run
  • purchaseTotals_currency
  • purchaseTotals_grandTotalAmount
To reduce your issuer step-up authentication rates, you can send additional request data in the order. It is best to send all available fields.
Use the enrollment check and card authorization services in the same request or in separate requests:
  • Same request:
    Cybersource
     attempts to authorize the card if your customer is not enrolled in a payer authentication program. In this case, the field values that are required to prove that you attempted to check enrollment are passed automatically to the authorization service. If authentication is required, processing automatically stops.
  • Separate requests: Manually include the enrollment check result values (Enrollment Check response fields) in the authorization service request (Card Authorization request fields).
Be sure to include the following card-specific information in your authorization request:
  • For Visa,
    JCB,
    China UnionPay, Elo,
    Diners Club, Discover
     and American Express include the CAVV.
  • For Mastercard only, include the collection indicator and the AAV (also known as UCAF).
These fields are listed in this table.
Enrollment Check and Response Fields
Identifier
Enrollment Check Response Field
Card Authorization Request Field
E-commerce indicator
payerAuthEnrollReply_ commerceIndicator
ccAuthService_commerceIn dicator
Collection indicator
payerAuthEnrollReply_ucaf CollectionIndicator
ucaf_collectionIndicator
CAVV
payerAuthValidateReply_cavv
ccAuthService_cavv
AAV
payerAuthValidateReply_ucafAuthenticationData
ucaf_authenticationData
XID
payerAuthEnrollReply_xid
 and
payerAuthValidateReply_xid
ccAuthService_xid
Result of the enrollment check for Asia, Middle East, and Africa Gateway
payerAuthEnrollReply_veresEnrolled
3-D Secure
 version
payerAuthEnrollReply_specificationVersion
ccAuthService_paSpecificationVersion
Directory server transaction ID
payerAuthEnrollReply_direc toryServerTransactionID
ccAuthService_directorySer verTransactionID

Interpreting the Response

In EMV
3-D Secure
, there are two possible responses:
  • Frictionless: No challenge or stepup to the cardholder. While frictionless authentication can indicate a successfully authenticated outcome because the customer's card is enrolled in a payer authentication program, it can also result from the bank failing or rejecting authentication without challenging the cardholder. In the frictionless authentication flow, you receive a PAResStatus of either
    Y
    ,
    A
    ,
    N
    ,
    I
    ,
    R
    , or
    U
     with an associated ECI value. With successful frictionless authentication, the PAResStatus =
    Y
     or
    A
     and you receive a CAVV. You may also receive a PAResStatus =
    I
     indicating successful authentication, but it might not include a CAVV.
  • Challenge: The response contains PAResStatus =
    C
    . A challenge response has a payload and contains an ACS URL and a step up URL. Challenge the cardholder to provide additional authentication information and display an authentication challenge window to the cardholder so the cardholder can respond to a validation request and receive a validation response.

Authenticating Enrolled Cards

In the response from the enrollment check service, confirm that you receive these fields and values:
  • 3-D Secure
     version = 2.x
  • VERes enrolled = Y
  • PARes status = C
These values identify whether it is an EMV
3-D Secure
 2.x transaction and that a challenge is required.
After you validate these fields, you request the
Cardinal.cca_continue
 process (Android SDK) or the
Cardinal session continue
process (iOS SDK) for the SDK to perform the challenge between the customer and the issuing bank.

Calling Cardinal.cca_continue (Android SDK)

After you verify that a customer’s card is enrolled in a card authentication program, you must include the payload and the
payerAuthEnrollReply_authenticationTransactionID
 response field and incorporate them into the
Cardinal.cca_continue
 function as shown in this example before proceeding with the authentication session.
/**
 * Cca continue.
 *
 * @param transactionId     the transaction id
 * @param payload           the payload
 * @param currentActivity   the current activity
 * @throws InvalidInputException        the invalid input exception
 * @throws JSONException                the json exception
 * @throws UnsupportedEncodingException the unsupported encoding exception
 */
try {
    cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", this, new CardinalValidateReceiver() {
           /**
            * This method is triggered when the transaction 
            * has been terminated. This is how SDK hands back
            * control to the merchant's application. This method will
            * include data on how the transaction attempt ended and
            * you should have your logic for reviewing the results of
            * the transaction and making decisions regarding next steps.
            * JWT will be empty if validate was not successful.
            *
            * @param validateResponse
            * @param serverJWT
            */
           @Override
           public void onValidated(Context currentContext, ValidateResponse validateResponse, String serverJWT) {
           }
       });
 }
catch (Exception e) {
   // Handle exception
 }

Calling Cardinal session continue (iOS SDK)

When you have verified that a customer’s card is enrolled in a card authentication program, include the payload, and the
payerAuthEnrollReply_authenticationTransactionID
 response field and incorporate them into the
Cardinal session continue
 function before proceeding with the authentication session.
In the
Cardinal session continue
 function, you should pass a class conforming to the
CardinalValidationDelegate
 protocol (and implement the
stepUpDidValidate
 method) as a parameter. These examples show a class conforming to the
CardinalValidationDelegate
 protocol.

Objective-C Examples

Cardinal session continue (iOS SDK - Objective-C) 
@interface YourViewController()<CardinalValidationDelegate>{ //Conform your ViewController or any other class to CardinalValidationDelegate protocol
   
}
@end
  
@implementation YourViewController
  
    /**
     * This method is triggered when the transaction has 
     * been terminated.This is how SDK hands back
     * control to the merchant's application. This method will
     * include data on how the transaction attempt ended and
     * you should have your logic for reviewing the results of
     * the transaction and making decisions regarding next steps.
     * JWT will be empty if validate was not successful
     *
     * @param session
     * @param validateResponse
     * @param serverJWT
     */
    -(void)cardinalSession:(CardinalSession *)session stepUpDidValidateWithResponse:(CardinalResponse *)validateResponse serverJWT:(NSString *)serverJWT{
       
    }
  
@end
If the
Cardinal.continue
 process is requested in the same class, request the method shown in the following example to start the step up flow.
Cardinal.continue Request in the Same Class (Objective-C)
[session continueWithTransactionId: @"[TRANSACTION_ID]"
                           payload: @"[PAYLOAD]"
               didValidateDelegate: self];

Swift Examples

Cardinal session continue (iOS SDK - Swift)
class YourViewController:CardinalValidationDelegate {
  
    /**
     * This method is triggered when the transaction has been 
     * terminated.This is how SDK hands back
     * control to the merchant's application. This method will
     * include data on how the transaction attempt ended and
     * you should have your logic for reviewing the results of
     * the transaction and making decisions regarding next steps.
     * JWT will be empty if validate was not successful
     *
     * @param session
     * @param validateResponse
     * @param serverJWT
     */
    func cardinalSession(cardinalSession session: CardinalSession!, stepUpValidated validateResponse: CardinalResponse!, serverJWT: String!) {
        
    }
 
}
If the
Cardinal.continue
 function is requested in the same class, request the method shown in the example below to start the step up flow.
Cardinal.continue Request in the Same Class (Swift)
session.continueWith(transactionId: "[TRANSACTION_ID]", payload: "[PAYLOAD]", validationDelegate: self)
When necessary, the SDK displays the authentication window and the customer enters their authentication information.

Receiving the Authentication Results

Next, the
onValidated()
 function (Android SDK) or the
stepUpDidValidate
 function (iOS SDK) launches and returns the authentication results and response JWT along with the processor transaction ID as shown in this example.
Decoded Response JWT
{
  "iss": "5a4504be6fe3d1127cdfd94e",
  "iat": 1555075930,
  "exp": 1555083130,
  "jti": "cc532159-636d-4fa8-931d-d4b0f4c83b99",
  "ConsumerSessionId": "0_9a16b7f5-8b94-480d-bf92-09cd302c9230",
  "aud": "d0cf3392-62c5-4107-bf6a-8fc3bb49922b",
  "Payload": {
    "Payment": {
      "Type": "CCA",
      "ProcessorTransactionId": "YGSaOBivyG0dzCFs2Zv0"
    },
    "ErrorNumber": 0,
    "ErrorDescription": "Success"
  }
}

Requesting the Validation Service

For enrolled cards, the next step is to make a back-end, server-to-server request for the validation service.
When you make the validation request, you must:
  • Send the
    payerAuthValidateService_authenticationTransactionID
     request field.
  • Send the credit card information including the PAN, currency, and expiration date (month and year).
The response that you receive contains the validation result.
It is recommended that you request the payer authentication and card authorization services at the same time. Doing so automatically sends the correct information to your payment processor and converts the values of these fields to the proper format required by your payment processor:
  • payerAuthEnrollReply_commerceIndicator
  • payerAuthValidateReply_cavv
  • payerAuthValidateReply_ucafAuthenticationData
  • payerAuthEnrollReply_xid
     and
    payerAuthValidateReply_xid
If you request the services separately, manually include the validation result values (Validation Check response fields) in the authorization service request (Card Authorization request fields). To receive liability shift protection, you must ensure that you pass all pertinent data for the card type and processor in your request. Failure to do so might invalidate your liability shift for that transaction. Include the electronic commerce indicator (ECI), the transaction ID (XID), the 3-D Secure version, the directory server transaction ID, and this card-specific information in your authorization request.
  • For Visa,
    JCB,,
    China UnionPay, Elo,
    Diners Club, Discover,
     and American Express include the CAVV.
  • For Mastercard only, include the collection indicator and the AAV (also known as UCAF).
Validation Check and Response Fields
Identifier
Validation Check Response Field
Card Authorization Request Field
E-commerce indicator
payerAuthValidateReply_commerceIndicator
e_commerce_indicator
Collection indicator
payerAuthValidateReply_ucafCollectionIndicator
ucaf_collection_indicator
CAVV
payerAuthValidateReply_cavv
ccAuthService_cavv
AAV
payerAuthValidateReply_ucafAuthenticationData
ucaf_authenticationData
XID
payerAuthValidateReply_xid
ccAuthService_xid
3-D Secure
 version
payerAuthValidateReply_specifi cationVersion
ccAuthService_paSpecificationVersion
Directory server transaction ID
payerAuthValidateReply_directory ServerTransactionID
ccAuthService_directoryServerTransactionID

Interpreting the Response

If the authentication fails, Visa,
Diners Club, Discover,
JCB,
China UnionPay, Elo,
 and American Express require that you not accept the card. Instead, you must ask the customer to use another payment method.
Proceed with the order according to the validation response received. The responses are similar for all card types:
  • Success: You receive
    reason code
    100
    , and other service requests, including authorization, are processed normally.
  • Failure: You receive
    reason code
    476
     indicating that the authentication failed
    , so the other services in your request are not processed.
  • Error: If you receive an error from the payment card company, process the order according to your business rules. If the error occurs frequently, report it to customer support. If you receive a system error, determine the cause, and proceed with card authorization only if appropriate.
To verify that the enrollment and validation checks are for the same transaction, ensure that the XID in the enrollment check and validation responses are identical.

Redirecting Customers to the Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. Ensure that all messages that display to customers are accurate, complete, and address all possible scenarios for enrolled and non-enrolled cards. For example, if the authentication fails, display a message such as this to the customer:
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.

Authentication Examples Using Primary Account Numbers

These examples list the API fields that are required or optional for the Setup, Check Enrollment, and Validate Authentication services. An example of a request payload and a successful response that occur with each service is provided. Payer authentication has three types of examples:
  • Primary Account Number (PAN): Illustrates how the payer authentication services work with customer PANs during transactions.
  • Tokens: Illustrates how the payer authentication services work with different types of tokens.
  • 3RI: Illustrates how the payer authentication services work with merchant-initiated transactions.
In certain circumstances, some payment card companies and some countries require more information than is normally collected when authenticating the customer. These circumstances, and the API fields to use in those circumstances, are noted for each case.

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.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Device Data Collection

These fields are the minimum fields required when you request the Payer Authentication Setup service. Other fields that can be used to collect additional information during a transaction are listed in the optional fields section. Under certain circumstances, a field that is normally optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for the US and Canada.
This field is required when the card type is Cartes Bancaires,
JCB,
China UnionPay, or Meeza.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
payerAuthSetupService_run

Optional Fields for Device Data Collection

These fields are optional for setting up a Payer Authentication transaction. Under certain circumstances, a field might appear as both an optional field and a required field.

Simple Order Example: Setting Up Device Data Collection

Request
card_accountNumber=XXXXXXXXXXXXXXXX
card_expirationMonth=12
card_expirationYear=2030
merchantID=patest
merchantReferenceCode=0001
payerAuthSetupService_run=true
Response to Successful Request
decision=ACCEPT
merchantReferenceCode=0001
payerAuththSetupReply_deviceDataCollectionURL=https://centinelapistag.cardinalcommerce.com/V1 /Cruise/Collect
payerAuthSetupReply_reasonCode=100
payerAuthSetupReply_referenceID=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
payerAuthSetupReply_accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi0z YmEzLTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ 5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElkIjoiNTVlZjNmMTBmNzIzYWE0MzFjOTliNWViIiwiUGF 5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2 hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56W VdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkzTkRNeVlUWXdN QzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkRFM01EaGhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb2lPR0U1TkRkaU9E TXRNRFJpTkMwMFltVmlMV0V5WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw 2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifSwiT2JqZWN0aWZ5UGF5bG9h ZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zdGVwLXVwLXJldHVybi11cmwuanNwIn0.8w Z8XhLgOIIRvgEUugvYrRAi-efavZTNM0tWInYLTfE
payerAuthSetupReply_reasonCode=100
requestID=5982993692286989203011
requestToken=AxjzbwSTRFa3h+A4wXZDABEBURwlqraRpAy7gDthk0kyro9JLIYA8AAA2wK2

Checking Enrollment in Payer Authentication

The Check Enrollment service tries to authenticate the cardholder. If the cardholder can be authenticated without additional information, the transaction can be authorized. If more information is required, the cardholder will be challenged to provide additional authentication.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (U.S.) when the product code is
AIR
 for an airline purchase.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
China
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Required Fields for Checking Enrollment in Payer Authentication

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentation program. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required for transactions in the US and Canada.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_workNumber
 is not used.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for SDK integration. When you use the SDK integration, this field is dynamically set to
SDK
. When you use the JavaScript code, this field is dynamically set to
Browser
. For merchant-initiated or 3RI transactions, you must set the field to
3RI
. When you use this field in addition to JavaScript code, you must set the field to
Browser
.
When the customer’s browser provides a value, include that value in your request.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required if
payerAuthEnrollService_workPhone
 or
billTo_phoneNumber
 is not used.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_phoneNumber
 is not used.
This field is optional when you use the
item_#_unitPrice
 field.

Optional Fields for Checking Enrollment in Payer Authentication

These fields are usually optional when you verify enrollment for a Payer Authentication transaction. In certain circumstances, the information provided by an optional field might be required before a transaction can proceed. Those optional fields that are sometimes required are also listed as required fields with the circumstance described.
This field is required for each leg.
The numbered element name should contain 0 instead of #. Payer Authentication services only use the first leg of the trip.
This field is required for each leg.
airlineData_numberOfPassengers
billTo_customerAccountChangeDate
billTo_customerAccountCreateDate
billTo_customerAccountPasswordChange Date
merchantDefinedData_mddField_1
 to
merchantDefinedData_mddField_5
These fields override the old merchant-defined data fields. For example, when you use the obsolete field
merchantDefinedData_field5
 and the new field
merchantDefinedData_mddField_5
 in the same request, the new field value overwrites the value specified in the obsolete field.
Merchant-defined data fields are not intended to and must not be used to capture personally identifying information. Accordingly, merchants are prohibited from capturing, obtaining, and/or transmitting any personally identifying information in or via the merchant defined data fields. Personally identifying information includes, but is not limited to, address, credit card number, Social Security number, driver's license number, state-issued identification number, passport number, and card verification numbers (CVV, CVC2, CVV2, CID, CVN). When a merchant is discovered capturing and/or transmitting personally identifying information via the merchant-defined data fields, whether intentionally or accidentally, the merchant's account is immediately suspended, resulting in a rejection of any and all transaction requests submitted by the merchant after the point of suspension.
pa_otpToken
This field is only used with mada cards.
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_addCardAttempts
This field is recommended for Discover ProtectBuy.
This field is required for Standard integration.
This field defaults to
01
 on your account but is overridden by the merchant when you include this field. EMV 3-D Secure version 2.1.0 supports values
01
-
04
. Version 2.2.0 supports values
01
-
09
.
Modifying this field could affect your liability shifts. Unless you are very familiar with the various types of authentication, do not change the default settings before consulting with customer support.
This field is required when tokenization is enabled in the merchant profile settings.
This field is recommended for Discover ProtectBuy.
This field is recommended for Discover ProtectBuy.
This field is required when the merchant and cardholder have agreed to installment payments.
This field is recommended for Discover ProtectBuy.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is the merchant bank identifier, such as Paymentech’s division, FDC’s Terminal ID, or Vital V number. Use this field for evaluation, testing, and production. This number is not your merchant ID.
This field is required for Visa Secure travel.
This field is required for transactions processed in France.
payerAuthEnrollService_ paymentAccountDate
This field is recommended for Discover ProtectBuy.
This field is required for American Express SafeKey (U.S.) when the product code is AIR (Airline purchase).
This field is required for recurring transactions.
This field is required for recurring transactions.
This field is required for recurring transactions.
This field is required for Hybrid or Cardinal Cruise Direct Connection API integration.
EMV 3-D Secure version 2.1.0 supports values
01
-
05
. Version 2.2.0 supports values
01
-
11
.
This field is required for 3-D Secure 2.x.
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_transactionCount Day
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_transactionCount Year
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_whiteListStatus
This field is required when any shipping address information is included. Required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required when the
bill_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
US
 or
CA
. Required for American Express SafeKey (U.S.).
This field is required only for American Express SafeKey (US).
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
Mainland China
. Required for American Express SafeKey (U.S.).
This field is required when any shipping address information is included. Required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).

Simple Order Example: Checking Enrollment

Request
billTo_city=Mountain View
billTo_country=US
billTo_email=test@email.com
billTo_firstName=Tanya
billTo_lastName=Lee
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1234 Gold Ave
card_accountNumber=XXXXXXXXXXXXXXXX
card_cardType=001
card_cvNumber=111
card_expirationMonth=12
card_expirationYear=2030
ccAuthService_run=true
merchantID=patest
merchantReferenceCode=0001
payerAuthEnrollService_referenceID=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
payerAuthEnrollService_returnURL=https://example.com/step-up-return-url.jsp
payerAuthEnrollService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
Response 

decision=REJECT
merchantReferenceCode=0001
payerAuthEnrollReply_accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi0z YmEzLTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6IjVkZDgzYmYwMGU0MjNk MTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElkIjoiNTVlZjNmMTBmNzIzYWE0MzFjOTliNWViIi wiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20 vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDS nRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkzT kRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkRFM01EaGhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb 2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVmlMV0V5WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVj JsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifS wiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zdGVwLXV wLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-efavZTNM0tWInYLTfE
payerAuthEnrollReply_acsTransactionID=8a947b83-04b4-4beb-a2b3-dcc1a5f94a12
payerAuthEnrollReply_acsURL=https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp
payerAuthEnrollReply_authenticationTransactionID=TD5oS0o1FC65qav0xsx0
payerAuthEnrollReply_cardBin=40000000
payerAuthEnrollReply_cardTypeName=VISA
payerAuthEnrollReply_challengeRequired=false
payerAuthEnrollReply_directoryServerTransactionID=395fb036-cfc6-462b-b28d-d6ed7c970cdd
payerAuthEnrollReply_paReq=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhy ZWVEU1NlcnZlclRyYW5zSUQiOiI3NDMyYTYwMC04MzM2LTRmODctYWJlOS02NmY3NDE3MDhhMWQiLCJhY3NU cmFuc0lEIjoiOGE5NDdiODMtMDRiNC00YmViLWEyYjMtZGNjMWE1Zjk0YTEyIiwiY2hhbGxlbmdlV2luZG93U2l 6ZSI6IjAyIn0
payerAuthEnrollReply_reasonCode=475
payerAuthEnrollReply_specificationVersion=2.2.0
payerAuthEnrollReply_stepUpUrl=https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp
payerAuthEnrollReply_threeDSServerTransactionID=7432a600-8336-4f87-abe9-66f741708a1d
payerAuthEnrollReply_veresEnrolled=Y
reasonCode=475
requestID=5982995245816268803007
requestToken=AxjzbwSTRFa9DM1xnUu/ABEBURwlqsQ5pAy7gDtXb0kyro9JLIYA8AAA2wK2

Checking Enrollment and Authorizing a Transaction

The Checking Enrollment service can be combined with the Authorization service so that when a customer's authentication does not require a challenge, the transaction is automatically submitted for authorization.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is required when the card type is Cartes Bancaires,
JCB,
 China UnionPay, or Meeza.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (U.S.) when the product code is
AIR
 for an airline purchase.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
China
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Validating a Challenge

Running the Validation service compares the customer's response to the challenge from the issuing bank to validate the customer identity.

Card-Specific Requirements

Some payment cards require additional information to be collected during a transaction.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (US) when the product code is
AIR
 for an airline purchase).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US)

Country-Specific Requirements

These fields are required for transactions in specific countries.
TThis field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for transactions in the US and Canada.
This field is required for transactions processed in France.

Endpoint

Set the
payerAuthValidateService_run
 fields to
true
.
Send the request to:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Validating a Challenge

Required Fields

This field is required when the
card_accountNumber
 field is included.
This field is required when the
card_accountNumber
 field is included.
This field is required when the
purchaseTotals_grandTotalAmount
 field is not used.
payerAuthValidateService_run
This field is required when the
item_#_unitPrice
 field is not used.

Optional Fields for Validating a Challenge

These fields are optional when validating a Payer Authentication transaction. In certain circumstances, the information provided by an optional field might be required before a transaction can proceed. Those optional fields that are sometimes required are listed in the required fields with the circumstance described.

Simple Order Example: Validating a Challenge

Request 
merchantID=patest merchantReferenceCode=0001
payerAuthValidateService_authenticationTransactionID=hejNPA0YQlL5gVwZ6OX0
payerAuthValidateService_run=true 
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
Response to Successful Request
decision=ACCEPT
merchantReferenceCode=0001
payerAuthValidateReply_acsTransactionID=ff412c09-4ea8-4f37-923e-4c405fb3951c
payerAuthValidateReply_authenticationResult=0
payerAuthValidateReply_authenticationStatusMessage=Success
payerAuthValidateReply_cardBin=40000000
payerAuthValidateReply_cardTypeName=VISA
payerAuthValidateReply_cavv=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
payerAuthValidateReply_commerceIndicator=vbv
payerAuthValidateReply_directoryServerTransactionID=6c29615b-1a1e-4c13-9739-0394917163a3
 payerAuthValidateReply_eci=05
payerAuthValidateReply_eciRaw=05
payerAuthValidateReply_paresStatus=Y
payerAuthValidateReply_reasonCode=100
payerAuthValidateReply_specificationVersion=2.1.0
 payerAuthValidateReply_threeDSServerTransactionID=2c2294e9-6b70-4b19-bedb-7b43065f20ce
 payerAuthValidateReply_xid=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
reasonCode=100
requestID=6001869286506329603009

Validating and Authorizing a Transaction

The Validation service can be combined with the Authorization service so that when a customer's authentication is validated, the transaction is automatically submitted for authorization.

Fields Specific to a Visa Secure Transaction

These API fields are required specifically for this use case.
Set this field to
vbv
 for a successful authentication (EMV
3-D Secure
 value of
05
),
vbv_attempted
 if authentication was attempted but did not succeed (EMV 3-D Secure value of
06
), or
vbv_failure
 if authentication failed (EMV
3-D Secure
 value of
07
).
This field is required when payer authentication is successful.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for American Express SafeKey (US) when the product code is
AIR
 for an airline purchase.
This field is required for Visa Secure travel.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for transactions in the US and Canada.

Endpoint

Set the
payerAuthValidateService_run
 and
ccAuthService_run
 fields to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for Processing an Authorization Using Visa Secure

Use these required fields to process an authorization using Visa Secure.
When relaxed requirements for address data and the expiration date are being used, not all fields in this list are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. Refer to the Payments guide for more information about relaxed requirements in payment transactions.

Required Fields

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_expirationMonth
card_expirationYear
ccAuthService_cavv
This field is required when payer authentication is successful. Otherwise, this field is optional.
ccAuthService_commerceIndicator
Set the value of this field to one of these values:
  • vbv
    : Successful authentication (EMV
    3-D Secure
     value of
    05
    ).
  • vbv_attempted
    : Authentication was attempted (EMV
    3-D Secure
     value of
    06
    ).
  • vbv_failure
    : or
    internet
    : Authentication failed or was not attempted (EMV
    3-D Secure
     value of
    07
    )
ccAuthService_run
Set the value of this field to
true
.
ccAuthService_xid
merchant_referenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Validating and Authorizing an Authorization

Request
billTo_city=Sao Paulo
billTo_country=BR
billTo_email=julia@email.com
billTo_firstname=Julia
billTo_lastname=Fernandez
billTo_postalCode=01310-000
billTo_state=SP
billTo_street1=R. Augusta
card_accountNumber=41111111XXXXXXXX
card_expirationMonth=12
card_expirationYear=2023
ccAuthService_run=true
ccAuthService_cavv=ABCDEFabcdefABCDEFabcdef0987654321234567
ccAuthService_commerceIndicator=vbv
ccAuthService_xid=MID23
merchant_referenceCode=Merchant_REF
purchaseTotals_currency=mxn
purchaseTotals_grandTotalAmount=100
Response to a Successful Request

merchantReferenceCode=Merchant_REF
request_id=6461515866500167772420
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=mxn
ccAuthReply_cardCategory=F
ccAuthService_reconciliationID=ZUDCXJO8KZRFXQJJ
ccAuthReply_reasonCode=100
ccAuthReply_amount=100.00
ccAuthReply_avsCode=5
ccAuthReply_authorizationCode=570110
ccAuthReply_processorResponse=1
ccAuthReply_authorizedDateTime=2022-03-01T161947Z
ccAuthReply_paymentNetworkTransactionID=111222

Non-Payment Authentication

Non-Payment Authentication (NPA) requests enable a merchant to authenticate a customer without a transaction. A non-payment use case can be used for such tasks as adding a card to a merchant website, updating cardholder information on file, or to verify a cardholder's identity when creating a token for future use. The same authentication used during the checking enrollment process is used for NPA. Non-payment use cases are enabled using a combination of the
payerAuthEnrollService_messageCategory
 and
payerAuthEnrollService_authenticationIndicator
 values. For example to add a card to a loyalty program, set the Message Category value to
02
 and the Authentication Indicator value to
04
. For other possible NPA use cases, refer to the other possible values for
payerAuthEnrollService_messageCategory
. The
payerAuthEnrollService_messageCategory
 value must be set to
02
 (non-payment authentication) to specify that the authentication is not for a transaction.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza
.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (U.S.) when the product code is
AIR
 for an airline purchase.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
China
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Examples Using
3-D Secure
 Data Only

3-D Secure
 data only is a solution that shares data that merchants collect during transactions with the issuer, so that the issuers can make more informed authorization decisions for future transactions. Data only uses the
3-D Secure
 infrastructure, but it is not a complete
3-D Secure
 authentication.
3-D Secure
 data only is a frictionless experience.
Data only can increase authorization approvals and reduce fraud in the following ways:
  • While some merchants have their own fraud tools,
    3-D Secure
     data only focuses on increasing approvals. Fraud is decreased with data only.
  • Merchants share additional transaction data with the issuer, allowing the issuer to feel more comfortable with the transaction’s risk level. The issuer can gain additional insight into who the buyer is and what they are purchasing which enables better authorization decisions.
  • Since data only is not a full authentication, merchants retain fraud liability, putting less risk on the issuers, which might lead to a higher approval rate when compared to non-authenticated transactions.
Visa supports
3-D Secure
 within the Visa Data Only program, and Mastercard supports data only with Identity Check Insights.

Visa Data Only

Visa has a data only data flow so that merchants can share customer data with the issuers without going through authentication. The additional data provided to the issuer helps the issuer make risk assessments about approving cardholder transactions. Data only data flows are frictionless and do not affect the customer experience. When sending a Visa data only check enrollment request, be sure to include all of the required fields and set the
CodepayerAuthEnrollService_challengeCode
 field to
06
.
The response from the data only request will include this data:
  • ECI =
    07
  • PARes =
    I
  • <CAVV> value
This data from the response must be included in the authorization request.

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to:

Required Fields for Visa Data Only

These fields are the minimum fields required when you request the Visa Data service. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required for transactions in the US and Canada.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_workNumber
 is not used.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
This field is required if
payerAuthEnrollService_workPhone
 or
billTo_phoneNumber
 is not used.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_phoneNumber
 is not used.

Simple Order Example: Testing Visa Data Only

Request
bill_address1=test address
bill_city=test city
bill_country=US
bill_state=MI
bill_zip=48104-2201
http_browser_color_depth=24
http_browser_java_enabled=N
http_browser_javascript_enabled=Y
http_browser_language=en_us
http_browser_screen_height=864
http_browser_screen_width=1536
http_browser_time_difference=300
http_user_accept=pa_http_user_accept
pa_http_user_agent =http_user_agent
pa_http_user_accept=pa_http_user_accept
card_type=001
currency=usd
customer_cc_expmo=12
customer_cc_expyr=2026
customer_cc_number= 4000000000002024
pa_challenge_code=06
grand_total_amount=100.00
ics_applications=ics_pa_enroll
merchant_id=patest1
merchant_ref_number=patest1
sender_id=ms_user

Simple Order Example: Bundled Authentication and Authorization with Visa Data Only

Request
bill_address1=test address
bill_city=test city
bill_country=US
bill_state=MI
bill_zip=48104-2201
http_browser_color_depth=24
http_browser_java_enabled=N
http_browser_javascript_enabled=Y
http_browser_language=en_us
http_browser_screen_height=864
http_browser_screen_width=1536
http_browser_time_difference=300
http_user_accept=pa_http_user_accept
pa_http_user_agent =http_user_agent
pa_http_user_accept=pa_http_user_accept
card_type=001
currency=usd
customer_cc_expmo=12
customer_cc_expyr=2026
customer_cc_number= 4000000000002024
pa_challenge_code=06
grand_total_amount=100.00
ics_applications=ics_pa_enroll,ics_auth
merchant_id=patest1
merchant_ref_number=patest1
sender_id=ms_user

Mastercard Data Only

Mastercard has a data only data flow so that merchants can share customer data with the issuers without going through authentication. The additional data provided to the issuer helps the issuer make risk assessments about approving cardholder transactions. Data only data flows are frictionless and do not affect the customer experience.
When sending a Mastercard data only check enrollment request, be sure to include all of the required fields and set the
payerAuthEnrollService_messageCategory
 to
80
.
The response from the data only request includes this data:
  • ECI =
    4
  • CAVV value
  • Directory server transaction ID
  • paresStatus =
    U
  • Risk score
  • Reason code
This data from the response must be included in the authorization request.

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to:

Required Fields for Mastercard Data Only

These fields are the minimum fields required when you request the Mastercard Data service. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_workNumber
 is not used.
.
This field is required if
payerAuthEnrollService_workPhone
 or
billTo_phoneNumber
 is not used.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_phoneNumber
 is not used.

Simple Order Example: Mastercard Data Only

Request
bill_address1=test address
bill_city=test city
bill_country=US
bill_state=MI
bill_zip=48104-2201
http_browser_color_depth=24
http_browser_java_enabled=N
http_browser_javascript_enabled=Y
http_browser_language=en_us
http_browser_screen_height=864
http_browser_screen_width=1536
http_browser_time_difference=300
http_user_accept=pa_http_user_accept
pa_http_user_agent =http_user_agent
pa_http_user_accept=pa_http_user_accept
card_type=002
currency=usd
customer_cc_expmo=12
customer_cc_expyr=2026
customer_cc_number= 5200000000002805
pa_score_request=N
pa_message_category=80
grand_total_amount=100.00
ics_applications=ics_pa_enroll
merchant_id=patest1
merchant_ref_number=patest1
sender_id=ms_user
Response to Successful Request
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=patest1
pa_enroll_authentication_outage_exemption_indicator=0
pa_enroll_authentication_status_msg=Informational Only
pa_enroll_authentication_transaction_id=IS5pM0zQscoVDCKCml81
pa_enroll_authorization_payload=eyJjb250YWluZXJWZXJzaW9uIjoiMSIsImVjaSI6IjA0IiwiYXV0aGVudGljYXRpb25WYWx1ZSI6IkFKa0JCa2hnUVFBQUFFNGdTRUp5ZFFBQ

UFBQT0iLCJlZmZlY3RpdmVBdXRoVHlwZSI6IkZSIiwiYWNzT3BlcmF0b3JJRCI6Ik1lcmNoYW50QUNTIiwidGhyZWVEU1JlcXVlc3RvckNoYWxsZW5nZUluZCI6IjAxIiwidHJhbnNTd

GF0dXMiOiJVIiwidHJhbnNTdGF0dXNSZWFzb24iOiI4MCIsImRzVHJhbnNJRCI6ImRlOGNiZjkzLThlNzQtNDJmYy05MWU0LTMxNzdhYjZkZDI0NCIsImFjc1RyYW5zSUQiOiI3NzRj

MjU1MC02MTJkLTRhOGYtOTUwNi1mMDMwNTYxOTdkYjQiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVyY2hhbnROYW1lIjoiUEFUZXN0NCIsInB1cmNoYXNlRGF0ZSI6IjIwMjUw

NDI1MDk0NDE3IiwicHVyY2hhc2VBbW91bnQiOiIxMDAwMCIsIm1lcmNoYW50Q291bnRyeUNvZGUiOiI4NDAiLCJhY3F1aXJlckJJTiI6IjQ2OTIxNiIsImFjcXVpcmVyTWVyY2hhbnRJRC

I6ImRlZmF1bHQiLCJ0aHJlZURTUmVxdWVzdG9yTmFtZSI6IlBBVGVzdDQiLCJ0aHJlZURTUmVxdWVzdG9ySUQiOiIxMDA1MjIzNio1NWVmM2VmYmY3MjNhYTQzMWM5OWFjNGQ

iLCJjYXJkQnJhbmQiOiJNQVNURVJDQVJEIn0=
pa_enroll_card_bin=520000
pa_enroll_card_type_name=MASTERCARD
pa_enroll_challenge_required=N
pa_enroll_directory_server_transaction_id=de8cbf93-8e74-42fc-91e4-3177ab6dd244
pa_enroll_e_commerce_indicator=spa
pa_enroll_eci_raw=04
pa_enroll_effective_authentication_type=FR
pa_enroll_pa_acs_operator_id=MerchantACS
pa_enroll_pa_acs_reference_number=CardinalACS
pa_enroll_pa_acs_transaction_id=774c2550-612d-4a8f-9506-f03056197db4
pa_enroll_pa_three_ds_server_transaction_id=9166404a-00bb-425e-8cc2-74789f4405f7
pa_enroll_pares_status=U
pa_enroll_pares_status_reason=80
pa_enroll_rcode=1
pa_enroll_rflag=SOK
pa_enroll_rmsg=ics_pa_enroll service was successful
pa_enroll_specification_version=2.2.0
pa_enroll_ucaf_authentication_data=AJkBBkhgQQAAAE4gSEJydQAAAAA=
pa_enroll_ucaf_collection_indicator=4
pa_enroll_veres_enrolled=Y
request_id=7455742587763896572043
request_token=AxjzbwSTlC02rVqit1iLAEQCUS6wE4F5pA6cQT+4ZNscUcfKjUhQFgAAGAZm

Simple Order Example: Bundled Authentication and Authorization with Mastercard Data Only

Request
bill_address1=test address
bill_city=test city
bill_country=US
bill_state=MI
bill_zip=48104-2201
http_browser_color_depth=24
http_browser_java_enabled=N
http_browser_javascript_enabled=Y
http_browser_language=en_us
http_browser_screen_height=864
http_browser_screen_width=1536
http_browser_time_difference=300
http_user_accept=pa_http_user_accept
pa_http_user_agent =http_user_agent
pa_http_user_accept=pa_http_user_accept
card_type=002
currency=usd
customer_cc_expmo=12
customer_cc_expyr=2026
customer_cc_number= 5200000000002805
pa_score_request=N
pa_message_category=80
grand_total_amount=100.00
ics_applications=ics_pa_enroll,ics_auth
merchant_id=patest1
merchant_ref_number=patest1
sender_id=ms_user
Response to Successful Request
additional_data=ABC
auth_additional_token_response_information=0
auth_auth_amount=100.00
auth_auth_avs=Y
auth_auth_code=831000
auth_auth_response=00
auth_auth_time=2025-04-25T094713Z
auth_avs_raw=Y
auth_cavv_response_code=2
auth_cavv_response_code_raw=2
auth_fee_program_indicator=123
auth_merchant_advice_code=01
auth_merchant_advice_code_raw=M001
auth_payment_network_transaction_id=0425MCC498174
auth_rcode=1
auth_reconciliation_reference_number=511509004370
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
auth_trans_ref_no=7455744328063896572043
card_type=002
currency=usd
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
issuer_clearing_data=6700040102F0F1
merchant_ref_number=patest1
pa_enroll_authentication_outage_exemption_indicator=0
pa_enroll_authentication_status_msg=Informational Only
pa_enroll_authentication_transaction_id=iChqahOxuK78PdvcCHK1
pa_enroll_authorization_payload=eyJjb250YWluZXJWZXJzaW9uIjoiMSIsImVjaSI6IjA0IiwiYXV0aGVudGljYXRpb25WYWx1ZSI6IkFKa0JCa2hnUVFBQUFFNGdTRUp5ZFFBQUFBQT0iLCJlZmZlY3RpdmVBdXRoVHlwZSI6IkZSIiwiYWNzT3BlcmF0b3JJRCI6Ik1lcmNoYW50QUNTIiwidGhyZWVEU1JlcXVlc3RvckNoYWxsZW5nZUluZCI6IjAxIiwidHJhbnNTdGF0dXMiOiJVIiwidHJhbnNTdGF0dXNSZWFzb24iOiI4MCIsImRzVHJhbnNJRCI6IjRiMzQ1ZDIxLWYxNDctNGJjMS1iZDBkLWU4N2FlNWE2YWFjYiIsImFjc1RyYW5zSUQiOiJlMjhlODUwYS1iNTI5LTQ0ZDQtYWNiMC0zYWMzMDYxZDlmMjMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwibWVyY2hhbnROYW1lIjoiUEFUZXN0NCIsInB1cmNoYXNlRGF0ZSI6IjIwMjUwNDI1MDk0NzExIiwicHVyY2hhc2VBbW91bnQiOiIxMDAwMCIsIm1lcmNoYW50Q291bnRyeUNvZGUiOiI4NDAiLCJhY3F1aXJlckJJTiI6IjQ2OTIxNiIsImFjcXVpcmVyTWVyY2hhbnRJRCI6ImRlZmF1bHQiLCJ0aHJlZURTUmVxdWVzdG9yTmFtZSI6IlBBVGVzdDQiLCJ0aHJlZURTUmVxdWVzdG9ySUQiOiIxMDA1MjIzNio1NWVmM2VmYmY3MjNhYTQzMWM5OWFjNGQiLCJjYXJkQnJhbmQiOiJNQVNURVJDQVJEIn0=
pa_enroll_card_bin=520000
pa_enroll_card_type_name=MASTERCARD
pa_enroll_challenge_required=N
pa_enroll_directory_server_transaction_id=4b345d21-f147-4bc1-bd0d-e87ae5a6aacb
pa_enroll_e_commerce_indicator=spa
pa_enroll_eci_raw=04
pa_enroll_effective_authentication_type=FR
pa_enroll_pa_acs_operator_id=MerchantACS
pa_enroll_pa_acs_reference_number=CardinalACS
pa_enroll_pa_acs_transaction_id=e28e850a-b529-44d4-acb0-3ac3061d9f23
pa_enroll_pa_three_ds_server_transaction_id=cbd30512-3b7c-4b2e-8481-f2a11f21e794
pa_enroll_pares_status=U
pa_enroll_pares_status_reason=80
pa_enroll_rcode=1
pa_enroll_rflag=SOK
pa_enroll_rmsg=ics_pa_enroll service was successful
pa_enroll_specification_version=2.2.0
pa_enroll_ucaf_authentication_data=AJkBBkhgQQAAAE4gSEJydQAAAAA=
pa_enroll_ucaf_collection_indicator=4
pa_enroll_veres_enrolled=Y
receipt_number=004370
request_id=7455744328063896572043
request_token=Axj/7wSTlC083CXOBNCLAEQs3aNWrdo0ZsnDBszcOWzVuyYNGaiXWAnAvgJRLrATgX2kDpxBP7hk2xxRx8qNSFgWk5QtPNwlzgTQiwAAwCEb

Authentication Examples Using Digital Payment (Google Pay)

Digital payments are electronic payments that transfer funds from one payment account to another. These use cases demonstrate how the authentication service works using a digital payment method like Google Pay.

Setting Up Device Data Collection Using Digital Payment (Google Pay)

Running 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. This use case demonstrates how the service works using a digital payment method like Google Pay.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Device Data Collection

These fields are the minimum fields required when you request the Payer Authentication Setup service. Other fields that can be used to collect additional information during a transaction are listed in the optional fields section. Under certain circumstances, a field that is normally optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for the US and Canada.
This field is required when the card type is Cartes Bancaires,
JCB,
China UnionPay, or Meeza.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
payerAuthSetupService_run

Optional Fields for Device Data Collection

These fields are optional for setting up a Payer Authentication transaction. Under certain circumstances, a field might appear as both an optional field and a required field.

Simple Order Example: Setting Up Device Data Collection When Using Google Pay

This is an example of an Payer Authentication Setup request and response using Google Pay as the digital payment option. The data in this example is for illustrative purposes.
Request
merchantID=patest
merchantReferenceCode=0001
payerAuthSetupService_run=true
payment_solution=012
encryptedPayment_data=eyJzaWduYXR1cmUiOiJNRVlDSVFDMnNQcmduTmQ1cUY5N0hIMU1uWXRGV1Q
        xSFlWbnFrek93NU4ySXNldUZBZ0loQU90dWF1anc5L3lXWm5BYUlxUlVySktLWFF3M1I0Y3Mr
        aWFlWHBJYlNPT2wiLCJwcm90b2NvbFZlcnNpb24iOiJFQ3YxIiwic2lnbmVkTWVzc2FnZSI6I
        ntcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIld2blBMbXVnR3NNZ3N5TlBRU2toWjEwWkJKV09lV2
        Z1SncxZzR2ZVRjOENoTWpTaE1SWkdBemJ2TEhpM2RvTGtaYkNxcXJQeVIwVU1SNEFDQUFlSks
        rSWNvTzM4UlFDbE5XNTgyM1ZrNEFEMmlkSGxKQU90YjhjYXVrWlFOTkdQUmVJL3lwZ3c3Szhj
        M0lRRlBHQStMZ2ZaZ1dtWjNtWm4yMFFmYU9JRHZvcGt2V1hFTHNSVXdvaC9lNXFUeTlpb2RoO
        WlTQmUvN09HSlUvK2h6MTMrRnc2ZFk3d2F3Y3FVY0hXUkRSYkl3Tzk5dXU5L2NEbzQxZjZyT3
        JoaGNVTTBlY25Eak1lYzhMNy9RUWozMmZsMGNJMVQwdHg2UFpuMU1iby9iMG5VOTAwTzN1VXB
        nNWtheHBpRzg5a0NhemR0V2FlMC9MaitsWENMcm1UYjV5VGxmVXE3L25OTmwvTEwwT1BaUit3
        MENDdnBKZDB4b3QwRkd1OXRTdHYwOG9CTkJ2Y25kNDMzUmYraGlyaGVoOW1JNEJET01rODIxa
        nlxWUcxNWdGVGFlMFFYTDUzS2lFalpYZHV4VDdmc0F2YXc3OXkzemNhMEVnXFx1MDAzZFxcdT
        AwM2RcIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOlwiQkRkR0xtQVg2MUoxZnRNTStLSU95dkZ
        1a1BPZWovVURld0krK0lqd2hyVXZwdVFpbDBRY29tK0JCRkh3QnN4U2VhZDYrK0tYanBCWUQ4
        VUVkWDR6ZFJnXFx1MDAzZFwiLFwidGFnXCI6XCJVallCemN6dEl6Q3pkMTJMVHRmTGF2OWRtV
        jc4aHM2NlVIT3c5WFRoQ2hzXFx1MDAzZFwifSJ9
Response to Successful Request
payerAuthSetupReply_accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI2N
>payerAuthSetupReply_accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI2N

         jFlZjkwMS04MTFlLTQzZWQtkwMS04MTFlLTQzZWQtYWU0MS00MDM4ZGIyNDI5MjUiLCJpYXQi
         OjE2Nzk1ODIyNDAsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTY3O
         TU4NTg0MCwiT3JnVW5pdElkIjoiNTVlZjNmMDNmNzIzYWE0MzFjOTliMDA2IiwiUmVmZXJlbm
         NlSWQiOiJjMjUxYmE4OC1hMjY2LTQ1YmItODE3OC02MDc4NzFjMWFhNzQifQ.picPcWjbtOLG
         ZmNyLEhlM0NV3GYNVu7nRXIt7diaO1w
decision=ACCEPT
payerAuthSetupReply_deviceDataCollectionURL=https://centinelapistag.cardinal
         commerce.com/V1/Cruise/Collect
payerAuthSetupReply_referenceID=c251ba88-a266-45bb-8178-607871c1aa74
merchantReferenceCode=0001
reasonCode=100
requestID=6795822405176891104008
payerAuthSetupReply_reasonCode=100
requestToken=AxizbwSTcGb7N7K5VVsI/7gBURy2bEzgAMCoZNJMq6PSYifATAAAFwni

Checking Enrollment in Payer Authentication Using Digital Payment (Google Pay)

Running the Check Enrollment service collects data about the device that the customer is using to place the order and verifies that the customer is enrolled in a payer authentication program. This use case demonstrates how the service works with a digital payment method like Google Pay.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is required when the card type is Cartes Bancaires, JCB, China UnionPay, or Meeza.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (U.S.) when the product code is
AIR
 for an airline purchase.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
China
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Required Fields for Checking Enrollment in Payer Authentication

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentation program. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required for transactions in the US and Canada.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_workNumber
 is not used.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for SDK integration. When you use the SDK integration, this field is dynamically set to
SDK
. When you use the JavaScript code, this field is dynamically set to
Browser
. For merchant-initiated or 3RI transactions, you must set the field to
3RI
. When you use this field in addition to JavaScript code, you must set the field to
Browser
.
When the customer’s browser provides a value, include that value in your request.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required if
payerAuthEnrollService_workPhone
 or
billTo_phoneNumber
 is not used.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is required if
payerAuthEnrollService_mobilePhone
 or
billTo_phoneNumber
 is not used.
This field is optional when you use the
item_#_unitPrice
 field.

Optional Fields for Checking Enrollment in Payer Authentication

These fields are usually optional when you verify enrollment for a Payer Authentication transaction. In certain circumstances, the information provided by an optional field might be required before a transaction can proceed. Those optional fields that are sometimes required are also listed as required fields with the circumstance described.
This field is required for each leg.
The numbered element name should contain 0 instead of #. Payer Authentication services only use the first leg of the trip.
This field is required for each leg.
airlineData_numberOfPassengers
billTo_customerAccountChangeDate
billTo_customerAccountCreateDate
billTo_customerAccountPasswordChange Date
merchantDefinedData_mddField_1
 to
merchantDefinedData_mddField_5
These fields override the old merchant-defined data fields. For example, when you use the obsolete field
merchantDefinedData_field5
 and the new field
merchantDefinedData_mddField_5
 in the same request, the new field value overwrites the value specified in the obsolete field.
Merchant-defined data fields are not intended to and must not be used to capture personally identifying information. Accordingly, merchants are prohibited from capturing, obtaining, and/or transmitting any personally identifying information in or via the merchant defined data fields. Personally identifying information includes, but is not limited to, address, credit card number, Social Security number, driver's license number, state-issued identification number, passport number, and card verification numbers (CVV, CVC2, CVV2, CID, CVN). When a merchant is discovered capturing and/or transmitting personally identifying information via the merchant-defined data fields, whether intentionally or accidentally, the merchant's account is immediately suspended, resulting in a rejection of any and all transaction requests submitted by the merchant after the point of suspension.
pa_otpToken
This field is only used with mada cards.
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_addCardAttempts
This field is recommended for Discover ProtectBuy.
This field is required for Standard integration.
This field defaults to
01
 on your account but is overridden by the merchant when you include this field. EMV 3-D Secure version 2.1.0 supports values
01
-
04
. Version 2.2.0 supports values
01
-
09
.
Modifying this field could affect your liability shifts. Unless you are very familiar with the various types of authentication, do not change the default settings before consulting with customer support.
This field is required when tokenization is enabled in the merchant profile settings.
This field is recommended for Discover ProtectBuy.
This field is recommended for Discover ProtectBuy.
This field is required when the merchant and cardholder have agreed to installment payments.
This field is recommended for Discover ProtectBuy.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is the merchant bank identifier, such as Paymentech’s division, FDC’s Terminal ID, or Vital V number. Use this field for evaluation, testing, and production. This number is not your merchant ID.
This field is required for Visa Secure travel.
This field is required for transactions processed in France.
payerAuthEnrollService_ paymentAccountDate
This field is recommended for Discover ProtectBuy.
This field is required for American Express SafeKey (U.S.) when the product code is AIR (Airline purchase).
This field is required for recurring transactions.
This field is required for recurring transactions.
This field is required for recurring transactions.
This field is required for Hybrid or Cardinal Cruise Direct Connection API integration.
EMV 3-D Secure version 2.1.0 supports values
01
-
05
. Version 2.2.0 supports values
01
-
11
.
This field is required for 3-D Secure 2.x.
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_transactionCount Day
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_transactionCount Year
This field is recommended for Discover ProtectBuy.
payerAuthEnrollService_whiteListStatus
This field is required when any shipping address information is included. Required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required when the
bill_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
US
 or
CA
. Required for American Express SafeKey (U.S.).
This field is required only for American Express SafeKey (US).
This field is required when the
shipTo_country
 field value is
CA
,
US
, or
Mainland China
. Required for American Express SafeKey (U.S.).
This field is required when any shipping address information is included. Required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).

Simple Order Example: Checking Enrollment in Payer Authentication Using Google Pay

Request 
{
  "paymentInformation": {
"fluidData" : {
      "value" : "eyJzaWduYXR1cmUiOiJNRVFDSUVhVVBmc1RIMERyMnZmeG8wVkFlZ3N2bHlSRzdENEFsYm Rwa1pPdlNzZGtBaUFVODE2aHpmMG5BMzJzQmx6anlUSURyZXBHNUY1eEtlRmNnSE9aK3RML2ZRXHUwMDNkXHUw MDNkIiwiaW50ZXJtZWRpYXRlU2lnbmluZ0tleSI6eyJzaWduZWRLZXkiOiJ7XCJrZXlWYWx1ZVwiOlwiTUZrd0V 3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFOFdKSHVMOFVuWW9WWDNHV3dGVkJpcnh6L3lJdGl0aW9ne WhDeGpCRm5tS3pCcWs2K3lnVU5SUGF4THdaaWtILzBxV0s1QXhlc3BDNVhwN1NHNUN1T1FcXHUwMDNkXFx1MDAzZF wiLFwia2V5RXhwaXJhdGlvblwiOlwiMTYzMDUxNjYyODA0OVwifSIsInNpZ25hdHVyZXMiOlsiTUVVQ0lRRHlTQTV 1T2t5UXQ5cFoyQlEzaXBmcGNWT0F5ZmIzM2ozUEZPQUw3K1o5S3dJZ2FjWWp2YWJpTEUyWHFkNU1xNGphNSt EVldoREttVHpoMmk1RGlnbllFQndcdTAwM2QiXX0sInByb3RvY29sVmVyc2lvbiI6IkVDdjIiLCJzaWduZWR NZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwiWG5qOGxSSWhGMDVEWWdRK3hwNEE5YUhsVGE1U2l jdUJac2w1L2NNRkJlclBBY1RzaE4zRFlOb1MvdEVkRkRYRzZJRXBpVlcxVnV6OUprejNWWGdpMzJrT21EVk9aakJNW TFvVHdTQnA5WG53ejlLYUtOekYvRFBSTy9jbStobW9iZ2dSdmxGSStOekN5U1VNWW1hbTJjZFUyZGRZWmZHck9nZWN Sc3FrdW1tNmlMa0xGQTFJcDFrNWFRV21EUElEdTh1SnNmbWs4bzMyMlpteVdMMVVWenE0WHFkNTZScXZoL1VFeEp3R C9HZXU5SW00M0pmblZqckVkeDE0Ykx1OUpmMHJrcU5ONG5sM0NVZEFoMVNhZnBzdkduTVRML1Nmenk1ZGdDZlRD cHJDdW85UVZPaXVValBJNUdXRlBKSWVVVVU1cUZhcis3NXFBT2dvZ0tNRUZ3OFVxL1A0UjBDcXczcFllNnc2enlaV zdDV1YxRzRMc3BITTNRaE83bFZNNmRjSWZQWW00ZitubWI3UzgwY29KTXR1QjkxVEhjZzJmVXhwM2FrWEhSdzNyN 3BRZk9KWWFieUlURmtieDh0Yi9ieWl6VUZEVVU4S3EwTmVCVTVrQng2L21qUDg4bWxoWkE2ZERrNWJVc2o4SDBDSk 9nWUtCbVgyR09vamRtTDd5YlBnTU5vNnhsYjRtUzVkaTJjZUpFakFybEZFa3NWNTlsS2lodk5pckRZc1BTU2lTRF VZNjBMUXVuTEErYjFMSnpCMkpYelFcIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOlwiQk84bmtEbE0ycVlCQmpQ d00wbDdUTFY2UytUbzZDTFl0eXArWGM2cXpQYklLTEgxVytySGh3NUlwU2lqb1lTb3VaclNuWU9LV21yRVAyYmt LMk4rTWFZXFx1MDAzZFwiLFwidGFnXCI6XCJuVU5xUVlxcy9YRVlDMmg0WFlibnVpajFLb1NzUFpacEpqVGI4TVVZ cUZNXFx1MDAzZFwifSJ9"
    }
  },
  "processingInformation": {
    "paymentSolution": "012"
  }
}
Response 
{
  "consumerAuthenticationInformation": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI5MjlhZDAwYy0zZmEyLTQ5ODgtODRjNC1hYTcxMGFl Y2I1OGEiLCJpYXQiOjE2Mjk4MjY5NjAsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTYyOTgz MDU2MCwiT3JnVW5pdElkIjoiNWI5YzRiYjNmZjYyNmIxMzQ0ODEwYTAxIiwiUmVmZXJlbmNlSWQiOiI5NDkzZjJiZi0 4NmIwLTQ0ZmYtYmJjZS0wZjU1MjNlMWIzNGEifQ.FgVbwbW9_lwnlr4ovYR5VVPuVl6CklAVHHXS_5ODskA",
    "deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
    "referenceId": "9493f2bf-86b0-44ff-bbce-0f5523e1b34a",
    "token": "AxizbwSTVW4Mj1fvsU27ABEBURxPZebOAE1IZNJMvRiuZhTA9AAA+QBf"
  },
  "id": "6298269599786696003003",
  "status": "COMPLETED",
  "submitTimeUtc": "2021-08-24T17:42:40Z"
}

Validating a Challenge Using Digital Payment (Google Pay)

Running the Validation service compares the customer's response to the challenge from the issuing bank to validate the customer identity.

Card-Specific Requirements

Some payment cards require additional information to be collected during a transaction.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (US) when the product code is
AIR
 for an airline purchase).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US)

Country-Specific Requirements

These fields are required for transactions in specific countries.
TThis field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for transactions in the US and Canada.
This field is required for transactions processed in France.

Endpoint

Set the
payerAuthValidateService_run
 fields to
true
.
Send the request to:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Validating Payer Authentication

These fields are the minimum fields required when requesting the Payer Authentication Validation service. Other fields to collect additional information during a transaction are available in the list of optional fields. Under certain circumstances, some of the fields that are normally optional may be required. The circumstances that make an optional field, a required field, are noted.
card_accountNumber
card_cardType
card-expirationMonth
Required when
card_accountNumber
 is included.
card-expirationYear
Required when
card_accountNumber
 is included.
item_#_unitPrice
Required when the
purchaseTotals_grandTotalAmount
 field is not used.
merchantID
merchantReferenceCode
payerAuthValidateService_authentica tionTransactionID
payerAuthValidateService_run
purchaseTotals_currency
purchaseTotals_grandTotalAmount
Required when the
item_#_unitPrice
 field is not used.

Optional Fields for Validating a Challenge

These fields are optional when validating a Payer Authentication transaction. In certain circumstances, the information provided by an optional field might be required before a transaction can proceed. Those optional fields that are sometimes required are listed in the required fields with the circumstance described.

Simple Order Example: Validating a Challenge When Using Google Pay

Request 
billTo_city=Mountain View
billTo_country=US
billTo_email=null@email.com
billTo_firstName=John
billTo_lastName=Doe
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1295 Charleston Road
card_accountNumber=XXXXXXXXXXXXXXXX
card_cardType=001
card_cvNumber=111
card_expirationMonth=12
card_expirationYear=2030
ccAuthService_run=true
merchantID=patest
merchantReferenceCode=0001
payerAuthValidateService_authenticationTransactionID=TD5oS0o1FC65qav0xsx0
payerAuthValidateService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00

Authentication Examples Using TMS Tokens

These examples list the API fields that are required for the Setup, Check Enrollment, and Validate Authentication services when using TMS tokens. An example of a request payload and a successful response that occurs with each service is provided.

Setting Up Device Data Collection with a TMS Token

Running 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. In this scenario, a TMS token is used instead of the card.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza
.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Setting Up Data Collection When Using a TMS Token

These fields are the minimum fields required when you request the Payer Authentication Setup service. Other fields that can be used to collect additional information during a transaction are listed in the optional fields section. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

This field is required when the
billTo_country
 field value is the US or CA.
This field is required for the US and Canada.
This field is required when the card type is Cartes Bancaires, JCB, UPI, or Meeza.
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.
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.
payerAuthSetupService_run

Checking Enrollment When Using a TMS Token

Running the Check Enrollment service identifies the customer's bank and collects data about the device that the customer is using to place the order. This use case demostrates this process while using a TMS token.

Card-Specific Requirements

Some payment cards require additional information to be collected during a transaction.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (US) when the product code is
Airlinepurchase
 (AIR).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
 or
US
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Required Fields for Checking Enrollment in Payer Authentication While Using a TMS Token

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentication program. It doesn't matter if the enrollment check is frictionless or results in a challenge, the same fields are required in the request. The fields in the response will differ.

Required Fields

This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is optional when you use the
item_#_unitPrice
 field.

Validating a Challenge When Using a TMS Token

Running the Validation service compares the customer's response to the challenge from the issuing bank to validate the customer identity.

Card-Specific Requirements

Some payment cards require additional information to be collected during a transaction.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (US) when the product code is
AIR
 for an airline purchase).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US)

Country-Specific Requirements

These fields are required for transactions in specific countries.
TThis field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required for transactions in the US and Canada.
This field is required for transactions processed in France.

Endpoint

Set the
payerAuthValidateService_run
 fields to
true
.
Send the request to:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Validating a Challenge When Using a TMS Token

These fields are the minimum fields required when you request the Payer Authentication Validation service. Other fields that can be used to collect additional information during a transaction are listed in the optional fields section. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.

Required Fields

Authentication Examples Using Flex Microform Tokens

These examples list the API fields that are required for the Setup, Check Enrollment, and Validate Authentication services when using a Flex Microform token. An example of a request payload and a successful response that occurs with each service is provided.
A Flex Microform token is valid for 15 minutes. After 15 minutes, a new Flex Microform token is needed.

Setting Up Device Data Collection When Using a Flex Microform Token

Running 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. In this use case, a Flex Microform token is used instead of the payment card data. Flex Microform tokens are only valid for 15 minutes.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is
JCB,
Cartes Bancaires, China UnionPay, or Meeza
.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Setting Up Device Data Collection When Using a Flex Microform Token

This field is required to use a Flex Microform token when you request the payer authentication Setup service.

Required Fields

payerAuthSetupService_run
tokenInfo_transientToken

Checking Enrollment When Using a Flex Microform Token

Running the Check Enrollment service identifies the customer's bank and prepares for collecting data about the device that the customer is using to place the order. In this use case, a Flex Microform token is used instead of the payment card data. Flex Microform tokens are only valid for 15 minutes.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is
JCB
, Cartes Bancaires,China UnionPay, or Meeza
.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Checking Enrollment When Using a Flex Microform Token

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentication program while using a Flex Microform token. It doesn't matter if the enrollment check is frictionless or results in a challenge, the same fields are required in the request. The fields in the response will differ.

Required Fields

This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is optional when you use the
item_#_unitPrice
 field.

Validating a Challenge When Using a Flex Microform Token

Running the Validation service identifies the customer's bank and prepares for collecting data about the device that the customer is using to place the order. In this use case, a Flex Microform token is used instead of the payment card data.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is
JCB
, Cartes Bancaires, China UnionPay, or Meeza
.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Validating a Challenge When Using a Flex Microform Token

These are the minimum fields required to use a Flex Microform token when you validate a Payer Authentication challenge.

Authentication Examples Using Network Token/Tokenized Cards

These examples list the API fields that are required for the Setup, Check Enrollment, and Validate Authentication services when using network tokens or tokenized cards. An example of a request payload and a successful response that occurs with each service is provided.

Setting Up Device Data Collection with a Network Token/Tokenized Card

Running 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. In this instance, a tokenized card is used instead of the payment card data.

Card-Specific Requirements

Some payment cards require specific information to be collected during a transaction.
This field is required when the card type is
JCB
, Cartes Bancaires, China UnionPay, or Meeza
.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
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.
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

Required Fields for Setting Up Device Data Collection with a Network Token/Tokenized Card

These fields are the minimum fields required when you request the Payer Authentication Setup service while using a tokenized card. Other fields that are required during Setup service are listed in Required Fields for Collecting Device Data.

Checking Enrollment with a Network Token/Tokenized Card

Running the Check Enrollment service identifies the customer's bank and collects data about the device that the customer is using to place the order. This instance demonstrates this process with a network token/tokenized card.

Card-Specific Requirements

Some payment cards require additional information to be collected during a transaction.
This field is required when the card type is Cartes Bancaires,
JCB,
China UnionPay, or Meeza.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for Visa Secure travel.
This field is required for American Express SafeKey (US) when the product code is
Airlinepurchase
 (AIR).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during boarding.
For Meeza transactions, this value must be set to
EG
 when Egypt is not set as the country in the merchant configuration during merchant boarding.
This field is required for transactions in the US and Canada.
This field is required for transactions in the US and Canada.
This field is required when the
billTo_country
 field value is
US
 or
CA
.
This field is required when the
shipTo_country
 field value is
CA
 or
US
.
This field is required when the
shipTo_country
field value is
US
 or
CA
.

Processor-Specific Requirements

These fields are required by specific processors for transactions.
This field is required only for merchants in Saudi Arabia.

Endpoint

Set the
ccAuthService_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

Required Fields for Checking Enrollment When Using a Network Token/Tokenized Card

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentation program when using a tokenized card.

Required Fields

This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required for the US and Canada.
This field is required when
card_accountNumber
 is included.
This field is required when
card_accountNumber
 is included.
payerAuthEnrollService_run
This field is required (when available) unless market or regional mandate restricts sending this information.
This field is optional when you use the
item_#_unitPrice
 field.

Authentication Examples of Merchant-Initiated Transactions

A 3RI transaction is an EMV
3-D Secure
 transaction that is initiated by the merchant instead of the cardholder. The merchant keeps the payment data from the initial payment so that the cardholder does not have to be present for subsequent 3RI transactions. Having the payment details from a previous transaction enables the merchant to obtain a new Cardholder Authentication Verification Value (CAVV) to authenticate when authorizing future payments.
The authorization request contains the
payerAuthEnrollService_deviceChannel
 field. This process can be applied to these types of transactions:
  • Recurring payments: payments occur at regular intervals for an indefinite interval like subscription services.
  • Installment payments: payments occur at regular intervals for a fixed interval.
  • Refunded purchases: the cost of an item is refunded before the item is received. Any charges for damage or missing items can be charged back to the customer using a 3RI transaction.
  • Delayed shipments: an ordered item is out of stock delaying the shipment until the item is back in stock.
  • Split payments: an order is fulfilled in split shipments rather than in a single shipment because one of multiple items in the order is temporarily out of stock.
  • Multiple party commerce: a single entity or party makes multiple transactions with different merchants, for example, a travel agent booking flights, hotels, and tour excursions.
  • Unknown final transaction amount: extra charges are made to the customer for items such as hotel services, driving citations, or tips.

Challenge Reponses to 3RI Transactions

The directory server prohibits any challenge response from an issuer in 3RI transactions because the cardholder is not present for authentication. If an issuer does respond with a challenge, the directory server:
• Returns an ARes with a Transaction Status (transStatus) =
N
 and a Transaction Status Reason (transStatusReason) =
87
 (Transaction is excluded from Attempts Processing) to the
3-D Secure
 Server (merchant).
• Sends an error message (Erro) to the Access Control Server (ACS), with Error Code (errorCode) =
203
 (Format of one or more data elements is invalid according to the specification.)
When you receive this response, you should find an alternate way of processing the transaction. Examples include going directly to authorization, or when the cardholder is present, resending the transaction. When you receive this response, contact your acquirer to raise the issue with customer support.
For Merchant Initiated Transactions which are expected to be frictionless, device details are not required in the MIT authentication transaction

Network-Specific Values for Multi-Party Commerce/Online Travel Agency (OTA)

When the request body requires a previous authentication reference ID (
payerAuthEnrollService_priorAuthenticationReferenceID
), use the network-specific value found in one of these fields in the original response.
  • Visa:
    payerAuthValidateReply_acsTransactionID
  • Mastercard:
    payerAuthValidateReply_directoryServerTransactionID
When the request body requires a value from the
payerAuthEnrollService_requestorInitiatedAuthenticationIndicator
 field and the 3RI transaction type is multi-party commerce, use use one of these network-specific values.
  • Visa:
    11
     (Other payment)
  • Mastercard:
    85
     (Agent payment)
Note that Mastercard uses the Electronic Commerce Indicator (ECI) value of
07
 for 3RI transactions.
The network specific values for Multi Party Commerce / OTA are below.
The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with the card numbers, replace the Xs with a 0 (zero).

1a: Initial Recurring Transaction

In this instance, the merchant initiates a 3RI recurring transaction that is a fixed amount for a set of transactions with no established expiration, such as with a subscription purchase.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 28X5

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

1b: Recurring Payments - Subsequent Transaction (Mastercard)

In this instance, the merchant is running a subsequent 3RI recurring transaction that is a fixed amount for a set of payments with no established expiration such as a subscription purchase.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 2235

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

2a: Installment - Customer Initiated Transaction (Mastercard)

In this instance, the initial authentication is for the total amount for all of the future installments. Once the initial authentication is completed by the customer, the subsequent installments do not require authentication and go directly to authorization, which is Mastercard’s preferred process.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 28X5

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

Required Fields for 3RI 2a: Installment - Customer Initiated Transaction (Mastercard)

3a: Split/Partial Shipment (Mastercard)

In this instance, the purchase includes multiple items that do not become available to the customer at different times. For example, the customer order has backordered or preordered items. During the initial purchase, the authentication should be for the full amount total (including products to be shipped at a later time).
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 2235

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

Required Fields for 3RI 3a: Split/Partial Shipment (Mastercard)

3b: Split/Delayed Shipment (Mastercard)

In this instance, the purchase includes multiple items that do not become available to the customer at different times. For example, the customer order has backordered or preordered items. During the initial purchase, the authentication should be for the full amount total (including products to be shipped at a later time).
Card Type
Test Card Number
Visa
Card Type = 002
52XXXX XX XXXX 2235

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

4a: Multi-Party Commerce or OTA (Visa)

In this test case, a travel booking merchant creates a multi-party transaction for the cardholder. The merchants participating in the multi-party transaction are required to authorize on flights, hotels, and car rentals etc. This test case focuses on what the participating merchants are required to send for a successful transaction. Note that each participating merchant must send their own CAVV.
Refer to the network specific values section for this use case.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 27X1

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

4b: Multi-Party Commerce or OTA (MasterCard)

In this test case, a travel booking merchant creates a multi-party transaction for the cardholder. The merchants participating in the multi-party transaction are required to authorize on flights, hotels, and car rentals etc. This test case focuses on what the participating merchants are required to send for a successful transaction. Note that each participating merchant must send their own CAVV.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 28X5

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

4c: Multi-Party Commerce or OTA (MasterCard)

The merchant initiates a (3RI) recurring transaction of a fixed amount for a specified number of transactions or with no set number of transactions such as occurs with subscription purchases. For more information, see Requester Initiated Payments.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 2235

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

Testing Payer Authentication

After you complete the necessary changes to your web and API integration, verify that all components are working correctly by performing all the tests for the cards that you support. Each test contains the specific input data and the most important result fields that you receive in the API response.

Testing Process

Use the card number specified in the test with the card’s expiration date set to the month of December and the current year plus three. For example, for 2025, use 2028. The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with the card numbers, replace a X with a 0 (zero). You also need the minimum required fields for an order.

Enrollment Check Response Fields

This table lists the checking enrollment response fields used in the test cases.
Enrollment Check Response Fields
Name Used in Test Cases
API Field
ACS URL
payerAuthEnrollReply_acsURL
E-commerce indicator
payerAuthEnrollReply_commerceIndicator
ECI
payerAuthEnrollReply_eci
PAReq
payerAuthEnrollReply_paReq
proofXML
payerAuthEnrollReply_proofXML
Reason code
payerAuthEnrollReply_reasonCode
VERes enrolled
payerAuthEnrollReply_veresEnrolled
XID
payerAuthEnrollReply_xid

Authentication Validation Response Fields

This table lists only the response fields used in the test cases.
Response Fields Used in Authentication Validation Test Cases
Name Used in Test Cases
API Field
Authentication result
payerAuthValidateReply_authenticationR esult
E-commerce indicator
payerAuthValidateReply_commerceIndicator
AAV (Mastercard only)
payerAuthValidateReply_ucafAuthenticationData
CAVV (all card types except Mastercard)
payerAuthValidateReply_cavv
Collection indicator
payerAuthValidateReply_ucafCollectionIndi cator
ECI
payerAuthValidateReply_eci
PARes status
payerAuthValidateReply_authenticationSt atusMessage
Reason code
payerAuthValidateReply_reasonCode
XID
payerAuthValidateReply_xid

Test Cases for
3-D Secure
 2.x

Use the card number specified in the test with the card expiration date set to the month of January and the current year plus three. For example, for 2025, use 2028. You also need the minimum required fields for an order.
Be sure to remove spaces in card numbers when testing.
The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with the card numbers, replace the Xs with a 0 (zero).
While the usage of transaction ID (XID) values have declined in importance, they are still included in
3-D Secure
 2.x test cases. Only Mastercard transactions do not return XIDs.
While the
3-D Secure
 version and directory server transaction ID fields are returned for the Check Enrollment and Validate Authentication services, this data is not included in the
3-D Secure
 2.x test cases.
Mastercard requires that the
3-D Secure
 version and directory server transaction ID be included along with all pertinent data in your authorization request.

Card Specific Setup

The cards listed below require a specific merchant attribute or configuration during testing.
  • eftpos
    : The merchant should request that customer support enable the preferred secondary brand attribute to enable the prerferred routing for eftpos.
  • mada: The merchant descriptor country should be set as
    SA
     and the card type should be set as
    mada
    .
  • Meeza: The merchant descriptor country should be set as
    EG
     and the card type should be set as
    Meeza

2.1: Frictionless Authentication Is Successful

This test verifies that successful frictionless authentication of the cardholder by the card issuer works correctly.

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 27X8

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XX XXXX XXXX 3XX1
52XX XXXX XXXX 48X1

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXX XXXX XXXX 3XX6
4XXX XXXX XXXX 497X

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XX X1XX XX2X XXXX
81XXX1 XX XXXX X142
621XX3 82 3532 713X

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11 XXXX XXXX 2117

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11 XXXX XXXX 2117

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 517X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XXX1
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5126
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XXXX
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2XXX

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XXXX
557755 X1 22XX XXX9

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XXX5
4632X8 21 XXXX XXX4

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X296

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 8XXX
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 8X2X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXX 2235

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 27X1
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
Y
PARes status =
Y
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)
XID = <XID value>

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
05
aesk
Cartes Bancaires Mastercard
02
spa
Cartes Bancaires Visa
05
vbv
China UnionPay
05
up3ds
Diners Club
05
pb
Discover
05
dipb
eftpos
05
oci
Elo
05
cs
ITMX Mastercard
05
lss
ITMX Visa
05
lss
JCB J/Secure
05
js
mada Mastercard
02
mada or spa
mada Visa
05
mada or vbv
Mastercard
02
spa
Visa
05
vbv

Results for the Validation Authentication Service

Validation does not apply to this test because no validation is needed when no challenge is issued during the transaction.

Action

If you request Check Enrollment and Authorization services separately, add the required payer authentication values to your authorization request. If you request the Check Enrollment and authorization services together, the process described above occurs automatically.

2.2: Frictionless Authentication Is Unsuccessful

This test verifies that cardholder authentication without a challenge by the card issuer will fail.

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2X96

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X19
52XXXX XX XXXX 4538

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X14
4XXXXX XX XXXX 4574

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX1X XX1X
81XXX1 XX XXXX X647
621XX3 77 X3X8 1377

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2364

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2364

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 522X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX19
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X19
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX18
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2X18

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX1X
557755 X1 22XX XX17

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX13
4632X8 22 XXXX XX12

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X361

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 8X1X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 8X4X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2276

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2925
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
476
  • User failed authentication.
  • Payer cannot be authenticated.
VERes enrolled =
Y
PARes status =
N
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw value, and their respective string values. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure

Results for the Validation Authentication Service

No results are returned.

Action

Even though the merchant can still authorize a failed
3-D Secure
 transaction as a non-authenticated transaction, it is not recommended to submit this transaction for authorization. Instead, ask the customer for another form of payment.

2.3: Stand-In Frictionless Authentication is Attempted

This test verifies how your system reacts when the cardholder is enrolled in
3-D Secure
 but the card issuer does not support 3-D Secure, requiring a stand-in authentication experience.

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2872

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X27
52XXXX XX XXXX 4587

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X22
4XXXXX XX XXXX 4111

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XXXX XX2X
62XXX1 XX XXXX XX2X
621XX3 35 3371 144X

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2646

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2646

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 5360
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX27

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X27
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX26

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2026

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX75
557755 X2 21XX XX74

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX7X
4632X8 22 XXXX XX79

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X585

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
—

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
—

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2482

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2719
The Meeza card and can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
Y
PARes status =
A
CAVV =
<CAVV value>
AVV =
<AVV value>
 (Mastercard only)
XID =
<XID value>
 (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
06
aesk_attempted
Cartes Bancaires Mastercard
01
spa
Cartes Bancaires Visa
06
vbv_attempted
China UnionPay
06
up3ds_attempted
Diners Club
06
pb_attempted
Discover
06
dipb_attempted
eftpos
06
oci_attempted
Elo
06
cs_attempted
ITMX Mastercard
06
lss_attempted
ITMX Visa
06
lss_attempted
JCB J/Secure
06
js_attempted
Mastercard
01
spa
Visa
06
vbv_attempted

Results for the Validation Authentication Service

No results are returned.

Action

If you request Check Enrollment and Authorization services separately, add the required payer authentication values (CAVV and ECI) to your authorization request. If you request the Check Enrollment and Authorization services together, the process described above occurs automatically.

2.4: Frictionless Authentication Is Unavailable

This test verifies how your system behaves when authentication is unavailable at the time of the transaction.

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXXX XX XXXX 2922

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3035
52XXXX XX XXXX 4306

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X3X
4XXXXX XX XXXX 4160

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX40 XX3X
81XXX1 XX XXXX X894
621XX3 17 X75X 3X15

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2612

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2612

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 541X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX35
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X35
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X56 5X X1XX XXX34
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2X34

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX91
557755 X1 22XX XX9X

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX96
4632X8 22 XXXX XX79

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X221

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXX X XXXX 8X5X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXX XX XXXX 8XX
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2268

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2313
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
Y
PARes status =
U
AVV =
<No value provided>
CAAV =
<No value provided>
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure

Results for the Validation Authentication Service

No results are returned.

Action

Submit your authorization request. There is no liability shift.

2.5: Frictionless Authentication Is Rejected

This test verifies how your system reacts when authentication rejects the cardholder without a challenge by the issuer.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2X62

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X43
52XXXX XX XXXX 4405

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X48
4XXXXX XX XXXX 4517

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX3X XX4X
81XXX1 XX XXXX X415
621XX3 X8 5745 X241

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2711

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2711

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 555X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX43
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X35
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
470565 XX 1XXX XX42
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2X83

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21X X125
557755 X1 22XX X1X8

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX X12X
4632X8 22 XXXX X1X3

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
3337XX XX XXXX X321
3338XX XX XXXX X734

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 8X8X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 813X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2185

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXXXX XXXX 2537

Results for the Check Enrollment Service

Reason code
 =
476
  • User failed authentication.
  • Payer cannot be authenticated.
VERes enrolled =
Y
PARes status =
R
AVV = <No value provided>
CAAV = <No value provided>
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type value for Meeza is
067
.

Results for the Validation Authentication Service

No results are returned.

Action

You are not permitted to submit this transaction for authorization. Instead, ask the customer for another form of payment.

2.6: Authentication Is Not Available

This test verifies how your system reacts when a system error when checking enrollment prevents authentication.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2468

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X5X
52XXXXXX XXXX 4X9X

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X55
4XXXXX XX XXXX 4285

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX6X XX5X
81XXX1 XX XXXX X795
621XX3 1X 724X 3478

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XXXX XXXX 2836

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2836

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 556X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX5X
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X5X
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX59
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2X91

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX X141
557755 X1 22XX X124

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX138
4632X8 22 XXXX X145

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X94X

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 8X9X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 814X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 24X9

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 299X
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
U
In the response, this error code and error description is returned:
directoryServerErrorCode:
101
directoryServerErrorDescription:
Invalid Formatted Message

E-Commerce Indicator (ECI) Values

This table lists the ECI raw value that must be passed within the authorization and its respective string value. Note that there is no raw ECI returned for these scenarios. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
eftpos
07
oci_failure
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

No results are returned.

Action

Submit your authorization request. There is no liability shift.

2.7: Check Enrollment Error

This test verifies how your system reacts when an error occurs while verifying that the cardholder is part of an authentication program.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2732

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X68
52XXXX XX XXXX 4X58

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X63
4XXXXXXX XXXX 4194

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX5X XX6X
81XXX1 XX XXXX X662
621XX3 41 5762 1444

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2315

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2315

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 579X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX68
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X68
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX67
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 21X9

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX X174
557755 X1 22XX X132

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX153
4632X8 22 XXXX X152

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X65X

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 811X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 817X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2X37

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2446
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
U
In the response, this error code and error description is returned:
directoryServerErrorCode:
101
directoryServerErrorDescription:
Error Processing Message Request 1001

E-Commerce Indicator (ECI) Values

This table lists the raw ECI value that must be passed within the authorization and its respective string value. Note that no raw ECI is returned for these scenarios. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
eftpos
07
oci_failure
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

No results are returned.
While Mastercard would normally return the directory server transaction ID, in this test case, it is not returned.

Action

Proceed with the authorization request, and contact your support representative to resolve the issue. There is no liability shift. If you requested payer authentication and authorization together, the authorization is processed automatically.

2.8: Time Out

This test verifies how your system reacts when an error occurs while verifying that the cardholder is part of an authentication program.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2047

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X76
52XXXX XX XXXX 4694

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X71
4XXXXX XX XXXX 4277

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX9X X7X
81XXX1 XX XXXX X928
621XX3 X1 X451 71X7

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2869

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2869

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 584X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX76
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX76
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX75
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2125

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX X182
557755 X1 22XX X14X

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX187
4632X8 22 XXXX X178

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX 0577

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXXXX XXXX 813X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 82XX
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2326

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2354
This test verifies how your system reacts when it times out while checking enrollment, causing an error on the transaction.
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
U
In the response, this error code and error description is returned:
directoryServerErrorCode:
402
directoryServerErrorDescription:
Transaction Timed Out

E-Commerce Indicator (ECI) Values

This table lists the raw ECI value that would need to be passed within the authorization and its respective string value. Note that there is no raw ECI value returned for these scenarios. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
eftpos
07
oci_failure
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

No results are returned.

Action

After 10-12 seconds, proceed with the authorization request. There is no liability shift.

2.9: Step-Up Authentication Is Successful

This test verifies how your system reacts to a successful step-up (or challenge) authentication transaction.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2534

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X92
52XXXX XX XXXX 4X74

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3139
4XXXXX XX XXXX 4855

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 99 998X XX19
81XXX1 XX XXXX X688
621XX3 25 7857 4424

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2265

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2265

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 5311
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX84
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 529X
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX83
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 219X

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX26
557755 X1 22XX XX25

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX21
4632X8 22 XXXX XX2X

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X569

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 816X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 827X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2151

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 25X3
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
475
The cardholder is enrolled in payer authentication. Authenticate before proceeding with authorization.
VERes enrolled =
Y
PARes status =
C
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values from this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
mada Mastercard
00
spa or mada
mada Visa
07
vbv or mada

Results for the Validation Authentication Service

Reason code
 =
100
ics_pa_validate
 service was successful.
PARes status =
Y
XID = <XID value>
CAVV =
<CAVV value>

E-Commerce Indicator (ECI) Values

This table lists the expected raw ECI values and their respective string values from validating this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
05
aesk
Cartes Bancaires Mastercard
02
spa
Cartes Bancaires Visa
05
vbv
China UnionPay
05
up3ds
Diners Club
05
pb
Discover
05
dipb
eftpos
05
oci
Elo
05
cs
ITMX Mastercard
05
lss
ITMX Visa
05
lss
JCB J/Secure
05
js
mada Mastercard
02
spa or mada
mada Visa
05
vbv or mada
Mastercard
02
spa
Visa
05
vbv

Action

If you request Validate Authentication and authorization services separately, add the required payer authentication values to your authorization request. If you request the Validate Authentication and authorization services together, the process described above occurs automatically. The merchant should include the CAVV and ECI values in the authorization message.

2.10: Step-Up Authentication Is Unsuccessful

This test verifies that the step-up (challenge) authentication transaction fails whenever the cardholder challenge fails.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2237

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 31XX
52XXXX XX XXXX 4124

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X97
4XXXXX XX XXXX 4293

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 99 997X XX29
81XXX1 XX XXXX X8X3
621XX3 81 8186 8X38

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2695

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2695

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 5329
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX XX92
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5217
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX XX91
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 22X8

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX34
557755 X1 22XX XX33

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX39
4632X8 22 XXXX XX38

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X874

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 817X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 828X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 249X

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2370
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
475
The cardholder is enrolled in payer authentication. Please authenticate before proceeding with authorization.
VERes enrolled =
Y
PARes status =
C
PAReq = <PAReq value>
ACS URL = <URL value>
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected raw ECI values and their respective string values from this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

Reason code
 =
476
  • User failed authentication.
  • Payer cannot be authenticated.
PARes status =
N
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected raw ECI values and their respective string values from this transaction. These values indicate whether the payer was validated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure

Action

You are not permitted to submit this transaction for authorization. Instead, ask the customer for another form of payment.

2.11: Step-Up Authentication Is Unavailable

This test verifies that the correct response is returned when step-up authentication is unavailable.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2484

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3188
52XXXX XX XXXX 4124

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 31X5
4XXXXX XX XXXX 464X

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 99 997X XX39
81XXX1 XX XXXX X159

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 1129

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 1129

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 5337
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX X1XX
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5225
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX X1X9
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2257

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX42
557755 X1 22XX XX41

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX47
4632X8 22 XXXX XX46

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X981

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 819X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 831X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2664

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 242X
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
475
The cardholder is enrolled in payer authentication. Authenticate before proceeding with authorization.
VERes enrolled =
Y
PARes Status =
C
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values from this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

Reason code
 =
100
ics_pa_validate
 service was successful.
PARes status =
U
XID = <XID value> (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values from this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure

Action

The merchant can retry authentication or process without the liability shift.

2.12: Error During Authentication

This test checks how your system reacts when authentication request errors occurs during processing.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXXX XX XXXX 2351

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3126
52XXXX XX XXXX 4611

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3113
4XXXXX XX XXXX 4913

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 99 994X XX59
81XXX1 XX XXXX X159
621XX3 32 7122 3145

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 257X

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 257X

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 5352
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX X118
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5241
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX X117
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2265

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX XX67
557755 X1 22XX XX66

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX XX62
4632X8 22 XXXX XX61

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X676

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 82XX
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 834X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 2656

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 2644
The Meeza card can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
475
The cardholder is enrolled in payer authentication. Please authenticate before proceeding with authorization.
VERes enrolled =
Y
PARes status =
C
PAReq =
<PAReq value>

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values from this transaction. These values indicate whether the payer was authenticated by the card network. These values should be passed under this test condition when a transaction is submitted for cardholder authentication.
Network
ECI Raw Value
ECI String Value
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure

Results for the Validation Authentication Service

Reason code
 =
476
  • User failed authentication.
  • Payer cannot be authenticated.
PARes status =
U
XID =
<XID value>
 (American Express only)

E-Commerce Indicator (ECI) Values

This table lists the expected ECI raw values and their respective string values from this transaction. These values indicate whether the payer was validated by the card network. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet or vbv_failure
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
mada_failure or internet
mada Visa
07
mada_failure or vbv_failure
Mastercard
00
internet
Visa
07
internet or vbv_failure

Action

You can retain liability and submit this transaction for authorization as an unauthenticated transaction, or you can ask the customer for another form of payment.

2.13: Authentication Is Bypassed

This test verifies how your system reacts when the challenge requested by the issuer is bypassed for the transaction.

Card Numbers

American Express (Card Type = 003)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
34XXX XX XXXX 2948

Cartes Bancaires Mastercard (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 3X84
52XXXX XX XXXX 4991

Cartes Bancaires Visa (Card Type = 036)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 3X89
4XXXXX XX XXXX 44XX

China UnionPay (Card Type = 062)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
62XXX1 XX XX8X XX8X
81XXX1 XX XXXX X985
621XX3 26 X765 76X4

Diners Club (Card Type = 005)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2976

Discover (Card Type = 004)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
6X11XX XX XXXX 2976

eftpos Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
52XXXX XX XXXX 598X
—

eftpos Mastercard (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
516366 XX 1XXX X126
—

eftpos Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4XXXXX XX XXXX 5X84
—

eftpos Visa (Card Type = 070)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
47X565 XX 1XXX X125
—

Elo (Card Type = 054)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
65X529 XX XXXX 2166

ITMX Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
557755 X1 21XX X19X
557755 X1 22XX X157

ITMX Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
4632X8 21 XXXX X211
4632X8 22 XXXX X186

JCB J/Secure (Card Type = 007)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
3338XX XX XXXX X122

mada Mastercard (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 815X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

mada Visa (Card Type = 060)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 826X
The merchant's country must be set to
SA
 within the merchant profile, or the
CountryCodeOverride
 field must be set to
SA
 on the Lookup Request. The response will include the
3-D Secure
 operator ID, DS reference number, brand authentication, and the ACS reference number.

Mastercard (Card Type = 002)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
52XXXX XX XXXX 25X8

Visa (Card Type = 001)

3-D Secure
 2.1.0
 Test Card Number
3-D Secure
 2.2.0
 Test Card Number
—
4XXXXX XX XXXX 256X
The Meeza card is supported in payer authentication and can be tested in the same manner as Mastercard using the same test card numbers. The only difference is that the card type for Meeza is
067
.

Results for the Check Enrollment Service

Reason code
 =
100
ics_pa_enroll
 service was successful.
VERes enrolled =
B
XID = <XID value>

E-Commerce Indicator (ECI) Values

This table lists the ECI raw value that would need to be passed within the authorization and its respective string value. Note that there is no raw ECI returned for these scenarios. These values should be passed under this test condition when a transaction is submitted for payment authorization.
Network
ECI Raw Value
ECI String Value
American Express
07
internet
Cartes Bancaires Mastercard
00
internet
Cartes Bancaires Visa
07
internet
China UnionPay
07
up3ds_failure
Diners Club
07
internet
Discover
07
internet
eftpos
07
oci_failure
Elo
07
internet
ITMX Mastercard
07
lss_failure
ITMX Visa
07
lss_failure
JCB J/Secure
07
internet
mada Mastercard
00
internet or mada_failure
mada Visa
07
internet or mada_failure
Mastercard
00
internet
Visa
07
internet

Results for the Validation Authentication Service

No results are returned.

Action

Submit your authorization request. There is no liability shift.

2.14: Require Method URL

This test ensures that the merchant is allowing sufficient time (10 seconds) for the issuer to complete device data collection.

Card Numbers

The Method URL process runs before the authentication request to ensure device data is collected properly. The enrollment check of the card account should not start until after the device data collection (DDC) response is received. This test verifies that there is enough time to collect the BIN of the issuer and to transmit it. This test attempts to collect the nine-digit BIN of the card number and verifies that the delay between the DDC request and the response is at least 7 seconds long. The test fails when fewer than nine digits of the BIN are collected or when the delay between the DDC request and response is too short in duration.
Do not run this test when your system does not collect device data. When device data is not collected, an older version of the EMV
3-D Secure
 protocol is automatically used, and the transaction is automatically assessed as a higher risk.
Card Type
Test Card Number
Visa
Card Type = 001
4XXX1X XX XXXX XXXX

Results for the Check Enrollment Service

VERes enrolled =
Y
PARes status =
Y
CAVV = <CAVV value>
ECI value =
05

E-Commerce Indicator (ECI) Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network
ECI Raw Value
Visa
05

Action

If your device data collection method implements correctly and EMV
3-D Secure
 processing occurs, the test transaction produces a Frictionless Success result. A failure is indicated when PARes status =
C
. With the failure, a warning message opens to explain the cause of the test failure.

Additional Test Cases

These test cases cover payer authentication scenarios that can occur outside of typical testing. These special use cases might require including additional API fields to accommodate different data that is necessary for that test.
The test card numbers that are provided are formatted with Xs for zeroes in the card number. When testing with the card numbers, replace a X with a 0 (zero).

1a: First Recurring Transaction: Fixed Amount

The merchant initiates a 3RI recurring transaction of a fixed amount for a specified number of transactions or with no set number of transactions such as occurs with subscription purchases. For more information, see Requester Initiated Payments.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 28X5

Required Fields for Check Enrollment

Message category
 =
01
Device channel
 =
APP
 (01),
BROWSER
 (02)
Three RI Indicator
 =
01
Challenge code
 =
03
Authentication code
 =
02
Purchase date
 = <yyyyMMDDHHMMSS>
Recurring frequency
 = <1 to 31>
Recurring end
 = <yyyyMMDD>

Results for the Check Enrollment Service

Reason code
 =
475
VERes enrolled =
Y
PARes status =
C
CAVV = (No value provided)
ECI =
00

Results for the Validation Authentication Service

Reason code
 =
100
ics_pa_validate
 service was successful.
PARes status =
Y
CAVV = <CAVV>
ECI =
07

Card Network and Version Specifications

Visa Secure 2.1 does not support this type of transaction. Visa Secure 2.2 test cards are in development.
For Mastercard Identity Check 2.1, 3RI is not supported for Payer Authentication. Only the initial transaction is supported for recurring payments.
If you attempt to run a Device Channel of 3RI within Mastercard Identity Check 2.1, you receive a transStatusReason=21 (3RI Transaction not supported) reason and a transaction status of
U
 rather than
Y
.
In EMV
3-D Secure
 2.2, Mastercard allocated a new ECI value, ECI 07, for 3RI transactions. It is present on a Mastercard response message for this particular 3RI scenario. For EMV
3-D Secure
 2.1, Mastercard will continue to use ECI 02.

2a: Card Authentication Failed

This scenario tests how your system reacts to various Trans Status Reasons (failed, suspected fraud, and similar instances). When
PAResStatus
 = N, the
CardholderInfo
 field can be returned by the card issuer. When this cardholder information is returned, you must display this information within your checkout experience.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2X4X

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
N
CAVV = (No value provided)
Cardholder Info = <cardholder information>
ECI =
07
Reason code =
01

2b: Suspected Fraud

This test case scenario checks for suspected fraud.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2149

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
U
CAVV = (No value provided)
ECI =
07
Reason code =
11

2c: Cardholder Not Enrolled in Service

This test case scenario verifies whether the cardholder is enrolled in the service.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2164

Results for the Check Enrollment Service

Reason code
 =
476
VERes enrolled =
Y
PARes status =
R
CAVV = (No value provided)
ECI =
07
Reason code =
13

2d: Transaction Timed Out at the ACS

This test case scenario verifies whether a transaction will time out at the Access Control Server (ACS). This test case is valid for both payer authentication and non-payer authentication transactions.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2172

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
U
CAVV = (No value provided)
ECI =
07
Reason code =
14

2e: Non-Payment Transaction Not Supported

This test case scenario checks whether a non-payment transaction can occur. This test case is valid for both payer authentication and non-payer authentication transactions.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 223X

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
U
CAVV = (No value provided)
ECI =
07
Reason code =
20

2f: 3RI Transaction Not Supported

This test case scenario verifies whether the merchant can initiate a recurring 3RI transaction, such as with subscriptions.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2248

Required Fields for Check Enrollment

Message category
 =
02
Device channel
 =
3RI (03)
Three RI Indicator
 =
01

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
U
CAVV = (No value provided)
ECI =
07
Reason code =
21

3a: TRA Exemption—Low Value: Mastercard EMV
3-D Secure
 2.1 and 2.2

You have performed a proprietary risk assessment based on fraud thresholds established with the network. You are requesting an exemption from transaction risk analysis (TRA) because the Mastercard transaction is low risk or low value. Be sure to use the correct test card number for your version of EMV
3-D Secure
. The PARes Status will differ between the EMV
3-D Secure
versions.
Card Type
Test Card Number
Mastercard
Card Type = 002
(version 2.1.0) 52XX XXXX XXXX 1161
(version 2.2.0) 52XX XX XX XXXX 2X52

Required Fields for Check Enrollment

Challenge code
 =
05

Results for the Check Enrollment Service

Reason code
 =
100
Version 2.1.0
VERes enrolled =
Y
PARes status =
N
CAVV = <CAVV value>
ECI =
06
Reason code =
81
For Mastercard Identity Check, the Challenge Indicator should be passed as
05
.
Version 2.2.0
VERes enrolled =
Y
PARes status =
I
CAVV = <CAVV value>
ECI =
06

Action

Proceed to authorization.
You can also request the transaction risk analysis exemption directly during authorization if the region and your agreements with your acquirer and the networks support it.

3b: TRA—Low Value: Visa

The merchant has performed a proprietary risk assessment based on fraud thresholds established with the network. You are requesting an exemption for a low risk or low value Visa transaction.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2X24

Required Fields for Check Enrollment

Challenge code
 =
05
 (no challenge requested)

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
I
CAVV = <CAVV value>
ECI =
07

Action

Proceed to authorization.
You can also request the transaction risk analysis exemption directly during authorization if the region and your agreements with your acquirer and the networks support it.

3c: TRA—Low Value: Discover

The merchant has performed a proprietary risk assessment based on fraud thresholds established with the network. You are requesting an exemption for a low risk or low value Discover transaction.
Card Type
Test Card Number
Discover
Card Type = 004
6X11XX XX XXXX 1XX2

Required Fields for Check Enrollment

Challenge code
 =
04
 (challenge requested)

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
Y
CAVV = <CAVV value>
ECI =
05

Action

Proceed to authorization.
You can also request the transaction risk analysis exemption directly during authorization if the region and your agreements with your acquirer and the networks support it.

3d: Acquirer TRA: Cartes Bancaires

The merchant has performed a proprietary risk assessment based on fraud thresholds established with the network. You are requesting an exemption for a low risk or low value Cartes Bancaires transaction.
Card Type
Test Card Number
Cartes Bancaires Visa
Card Type = 036
4XXXXX XX XXXX 3XX6
Cartes Bancaires Mastercard
Card Type =036
52XXXX XX XXXX 3XX1

Required Fields for Check Enrollment

Challenge code
 =
05
 (no challenge requested)

Results for the Check Enrollment Service

Reason code
 =
100
VERes enrolled =
Y
PARes status =
Y
CAVV = <CAVV value> (The CAVV value is not returned during testing but can be returned in production based on issuer rules surrounding co-branding with Visa or Mastercard BINs.)
ECI = (no value provided)

Action

Proceed to authorization.
You can also request the transaction risk analysis exemption directly during authorization if the region and your agreements with your acquirer and the networks support it.

4a: Trusted Beneficiary Prompt for Trustlist

You have a successful traditional step-up (challenge) authentication transaction with a prompt for the Trustlist and an accepted exemption result.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2XX8
Mastercard
Card Type = 002
52XXXX XX XXXX 2XX3

Required Fields for Check Enrollment

Challenge code
 =
09
 (challenge requested)

Results for the Check Enrollment Service

With the Direct API, the response also includes a StepUpUrl.
VERes enrolled =
Y
PARes status =
C
CAVV = (No value provided)

Results for the Authenticate Response

PARes status =
Y
CAVV = <CAVV value>
ECI =
  • Visa =
    05
  • Mastercard =
    02
WhiteListStatus = <WhiteListStatus value>
WhiteListStatusSource = <WhiteListStatusSource value>

Action

You should append the CAVV and ECI values to the authorization message.

4b: Use Trusted Beneficiary Exemption

There is a successful frictionless authentication transaction with a pre-approved indication and an accepted exemption result.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2X16
Mastercard
Card Type = 002
52XXXX XX XXXX 2X11

Required Fields for Check Enrollment

Challenge code
 =
08
 (No challenge requested)

Results for the Check Enrollment Service

Reason code
 =
100
PARes status =
Y
CAVV = <CAVV value>
ECI =
  • Visa =
    05
  • Mastercard =
    02
WhiteListStatus = <WhiteListStatus value>
WhiteListStatusSource = <WhiteListStatusSource value>
ThreeDSVersion = <ThreeDSVersion value>

Action

Append the CAVV and ECI values to the authorization message.

5a: Visa Data Only

This request is for Visa Data Only authentication. This is a frictionless authentication because it is for informational purposes. Using Payer Authentication to share additional data with issuers prior to authorization,
3-D Secure
 Data Only provides a frictionless experience with EMV
3-D Secure
.
Card Type
Test Card Number
Visa
Card Type = 001
4XXXXX XX XXXX 2X24

Required Fields for Check Enrollment

ChallengeIndicator
 =
06

Results for the Check Enrollment Service

PAResStatus =
I
CAVV = <CAVV value>
ECI =
07
Reason code
 =
100

Action

Append the ECI and Directory Server transaction ID values to the authorization message.

5b: Identity Check Insights (ScoreRequest = Y)

This request is for Mastercard Data Only authentication.
Card Type
Test Card Number
Mastercard
Card Type = 002
52XXXX XX XXXX 1XX5

Required Fields for Check Enrollment

Message Category
 =
80
Optional Fields for Check Enrollment
Score Request =
Y
Merchant Reason Code =
A

Results for the Check Enrollment Service

Reason code
 =
100
PAResStatus =
U
CAVV = <CAVV value>
ECI =
04
StatusReason =
80
ThreeDSVersion = <ThreeDSVersion value>
Optional Results for the Check Enrollment Service (if ScoreRequest =
Y
)
IDCI_Score =
9
IDCI_Decisions =
not low risk
IDCI_ReasonCode1 =
A
IDCI_ReasonCode2 =
GG

Results for the Authentication Result

Reason code
 =
100

Action

Append the ECI and Directory Server transaction ID values to the authorization message.

Website Modification Reference

This section describes how to modify your website to integrate Payer Authentication services into your checkout process. It also provides links to payment card company websites where you can download the appropriate logos.

Website Modification Checklist

Modify web page buttons:
  • Order submission button: Disable the final “buy” button until the customer completes all payment and authentication requirements.
  • Browser back button: Plan for unexpected customer behavior. Check throughout the authentication process so you do not authenticate transactions twice. Avoid confusing messages, such as warnings about expired pages.
Add appropriate logos:
  • Download the appropriate logos of the cards that you support. Place these logos next to the card information entry fields on your checkout pages. For more information about obtaining logos and using them, see EMV 3-D Secure Service Logos.
Add informational message:
  • Add a message next to the final “buy” button and the card logo to inform your customers that they might be prompted to provide their authentication password. For examples of messages you can use, see Informational Message Examples.

EMV
3-D Secure
 Service Logos

This table contains links to payment card company websites from which you can download logos and information about how to incorporate them into your online checkout process.
3-D Secure
 Service Logos Download Location
EMV
3-D Secure
 Service
Download Location
Visa Secure
This website contains information about Visa Secure and links to logos for download. The page also contains links to a best practice guide for implementing Visa Secure and a link to a Merchant Toolkit.
Mastercard Identity Check and Maestro
This website contains information about Identity Check, links to logos for download, and information about integrating the Identity Check information into your website checkout page.
For information about Maestro logos, go to:
American Express SafeKey
This website contains information about SafeKey and links to logos for download.
JCB J/Secure
This website contains information about J/Secure and links to logos for download.
Diners Club ProtectBuy
Contact Diners Club customer service for assistance.
Discover ProtectBuy
This website contains information about Discover ProtectBuy and links to logos for download.
Elo Compra Segura
Contact Elo customer support to obtain logos.
China UnionPay
Contact China UnionPay customer support to obtain logos.

Informational Message Examples

Add a brief message next to the final buy button on your checkout page to inform customers that they might be prompted for their authentication password or to enroll in the authentication program for their card.
These examples might be used, but consult your specific card authentication program to make sure you conform to their messaging requirements.
Example
To help prevent unauthorized use of
<card_type>
 cards online,
<your_business_name>
 participates in
<card_authentication_program>
. When you submit your order, you might receive a
<card_authentication_program>
 message from your
<card_type>
 card issuer. If your card or issuer does not participate in the program, you are returned to our secure checkout to complete your order. Please wait while the transaction is processed. Do not click the
Back
 button or close the browser window.
Example
Your card might be eligible for Visa Secure, Mastercard,
Maestro,
 American Express SafeKey,
JCB J/Secure,
Diners Club ProtectBuy, or Discover ProtectBuy
 programs. After you submit your order, your card issuer might prompt you to authenticate yourself. This authentication can be done through a one-time pass code sent to your phone or email, by biometrics, or some other form of authentication.

Finding Payer Authentication Transaction Details in the
Business Center

This section describes how to find the details of Payer Authentication transactions in the
Business Center
. You need certain information about a transaction to respond to a chargeback. For details about past transactions, from the left navigation pane, go to
Transaction Management > Transactions
. This detailed data about a past transaction is stored for 12 months.

Storing Payer Authentication Data

Payment card companies permit only a certain number of days between the payer authentication and the authorization request. If you settle transactions that are older than the predetermined number of days, payment card companies might require that you send them the AAV, CAVV, or the XID when a chargeback occurs. The requirements depend on the card type and the region. For more information, refer to your agreement with your payment card company. You can get this type of information from the transaction details. The payer authentication transaction ID is listed in the transaction log. To access the transaction log, go to the Transaction Details page and in the Request Information section, click the
View
 button. After your transactions are settled, you can also use this data to update the statistics of your business.

Searching for Payer Authentication Details

Search the payer authentication data returned in API response fields with the Transaction Search feature in the
Business Center
.
Interpret the result of an enrollment check using this color coding.
  • If the application result appears in green, you do not need to authenticate the user. You can authorize the card immediately.
  • If the application result appears in red, the authentication failed.
  • If the application result appears in yellow, the transaction requires authentication.

Enrolling a Card

Enrolling a card consists of two steps:
  1. Checking for enrollment.
  2. Authenticating the customer.

Checking Enrollment

You can find payer authentication data on the Transaction Details page in these sections:
  • Request Information section: The enrollment check service is shown in red when the card is enrolled. You receive the corresponding response. If the card authorization service was requested at the same time, it did not run and appears in black.
  • Order Information section: When authentication is required, American Express SafeKey requires that you save the XID for later use. You do not receive an ECI, AAV, or CAVV because the authentication is not complete.
If the CAVV and ECI are not provided, and the enrollment transaction results in a challenge, authentication is required.

Authentication Validation

When an authentication is valid and the card authorization succeeds, payer authentication data appears in the Transaction Search Details window in these sections:
  • Request Information section: The validation service succeeded. A reason code 100 was returned with the corresponding response. The necessary payer authentication information was passed to the card authorization service, which processed successfully. Both services are shown in green.
  • Order Information section: You received a value for all three parameters because the validation was successful. You might not receive an ECI value when a system error prevents the card issuer from performing the validation or when the cardholder does not complete the process.

Card Not Enrolled

When a card is not enrolled, the result of the enrollment check service appears in green, and the card authorization request (if requested at the same time) proceeds normally.

Transaction Details

Enter the payer authentication transaction ID into the quick search feature to find all segments of a transaction. For a transaction in which the card is not enrolled, find payer authentication data in the Transaction Details window in these sections:
  • Request Information section: The service appears in green. You can obtain additional information about related orders by clicking the link on the right.
  • Order Information section:
    • For Mastercard, the ECI value is 00: authentication is not required because the customer’s Mastercard card is not enrolled. Other cards have an ECI value of 07.
    • The AAV/CAVV area is empty because you receive a value only when the customer is authenticated.
    • The XID area is empty because the card is not enrolled.
You might encounter these reason codes:
465: DAUTHENTICATE
Encountered a Payer Authentication problem. Payer could not be authenticated. Authenticate the cardholder before continuing with the transaction.
475: DAUTHENTICATE​
The cardholder is enrolled in Payer Authentication.​ Authenticate the cardholder before continuing with the transaction.​
476​: DAUTHENTICATIONFAILED​
Encountered a Payer Authentication problem. Payer could not be authenticated.​ Authenticate the cardholder before continuing with the transaction.​
261​: DINVALIDDATA​
The merchant account set up is either invalid or missing on the acquirer’s gateway. ​Check the currency, acquirer ID, merchant ID configuration. If these are configured as expected, contact the acquirer​.

Payer Authentication Reports

This section describes the Payer Authentication reports that you can download from the
Business Center
.
All reports on the production servers are retained for 16 months, but the transaction history is kept in the database for only 12 months. All reports on the test servers are deleted after 60 days. Only transactions that were processed are reported. Those transactions that resulted in a system error or a time-out are not reported.
To get access to the reports, you must file a support ticket in the Support Center.

Payer Authentication Summary Report

This daily, weekly, and monthly summary report indicates the performance of the enrollment and validation services as a number of transactions and a total amount for groups of transactions. The report provides this information for each currency and type of card that you support. You can use this information to estimate how payer authentication screens your transactions: successful, attempted, and incomplete authentication. The cards reported are Visa, Mastercard,
JCB,
Maestro,
China UnionPay, Elo,
Diners Club, Discover,
 and American Express. This daily report is generally available by 7:00 a.m. EST. Data in this report remains available for 6 months.

Download the Report

Follow these steps to view the Payer Authentication Summary report:
  1. In the left navigation panel, click the
    Reports
     icon.
  2. Under Transaction Reports, click
    Payer Auth Summary
    . The Payer Auth Summary Report page appears.
  3. In the search toolbar, select a date range to include in the report. Account-level users must select a merchant as well.
  4. Based on the date range you selected, choose the specific day, week, or month you want to review.

RESULT

Only months that have already occurred in the current year display in the Month list. To view all months of a previous year, select the year first, and then choose the month.
To view results from before the selected period, click
Previous
. Click
Next
 to see the next period.

Matching the Report to the Transaction Search Results

The image below shows the search results that contain the transactions that appear in the report. For more information on search results, see Searching for Payer Authentication Details.

Figure:

Payer Authentication Report Details

Interpreting the Report

The report is organized by card type. In each card type section, currencies are reported alphabetically. For each currency, a summary of your payer authentication validation results appear as a total amount and number of transactions.
Payer Authentication Report Interpretation
Card Type
Interpretation
Protected?
Commerce Indicator
ECI
Visa, American Express
, and JCB
No authentication
No
Internet
7
Recorded attempt to authenticate
Yes
VbV, Desk, or JS Attempted
6
Successful authentication
Yes
VbV, JS, or Aesk
5
Mastercard,
Meeza,
and Maestro
No authentication
No
Internet**
7*
Recorded attempt to authenticate
Yes
SPA
1
Successful authentication
Yes
SPA
2
Diners Club and Discover
No authentication
No
Internet
7
Recorded attempt to authenticate
Yes
PB or DIPB Attempted
6
Successful authentication
Yes
PB or DIPB
5
China UnionPay and Elo
No authentication
No
Internet
7
Recorded attempt to authenticate
Yes
CS or Up3ds Attempted
6
Successful authentication
Yes
CS or Up3ds
5
* Although the report heading is 7, you receive a collection indicator value of 1, or the response field is empty.
** Although the report heading is Internet, you receive
spa_failure
 in the commerce indicator response field.
Transactions are divided into two groups: those for which you are protected and those for which you are not protected:
  • For Visa,
    China UnionPay, Elo,
    JCB,
    Diners Club, Discover,
     and American Express: liability shift for VbV and VbV attempted.
  • For Mastercard and Maestro: liability shift only for SPA.
  • For all other results: no liability shift.

Comparing Payer Authentication and Payment Reports

The Payer Authentication report and the payment reports might differ when an authenticated transaction is not authorized.
The values (amounts and counts) in the Payer Authentication report might not match your other sources of reconciliation. This report shows the transactions validated by payer authentication. A different number of transactions might have been authorized.
The amounts and numbers can be higher in the Payer Authentication report than in the payment reports. This example shows the results of the first two numbers in the Payer Authentication report and the last number in the payment reports.
To reconcile your reports more easily when using payer authentication, we recommend that you attempt to authenticate the same amount that you want to authorize.
Payer Authentication Reports Compared to Payment Reports
For 10,000 orders, you might receive these results:
  • 9900 successful enrollment checks (Payer Authentication report)
  • 9800 successful authentication checks (Payer Authentication report)
  • 9500 successful authorization checks (Payment report)

Payer Authentication Detail Report

This section describes the elements of the Payer Authentication Detail report. Refer to the
Business Center
 Reporting User Guide
 for instructions for downloading the report and additional report information.

Report Element

The
Report
 element is the root element of the report.
<Report>
<PayerAuthDetails>
  (PayerAuthDetail+)
</PayerAuthDetails>
</Report>
Child Elements of Report
Element Name
Description
PayerAuthDetails
Contains the transaction in the report. For a list of child elements, see
PayerAuthDetail
.
PayerAuthDetails Element
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Report SYSTEM "
https://api.cybersource.com
/reporting/v3/dtds/padr">
<PayerAuthDetails>
  <PayerAuthDetail>
    ...
  </PayerAuthDetail>
</PayerAuthDetails>

PayerAuthDetail Element

The
PayerAuthDetail
 element contains information about a single transaction.
<PayerAuthDetail>
  (RequestID)
  (MerchantID)
  (RequestDate)
  (TransactionType)
  (PAReq)?
  (PARes)?
  (AuthInfo)?
</PayerAuthDetail>
Child Elements of PayerAuthDetail
Element Name
Description
Type & Length
RequestID
Unique identifier generated for the transaction. This field corresponds to the
requestID
 API field.
Numeric (26)
MerchantID
Merchant ID used for the transaction.
String (30)
RequestDate
Date on which the transaction was processed.
DateTime (25)
PAReq
The Payer Authentication Request message sent to the ACS through the payment card company. Corresponds to the
payerAuthEnrollReply_paReq
 API field.
For a list of child elements, see PAReq.
PARes
The Payer Authentication Response message sent by the ACS. For a list of child elements, see PARes.
AuthInfo
Address and card verification data. For a list of child elements, see AuthInfo Element.
PayerAuthDetail Element
<PayerAuthDetail>
  <RequestID>0004223530000167905139</RequestID>
  <MerchantID>example_merchant</MerchantID>
  <RequestDate>2020-02-09T08:00:09-08:00</RequestDate>
  <TransactionType>ics_pa_enroll</TransactionType>
  <PAReq>
    ...
  </PAReq>
  <PARes>
    ...
  </PARes>
</PayerAuthDetail>

PAReq Element

The
PAReq
 element contains the payer authentication request message. This element corresponds to the
payerAuthEnrollReply_paReq
 API field.
<PAReq>
  (AcqBIN)
  (MerID)
  (Name)
  (Country)
  (URL)
  (XID)
  (Date)
  (PurchaseAmount)
  (AcctID)
  (Expiry)
</PAReq>
Child Elements of PAReq
Element Name
Description
Type & Length
AcqBIN
First six digits of the acquiring bank’s identification number.
Numeric (6)
MerID
Identifier provided by your acquirer to the merchant to log in to the ACS URL.
String (24)
Name
Merchant’s company name.
String (25)
Country
Two-character code for the merchant’s country of operation.
String (2)
URL
Merchant’s business website.
String
XID
Unique transaction identifier generated for each Payment Authentication Request (PAReq) message. The PARes sent back by the issuing bank contains the XID of the PAReq. To ensure that both XIDs are the same, compare it to the XID in the response. To find all requests related to a transaction, you can also search transactions for a specific XID.
String (28)
Date
Date and time of request.
Differing time zones and the lack of synchronization between servers might prevent the date and time from appearing sequentially during all stages of processing.
DateTime (25)
Purchase Amount
Authorization amount and currency for the transaction. This element corresponds to the totals of the offer lines or from:
ccAuthReply_amount
 or
purchaseTotals_grandTotalAmount
 from external data
Amount (15)
AcctID
Masked string used by the ACS.
String (28)
Expiry
Expiration month and year of the customer’s card.
Number (4)
PAReq Element
<PAReq>
  <AcqBIN>123456</AcqBIN>
  <MerID>444444</MerID>
  <Name>example</Name>
  <Country>US</Country>
  <URL>http://www.example.com</URL>
  <XID>fr2VCDrbEdyC37MOPfIzMwAHBwE=</XID>
  <Date>2020-02-09T08:00:34-08:00</Date>
  <PurchaseAmount>1.00 USD</PurchaseAmount>
  <AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
  <Expiry>2309</Expiry>
</PAReq>

PARes Element

The
PARes
 element contains the payer authentication response.
<PARes>
  (AcqBIN)
  (MerID)
  (XID)
  (Date)
  (PurchaseAmount)
  (PAN)
  (AuthDate)
  (Status)
  (CAVV)
  (ECI)
</PARes>
Child Elements of PARes
Element Name
Description
Type & Length
AcqBIN
First six digits of the acquiring bank’s identification number.
Numeric (6)
MerID
Identifier provided by your acquirer; used to log in to the ACS URL.
String (24)
XID
XID value returned in the customer authentication response. This element corresponds to the
consumerAuthenticationInformation.xid
payerAuthEnrollReply_xid
 and
payerAuthValidateReply_xid
 API fields.
String (28)
Date
Date and time of request.
Differing time zones and the lack of synchronization between servers might prevent the date and time from appearing sequentially during all stages of processing.
DateTime (25)
PurchaseAmount
Authorization amount and currency for the transaction. This element corresponds to the totals of the offer lines or from the
ccAuthReply_amount
 or
purchaseTotals_grandTotalAmount
 field.
Amount (15)
PAN
Customer’s masked account number. This element corresponds to the
payerAuthEnrollReply_proxyPAN
 API field.
String (19)
AuthDate
Date and time of request.
(Although the date and time should appear sequentially during all stages of the processing of an order, they may not because of differing time zones and synchronization between servers.)
DateTime (25)
Status
Result of the authentication check. This field contains one of these values:
  • Y
    : Customer was successfully authenticated.
  • N
    : Customer failed or cancelled authentication. Transaction denied.
  • U
    : Authenticate not completed regardless of the reason.
  • A
    : Proof of authentication attempt was generated.
String (1)
CAVV
CAVV (Visa, American Express,
JCB, China UnionPay, Elo,
Diners Club, and Discover cards
) element corresponds to the
payerAuthValidateReply_cavv
 field returned in the customer authentication response. The AAV (Mastercard
, and Maestro
 cards) element corresponds to the
payerAuthValidateReply_ucafAuthenticationData
 API field returned in the customer authentication response.
String (50)
ECI
Electronic Commerce Indicator returned in the customer authentication response. This element corresponds to the
payerAuthValidateReply_eci
 and
payerAuthValidateReply_ucafCollectionIndicator
API fields.
Numeric (1)
PARes Element
<PARes>
  <AcqBIN>123456</AcqBIN>
  <MerID>4444444</MerID>
  <XID>Xe5DcjrqEdyC37MOPfIzMwAHBwE=</XID>
  <Date>2020-02-09T07:59:46-08:00</Date>
  <PurchaseAmount>1002.00 USD</PurchaseAmount>
  <PAN>0000000000000771</PAN>
  <AuthDate>2020-02-09T07:59:46-08:00</AuthDate>
  <Status>Y</Status>
  <CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
  <ECI>5</ECI>
</PARes>

AuthInfo Element

The
AuthInfo
 element contains address and card verification information.
<AuthInfo>
  (AVSResult)
  (CVVResult)
</AuthInfo>
Child Elements of AuthInfo
Element Name
Description
Type & Length
AVSResult
Results of the address verification test.
String (1)
CVVResult
Results of the card verification number test.
String (1)
AuthInfo Element
<AuthInfo>
  <AVSResult>Y</AVSResult>
  <CVVResult/>git 
</AuthInfo>

Report Examples

These examples show a complete transaction: the failed enrollment check (enrolled card) and the subsequent successful authentication.
For transactions in India, use transactionProcessor.
Failed Enrollment Check
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Result SYSTEM "
https://api.cybersource.com
/reporting/v3/dtd/padr">
<Report>
Name="Payer Authentication Detail" 
Version="1.0”
xmlns="
https://api.cybersource.com
/reporting/v3/dtds/padr" 
MerchantID="sample_merchant_id" 
ReportStartDate="2022-02-09T08:00:00-08:00" 
ReportEndDate="2022-02-10T08:00:00-08:00"
<PayerAuthDetails>
   <PayerAuthDetail>
      RequestID=”1895549430000167904548”
      TransactionType=”ics_pa_enroll
      RequestDate=”2022-02-09T08:00:02-08:00”
      <ProofXML>
         <Date>20220209 08:00:34</Date>
         <DSURL>https:123.456.789.01:234/DSMsgServlet</DSURL>
         <PAN>XXXXXXXXXXXX0771</PAN>
         <AcqBIN>123456</AcqBIN>
         <MerID>4444444</MerID>
         <Password />
         <Enrolled>Y</Enrolled>
      </ProofXML>
      <VEReq>
         <PAN>XXXXXXXXXXXX0771</PAN>
         <AcqBIN>123456</AcqBIN>
         <MerID>example</MerID>
      </VEReq>
      <VERes>
         <Enrolled>Y</Enrolled>
         <AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
         <URL>https://www.sample_url.com</URL>
      </VERes>
      <PAReq>
         <AcqBIN>123456</AcqBIN>
         <MerID>example</MerID>
         <Name>Merchant Name</Name>
         <Country>US</Country>
         <URL>http://www.merchant_url.com</URL>
         <XID>2YNaNGDBEdydJ6WI6aFJWAAHBwE=</XID>
         <Date>2022-02-09T08:00:34-08:00</Date>
         <PurchaseAmount>1.00 USD</PurchaseAmount>
         <AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
         <Expiry>2309</Expiry>
      </PAReq>
   </PayerAuthDetail>
</PayerAuthDetails>
</Report>
Successful Authentication
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Result SYSTEM "
https://api.cybersource.com
/reporting/v3/dtd/padr">
<Report>
<PayerAuthDetails>
   <PayerAuthDetail>
      RequestID=”1895549900000167904548”
      TransactionType=”ics_pa_validate”
      XID=”2YNaNGDBEdydJ6WI6aFJWAAHBwE=”
      RequestDate=”2022-02-09T08:00:02-08:00”
      <PARes>
         <AcqBIN>469216</AcqBIN>
         <MerID>6678516</MerID>
         <XID>2YNaNGDBEdydJ6WI6aFJWAAHBwE=</XID>
         <Date>2020-02-09T07:59:46-08:00</Date>
         <PurchaseAmount>1.00 USD</PurchaseAmount>
         <PAN>0000000000000771</PAN>
         <AuthDate>2022-02-09T07:59:46-08:00</AuthDate>
         <Status>Y</Status>
         <CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
         <ECI>5</ECI>
      </PARes>
   </PayerAuthDetail>
</PayerAuthDetails>
</Report>

HTTP Status Codes

These HTTP status codes can appear during payer authentication.
201: AUTHENTICATION_FAILED
Encountered a payer authentication problem. Payer could not be authenticated.
201: CONSUMER_AUTHENTICATIION_REQUIRED
Encountered a payer authentication problem. Payer could not be authenticated.
400: CONSUMER_AUTHENTICATIION_FAILED
Encountered a payer authentication problem. Payer could not be authenticated.
400: INVALID_DATA
Declined: One or more fields in the request contain invalid data.
400: INVALID_MERCHANT_CONFIGURATION
Declined: There is a problem with your merchant configuration.
400: MISSING_FIELD
Declined: The request is missing one or more fields.
502: SYSTEM_ERROR
Error: General system failure. A system error occurred.
502: SYSTEM_TIMEOUT
Error: The request was received but a server timeout occurred. This error does not include timeouts between the client and the server.
502: SYSTEM_TIMEOUT
Error: The request was received, but a service did not finish running in time.

Reason Codes

These reason codes can appear during payer authentication transactions. For a complete list of reason codes, go to Reason Codes for the Simple Order API.
100
Transaction was successful.
101
The request is missing one or more required fields. Possible action: See the response fields
missingField_0
 through
missingField_N
 for the missing fields. Possible action: Resend the request with the complete information.
102
One or more fields in the request contains invalid data. Possible action: See the response fields
invalidField_0
 through
invalidField_N
 for the invalid fields. Possible action: Resend the request with the correct information.
150
Error: General system failure. Possible action: Wait a few minutes and resend the request.
151
Error: The request was received, but a server time-out occurred. This error does not include time-outs between the client and the server. Possible action: Wait a few minutes and resend the request.
152
Error: The request was received, but a service time-out occurred. Possible action: Wait a few minutes and resend the request.
234
A problem exists with your
Cybersource
 merchant configuration. Possible action: Do not resend the request. Contact customer support to correct the configuration problem.
261
The merchant account set up is either invalid or missing on the acquirer’s gateway. Possible action: Check the merchant account configuration.
465
Encountered a Payer Authentication problem. Payer could not be authenticated. Possible action: Authenticate the cardholder before continuing with the transaction.
475
The cardholder is enrolled in Payer Authentication. Possible action: Authenticate the cardholder before continuing with the transaction.
476
Payer could not be authenticated. Possible action: Authenticate the cardholder before continuing with the transaction.
478
Strong customer authentication (SCA) is required for this transaction.

Glossary

3RI Payment

The EMV
3-D Secure
 request for information. It is an EMVCo term for the EMV 3-D Secure service that can check a BIN without performing a complete authentication.

3-D Secure

Security protocol for online credit card and debit card transactions used by Visa Secure, Mastercard Identity Check, American Express SafeKey,
China UnionPay, Elo, JCB J⁄Secure,
 Diners Club ProtectBuy, and Discover ProtectBuy.

AAV

Account Authentication Value. A unique 32-character transaction token for a
3-D Secure
 transaction. For Mastercard Identity Check, the AAV is named the UCAF. For Visa Secure, the AAV is named the CAVV.

acquirer

The financial institution that accepts payments for products or services on behalf of a merchant. Also referred to as the acquiring bank. This bank accepts or acquires transactions that involve a credit card issued by a bank other than itself.

acquirer BIN

An eight-digit number that uniquely identifies the acquiring bank. Every participating acquirer has a different acquirer BIN. The Mastercard BIN starts with 5 and the Visa BIN starts with 4.

acquirer processor

Processor that provides credit card processing, settlement, and services to merchant banks.

ACS

Access Control Server. The card-issuing bank’s host for the payer authentication data.

ACS URL

The URL of the Access Control Server of the card-issuing bank that is returned in the response to the request to check enrollment. You send the PAReq to this URL so that the customer can be authenticated.

American Express

A globally issued card type that starts with 3 and which is identified as card type 003. These cards participate in a card authentication service (SafeKey) provided by EMV
3-D Secure
.

authentication result

Raw data sent by the card issuer that indicates the status of authentication. You do not need to pass this raw data into the authorization.

authorization

A request sent to the card issuing bank that ensures a cardholder has the funds available on their credit card for a specific purchase. A positive authorization generates an authorization code and puts a hold on the funds.

Base64

Standard encoding method for data transfer over the internet.

BIN

Bank Identification Number. The eight-digit number that identifies the card issuer.

CAVV

Cardholder Authentication Verification Value. A Base64-encoded string sent back with Visa Secure-enrolled cards that specifically identifies the transaction with the issuing bank and Visa. Standard for collecting and sending AAV data for Visa Secure transactions. See AAV.

CAVV algorithm

The method used to generate the CAAV value.

Compra Segura

Trademarked name for the Elo card authentication service.

CVV

Card Verification Value. Security feature for credit cards and debit cards. This feature consists of two values or codes: one that is encoded in the magnetic strip and one that is printed on the card. Usually, the CVV is a three-digit number on the back of the card. The CVV for American Express cards is a 4-digit number on the front of the card. CVVs are used as an extra level of validation by issuing banks.

Diners Club

A globally issued card type whose numbers start with a 3 or a 5. Diners Club cards are identified as card type 005. These cards participate in a card authentication service (ProtectBuy) provided by
3-D Secure
.

Directory Servers

The Visa and Mastercard servers that are used to verify enrollment in a card authentication service.

Discover

Primarily, a U.S. card type starting with a 6. Discover cards are identified as card type 004. These cards participate in a card authentication service (ProtectBuy) provided by
3-D Secure
.

ECI (ECI Raw)

The numeric commerce indicator that indicates to the bank the degree of liability shift achieved during payer authentication processing.

E-Commerce Indicator

Alpha character value that indicates the transaction type, such as MOTO or INTERNET.

Elo

A globally issued card type starting with a 5. Elo cards are identified as card type of 054. These cards participate in a card authentication service (Compra Segura) provided by
3-D Secure
.

Enroll

A type of transaction used for verifying whether a card is enrolled in the Mastercard Identity Check or Visa Secure service.

HTTP

The Hypertext Transfer Protocol is an application protocol used for data transfer on the internet.

HTTP POST request

POST is one of the request methods supported by the HTTP protocol. The POST request method is used when the client sends data to the server as part of the request, such as when uploading a file or submitting a completed form.

HTTPS

Hypertext Transfer Protocol combines with SSL/TLS (Secure Sockets Layer/Transport Layer Security) to provide secure encryption of data transferred over the Internet.

issuer

The bank that issues the credit card.

J/Secure

The EMV
3-D Secure
 program of JCB.

JCB

Japan Credit Bureau. A globally issued card type starting with a 3. JCB cards are identified as a card type of 007. These cards participate in a card authentication service (J/Secure) provided by EMV
3-D Secure
.

Maestro

A card brand owned by Mastercard that includes several debit card BINs within the U.K. and in Europe. Merchants who accept Maestro cards online are required to use Mastercard Identity Check, Mastercard’s card authentication service. Maestro cards are identified as 024 and 042 card types. Note that many international Maestro cards are not set up for online acceptance and cannot be used even if they participate in a Mastercard Identity Check authentication program.

Mastercard

A globally issued card that includes credit and debit cards. These cards start with a 5. These cards are identified as card type 002 for both credit and debit cards. These cards participate in a card authentication service (Mastercard Identity Check) provided by
3-D Secure
.

Mastercard Identity Check

Trademarked name for Mastercard’s payer authentication service.

MD

Merchant-defined Data that is posted as a hidden field to the ACS URL. You can use this data to identify the transaction on its return. This data is used to match the response from the card-issuing bank to a customer’s specific order. Although payment card companies recommend that you use the XID, you can also use data such as an order number. This field is required, but including a value is optional. The value has no meaning for the bank and is returned to the merchant as is.

Merchant ID

Data that must be uploaded for the Mastercard and Visa card authentication process for each participating merchant. The Merchant ID is usually the bank account number or it contains the bank account number. The data is stored on the Directory Servers to identify the merchant during the enrollment check.

MPI

Merchant Plug-In. The software used to connect to Directory Servers and to decrypt the PARes.

PAN

Primary Account Number. Another term for the credit card number.

PAReq

Payer Authentication Request. Digitally signed Base64-encoded payer authentication request message, containing a unique transaction ID that a merchant sends to the card-issuing bank. Send this data without alteration or decoding. Note that the field name has a lowercase “a” (PaReq), but the message name has an uppercase “A” (PAReq).

PARes

Payer Authentication Response. A compressed, Base64-encoded response from the card-issuing bank. This data is passed for validation.

PARes status

Payer Authentication Response status. One-character length status passed back by Visa and Mastercard that is required data for Asia, Middle East, and Africa Gateway authorizations.

processor

Financial entity that processes payments. Also see
acquiring processor
.

ProofXML

This field contains the VEReq and VERes messages for merchant storage. Merchants can use this data for potential chargeback repudiation.

ProtectBuy

Trademarked name for the Diners Club and Discover card authentication services.

request ID

A 22- or 23-digit number that uniquely identifies each transaction. Merchants should store this number for future reference.

risk-based authentication

Risk-based authentication is provided by the card-issuing bank. The card-issuing bank gathers a cardholder’s transaction data or leverages whatever data they have to silently authenticate the cardholder based on the perceived degree of risk. They base their risk assessment on factors such as cardholder spending habits, order or product velocity, the device IP address, order amount, and so on.

SafeKey

Trademarked name for the American Express card authentication service.

SCMP API

A legacy name-value pair API that was superseded by the Simple Order API.

Simple Order API

An API, that provides three ways to access services: name-value pair (NVP), XML, and SOAP.

TermURL

Termination URL on a merchant’s website where the card-issuing bank posts the payer authentication response (PARes) message.

UCAF

Universal Cardholder Authentication Field. A Base64-encoded string sent back with Mastercard Identity Check enrolled cards specifically identifying the transaction with the issuing bank and Mastercard. Standard for collecting and sending AAV data for Mastercard Identity Check transactions. See also
AAV
.

UCAF collection indicator

Value of
1
 or
2
 that indicates whether a Mastercard cardholder has authenticated themselves.

validate

A service that decodes and decrypts the PARes message to determine success. The validate service returns the needed values for authorization.

VEReq

Verify Enrollment Request. Request sent to the Directory Servers to verify that a card is enrolled in a card authentication service.

VERes

Verify Enrollment Response. Response from the Directory Servers to the VEReq.

VERes enrolled

Verify Enrollment Response enrolled. One-character length status passed back by Visa and Mastercard that is required data for Asia, Middle East, and Africa Gateway authorizations.

Visa

A globally issued card that includes credit and debit cards. These card numbers start with a 4. These cards are identified as card type 001 for both credit and debit cards. These cards participate in a card authentication service (Visa Secure) provided by EMV
3-D Secure
.

Visa Secure

Trademarked name for Visa’s card authentication service.

XID

String used by both Visa and Mastercard, that identifies a specific transaction on the Directory Servers. This string value should remain consistent throughout a transaction’s history.