Cybersource Payer Authentication
Uploaded by
hoalong.rbvnCybersource Payer Authentication
Uploaded by
hoalong.rbvnPayer
Authentication
REST API
Developer Guide
Cybersource Contact Information
For general information about our company, products, and services, go to https://www.cybersource.com.
For sales questions about any Cybersource service, email [email protected] or call 650-432-7350 or 888-330-2300 (toll free in
the United States).
For support information about any Cybersource service, visit the Support Center: https://www.cybersource.com/support
Copyright
© 2020. Cybersource Corporation. All rights reserved. Cybersource Corporation (“Cybersource”) furnishes this document and the
software described in this document under the applicable agreement between the reader of this document (“You”) and Cybersource
(“Agreement”). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly
set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not
be interpreted in any way as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability for any errors
that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict
accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the
Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in
any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of Cybersource.
Restricted Rights Legends
For Government or defense agencies:Use,duplication, or disclosure by the Government or defense agencies is subject to restrictions
as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and
NASA FAR Supplement.
For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in suparagraphs (a) through (d) of the
Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in Cybersource Corporation's
standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.
Trademarks
Authorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation. Cybersource,
Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, and Cybersource Connect are trademarks
and/or service marks of Cybersource Corporation. Visa, Visa International, Cybersource, the Visa logo, and the Cybersource logo
are the registered trademarks of Visa International in the United States and other countries. All other trademarks, service marks,
registered marks, or registered service marks are the property of their respective owners.
Condentiality Notice
This document is furnished to you solely in your capacity as a client of Cybersource and as a participant in the Visa payments system.
By accepting this document, you acknowledge that the information contained herein (the “Information”) is condential and subject
to the condentiality restrictions contained in Visa's operating regulations and/or other condentiality agreements, which limity our
use of the Information. You agree to keep the Information condential and not to use the Information for any purpose other than its
intended purpose and in your capacity as a customer of Cybersource or as a participant in the Visa payments system. The Information
may only be disseminated within your organization on a need-to-know basis to enable your participation in the Visa payments system.
Please be advised that the Information may constitute material non-public information under U.S. federal securities laws and that
purchasing or selling securities of Visa Inc. while being aware of material non-public information would constitute a violation of
applicable U.S. federal securities laws.
Revision
Version: 23.02
Contents
Contents
Recent Revisions to This Document............................................................................................... 7
About This Guide.............................................................................................................................. 10
Introducing Payer Authentication..................................................................................................12
Overview of Chargeback Protection...................................................................................12
PSD2................................................................................................................................. 13
EMV 3-D Secure............................................................................................................ 13
Strong Customer Authentication...............................................................................13
Prerequisites for Implementing Payer Authentication........................................... 13
Payer Authentication Process Flow Overview................................................................... 14
Integrating Payer Authentication into Your Business...................................................... 15
Host Names.................................................................................................................... 15
Endpoints........................................................................................................................ 16
Tokenization and Digital Payment Options................................................................16
Overview of 3-D Secure 2.x Implementation........................................................... 16
Using Secure Acceptance with Payer Authentication......................................................17
Required Merchant Information............................................................................................17
Implementing Cardinal Cruise Direct Connection API Payer Authentication......................... 19
Prerequisites............................................................................................................................19
After Implementation and Before Go Live......................................................................... 19
Step 1: Payer Authentication Setup Service..................................................................... 20
Request Fields...............................................................................................................20
Important Response Fields.........................................................................................20
Step 2: Device Data Collection Iframe............................................................................... 20
Build the Iframe............................................................................................................ 20
Initiate the Device Data Collection Iframe............................................................... 21
Submit the Device Data Collection Iframe................................................................21
Listen for the Device Data Collection URL Response............................................ 22
Step 3: Payer Authentication Check Enrollment Service................................................22
Request Fields............................................................................................................... 22
Combining Services......................................................................................................24
Interpreting the Response......................................................................................... 25
Important Response Fields......................................................................................... 25
Cybersource Contents 3
Contents
Step 4: Step-Up IFrame........................................................................................................ 26
Building the Iframe Parameters................................................................................. 26
Creating the Iframe...................................................................................................... 27
Invoke the Iframe.......................................................................................................... 27
Receiving the Step-Up Results.................................................................................. 27
Step 5: Payer Authentication Validation Service..............................................................28
Request Fields...............................................................................................................28
Combining Services or Mapping Authorization Fields............................................28
Interpreting the Response......................................................................................... 29
Redirecting Customers to Pass or Fail Message Page.......................................... 30
Cardinal Cruise Direct Connection Integration Examples.............................................. 30
Setup Service Request and Response Examples....................................................30
Check Enrollment Request and Response Examples............................................. 32
Validate Authentication Request and Response.....................................................35
Authorization with Enroll............................................................................................. 37
Authorization with Validation..................................................................................... 39
Implementing SDK Payer Authentication..................................................................................... 42
Implementation Overview..................................................................................................... 42
Process Flow for SDK Integration.......................................................................................43
Prerequisites for SDK Implementation..............................................................................44
Credentials/API Keys................................................................................................... 44
Using the Android SDK.......................................................................................................... 44
Update the Gradle Build Properties......................................................................... 45
Congure the Android SDK........................................................................................ 45
Set Up the Initial Call................................................................................................... 47
Using the iOS SDK..................................................................................................................48
Download and Import the SDK................................................................................... 48
Set Up Your Build Environment.................................................................................. 48
Congure the iOS SDK................................................................................................49
Set Up the Initial Call....................................................................................................51
Running Payer Authentication in SDK.................................................................................52
Requesting the Check Enrollment Service (SDK)...................................................52
Interpreting the Response......................................................................................... 54
Authenticating Enrolled Cards...................................................................................54
Requesting the Validation Service............................................................................ 57
Hybrid Payer Authentication..........................................................................................................60
Implementation Overview.....................................................................................................60
Process Flow for Hybrid Integration................................................................................... 61
Payer Authentication Setup........................................................................................ 61
Add the JavaScript.......................................................................................................62
BIN Detection................................................................................................................ 62
Requesting the Check Enrollment Service.............................................................. 62
Authenticating Enrolled Cards...................................................................................64
Requesting the Validation Service............................................................................ 65
Hybrid Integration Examples.......................................................................................67
API Fields............................................................................................................................................76
Cybersource Contents 4
Contents
Required Fields for Setting Up Payer Authentication......................................................76
Optional Fields for Setting Up Payer Authentication............................................. 77
Required Fields for Checking Enrollment in Payer Authentication................................ 77
Optional Fields for Enrolling in Payer Authentication............................................ 78
Required Fields for Validating Payer Authentication....................................................... 86
Optional Fields for Validating Payer Authentication.............................................. 86
Testing Payer Authentication.........................................................................................................88
Testing Process...................................................................................................................... 88
Enrollment Check......................................................................................................... 88
Enrollment Check Response Fields...........................................................................89
Authentication Validation Test Case Fields............................................................. 89
3-D Secure 1.0 Testing.......................................................................................................... 90
Visa Secure 3-D Secure 1.0 Test Cases................................................................... 90
Mastercard Identity Check 3-D Secure 1.0 Test Cases......................................... 97
Maestro 3-D Secure 1.0 Test Cases........................................................................ 103
American Express SafeKey 3-D Secure 1.0 Test Cases........................................ 109
JCB J/Secure 3-D Secure 1.0 Test Cases............................................................... 116
Diners Club Protect Buy 3-D Secure 1.0 Test Cases.............................................123
Discover Protect Buy 3-D Secure 1.0 Test Cases................................................. 130
Test Cases for 3-D Secure 2.x........................................................................................... 138
Test Case 2.1: Successful Frictionless Authentication......................................... 138
Test Case 2.2: Unsuccessful Frictionless Authentication.....................................141
Test Case 2.3: Attempts Processing Frictionless Authentication...................... 142
Test Case 2.4: Unavailable Frictionless Authentication........................................144
Test Case 2.5: Rejected Frictionless Authentication............................................146
Test Case 2.6: Authentication not Available on Lookup....................................... 148
Test Case 2.7: Enrollment Check Error................................................................... 150
Test Case 2.8: Time-Out............................................................................................ 152
Test Case 2.9: Bypassed Authentication................................................................ 154
Test Case 2.10a: Successful Step-Up Authentication.......................................... 156
Test Case 2.11a: Unsuccessful Step-Up Authentication....................................... 158
Test Case 2.12a: Unavailable Step-Up Authentication..........................................160
Test Case 2.14: Require MethodURL........................................................................ 163
Payer Authentication Exemption Test Cases...................................................................165
Test Case 1a: Initial/First Recurring Transaction - Fixed Amount....................... 165
Test Case 2a: Card Authentication Failed.............................................................. 166
Test Case 2b: Suspected Fraud............................................................................... 166
Test Case 2c: Cardholder Not Enrolled in Service................................................ 167
Test Case 2d: Transaction Timed Out at the ACS..................................................167
Test Case 2e: Non-Payment Transaction Not Supported.................................... 167
Test Case 2f: 3RI Transaction Not Supported....................................................... 168
Test Case 3a: Transaction Risk Analysis Exemption - Low Value -
Mastercard EMV 3-D Secure 2.1 and 2.2......................................................... 168
Test Case 3b-Transaction Risk Analysis Low Value - Visa................................... 169
Test Case 3c: Transaction Risk Analysis-Low Value-Discover.............................170
Test Case 3d: Acquirer Transaction Risk Analysis-Cartes Bancaires.................170
Cybersource Contents 5
Test Case 4a: Trusted Beneciary Prompt for Trustlist........................................ 171
Test Case 4b: Utilize Trusted Beneciary Exemption............................................ 171
Test Case 5a-1: Identity Check Insights (ScoreRequest = N).............................. 172
Test Case 5a-2: Identity Check Insights (ScoreRequest = Y)..............................172
Website Modication Reference..................................................................................................174
Website Modication Checklist..........................................................................................174
3-D Secure Services Logos................................................................................................ 174
Informational Message Examples....................................................................................... 176
Alternate Methods for Device Data Collection......................................................................... 177
Device Data Collection Overview....................................................................................... 177
Prerequisites.................................................................................................................177
Endpoints...................................................................................................................... 178
Collecting Device Data.........................................................................................................178
Card BIN in JWT........................................................................................................... 178
Card BIN as a POST Parameter Plus JWT................................................................ 179
Upgrading Your Payer Authentication Implementation........................................................... 180
Benets.................................................................................................................................. 180
PSD2 Impact...........................................................................................................................180
Mandates....................................................................................................................... 181
Recommended Integration...................................................................................................181
Migration FAQ.........................................................................................................................181
Payer Authentication Transaction Details in the Business Center........................................ 183
Payer Authentication Search..............................................................................................183
Storing Payer Authentication Data....................................................................................183
Searching for Payer Authentication Details.....................................................................184
Enrolled Card............................................................................................................... 184
Card Not Enrolled....................................................................................................... 185
Payer Authentication Reports......................................................................................................186
Payer Authentication Summary Report............................................................................ 186
Downloading the Report............................................................................................186
Matching the Report to the Transaction Search Results.....................................187
Interpreting the Report............................................................................................. 187
Comparing Payer Authentication and Payment Reports...................................... 188
Payer Authentication Detail Report.................................................................................. 189
Report Elements..........................................................................................................189
Report............................................................................................................................189
PayerAuthDetail........................................................................................................... 190
ProofXML...................................................................................................................... 192
VEReq............................................................................................................................ 193
VERes.............................................................................................................................194
PAReq.............................................................................................................................194
PARes.............................................................................................................................196
AuthInfo........................................................................................................................ 198
Report Examples......................................................................................................... 198
Glossary............................................................................................................................................201
Recent Revisions to This Document
Recent Revisions to This
Document
23.02
Updated American Express Test Numbers • An extra digit was inserted into the
American Express test card numbers
when syncing the test card numbers to
the Cardinal test numbers. The extra digit
was removed.
• The American Express test card number
for the 3-D Secure 2.14: Require
MethodURL test case was updated.
Test Results for Exemption Test Case The reason code result for the exemption
Updated test case 2c: Cardholder Not Enrolled in
Service was updated.
List of Required and Optional Fields was The lists of required and optional elds
Audited were veried to ensure that all eld names
were included in the lists.
23.01
Updated 3-D Secure 2.x Test Cases • All test card numbers used for testing 3-
D Secure 2.x were changed to the same
card numbers used by Cardinal.
• Updated the expected results for several
test cases.
Updated Check Enrollment Response Rewrote Check Enrollment response
section to clarify the possible responses.
Cybersource Recent Revisions to This Document 7
Recent Revisions to This Document
22.07
3-D Secure 2.0 has made test cases for 3-D Added a note to explain that 3-D Secure
Secure 1.0 obsolete 2.0 which took effect in October 2022,
supersedes the 1.0 version so most users
should not use the 1.0 test cases. However,
since some countries were granted an
extension to continue to use 1.0, the
test cases are still available for those
users. See 3-D Secure 1.0 Testing for more
information.
22.06
Editorial changes only.
22.05
Updated Required and Optional API elds • Eliminated redundancies between
required and optional API elds.
• Moved browser elds from required to
optional elds and marked them with an
asterisk.
Updated Test PANs • Updated the JCB, Mastercard, and
American Express personal account
numbers used for testing.
Updated test cases • Removed a duplicate version of
Exemption Test Case 3a.
• Corrected test case status results for
Test Case 2.10a.-Successful Step-Up
Authentication
22.04
Minor updates • Noted that merchants using tokens
or digital payments must use PA Setup
Service unless they are using Cardinal
Mobile integration. See Tokenization and
Digital Payments Options.
• Added description of Cardinal's
consumerSessionId API eld and
noted its value must be passed to the
Cybersource Recent Revisions to This Document 8
Recent Revisions to This Document
payerAuthEnrollService_referenceId API
eld. See Setup the Initial Call.
Cybersource Recent Revisions to This Document 9
About This Guide
About This Guide
Audience and Purpose
This guide is written for application developers who want to use the REST 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.
You must write code that uses the API request and response elds to integrate payer
authentication services into your existing order management system.
Scope
This guide describes how to use the REST API to integrate payer authentication services
with your order management system. It does not describe how to get started using the
REST API nor does it explain how to use services other than payer authentication. For that
information, see the Related Documents section.
Conventions
These special statements are used in this document:
Important
An Important statement contains information essential to successfully completing
a task or learning a concept.
Warning
A Warning contains information or instructions, which, if not followed, can result in
a security risk, irreversible loss of data, or signicant cost in time or revenue.
Related Documentation
Refer to the Support Center for complete technical documentation:
Cybersource About This Guide 10
About This Guide
• Secure Acceptance Hosted Checkout Integration Guide describes how to create
Secure Acceptance proles, which enable you to integrate your order management
system with the Secure Acceptance hosted checkout. (PDF)
• Secure Acceptance Checkout API Guide describes how to create Secure Acceptance
proles, which enable you to integrate your order management system with a website
to process transactions. (PDF)
• Reporting Developer Guide describes how to view and congure Business Center
reports. (HTML)
• The API Versions page provides information about the API versions.
• The API Field Reference Guide provides information about the individual API elds.
Customer Support
For support information about any service, visit the Support Center:
customer supportcustomer support
Cybersource About This Guide 11
Introducing Payer Authentication
Introducing Payer
Authentication
Payer authentication services use front-end JavaScript and back-end API services to
provide authentication. Payer authentication services enable you to add support to your
web store for card authentication services, including:
SM
• Visa Secure
• Mastercard Identity Check®
• Maestro® (UK Domestic and international)
SM
• American Express SafeKey
• JCB J/Secure™
• Diners Club ProtectBuy
• Discover ProtectBuy
• China UnionPay
• Elo Compra Segura
These card authentication services deter unauthorized card use and protect you from
fraudulent chargeback activity referred to as liability shift. However, payer authentication
is not a fraud management service, such as Decision Manager. It is recommended
that you implement a comprehensive fraud management program in addition to payer
authentication services.
You can use payer authentication services with specic payment processors.
To nd out if your payment processor supports this feature, see the “Payer
Authentication” section in the Credit Card Services guide.
Overview of Chargeback Protection
Visa, Mastercard, Maestro, American Express, JCB, Diners Club, Discover, China UnionPay,
and Elo offer chargeback protection if merchants participate in 3-D Secure card
authentication programs, such as Visa Secure or Mastercard Identity Check. Chargebacks
occur after a transaction is processed, and how they are handled varies according to the
Cybersource Introducing Payer Authentication 12
Introducing Payer Authentication
region that issued the card. Payment card company rules might vary over time and across
geographical regions. Contact your merchant account provider to learn how to interpret
chargeback requirements and to discover which chargeback protections are offered.
PSD2
PSD2 (Payment Service Directive 2) is the new European regulatory framework that
governs payment processing and customer security and authentication. PSD2 establishes
a European Economic Area (EEA) single market for payments to encourage safer and more
innovative payment services. PSD2 mandates Strong Customer Authentication (SCA) for
all electronic payments. This requirement affects the way merchants receive payments
from customers and how customers are authenticated. PSD2 stipulates that two-factor
authentication must be applied for all electronic payments.
EMV 3-D Secure
EMV 3-D Secure, often referred to as 3-D Secure 2.x, is the authentication protocol
provided by the card networks to support SCA. To comply with SCA, merchants must
deploy 3-D Secure 2.x to their checkout page or use a compliant hosted checkout.
Additional data can be passed in now and is automatically sent to issuers as they upgrade
to 3-D Secure 2.x. The payer authentication service is also backward-compatible with 3-D
Secure 1.0.
Strong Customer Authentication
Strong customer authentication (SCA) increases the security of online payments. SCA
is required for an online payment when the issuer and acquirer are in the European
Economic Area, the U.K., or Gibraltar. To meet SCA requirements, perform payer
authentication.
An SCA exemption enables you to bypass SCA requirements. SCA exemptions enable you
to balance fraud reduction with a convenient payment experience for the customer. For
some transactions, you must obtain approval from your acquirer before using a particular
SCA exemption, especially when the acquirer is involved in the calculation of risk. You can
request only one SCA exemption for a transaction.
You can request an SCA exemption when you make an authorization request, as
documented in the Credit Card Services Developer Guide.
Prerequisites for Implementing Payer Authentication
To use the payer authentication services, you and your developers must be able to
complete these tasks:
• Write code to enable a connection to the issuing bank.
• Add JavaScript to your website to facilitate the authentication.
• Add specic data to your API requests.
• Validate the necessary data.
• Provide the additional data to the authorization request.
• Modify your website to help the customer understand the process.
Cybersource Introducing Payer Authentication 13
Introducing Payer Authentication
Payer Authentication Process Flow Overview
While each merchant's web browser-based ow will differ according to their individual
circumstances, a general overview of the payer authentication process is described
below.
1. When the cardholder checks out, and before the Buy Now button is pressed, a call is
made to the pa_setup service. This call generates a JWT and returns a sessionId that is
used for device collection in the next step.
2. The response from the pa_setup service call, returns a JWT and device data collection
URL (DCC URL) to which the merchant must POST to the DDC URL in a hidden 10x10
frame including the JWT as a POST parameter; enabling EMVCo and issuer device
collection.
3. Provide an eight-second delay before the Buy Now button is enabled, so there is
enough time for device collection to complete. After device collection is completed,
a POST response is sent to the merchant conrming that device collection completed
and that the user can press the Buy Now button to place the order.
4. Pressing Buy Now triggers the pa_enroll service request that relays the order details
(billing, email, phone information, etc.) and the initial sessionId returned from the
pa_setup service. The pa_enroll initiates 3-D Secure and checks with the issuing
bank to see if a bank challenge/step up requiring the cardholder to provide additional
authentication is necessary.
5. The pa_enroll response can occur in two different ways:
• If no step up or challenge is necessary (frictionless ow), the response includes
the ECI, CAVV, DSTransactionId, and a PAResStatus. The PAResStatus can be Y
or A for successful authentication or N, U, R for failed, unavailable, or rejected
authentication. With successful authentication, the data points are added to the
authorization message and the order is completed.
• If the issuer must step up and challenge (friction ow), the response returns an ACS
Url, a PAReq payload, a ParesStatus=C, a StepUpURL, a new JWT, and a TransactionId.
6. The JWT and the StepUpUrl received in the pa_enroll response, is passed to the client.
A POST goes to the StepUpUrl in a viewable iframe with the JWT as a POST parameter to
display a bank challenge screen. This enables the cardholder to view and respond to any
bank challenge screen.
7. After the cardholder completes the bank challenge by providing additional
authentication, a POST is sent to the merchant's returnUrl contained in the JWT. This
POST is a notication that the challenge is complete and triggers the merchant to make
a pa_validate call to obtain the nal authentication outcome.
8. The challenge response triggers the pa_validate request with the TransactionId. The
response to this pa_validate request contains the nal authentication results including
the nal ECI, CAVV (if successful), DSTransactionId, ThreeDSVersion, and PAResStatus
(Y or A = successful or N, U, R = failed, unavailable, or rejected).
9. If the authentication result is:
Cybersource Introducing Payer Authentication 14
Introducing Payer Authentication
• Successful—Proceed to authorization and append the 3-D Secure data points to the
authorization message.
• Failed, Unavailable, or Rejected—The cardholder is returned to the payment page to
attempt payment with a different card.
Integrating Payer Authentication into Your
Business
You can integrate payer authentication services into your existing business processes
whether you are currently using 3-D Secure 1.0 or you are new to payer authentication.
There are three types of integration available:
• Cardinal Cruise Direct Connection API: This is the most recently developed integration
method and is the method that is recommended for most merchants.
• SDK: This integration method is used for implementing payer authentication in your
Android and iOS mobile applications.
• Hybrid: This older integration method is still supported for customers but is not
recommended for new customers.
The SDK integration is designed for 3-D Secure 2.x transactions only; however, support
for 3-D Secure 1.0 is available until October 2022. If you are currently using 3-D Secure
1.0, you need to upgrade to 3-D Secure 2.0. (See Upgrading Your Payer Authentication
Implementation on page 180.) Most card networks have announced their intention to
stop supporting 3-D Secure 1.0 by October 2022. After that, no transactions can use
3-D Secure 1.0. We recommend updating to the Cardinal Cruise Direct Connection API
solution to meet EMVCo 3-D Secure protocols and ensure a smooth experience for your
cardholders.
You can also use Secure Acceptance to enable 3-D Secure 2.x for payer authentication
services. For more information, see Using Secure Acceptance with Payer Authentication
on page 17.
Host Names
The host names that you use depend upon the environment receiving the request. Use
a testing environment as a sandbox to test your system conguration by simulating
transactions with various payment cards. Use the production environment to process real
transactions.
Testing Environment
https://apitest.cybersource.com
Production Environment
https://api.cybersource.com
Cybersource Introducing Payer Authentication 15
Introducing Payer Authentication
Endpoints
All requests to the payer authentication resource use a POST to these endpoints.
Endpoints
Endpoint Description
/risk/v1/authentications Checks whether a card is enrolled in a card
authentication program and if so, an authentication
is requested from the issuer.
/risk/v1/authentication-results Retrieves and validates the authentication results
from the issuer and enables the merchant to
proceed with processing the payment.
/pts/v2/payments Bundles multiple payments together.
Tokenization and Digital Payment Options
When merchants are utilizing Secure Acceptance tokenization service or any of the digital
payment options such as Apple Pay or Google Pay, they must use the Payer Authentication
Setup Service unless the merchant is utilizing the Cardinal Mobile integration.
Overview of 3-D Secure 2.x Implementation
A broad overview of the process of implementing 3-D Secure 2.x is described below.
Depending upon your current business arrangements, some of the steps may not apply to
your situation.
1. Contact your account manager or sales manager to discuss how your business can
implement 3-D Secure 2.x and the European Union's Payment Services Directive 2
(PSD2).
2. If you are new to payer authentication, set up your merchant ID by contacting
customer supportcustomer support to enable 3-D Secure 2.x for the desired card
types, currencies, and acquiring bank. For additional details, see Required Merchant
Information on page 17.
3. Log in to the Business Center to obtain the API keys for implementation.
4. Implement 3-D Secure 2.x with the REST API using the Cardinal Cruise Direct
Connection API as well as the SDK if you want to implement a native mobile application.
SDKs are available for iOS or Android. Implement the SDK to handle authentication
steps within the native application. The SDKs are the CardinalCommerce JavaScript
equivalent for mobile applications.
5. Congure your system to request the Check Enrollment and Validate Authentication
services. Include the required API elds in your request and consider including optional
elds based on your business needs. For more information, see the Required Merchant
Information on page 17 section and Implementing Cardinal Cruise Direct Connection
API Payer Authentication. You can congure your system to request payment services
along with your payer authentication for 3-D Secure 2.x, but it is not required.
Cybersource Introducing Payer Authentication 16
Introducing Payer Authentication
6. Test your 3-D Secure 2.x services. This testing ensures that you understand the
possible use cases as part of implementation. Refer to Testing Payer Authentication
Services and run the test cases in Test Cases for 3-D Secure 2.x.
7. Congure your account for production by requesting a boarding form from customer
supportcustomer support for your processor or acquirer.
8. If you are new to payer authentication, complete the boarding form with required
information including your merchant ID, your acquirer merchant ID, and Bank
Identication Number (BIN) information for all chosen card types. For details, see
Required Merchant Information on page 17.
Using Secure Acceptance with Payer
Authentication
Secure Acceptance offers the ability to enable 3-D Secure 2.x for payer authentication
services. You can choose when to upgrade by selecting the option in your Secure
Acceptance prole in the Business Center.
For more information on implementing Secure Acceptance with payer authentication, see
the Secure Acceptance Hosted Checkout Integration Guide (PDF) or Secure Acceptance
Checkout API Guide (PDF).
Required Merchant Information
Before using payer authentication services in production, you must contact customer
supportcustomer support and provide information about your company and your acquiring
bank so your account can be congured to implement these services.
You must provide this information before payer authentication services can be enabled:
Information Description
About your company • Your merchant ID.
• URL of your company’s website, for example: http://
www.example.com
• Two-character ISO code for your country.
• 3-D Secure requestor ID (optional)
• 3-D Secure requestor name (optional)
• Merchant category code
• Name of your bank acquirer.
• Complete name and address of your bank contact,
including email address.
Cybersource Introducing Payer Authentication 17
Introducing Payer Authentication
Information Description
Bank information • Name of your bank acquirer.
• Complete name and address of your bank contact,
including email address.
Visa, Mastercard, Maestro, Information provided by your bank acquirer about each
American Express, JCB, payment card company for which you are congured:
Diners Club, Discover,
• Eight-digit BIN numbers.
China UnionPay, and Elo
information Acquirer • Acquirer merchant ID: merchant ID assigned by your
merchant ID acquirer.
• All currencies that you can process.
Cybersource Introducing Payer Authentication 18
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Implementing Cardinal
Cruise Direct Connection
API Payer Authentication
The Cardinal Cruise Direct Connection API supports 3-D Secure 2.x and is backward-
compatible with 3-D Secure 1.0 when the issuer or acquirer is not ready for 2.x. This
integration enables you to use an iframe to complete the device proling and 3-D Secure
authentication requirements without including third-party JavaScript directly on your site.
The implementation still requires the use of JavaScript on the page, and it uses
CardinalCommerce JavaScript to leverage the authentication. The CardinalCommerce
JavaScript is hosted and contained in the iframe and does not directly access your web
page.
Prerequisites
Notify your account representative that you want to implement payer authentication (3-D
Secure) using the Cardinal Cruise Direct Connection API. 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 elds 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 on page 88. Testing ensures that your account is
congured for production.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 19
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Step 1: Payer Authentication Setup Service
Call the Payer Authentication Setup service on the server side before selecting the
button to submit payment. Request the Payer Authentication Setup service separately
without including other services.
Request Fields
When requesting the Payer Authentication Setup service, you must send either the
customer’s card number, encrypted payment data, transient token, or a TMS token or
some other equivalent of card data used by your integration. The request elds may
include any of the following:
• paymentInformation.card.numberpaymentInformation.tokenizedCard.number
• paymentInformation.customer.customerId
• tokenInformation.transientToken
The paymentInformation.card.type eld is required when the card type is Cartes Bancaires
or UPI.
Important Response Fields
consumerAuthenticationInformation.accessToken is used in Step 2: Device Data
Collection Iframe on page 20.
consumerAuthenticationInformation.deviceDataCollectionUrl is used in Step 2: Device
Data Collection Iframe on page 20.
consumerAuthenticationInformation.referenceId is used in Step 3: Payer Authentication
Check Enrollment Service on page 22.
For further details on examples, see the Request and Response Examples in the Payer
Authentication Developer Guide.
Step 2: Device Data Collection Iframe
Device data collection is initiated on the front end after you receive the server-side Payer
Authentication Setup service response as described in Step 1: Payer Authentication Setup
Service on page 20 and pass consumerAuthenticationInformation.accessToken and
device data collection URL to the front end.
The hidden pixel iframe is rendered to the browser to prole the customer device. The
response depends on the card-issuing bank and can take about eight seconds. If you
proceed with the check enrollment service as described in Step 3: Payer Authentication
Check Enrollment Service on page 22 before a response is received, authentication
reverts to 3-D Secure 1.0.
Build the Iframe
The iframe has these parameters.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 20
Implementing Cardinal Cruise Direct Connection API Payer Authentication
• Form POST Action: The POST that goes to the URL that is opened within the iframe is
from the consumerAuthenticationInformation.deviceDataCollectionUrl response eld
discussed in Step 1: Payer Authentication Setup Service on page 20.
• JWT POST Parameter: Use the value from the
consumerAuthenticationInformation.accessToken response eld discussed in Step 1:
Payer Authentication Setup Service on page 20.
Initiate the Device Data Collection Iframe
Initiate a form POST in a hidden 10 x 10 iframe and send it to the device data collection URL
( consumerAuthenticationInformation.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: Payer Authentication Setup Service on page 20. 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>
Submit 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 can submit the form at a different time, but 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>
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 21
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Listen for 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.
The event.origin URL that you use depends on whether you are in a test or production
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": "prole.completed",
"Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",
"Status": true
}
Step 3: Payer Authentication Check
Enrollment Service
The device collection process must nish before the customer selects the option to buy.
You must receive a response before requesting the Check Enrollment service.
Request Fields
The consumerAuthenticationInformation.referenceId eld is mapped from the
consumerAuthenticationInformation.referenceId eld as discussed in Step 1: Payer
Authentication Setup Service on page 20.
consumerAuthenticationInformation.returnUrl is set to the URL where the issuing bank
will redirect the customer as discussed in Step 4: Step-Up IFrame on page 26.
To request the Payer Authentication Check Enrollment service, you must send either
the customer’s card number, encrypted payment data, transient token, or a TMS token
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 22
Implementing Cardinal Cruise Direct Connection API Payer Authentication
or transient token or some other equivalent of card data used by your integration. The
request elds may include any of these:
• paymentInformation.card.number
• paymentInformation.uidData.value
• paymentInformation.uidData.descriptor
• paymentInformation.customer.customerID
• tokenInformation.transientToken
These elds are required (merchant ID is in the header):
• orderInformation.amountDetails.totalAmount
• orderInformation.billTo.address1
• orderInformation.billTo.locality
• orderInformation.billTo.country
• orderInformation.billTo.administrativeArea
• orderInformation.billTo.postalCode
• paymentInformation.card.type
• orderInformation.amountDetails.currency
• paymentInformation.card.expirationMonth
• paymentInformation.card.expirationYear
• orderInformation.billTo.email
• orderInformation.billTo.rstName
• orderInformation.billTo.lastName
• consumerAuthenticationInformation.referenceId
• consumerAuthenticationInformation.returnUrl
• clientReferenceInformation.code
You can send additional request data to reduce your issuer step-up authentication rates.
Send all available elds. As a backup, in case, device data collection fails, it is a good idea
to include the 11 device information elds listed among the optional elds for the Check
Enrollment service in your request. If a failure does occur, adding these device information
elds ensures a transaction is not downgraded to 3-D Secure 1.0. If you do not have data
for a eld, do not send dummy data.
The size of the step-up iframe discussed in Step 4: Step-Up IFrame on page 26 can
vary depending on the 3-D Secure version of the transaction (1.0 or 2.x). You can send the
size of the challenge window in the consumerAuthenticationInformation.acsWindowSize
request eld.
Requesting a specic window size does not guarantee this size. Parsing the PAReq as
described in Step 4: Step-Up IFrame on page 26 determines the actual size.
For further details on individual API elds, refer to the API Field Reference Guide. The eld
values should use the ISO 3166-2 format.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 23
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Combining Services
You can combine the enrollment check and card authorization services into the
same request or use a separate request for each service. Using the same request is
recommended.
• Same request: Attempts to authorize the card after authentication are made if step-
up payer authentication is not required. In this case, the eld values that are required
to prove that you attempted to check enrollment are passed automatically to the
authorization service. With same request transactions, a different endpoint must
be referenced and an additional element must be added to the JSON. If step-up
authentication is required, processing stops to allow completion, and authorization is
not called. This integration method is recommended.
• Separate requests: Manually include the enrollment check result values (Enrollment
Check Response Fields) in the authorization service request (Card Authorization
Request Fields). Refer to the elds that are listed in the table.
Depending on your card type, and whether it is a 3-D Secure 1.0 or 2.x transaction, you
might not receive the XID. If you receive this eld under a frictionless scenario, it is
required for authorization.
This table lists these elds.
Enrollment Check and Response Fields
Identier Enrollment Check Response Card Authorization Request
Field Field
E-commerce indicator consumerAuthenticationInfo processingInformation.com
rmation.ecommerceIndicator merceIndicator
Collection indicator consumerAuthenticationInfo consumerAuthenticationInfo
(Mastercard only) rmation.ucaf CollectionI rmation.ucafCollectionIndi
ndicator cator
CAVV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.cavv rmation.cavv
AAV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.ucafAuthenticationData
rmation.ucafAuthentication
Data
XID consumerAuthenticationInfo consumerAuthenticationInfo
rmation.xid rmation.xid
Result of the enrollment consumerAuthenticationInfo consumerAuthenticationInfo
check for Asia, Middle East, rmation.veresEnrolled rmation.veresEnrolled
and Africa Gateway
3-D Secure version consumerAuthenticationInfo consumerAuthenticationInfo
rmation.specicationVersion rmation.paSpecicationVers
ion
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 24
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Identier Enrollment Check Response Card Authorization Request
Field Field
Directory server transaction consumerAuthenticationInfo consumerAuthenticationInfo
ID rmation.directoryServerTrans rmation.directoryServerTran
(Not required for 3-D actionId sactionId
Secure 1.0.)
Interpreting the Response
The possible response statuses to checking enrollment in a payer authentication program
are similar for all card types.
• PENDING_AUTHENTICATION: the customer’s card is enrolled in a payer authentication
program. When you receive this response, proceed to Step 4: Step-Up IFrame on page
26.
• AUTHENTICATION_SUCCESSFUL: the card is not enrolled in a payer authentication
program or step-up authentication is not required. There are multiple reasons this
response might occur:
• Account number is not eligible for a payer authentication program. The other
services in your request are processed normally. To receive liability shift protection
when making separate enrollment and authorization calls, pertinent payer
authentication data must be included whenever step-up authentication is required.
• Step-up authentication is not required. The other services in your request are
processed normally.
• Payer authentication is not supported by the card type. When you receive this
response, you can proceed to card authorization. If you receive the authentication
results along with AUTHENTICATION_SUCCESSFUL, you might receive liability shift
protection.
• AUTHENTICATION_FAILED: the card could not be authenticated. The
merchant must display a card issuer message to the cardholder using the
consumerAuthenticationInformation.cardholderMessage eld.
The message text is provided by the ACS/issuer to the cardholder during a frictionless
or decoupled transaction to convey information to cardholder. For example, “Additional
authentication is needed for this transaction, contact (issuer name) at xxx-xxx-xxxx.”
The entry that appears in the log will be similar to this example:
"cardholderInfo":"You're unable to complete this purchase right now. For help call
CommBank on 13 2221"
Important Response Fields
When you receive a PENDING_AUTHENTICATION response, you also receive these elds:
• consumerAuthenticationInformation.stepUpUrl discussed in Step 4: Step-Up IFrame on
page 26.
• consumerAuthenticationInformation.accessToken discussed in Step 4: Step-Up IFrame
on page 26.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 25
Implementing Cardinal Cruise Direct Connection API Payer Authentication
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 on page 22. Note
that frictionless authentication does not require this Step-Up iframe step. This step is
only for step-up authentication.
The iframe manages customer interaction with the card-issuing bank’s Access Control
Server and 3-D Secure version compatibility for 3-D Secure 1.0 and 3-D Secure 2.x.
Building the Iframe Parameters
• Form POST Action: The POST is made to the URL within the iframe is from the
consumerAuthenticationInformation.stepUpUrl response eld discussed in Step 3:
Payer Authentication Check Enrollment Service on page 22.
• JWT POST Parameter: Use the value from the
consumerAuthenticationInformation.accessToken eld discussed in Step 3: Payer
Authentication Check Enrollment Service on page 22.
• MD POST Parameter: Merchant-dened data returned in the response. This eld is
optional.
• Iframe height and width:
• 3-D Secure 1.0 uses a standard size of 400 pixels by 400 pixels.
• 3-D Secure 2.x offers multiple size options:
• Use the consumerAuthenticationInformation.acsWindowSize request eld to
request (but not guarantee) a specic window size.
• Use the consumerAuthenticationInformation. pareq response eld to determine
iframe dimensions by Base64 decoding the string and cross-referencing a
Challenge Window Size value with its corresponding size.
This table lists these values.
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.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 26
Implementing Cardinal Cruise Direct Connection API Payer Authentication
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>
Invoke 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 user is returned to the
consumerAuthenticationInformation.returnUrl within the iframe as specied in Step 3:
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 27
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Payer Authentication Check Enrollment Service on page 22. The payload sent to the
returnURL is URL-encoded and Base64-encoded (see the example below). The merchant
hosting the returnURL can then close the iframe after redirection.
The response sent back to the return URL contains this:
• Transaction ID: (consumerAuthenticationInformation.authenticationTransactionId
response eld). This is used in Step 5: Payer Authentication Validation Service on page
28.
• 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 response as discussed in Step 4: Step-Up IFrame on page 26,
make a validation call to verify that the customer successfully authenticated. Note that
frictionless authentication does not require this validation step. Validation is required only
for step-up authentication.
Request Fields
The consumerAuthenticationInformation.authenticationTransactionId eld is mapped
from the consumerAuthenticationInformation.authenticationTransactionId eld in Step 4:
Step-Up IFrame on page 26.
Combining Services or Mapping Authorization Fields
It is recommended that you request both payer authentication and card authorization
services at the same time. When you do both services simultaneously, the correct
information is automatically sent to your payment processor with the values of these
elds being converted to the proper format required by your payment processor:
• E-commerce indicator: consumerAuthenticationInformation.indicator
• CAVV: consumerAuthenticationInformation.cavv
• AAV: consumerAuthenticationInformation.ucafAuthenticationData
• XID: consumerAuthenticationInformation.xid
If you request the services separately, you must manually pass the validation result values
(Validation Check Response Fields) received in the response to 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 pass this information can invalidate your liability shift for that transaction. This
transaction information includes the electronic commerce indicator (ECI), the transaction
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 28
Implementing Cardinal Cruise Direct Connection API Payer Authentication
ID (XID), the 3-D Secure version, the directory server transaction ID, and the following
card-specic information in your authorization request:
• For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo include
the CAVV (cardholder authentication verication value).
• For Mastercard, include the UCAF (universal cardholder authentication eld) and the
collection indicator.
Depending on your card type and whether it is a 3-D Secure 1.0 or 2.x transaction, you
might not receive the XID. If you receive this eld back, it is required for authorization.
The following table lists these elds.
Identier Validation Check Response Card Authorization Request
Field Field
E-commerce indicator consumerAuthenticationInfo processingInformation.com
rmation.indicator merceIndicator
Collection indicator consumerAuthenticationInfo consumerAuthenticationInfo
(Mastercard only) rmation.ucafCollectionIndi rmation.ucafCollectionIndi
cator cator
CAVV (Visa and American consumerAuthenticationInfo consumerAuthenticationInfo
Express only) rmation.cavv rmation.cavv
AAV (Mastercard only. consumerAuthenticationInfo consumerAuthenticationInfo
Known as UCAF) rmation.ucafAuthentication rmation.ucafAuthentication
Data Data
XID consumerAuthenticationInfo consumerAuthenticationInfo
rmation.xid rmation.xid
3-D Secure version consumerAuthenticationInfo consumerAuthenticationInfo
rmation.specicationVersion rmation.paSpecicationVer
sion
Directory server transaction consumerAuthenticationInfo consumerAuthenticationInfo
ID rmation.directoryServerTran rmation.directoryServerTran
(Not required for 3-D sactionId sactionId
Secure 1.0.)
Interpreting the Response
If the authentication is rejected (TransStatus R), Visa, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo recommend that you do not proceed to AuthZ. Instead,
you must ask the customer to use another payment method.
Proceed with the order according to the validation response that you receive. The
responses are similar for all card types:
• Success: A status of AUTHENTICATION_SUCCESSFUL indicates other service requests,
including authorization, processed normally.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 29
Implementing Cardinal Cruise Direct Connection API Payer Authentication
• Failure: A status of AUTHENTICATION_FAILED indicates the other services in your
request did not process.
• 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 support. If you receive a system error, determine the cause, and
proceed with card authorization only when appropriate.
Verify that the enrollment and validation checks are for the same transaction. One way to
ensure that the enrollment check and validation responses are identical is to verify that
the XID value is the same for each.
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.
Cardinal Cruise Direct Connection
Integration Examples
These examples show a request and response for the Payer Authentication Setup, the
Check Enrollment, and Validate Authentication services.
Setup Service Request and Response Examples
These are examples of a Setup service request that is called after selecting the payment
instrument and the corresponding response.
Payer Authentication Setup Service Request
URL: https://apitest.cybersource.com/risk/v1/authentication-setups
{
"paymentInformation": {
"card": {
"expirationMonth": "12",
"expirationYear": "2025",
"number": "XXXXXXXXXXXXXXXX"
}
}
}
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 30
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Payer Authentication Setup Service Response
{
"consumerAuthenticationInformation": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwOTczYjBiMC00NmU1LTQ3NWQ
tYWUxMC04ZDFkYmRlMzQ0ZDYiLCJpYXQiOjE2MjgxMTk1OTMsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRj
YmFjYSIsImV4cCI6MTYyODEyMzE5MywiT3JnVW5pdElkIjoiNWI5YzRiYjNmZjYyNmIxMzQ0ODEwYTAxIiwiUmVmZX
JlbmNlSWQiOiJiODRlM2RjYS1mNzRmLTQ1YjEtYTVkMC00YTE5ZGViN2I4MTMifQ.W_IetbptYPtIckZkLQY8nPAh
VbnJ12NoniNTKnadswQ",
"deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
"referenceId": "b84e3dca-f74f-45b1-a5d0-4a19deb7b813",
"token": "AxizbwSTVIEatEaJItj7ABEBURxNDQF4AEwIZNJMvRiuZhTAGAAA9QBZ"
},
"id": "6281195931256576203003",
"status": "COMPLETED",
"submitTimeUtc": "2021-08-04T23:26:33Z"
}
The Payer Authentication APIs are capable of handling encrypted digital payment payloads
instead of the payment information. The following is an example of an Payer Authentication
Setup request and its corresponding response using Google Pay as the digital payment
option.
Setup Request Using Google Pay
{
"paymentInformation": {
"uidData" : {
"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"
}
}
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 31
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Setup Response Using Google Pay
{
"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"
}
Check Enrollment Request and Response Examples
These are examples of a Check Enrollment request that veries whether a card is enrolled
in a card authentication program and its corresponding response.
Payer Authentication Check Enrollment Request
URL: https://apitest.cybersource.com/risk/v1/authentications
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"expirationMonth": "08",
"expirationYear": 2023
}
},
"consumerAuthenticationInformation": {
"referenceId": "c44224db-0dda-40aa-9536-ac1595fd2e8d",
"transactionMode": "S",
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 32
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"returnUrl": "https://wv730hw7033250:3002/restapi/cardinalDirect/StepUp/Response"
}
}
Check Enrollment Response
{
"consumerAuthenticationInformation": {
"acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"challengeRequired": "N",
"stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
"authenticationTransactionId": "1xRSpLPEoTNsinp8XUK0",
"pareq":
"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSU
QiOiI4NGU2YzIzYi1lNjIxLTQ2NGUtYWFlYy0xOGNkZDE1YTBlZWMiLCJhY3NUcmFuc0lEIjoiZWU3NDVlM2MtYz
I2Ny00YzM0LTkzMTEtMGI3NTYwYzJkNjhmIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"directoryServerTransactionId": "4d19781a-49d7-4c90-a145-72b8107fed8f",
"veresEnrolled": "Y",
"threeDSServerTransactionId": "84e6c23b-e621-464e-aaec-18cdd15a0eec",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyN2I1MjcyYS00OWFiLTQ5Y
jQtYTljYy1mMTBhYjcxMGMyYjciLCJpYXQiOjE2MzAwOTkxNjMsImlzcyI6IjVkZDgzYmYwMGU0M
jNkMTQ5OGRjYmFjYSIsImV4cCI6MTYzMDEwMjc2MywiT3JnVW5pdElkIjoiNTk1YWRhYj
AzM2ZhZGQyYzUwZTg5NDYxIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJ
jaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJ
QYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVd
kbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNu
WmxjbFJ5WVc1elNVUWlPaUk0TkdVMll6SXpZaTFsTmpJeExUUTJOR1V0WVdGbFl5MHhPR05rWkRFMVlU
QmxaV01pTENKaFkzTlVjbUZ1YzBsRUlqb2laV1UzTkRWbE0yTXRZekkyTnkwMFl
6TTBMVGt6TVRFdE1HSTNOVFl3WXpKa05qaG1JaXdpWTJoaGJHeGxibWRsVj
JsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiMXhSU3BMUEVvVE5zaW5wO
FhVSzAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly93dj
czMGh3NzAzMzI1MDozMDAyL3Jlc3RhcGkvY2FyZGluYWxEaXJlY3QvU3RlcFVwL1Jlc3
BvbnNlIn0.ixbdhFoB8M_BWI2sAIIQUjWtIOMzIwRImrg5iu7AyNE",
"specicationVersion": "2.1.0",
"token": "AxjzbwSTVZPTJPD7ixR8ADUBURxP1CnnpA6cQE1129JMvRiuHCKArAAAx/+g",
"acsTransactionId": "ee745e3c-c267-4c34-9311-0b7560c2d68f"
},
"errorInformation": {
"reason": "CONSUMER_AUTHENTICATION_REQUIRED",
"message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder
before continuing with the transaction."
},
"id": "6300991627296049403004",
"paymentInformation": {
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"status": "PENDING_AUTHENTICATION",
"submitTimeUtc": "2021-08-27T21:19:23Z"
}
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 33
Implementing Cardinal Cruise Direct Connection API Payer Authentication
The following is an example of an Payer Authentication Check Enrollment request and its
corresponding response using Google Pay as the digital payment option.
Check Enrollment Request Using Google Pay
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.99"
},
"billTo": {
"address1": "1 Market St",
"address2": "Address 2",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "4158880000",
"email": "[email protected]",
"postalCode": "94105"
}
},
"paymentInformation": {
"uidData" : {
"value" :
"eyJzaWduYXR1cmUiOiJNRVFDSUVhVVBmc1RIMERyMnZmeG8wVkFlZ3N2bHlSRzdENEFsYmRwa1pPdlNzZGtBaUFVO
DE2aHpmMG5BMzJzQmx6anlUSURyZXBHNUY1eEtlRmNnSE9aK3RML2ZRXHUwMDNkXHUwMDNkIiwiaW50ZXJtZWRpY
XRlU2lnbmluZ0tleSI6eyJzaWduZWRLZXkiOiJ7XCJrZXlWYWx1ZVwiOlwiTUZrd0V3WUhLb1pJemowQ0FRWUlLb
1pJemowREFRY0RRZ0FFOFdKSHVMOFVuWW9WWDNHV3dGVkJpcnh6L3lJdGl0aW9neWhDeGpCRm5tS3pCcWs2K3l
nVU5SUGF4THdaaWtILzBxV0s1QXhlc3BDNVhwN1NHNUN1T1FcXHUwMDNkXFx1MDAzZFwiLFwia2V5RXhwaXJhdGlvb
lwiOlwiMTYzMDUxNjYyODA0OVwifSIsInNpZ25hdHVyZXMiOlsiTUVVQ0lRRHlTQTV1T2t5UXQ5cFoyQlEzaXBmc
GNWT0F5ZmIzM2ozUEZPQUw3K1o5S3dJZ2FjWWp2YWJpTEUyWHFkNU1xNGphNStEVldoREttVHpoMmk1RGlnbllF
QndcdTAwM2QiXX0sInByb3RvY29sVmVyc2lvbiI6IkVDdjIiLCJzaWduZWRNZXNzYWdlIjoie1wiZW5jcnlwdGVk
TWVzc2FnZVwiOlwiWG5qOGxSSWhGMDVEWWdRK3hwNEE5YUhsVGE1U2ljdUJac2w1L2NNRkJlclBBY1RzaE4zRFl
Ob1MvdEVkRkRYRzZJRXBpVlcxVnV6OUprejNWWGdpMzJrT21EVk9aakJNWTFvVHdTQnA5WG53ejlLYUtOekYvRFB
STy9jbStobW9iZ2dSdmxGSStOekN5U1VNWW1hbTJjZFUyZGRZWmZHck9nZWNSc3FrdW1tNmlMa0xGQTFJcDFrNW
FRV21EUElEdTh1SnNmbWs4bzMyMlpteVdMMVVWenE0WHFkNTZScXZoL1VFeEp3RC9HZXU5SW00M0pmblZqckVke
DE0Ykx1OUpmMHJrcU5ONG5sM0NVZEFoMVNhZnBzdkduTVRML1Nmenk1ZGdDZlRDcHJDdW85UVZPaXVValBJNUdX
RlBKSWVVVVU1cUZhcis3NXFBT2dvZ0tNRUZ3OFVxL1A0UjBDcXczcFllNnc2enlaVzdDV1YxRzRMc3BITTNRaE
83bFZNNmRjSWZQWW00ZitubWI3UzgwY29KTXR1QjkxVEhjZzJmVXhwM2FrWEhSdzNyN3BRZk9KWWFieUlURmtie
Dh0Yi9ieWl6VUZEVVU4S3EwTmVCVTVrQng2L21qUDg4bWxoWkE2ZERrNWJVc2o4SDBDSk9nWUtCbVgyR09vamRt
TDd5YlBnTU5vNnhsYjRtUzVkaTJjZUpFakFybEZFa3NWNTlsS2lodk5pckRZc1BTU2lTRFVZNjBMUXVuTEErYj
FMSnpCMkpYelFcIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOlwiQk84bmtEbE0ycVlCQmpQd00wbDdUTFY2UytUb
zZDTFl0eXArWGM2cXpQYklLTEgxVytySGh3NUlwU2lqb1lTb3VaclNuWU9LV21yRVAyYmtLMk4rTWFZXFx1MDAzZ
FwiLFwidGFnXCI6XCJuVU5xUVlxcy9YRVlDMmg0WFlibnVpajFLb1NzUFpacEpqVGI4TVVZcUZNXFx1MDA zZFwifSJ9"
}
},
"processingInformation": {
"paymentSolution": "012"
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 34
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"transactionMode": "MOTO"
}
}
Setup Response Using Google Pay
{
"consumerAuthenticationInformation": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI5MjlhZDAwYy0zZmEyLTQ5ODgtODR
jNC1hYTcxMGFlY2I1OGEiLCJpYXQiOjE2Mjk4MjY5NjAsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsIm
V4cCI6MTYyOTgzMDU2MCwiT3JnVW5pdElkIjoiNWI5YzRiYjNmZjYyNmIxMzQ0ODEwYTAxIiwiUmVmZXJlbmNlSWQi
OiI5NDkzZjJiZi04NmIwLTQ0ZmYtYmJjZS0wZjU1MjNlMWIzNGEifQ.FgVbwbW9_lwnlr4ovYR5VVPuVl6CklAVHHX
S_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"
}
Validate Authentication Request and Response
These are examples of a Payer Authentication Validate Authentication request and its
corresponding response.
Validate Authentication Request
Test URL: https://apitest.cybersource.com/pts/v2/payments
Prod URL: https://api.cybersource.com/pts/v2/payments
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 35
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"expirationMonth": "01",
"expirationYear": 2023
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"authenticationTransactionId": "1xRSpLPEoTNsinp8XUK0"
}
}
Validate Authentication Response
{
"clientReferenceInformation": {
"code": "3DSHarness_PaValidateRestAPI"
},
"consumerAuthenticationInformation": {
"indicator": "vbv",
"eciRaw": "05",
"authenticationResult": "0",
"authenticationStatusMsg": "Success",
"eci": "05",
"token": "AxjzbwSTVZPVXrQRXOgcADUBURxP1C3TpA6cQE14ZNJMvRiuHCKArAAA5AAG",
"cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"paresStatus": "Y",
"xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"directoryServerTransactionId": "4d19781a-49d7-4c90-a145-72b8107fed8f",
"threeDSServerTransactionId": "84e6c23b-e621-464e-aaec-18cdd15a0eec",
"specicationVersion": "2.1.0",
"acsTransactionId": "ee745e3c-c267-4c34-9311-0b7560c2d68f"
},
"id": "6300992253756050303004",
"paymentInformation": {
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"status": "AUTHENTICATION_SUCCESSFUL",
"submitTimeUtc": "2021-08-27T21:20:25Z"
}
The following is an example of an Payer Authentication Validate request and its
corresponding response using Google Pay as the digital payment option.
Validate Request Using Google Pay
{
"clientReferenceInformation": {
"code": ""
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 36
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"totalAmount": "200.00"
},
"lineItems": [
{
"unitPrice": "10",
"quantity": "2",
"taxAmount": "32.40"
}
]
},
"paymentInformation": {
"card": {
"type": "002",
"expirationMonth": "12",
"expirationYear": "2025",
"number": "5200000000000007"
},
"uidData": {
"value": "XFx1MDAzZFwiLFwia2V5RXhwaXJhdGlvblwiOlwiMTYzMDUxNjYyODA0OVwifSI
sInNpZ25hdHVyZXMiOlsiTUVVQ0lRRHlTQTV1T2t5UXQ5cFoyQlEzaXBmcGNWT0F5ZmIzM2ozUEZPQUw3K1o5S3
dJZ2FjWWp2YWJpTEUyWHFkNU1xNGphNStEVldoREttVHpoMmk1RGlnbllFQndcdTAwM2QiXX0sInByb3Rv
Y29sVmVyc2lvbiI6IkVDdjIiLCJzaWduZWRNZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwiWG5qOG
xSSWhGMDVEWWdRK3hwNEE5YUhsVGE1U2ljdUJac2w1L2NNRkJlclBBY1RzaE4zRFlOb1MvdEVkRkRYRzZJRXBp
VlcxVnV6OUprejNWWGdpMzJrT21EVk9aakJNWTFvVHdTQnA5WG53ejlLYUtOekYvRFBSTy9jbStobW9iZ2dSdmx
GSStOekN5U1VNWW1hbTJjZFUyZGRZWmZHck9nZWNSc3FrdW1tNmlMa0xGQTFJcDFrNWFRV21EUElEdTh1SnNmbWs4
bzMyMlpteVdMMVVWenE0WHFkNTZScXZoL1VFeEp3RC9HZXU5SW00M0pmblZqckVkeDE0Ykx1OUpm"
}
},
"consumerAuthenticationInformation": {
"authenticationTransactionId": "PYffv9G3sa1e0CQr5fV0"
}
}
Validate Response Using Google Pay
{
"clientReferenceInformation": {
"code": "1648503547340"
},
"consumerAuthenticationInformation": {
"indicator": "internet",
"ucafCollectionIndicator": "0",
"token": "AxjzbwSTX43yPAubTbmGAD0CURxtQdcxpA+cQEE8MmkmXoxYboZgHAAA/wHd"
},
"id": "6485035473596312304006",
"status": "AUTHENTICATION_SUCCESSFUL",
"submitTimeUtc": "2022-03-28T21:39:09Z"
}
Authorization with Enroll
These are examples of an Payer Authentication Authorization with Enroll request and its
corresponding response.
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 37
Implementing Cardinal Cruise Direct Connection API Payer Authentication
Authorization with Payer Authentication Enroll (Authentication Needed) Request
POST /pts/v2/payments HTTP/1.1
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
"expirationMonth": "01",
"expirationYear": 2023
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"referenceId": "eb0d0ad6-510a-4f0e-9103-e6ee5b024ae2",
"transactionMode": "S",
"returnUrl": "https://wv730hw7033250:3002/restapi/cardinalDirect/StepUp/Response"
},
"processingInformation": {
"actionList": [
"CONSUMER_AUTHENTICATION"
]
}
}
Authorization with Payer Authentication Enroll (Authentication Needed) Response
{
"consumerAuthenticationInformation": {
"acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"challengeRequired": "N",
"stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
"authenticationTransactionId": "grmOLQpFJd6KjSqV2ow0",
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 38
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1Nlcn
ZlclRyYW5zSUQiOiI0ZjIwZWM4ZC1iOGFiLTQ1ZDAtYjVmZC0wMDdlNzYwNDcwYjEiLCJhY3NUcmFuc0lEIj
oiNTUyMGQxZDAtOGE2Yi00NGIzLTlhYmQtM2IyMDQ3NWFjODVkIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"directoryServerTransactionId": "d68cd64d-d42e-43f8-9ab0-f76d6b36f9f6",
"veresEnrolled": "Y",
"threeDSServerTransactionId": "4f20ec8d-b8ab-45d0-b5fd-007e760470b1",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwNmYzZTdhMy0xMjc1LTRmMjQ
tYmM1OS1lMDRhYmY5N2IzMzkiLCJpYXQiOjE2MzAwOTk0MzcsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRj
YmFjYSIsImV4cCI6MTYzMDEwMzAzNywiT3JnVW5pdElkIjoiNTk1YWRhYjAzM2ZhZGQyYzUwZTg5NDYxIiwiUG
F5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTW
VyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDS
nRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPa
UkwWmpJd1pXTTRaQzFpT0dGaUxUUTFaREF0WWpWbVpDMHdNRGRsTnpZd05EY3dZakVpTENKaFkzTlVjbUZ1YzB
sRUlqb2lOVFV5TUdReFpEQXRPR0UyWWkwME5HSXpMVGxoWW1RdE0ySXlNRFEzTldGak9EVmtJaXdpWTJoaGJHe
GxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiZ3JtT0xRcEZKZDZLalNxVj
JvdzAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly93djczMGh3NzAzMz
I1MDozMDAyL3Jlc3RhcGkvY2FyZGluYWxEaXJlY3QvU3RlcFVwL1Jlc3BvbnNlIn0.PcBsuaGonlmBNmugRLJ
JKQ2EsrsRzibPl9o4ljLGAkM",
"specicationVersion": "2.1.0",
"token": "AxjzbwSTVZPc53psJ3L9ADUBURxP1DuNpA6cQE1129JMvRiuHCKArAAAzAER",
"acsTransactionId": "5520d1d0-8a6b-44b3-9abd-3b20475ac85d"
},
"errorInformation": {
"reason": "CONSUMER_AUTHENTICATION_REQUIRED",
"message": "The cardholder is enrolled in Payer Authentication. Please authen ticate the cardholder
before continuing with the transaction."
},
"id": "6300994374466395403005",
"paymentInformation": {
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"status": "PENDING_AUTHENTICATION",
"submitTimeUtc": "2021-08-27T21:23:57Z"
}
Authorization with Validation
These are examples of Payer Authentication Authorization with Validation request and its
corresponding response.
Authorization with Payer Authentication Validation Request
POST /pts/v2/payments HTTP/1.1
{
"clientReferenceInformation": {
"code": "3DSHarness_PaValidateRestAPI"
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 39
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
"expirationMonth": "01",
"expirationYear": 2023
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"authenticationTransactionId": "grmOLQpFJd6KjSqV2ow0"
},
"processingInformation": {
"actionList": [
"VALIDATE_CONSUMER_AUTHENTICATION"
]
}
}
Authorization with Payer Authentication Validate Response
{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6300995545226652403001/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6300995545226652403001"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6300995545226652403001/captures"
}
},
"clientReferenceInformation": {
"code": "3DSHarness_PaValidateRestAPI"
},
"consumerAuthenticationInformation": {
"indicator": "vbv",
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 40
Implementing Cardinal Cruise Direct Connection API Payer Authentication
"eciRaw": "05",
"authenticationResult": "0",
"authenticationStatusMsg": "Success",
"eci": "05",
"token": "Axj/7wSTVZPhEEdJY8U5ADUg3btnLZu4YxKdJqzsT5yiOJ+ogvwFRHE/UQX
+kDpxATXhk0ky9GK4cIqCuTVZPhEEdJY8U5AAICFg",
"cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"paresStatus": "Y",
"xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"directoryServerTransactionId": "d68cd64d-d42e-43f8-9ab0-f76d6b36f9f6",
"threeDSServerTransactionId": "4f20ec8d-b8ab-45d0-b5fd-007e760470b1",
"specicationVersion": "2.1.0",
"acsTransactionId": "5520d1d0-8a6b-44b3-9abd-3b20475ac85d"
},
"id": "6300995545226652403001",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "100.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"pointOfSaleInformation": {
"terminalId": "123456"
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "77696781DSR53XON",
"status": "AUTHORIZED",
"submitTimeUtc": "2021-08-27T21:25:54Z"
}
Cybersource Implementing Cardinal Cruise Direct Connection API Payer Authentication 41
Implementing SDK Payer Authentication
Implementing SDK Payer
Authentication
This chapter summarizes the process of integrating SDK Payer Authentication services
into your mobile application. Payer authentication services use the Cardinal 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 Cardinal's distribution list to be
informed of updates and other product announcements. You can subscribe by going to
this link: https://win.cardinalcommerce.com/CardinalMobileSDKNotications
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 3-D Secure 2.x transactions. If a 3-D Secure 1.0
transaction occurs, you must include functionality to open up a WebView.
Implementation Overview
Notify your account representative that you want to implement payer authentication (3-
D Secure). Give the representative, the merchant ID that you will use for testing. For more
information, see Required Merchant Information on page 17.
Implementation tasks include:
• Download, import, and congure the Cardinal 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:
: Payer Authentication Validation
: Card Authorization service (optional)
• Use the test cases to test your preliminary code and make appropriate changes. See
Testing Payer Authentication on page 88.
Cybersource Implementing SDK Payer Authentication 42
Implementing SDK Payer Authentication
• Ensure that your account is congured for production.
Note that calling the Payer Authentication Setup Service is not required.
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 Cardinal Mobile SDK for either iOS or Android.
3. Set up your build environment.
4. Congure your SDK.
5. Setup the initial call to Cardinal.
6. Create an API call to your merchant server to request the Enrollment Check service,
passing in transaction details and the consumerAuthenticationInformation.referenceId
request eld.
7. If the issuing bank does not require authentication, you receive this information in the
Enrollment Check response:
• E-commerce indicator (consumerAuthenticationInfo rmation.ecommerceIndicator)
• CAVV (all card types except Mastercard) (consumerAuthenticationInfo rmation.cavv)
• AAV (Mastercard only) (consumerAuthenticationInfo rmation.ucaf CollectionI
ndicator)
• Transaction ID (consumerAuthenticationInfo rmation.xid )
• 3-D Secure version (consumerAuthenticationInfo rmation.specicationVersion)
• Directory server transaction ID (consumerAuthenticationInfo
rmation.directoryServerTrans actionId)
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 Cardinal 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 Java 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 consumerAuthenticationInformation.authenticationTransactionId request eld. 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 on page 57.
Cybersource Implementing SDK Payer Authentication 43
Implementing SDK Payer Authentication
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 elds 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 JSON Web Tokens (JWT) are
described in this section.
Credentials/API Keys
API keys are required to create the JSON Web Token (JWT). For further information,
contact customer supportcustomer 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
nab_merchant name_contact name
For example:
cybersource_petairways_peter
nab_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 Prole.
3. Enter your password and click Unlock.
4. Under Authentication Settings, click Generate API Key.
Using the Android SDK
A Cardinal Mobile SDK is available for integrating payer authentication services into mobile
applications running on the Android platform. Since this Android SDK only works with 3-D
Secure 2.x transactions, you must provide functionality to open a WebView to handle any
3-D Secure 1.0 transactions that occur.
Cybersource Implementing SDK Payer Authentication 44
Implementing SDK Payer Authentication
Update the Gradle Build Properties
In Android Studio, open the app directory (which can also be labeled Module: app) and
open the build.gradle le. Edit the Gradle le located in the app directory. Add the
contents shown in the example below to the Gradle le.
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 le.
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.**
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.**
Congure the Android SDK
Get the instance of the Cardinal object by Cardinal.getInstance(). Use the default
conguration options. See the example below to complete Cardinal.congure().
For more details on conguration, refer to the conguration options table after the
example.
private Cardinal cardinal = Cardinal.getInstance();
@Override
protected void onCreate(Bundle savedInstanceState) {
CardinalCongurationParameters cardinalCongurationParameters = new
CardinalCongurationParameters();
cardinalCongurationParameters.setEnvironment(CardinalEnvironment.STAGING);
cardinalCongurationParameters.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);
cardinalCongurationParameters.setRenderType(rType);
Cybersource Implementing SDK Payer Authentication 45
Implementing SDK Payer Authentication
cardinalCongurationParameters.setUiType(CardinalUiType.BOTH);
UiCustomization yourUICustomizationObject = new UiCustomization();
cardinalCongurationParameters.setUICustomization(yourUICustomizationObject);
cardinal.congure(this,cardinalCongurationParameters);
}
Method Description Default Values
setEnableDFSync (boolean On setting true, False
enableDFSync) onSetupCompleted is called
after the collected device
data is sent to the server.
setEnableQuickAuth Sets enable quick auth false. False
(boolean enableQuickAuth)
setEnvironment(Setting Sets the environment CardinalEnvironment.
up Cardinal Mobile to which the SDK must PRODUCTION
SDK - Android- V connect.
2.1#CardinalEnvironment
environment)
setProxyAddress(java.lang. Sets the proxy to which the ““
String proxyAddress) SDK must connect.
setRenderType(org.json. Sets renderLists all user JSONArray rType = new
JSONArray renderType) interface types that JSONArray();
the device supports for rType.put(Cardinal
displaying specic challenge RenderType.OTP);
user interfaces within the rType.put(Cardinal
SDK. 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 8000
time (in milliseconds) for all
exchanges.
setUICustomization Sets UICustomization Device Default Values
(UiCustomization UI
Customization)
Cybersource Implementing SDK Payer Authentication 46
Implementing SDK Payer Authentication
Method Description Default Values
setUiType(CardinalUiType Sets all user interface types CardinalUiType.BOTH
uiType) that the device supports for
displaying specic challenge
user interfaces within the
SDK.
Set Up the Initial Call
Calling Cardinal.init():
• begins the communication process with Cardinal
• authenticates your credentials (server JWT)
• 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, Cardinal assigns a unique identier to the
session called a consumerSessionId. This consumerSessionId ensures that Cardinal
matches the correct device data collection results to a request. Cybersource calls this
session identier, payerAuthEnrollService_referenceID. You must assign the value of
the consumerSessionId eld to the payerAuthEnrollService_referenceID eld so that
Cybersource can also track the calls for each user session.
Study the code example shown below for completing the cardinal.init().
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) {
}
});
See the Running Payer Authentication in SDK on page 52 section for the next steps.
Cybersource Implementing SDK Payer Authentication 47
Implementing SDK Payer Authentication
Using the iOS SDK
A Cardinal Mobile SDK is available for integrating payer authentication services into mobile
applications running on the iOS platform. Since this iOS SDK only works with 3-D Secure
2.x transactions, you must provide functionality to open a WebView to handle any 3-D
Secure 1.0 transactions that occur.
Download and Import the SDK
Download the CardinalMobile.framework le using cURL 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 le 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 le into the Frameworks group
in your Xcode Project. (Create the group if it doesn't 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 les are now available for linking in your project.
Set Up 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. Add CardinalMobile.framework from the list.
Cybersource Implementing SDK Payer Authentication 48
Implementing SDK Payer Authentication
Congure the iOS SDK
Create a new instance of the cardinal object by CardinalSession new. Use the default
conguration options. Study these examples to complete the iOS SDK conguration.
For more details on conguration 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];
CardinalSessionConguration *cong = [CardinalSessionConguration new];
cong.deploymentEnvironment = CardinalSessionEnvironmentProduction;
cong.timeout = CardinalSessionTimeoutStandard;
cong.uiType = CardinalSessionUITypeBoth;
UiCustomization *yourCustomUi = [[UiCustomization alloc] init];
//Set various customizations here. See "iOS UI Customization" documentation for detail.
cong.uiCustomization = yourCustomUi;
CardinalSessionRenderTypeArray *renderType = [[CardinalSessionRenderTypeArray alloc]
initWithObjects:
CardinalSessionRenderTypeOTP,
CardinalSessionRenderTypeHTML,
nil];
cong.renderType = renderType;
cong.enableQuickAuth = false;
[session congure:cong];
}
CardinalSession new (iOS SDK - Swift)
import CardinalMobile
var session : CardinalSession!
//Setup can be called in viewDidLoad
func setupCardinalSession{
session = CardinalSession()
var cong = CardinalSessionConguration()
cong.deploymentEnvironment = .production
cong.timeout = 8000
cong.uiType = .both
let yourCustomUi = UiCustomization()
//Set various customizations here. See "iOS UI Customization" documentation for detail.
cong.uiCustomization = yourCustomUi
cong.renderType = [CardinalSessionRenderTypeOTP, CardinalSessionRenderTypeHTML]
cong.enableQuickAuth = true
session.congure(cong)
Cybersource Implementing SDK Payer Authentication 49
Implementing SDK Payer Authentication
Method Description Default Values Possible Values
deploymentEnviron The environment CardinalSessionEnviron CardinalSessionEnvi
ment to which the SDK mentProduction ronment
connects. Staging
CardinalSessionEnvi
ronment
Production
timeoutInMilli Maximum amount 8000
seconds of time (in
milliseconds) for all
exchanges.
uiType Interface types CardinalSessionUITy CardinalSessionUIT
that the device peBoth ypeBoth
supports for CardinalSessionUIT
displaying specic ypeNative
challenge user CardinalSessionUIT
interfaces within ypeHTML
the SDK.
renderType List of all the [CardinalSessionRend CardinalSessionRen
render types erTypeOTP, derType
that the device CardinalSessionRend OTP
supports for erTypeHTML, CardinalSessionRen
displaying specic CardinalSessionRend derType
challenge user erTypeOOB, HTML
interfaces within CardinalSessionRend CardinalSessionRen
the SDK. erTypeSingleSelect, derType
CardinalSessionRend OOB
erTypeMultiSelect] CardinalSessionRen
derType
SingleSelect
CardinalSessionRen
derType
MultiSelect
proxyServerURL Proxy server nil
through which
the Cardinal SDK
Session operates.
enableQuickAuth Enable Quick false
Authentication
Cybersource Implementing SDK Payer Authentication 50
Implementing SDK Payer Authentication
Method Description Default Values Possible Values
uiCustomization Set Custom nil
UICustomization
for SDK-Controlled
Challenge UI.
enableDFSync Enable DF false
Sync to get
onSetupCompleted
called after
collected device
data is sent to the
server.
Set Up the Initial Call
Calling cardinal session setup begins the communication process with Cardinal,
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, Cardinal assigns a unique value to the
consumerSessionId API eld to identify the session. This consumerSessionId value
ensures that Cardinal matches the correct device data collection results to each user
request. Cybersource uses its payerAuthEnrollService_referenceID eld to contain
Cardinal's consumerSessionId value. You must assign the value of the consumerSessionId
eld to the payerAuthEnrollService_referenceID eld so that Cybersource can also track
the calls for each user session.
Study these code examples to understand how to complete the cardinal session setup.
The function call 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"
Cybersource Implementing SDK Payer Authentication 51
Implementing SDK Payer Authentication
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 in 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 veries that the card is enrolled in a card authentication
program. The merchant ID is included as part of the header but these elds are required in
the request:
• clientReferenceInformation.code
• consumerAuthenticationInformation.referenceId
• orderInformation.amountDetails.currency
• orderInformation.amountDetails.totalAmount
• orderInformation.billTo.address1
• orderInformation.billTo.administrativeArea
• orderInformation.billTo.country
• orderInformation.billTo.email
• orderInformation.billTo.rstName
• orderInformation.billTo.lastName
• orderInformation.billTo.locality
• orderInformation.billTo.postalCode
• paymentInformation.card.expirationMonth
• paymentInformation.card.expirationYear
• paymentInformation.card.number
• paymentInformation.card.type
Cybersource Implementing SDK Payer Authentication 52
Implementing SDK Payer Authentication
Important
To reduce your issuer step-up authentication rates, you can send additional
request data in order. It is best to send all available elds.
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 eld 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 elds) in the authorization service request (Card Authorization
request elds).
These elds are listed in this table.
Enrollment Check and Response Fields
Identier Enrollment Check Response Card Authorization Request
Field Field
E-commerce indicator consumerAuthenticationInfo processingInformation.com
rmation.ecommerceIndicator merceIndicator
Collection indicator consumerAuthenticationInfo consumerAuthenticationInfo
(Mastercard only) rmation.ucafCollectionIndi rmation.ucafCollectionIndi
cator cator
CAVV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.cavv rmation.cavv
AAV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.ucafAuthentication rmation.ucafAuthentication
Data Data
XID consumerAuthenticationInfo consumerAuthenticationInfo
rmation.xid and rmation.xid
Result of the enrollment consumerAuthenticationInfo consumerAuthenticationInfo
check for Asia, Middle East, rmation.veresEnrolled rmation.veresEnrolled
and Africa Gateway
3-D Secure version consumerAuthenticationInfo consumerAuthenticationInfo
rmation.specicationVersion rmation.paSpecicationVer
sion
Directory server transaction consumerAuthenticationInfo consumerAuthenticationInfo
ID rmation.directoryServerTran rmation.directoryServerTran
(Not required for 3-D sactionId sactionId
Secure 1.0.)
Cybersource Implementing SDK Payer Authentication 53
Implementing SDK Payer Authentication
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 ow, 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 StepUpUrl. 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, conrm that you receive these elds
and values:
• 3-D Secure version = 2.x
• VERes enrolled = Y
• PARes status = C
These values identify whether it is a 3-D Secure 2.x transaction and that a challenge is
required. If the 3-D Secure version is 1.0, then the SDK is no longer applicable and you
must open up a WebView.
Once you validate these elds, you call Cardinal.cca_continue (Android SDK) or Cardinal
session continue (iOS SDK) for the SDK to perform the challenge between the customer
and the issuing bank.
Call Cardinal.cca_continue (Android SDK)
When you have veried that a customer’s card is enrolled in a
card authentication program, you must take the payload, and the
consumerAuthenticationInformation.authenticationTransactionId response eld
and include them in the Cardinal.cca_continue function before proceeding with the
authentication session as shown in this example.
/**
* 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
Cybersource Implementing SDK Payer Authentication 54
Implementing SDK Payer Authentication
*/
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
}
Call Cardinal session continue (iOS SDK)
When you have veried that a customer’s card is enrolled in a card authentication
program, take the payload, and the response eld and include them in the Cardinal session
continue function before proceeding with the authentication session as shown in Example
22 .
In Continue, you should pass a class conforming to a protocol CardinalValidationDelegate
(and implement a method stepUpDidValidate) as a parameter. These examples show a class
conforming to 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.
Cybersource Implementing SDK Payer Authentication 55
Implementing SDK Payer Authentication
* 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 Continue is called in the same class, call the method shown in the following example to
start StepUpFlow.
Cardinal.continue Call 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 Continue is called in the same class, call the method shown in the example below to start
StepUpFlow.
Cardinal.continue Call in the Same Class (Swift)
session.continueWith(transactionId: "[TRANSACTION_ID]", payload: "[PAYLOAD]", validationDelegate: self)
Cybersource Implementing SDK Payer Authentication 56
Implementing SDK Payer Authentication
When necessary, the SDK displays the authentication window, and the customer enters
their authentication information.
Receiving the Authentication Results
Next onValidated() (Android SDK) or stepUpDidValidate (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 call to request
the validation service.
When you make the validation request, you must:
• Send the consumerAuthenticationInformation.authenticationTransactionId request
eld
• 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 this, automatically sends the correct information to your
payment processor and converts the values of these elds to the proper format required
by your payment processor:
• E-commerce indicator: consumerAuthenticationInformation.ecommerceIndicator
• CAVV: consumerAuthenticationInformation.cavv
• AAV: consumerAuthenticationInformation.ucafAuthenticationData
• XID: consumerAuthenticationInformation.xid and
consumerAuthenticationInformation.xid
Cybersource Implementing SDK Payer Authentication 57
Implementing SDK Payer Authentication
If you request the services separately, manually include the validation result values
(Validation Check response elds) in the authorization service request (Card
Authorization request elds). 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 may 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-specic information in your authorization request:
• For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo include
the CAVV (cardholder authentication verication value).
• For Mastercard, include the UCAF (universal cardholder authentication eld) and the
collection indicator.
Validation Check and Response Fields
Identier Validation Check Response Field Card Authorization Request
Field
E-commerce indicator consumerAuthenticationInforma processingInformation.com
tion.indicator merceIndicator
Collection indicator consumerAuthenticationInforma consumerAuthenticationInfo
(Mastercard only) tion.ucafCollectionIndicator rmation.ucafCollectionIndi
cator
CAVV (Visa and consumerAuthenticationInforma consumerAuthenticationInfo
American Express tion.cavvv rmation.cavv
only)
AAV (Mastercard only. consumerAuthenticationInforma consumerAuthenticationInfo
Known as UCAF) tion.ucafAuthenticationData rmation.ucafAuthentication
Data
XID consumerAuthenticationInforma consumerAuthenticationInfo
tion.xid rmation.xid
3-D Secure version consumerAuthenticationInforma consumerAuthenticationInfo
tion.specicationVersion rmation.paSpecicationVer
sion
Directory server consumerAuthenticationInforma consumerAuthenticationInfo
transaction ID tion.directoryServerTransactio rmation.directoryServerTran
(Not required for 3-D nId sactionId
Secure 1.0.)
Interpreting the Response
Important
Cybersource Implementing SDK Payer Authentication 58
Implementing SDK Payer Authentication
If the authentication fails, Visa, American Express, JCB, Diners Club, Discover,
China UnionPay, and Elo 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 AUTHENTICATION_SUCCESSFUL, and other service requests,
including authorization, are processed normally.
• Failure: You receive 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
supportcustomer 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.
Cybersource Implementing SDK Payer Authentication 59
Hybrid Payer Authentication
Hybrid Payer Authentication
If you are just getting started with payer authentication, use the Cardinal Direct
Connection API implementation method. It is the newest and most advanced method of
integrating 3-D Secure into your transaction process and is the method the majority of
our customers choose. The Hybrid implementation is still available when customer support
determines that it best ts your company's business needs.
The same prerequisites involving API keys and JSON Web Tokens necessary for the SDK
integration are also required for the Hybrid integration. In addition, you need to add
JavaScript to your checkout page and setup BIN detection as explained below. Complete
these prerequisites before continuing with your Hybrid implementation. Additional
information about conguring the Hybrid version of payer authentication is available at
Cardinal Cruise documentation.
Implementation Overview
Notify your account representative that you want to implement payer authentication (3-D
Secure). Give them the merchant ID that you will use for testing. For more information, see
Required Merchant Information.
Implementation tasks include:
• Add the JavaScript code to your checkout page
• For each purchase request
• Build the authentication request
• Call the Payer Authentication Setup service
• Allow device collection
• Handle declines
• Call Payer Authentication Enroll
• Call these services:
• Payer Authentication Validation (only for Hybrid integration)
• Card Authorization service (optional)
Cybersource Hybrid Payer Authentication 60
Hybrid Payer Authentication
• Use the test cases to test your preliminary code and make appropriate changes.
Change to the test environment by changing the URL in your JavaScript code. See
Testing Payer Authentication on page 88.
• Ensure that your account is congured for production.
Process Flow for Hybrid Integration
1. Call Setup service.
2. Add the JavaScript tag to your checkout page.
3. Call Cardinal.setup (init).
4. Run BIN detection. If the BIN is eligible for 3-D Secure 2.x, it gathers the proper Method
URL JavaScript required by the issuer to collect additional device data.
5. User selects the Submit Payment button.
6. You request the Enrollment Check service, passing in transaction details and the
request eld.
7. If the issuing bank does not require authentication, you receive this information in the
Enrollment Check response:
• E-commerce indicator
• CAVV (all card types except Mastercard)
• AAV (Mastercard only)
• Transaction ID
• 3-D Secure version
• Directory server transaction ID
8. If the issuing bank requires authentication, you receive a response with the ACS
URL of the issuing bank, the payload, and the transaction ID that you include in the
Cardinal.continue JavaScript call.
9. The JavaScript displays the authentication window, and the customer enters the
authentication information.
10.The bank validates the customer credentials, and a JWT is returned that the merchant is
required to validate server-side for security reasons.
11. You request the Validate Authentication service, extracting the processor transaction
ID value from the JWT and sending it in the request eld. 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.
Pass all pertinent data for the card type and processor in your authorization request. For
more information, see Requesting the Validation Service.
Payer Authentication Setup
Run the Payer Authentication Setup service on the server side before selecting the
button to submit payment. Request the Payer Authentication Setup service without
including other services.
Cybersource Hybrid Payer Authentication 61
Hybrid Payer Authentication
When requesting the Payer Authentication Setup service, you must send either the
customer’s card number, encrypted payment data, transient token, or a TMS token or
some other equivalent of card data used by your integration. The request elds may
include any of the following:
• paymentInformation.card.numberpaymentInformation.tokenizedCard.number
• paymentInformation.customer.customerId
• tokenInformation.transientToken
When the card type is Cartes Bancaires or UPI, the paymentInformation.card.type eld is
required.
Add the JavaScript
Add Songbird.js to your checkout page and complete the additional steps:
1. Congure it: create the conguration object and pass it to Cardinal.congure().
2. Listen for Events: subscribe to events with Cardinal.on() and set up callback functions
for:
• payments.setupComplete: this optional event triggers when the JavaScript
successfully initializes, after calling Cardinal.setup().
• payments.validated: this event triggers when the transaction completes.
3. Initialize it: call Cardinal.setup() to trigger and pass your JWT to the JavaScript for each
transaction.
To complete these steps, see the JavaScript Documentation.
BIN Detection
BIN detection is required and enables the card-issuing bank’s ACS provider to collect
additional device data. It speeds up the authentication process by collecting this
data before the checkout page launches. This step occurs before authentication. For
additional information, see the JavaScript Documentation.
Requesting the Check Enrollment Service
Request the Check Enrollment service to verify that the card is enrolled in a card
authentication program. These elds are required:
• orderInformation.amountDetails.totalAmount
• orderInformation.billTo.address1
• orderInformation.billTo.locality
• orderInformation.billTo.country
• orderInformation.billTo.administrativeArea
• orderInformation.billTo.postalCode
• paymentInformation.card.type
• orderInformation.amountDetails.currency
• paymentInformation.card.expirationMonth
• paymentInformation.card.expirationYear
Cybersource Hybrid Payer Authentication 62
Hybrid Payer Authentication
• orderInformation.billTo.email
• orderInformation.billTo.rstName
• orderInformation.billTo.lastName
• consumerAuthenticationInformation.referenceId
• clientReferenceInformation.code
To reduce your issuer step-up authentication rates, you can send additional request data
in order. Send all available elds.
You can use the enrollment check and card authorization services in the same request or
in separate requests:
• Same request: Cybersource attempts to authorize the card when your customer is
not enrolled in a payer authentication program. In this case, the eld values 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 elds) in the authorization service request (Card Authorization
request elds).
This table lists these elds.
Enrollment Check and Response Fields
Identier Enrollment Check Response Card Authorization Request
Field Field
E-commerce indicator consumerAuthenticationInfo processingInformation.com
rmation.ecommerceIndicator merceIndicator
Collection indicator consumerAuthenticationInfo consumerAuthenticationInfo
(Mastercard only) rmation.ucafCollectionIndi rmation.ucafCollectionIndi
cator cator
CAVV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.cavv rmation.cavv
AAV consumerAuthenticationInfo consumerAuthenticationInfo
rmation.ucafAuthenticationD rmation.ucafAuthentication
ata Data
XID consumerAuthenticationInfo consumerAuthenticationInfo
rmation.xid and rmation.xid
Result of the enrollment consumerAuthenticationInfo consumerAuthenticationInfo
check for Asia, Middle East, rmation.veresEnrolled rmation.veresEnrolled
and Africa Gateway
3-D Secure version consumerAuthenticationInfo consumerAuthenticationInfo
rmation.specicationVersion rmation.paSpecicationVer
sion
Cybersource Hybrid Payer Authentication 63
Hybrid Payer Authentication
Identier Enrollment Check Response Card Authorization Request
Field Field
Directory server transaction consumerAuthenticationInfo consumerAuthenticationInfo
ID rmation.directoryServerTran rmation.directoryServerTran
(Not required for 3-D sactionId sactionId
Secure 1.0.)
Interpreting the Response
After you receive this response, you can proceed to card authorization.
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 ow, 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 StepUpUrl. Challenge the cardholder and
display an authentication challenge window to the cardholder so the cardholder can
send a validation request and receive a validation response.
Authenticating Enrolled Cards
When you have veried that a customer’s card is enrolled in a card
authentication program, you must include the URL of the card-
issuing bank’s Access Control Server (ACS), the payload, and the
consumerAuthenticationInformation.authenticationTransactionId response eld in the
Cardinal.continue function in order to proceed with the authentication session as shown
in this example.
Cardinal.continue
Cardinal.continue('cca',
{
"AcsUrl":"https://testcustomer34.cardinalcommerce.com/merchantacsfrontend/pareq.jsp?
vaa=b&gold=AAAAAAAA...AAAAAAA",
"Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGOcz/
se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ=="
},
{
"OrderDetails":{
"TransactionId" :"123456abc"
}
}
);
Cybersource Hybrid Payer Authentication 64
Hybrid Payer Authentication
Cardinal.continue displays the authentication window if necessary and automatically
redirects the customer’s session over to the ACS URL for authentication. The customer’s
browser displays the authentication window with the option to enter their password.
Receiving the Authentication Results
Next, payments.validated 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 request the validation service. When you make the
validation request, you must:
• Send the consumerAuthenticationInformation.authenticationTransactionId request
eld
• Send the credit card information including the PAN, currency, and expiration date
(month and year).
The response that you receive contains the validation result.
You should request the payer authentication and card authorization services at the same
time. Requesting both services simultaneously ensures that the correct information
is automatically sent to your payment processor and the values of these elds are
converted to the proper format required by your payment processor:
• E-commerce indicator: consumerAuthenticationInformation.indicator
• CAVV: consumerAuthenticationInformation.cavv
• AAV: consumerAuthenticationInformation.ucafAuthenticationData
• XID: consumerAuthenticationInformation.xid and
If you request the services separately, manually include the validation result values
(Validation Check response elds) in the authorization service request (Card
Authorization request elds). To receive liability shift protection, ensure that you pass
all pertinent data for the card type and processor in your request. Failure to do so may
Cybersource Hybrid Payer Authentication 65
Hybrid Payer Authentication
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 the following card-specic information in your authorization request:
• For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo include
the CAVV (cardholder authentication verication value).
• For Mastercard, include the UCAF (universal cardholder authentication eld) and the
collection indicator.
This table lists these elds.
Identier Validation Check Response Card Authorization Request
Field Field
E-commerce indicator consumerAuthenticationInfo processingInformation.eCom
rmation.indicator merceIndicator
Collection indicator consumerAuthenticationInfo consumerAuthenticationInfo
(Mastercard only) rmation.ucafCollectionIndi rmation.ucafCollectionIndi
cator cator
CAVV (Visa and American consumerAuthenticationInfo consumerAuthenticationInfo
Express only) rmation.cavv rmation.cavv
(Mastercard only. Known as consumerAuthenticationInfo consumerAuthenticationInfo
UCAF) rmation.ucafAuthentication rmation.ucafAuthentication
Data Data
XID consumerAuthenticationInfo consumerAuthenticationInfo
rmation.xid rmation.xid
3-D Secure version consumerAuthenticationInfo consumerAuthenticationInfo
rmation.specicationVersion rmation.paSpecicationVer
sion
Directory server transaction consumerAuthenticationInfo consumerAuthenticationInfo
ID rmation.directoryServerTran rmation.directoryServerTran
(Not required for 3-D sactionId sactionId
Secure 1.0.)
Interpreting the Response
Important
If a TransStatus R is returned, do not authorize the transaction. Ask the customer
to use another payment method.
Proceed with the order according to the validation response that you receive. The
responses are similar for all card types:
• Success: You receive a status of AUTHENTICATION_SUCCESSFUL, and other service
requests, including authorization, are processed normally.
Cybersource Hybrid Payer Authentication 66
Hybrid Payer Authentication
• Failure: You receive a status of 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
supportcustomer 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 Pass or Fail 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 unenrolled cards. For
example, if the authentication fails, a message such as this should be displayed to the
customer:
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card or form of payment to
complete your purchase.
Hybrid Integration Examples
These examples show a request and response for the check enrollment service and a
request and response for the validate authentication service.
Check Enrollment
This is a Payer Authentication Check Enrollment request example and its corresponding
response using the Hybrid implementation.
Check Enrollment Request
URL: https://apitest.cybersource.com/risk/v1/authentications
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.99"
}
},
"paymentInformation": {
"card": {
"expirationMonth": "12",
"expirationYear": "2025",
"number": "4000000000000101"
}
}
}
Cybersource Hybrid Payer Authentication 67
Hybrid Payer Authentication
Check Enrollment Response
{
"clientReferenceInformation": {
"code": "1674501852837"
},
"consumerAuthenticationInformation": {
"eciRaw": "06",
"authenticationTransactionId": "HvhMt5mTLb53bv3m1nm0",
"strongAuthentication": {
"OutageExemptionIndicator": "0"
},
"eci": "06",
"proofXml": "<AuthProof> <Time>2023 Jan 23 19:24:12</Time> <DSUrl>https://
merchantacsstag.cardinalcommerce.com/MerchantACSWeb/vereq.jsp?acqid=CYBS</
DSUrl> <VEReqProof> <Message id=\"HvhMt5mTLb53bv3m1nm0\"> <VEReq>
<version>1.0.2</version> <pan>XXXXXXXXXXXX0101</pan> <Merchant> <acqBIN>469216</
acqBIN> <merID>341422420000000</merID> <password> </password> </Merchant>
<Browser> <deviceCategory>0</deviceCategory> </Browser> </VEReq> </Message>
</VEReqProof> <VEResProof> <Message id=\"HvhMt5mTLb53bv3m1nm0\"> <VERes>
<version>1.0.2</version> <CH> <enrolled>Y</enrolled> <acctID>6158139</acctID> </CH>
<url>https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?
visaattempts=true&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
url> <protocol>ThreeDSecure</protocol> </VERes> </Message> </VEResProof> </
AuthProof>",
"token": "AxjzbwSTbaXvlhKYr2O5ABEBURyq20gRpAuJZefDJpJl6MVzMKYAwAAA5AL6",
"cavv": "BwAQAgJ4IAUFBwdik3ggEETHTsU=",
"paresStatus": "A",
"xid": "SHZoTXQ1bVRMYjUzYnYzbTFubTA=",
"cavvAlgorithm": "2",
"veresEnrolled": "Y",
"authenticationPath": "ATTEMPTS_COMPLETE",
"ecommerceIndicator": "vbv_attempted",
"specicationVersion": "1.0.2"
},
"id": "6745018527446293504953",
"paymentInformation": {
"card": {
"bin": "400000",
"type": "VISA"
}
},
"status": "AUTHENTICATION_SUCCESSFUL",
"submitTimeUtc": "2023-01-23T19:24:12Z"
}
Cybersource Hybrid Payer Authentication 68
Hybrid Payer Authentication
Check Enrollment Request
URL: https://apitest.cybersource.com/pts/v2/payments
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
"expirationMonth": "01",
"expirationYear": 2023
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"referenceId": "e704b4a3-14c8-4302-a5cc-ca6e7d0bd0a8",
"transactionMode": "S"
}
}
Check Enrollment Response
{
"consumerAuthenticationInformation": {
"acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"challengeRequired": "N",
"stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
"authenticationTransactionId": "DZZRorz8NoEtsaiYZgb0",
"pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1Nlcn
ZlclRyYW5zSUQiOiJhNDM2MjExYS05YmQwLTRhZjMtYmYwYi03MWE5NWQ3N2ExYzkiLCJhY3NUcmFuc0lEIjoiYzkx
OGJlNGQtN2RiNy00MzRlLThhMDktMmZjZTc1NTNmYjZmIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"directoryServerTransactionId": "5daecf27-b846-4bff-969c-966e48f65bc7",
"veresEnrolled": "Y",
"threeDSServerTransactionId": "a436211a-9bd0-4af3-bf0b-71a95d77a1c9",
"specicationVersion": "2.1.0",
"token": "AxjzbwSTVZPqZk18lbibADUBURxP1E9bpA6cQE1129JMvRiuHCKArAAAhACX",
Cybersource Hybrid Payer Authentication 69
Hybrid Payer Authentication
"acsTransactionId": "c918be4d-7db7-434e-8a09-2fce7553fb6f"
},
"errorInformation": {
"reason": "CONSUMER_AUTHENTICATION_REQUIRED",
"message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder
before continuing with the transaction."
},
"id": "6300998173086071503003",
"paymentInformation": {
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"status": "PENDING_AUTHENTICATION",
"submitTimeUtc": "2022-08-27T21:30:17Z"
}
Validate
This is a Payer Authentication Validate request example and its corresponding response
using the Hybrid implementation.
Prod URL: https://api.cybersource.com/pts/v2/payments
Validate Request
{
"orderInformation": {
"billTo": {
"rstName": "John",
"lastName": "Doe",
"address2": "Address 2",
"address1": "1 Market St",
"postalCode": "94105",
"locality": "san francisco",
"administrativeArea": "CA",
"country": "US",
"phoneNumber": "4158880000",
"company": "Visa",
"email": [email protected]
},
"amountDetails": {
"totalAmount": "10.99",
"currency": "USD"
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"paymentInformation": {
"card": {
"expirationMonth": "12",
"expirationYear": "2025",
"number": "4000000000000101"
}
},
Cybersource Hybrid Payer Authentication 70
Hybrid Payer Authentication
"consumerAuthenticationInformation": {
"transactionMode": "MOTO"
}
}
Validate Response
{
"consumerAuthenticationInformation": {
"eciRaw": "06",
"authenticationTransactionId": "Vg5ftsTvuwCfSt43NJm0",
"strongAuthentication": {
"OutageExemptionIndicator": "0"
},
"eci": "06",
"proofXml": "<AuthProof><Time>2022 Dec 20 19:41:33</Time><DSUrl>https://
merchantacsstag.cardinalcommerce.com/MerchantACSWeb/vereq.jsp?acqid=CYBS</
DSUrl><VEReqProof><Message id=\"Vg5ftsTvuwCfSt43NJm0\"><VEReq><version>1.0.2</
version><pan>XXXXXXXXXXXX0101</pan><Merchant><acqBIN>469216</acqBIN><merID>341422420000000</
merID><password></password></Merchant><Browser><deviceCategory>0</
deviceCategory></Browser></VEReq></Message></VEReqProof><VEResProof><Message id=
\"Vg5ftsTvuwCfSt43NJm0\"><VERes><version>1.0.2</version><CH><enrolled>Y</enrolled><acctID>6158139</
acctID></CH><url>https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?
visaattempts=true&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
url><protocol>ThreeDSecure</protocol></VERes></Message></VEResProof></AuthProof>",
"token": "AxjzbwSTbA5oEUqDRvAzABEBT9u4dzfHSBcSyTKGTSTL0YrmYUwBgAAAmhUF",
"cavv": "BwAQAgJ4IAUFBwdik3ggEETHTsU=",
"paresStatus": "A",
"xid": "Vmc1ZnRzVHZ1d0NmU3Q0M05KbTA=",
"cavvAlgorithm": "2",
"veresEnrolled": "Y",
"authenticationPath": "ATTEMPTS_COMPLETE",
"ecommerceIndicator": "vbv_attempted",
"specicationVersion": "1.0.2"
},
"id": "6715652941556113403955",
"paymentInformation": {
"card": {
"bin": "400000",
"type": "VISA"
}
},
"status": "AUTHENTICATION_SUCCESSFUL",
"submitTimeUtc": "2022-12-20T19:41:34Z"
}
Enrollment and Authorization
This is a Payer Authentication Check Enrollment and Authorization request example and its
corresponding response using the Hybrid implementation.
Check Enrollment and Authorization Request Example
URL: https://apitest.cybersource.com/pts/v2/payments
Cybersource Hybrid Payer Authentication 71
Hybrid Payer Authentication
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
"expirationMonth": "08",
"expirationYear": 2023
}
},
"buyerInformation": {
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"referenceId": "d5180465-bae3-4df7-940d-3b029b7de81a",
"transactionMode": "S"
},
"processingInformation": {
"actionList": [
"CONSUMER_AUTHENTICATION"
]
}
}
Check Enrollment and Authorization Response
{
"consumerAuthenticationInformation": {
"acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"challengeRequired": "N",
"stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
"authenticationTransactionId": "3HHi4FeT0wsWSd1D5fv0",
"pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlcl
RyYW5zSUQiOiI0NDllNjg2Zi00MjdkLTQ2NTktYWYxZS0wZGY3OTk1MWMyNWIiLCJhY3NUcmFuc0lEIjoiYzg3OGU
zMmEtNjk1Yi00MGNkLTg3ZTUtNWExM2U5OTAxY2JiIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"directoryServerTransactionId": "91706faf-1f43-4e8a-aa99-8bced446caac",
"veresEnrolled": "Y",
"threeDSServerTransactionId": "449e686f-427d-4659-af1e-0df79951c25b",
"specicationVersion": "2.1.0",
"token": "AxjzbwSTVZPyZCW03H3+ADUBURxP1FqDpA6cQE1129JMvRiuHCKArAAAxf+Y",
Cybersource Hybrid Payer Authentication 72
Hybrid Payer Authentication
"acsTransactionId": "c878e32a-695b-40cd-87e5-5a13e9901cbb"
},
"errorInformation": {
"reason": "CONSUMER_AUTHENTICATION_REQUIRED",
"message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder
before continuing with the transaction."
},
"id": "6301000422516007403006",
"paymentInformation": {
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"status": "PENDING_AUTHENTICATION",
"submitTimeUtc": "2022-08-27T21:34:02Z"
}
Validation and Authorization Request
This is a Payer Authentication Validation and Authorization request example and its
corresponding response using the Hybrid implementation.
Validate and Authorization Request
Test URL: https://apitest.cybersource.com/pts/v2/payments
Prod URL: https://api.cybersource.com/pts/v2/payments
{
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "100"
},
"billTo": {
"address1": "901 metro center blvd",
"address2": "metro 3",
"administrativeArea": "CA",
"country": "US",
"locality": "san francisco",
"rstName": "John",
"lastName": "Doe",
"phoneNumber": "18007097779",
"postalCode": "94404",
"email": "[email protected]"
}
},
"paymentInformation": {
"card": {
"number": "4XXXXXXXXXXXXXXX",
"type": "001",
"expirationMonth": "01",
"expirationYear": 2023
}
},
"buyerInformation": {
Cybersource Hybrid Payer Authentication 73
Hybrid Payer Authentication
"mobilePhone": "1245789632"
},
"consumerAuthenticationInformation": {
"authenticationTransactionId": "3HHi4FeT0wsWSd1D5fv0"
},
"processingInformation": {
"actionList": [
"VALIDATE_CONSUMER_AUTHENTICATION"
]
}
}
Validate and Authorization Response
{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6301001634966060103004/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6301001634966060103004"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6301001634966060103004/captures"
}
},
"clientReferenceInformation": {
"code": "3DSHarness_PaValidateRestAPI"
},
"consumerAuthenticationInformation": {
"indicator": "vbv",
"eciRaw": "05",
"authenticationResult": "0",
"authenticationStatusMsg": "Success",
"eci": "05",
"token": "Axj/7wSTVZP2st07j3VcADUg3btnLZw1YsKdJq0bQaqiOJ+owWAFRHE/
UYLGkDpxATXhk0ky9GK4cIqCuTVZP2st07j3VcAA+TgB",
"cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"paresStatus": "Y",
"xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"directoryServerTransactionId": "91706faf-1f43-4e8a-aa99-8bced446caac",
"threeDSServerTransactionId": "449e686f-427d-4659-af1e-0df79951c25b",
"specicationVersion": "2.1.0",
"acsTransactionId": "c878e32a-695b-40cd-87e5-5a13e9901cbb"
},
"id": "6301001634966060103004",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "100.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
Cybersource Hybrid Payer Authentication 74
Hybrid Payer Authentication
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"bin": "4XXXXXXX",
"type": "VISA"
}
},
"pointOfSaleInformation": {
"terminalId": "123456"
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "776968510SR546AU",
"status": "AUTHORIZED",
"submitTimeUtc": "2021-08-27T21:36:03Z"
}
This is an example of an Payer Authentication Validation and Authorization request and
its corresponding response using Google Pay as the digital payment option. The Google
Pay developer guide has additional information and code samples. There is a Google Pay
developer guide available for each processor.
When requesting an authorization for a Google Pay transaction, be sure to:
• Set the paymentInformation.uidData.value eld to the string value generated from the
full wallet response.
• Set the paymentInformation.tokenizedCard.request eld to your token requestor ID.
• Set the processingInformation.paymentSolution eld to 012.
Cybersource Hybrid Payer Authentication 75
API Fields
API Fields
This section describes the REST API elds that you can use to access Payer
Authentication services.
The API and client toolkits can be downloaded from the website at the following
URL:https://developer.cybersource.com/api-reference-assets/index.html.
Formatting Restrictions
Do not use the following characters: < > $ % ^ * _ = [ ] \ { } | ; ~ ` Using these characters
may result in data validation errors.
Required Fields for Setting Up Payer
Authentication
These elds are the minimum elds required when requesting the Payer Authentication
Setup service. Other elds to collect additional information during a transaction are
available in the list of optional elds. Some of the optional elds may be required in certain
circumstances.
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
Related information
API Field Reference for the REST API
Cybersource API Fields 76
API Fields
Optional Fields for Setting Up Payer Authentication
While these elds are optional when requesting the Payer Authentication Setup service,
in certain transaction circumstances, an optional eld may be required. The circumstance
when an optional eld becomes required is noted.
clientReferenceInformation.code
merchantID
orderInformation.billTo.administrativeArea Required for U.S., Canada, and Mainland
China.
orderInformation.billTo.locality
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderInformation.billTo.postalCode Required when the
orderInformation.billTo.country eld is US or
CA.
orderInformation.billTo.address1
paymentInformation.card.type This eld is required when the card type is
Cartes Bancaires or UPI.
paymentInformation.uidData.value
payerAuthSetupService_run
paymentInformation.customer.customerId
paymentInformation.uidData.descriptor
tokenInformation.transientToken
Required Fields for Checking Enrollment in
Payer Authentication
These elds are the minimum elds required when requesting the Payer
Authentication Check Enrollment service. Other elds to collect additional
information during a transaction are available in the list of optional elds.
Some of the optional elds may be required in certain circumstances.
orderInformation.amountDetails.currency
orderInformation.amountDetails.total Optional when you use the
Amount orderInformation.lineItems.unitPrice eld.
Cybersource API Fields 77
API Fields
orderinformation.billTo.administrativeArea Required for U.S., Canada, and Mainland
China. For Mainland China, use the ISO
3166-2 format.
paymentInformation.card.expirationMonth Required when
paymentInformation.card.number is
included.
paymentInformation.card.expirationYear Required when
paymentInformation.card.number is
included.
paymentInformation.card.number
Related information
API Field Reference for the REST API
Optional Fields for Enrolling in Payer Authentication
While these elds are optional when checking if the card holder is enrolled in a Payer
Authentication program, in certain circumstances, additional information on the card
holder may be required before the transaction can proceed. The circumstance when an
optional eld is required is noted.
The elds that are marked with an asterisk are browser-related elds. The information
collected by these browser-related elds are useful during 3-D Secure transactions.
merchantInformation.merchantDescriptor. Required for Visa Secure travel.
name
acquirerInformation.acquirerBin
acquirerInformation.country
acquirerInformation.merchantId
billTo_passportCountry Recommended for Discover ProtectBuy.
billTo_passportNumber Recommended for Discover ProtectBuy.
buyerInformation.mobilePhone
buyerInformation.workPhone
clientReferenceInformation.code
consumerAuthenticationInformation.acsWin
dowSize
consumerAuthenticationInformation.alter
nateAuthenticationData
consumerAuthenticationInformation.alter
nateAuthenticationDate
Cybersource API Fields 78
API Fields
consumerAuthenticationInformation.alter
nateAuthenticationMethod
consumerAuthenticationInformation.auth Required for Standard integration.
enticationTransactionId
consumerAuthenticationInformation.chal This eld defaults to 01 on your account
lengeCode but is overridden by the merchant when you
include this eld. EMV 3D Secure version
2.1.0 supports values 01-04. Version 2.2.0
supports values 01-09.
Warning
Modifying this eld could affect
liability shifts down the payment
chain. Unless you are very
familiar with the various types of
authentication, do not change the
default settings before consulting
with customer support.
consumerAuthenticationInformation.creden
tialEncrypted
consumerAuthenticationInformation.cus Required when tokenization is enabled in
tomerCCAlias the merchant prole settings.
consumerAuthenticationInformation.sdkMax Required for 3-D Secure 2.x.
Timeout
consumerAuthenticationInformation.decoup
ledAuthenticationIndicator
consumerAuthenticationInformation.decoup
ledAuthenticationMaxTime
consumerAuthenticationInformation.default Recommended for Discover ProtectBuy.
Card
*consumerAuthenticationInformation.device Required for SDK integration. When you
Channel use the SDK integration, this eld is
dynamically set to SDK. When you use the
JavaScript code, this eld is dynamically
set to Browser. For merchant-initiated or
3RI transactions, you must set the eld to
3RI. When you use this eld in addition to
JavaScript code, you must set the eld to
Browser.
Cybersource API Fields 79
API Fields
consumerAuthenticationInformation.market Recommended for Discover ProtectBuy.
ingOptIn
consumerAuthenticationInformation.market Recommended for Discover ProtectBuy.
ingSource
consumerAuthenticationInformation.mcc Required when the card type is Cartes
Bancaires.
consumerAuthenticationInformation.merch
antFraudRate
consumerAuthenticationInformation.merch Required for transactions processed in
antScore France.
consumerAuthenticationInformation.merch
antURL
consumerAuthenticationInformation.mess
ageCategory
consumerAuthenticationInformation.otpTo
ken
consumerAuthenticationInformation.over
rideCountryCode
consumerAuthenticationInformation.over
ridePaymentMethod
consumerAuthenticationInformation.pay Recommended for Discover ProtectBuy.
mentAccountDate
consumerAuthenticationInformation.pre
order
consumerAuthenticationInformation.pre
orderDate
consumerAuthenticationInformation.prior
AuthenticationData
consumerAuthenticationInformation.prior
AuthenticationMethod
consumerAuthenticationInformation.prior
AuthenticationReferenceId
consumerAuthenticationInformation.prior
AuthenticationTime
consumerAuthenticationInformation.productRequired for American Express SafeKey
Code (U.S.) when the product code is AIR (Airline
purchase).
consumerAuthenticationInformation.reque
storName
Cybersource API Fields 80
API Fields
consumerAuthenticationInformation.refer Required for Hybrid or Cardinal Cruise
enceID Direct Connection API integration.
consumerAuthenticationInformation.returnURL
consumerAuthenticationInformation.trans
actionMode
consumerAuthenticationInformation.score
Request
consumerAuthenticationInformation.sdkMax
Timeout
consumerAuthenticationInformation.strong
Authentication.authenticationIndicator
*deviceInformation.httpAcceptBrowserValueWhen the customer’s browser provides a
value, you must include that value in your
request.
*deviceInformation.httpAcceptContent
*deviceInformation.httpBrowserColorDepth
*deviceInformation.httpBrowserJavaEnabled
*deviceInformation.httpBrowserJavaScript
Enabled
*deviceInformation.httpBrowserLanguage
*deviceInformation.httpBrowserScreenHeight
*deviceInformation.httpBrowserScreenWidth
*deviceInformation.httpBrowserTimeDiffer
ence
*deviceInformation.ipAddress
*deviceInformation.userAgentBrowserValue When the customer’s browser provides a
value, you must include that value in your
request.
merchantDenedData_mddField_1 to Important: These elds override the
merchantDenedData_mddField_5 old merchant-dened data elds. For
example, when you use the obsolete eld
merchantDenedData_eld5 and the new
eld merchantDenedData_mddField_5
in the same request, the new eld value
overwrites the value specied in the
obsolete eld.
Warning
Cybersource API Fields 81
API Fields
Merchant-dened data elds
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 dened data elds.
Personally identifying information
includes, but is not limited to,
address, credit card number, Social
Security number, driver's license
number, state-issued identication
number, passport number, and card
verication numbers (CVV, CVC2,
CVV2, CID, CVN). When a merchant
is discovered capturing and/or
transmitting personally identifying
information via the merchant-
dened data elds, 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.
merchantInformation.merchantDescriptor. Required for Visa Secure travel.
name
orderInformation.amountDetails.currency
orderInformation.billTo.address2
orderinformation.billTo.country
orderinformation.billTo.email
orderInformation.billTo.rstName
orderInformation.billTo.lastName
orderinformation.billTo.locality Required for U.S., Canada, and Mainland
China.
orderInformation.billTo.phoneNumber
orderinformation.billTo.postalCode Required when the
orderInformation.shipTo.country eld is US
or CA.
Cybersource API Fields 82
API Fields
orderInformation.lineItems.passenger.rst
Name
orderInformation.lineItems.passenger.last
Name
orderInformation.lineItems.productDescrip
tion
orderInformation.lineItems.productName
orderInformation.lineItems.productSku
orderInformation.lineItems.quantity
orderInformation.lineItems.shippingAddress1
orderInformation.lineItems.shippingAddress2
orderInformation.lineItems.shippingCity
orderInformation.lineItems.shippingCountry
Code
orderInformation.lineItems.shippingDestina
tionTypes
orderInformation.lineItems.shippingLast
Name
orderInformation.lineItems.shippingMiddle
Name
orderInformation.lineItems.shippingPhone
orderInformation.lineItems.shippingPostal
Code
orderInformation.lineItems.shippingState
orderInformation.lineItems.unitPrice
orderInformation.lineItems[i].giftCardCur
rency
orderInformation.lineItems[i].quantity
orderInformation.lineItems[i].totalAmount
orderInformation.lineItems.shippingDestina
tionTypes
orderInformation.preOrderDate
orderInformation.reordered
orderInformation.shipTo.addess1 Required when any shipping address
information is included. Required only for
American Express SafeKey (U.S.).
Cybersource API Fields 83
API Fields
orderInformation.shipTo.address2 Required only for American Express SafeKey
(U.S.).
orderInformation.shipTo.address3
orderInformation.shipTo.administrativeArea Required when the
orderInformation.shipTo.country eld
value is CA, US, or China. Required only for
American Express SafeKey (U.S.).
orderInformation.shipTo.country Required only for American Express SafeKey
(U.S.).
orderInformation.shipTo.destinationCode
orderInformation.shipTo.email
orderInformation.shipTo.rstName
orderInformation.shipTo.lastName
orderInformation.shipTo.middleName
orderInformation.shipTo.locality
orderInformation.shipTo.method
orderInformation.shipTo.postalCode Required if the
orderInformation.shipTo.country eld value
is US or CA. Required for American Express
SafeKey (U.S.).
payerAuthEnrollService_accountPurchases Recommended for Discover ProtectBuy.
payerAuthEnrollService_fraudActivity Recommended for Discover ProtectBuy.
payerAuthEnrollService_giftCardAmount
payerAuthEnrollService_giftCardCount
payerAuthEnrollService_giftCardCurrency
payerAuthEnrollService_merchantNewCust
omer
payerAuthEnrollService_priorAuthentica
tionTime
payerAuthEnrollService_productCode Required for American Express SafeKey
(U.S.).
payerAuthEnrollService_recurringOrigin When this eld is empty, the current date is
alPurchaseDate used.
payerAuthEnrollService_reorder
payerAuthEnrollService_requestorInitia EMV 3D Secure version 2.1.0 supports
tedAuthenticationIndicator values 01-05. Version 2.2.0 supports values
01-11.
Cybersource API Fields 84
API Fields
payerAuthEnrollService_secureCorporate
PaymentIndicator
payerAuthEnrollService_shipAddressUsage Recommended for Discover ProtectBuy.
Date
payerAuthEnrollService_totalOffersCount
payerAuthEnrollService_transactionCount Recommended for Discover ProtectBuy.
Day
payerAuthEnrollService_transactionCount Recommended for Discover ProtectBuy.
Year
payerAuthEnrollService_transactionMode
payerAuthEnrollService_whiteListStatus
paymentInformation.card.type
paymentInformation.card.securityCode
paymentInformation.uidData.value
riskInformation.buyerHistory.accountPur
chases
riskInformation.buyerHistory.addCard Recommended for Discover ProtectBuy.
Attempts
riskInformation.buyerHistory.customer Recommended for Discover ProtectBuy.
Account.createDate
riskInformation.buyerHistory.customerAcco Recommended for Discover ProtectBuy.
unt.lastChangeDate
riskInformation.buyerHistory.customerAc Recommended for Discover ProtectBuy.
count.passwordChangeDate
riskInformation.buyerHistory.customerAc
count.shipAddressUsageDate
riskInformation.buyerHistory.paymentAc
countDate
riskInformation.buyerHistory.priorSuspic
iousActivity
riskInformation.buyerHistory.transaction
CountDay
riskInformation.buyerHistory.transaction
CountYear
shipTo_destinationCode
shipTo_rstName
shipTo_lastName
Cybersource API Fields 85
API Fields
shipTo_phoneNumber
travelInformation.legs.departureDate
travelInformation.legs.origination
travelInformation.numberOfPassengers
travelInformation.passengers.rstName
travelInformation.passengers.lastName
Required Fields for Validating Payer
Authentication
These elds are required when requesting the Payer Authentication Validation service:
authenticationTransactionID
clientReferenceInformation.code
merchantID
paymentInformation.card.number
paymentInformation.card.type
paymentInformation.card.expiration Month Required when
paymentInformation.card.number is
included.
paymentInformation.card.expiration Year Required when
paymentInformation.card.number is
included.
orderInformation.amountDetails.cur rency
orderInformation.amountDetails.total Optional when the
Amount orderInformation.lineItems.unitPrice eld is
used.
orderInformation.lineItems.unitPrice Optional when the
orderInformation.amountDetails.totalAmount
eld is used.
Related information
API Field Reference for the REST API
Optional Fields for Validating Payer Authentication
These elds are optional when requesting the Payer Authentication Validation service:
Cybersource API Fields 86
API Fields
consumerAuthenticationInformation.authen Required for Hybrid integration.
ticationTransactionId
consumerAuthenticationInformation.creden
tialEncrypted
consumerAuthenticationInformation.respon Required for Hybrid integration when you
seAccessToken use the generated access token.
consumerAuthenticationInformation.signedPares
Cybersource API Fields 87
Testing Payer Authentication
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 specic input data and the most important results elds
that you receive in the API response.
Testing Process
Use the card number specied in the test with the card’s expiration date set to the month
of December and the current year plus three. For example, for 2023, use 2026. You also
need the minimum required elds for an order.
Enrollment Check
For some of the enrolled cards, an authentication window appears after the enrollment
check completes.
To view the authentication window, you must enable your browser to display popup
windows.
The test password is 1234.
Depending on the user’s action, two results are possible:
• If the user submits the correct password for the enrolled card, authentication is
successful.
• If the user clicks the Exit link and clicks OK in the verication window, authentication
does not occur.
The following table lists the response elds used in the test cases.
Cybersource Testing Payer Authentication 88
Testing Payer Authentication
Response Fields Used in the Enrollment Check Test Cases
Name Used in Test Cases API Field
ACS URL consumerAuthenticationInformation. acsUrl
E-commerce indicator consumerAuthenticationInformation.
ecommerceIndicator
ECI consumerAuthenticationInformation. eci
PAReq consumerAuthenticationInformation. pareq
proofXML consumerAuthenticationInformation.
proofXml
VERes enrolled consumerAuthenticationInformation.
veresEnrolled
XID consumerAuthenticationInformation. xid
Enrollment Check Response Fields
Name Used in Test Cases API Field
ACS URL consumerAuthenticationInformation.
acsUrll
E-commerce indicator consumerAuthenticationInformation.
ecommerceIndicator
ECI consumerAuthenticationInformation. eci
PAReq consumerAuthenticationInformation. pareq
proofXML consumerAuthenticationInformation.
proofXml
VERes enrolled consumerAuthenticationInformation.
veresEnrolled
XID consumerAuthenticationInformation. xid
Authentication Validation Test Case Fields
The following table lists only the response elds used in the test cases.
Response Fields Used in the Authentication Validation Test Cases
Name Used in Test Cases API Field
Authentication result consumerAuthenticationInformation.auth
enticationResult
Cybersource Testing Payer Authentication 89
Testing Payer Authentication
Name Used in Test Cases API Field
E-commerce indicator consumerAuthenticationInformation.in
dicator
AAV (Mastercard only) consumerAuthenticationInformation.ucafAu
thenticationDat
CAVV ((all card types except Mastercard) consumerAuthenticationInformation.cavv
Collection indicator consumerAuthenticationInformation.ucafCol
lectionIndicator
ECI consumerAuthenticationInformation.eci
PARes status consumerAuthenticationInformation.pares
Status
Status status
XID consumerAuthenticationInformation.xid
3-D Secure 1.0 Testing
The following test cases can be used to test 3-D Secure 1.0 authentication for each
supported processor.
Important
In most countries, card network support for 3-D Secure 1.0 was discontinued in
October 2022 as 3-D Secure 2.0 superseded the older 1.0 version. Most countries
should now use the 3-D Secure 2.0 test cases when conguring responses to
various transaction scenarios. The 3-D Secure 1.0 test cases in this section are
no longer relevant and should not be used by most merchants. Merchants in some
South Asian countries are allowed to continue to use the 3-D Secure 1.0 protocol
until October 2023. Contact customer supportcustomer support for further
information.
Visa Secure 3-D Secure 1.0 Test Cases
These test cases can be used to test 3-D Secure authentication with Visa.
Visa Secure Test Cases for 3-D Secure 1.0
You can use Payer Authentication services with 16- and 19-digit Visa cards if they are
supported by your processor.
Remove spaces in card numbers when testing.
Possible Values for Visa Secure Response Fields
Result and Interpretation Validate Authentication Response
Cybersource Testing Payer Authentication 90
Testing Payer Authentication
Authentica ECI Commerce Status
tion Result Indicator
Success Successful 0 05 vbv AUTHENTICA
authentication. TION_SUCCES
SFUL
Recorded attempt 1 06 vbv_attemp AUTHENTICA
to authenticate. ted TION_SUCCES
SFUL
2
Failure System error 6 1 — AUTHENTICA
(Customer that prevents the TION_SUCCES
not completion of SFUL
responsible) authentication:
you can
proceed with
authorization, but
there is no liability
shift.
Issuer unable 6 07 internet AUTHENTICA
to perform TION_SUCCES
authentication. SFUL
No response from 07 internet
the Directory vbv_failure
Servers or Issuer (processors:
because of a AIBMS,
problem. Barclays,
Streamline,
or FDC
Germany)
Invalid PARes. -1 — — AUTHENTICA
TION_FAILED
Cybersource Testing Payer Authentication 91
Testing Payer Authentication
Failure Authentication 9 — — AUTHENTICA
(Customer failed or TION_FAILED
responsible) cardholder did
not complete
authentication.
If the
authentication
fails, Visa
suggests that you
do not accept the
card. You must
ask the customer
to use another
payment method.
1. The ECI value can vary depending on the reason for the failure.
2. A dash (—) indicates that the eld is blank or absent.
Test Case 1: Visa Secure Card Enrolled: Successful Authentication
Card Number 445653 With authentication window
00 0000 0007 With 19-digit PAN
445653
00 0000 0000 025
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The cardholder is enrolled in payer Authentication is validated.
authentication. Please authenticate
before proceeding with authorization.
Details ACS URL URL Authentica 0
tion result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E- vbv
commerce
indicator
VERes enrolled Y ECI 05
XID XID value PARes Y
status
Cybersource Testing Payer Authentication 92
Testing Payer Authentication
XID XID value
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from the
authentication validation.
3. Add the CAVV and ECI values to your authorization request.
Test Case 2: Visa Secure Card Enrolled: Successful Authentication but Invalid PARes
Card Number 445653 With authentication window
00 0000 0015
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: PARes
authenticate before proceeding signature digest value mismatch.
with authorization. PARes message has been modied.
Details ACS URL URL value Authentication -1
result
PAReq PAReq value XID XID value
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Do not proceed with authorization. Instead, ask the customer for
another form of payment.
Test Case 4: Visa Secure Card Enrolled: Incomplete Authentication
Card Number 445653
00 0000 0031
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
Cybersource Testing Payer Authentication 93
Testing Payer Authentication
The cardholder is enrolled in • Issuer unable to perform
payer authentication. Please authentication.
authenticate before proceeding • Authentication is validated.
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value E-commerce internet or
indicator vbv_failure
proofXML proofXML value ECI 07
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 5: Visa Secure Card Enrolled: Unsuccessful Authentication
Card Number 445653 With authentication window
00 0000 0023
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • User failed authentication.
payer authentication. Please • Payer cannot be authenticated.
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value XID XID value
VERes enrolled Y
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 6: Visa Secure Card Enrolled: Unsuccessful Authentication (Customer Exited)
Card Number 445653
00 0000 0023
Cybersource Testing Payer Authentication 94
Testing Payer Authentication
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • Customer prevents
payer authentication. Please authentication.
authenticate before proceeding • Authentication is validated.
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value XID XID value
VERes enrolled Y
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 7: Visa Secure Card Enrolled: Unavailable Authentication
Card Number 445653
00 0000 0064
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet or
indicator vbv_failure
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.
Cybersource Testing Payer Authentication 95
Testing Payer Authentication
Test Case 8: Visa Secure Card Enrolled: Authentication Error
Card Number 445653
00 0000 0098
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value E-commerce internet or
indicator vbv_failure
PAReq PAReq value ECI 07
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.
Test Case 10: Visa Secure Enrollment Check: Time-Out
Card Number 445653
00 0000 0049
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCESSFUL
iThe cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet or
indicator vbv_failure
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No
liability shift.
Cybersource Testing Payer Authentication 96
Testing Payer Authentication
Test Case 11: Visa Secure Enrollment Check Error
Card Number 445653 Error response
00 0000 0080
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet or
indicator vbv_failure
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you requested
payer authentication and authorization together, the authorization is
processed automatically.
Mastercard Identity Check 3-D Secure 1.0 Test Cases
The following test cases can be used to test 3-D Secure authentication with Mastercard.
Mastercard Identity Check Test Cases for 3-D Secure 1.0
Possible Values for Mastercard Identity Check Response Fields
Result and Interpretation Validate Authentication Response
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 2 spa AUTHENTICA
authentication. TION_SUCCES
SFUL
Recorded 1 1 spa AUTHENTICA
attempt to TION_SUCCES
authenticate. SFUL
Authentication 1 0 spa AUTHENTICA
not completed. TION_SUCCES
SFUL
Cybersource Testing Payer Authentication 97
Testing Payer Authentication
Failure System error 6 0 internet AUTHENTICA
(Customer (Issuer unable TION_SUCCES
not to perform SFUL
responsible) authentication):
you cannot
authorize this
card; no liability
shift.
Invalid PARes. -1 0 AUTHENTICA
TION_FAILED
Failure Authentication 9 0 – AUTHENTICA
(Customer failed or TION_FAILED
responsible) cardholder did
not complete
authentication.
Test Case 16: Mastercard Identity Check Card Enrolled: Successful Authentication
Card Number 520000 With authentication window
00 0000 0007 Without authentication window
520000
00 0000 0114
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The card is enrolled in payer Cardholder is authenticated.
authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 0
result
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection 2
indicator
VERes enrolled Y E-commerce spa
indicator
XID XID value PARes status Y
XID XID value
Cybersource Testing Payer Authentication 98
Testing Payer Authentication
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the required payer authentication values to your authorization
request.
Test Case 17: Mastercard Identity Check Card Enrolled: Successful Authentication but
Invalid PARes
Card Number 520000 With authentication window
00 0000 0015
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in Payer authentication problem:
payer authentication. Please PARes signature digest value
authenticate before proceeding mismatch. PARes message has
with authorization. been modied.
Details ACS URL URL Authentication -1
result
PAReq PAReq value XID XID value
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Do not process the authorization request. Instead ask the customer
for another form of payment.
Test Case 19: Mastercard Identity Check Card Enrolled: Incomplete Authentication
Card Number 520000 Without authentication window
00 0000 0031
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
Cybersource Testing Payer Authentication 99
Testing Payer Authentication
The cardholder is enrolled in • Cardholder is authenticated.
payer authentication. Please • Issuer unable to perform
authenticate before proceeding authentication.
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value Collection 0
indicator
proofXML proofXML value E-commerce internet
indicator
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 20: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
Card Number 520000 With authentication window
00 0000 0023
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • User failed authentication
payer authentication. Please • Payer could not be
authenticate before proceeding authenticated.
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value Collection 0
indicator
VERes enrolled Y XID XID value
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Cybersource Testing Payer Authentication 100
Testing Payer Authentication
Test Case 21: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
(Customer Exited)
Card Number 564182
10 0001 0028
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • Customer prevents
payer authentication. Please authentication.
authenticate before proceeding • Cardholder is authenticated.
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value XID XID value
VERes enrolled Y Collection 0
Indicator
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 22: Mastercard Identity Check Card Enrolled: Unavailable Authentication
Card Number 520000
00 0000 0064
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
Cardholder is authenticated.
Details Collection 0
indicator
E-commerce internet
indicator
proofXML proofXML value
Cybersource Testing Payer Authentication 101
Testing Payer Authentication
VERes enrolled U
Action Submit the transaction. No liability shift.
Test Case 23: Mastercard Identity Check Card Enrolled: Authentication Error
Card Number 520000 Without authentication window
00 0000 0098
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value Collection 0
indicator
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.
Test Case 24: Mastercard Identity Check Enrollment Check Time-Out
Card Number 520000
00 0000 0049
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Cybersource Testing Payer Authentication 102
Testing Payer Authentication
Details Collection 0
indicator
E-commerce internet
indicator
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization message. No
liability shift.
Test Case 25: Mastercard Identity Check Enrollment Check Error
Card Number 520000
00 0000 0080
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details Collection 0
indicator
E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you requested
payer authentication and authorization together, the authorization is
processed automatically.
Maestro 3-D Secure 1.0 Test Cases
The following test cases can be used test 3-D Secure authentication with Maestro.
Cybersource Testing Payer Authentication 103
Testing Payer Authentication
Maestro Test Cases for 3-D Secure 1.0
Possible Values for Maestro Response Fields
Result and Interpretation Validate Authentication Response
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 2 spa AUTHENTICA
authentication. TION_SUCCES
SFUL
Recorded 1 1 spa AUTHENTICA
attempt to TION_SUCCES
authenticate. SFUL
Authentication 1 0 spa AUTHENTICA
not completed. TION_SUCCES
SFUL
Failure System error 6 0 internet AUTHENTICA
(Customer (Issuer unable TION_SUCCES
not to perform SFUL
responsible) authentication):
you cannot
authorize this
card; no liability
shift.
Invalid PARes. -1 0
Failure Authentication 9 0 –
(Customer failed or
responsible) cardholder did
not complete
authentication.
Test Case 30: Maestro Card Enrolled: Successful Authentication
Card Number 675941 Without authentication window
11 0000 0008 With authentication window
675941
00 0000 6404
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Cybersource Testing Payer Authentication 104
Testing Payer Authentication
Summary Status Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 0
result
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection 2
indicator
VERes enrolled Y E-commerce spa
indicator
XID XID value PARes status Y
XID XID value
Action 1. Add the signed PARes to the validation request.
2. In the response, ensure that the XID from the enrollment check
matches that from the validation.
3. Add the required payer authentication values to your authorization
request.
Test Case 31: Maestro Card Enrolled: Successful Authentication but Invalid PARes
Card Number 633110 Without authentication window
12 3456 7892
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status Status
The cardholder is enrolled in Payer authentication problem:
payer authentication. Please PARes signature digest value
authenticate before proceeding mismatch. PARes message has
with authorization. been modied.
Details ACS URL URL Authentication -1
result
PAReq PAReq value XID XID value
proofXML proofXML value
VERes enrolled Y
Cybersource Testing Payer Authentication 105
Testing Payer Authentication
XID XID value
Action Do not process the authorization request. Instead ask the customer
for another form of payment.
Test Case 32: Maestro Card Enrolled: Attempts Processing - Deprecated This test case is
no longer used.
Card Number 560000 Card enrollment option during purchase process
00 0000 00
0193
Auth. Type Maestro stand in attempts service
Results Check Enrollment Validate Authentication
Summary Status Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 1
result
PAReq PAReq value AAV AAV value
proofXML proofXML value E-commerce spa
indicator
VERes enrolled Y PARes status A
XID XID value XID XID value
Action This test card enables you to reproduce the process by which the
customer enrolls the card during the purchase. If the card is not
enrolled, a card enrollment option windows appears in the customer’s
browser after the enrollment check. The customer can activate the
card at that time or later. In both cases, the card is authenticated, and
validation is successful.
1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the required payer authentication values to your authorization
request.
Cybersource Testing Payer Authentication 106
Testing Payer Authentication
Test Case 33: Maestro Card Enrolled: Incomplete Authentication
Card Number 633110 Without authentication window
12 5035 3227
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Issuer unable to perform
payer authentication. Please authentication.
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value Collection 0
indicator
proofXML proofXML value E-commerce spa
indicator
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 34: Maestro Card Enrolled: Unsuccessful Authentication
Card Number 633110 Without authentication window
06 1019 4313
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status Status
The cardholder is enrolled in User failed authentication
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
Cybersource Testing Payer Authentication 107
Testing Payer Authentication
proofXML proofXML value XID XID value
VERes enrolled Y Collection 0
Indicator
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 35: Maestro Card Enrolled: Unavailable Authentication
Card Number 633110
02 6697 7839
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details Collection 0
indicator
E-commerce spa
indicator
proofXML proofXML value
Action Submit the transaction. No liability shift.
Test Case 36: Maestro Card Enrolled: Authentication Error
Card Number 560000 Without authentication window
51 1607 57 7094
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status 475 Status
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Cybersource Testing Payer Authentication 108
Testing Payer Authentication
Details ACS URL URL value Collection 0
indicator
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Do not request authorization. Instead ask the customer for another
form of payment. No liability shift.
Test Case 37: Maestro Enrollment Check Error
Card Number 560000
84 1211 09 2515
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details Collection 0
indicator
E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you requested
payer authentication and authorization together, the authorization is
processed automatically.
American Express SafeKey 3-D Secure 1.0 Test Cases
The following test cases can be used to test 3-D Secure authentication with American
Express.
Cybersource Testing Payer Authentication 109
Testing Payer Authentication
American Express SafeKey Test Cases for 3-D Secure 1.0
Possible Values for American Express SafeKey Response Fields
Result and Interpretation Validate Authentication Response
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 05 aesk AUTHENTICA
authentication. TION_SUCCES
SFUL
Recorded 1 06 aesk_ AUTHENTICA
attempt to attempted TION_SUCCES
authenticate. SFUL
2
Failure System error 6 1 — AUTHENTICA
(Customer that prevents the TION_SUCCES
not completion of SFUL
responsible) authentication:
you can
proceed with
authorization,
but there is no
liability shift.
Issuer unable 6 07 internet AUTHENTICA
to perform TION_SUCCES
authentication. SFUL
Incomplete 07 internet
or unavailable
authentication.
Invalid PARes. -1 — — AUTHENTICA
TION_FAILED
Cybersource Testing Payer Authentication 110
Testing Payer Authentication
Result and Interpretation Validate Authentication Response
Failure Authentication 9 — — AUTHENTICA
(Customer failed or TION_SUCCES
responsible) cardholder did SFUL
not complete
authentication.
If the
authentication
fails, Visa
requires that you
do not accept
the card. You
must ask the
customer to use
another payment
method.
1. The ECI value can vary depending on the reason for the failure.
2. A dash (—) indicates that the eld is blank or absent.
Test Case 38: American Express SafeKey Card Enrolled: Successful Authentication
Card Number 340000 Without authentication window
00 0003 961 With authentication window
371449
11 1020 228
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 0
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce aesk
indicator
VERes enrolled Y ECI 05
Cybersource Testing Payer Authentication 111
Testing Payer Authentication
XID XID value PARes status Y
XID XID value
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
Test Case 39: American Express SafeKey Card Enrolled: Successful Authentication but
Invalid PARes
Card Number 340000
00 0006 022
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: PARes
authenticate before proceeding signature digest value mismatch.
with authorization. PARes message has been modied.
Details ACS URL URL value Authentication -1
result
PAReq PAReq value XID XID value
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Do not proceed with authorization. Instead, ask the customer for
another form of payment.
Test Case 41: American Express SafeKey Card Enrolled: Incomplete Authentication
Card Number 340000 Without authentication window
00 0002 302
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Cybersource Testing Payer Authentication 112
Testing Payer Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value ECI 07
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 42: American Express SafeKey Card Enrolled: Unsuccessful Authentication
Card Number 340000 Without authentication window
00 0000 033
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • User failed authentication.
payer authentication. Please • Payer cannot be authenticated.
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value ECI 07
VERes enrolled Y XID XID value
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Cybersource Testing Payer Authentication 113
Testing Payer Authentication
Test Case 43: American Express SafeKey Card Enrolled: Unavailable Authentication
Card Number 340000
00 0007 780
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.
Test Case 44: American Express SafeKey Card Enrolled: Authentication Error
Card Number 340000
00 0009 299
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value ECI 07
PAReq PAReq value E-commerce internet
Indicator
proofXML proofXML value
VERes enrolled Y
XID XID value
Cybersource Testing Payer Authentication 114
Testing Payer Authentication
Action Ask the customer for another form of payment. No liability shift.
Test Case 45: American Express SafeKey Card Not Enrolled
Card Number 340000
00 0008 135
Auth. Type Non-
participating
bank
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.
Test Case 46: American Express SafeKey Enrollment Check: Time-Out
Card Number 340000
00 0008 309
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
Cybersource Testing Payer Authentication 115
Testing Payer Authentication
ECI 07
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No
liability shift.
Test Case 47: American Express SafeKey Enrollment Check Error
Card Number 340000
00 0007 244
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICA
TION_SUCCES
SFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. If you requested payer
authentication and authorization together, the authorization is
processed automatically. No liability shift.
JCB J/Secure 3-D Secure 1.0 Test Cases
The following test cases can be used to test 3-D Secure authentication with JCB.
JCB J/Secure Test Cases for 3-D Secure 1.0
Possible Values for JCB J/Secure Response Fields
Result and Interpretation Validate Authentication Response_
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 05 js AUTHENTICA
authentication. TION_SUCCES
SFUL
Cybersource Testing Payer Authentication 116
Testing Payer Authentication
Result and Interpretation Validate Authentication Response_
Recorded 1 06 js_attempted AUTHENTICA
attempt to TION_SUCCES
authenticate SFUL
1 2
Failure System error 6 —
(Customer that prevents the
not completion of
responsible) authentication:
you can
proceed with
authorization,
but no liability
shift.
Issuer unable 6 07 internet AUTHENTICA
to perform TION_SUCCESS
authentication FUL
Incomplete 07 internet
or unavailable js_failure
authentication.
Invalid PARes. -1 00 AUTHENTICA
TION_FAILED
Failure Authentication 9 — — AUTHENTICA
(Customer failed or TION_FAILED
responsible) cardholder did
not complete
authentication.
If the
authentication
fails, Visa
requires that you
do not accept
the card. You
must ask the
customer to use
another payment
method.
1 The ECI value can vary depending on the reason for the failure.
2 A dash (—) indicates that the eld is blank or absent.
Test Case 48: JCB J/Secure Card Enrolled: Successful Authentication
Card Number 356999 Without authentication window
00 1008 3722
Cybersource Testing Payer Authentication 117
Testing Payer Authentication
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_SUCCESSFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 0
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce js
indicator
VERes enrolled Y ECI 05
XID XID value PARes status Y
XID XID value
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
Test Case 49: JCB J/Secure Card Enrolled: Successful Authentication but Invalid PARes
Card Number 356999 Without authentication window
00 1008 3748
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status Status
The cardholder is enrolled in Payer authentication problem:
payer authentication. Please PARes signature digest value
authenticate before proceeding mismatch. PARes message has
with authorization. been modied.
Details ACS URL URL Authentication -1
result
PAReq PAReq value XID XID value
VERes enrolled Y
Cybersource Testing Payer Authentication 118
Testing Payer Authentication
Action Do not process the authorization request. Instead ask the customer
for another form of payment.
Test Case 50: JCB J/Secure Card Enrolled: Attempted Authentication
Card Number 356996
00 1008 3758
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 1
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce js_attempted
indicator
VERes enrolled Y ECI 06
XID XID value PARes status A
XID XID value
Action If you request Validate Authentication and authorization services
separately, follow these steps:
1. Add the signed PARes to the validation request.
2. In the response, ensure that the XID from the enrollment check
matches that from the validation.
3. Add the CAVV and ECI values to your authorization request.
If you request the Validate Authentication and authorization services
together, the process described above occurs automatically.
Test Case 51: JCB J/Secure Card Enrolled: Incomplete Authentication (Unavailable)
Card Number 354159 Without authentication window
99 9810 3643
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Cybersource Testing Payer Authentication 119
Testing Payer Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_SUCCES
SFUL
The cardholder is enrolled in • Issuer unable to perform
payer authentication. Please authentication.
authenticate before proceeding • Cardholder is authenticated.
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value ECI 07
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 52: JCB J/Secure Card Enrolled: Failed Authentication
Card Number 356999 Without authentication window
01 1008 3721
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in • User failed authentication.
payer authentication. Please • Payer cannot be authenticated.
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value XID XID value
VERes enrolled Y ECI 07
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Cybersource Testing Payer Authentication 120
Testing Payer Authentication
Test Case 53: JCB J/Secure Card Enrolled: Unavailable Authentication
Card Number 354159
99 9910 3865
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.
Test Case 54: JCB J/Secure Card Enrolled: Authentication Error Processing PARes
Card Number 354159
99 9910 3881
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICA
ENTICATION TION_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value ECI 07
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.
Cybersource Testing Payer Authentication 121
Testing Payer Authentication
Test Case 55: JCB J/Secure Card Not Enrolled
Card Number 356997
00 1008 3724
Auth. Type Non-
participating
bank
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce js_attempted
indicator
ECI 06
proofXML proofXML value
VERes enrolled N
Action Submit your authorization request.
Test Case 56: JCB J/Secure Enrollment Check: Time-Out
Card Number 356998
00 1008 3723
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No
liability shift.
Cybersource Testing Payer Authentication 122
Testing Payer Authentication
Test Case 57: JCB J/Secure Enrollment Check: Lookup Error Processing Message Request
Card Number 354159
99 6910 3614
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you requested
payer authentication and authorization together, the authorization is
processed automatically.
Diners Club Protect Buy 3-D Secure 1.0 Test Cases
The following test cases can be used to test 3-D Secure authentication with Diners Club.
Diners Club Protect Buy Test Cases for 3-D Secure 1.0
Possible Values for Diners Club ProtectBuy Response Fields
Result and Interpretation Validate Authentication Response
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 05 pb AUTHENTICATI
authentication. ON_SUCCESS
FUL
Recorded 1 06 pb_attemptedAUTHENTICATI
attempt to ON_SUCCESS
authenticate. FUL
Cybersource Testing Payer Authentication 123
Testing Payer Authentication
Result and Interpretation Validate Authentication Response
1 2
Failure System error 6 — AUTHENTICATI
(Customer that prevents the ON_SUCCESS
not completion of FUL
responsible) authentication:
you can
proceed with
authorization,
but there is no
liability shift.
Issuer unable 6 07 internet AUTHENTICATI
to perform ON_SUCCESS
authentication. FUL
Incomplete 07 internet
or unavailable
authentication.
Invalid PARes. -1 — — AUTHENTICATI
ON_FAILED
Failure Authentication 9 — — AUTHENTICATI
(Customer failed or ON_FAILED
responsible) cardholder did
not complete
authentication.
If the
authentication
fails, Visa
requires that you
do not accept
the card. You
must ask the
customer to use
another payment
method.
1. The ECI value can vary depending on the reason for the failure.
2. A dash (—) indicates that the eld is blank or absent.
Test Case 58: Diners Club ProtectBuy Card Enrolled: Successful Authentication
Card Number 300500
00 0000 6246
Auth. Type Active
authentication
Cybersource Testing Payer Authentication 124
Testing Payer Authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATI
ENTICATION ON_SUCCESS
FUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 0
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce pb
indicator
VERes enrolled Y ECI 05
XID XID value PARes status Y
XID XID value
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
Test Case 59: Diners Club ProtectBuy Card Enrolled: Successful Authentication but Invalid
PARes
Card Number 300500
00 0000 4373
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AU Status AUTHENTICATI
THENTICATI ON_FAILED
ON
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem:
authenticate before proceeding PARes signature digest value
with authorization. mismatch. PARes message has
been modied.
Details ACS URL URL value Authentication-1
result
Cybersource Testing Payer Authentication 125
Testing Payer Authentication
PAReq PAReq value XID XID value
proofXML proofXML
value
VERes enrolled Y
XID XID value
Action Do not proceed with authorization. Instead, ask the customer for
another form of payment.
Test Case 60: Diners Club ProtectBuy Card Enrolled: Attempts Processing
Card Number 300500 Card enrollment option during purchase process
00 0000 5271
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATI
ENTICATION ON_SUCCESSFU
L
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 1
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce pb_attempted
indicator
VERes enrolled Y ECI 06
XID XID value PARes status A
XID XID value
Action If you request Validate Authentication and authorization services
separately, follow these steps:
1. Add the signed PARes to the validation request.
2. Ensure that the XID from the enrollment check matches that
from the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
If you request the Validate Authentication and authorization
services together, the process described above occurs
automatically.
Cybersource Testing Payer Authentication 126
Testing Payer Authentication
Test Case 61: Diners Club ProtectBuy Card Enrolled: Incomplete Authentication
Card Number 300500
00 0000 7376
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATI
ENTICATION ON_SUCCESS
FUL
The cardholder is enrolled • Issuer unable to perform
in payer authentication. authentication.
Authenticate before proceeding • Cardholder is authenticated.
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value ECI 07
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 62: Diners Club ProtectBuy Card Enrolled: Unsuccessful Authentication
Card Number 300500
00 0000 5925
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATI
ENTICATION ON_FAILED
The cardholder is enrolled in • User failed authentication.
payer authentication. Please • Payer cannot be
authenticate before proceeding authenticated.
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
Cybersource Testing Payer Authentication 127
Testing Payer Authentication
proofXML proofXML value XID XID value
VERes enrolled Y
XID XID value ECI 07
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 63: Diners Club ProtectBuy Card Enrolled: Unavailable Authentication
Card Number 300500
00 0000 6030
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.
Test Case 64: Diners Club ProtectBuy Card Enrolled: Authentication Error
Card Number 300500
00 0000 5602
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATI
ENTICATION ON_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value E-commerce internet
indicator
Cybersource Testing Payer Authentication 128
Testing Payer Authentication
PAReq PAReq value ECI 07
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.
Test Case 65: Diners Club ProtectBuy Card Not Enrolled
Card Number 300500
00 0000 7269
Auth. Type Non-
participating
bank
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.
Test Case 66: Diners Club ProtectBuy Enrollment Check: Time-Out
Card Number 300500
00 0000 1890
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
Cybersource Testing Payer Authentication 129
Testing Payer Authentication
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No
liability shift.
Test Case 67: Diners Club ProtectBuy Enrollment Check Error
Card Number 300500 Error response
00 0000 9877 Incorrect Conguration: Unable to Authenticate
300500
00 0000 4837
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATI
ON_SUCCESSFUL
The cardholder is enrolled
in Payer Authentication.
Authenticate the cardholder
before continuing with the
transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you
requested payer authentication and authorization together, the
authorization is processed automatically.
Discover Protect Buy 3-D Secure 1.0 Test Cases
The following test cases can be used to test 3-D Secure authentication with Discover.
Cybersource Testing Payer Authentication 130
Testing Payer Authentication
Discover Protect Buy Test Cases for 3-D Secure 1.0
Possible Values for Discover ProtectBuy Response Fields
Result and Interpretation Validate Authentication Response
Authentication ECI Commerce Status
Result Indicator
Success Successful 0 05 dipb AUTHENTICATI
authentication. ON_SUCCESS
FUL
Recorded 1 06 dipb_ AUTHENTICATI
attempt to attempted ON_SUCCESS
authenticate. FUL
1 2
Failure System error 6 — AUTHENTICATI
(Customer that prevents the ON_SUCCESS
not completion of FUL
responsible) authentication:
you can
proceed with
authorization,
but there is no
liability shift.
Issuer unable 6 07 internet AUTHENTICATI
to perform ON_SUCCESS
authentication. FUL
Incomplete 07 internet
or unavailable
authentication.
Invalid PARes. -1 — — AUTHENTICATI
ON_FAILED
Cybersource Testing Payer Authentication 131
Testing Payer Authentication
Result and Interpretation Validate Authentication Response
Failure Authentication 9 — — AUTHENTICATI
(Customer failed or ON_FAILED
responsible) cardholder did
not complete
authentication.
If the
authentication
fails, Visa
requires that you
do not accept
the card. You
must ask the
customer to use
another payment
method.
1 The ECI value can vary depending on the reason for the failure.
2 A dash (—) indicates that the eld is blank or absent.
Test Case 68: Discover ProtectBuy Card Enrolled: Successful Authentication
Card Number 601100
00 0000 0004
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_SUCCESSFUL
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL Authentication 0
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce dipb
indicator
VERes enrolled Y ECI 05
XID XID value PARes status Y
XID XID value
Cybersource Testing Payer Authentication 132
Testing Payer Authentication
Action 1. Add the signed PARes to the Validate Authentication request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
Test Case 69: Discover ProtectBuy Card Enrolled: Successful Authentication but Invalid
PARes
Card Number 601100
00 0000 0012
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: PARes
authenticate before proceeding signature digest value mismatch.
with authorization. PARes message has been modied.
Details ACS URL URL value Authentication -1
result
PAReq PAReq value XID XID value
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Do not proceed with authorization. Instead, ask the customer for
another form of payment.
Test Case 70: Discover ProtectBuy Card Enrolled: Attempts Processing - Deprecated This
test case is no longer used.
Card Number 601100 Card enrollment option during purchase process
00 0000 0038
Auth. Type Discover stand in attempts service
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_SUCCESSFUL
Cybersource Testing Payer Authentication 133
Testing Payer Authentication
The cardholder is enrolled in Cardholder is authenticated.
payer authentication. Please
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 1
result
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce dipb_attempted
indicator
VERes enrolled Y ECI 06
XID XID value PARes status A
XID XID value
Action If you request Validate Authentication and authorization services
separately, follow these steps:
1. Add the signed PARes to the validation request.
2. Ensure that the XID from the enrollment check matches that from
the authentication validation.
3. Add the CAVV and ECI values to your authorization request.
If you request the Validate Authentication and authorization services
together, the process described above occurs automatically.
Test Case 71: Discover ProtectBuy Card Enrolled: Incomplete Authentication
Card Number 601100
00 0000 0103
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_SUCCESSFUL
The cardholder is enrolled in • Issuer unable to perform
payer authentication. Please authentication.
authenticate before proceeding • Cardholder is authenticated.
with authorization.
Details ACS URL URL value Authentication 6
result
PAReq PAReq value E-commerce internet
indicator
proofXML proofXML value ECI 07
Cybersource Testing Payer Authentication 134
Testing Payer Authentication
VERes enrolled Y PARes status U
XID XID value XID XID value
Action Ask the customer for another form of payment, or submit the
transaction. No liability shift.
Test Case 72: Discover ProtectBuy Card Enrolled: Unsuccessful Authentication
Card Number 601100
00 0000 0020
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_FAILED
The cardholder is enrolled in • User failed authentication.
payer authentication. Please • Payer cannot be authenticated.
authenticate before proceeding
with authorization.
Details ACS URL URL value Authentication 9
result
PAReq PAReq value PARes status N
proofXML proofXML value XID XID value
VERes enrolled Y
XID XID value
Action You are not permitted to submit this transaction for authorization.
Instead ask the customer for another form of payment.
Test Case 73: Discover ProtectBuy Card Enrolled: Unavailable Authentication
Card Number 601100
00 0000 0061
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Cybersource Testing Payer Authentication 135
Testing Payer Authentication
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.
Test Case 74: Discover ProtectBuy Card Enrolled: Authentication Error
Card Number 601100
00 0000 0095
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status PENDING_AUTH Status AUTHENTICATIO
ENTICATION N_FAILED
The cardholder is enrolled in We encountered a payer
payer authentication. Please authentication problem: Error
authenticate before proceeding Processing PARes.
with authorization.
Details ACS URL URL value E-commerce internet
indicator
PAReq PAReq value ECI 07
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.
Test Case 75: Discover ProtectBuy Card Not Enrolled
Card Number 601100
00 0000 0053
Auth. Type Non-
participating
bank
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
Cybersource Testing Payer Authentication 136
Testing Payer Authentication
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.
Test Case 76: Discover ProtectBuy Enrollment Check: Time-Out
Card Number 601100
00 0000 0046
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No
liability shift.
Test Case 77: Discover ProtectBuy Enrollment Check Error
Card Number 601100 Error response
00 0000 0087 Incorrect Conguration: Unable to Authenticate
601100
00 0000 0079
Auth. Type Active
authentication
Results Check Enrollment Validate Authentication
Cybersource Testing Payer Authentication 137
Testing Payer Authentication
Summary Status AUTHENTICATIO
N_SUCCESSFUL
The cardholder is enrolled in Payer
Authentication. Authenticate the
cardholder before continuing with
the transaction.
Details E-commerce internet
indicator
proofXML proofXML value
VERes enrolled U
Action Proceed with the authorization request, and contact your support
representative to resolve the issue. No liability shift. If you requested
payer authentication and authorization together, the authorization is
processed automatically.
Test Cases for 3-D Secure 2.x
Use the card number specied in the test with the card’s expiration date set to the month
of January and the current year plus three. For example, for 2023, use 2026. You also need
the minimum required elds for an order.
Be sure to remove spaces in card numbers when testing.
The transaction ID (XID) values are included in 3-D Secure 2.x test cases for legacy
reasons. Only Mastercard transactions do not return XID.
While the 3-D Secure version and directory server transaction ID elds are returned for
the Check Enrollment and Validate Authentication services, this data is not included in the
3-D Secure 2.x test cases.
Important
Mastercard requires that the 3-D Secure version and directory server transaction
ID be included along with all pertinent data in your authorization request.
Test Case 2.1: Successful Frictionless Authentication
Successful frictionless authentication of the cardholder by the card issuer.
Cybersource Testing Payer Authentication 138
Testing Payer Authentication
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1000 00 0000 2701
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3006 00 0000 4970
Mastercard 520000 520000
CardType = 002 00 0000 1005 00 0000 2235
Cartes Bancaires 520000 520000
Mastercard 00 0000 3001 00 0000 4801
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1007 00 0000 2708
Discover 601100 —
CardType = 004 00 0000 1002
Diners Club 601100 —
CardType = 005 00 0000 1002
JCB J/Secure 333700 333800
CardType = 007 00 0000 0008 00 0000 0296
Elo 650529 —
CardType = 054 00 0000 1002
China UnionPay 620001 —
CardType = 062 00 0020 0000
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = Y
PARes status = Y
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)
XID = <XID value>
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Cybersource Testing Payer Authentication 139
Testing Payer Authentication
Network Expected E-Commerce Indicator
Visa vbv
Cartes Bancaires Visa vbv
Mastercard spa
Cartes Bancaires Mastercard spa
American Express aesk
Discover dipb
Diners Club pb
JCB J/Secure js
Elo cs
China UnionPay up3ds
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 05
Cartes Bancaires Visa 05
American Express 05
Discover 05
Diners Club 05
JCB J/Secure 05
Elo 05
China UnionPay 05
Mastercard 02
Cartes Bancaires Mastercard 02
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 to your authorization request. If you request the Check
Enrollment and authorization services together, the process described above occurs
automatically.
Cybersource Testing Payer Authentication 140
Testing Payer Authentication
Test Case 2.2: Unsuccessful Frictionless Authentication
Cardholder authentication without a challenge by the card issuer failed.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1018 00 0000 2925
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3014 00 0000 4574
Mastercard 520000 520000
CardType = 002 00 0000 1013 00 0000 2276
Cartes Bancaires 520000 520000
Mastercard 00 0000 3019 00 0000 4538
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1015 00 0000 2096
Discover 601100 —
CardType = 004 00 0000 1010
Diners Club 601100 —
CardType = 005 00 0000 1010
JCB J/Secure 333700 333800
CardType = 007 00 0000 0990 00 0000 0361
Elo 650529 —
CardType = 054 00 0000 1010
China UnionPay 620001 —
CardType = 062 00 0010 0010
Results for the Check Enrollment Service
Status = AUTHENTICATION_FAILED
• User failed authentication.
• Payer cannot be authenticated.
VERes enrolled = Y
PARes status = N
Cybersource Testing Payer Authentication 141
Testing Payer Authentication
ECI/Collection Indicator Values
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
No results are returned.
Action
While 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.
Test Case 2.3: Attempts Processing Frictionless Authentication
While the cardholder is enrolled in 3-D Secure, the card issuer does not
support 3-D Secure, requiring a stand-in authentication experience.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1026 00 0000 2719
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3022 00 0000 4111
Mastercard 520000 520000
CardType = 002 00 0000 2482 00 0000 2482
Cybersource Testing Payer Authentication 142
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Cartes Bancaires 520000 520000
Mastercard 00 0000 3027 00 0000 4587
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1023 00 0000 2872
Discover 601100 —
CardType = 004 00 0000 1028
Diners Club 601100 —
CardType = 005 00 0000 1028
JCB J/Secure 333700 333800
CardType = 007 00 0000 7045 00 0000 0585
Elo 650529 —
CardType = 054 00 0000 1069
China UnionPay 620001 —
CardType = 062 00 0000 0020
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = Y
PARes status = A
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)
XID = <XID value> (American Express only)
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Network Expected E-Commerce Indicator
Visa vbv_attempted
Cartes Bancaires Visa vbv_attempted
Mastercard spa
Cartes Bancaires Mastercard spa
American Express aesk_attempted
Discover dipb_attempted
Diners Club pb_attempted
Cybersource Testing Payer Authentication 143
Testing Payer Authentication
Network Expected E-Commerce Indicator
JCB J/Secure js_attempted
Elo cs_attempted
China UnionPay up3ds_attempted
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 06
Cartes Bancaires Visa 06
American Express 06
Discover 06
Diners Club 06
JCB J/Secure 06
Elo 06
China UnionPay 06
Mastercard 01
Cartes Bancaires Mastercard 01
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.
Test Case 2.4: Unavailable Frictionless Authentication
Authentication is unavailable at the time of transaction.
Cybersource Testing Payer Authentication 144
Testing Payer Authentication
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1034 00 0000 2313
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3030 00 0000 4160
Mastercard 520000 520000
CardType = 002 00 0000 2268 00 0000 1088
Cartes Bancaires 520000 520000
Mastercard 00 0000 3035 00 0000 4306
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1031 00 0000 2922
Discover 601100 —
CardType = 004 00 0000 1036
Diners Club 601100 —
CardType = 005 00 0000 1036
JCB J/Secure 333700 333800
CardType = 007 00 0000 0735 00 0000 0221
Elo 650529 —
CardType = 054 00 0000 1085
China UnionPay 620001 —
CardType = 062 00 0040 0030
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = Y
PARes status = U
AVV = <AVV value> (American Express only)
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Network Expected E-Commerce Indicator
Visa internet or vbv_failure
Cartes Bancaires Visa internet or vbv_failure
Cybersource Testing Payer Authentication 145
Testing Payer Authentication
Network Expected E-Commerce Indicator
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
No results are returned.
Action
Submit your authorization request. No liability shift.
Test Case 2.5: Rejected Frictionless Authentication
Cardholder authentication without a challenge was rejected by the issuer.
Cybersource Testing Payer Authentication 146
Testing Payer Authentication
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1042 00 0000 2537
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3048 00 0000 4517
Mastercard 520000 520000
CardType = 002 00 0000 1047 00 0000 2185
Cartes Bancaires 520000 520000
Mastercard 00 0000 3043 00 0000 4405
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1049 00 0000 2062
Discover 601100 —
CardType = 004 00 0000 1044
Diners Club 601100 —
CardType = 005 00 0000 1044
JCB J/Secure 333700 333800
CardType = 007 00 0000 0321 00 0000 0734
Elo 650529 —
CardType = 054 00 0000 1143
China UnionPay 620001 —
CardType = 062 00 0030 0040
Results for the Check Enrollment Service
Status = AUTHENTICATION_FAILED
• User failed authentication.
• Payer cannot be authenticated.
VERes enrolled = Y
PARes status = R
AVV = <AVV value> (American Express only)
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cybersource Testing Payer Authentication 147
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
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.
Test Case 2.6: Authentication not Available on Lookup
A system error prevented authentication on Lookup.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1059 00 0000 2990
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3055 00 0000 4285
Mastercard 520000 520000
CardType = 002 00 0000 1054 00 0000 2409
Cartes Bancaires 520000 520000
Mastercard 00 0000 3050 00 0000 4090
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1056 00 0000 2468
Cybersource Testing Payer Authentication 148
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Discover 601100 —
CardType = 004 00 0000 1051
Diners Club 601100 —
CardType = 005 00 0000 1051
JCB J/Secure 333700 333800
CardType = 007 00 0000 6765 00 0000 0940
Elo 650529 —
CardType = 054 00 0000 1150
China UnionPay 620001 —
CardType = 062 00 0060 0050
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = U
E-Commerce Indicator Values
Network Expected E-Commerce Indicator
Visa internet or vbv_failure
Cartes Bancaires Visa internet or vbv_failure
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Cybersource Testing Payer Authentication 149
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
No results are returned.
Action
Submit your authorization request. No liability shift.
Test Case 2.7: Enrollment Check Error
An error occurred while attempting to authenticate the cardholder.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1067 00 0000 2446
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3063 00 0000 4194
Mastercard 520000 520000
CardType = 002 00 0000 1062 00 0000 2037
Cartes Bancaires 520000 520000
Mastercard 00 0000 3068 00 0000 4058
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1064 00 0000 2732
Cybersource Testing Payer Authentication 150
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Discover 601100 —
CardType = 004 00 0000 1069
Diners Club 601100 —
CardType = 005 00 0000 1069
JCB J/Secure 333700 333800
CardType = 007 00 0000 0016 00 0000 0650
Elo 650529 —
CardType = 054 00 0000 1176
China UnionPay 620001 —
CardType = 062 00 0050 0060
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = U
E-Commerce Indicator Values
Network Expected E-Commerce Indicator
Visa internet or vbv_failure
Cartes Bancaires Visa internet or vbv_failure
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Cybersource Testing Payer Authentication 151
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
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. No liability shift. If you requested payer authentication and authorization
together, the authorization is processed automatically.
Test Case 2.8: Time-Out
Timeout occurred while checking enrollment, causing an error on the transaction.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1075 00 0000 2354
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3071 00 0000 4277
Mastercard 520000 520000
CardType = 002 00 0000 1070 00 0000 2326
Cybersource Testing Payer Authentication 152
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Cartes Bancaires 520000 520000
Mastercard 00 0000 3076 00 0000 4694
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1072 00 0000 2047
Discover 601100 —
CardType = 004 00 0000 1077
Diners Club 601100 —
CardType = 005 00 0000 1077
JCB J/Secure 333700 333800
CardType = 007 00 0000 0081 00 0000 0577
Elo 650529 —
CardType = 054 00 0000 1192
China UnionPay 620001 —
CardType = 062 00 0090 0070
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
E-Commerce Indicator Values
Network Expected E-Commerce Indicator
Visa internet or vbv_failure
Cartes Bancaires Visa internet or vbv_failure
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
Cybersource Testing Payer Authentication 153
Testing Payer Authentication
ECI/Collection Indicator Values
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
No results are returned.
Action
After 10-12 seconds, proceed with the authorization request. No liability shift.
Test Case 2.9: Bypassed Authentication
The challenge requested by the issuer was bypassed for this transaction.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1083 00 0000 2560
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3089 00 0000 4400
Mastercard 520000 520000
CardType = 002 00 0000 1088 00 0000 2508
Cartes Bancaires 520000 520000
Mastercard 00 0000 3084 00 0000 4991
CardType = 036
Cybersource Testing Payer Authentication 154
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
American Express 340000 340000
CardType = 003 00 0000 1080 00 0000 2948
Discover 601100 —
CardType = 004 00 0000 1085
Diners Club 601100 —
CardType = 005 00 0000 1085
JCB J/Secure 333700 333800
CardType = 007 00 0000 0537 00 0000 0122
Elo 650529 —
CardType = 054 00 0000 1226
China UnionPay 620001 —
CardType = 062 00 0080 0080
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
The cardholder is enrolled in Payer Authentication. Authenticate the cardholder before
continuing with the transaction.
VERes enrolled = B
XID = <XID value>
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Network Expected E-commerce Indicator
Visa internet
Cartes Bancaires Visa internet
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
Cybersource Testing Payer Authentication 155
Testing Payer Authentication
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
No results are returned.
Action
Submit your authorization request. No liability shift.
Test Case 2.10a: Successful Step-Up Authentication
Successful step up (or challenge) authentication transaction.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1091 00 0000 2503
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3139 00 0000 4855
Mastercard 520000 520000
CardType = 002 00 0000 1096 00 0000 2151
Cartes Bancaires 520000 520000
Mastercard 00 0000 3092 00 0000 4074
CardType = 036
Cybersource Testing Payer Authentication 156
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
American Express 340000 340000
CardType = 003 00 0000 1098 00 0000 2534
Discover 601100 —
CardType = 004 00 0000 1093
Diners Club 601100 —
CardType = 005 00 0000 1093
JCB J/Secure 333700 333800
CardType = 007 00 0000 0004 00 0000 0569
Elo 650529 —
CardType = 054 00 0000 1234
China UnionPay 620001 —
CardType = 062 99 9980 0019
Results for the Check Enrollment Service
Status = PENDING_AUTHENTICATION
The cardholder is enrolled in payer authentication. Please authenticate before proceeding
with authorization.
VERes enrolled = Y
PARes status = C
XID = <XID value>
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Network Expected E-Commerce Indicator
Visa vbv
Cartes Bancaires Visa vbv
Mastercard spa
Cartes Bancaires Mastercard spa
American Express aesk
Discover dipb
Diners Club pb
JCB J/Secure js
Elo cs
China UnionPay up3ds
Cybersource Testing Payer Authentication 157
Testing Payer Authentication
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
Status = AUTHENTICATION_SUCCESSFUL
Authentication is validated.
PARes status = Y
XID = <XID value> (American Express only)
CAVV = <CAVV value>
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.
Test Case 2.11a: Unsuccessful Step-Up Authentication
Step up (challenge) authentication transaction where the cardholder challenge failed.
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1109 00 0000 2370
Cybersource Testing Payer Authentication 158
Testing Payer Authentication
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3097 00 0000 4293
Mastercard 520000 520000
CardType = 002 00 0000 2490 00 0000 1104
Cartes Bancaires 520000 520000
Mastercard 00 0000 3100 00 0000 4041
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1106 00 0000 2237
Discover 601100 —
CardType = 004 00 0000 1101
Diners Club 601100 —
CardType = 005 00 0000 1101
JCB J/Secure 333700 333800
CardType = 007 00 0000 0087 00 0000 0874
Elo 650529 —
CardType = 054 00 0000 1275
China UnionPay 620001 —
CardType = 062 99 9970 0029
Results for the Check Enrollment Service
= PENDING_AUTHENTICATIONThe 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>
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
Cybersource Testing Payer Authentication 159
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
= AUTHENTICATION_FAILED
• User failed authentication.
• Payer cannot be authenticated.
PARes status = N
XID = <XID value> (American Express only)
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Action
You are not permitted to submit this transaction for authorization. Instead ask the
customer for another form of payment.
Test Case 2.12a: Unavailable Step-Up Authentication
Step up authentication is unavailable.
Cybersource Testing Payer Authentication 160
Testing Payer Authentication
Card Numbers
Card Type Test Card Number
3-D Secure 2.1.0 3-D Secure 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1117 00 0000 2420
Cartes Bancaires Visa 400000 400000
CardType = 036 00 0000 3105 00 0000 4640
Mastercard 520000 520000
CardType = 002 00 0000 1112 00 0000 2664
Cartes Bancaires 520000 520000
Mastercard 00 0000 3118 00 0000 4124
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 1114 00 0000 2484
Discover 601100 —
CardType = 004 00 0000 1119
Diners Club 601100 —
CardType = 005 00 0000 1119
JCB J/Secure 333700 333800
CardType = 007 00 0020 0079 00 0000 0981
Elo 650529 —
CardType = 054 00 0000 1283
China UnionPay 620001 —
CardType = 062 99 9960 0039
Results for the Check Enrollment Service
Status = PENDING_AUTHENTICATION
The cardholder is enrolled in payer authentication. Authenticate before proceeding with
authorization.
VERes enrolled = Y
PARes Status = C
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
Cybersource Testing Payer Authentication 161
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Results for the Validation Authentication Service
Status = AUTHENTICATION_SUCCESSFUL Authentication is validated.
PARes status = U
XID = <XID value>
E-Commerce Indicator Values
The following table lists the expected e-commerce indicator value for each network.
Network Expected E-Commerce Indicator
Visa internet or vbv_failure
Cartes Bancaires Visa internet or vbv_failure
Mastercard internet
Cartes Bancaires Mastercard internet
American Express internet
Discover internet
Diners Club internet
JCB J/Secure internet
Elo internet
China UnionPay up3ds_failure
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 07
Cartes Bancaires Visa 07
Cybersource Testing Payer Authentication 162
Testing Payer Authentication
Network E-Commerce Indicator (ECI)
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Mastercard 00
Cartes Bancaires Mastercard 00
Action
Retry authentication or process without liability shift.
Test Case 2.14: Require MethodURL
Provides a URL associated with the issuer's BIN range.
Card Numbers
This Method runs before the authentication request to gather information about the
location and type of device being used in the transaction to better assess the risk of a
transaction. If device data can't be collected, an older version of the 3-D Secure protocol
is used and the order is assessed as a higher risk.
Card Type Test Card Number
Version 2.1.0 Version 2.2.0
Visa 400000 400000
CardType = 001 00 0000 1000 00 0000 2701
Cartes Bancaires Visa 400000 400001
CardType = 036 00 0000 3006 00 0000 4970
Mastercard 520001 520000
CardType = 002 00 0000 1005 00 0000 2235
Cartes Bancaires 520000 520000
Mastercard 00 0000 3001 00 0000 4801
CardType = 036
American Express 340000 340000
CardType = 003 00 0000 0007 00 0000 2708
Discover 601101 —
CardType = 004 00 0000 0002
Cybersource Testing Payer Authentication 163
Testing Payer Authentication
Card Type Test Card Number
Version 2.1.0 Version 2.2.0
Diners Club 601101 —
CardType = 005 00 0000 0002
JCB J/Secure 333700 333800
CardType = 007 00 0000 0008 00 0000 0296
Elo 650529 —
CardType = 054 00 0000 1002
China UnionPay 620001 —
CardType = 062 00 0020 0000
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = Y
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)
XID = <XID value> (American Express only)
ECI/Collection Indicator Values
The following table lists the expected ECI or Collection Indicator values for each network.
Network E-Commerce Indicator (ECI)
Visa 05
Cartes Bancaires Visa 05
American Express 05
Discover 05
Diners Club 05
JCB J/Secure 05
Elo 05
China UnionPay 05
Mastercard 02
Cartes Bancaires Mastercard 02
Results for the Validation Authentication Service
If device data cannot be collected or you do not run the 3-D Secure Method (or you do not
provide the browser elds needed for an 3-D Secure transaction on the lookup request),
the transaction reverts to using 3-D Secure 1.0.2 with an PARes status of U.
Cybersource Testing Payer Authentication 164
Testing Payer Authentication
If you provide the browser elds on the Enroll request but do not run the 3-D Secure
Method, you get the following result:
Status = AUTHENTICATION_SUCCESSFUL Authentication is validated.
PARes status = Y
Action
If your device data collection method implements correctly and 3-D Secure Method
processing occurs, the test transaction produces a Frictionless Success result. A failure
is indicated by a PARes status = C.
Payer Authentication Exemption 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 elds to
accommodate different data that is necessary for that test.
Test Case 1a: Initial/First Recurring Transaction - Fixed Amount
Merchant initiates a Requester Initiated Payments (3RI) recurring transaction of a xed
amount for a specied number of transactions or with no set number of transactions such
as occurs with subscription purchases.
Card Type Test Card Number
Mastercard 520000
CardType = 002 00 0000 2805
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
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = C
ECI = 00
Cybersource Testing Payer Authentication 165
Testing Payer Authentication
Results for the Validation Authentication Service
Status = AUTHENTICATION_SUCCESSFUL Authentication is validated.
PARes status = Y
CAVV = <CAVV>
ECI = 02
Card Network and Version Specications
Visa Secure 2.1 does not support this use case. Visa Secure 2.2 test cards are in
development.
For Mastercard Identity Check 2.1, 3RI is not supported for Payment Authentication (PA).
This means 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) and a transaction status
of “U” rather than “Y.”
In EMV 3-D Secure 2.2, Mastercard has allocated a new ECI value, ECI 07, for 3RI
transactions. This 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.
Test Case 2a: Card Authentication Failed
The following test case scenarios test various Trans Status Reasons (failed, suspected
fraud, and similar instances). When PAResStatus = N, the CardholderInfo eld 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 445653
CardType = 002 00 0000 2045
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = N
Cardholder Info = <cardholder information>
ECI = 07
Reason code = 01
Test Case 2b: Suspected Fraud
This test case scenario checks for suspected fraud.
Card Type Test Card Number
Visa 445653
CardType = 001 00 0000 2144
Cybersource Testing Payer Authentication 166
Testing Payer Authentication
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = U
ECI = 07
Reason code = 11
Test Case 2c: Cardholder Not Enrolled in Service
This test case scenario veries whether the cardholder is enrolled in the service.
Card Type Test Card Number
Visa 445653
CardType = 001 00 0000 2169
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = R
Reason code = 476
Test Case 2d: Transaction Timed Out at the ACS
This test case scenario veries 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 445653
CardType = 001 00 0000 2177
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = U
ECI = 07
Reason code = 14
Test Case 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.
Cybersource Testing Payer Authentication 167
Testing Payer Authentication
Card Type Test Card Number
Visa 445653
CardType = 001 00 0000 2235
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = U
ECI = 07
Reason code = 20
Test Case 2f: 3RI Transaction Not Supported
This test case scenario veries whether the merchant can initiate a recurring 3RI
transaction, such as with subscriptions.
Card Type Test Card Number
Visa 445653
CardType = 001 00 0000 2243
Required Fields for Check Enrollment
Message category = 02
Device channel = 3RI (03)
Three RI Indicator = 01
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = U
ECI = 07
Reason code = 21
Test Case 3a: Transaction Risk Analysis Exemption - Low Value -
Mastercard EMV 3-D Secure 2.1 and 2.2
You have performed a proprietary risk assessment and are requesting a transaction risk
analysis, low risk, or low value exemption based on fraud thresholds established with the
network. Be sure to use the correct test card number for your version of 3-D Secure. The
PARes Status will differ between the 3-D Secure versions.
Card Type Test Card Number
Mastercard (version 2.1.0) 5200 0000 0000 1161
CardType = 002 (version 2.2.0) 5200 0000 0000 2052
Cybersource Testing Payer Authentication 168
Testing Payer Authentication
Required Fields for Check Enrollment
Challenge code = 05
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status (version 2.1.0) = N
(version 2.2.0) = I
CAVV = <CAVV value>
ECI = 06
Reason code = 81
Action
Proceed to Authorization.
You can also request the transaction risk analysis (TRA) exemption directly during
authorization depending on the region and your agreements with your acquirer and the
networks.
Test Case 3b-Transaction Risk Analysis Low Value - Visa
The merchant has performed a proprietary risk assessment and is requesting a
transaction risk analysis, low risk, or low value exemption based on fraud thresholds
established with the network.
Card Type Test Card Number
Visa 445653
CardType = 001 00 0000 2029
Required Fields for Check Enrollment
Challenge code = 05
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = I
CAVV = <CAVV value>
ECI = 07
Action
Proceed to Authorization.
You can also request the TRA exemption directly during authorization depending on the
region and your agreements with your acquirer and the networks.
Cybersource Testing Payer Authentication 169
Testing Payer Authentication
Test Case 3c: Transaction Risk Analysis-Low Value-Discover
The merchant has performed a proprietary risk assessment and is requesting a
transaction risk analysis, low risk, or low value exemption based on fraud thresholds
established with the network.
Card Type Test Card Number
Discover 601100
CardType = 004 00 0000 1002
Required Fields for Check Enrollment
Challenge code = 04
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = Y
CAVV = <CAVV value>
Action
Proceed to Authorization.
You can also request the TRA exemption directly during authorization depending on the
region and your agreements with your acquirer and the networks.
Test Case 3d: Acquirer Transaction Risk Analysis-Cartes Bancaires
You have performed a proprietary risk assessment and is requesting a transaction risk
analysis, low risk, or low value exemption based on fraud thresholds established with the
network.
Card Type Test Card Number
Cartes Bancaires Visa 400000
CardType = 036 00 0000 3006
Cartes Bancaires Mastercard 520000
CardType = 036 00 0000 3001
Required Fields for Check Enrollment
Challenge code = 02
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
VERes enrolled = Y
PARes status = Y
Cybersource Testing Payer Authentication 170
Testing Payer Authentication
CAVV = <CAVV value> (The CAVV value is not returned during testing but could be
returned in production based on issuer rules surrounding co-branding with Visa or
Mastercard BINs.)
Action
Proceed to Authorization.
You can also request the TRA exemption directly during authorization depending on the
region and your agreements with your acquirer and the networks.
Test Case 4a: Trusted Beneciary 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 445653
CardType = 002 00 0000 2003
Required Fields for Check Enrollment
Challenge code = 09
Results for the Check Enrollment Service
VERes enrolled = Y
PARes status = C
ECI = 07
Results for the Authenticate Response
PARes status = Y
CAVV = <CAVV value>
ECI = 05
WhiteListStatus = Y
WhiteListStatusSource = 03
Action
You should append the CAVV and ECI values to the authorization message.
Test Case 4b: Utilize Trusted Beneciary Exemption
There is a successful frictionless authentication transaction with a pre-whitelisted
indication and an accepted exemption result.
Card Type Test Card Number
Visa 445653
CardType = 002 00 0000 2011
Cybersource Testing Payer Authentication 171
Testing Payer Authentication
Required Fields for Check Enrollment
Challenge code = 08
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
PARes status = Y
CAVV = <CAVV value>
ECI = 05
WhiteListStatus = Y
WhiteListStatusSource = 03
ThreeDSVersion = 2.2.0
Action
You should append the CAVV and ECI values to the authorization message.
Test Case 5a-1: Identity Check Insights (ScoreRequest = N)
This is a Mastercard Data Only authentication request.
Card Type Test Card Number
Mastercard 520000
CardType = 002 00 0000 1005
Required Fields for Check Enrollment
MessageCategory = 80
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
PAResStatus = U
CAVV = <CAVV value>
ECI = 04
ThreeDSVersion = 2.1.0
Status = AUTHENTICATION_SUCCESSFUL
Action
You should append the ECI and DS Transaction ID values to the authorization message.
Test Case 5a-2: Identity Check Insights (ScoreRequest = Y)
This is a Mastercard Data Only authentication request.
Cybersource Testing Payer Authentication 172
Testing Payer Authentication
Card Type Test Card Number
Mastercard 520000
CardType = 002 00 0000 1005
Required Fields for Check Enrollment
Message Category = 80
Score Request = Y
Merchant Reason Code = A
Results for the Check Enrollment Service
Status = AUTHENTICATION_SUCCESSFUL
PAResStatus = U
CAVV = <CAVV value>
ECI = 04
ThreeDSVersion = 2.1.0
Results for the Authentication Result
Status = AUTHENTICATION_SUCCESSFUL
Action
You should append the ECI and DS Transaction ID values to the authorization message.
Cybersource Testing Payer Authentication 173
Website Modication Reference
Website Modication
Reference
This section contains information about modifying 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 Modication Checklist
Modify web page buttons:
• Order submission button: Disable the nal “buy” button until the customer completes all
payment and authentication requirements.
• Browser back button: Plan for unexpected customer behavior. Use session checks
throughout the authentication process to prevent authenticating transactions twice.
Avoid confusing messages, such as warnings about expired pages.
Add appropriate logos:
• Download the appropriate logos of the cards that you support and place these logos
next to the card information entry elds on your checkout pages. For more information
about obtaining logos and using them, see 3-D Secure Services Logos on page 174.
Add informational message:
• Add a message next to the nal “buy” button and the card logo to inform your
customers that they may be prompted to provide their authentication password. For
examples of messages you can use, see Informational Message Examples on page 176.
3-D Secure Services 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.
Cybersource Website Modication Reference 174
Website Modication Reference
3-D Secure Services Logos Download Location
3-D Secure Service Download Location
Visa Secure https://usa.visa.com/run-your-business/
small-business-tools/payment-
technology/visa-secure.html
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 https://brand.mastercard.com/
brandcenter.html
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:
http://www.mastercardbrandcenter.com/
us/howtouse/bms_mae.shtml
American Express SafeKey https://network.americanexpress.com/uk/
en/safekey/
This website contains information about
SafeKey and links to logos for download.
JCB J/Secure http://partner.jcbcard.com/security/
jsecure/logo.html
This website contains information about J/
Secure and links to logos for download.
Diners Club https://www.dinersclubus.com/home/
ProtectBuy customer-service
Contact Diners Club customer service for
assistance.
Discover ProtectBuy https://www.discovernetwork.com/en-us/
business-resources/free-signage-logos
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.
Cybersource Website Modication Reference 175
Website Modication Reference
Informational Message Examples
Add a brief message next to the nal buy button on your checkout page to inform
customers that they may be prompted for their authentication password or to enroll in the
authentication program for their card.
These examples may be used, but consult your specic 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 may 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 may be eligible 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 may
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.
Cybersource Website Modication Reference 176
Alternate Methods for Device Data Collection
Alternate Methods for
Device Data Collection
There are alternate methods for device data collection. You can also use the Payer
Authentication Setup service described in Implementing Cardinal Cruise Direct
Connection API Payer Authentication.
Important
If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.
Device Data Collection Overview
The device data collection collects the required browser data elements in order to make
the 3-D Secure 2.x request and invoke the 3-D Secure Method URL when it is available.
The Cardinal Cruise Direct Connection API places the required Method URL on the
merchant site on behalf of the merchant. Per EMV 3-D Secure requirements, if the issuing
bank uses a Method URL, then it must run on the merchant site. This is done after a
merchant passes in the BIN (at least the rst eight digits of the card number) into Cardinal
on the POST to the device data collection URL. Options on how to include the BIN are
below.
The Method URL is a concept in the EMV 3-D Secure protocol that enables an issuing bank
to obtain additional browser information prior to starting the authentication session to
help facilitate risk-based authentication. The implementation techniques for obtaining
the additional browser information are out of scope of the EMV 3-D Secure protocol. This
process also occurred in 3-D Secure 1.0 when the customer's browser was redirected to
the ACS URL. The Method URL step provides a better user experience.
Prerequisites
To support device data collection, you must complete one of the following:
Cybersource Alternate Methods for Device Data Collection 177
Alternate Methods for Device Data Collection
• Obtain access to the card BIN (rst eight digits or full card number of cardholder).
• Create an iframe on your website and POST to the device data collection URL.
Endpoints
• Staging: https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
• Production: https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect
Collecting Device Data
The following options are available for device data collection:
• Card BIN in JWT: This option is the recommended approach and allows you to pass the
card BIN (rst eight digits or full card number) in the JWT.
• Card BIN as a POST parameter plus JWT: This option allows you to pass the card BIN
directly from the web front end to the device data collection URL instead of the JWT.
However, a JWT is still required in order to authenticate the session.
Card BIN in JWT
As part of the JWT generation, you add the card BIN to the payload within the
transactional JWT. When the device data collection URL is invoked, the transactional JWT
is sent to the URL.
The following example shows the return URL populated in the transactional JWT instead of
a POST parameter.
1. Add the card BIN (rst eight digits or full card number) to the transactional JWT.
2. Create a POST request to send the transactional JWT to the device data collection URL.
3. Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.
Card BIN in JWT
<iframe height="1" width="1" style="display: none;">
<form id="collectionForm" name="devicedata" method="POST" action="https://
centinelapistag.cardinalcommerce.com/V1/Cruise/Collect">
<input type="hidden" name="JWT" value="Transactional JWT generated per specication" />
</form>
<script>window.onload = function() {
// Auto submit form on page load
document.getElementById('collectionForm').submit();
}
</script>
</iframe>
Cybersource Alternate Methods for Device Data Collection 178
Alternate Methods for Device Data Collection
Card BIN as a POST Parameter Plus JWT
This option allows you to post the card BIN as a POST parameter along with the
transactional JWT. When the device data collection URL is invoked, the transactional JWT
and the BIN are posted to the URL.
The following example shows the return URL populated in the transactional JWT along with
a POST parameter.
1. Create a POST request to send the transactional JWT and the card BIN (rst eight
digits or full card number) to the device data collection URL.
2. Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.
Card BIN as a POST Parameter Plus JWT
<iframe height="1" width="1" style="display: none;">
<form id="collectionForm" name="devicedata" method="POST" action="https://
centinelapistag.cardinalcommerce.com/V1/Cruise/Collect">
<!-- POST Parameters: Bin=First eight digits to full pan of the payment card number. JWT=JWT generated
per merchant spec -->
<input type="hidden" name="Bin" value="41000000" />
<input type="hidden" name="JWT" value="JWT generated per merchant spec" />
</form>
<script>window.onload = function() {
// Auto submit form on page load
document.getElementById('collectionForm').submit();
}
</script>
</iframe>
Cybersource Alternate Methods for Device Data Collection 179
Upgrading Your Payer Authentication Implementation
Upgrading Your
Payer Authentication
Implementation
This section provides information about upgrading to 3-D Secure 2.x for merchants
currently using Payer Authentication services.
Benets
3-D Secure 2.x provides these benets:
• More secure transactions as additional data is available.
• Backward compatibility. Additional data is automatically sent to issuers as they upgrade
to 3-D Secure 2.x.
• Improved user-friendly shopping experience for customers, including frictionless
authentication and shorter transaction times.
• Can result in higher authorization rates.
• Easier to upgrade to 3-D Secure 2.2. Version 2.2 includes support for exemptions
for PSD2, which might allow frictionless authentication, including acquirer/issuer
transactional risk assessment; white listing; low value, one leg out, and merchant-
initiated transactions. These exemptions will be dened as they become available.
PSD2 Impact
If PSD2 affects you, you must upgrade to 3-D Secure 2.x.
PSD2 requires additional security measures outlined in the Regulatory Technical
Standards (RTS) that become applicable in the future. PSD2 requires stronger identity
checks for online payments, particularly for high-value transactions.
PSD2 means changes for all companies in Europe that deal with payments. Some of the
implications for merchants include:
Cybersource Upgrading Your Payer Authentication Implementation 180
Upgrading Your Payer Authentication Implementation
• Requiring two-factor authentication for all electronic payments, although there are
exemptions to allow a frictionless ow.
• Requiring 3-D Secure e-commerce merchants to integrate dynamic authentication
tools (such as 3-D Secure 2.x).
Mandates
PSD2 includes mandates around strong customer authentication (SCA) and exemptions
and challenges. For more information on the mandates, go to Cardinal's consumer
authentication demos page, launch the 3-D Secure information demo and click on the
Country Mandates button at the upper, right of the page.
Recommended Integration
Three types of integration are available for 3-D Secure 2.x:
• Cardinal Cruise Direct Connection API
• SDK integration for your mobile application
• Hybrid integration
If you are currently using Payer Authentication services in your existing business
processes and need to upgrade to 3-D Secure 2.x, we recommend using the Cardinal
Cruise Direct Connection API integration. The Cardinal Cruise Direct Connection API
integration most closely resembles the current process in which you request the
Enrollment Check service to verify that the customer is enrolled in one of the card
authentication programs and receive a response. With 3-D Secure 2.x, that response
includes a new value, the processor transaction ID.
For enrolled cards, include the Access Control Server (ACS) URL, payload, and processor
transaction ID to proceed with the authentication session. Then request the validation
service, sending the processor transaction ID with your request, and receive a response
with the e-commerce indicator and Cardholder Authentication Verication Value (CAVV)
or Account Authentication Value (AAV).
For more information about the Cardinal Cruise Direct Connection API, see Implementing
Cardinal Cruise Direct Connection API Payer Authentication on page 19.
For details about the other integrations, see Implementing SDK Payer Authentication on
page 42 or Implementing Hybrid Payer Authentication.
Important
If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method for Payer Authentication.
Migration FAQ
Q: Is a new JWT required for each transaction?
Cybersource Upgrading Your Payer Authentication Implementation 181
Upgrading Your Payer Authentication Implementation
A: Yes, even though the JWT does not expire for two hours, you should send a new JWT
with each new transaction.
Q: How do you link the device data to the transaction-level data?
A: There are two ways to do this:
• You can create a reference ID in the original JWT and then pass that same value for the
request eld for the Check Enrollment service.
• You can use the session ID returned from Payments.setupComplete for the request
eld for the Check Enrollment service.
Q: When will the Payer Authentication reports include the new elds for 3-D Secure 2.x?
A: They will be added in a future release.
Q: Will my current implementation continue to work while I am implementing and testing
the newer version in parallel?
A: Yes, current implementation will continue to work.
Q: What testing should I conduct, to ensure that my code is working correctly?
A: Use the test cases (Test Cases for 3-D Secure 2.x on page 138) to test your preliminary
code and make the appropriate changes.
Q: How does 3-D Secure 2.x authentication improve the experience for a customer who
uses a mobile or tablet device?
A: 3-D Secure 2.x is agnostic to the device and you have control over the formatting of
the authentication form. 3-D Secure 2.x also supports newer, more secure authentication
delivery tools, such as a one-time password (OTP) sent to a customer’s mobile device or
email.
Cybersource Upgrading Your Payer Authentication Implementation 182
Payer Authentication Transaction Details in the Business Center
Payer Authentication
Transaction Details in the
Business Center
This section describes how to search the Business Center for details of Payer
Authentication transactions. Transaction data is stored for 12 months so that you can
retrieve and send the data to payment card companies, if necessary.
Payer Authentication Search
You can search for transactions that used the payer authentication and card authorization
services. When searching for transactions, consider the following:
• Search options:
• Use the PA Transaction ID as search parameter to nd both parts of a transaction
processed with an enrolled card.
• The list of applications is simplied to facilitate searching for the relevant service
requests.
• Payer authentication information is available for 12 months after the transaction
date.
• Search results: the results options include the PA Transaction ID and the customer’s
account number (PAN). Use the PA Transaction ID to nd all parts of the transaction.
• Payer authentication details: all transaction details are discussed under Searching for
Payer Authentication Details.
Storing Payer Authentication Data
Payment card companies permit only a certain number of days between the payer
authentication and the authorization requests. If you settle transactions that are older
than the predetermined number of days, payment card companies might require that
Cybersource Payer Authentication Transaction Details in the Business Center 183
Payer Authentication Transaction Details in the Business Center
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. After your transactions are settled, you can also use this
data to update the statistics of your business.
Searching for Payer Authentication Details
The payer authentication data that is returned in API response elds can be searched by
using the Transaction Search feature in the Business Center.
With other services, green means success, red means failure, and black means that the
service request did not run. The result of the enrollment check is interpreted differently:
• 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, it means that authentication failed.
• If the application result appears in yellow, it means the transaction requires
authentication.
Enrolled Card
When a card is enrolled, the process consists of two steps:
1. Checking for enrollment
2. Authenticating the customer
Enrollment Check
For the enrollment check for an enrolled card, payer authentication data is located in the
Transaction Search Details window in these sections:
• Request Information section: The enrollment check service is shown in red because
the card is enrolled. You receive the corresponding response information. 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 use later. You do not receive an ECI or AAV_CAVV
because the authentication is not complete.
If CAVV and ECI are not provided and the Enrollment transaction results in a challenge,
then authentication is required.
Authentication Validation
For a transaction in which the validation and the card authorization services were
processed successfully, payer authentication data is located in the Transaction Search
Details window in these sections:
• Request Information section: The validation service succeeded. A reason code
100 is returned with the corresponding response message. The necessary payer
Cybersource Payer Authentication Transaction Details in the Business Center 184
Payer Authentication Transaction Details in the Business Center
authentication information is 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 may 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 the 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
For a transaction in which the card is not enrolled, payer authentication data is located in
the Transaction Search 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: the detailed information for the authorization service:
• For Mastercard, the ECI value is 00: authentication is not required because the
customer’s Mastercard card is not enrolled. Other cards will have an ECI value of 07.
• The AAV/CAVV area is empty because you receive a value only if the customer is
authenticated.
• The XID area is empty because the card in not enrolled.
Cybersource Payer Authentication Transaction Details in the Business Center 185
Payer Authentication Reports
Payer Authentication
Reports
This section describes the Payer Authentication reports that you can download from the
Business Center:
• Payer Authentication Summary Report
• Payer Authentication Detail Report
All reports on the production servers are retained for 16 months but the transaction
history is only kept in the database for six 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 le 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, Maestro, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo. This daily report is generally available by 7:00 am EST.
Data in this report remains available for six months.
Downloading the Report
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.
Cybersource Payer Authentication Reports 186
Payer Authentication Reports
3. In the search toolbar, select the Date Range you want to include in the report. Account
level users must select a merchant as well.
4. Based on the Date Range selected, choose the specic day, week, or month you want
to review.
Only months which have already occurred in the current year display in the Month list. To
view all months of a previous year, select the year rst, then choose the desired month.
To view results before the selected period, below the search toolbar, click Previous. Click
Next to see the previous 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 on page 184.
Payer Authentication Report Details
Interpreting the Report
A report heading shows the title, the ID of the user who downloaded the report, the
merchant ID, and the date or date range of the report. The report is organized by card
type. In each section, currencies are reported alphabetically. For each currency, a
summary of your payer authentication validation results displayed as total amount and
number of transactions.
Payer Authentication Report Interpretation
Card Type Interpretation Protected? Reported
Commerce ECI
Indicator
Visa, American No No Internet 7
Express, and authentication Yes VbV, Desk, or JS 6
JCB Recorded Yes Attempted 5
attempt to VbV, JS, or Aesk
authenticate
Successful
authentication
Cybersource Payer Authentication Reports 187
Payer Authentication Reports
Card Type Interpretation Protected? Reported
2 1
Mastercard and No No Internet 7
Maestro authentication Yes SPA 1
Recorded Yes SPA 2
attempt to
authenticate
Successful
authentication
Diners Club and No No Internet 7
Discover authentication Yes PB or DIPB 6
Recorded Yes Attempted 5
attempt to PB or DIPB
authenticate
Successful
authentication
China UnionPay, No No Internet 7
and Elo authentication Yes CS or Up3ds 6
Recorded Yes Attempted 5
attempt to CS or Up3ds
authenticate
Successful
authentication
1. Although the report heading is 7, you receive a collection indicator value of 1, or the
response eld is empty.
2. Although the report heading is Internet, you receive spa_failure in the commerce
indicator response eld.
Transactions are divided into two groups: those for which you are protected and those for
which you are not protected:
• For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo: 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
There may be differences between the Payer Authentication report and the payment
reports because an authenticated transaction may not be authorized.
The values (amounts and counts) in the Payer Authentication report may not match
exactly your other sources of reconciliation. This report shows the transactions validated
by payer authentication. There may be a different number of transactions that were
authorized. There are more likely to be reconciliation discrepancies if you process your
authorizations outside of <keyword keyref="company"/>.
Cybersource Payer Authentication Reports 188
Payer Authentication Reports
The amounts and numbers can be higher in the Payer Authentication report than in the
payment reports. In this example, it shows the results of the rst two numbers in the Payer
Authentication report and the last one 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 may 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
Refer to the Business Center Reporting User Guide for instructions for downloading the
report and additional report information. For more information about the
Report Elements
The Payer Authentication Detail report consists of these elements:
• <Report>
• <PayerAuthDetail>
• <ProofXML>
• <VEReq>
• <VERes>
• <PAReq>
• <PARes>
• <AuthInfo>
Report
The <Report> element is the root element of the report.
<Report>
<PayerAuthDetails>
(PayerAuthDetail+)
</PayerAuthDetails>
</Report>
Child Elements of <Report>
Element Name Description
<PayerAuthDetail> Contains the transaction in the report. For a list of child elements,
see <PayerAuthDetail>.
Cybersource Payer Authentication Reports 189
Payer Authentication Reports
<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
The <PayerAuthDetail> element contains information about a single transaction.
<PayerAuthDetail>
(RequestID)
(MerchantID)
(RequestDate)
(TransactionType)
(ProofXML)?
(VEReq)?
(VERes)?
(PAReq)?
(PARes)?
(AuthInfo)?
</PayerAuthDetail>
Child Elements of <PayerAuthDetail>
Element Name Description Type & Length
<RequestID> Unique identier generated for the Numeric (26)
transaction. This eld corresponds to the
API eld.
<MerchantID> Merchant ID used for the transaction. String (30)
<RequestDate> Date on which the transaction was DateTime (25)
processed.
<ProofXML> Data that includes the date and time of the String (1024)
enrollment check and the VEReq and VERes
elements. This eld corresponds to the
consumerAuthenticationInformation.Auth
EnrollReply_proofXML API eld. For a list of
child elements, see <ProofXML>.
Cybersource Payer Authentication Reports 190
Payer Authentication Reports
Element Name Description Type & Length
<VEReq> Verify Enrollment Request (VEReq) is
sent by the merchant’s server to the
directory server. The directory server
also sends it to the ACS to determine
whether authentication is available for the
customer’s card number. For a list of child
elements, see <VEReq>.
<VERes> Verify Enrollment Response (VERes) is sent
by the directory server. For a list of child
elements, see <VERes>.
<PAReq> Payer Authentication Request message
that you send to the ACS through the
payment card company. Corresponds to the
consumerAuthenticationInformation.payer
AuthEnrollReply_paReq API eld.
For a list of child elements, see <PAReq>.
<PARes> Payer Authentication Response message
sent by the ACS. For a list of child elements,
see <PARes>.
<AuthInfo> Address and card verication data. For a
list of child elements, see AuthInfo on page
198.
<PayerAuthDetail> Element
<PayerAuthDetail>
<RequestID>0004223530000167905139</RequestID>
<MerchantID>example_merchant</MerchantID>
<RequestDate>2020-02-09T08:00:09-08:00</RequestDate>
<TransactionType>ics_pa_enroll</TransactionType>
<ProofXML>
...
</ProofXML>
<VEReq>
...
</VEReq>
<VERes>
...
</VERes>
<PAReq>
...
</PAReq>
<PARes>
...
</PARes>
</PayerAuthDetail>
Cybersource Payer Authentication Reports 191
Payer Authentication Reports
ProofXML
The <ProofXML> element contains data that includes the date and time of the
enrollment check and the VEReq and VERes elements. This element corresponds to the
consumerAuthenticationInformation. proofXml API eld.
<ProofXML>
(Date)
(DSURL)
(PAN)
(AcqBIN)
(MerID)
(Password)
(Enrolled)
</ProofXML>
Child Elements of <ProofXML>
Element Name Description Type & Length
<Date> Date when the proof XML is generated. DateTime (25)
(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.)
<DSURL> URL for the directory server where the String (50)
proof XML originated.
<PAN> Customer’s masked account number. String (19)
This element corresponds to the
consumerAuthenticationInformation.payer
AuthEnrollReply_proxyPAN API eld.
<AcqBIN> First six digits of the acquiring bank’s Numeric (6)
identication number.
<MerID> Identier provided by your acquirer; used to String (24)
log into the ACS URL.
<Password> Merchant's masked authentication String (8)
password to the ACS; provided by your
acquirer. Applies only to cards issued
outside the U.S.
Cybersource Payer Authentication Reports 192
Payer Authentication Reports
Element Name Description Type & Length
<Enrolled> Result of the enrollment check. This eld String (1)
can contain one of these values:
Y: Authentication available.
N: Cardholder not participating.
U: Unable to authenticate regardless of the
reason.
<ProofXML> Element
<ProofXML>
<Date>20200209 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
The <VEReq> element contains the enrollment check request data.
<VEReq>
(PAN)
(AcqBIN)
(MerID)
</VEReq>
Child Elements of <VEReq>
Element Name Description Type & Length
<PAN> Customer’s masked account number. String (19)
This element corresponds to the
consumerAuthenticationInformation.
proxyPan API eld.
<AcqBIN> First six digits of the acquiring bank’s Numeric (6)
identication number.
<MerID> Identier provided by your acquirer; used to String (24)
log in to the ACS URL.
<VEReq> Element
<VEReq>
<PAN>XXXXXXXXXXXX0771</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>example</MerID>
Cybersource Payer Authentication Reports 193
Payer Authentication Reports
</VEReq>
VERes
The <VERes> element contains the enrollment check response data.
<VERes>
(Enrolled)
(AcctID)
(URL)
</VERes>
Child Elements of <VERes>
Element Name Description Type & Length
<Enrolled> Result of the enrollment check. This eld String (1)
can contain one of these values:
• Y: Authentication available.
• N: Cardholder not participating.
• U: Unable to authenticate regardless of
the reason.
<AcctID> Masked string used by the ACS. String (28)
<URL> URL of Access Control Server where to String (1000)
send the PAReq. This element corresponds
to the consumerAuthenticationInformation.
acsUrl API eld.
<VERes> Element
<VERes>
<Enrolled>Y</Enrolled>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<URL>https://www.example_url.com</URL>
</VERes>
PAReq
The <PAReq> element contains the payer authentication request message. This element
corresponds to the consumerAuthenticationInformation.pareq API eld.
<PAReq>
(AcqBIN)
(MerID)
(Name)
(Country)
(URL)
(XID)
(Date)
Cybersource Payer Authentication Reports 194
Payer Authentication Reports
(PurchaseAmount)
(AcctID)
(Expiry)
</PAReq>
Child Elements of <PAReq>
Element Name Description Type & Length
<AcqBIN> First six digits of the acquiring bank’s Numeric (6)
identication number.
<MerID> Identier provided by your acquirer; used to String (24)
log in to the ACS URL.
<Name> Merchant’s company name. String (25)
<Country> Two-character code for the merchant’s String (2)
country of operation.
<URL> Merchant’s business website. String
<XID> Unique transaction identier generated String (28)
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 nd all requests related to a transaction,
you can also search transactions for a
specic XID.
<Date> Date and time of request. DateTime (25)
(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.)
<Purchase Amount> Authorization amount and currency for the Amount (15)
transaction. This element corresponds to
the totals of the offer lines or from:
• orderInformation.amountDetails.totalAmount
<AcctID> Masked string used by the ACS. String (28)
<Expiry> Expiration month and year of the Number (4)
customer’s card.
<PAReq>
<AcqBIN>123456</AcqBIN>
<MerID>444444</MerID>
Cybersource Payer Authentication Reports 195
Payer Authentication Reports
<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
The <PARes> element contains the payer authentication response.
<PARes>
(AcqBIN)
(MerID)
(XID)
(Date)
(PurchaseAmount)
(PAN)
(AuthDate)
(Status)
(CAVV)
(ECI)
</PARes>
Element Name Description Type & Length
<AcqBIN> First six digits of the acquiring bank’s Numeric (6)
identication number.
<MerID> Identier provided by your acquirer; used to log in String (24)
to the ACS URL.
<XID> XID value returned in the customer authentication String (28)
response. This element corresponds to the
consumerAuthenticationInformation. xid and
consumerAuthenticationInformation.xid API elds.
<Date> Date and time of request. DateTime (25)
(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.)
<PurchaseAmount>Authorization amount and currency for Amount (15)
the transaction. This element corresponds
to the totals of the offer lines or from:
orderInformation.amountDetails.totalAmount
Cybersource Payer Authentication Reports 196
Payer Authentication Reports
Element Name Description Type & Length
<PAN> Customer’s masked account number. String (19)
This element corresponds to the
consumerAuthenticationInformation. proxyPan
API eld.
<AuthDate> Date and time of request. DateTime (25)
(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.)
<Status> Result of the authentication check. This eld can String (1)
contain 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.
<CAVV> CAVV (Visa, American Express, JCB, Diners Club, String (50)
Discover, China UnionPay, and Elo) cards = *
below) or AAV (Mastercard, and Maestro cards =
** below) returned in the customer authentication
response. This element corresponds to the
consumerAuthenticationInformation.cav and
consumerAuthenticationInformation.ucaf
AuthenticationData API elds.
<ECI> Electronic Commerce Indicator returned Numeric (1)
in the customer authentication response.
This element corresponds to the
consumerAuthenticationInformation.eci and
consumerAuthenticationInformation.ucaf
CollectionIndicator API elds.
<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>
Cybersource Payer Authentication Reports 197
Payer Authentication Reports
<CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
<ECI>5</ECI>
</PARes>
AuthInfo
The <AuthInfo> element contains address and card verication information.
<AuthInfo>
(AVSResult)
(CVVResult)
</AuthInfo>
Element Name Description Type & Length
<AVSResult> Optional results of the address verication String (1)
test.
.
<CVVResult> Optional results of the card verication String (1)
number test.
.
<AuthInfo> Element
<AuthInfo>
<AVSResult>Y</AVSResult>
<CVVResult/>
</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 https://ics2ws.in.ic3.com/commerce/1.x/
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="2020-02-09T08:00:00-08:00"
ReportEndDate="2020-02-10T08:00:00-08:00"
<PayerAuthDetails>
<PayerAuthDetail>
RequestID=”1895549430000167904548”
TransactionType=”ics_pa_enroll
RequestDate=”2020-02-09T08:00:02-08:00”
Cybersource Payer Authentication Reports 198
Payer Authentication Reports
<ProofXML>
<Date>20200209 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>2020-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=”2020-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>2020-02-09T07:59:46-08:00</AuthDate>
<Status>Y</Status>
<CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
Cybersource Payer Authentication Reports 199
Payer Authentication Reports
<ECI>5</ECI>
</PARes>
</PayerAuthDetail>
</PayerAuthDetails>
</Report>
Cybersource Payer Authentication Reports 200
Glossary
Glossary
3RI Payments A 3-D Secure request for information. It is
an EMVCo term for a 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, JCB
J⁄Secure, Diners Club ProtectBuy, Discover
ProtectBuy, China UnionPay, and Elo.
AAV Account Authentication Value. 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 nancial institution that accepts
payments for products or services on
behalf of a merchant. Also referred to
as “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
identies the acquiring bank. There is
a different acquirer BIN for Mastercard
(starts with 5) and Visa (starts with 4) for
every participating acquirer.
acquiring processor Processor that provides credit card
processing, settlement, and services to
merchant banks.
Cybersource Glossary 201
Glossary
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. This is where you send the
PAReq so that the customer can be
authenticated.
American Express A globally issued card type that starts
with 3 and which is identied as card type
003. These cards participate in a card
authentication service (SafeKey) provided
by 3-D Secure.
API Application Programming Interface. A
specication used by software components
to communicate with each other.
authentication result Raw data sent by the card issuer that
indicates the status of authentication. It
is not required to pass this 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 specic
purchase. A positive authorization causes
an authorization code to be generated
and the funds to be held. Following a payer
authentication request, the authorization
must contain payer authentication-specic
elds containing card enrollment details.
If these elds are not passed correctly to
the bank, it can invalidate the liability shift
provided by card authentication. Systemic
failure can result in payment card company
nes.
Base64 Standard encoding method for data
transfer over the Internet.
BIN Bank Identication Number. The eight-digit
number at the beginning of the card that
identies the card issuer.
CAVV Cardholder Authentication Verication
Value. A Base64-encoded string sent
back with Visa Secure-enrolled cards that
Cybersource Glossary 202
Glossary
specically identies the transaction with
the issuing bank and Visa. Standard for
collecting and sending AAV data for Visa
Secure transactions. See AAV.
CAVV algorithm A one-digit response passed back when the
xPARes status is a Y or an A.
Compra Segura Trademarked name for the Elo card
authentication service.
CVV Card Verication 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 that starts with
a 3 or a 5. Diners Club cards are identied
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 that starts with
a 6. Discover cards are identied 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 that starts with
a 5. Elo cards are identied as card type
of 054. These cards participate in a card
authentication service (Compra Segura)
provided by 3-D Secure.
Cybersource Glossary 203
Glossary
HTTP Hypertext Transfer Protocol. An application
protocol used for data transfer on the
Internet.
Enroll A type of transaction used for verifying
whether a card is enrolled in the
Mastercard Identity Check or Visa Secure
service.
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 le 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.
J/Secure The 3-D Secure program of JCB.
issuer The bank that issued a credit card.
JCB Japan Credit Bureau. A globally issued card
type that starts with a 3. JCB cards are
identied as a card type of 007. These cards
participate in a card authentication service
(J/Secure) provided by 3-D Secure.
Maestro. A card brand owned by Mastercard that
includes several debit card BINs within
the U.K. (where it was formerly known as
Switch), and in Europe. Merchants who
accept Maestro cards online are required
to use SecureCode, Mastercard’s card
authentication service. Maestro cards are
identied 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 card
authentication program.
Mastercard A globally issued card that includes credit
and debit cards. These cards start with a 5.
These cards are identied as card type 002
for both credit and debit cards. These cards
participate in a card authentication service
Cybersource Glossary 204
Glossary
(Mastercard Identity Check) provided by 3-
D Secure.
Mastercard Identity Check Trademarked name for Mastercard’s card
authentication service.
MD Merchant-dened Data that is posted as
a hidden eld 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 specic order. Although
payment card companies recommend
that you use the XID, you can also use
data such as an order number. This eld 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
a 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 eld name
has a lowercase “a” (PaReq), whereas
the message name has an uppercase
“A” (PAReq).
PARes Payer Authentication Response.
Compressed, Base64-encoded response
from the card-issuing bank. This data is
passed for validation.
Cybersource Glossary 205
Glossary
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 eld contains the VEReq and VERes for
merchant storage. Merchants can use this
data for future chargeback repudiation.
ProtectBuy Trademarked name for the Diners Club and
Discover card authentication services.
request ID A 22- or 23-digit number that uniquely
identies 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 what 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, which provides three ways to
access services: name-value pair (NVP),
XML, and SOAP.
Solo A debit card type owned by Maestro. It was
permanently discontinued March 31, 2011.
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
Cybersource Glossary 206
Glossary
specically identifying the transaction with
the issuing bank and Mastercard. Standard
for collecting and sending AAV data for
Mastercard Identity Check transactions.
See AAV.
UCAF collection indicator Value of 1 or 2 that indicates whether a
Mastercard cardholder has authenticated
themselves or not.
Switch See Maestro.
validate CyberCybersourcesource service for
decoding and decrypting the PARes
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 cards start with a 4.
These cards are identied as card type 001
for both credit and debit cards. These cards
participate in a card authentication service
(Visa Secure) provided by 3-D Secure.
Visa Secure (VbV) Trademarked name for Visa’s card
authentication service.
XID String used by both Visa and Mastercard,
which identies a specic transaction on
the Directory Servers. This string value
should remain consistent throughout a
transaction’s history.
Cybersource Glossary 207
You might also like
- Cybersource Payer Authentication: Using The Simple Order APINo ratings yetCybersource Payer Authentication: Using The Simple Order API261 pages
- Cybersource Cartridge Controllers Integration GuideNo ratings yetCybersource Cartridge Controllers Integration Guide144 pages
- Payer - Authentication - SO - API Mar20No ratings yetPayer - Authentication - SO - API Mar20241 pages
- Mobile Push Payments Technical SpecificationsNo ratings yetMobile Push Payments Technical Specifications77 pages
- NetSuite CyberSource Bundle Installation Guide 24.3.0No ratings yetNetSuite CyberSource Bundle Installation Guide 24.3.073 pages
- Cybersource Credit Card Services Using The Simple Order APINo ratings yetCybersource Credit Card Services Using The Simple Order API93 pages
- CyberSource Cartridge Storefront Reference Architecture Integration GuideNo ratings yetCyberSource Cartridge Storefront Reference Architecture Integration Guide45 pages
- Advanced Integration Method (AIM) Developer Guide: Card Not Present TransactionsNo ratings yetAdvanced Integration Method (AIM) Developer Guide: Card Not Present Transactions56 pages
- Cybersource Salesforce Order Management Technical GuideNo ratings yetCybersource Salesforce Order Management Technical Guide9 pages
- Mobile Acceptance Guides Ve Version Ap03!73!18426No ratings yetMobile Acceptance Guides Ve Version Ap03!73!1842612 pages
- Payer Authentication Service: Verified by Visa, Mastercard Securecode, JCB J/SecureNo ratings yetPayer Authentication Service: Verified by Visa, Mastercard Securecode, JCB J/Secure1 page
- Cybersource Extension For Magento 2: Secure Payment Management For A Leading Ecommerce PlatformNo ratings yetCybersource Extension For Magento 2: Secure Payment Management For A Leading Ecommerce Platform2 pages
