Title Page

Cybersource Payer Authentication

Using the SCMP API
Cybersource Contact Information
For general information about our company, products, and services, go to http://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:
http://www.cybersource.com/support

Copyright
© 2021. 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 subparagraphs (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.

Version: 21.05

2
 CONTENTS
Contents

Recent Revisions to This Document 11

About This Guide 13

Audience and Purpose 13
Scope 13
Conventions 14
Note, Important, and Warning Statements 14
Text and Command Conventions 14
Related Documents 15
Customer Support 15

Chapter 1 Introducing Payer Authentication 16

Overview of Chargeback Protection 16
PSD2 17
3D Secure 2.x 17
Prerequisites for Implementing Payer Authentication 17
Integrating Payer Authentication into Your Business 18
Implementing 3D Secure 2.x 19
Scenario 1: You are a New Merchant 19
Scenario 2: You Use the Cybersource SCMP API and Payer Authentication Ser-
vices for 3D Secure 1.0 20
Scenario 3: You Want to Integrate Using an SDK for your Mobile Application 21
Using Secure Acceptance with Payer Authentication 22
Required Merchant Information 22

Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer

Authentication 23
Prerequisites 23
After Implementation and Before Go Live 23
Process Flow for Cardinal Cruise Direct Connection API 24
Step 1: Payer Authentication Setup Service 24

Payer Authentication Using the SCMP API | 3

 Contents

Request Fields 24
Important Response Fields 24
Field Definitions and Details 24
Request and Response API Examples 24
Step 2: Device Data Collection Iframe 25
Building the Iframe 25
Step 3: Payer Authentication Check Enrollment Service 27
Request Fields 27
Field Definitions and Details 28
Combining Services 28
Interpreting the Response 29
Important Response Fields 30
Field Definitions and Details 30
Step 4: Step-Up IFrame 30
Building the Iframe 30
Receiving the Step-Up Results 32
Step 5: Payer Authentication Validation Service 33
Request Fields 33
Field Definitions and Details 33
Request and Response API Examples 33
Combining Services or Mapping Authorization Fields 33
Interpreting the Response 34
Redirecting Customers to Pass or Fail Message Page 35

Chapter 3 Implementing SDK Payer Authentication 36

Implementation Overview 36
Process Flow for SDK Integration 37
Before You Begin 38
Credentials/API Keys 38
Create the JSON Web Token (JWT) 39
JWT Claims 39
JWT Examples 40
Using the Android SDK 41
Update the Gradle Build Properties 41
Configure the Android SDK 42
Set Up the Initial Call 44
Using the iOS SDK 45
Download and Import the SDK 45
Set Up Your Build Environment 46
Configure the iOS SDK 47
Set Up the Initial Call 50
Implementing SDK Payer Authentication 51
Requesting the Check Enrollment Service (SDK) 51

Payer Authentication Using the SCMP API | 4

 Contents

Interpreting the Response 52

Authenticating Enrolled Cards 53
Call Cardinal.cca_continue (Android SDK) 54
Call Cardinal session continue (iOS SDK) 55
Receiving the Authentication Results 57
Requesting the Validation Service 57
Interpreting the Response 59
Redirecting Customers to Pass or Fail Message Page 59

Chapter 4 Upgrading Your Payer Authentication Implementation 60

Upgrading to 3D Secure 2.x 60
Benefits 60
PSD2 Impact 61
Mandates 61
Timelines 61
Recommended Integration 61
Migration FAQ 62

Chapter 5 Testing Payer Authentication Services 64

Testing Process 64
Enrollment Check 64
Authentication Validation 65
Expected Results 66
Test Cases for 3D Secure 1.0 68
Visa Secure 68
Mastercard Identity Check 75
Maestro 84
American Express SafeKey 89
JCB J/Secure 95
Diners Club ProtectBuy 101
Discover ProtectBuy 107
Elo Compra Segura 113
China UnionPay 114
Test Cases for 3D Secure 2.x 115
Test Case 2.1: Successful Frictionless Authentication 116
Card Numbers 116
Results for the Check Enrollment Service 116
Results for the Validation Authentication Service 117
Action 118
Test Case 2.2: Unsuccessful Frictionless Authentication 118
Card Numbers 118

Payer Authentication Using the SCMP API | 5

 Contents

Results for the Check Enrollment Service 119

Results for the Validation Authentication Service 119
Action 119
Test Case 2.3: Attempts Processing Frictionless Authentication 120
Card Numbers 120
Results for the Check Enrollment Service 120
Results for the Validation Authentication Service 121
Action 122
Test Case 2.4: Unavailable Frictionless Authentication 122
Card Numbers 122
Results for the Check Enrollment Service 123
Results for the Validation Authentication Service 124
Action 124
Test Case 2.5: Rejected Frictionless Authentication 124
Card Numbers 124
Results for the Check Enrollment Service 125
Results for the Validation Authentication Service 125
Action 125
Test Case 2.6: Authentication not Available on Lookup 126
Card Numbers 126
Results for the Check Enrollment Service 126
Results for the Validation Authentication Service 127
Action 127
Test Case 2.7: Enrollment Check Error 128
Card Numbers 128
Results for the Check Enrollment Service 128
Results for the Validation Authentication Service 129
Action 129
Test Case 2.8: Time-Out (Cruise Direct and Hybrid Only) 130
Card Numbers 130
Results for the Check Enrollment Service 130
Results for the Validation Authentication Service 131
Action 131
Test Case 2.9: Bypassed Authentication 132
Card Numbers 132
Results for the Check Enrollment Service 132
Results for the Validation Authentication Service 133
Action 133
Test Case 2.10a: Successful Step-Up Authentication (Cruise Direct and Hybrid) 134
Card Numbers 134
Results for the Check Enrollment Service 134
Results for the Validation Authentication Service 135
Action 136
Test Case 2.10b: Successful Step-Up Authentication (Standard) 137
Card Numbers 137

Payer Authentication Using the SCMP API | 6

 Contents

Results for the Check Enrollment Service 137

Results for the Validation Authentication Service 138
Action 139
Test Case 2.11a: Unsuccessful Step-Up Authentication (Cruise Direct and
Hybrid) 139
Card Numbers 139
Results for the Check Enrollment Service 140
Results for the Validation Authentication Service 140
Action 140
Test Case 2.11b: Unsuccessful Step-Up Authentication (Standard) 141
Card Numbers 141
Results for the Check Enrollment Service 141
Results for the Validation Authentication Service 142
Action 142
Test Case 2.12a: Unavailable Step-Up Authentication (Cruise Direct and Hybrid) 143
Card Numbers 143
Results for the Check Enrollment Service 143
Results for the Validation Authentication Service 144
Action 145
Test Case 2.12b: Unavailable Step-Up Authentication (Standard) 145
Card Numbers 145
Results for the Check Enrollment Service 146
Results for the Validation Authentication Service 147
Action 147

Appendix A API Fields 148

Formatting Restrictions 148
Data Type Definitions 148
Request-Level Fields 149
Offer-Level Fields 169
Response Fields 170

Appendix B Response Flags 188

Appendix C Request and Response Examples 189

Cardinal Cruise Direct Connection API Integration Examples 189
Payer Authentication Setup Service Request Example 189
Payer Authentication Setup Service Response Example 190
Check Enrollment Request Example 191
Check Enrollment Response Example 192

Payer Authentication Using the SCMP API | 7

 Contents

Validate Authentication Request Example 193

Validate Authentication Response Example 194
Standard Integration Examples 196
Check Enrollment Request Example 196
Check Enrollment Response Example 197
Hybrid Integration Examples 198
Check Enrollment Request Example 198
Check Enrollment Response Example 199
Validate Authentication Request Example 200
Validate Authentication Response Example 201

Appendix D Website Modification Reference 202

Website Modification Checklist 202
3D Secure Services Logos 203
Informational Message Examples 204

Appendix E Payer Authentication Transaction Details in the Business Center 205

Searching for Payer Authentication Details 205
Enrolled Card 205
Enrollment Check 205
Authentication Validation 206
Card Not Enrolled 207
Transaction Details 207
Payer Authentication Search 207
Storing Payer Authentication Data 208

Appendix F Payer Authentication Reports 209

Payer Authentication Summary Report 209
Downloading the Report 210
Matching the Report to the Transaction Search Results 210
Interpreting the Report 211
Comparing Payer Authentication and Payment Reports 212
Payer Authentication Detail Report 213
Report Elements 213
<Report> 213
<PayerAuthDetail> 213
<ProofXML> 215
<VEReq> 216
<VERes> 217
<PAReq> 218

Payer Authentication Using the SCMP API | 8

 Contents

<PARes> 219
<AuthInfo> 221
Examples 222
Failed Enrollment Check 222
Successful Authentication 223

Appendix G Rules-Based Payer Authentication 224

Available Rules 224
API Responses 225
Bypassed Authentication Transactions 225
Risk-Based Bank Transactions 226

Appendix H Implementing Hybrid or Standard Payer Authentication 227

Hybrid Payer Authentication 227
Implementation Overview 227
Process Flow for Hybrid Integration 228
Before You Begin 229
Credentials/API Keys 229
Create the JSON Web Token (JWT) 229
Add the JavaScript 232
BIN Detection 232
Implementing Hybrid Payer Authentication 232
Requesting the Check Enrollment Service (Hybrid) 232
Authenticating Enrolled Cards 235
Requesting the Validation Service 236
Standard Payer Authentication 238
Implementation Overview 238
Process Flow for Standard Integration 239
Before You Begin 240
Credentials/API Keys 240
Create the JSON Web Token (JWT) 240
Add the JavaScript 242
BIN Detection 242
Implementing Standard Payer Authentication 243
Starting Authentication 243
Requesting the Check Enrollment Service (Standard) 244

Appendix I Alternate Methods for Device Data Collection 247

Device Data Collection Overview 247
Prerequisites 247
Endpoints 247

Payer Authentication Using the SCMP API | 9

 Contents

Collecting Device Data 248

Option 1: Card BIN in JWT 248
Option 2: Card BIN as a POST Parameter Plus JWT 249

Glossary 250

Payer Authentication Using the SCMP API | 10

 REVISIONS
Recent Revisions to This
Document

Release Changes
21.05  Updated the process to obtain credentials to generate your API keys for the Cardinal Mobile
SDK integration. See "Credentials/API Keys."
 Updated "Test Case 38: American Express SafeKey Card Enrolled: Successful
Authentication" to fix a missing credit card digit.
 Added note that XID is not returned for Mastercard transactions. See "Test Cases for 3D
Secure 2.x."
 Updated "Test Case 2.8: Time-Out (Cruise Direct and Hybrid Only)" from PARes status = U to
VERes enrolled = U.
21.04  Updated the card_type field description to specify it is required for the Payer Authentication
Setup service when the card type is Cartes Bancaires.
 Updated the length of the pa_sdk_max_timeout field from 1 to 2.
 Updated the size of the device data collection iframe to 10x10. See "Step 2: Device Data
Collection Iframe," page 25.
21.03  Added support for China UnionPay and Elo cards, including new test cases and updated API
fields. See "Elo Compra Segura," "China UnionPay," and Appendix A, "API Fields," on
page 148.
 Added JCB, Elo, and China UnionPay card numbers to 2.x test cases. See "Test Cases for
3D Secure 2.x."
 Updated the 2.x test cases to include all card types in a single set of test cases. See "Test
Cases for 3D Secure 2.x."
 Updated the following field descriptions to specify required for China and add additional
information:
 bill_state

 ship_to_state

Payer Authentication Using the SCMP API | 11

 Recent Revisions to This Document

Release Changes
21.02  Updated 3D Secure requestor ID and 3D Secure requestor name to be optional. See
"Required Merchant Information."
 Added vbv_failure as a possible value along with internet for the e-commerce indicator for
1.0 Visa test cases 4, 7, 8, 10, and 11. See "Test Cases for 3D Secure 1.0."
 Added card numbers for Cartes Bancaires Visa and Mastercard. See "Test Cases for 3D
Secure 2.x."
 Updated the following field descriptions to specify they are not limited to Cartes Bancaires
transactions:
 pa_merchant_score
 authorization_payload
 effective_authentication_type
 Updated the length of following fields from 20 to 8 to match the EMV® Specifications.
 pa_enroll_specification_version

 pa_validate_specification_version
21.01  Reformatted all card numbers with line breaks and spacing. See Chapter 5, "Testing Payer
Authentication Services," on page 64.
 Updated the following fields to change the data type from integer to string:
 challenge_cancel_code

 pa_network_score
 pares_status_reason
 Updated the following field descriptions to remove required for transactions in Brazil:
 pa_mcc

 pa_mobile_phone
 pa_override_payment_method
 pa_product_code
20.05  Revised Chapter 2, "Implementing Cardinal Cruise Direct Connection API Payer
Authentication," on page 23.
 Added new request fields for the Payer Authentication Setup service:
 pa_response_access_token

 pa_return_url
 Added a new response field for the Payer Authentication Setup service:
 pa_access_token

 Added new examples for the Payer Authentication Setup service and Cardinal Cruise Direct
Connection API. See Appendix C, "Request and Response Examples," on page 189.

Payer Authentication Using the SCMP API | 12

 ABOUT GUIDE
About This Guide

Audience and Purpose

This guide is written for application developers who want to use the Cybersource SCMP
API to integrate Payer Authentication services into their order management system. It
describes the tasks you must perform in order to complete this integration.

Implementing Cybersource Payer Authentication services requires software development

skills. You must write code that uses the API request and response fields to integrate
payer authentication services into your existing order management system.

Scope
This guide describes how to use the SCMP API to integrate payer authentication services
with your order management system. It does not describe how to get started using the
SCMP API nor does it explain how to use Cybersource services other than payer
authentication. For that information, see "Related Documents," page 15.

Payer Authentication Using the SCMP API | 13

 About This Guide

Conventions

Note, Important, and Warning Statements

A Note contains helpful suggestions or references to material not contained in

this document.

An Important statement contains information essential to successfully

completing a task or learning a concept.

A Warning contains information or instructions, which, if not heeded, can result

in a security risk, irreversible loss of data, or significant cost in time or revenue
or both.

Text and Command Conventions

Convention Usage
bold  Field and service names in text. For example:
Include the ics_applications field.
 Items that you are instructed to act upon. For example:
Click Save.
italic  Filenames and pathnames. For example:
Add the filter definition and mapping to your web.xml file.
 Placeholder variables for which you supply particular values.
Screen text  XML elements.
 Code examples and samples.
 Text that you enter in an API environment. For example:
 Set the davService_run field to true.

Payer Authentication Using the SCMP API | 14

 About This Guide

Related Documents
 Getting Started with Cybersource Advanced for the SCMP API describes how to get
started using the SCMP API. (PDF | HTML)

 Decision Manager Developer Guide Using the SCMP API describes how to integrate
Decision Manager, a fraud detection service, with your order management system.
(PDF | HTML)

 Credit Card Services Using the SCMP API describes how to integrate Cybersource
payment processing services into your business. (PDF | HTML)

 Secure Acceptance Hosted Checkout Integration Guide describes how to create

Secure Acceptance profiles, which enable you to integrate your order management
system with the Secure Acceptance web/mobile checkout. (PDF | HTML)

 Secure Acceptance Checkout API Integration Guide describes how to create Secure
Acceptance profiles, which enable you to integrate your order management system
with a website to process transactions. (PDF | HTML)

 Reporting Developer Guide describes how to view and configure Business Center
reports. (PDF | HTML)

 The Cybersource API Versions page provides information about the API versions.

Refer to the Support Center for complete documentation:

https://www.cybersource.com/en-us/support/technical-documentation.html

Customer Support
For support information about any Cybersource service, visit the Support Center:
http://www.cybersource.com/support

Payer Authentication Using the SCMP API | 15

 CHAPTER
Introducing Payer
Authentication
1

Cybersource Payer Authentication services use JavaScript and the ICS services to
provide authentication.

Payer Authentication services enable you to add support to your web store for card
authentication services, including Visa SecureSM, Mastercard Identity Check®, Maestro®
(UK Domestic and international), American Express SafeKeySM, JCB J/Secure™, Diners
Club ProtectBuy, Discover ProtectBuy, China UnionPay, and Elo Compra Segura.

These card authentication services deter unauthorized card use and protect you from
fraudulent chargeback activity referred to as liability shift. However, Cybersource Payer
Authentication is not a fraud management service, such as Decision Manager with
Advanced Fraud Screen. Cybersource recommends that you implement a comprehensive
fraud management program in addition to payer authentication services.

You can use payer authentication services with specific payment processors. To find out if
your payment processor supports this feature, see the “Payer Authentication” section in
Credit Card Services Using the SCMP API (PDF | HTML).

Overview of Chargeback Protection

Visa, Mastercard, Maestro, American Express, JCB, Diners Club, Discover, China
UnionPay, and Elo offer chargeback protection if merchants participate in 3D 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 region that issued the card. Payment card company rules might vary over
time and across geographical regions. Cybersource recommends that you contact your
merchant account provider to find out exactly how to interpret chargeback requirements
and which chargeback protections are offered.

Payer Authentication Using the SCMP API | 16

 Chapter 1 Introducing Payer Authentication

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 (including the UK even if
departed from the EEA) 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 be applied for
all electronic payments.

3D Secure 2.x
3D Secure 2.x is the authentication protocol provided by the card networks to support
SCA. To comply with SCA, merchants must deploy 3D Secure 2.x to their checkout page
or use a compliant hosted checkout.

Additional data can be passed in now and will be automatically sent to issuers as they
upgrade to 3D Secure 2.x. Cybersource Payer Authentication service is also backward-
compatible with 3D Secure 1.0.

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 specific data to your API requests to Cybersource.
 Validate the necessary data.
 Provide the additional data to the authorization request.
 Modify your website to help the customer understand the process.

Payer Authentication Using the SCMP API | 17

 Chapter 1 Introducing Payer Authentication

Integrating Payer Authentication

into Your Business
You can integrate payer authentication services into your existing business processes
whether you are currently using 3D Secure 1.0 or are new to payer authentication.

Four types of integration are available:

 Cardinal Cruise Direct Connection API
 SDK integration for your mobile application
 Hybrid integration
 Standard integration

If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.

The SDK integration is designed for 3D Secure 2.x transactions only.

The Cardinal Cruise Direct Connection API is the recommended integration method.

If you are currently using 3D Secure 1.0, see Chapter 4, "Upgrading Your
Payer Authentication Implementation," on page 60.

You can also use Secure Acceptance to enable 3D Secure 2.x for payer authentication
services. For more information, see "Using Secure Acceptance with Payer
Authentication."

Payer Authentication Using the SCMP API | 18

 Chapter 1 Introducing Payer Authentication

Implementing 3D Secure 2.x

Scenario 1: You are a New Merchant

Step 1 Contact your Cybersource account manager or sales manager to learn more about 3D
Secure 2.x and PSD2.

Step 2 Set up your merchant ID with Cybersource.

a Contact Customer Support to enable 3D Secure 2.x for the desired card type,
currencies, and acquiring bank. For details, see "Required Merchant Information."
You must request additional services such as payments using Secure Acceptance at
this time; you can request additional services such as token management as well.
b Log in to the Business Center to obtain the API keys for implementation.

Step 3 Implement 3D Secure 2.x.

 Using Cybersource SCMP API:
a Use the Cardinal Cruise Direct Connection API.
b Configure your system to request the Check Enrollment and Validate
Authentication services. Include the required API fields in your request and
consider including optional fields based on your business needs.
For more information, see the "Required Merchant Information" section and
Chapter 2, "Implementing Cardinal Cruise Direct Connection API Payer
Authentication," on page 23.
You can configure your system to request payment services through Cybersource
along with your payer authentication for 3D Secure 2.x; however, it is not required.

Step 4 Test your 3D Secure 2.x services.

This testing ensures that you understand the possible use cases as part of
implementation.
Refer to Chapter 5, "Testing Payer Authentication Services," on page 64 and run the test
cases in "Test Cases for 3D Secure 2.x."

Step 5 Configure your account for production.

a Request a boarding form from Customer Support for your processor or acquirer.
b Complete the boarding form with required information including your Cybersource
merchant ID, your acquirer merchant ID, and BIN information for all chosen card
types. For details, see "Required Merchant Information."

Payer Authentication Using the SCMP API | 19

 Chapter 1 Introducing Payer Authentication

Scenario 2: You Use the Cybersource SCMP API and Payer

Authentication Services for 3D Secure 1.0

Step 1 Contact your Cybersource account manager, sales manager, or technical account
manager to learn more about 3D Secure 2.x and PSD2.

Step 2 Configure your test merchant ID with Cybersource.

a Contact Customer Support to make the necessary configuration changes to enable
3D Secure 2.x for the desired card type and currencies.
b Log in to the Business Center to obtain the API keys for implementation.

Step 3 Implement 3D Secure 2.x. by migrating to the Hybrid integration.

a Add the CardinalCommerce JavaScript code to your checkout page.
b Configure your system to request the Check Enrollment and Validate Authentication
services. Include the required API fields in your request and consider including
optional fields based on your business needs.
For more information, see Chapter 4, "Upgrading Your Payer Authentication
Implementation," on page 60.
You can configure your system to request payment services through Cybersource
along with your payer authentication for 3D Secure 2.x; however, it is not required.

Step 4 Test your 3D Secure 2.x services.

This testing ensures that you understand the possible use cases as part of
implementation.
Refer to Chapter 5, "Testing Payer Authentication Services," on page 64 and run the test
cases in "Test Cases for 3D Secure 2.x."

Step 5 Configure your account for production. Repeat Steps 2-4 for the production environment.

Payer Authentication Using the SCMP API | 20

 Chapter 1 Introducing Payer Authentication

Scenario 3: You Want to Integrate Using an SDK for your

Mobile Application

Step 1 Contact your Cybersource account manager, sales manager, or technical account
manager to learn more about 3D Secure 2.x and PSD2.

Step 2 Configure your test merchant ID with Cybersource.

a Contact Customer Support to make the necessary configuration changes to enable
3D Secure 2.x for the desired card type and currencies. For details, see "Required
Merchant Information."
b Log in to the Business Center to obtain the API keys for implementation.

Step 3 Implement 3D Secure 2.x.

You must use the Cybersource SCMP API as well as the SDK in order to implement a
native mobile application. SDKs are available for iOS or Android.
a Implement the SDK to handle authentication steps within the native application. The
SDKs are the CardinalCommerce JavaScript equivalent for mobile applications.
For more information see Chapter 3, "Implementing SDK Payer Authentication," on
page 36.
b Configure your system to request the Check Enrollment and Validate Authentication
services. Include the required API fields in your request and consider including
optional fields based on your business needs.
You can configure your system to request payment services through Cybersource
along with your payer authentication for 3D Secure 2.x; however, it is not required.

Step 4 Test your 3D Secure 2.x services.

This testing ensures that you understand the possible use cases as part of
implementation.
Refer to Chapter 5, "Testing Payer Authentication Services," on page 64 and run the test
cases in "Test Cases for 3D Secure 2.x."

Step 5 Configure your account for production. Repeat Steps 2-4 for the production environment.

Payer Authentication Using the SCMP API | 21

 Chapter 1 Introducing Payer Authentication

Using Secure Acceptance with Payer Authentication

Secure Acceptance offers the ability to enable 3D Secure 2.x for payer authentication
services. You can choose when to upgrade by selecting the option in your Secure
Acceptance profile in the Business Center.

For more information on implementing Secure Acceptance with payer authentication, see
the Secure Acceptance Hosted Checkout Integration Guide or Secure Acceptance
Checkout API Integration Guide.

Required Merchant Information

Before using Cybersource Payer Authentication services in production, you must contact
Customer Support to provide information about your company and your acquiring bank so
that Cybersource can configure your account to implement these services.

You must provide the information listed in Table 1 to Cybersource before payer
authentication services can be enabled:

Table 1 Merchant Information Required for Payer Authentication Services

Information Description
About your company  Your Cybersource merchant ID.
 URL of your company’s website, for example:
http://www.example.com
 Two-character ISO code for your country.
 3D Secure requestor ID (optional)
 3D Secure requestor name (optional)
 Merchant category code
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, Diners payment card company for which you are configured:
Club, Discover, China
 6-digit BIN numbers.
UnionPay, and Elo information
 Acquirer merchant ID: merchant ID assigned by your
Acquirer merchant ID
acquirer.
 All currencies that you are set up to process.

Payer Authentication Using the SCMP API | 22

 CHAPTER
Implementing Cardinal
Cruise Direct Connection
2
API Payer Authentication
The Cardinal Cruise Direct Connection API supports 3D Secure 2.x and is backward-
compatible with 3D Secure 1.0 when the issuer, acquirer, or both, are not ready for 2.x.
This integration allows you to use an iframe to complete the device profiling and 3D
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. However, the
CardinalCommerce JavaScript is hosted and contained in the iframe and does not directly
access your webpage.

Prerequisites
Notify your Cybersource account representative that you want to implement payer
authentication (3D Secure) using the Cardinal Cruise Direct Connection API. Give them
the Cybersource merchant ID that you will use for testing. For more information, see
"Required Merchant Information," page 22.

Before you can implement payer authentication services, your business team must
contact your acquirer and Cybersource to establish the service. Your software
development team should become familiar with the API fields and technical details of this
service.

After Implementation and Before Go Live

Use the test cases to test your preliminary code and make appropriate changes. See
Chapter 5, "Testing Payer Authentication Services," on page 64.

Ensure that your account is configured for production.

Payer Authentication Using the SCMP API | 23

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Process Flow for Cardinal Cruise Direct

Connection API

Step 1: Payer Authentication Setup Service

The Payer Authentication Setup service is called on the server side after the customer
enters their payment information. Request the Payer Authentication Setup service
separately without including other Cybersource services.

Request Fields
To request the Payer Authentication Setup service, you must send the customer’s card
number, encrypted payment data, transient token, or TMS token for digital wallet
transactions, in addition to other fields. The request fields may include:

 customer_cc_number
 encrypted_payment_data
 encrypted_payment_descriptor
 subscription_id
 transient_token

The card_type field is required when card type is Cartes Bancaires.

Important Response Fields

 pa_access_token is used in "Step 2: Device Data Collection Iframe."

 pa_setup_pa_device_data_collection_url is used in "Step 2: Device Data Collection

Iframe."

 pa_setup_pa_reference_id is used in "Step 3: Payer Authentication Check Enrollment

Service."

Field Definitions and Details

For further details on required and optional fields, see Appendix A, "API Fields," on
page 148.

Request and Response API Examples

For further details on examples, see Chapter C, "Request and Response Examples," on
page 189.

Payer Authentication Using the SCMP API | 24

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

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" and pass pa_access_token to the front end.

The hidden 10x10 pixel iframe is rendered to the browser in order to profile the customer
device. The response depends on the card-issuing bank and can take 3 to 5 seconds. If
you proceed with the check enrollment service as described in "Step 3: Payer
Authentication Check Enrollment Service" before a response is received, Cybersource will
fall back to 3D Secure 1.0.

Building the Iframe

Iframe Parameters
 Form POST Action: The URL posted to the iframe is from the pa_setup_pa_device_
data_collection_url response field discussed in "Step 1: Payer Authentication Setup
Service."

 JWT POST Parameter: Use the value from the pa_access_token response field
discussed in "Step 1: Payer Authentication Setup Service."

Initiate the Device Data Collection Iframe

Initiate a form POST in a hidden iframe and send to the device data collection URL. See
Example 1.

Place the following HTML anywhere inside the <body> element of the checkout page.
Note that you must 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."

Example 1 Initiate the Device Data Collection Iframe

<iframe name=”ddc-iframe” height="10" width="10" style="display: none;">

</iframe>
<form id="ddc-form" target=”ddc-iframe” method="POST"
action="https://centinelapistag.cardinalcommerce.com/V1/Cruise/
Collect">
<input type="hidden" name="JWT" value="
eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YWZiNGRkY2ZmNjI2YjIzNzA2OWZhM2QiLCJpYX
QiOjE1OTExMTgyNzIsImV4cCI6MTU5MTEyNTQ3MiwianRpIjoiNWU4MDg5MGEtN2UyNi00Z
mI3LThiYTUtNjQ2ZDU0NjJiMzBkIiwiUGF5bG9hZCI6eyJBY3Rpb25Db2RlIjoiU1VDQ0VT
UyIsIlNlc3Npb25JZCI6IjY0ZTY2NjQ4LTFkYzYtNDZjMS1hNGYzLTBkYzE2MzQwZmFmMTA
iLCJFcnJvck51bWJlciI6MCwiRXJyb3JEZXNjcmlwdGlvbiI6IlN1Y2Nlc3MifX0.j8EPWE
EDf85hYQcxFzXxmHqHFTlptSQITJgfBGtLLjA" />
</form>

Payer Authentication Using the SCMP API | 25

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Add JavaScript to 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 Example 2. The JavaScript invokes the iframe form POST
automatically when the window loads. You may also choose to submit the form at a
different time, but you must do it before requesting the check enrollment service.

Example 2 JavaScript to Invoke the Iframe Form POST

<script>
window.onload = function() {
var ddcForm = document.querySelector('#ddc-form');
if(ddcForm) // ddc form exists
ddcForm.submit();
}
</script>

Listen For the Device Data Collection URL Response

Receiving the response indicates that the device data collection URL has completed its
processing. The response is an event callback that contains a message with the status of
the device data collection process.

Note that the event.origin URL is variable depending on your environment:

 Test: https://centinelapistag.cardinalcommerce.com

 Production: https://centinelapi.cardinalcommerce.com

See Example 3 to understand how to subscribe to the event and add JavaScript to receive
the response from the device data collection iframe. Place the JavaScript after the closing
</body> element.

Example 3 Listen for Device Data Collection Response

<script>
window.addEventListener("message", (event) => {
//{MessageType: "profile.completed", Session Id: "0_57f063fd-659a-
4779-b45b-9e456fdb7935", Status: true}
if (event.origin === "https://centinelapistag.cardinalcommerce.com") {
let data = JSON.parse(event.data);
console.log('Merchant received a message:', data);
}
if (data !== undefined && data.Status) {
console.log('Songbird ran DF successfully');
}
}, false);
</script>

Payer Authentication Using the SCMP API | 26

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Example 4 shows a response payload from the event. None of the data returned must be
stored for future use.

Example 4 Event Listener Callback Payload

{
"MessageType": "profile.completed",
"Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",
"Status": true
}

Step 3: Payer Authentication Check Enrollment

Service
After device collection completes, request the Payer Authentication Check Enrollment
service to determine if step-up authentication is needed.

Request Fields
 pa_reference_id field is mapped from the pa_setup_pa_reference_id field as
discussed in "Step 1: Payer Authentication Setup Service."

 pa_return_url is set to the URL to POST the results as discussed in "Step 4: Step-Up
IFrame."

To request the Payer Authentication Check Enrollment service, you must send the
customer’s card number, encrypted payment data, transient token, or TMS token for digital
wallet transactions. The request fields may include:

 customer_cc_number
 encrypted_payment_data
 encrypted_payment_descriptor
 subscription_id
 transient_token

The following fields are required:

 amount or grand_total_amount
 bill_address1
 bill_city
 bill_country
 bill_state
 bill_zip
 card_type

Payer Authentication Using the SCMP API | 27

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

 currency
 customer_cc_expmo
 customer_cc_expyr
 customer_email
 customer_firstname
 customer_lastname
 ics_applications
 merchant_id
 merchant_ref_number
 pa_reference_id
 pa_return_url

You can send additional request data in order to reduce your issuer step-up authentication
rates. It is best to send all available fields. However, do not send dummy data if you do not
have data for the field.
The size of the step-up iframe discussed in "Step 4: Step-Up IFrame" can vary depending
on the 3D Secure version of the transaction (1.0 or 2.x ). For 3D Secure 2.x transactions,
you can send the size of the challenge window in the pa_acs_window_size request field.

However, requesting a specific acsWindowSize does not guarantee this size. Parsing the
PAReq as described in "Step 4: Step-Up IFrame" determines the actual size.

Field Definitions and Details

For further details on required and optional fields, see Appendix A, "API Fields," on
page 148.

Combining Services
You can use the enrollment check and card authorization services in the same request or
in separate requests. Using the same request is recommended.

 Same request: Cybersource attempts to authorize the card after authentication if

step-up payer authentication is not required. In this case, the field values that are
required in order to prove that you attempted to check enrollment are passed
automatically to the authorization service. If step-up authentication is required,
processing stops to allow completion, and authorization is not called. This integration
method is recommended.

 Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).

Payer Authentication Using the SCMP API | 28

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Table 2 lists these fields.

Table 2 Enrollment Check and Response Fields

Identifier Enrollment Check Response Card Authorization

Field Request Field
E-commerce indicator pa_enroll_e_commerce_indicator e_commerce_indicator
Collection indicator pa_enroll_ucaf_collection_indicator ucaf_collection_indicator
(Mastercard only)
Result of the enrollment pa_enroll_veres_enrolled veres_enrolled
check for Asia, Middle
East, and Africa Gateway
3D Secure version pa_enroll_specification_version pa_specification_version
Directory server pa_enroll_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Interpreting the Response

The responses are similar for all card types. See Appendix C, "Request and Response
Examples," on page 189 for examples of enrollment responses.

 Enrolled cards

You receive reply flag DAUTHENTICATE if the customer’s card is enrolled in a payer
authentication program. When you receive this response, further authentication steps
are required. Proceed to "Step 4: Step-Up IFrame."

 Cards not enrolled, or step-up authentication not required

You receive reply flag SOK in the following cases:

 When the account number is not eligible for a payer authentication program or
when step-up authentication is not required. The other services in your request
are processed normally.

If you are making separate enrollment and authorization calls, you must include
pertinent payer authentication data in the authorization request to receive liability
shift protection.

 When 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 reply flag SOK, you receive liability shift
protection.

Payer Authentication Using the SCMP API | 29

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Important Response Fields

If you receive reply flag DAUTHENTICATE, you also receive the following fields:
 pa_step_up_url discussed in "Step 4: Step-Up IFrame."
 pa_access_token discussed in "Step 4: Step-Up IFrame."

Field Definitions and Details

For further details on required and optional fields, see Appendix A, "API Fields," on
page 148.

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." You only need to
perform "Step 4: Step-Up IFrame" if Step 3 indicates step-up authentication is required.

The iframe manages customer interaction with the card-issuing bank’s Access Control
Server (ACS) and 3D Secure version compatibility for 3D Secure 1.0 and 3D Secure 2.x.

Building the Iframe

Iframe Parameters
 Form POST Action: The URL posted by the iframe is from the pa_step_up_url
response field discussed in "Step 3: Payer Authentication Check Enrollment Service."

 JWT POST Parameter: Use the value from the pa_access_token response field
discussed in "Step 3: Payer Authentication Check Enrollment Service."

 MD POST Parameter: Merchant-defined data returned in the response. This field is

optional.

 Iframe height and width:

 3D Secure 1.0 uses a standard size of 400 by 400 pixels.

 For 3D Secure 2.x:
- Use the pa_acs_window_size request field to request (but not guarantee) a
specific window size.
- Use the pa_enroll_pareq response field to determine iframe dimensions by
Base64 decoding the string and cross-referencing the challengeWindowSize
value with the corresponding size.

Payer Authentication Using the SCMP API | 30

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Table 3 lists these values.

Table 3 Challenge Window Size Value and Corresponding Size

Challenge Window Size Value Step-Up Iframe Dimensions (Width x Height)

01 250 x 400
02 390 x 400
03 500 x 600
04 600 x 400
05 Full screen

See Example 5 for the decoded value.

Example 5 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"
}

Create the Iframe

Create the iframe to send a POST request to the step-up URL. See Example 6.

Example 6 Send a POST Request to 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="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmNmFmMTRmOS04YWR
jLTRiNzktOGVkYS04YWVlMTI2NTkzZTEiLCJpYXQiOjE1OTYwNTEyNzYsImlzcyI6IjVkZD
gzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5NjA1NDg3NiwiT3JnVW5pdElkIjoiN
TVlZjNmNTZmNzIzYWE0MzFjOTlkNTRiIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczov
LzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWI
vY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSn
RaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5W
Vc1elNVUWlPaUpsTkdKaVpqazNNeTFqTW1FeUxUUTNOREF0T1RWak5DMWpNVGhoTVRNeE16
TmlPRFFpTENKaFkzTlVjbUZ1YzBsRUlqb2lNVGMzT0RFM016SXROREk1TVMwME1HUmlMVGx
oTkRndE1ESm1OREpoTlRZd1lqYzVJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNk
lqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiQnh5a0hYVEp4M1JuNHBGWnF1bjAifSwiT2JqZ
WN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9taWNoYWVsdGF5bG9y
LmlvL2N5YnMvc3RvcmVEZW1vL3B1YmxpYy9saXN0ZW5lci5weSJ9.H8j-VYCJK_
7ZEHxGz82_IwZGKBODzPaceJNNC99xZRo" /> <input type="hidden" name="MD"
value="optionally_include_custom_data_that_will_be_returned_as_is”/> </
form>

Payer Authentication Using the SCMP API | 31

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body> tag (see Example 7). The JavaScript invokes the iframe form POST
automatically when the window loads. You may also choose to submit the form at a
different time, but you must do it before requesting the validation service.

Example 7 JavaScript to Invoke the Iframe Form POST

<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, you get the session back through the
pa_return_url response field specified in "Step 3: Payer Authentication Check Enrollment
Service." The payload sent to the return URL is URL-encoded and Base64-encoded (see
Example 8).

The response sent back to the return URL contains the following:

 Transaction ID: (pa_enroll_authentication_transaction_id response field). This is

used in "Step 5: Payer Authentication Validation Service."

 MD: merchant data returned if present in the POST to step-up URL. Otherwise, null.

Example 8 POST to Return URL

TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null

Payer Authentication Using the SCMP API | 32

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Step 5: Payer Authentication Validation Service

When you receive the response as discussed in "Step 4: Step-Up IFrame," make a
validation call to verify that the customer successfully authenticated.

Request Fields
 pa_authentication_transaction_id field is mapped from the pa_enroll_
authentication_transaction_id field in "Step 4: Step-Up IFrame."

Field Definitions and Details

For further details on required and optional fields, see Appendix A, "API Fields," on
page 148.

Request and Response API Examples

For further details on examples, see Chapter C, "Request and Response Examples," on
page 189.

Combining Services or Mapping Authorization Fields

Cybersource recommends that you request both payer authentication and card
authorization services at the same time. When you do so, Cybersource automatically
sends the correct information to your payment processor; Cybersource converts the
values of these fields to the proper format required by your payment processor:

 E-commerce indicator: pa_enroll_e_commerce_indicator

 CAVV: pa_validate_cavv
 AAV: pa_validate_ucaf_authentication_data
 XID: pa_enroll_xid and pa_validate_xid

If you request the services separately, you must manually include the validation result
values (Validation Check Response Fields) in the authorization service request (Card
Authorization Request Fields). To receive liability shift protection, you must ensure that
you pass all pertinent data for the card type and processor in your request. Failure to do
so can invalidate your liability shift for that transaction. Include the electronic commerce
indicator (ECI), the transaction ID (XID), the 3D Secure version, the directory server
transaction ID, and the following card-specific information in your authorization request:

 For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).

 For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.

Payer Authentication Using the SCMP API | 33

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

Depending on your card type and whether it is a 3D Secure 1.0 or 2.x transaction, you
might not receive the XID.

Table 4 lists these fields.

Table 4 Validation Check and Response Fields

Identifier Validation Check Response Card Authorization

Field Request Field
E-commerce indicator pa_validate_e_commerce_indicator e_commerce_indicator
Collection indicator pa_validate_ucaf_collection_ ucaf_collection_indicator
(Mastercard only) indicator
CAVV (Visa and American pa_validate_cavv cavv
Express only)
AAV (Mastercard only. pa_validate_ucaf_authentication_ ucaf_authentication_data
Known as UCAF) data
XID pa_validate_xid xid
3D Secure version pa_validate_sepcification_version pa_specification_version
Directory server pa_validate_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Interpreting the Response

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 that you receive. The
responses are similar for all card types:

 Success:

You receive the reply flag SOK, and other service requests, including authorization,
are processed normally.

 Failure:

You receive the reply flag DAUTHENTICATIONFAILED, so the other services in your
request are not processed.

Payer Authentication Using the SCMP API | 34

 Chapter 2 Implementing Cardinal Cruise Direct Connection API Payer Authentication

 Error:

If you receive an error from the payment card company, process the order according
to your business rules. If the error occurs frequently, report it to Customer Support. If
you receive a Cybersource 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. You must ensure that all messages that display to customers are
accurate, complete, and that they address all possible scenarios for enrolled and
nonenrolled cards. For example, if the authentication fails, a message such as the
following 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.

Payer Authentication Using the SCMP API | 35

 CHAPTER
Implementing SDK Payer
Authentication
3

This chapter summarizes the process of integrating SDK Payer Authentication services
into your mobile application. Cybersource Payer Authentication services use the Cardinal
Mobile SDK for iOS or Android to facilitate the authentication.

The SDK is only designed to handle 2.x transactions. If a 1.0 transaction occurs, you must
include functionality to open up a WebView.

Implementation Overview
Notify your Cybersource account representative that you want to implement payer
authentication (3D Secure). Give them the Cybersource merchant ID that you will use for
testing. For more information, see "Required Merchant Information," page 22.

Implementation tasks include:

 Download, import, and configure the Cardinal Mobile SDK for either iOS or Android

 For each purchase request:

 Build the authentication request

 Make a back-end, server-to-server call to request the ics_pa_enroll: Payer
Authentication Enrollment Check service
 Invoke the authentication
 Handle declines
 Make another back-end, server-to-server call to request the following services:
- ics_pa_validate: Payer Authentication Validation
- ics_auth: Card Authorization service (optional)

 Use the test cases to test your preliminary code and make appropriate changes. See
Chapter 5, "Testing Payer Authentication Services," on page 64.

 Ensure that your account is configured for production.

Payer Authentication Using the SCMP API | 36

 Chapter 3 Implementing SDK Payer Authentication

Process Flow for SDK Integration

1 You generate a JSON Web Token (JWT).

2 Contact CardinalCommerce Customer Support for instructions to register for an API key.

3 Download and import the Cardinal Mobile SDK for either iOS or Android.

4 Set up your build environment.

5 Configure your SDK.

6 Call Cardinal session.setup().

7 Create an API call to your merchant server to request the Enrollment Check service,
passing in transaction details and the pa_reference_id request field.

8 If the issuing bank does not require authentication, you receive the following information in
the Enrollment Check response:
 E-commerce indicator
 CAVV (all card types except Mastercard)
 AAV (Mastercard only)
 Transaction ID
 3D Secure version
 Directory server transaction ID

9 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.

10 The Cardinal Mobile SDK displays the authentication window, and the customer enters the
authentication information.

11 The bank validates the customer credentials and a JWT is returned by the SDK in the
onValidated callback that the merchant is required to validate server-side for security
reasons.

12 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 pa_
authentication_transaction_id request field. You receive the e-commerce indicator,
CAVV or AAV, transaction ID, 3D 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," page 57.

Payer Authentication Using the SCMP API | 37

 Chapter 3 Implementing SDK Payer Authentication

Before You Begin

Before you can implement payer authentication services, your business team must
contact your acquirer and Cybersource to establish the service. Your software
development team should become familiar with the API fields and technical details of this
service.

Implementing the SDK in your mobile application requires either Android or iOS platform
application programming skills. Android API 19 or iOS 8 and XCode 8 are required.

Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). To obtain
credentials to generate your API keys, contact Cybersource Customer Support.

You will receive an email with your user name and a temporary password. Your user name
will be in the following format:

cybersource_merchant name_contact name

for example, cybersource_britishairways_peter

Once your receive your credentials, log in to your JFrog account and update your
temporary password. Follow the process below to generate your API key.

To generate your API key:

Step 1 Log in to to your JFrog account.

Step 2 In the top-right of the JFrog Platform, select the Welcome drop-down menu and click Edit
Profile.

Step 3 Enter your password and click Unlock.

Step 4 Under Authentication Settings, click Generate API Key.

Payer Authentication Using the SCMP API | 38

 Chapter 3 Implementing SDK Payer Authentication

Create the JSON Web Token (JWT)

The Cardinal Mobile SDK integration uses JWTs as the method of authentication.

For security reasons, all JWT creation must be done on the server side.

When creating the JWT, use your company API Key as the JWT secret. You can use any
JTW library that supports JSON Web Signature (JWS). For further information about
JWTs, see https://jwt.io/.

JWT Claims
Table 5 lists the standard claims that can be used in a JWT claim set.

Table 5 JWT Claims

Claim Name Description

Required Note Each claim key is case sensitive.
jti JWT ID - unique identifier for the JWT. This field should
change each time a JWT is generated.
iat Issued at - the epoch time in seconds beginning when the
JWT is issued. This value indicates how long a JWT has
existed and can be used to determine if it is expired.
iss Issuer - identifier of who is issuing the JWT. Contains the
API key identifier or name.
OrgUnitId The merchant SSO Org Unit Id.

Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Cardinal Mobile SDK and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.

exp Expiration - the numeric epoch time in which the JWT

should be considered expired. This value is ignored if it is
more than 4 hours.

Payer Authentication Using the SCMP API | 39

 Chapter 3 Implementing SDK Payer Authentication

JWT Examples
Example 9 shows the JSON content of a basic JWT payload that passes an object within
the payload claim.

Example 9 Raw JWT

{
"jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e",
"iat": 1448997865,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": {
"OrderDetails": {
"OrderNumber": "0e5c5bf2-ea64-42e8-9ee1-71fff6522e15",
"Amount": "1500",
"CurrencyCode": "840"
}
},
"ObjectifyPayload": true,
"ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15",
"exp": 1449001465,
}

Example 10 shows the JSON content of a basic JWT payload that passes a string within
the payload claim.

Example 10 Stringified JWT

{
"jti": "29311a10-5048-11e6-8c35-8789b865ff15",
"iat": 1448997875,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": "{\"OrderDetails\":{\"OrderNumber\":\"19ec6910-5048-11e6-
8c35-8789b865ff15\",\"Amount\":\"1500\",\"CurrencyCode\":\"840\"}}",
"ObjectifyPayload" false
"ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15"
"exp":1449001465,
}

Payer Authentication Using the SCMP API | 40

 Chapter 3 Implementing SDK Payer Authentication

Using the Android SDK

Update the Gradle Build Properties

In Android Studio, open the app directory (which can also be labeled Module: app) and
open the build.gradle file. Make sure that you edit the Gradle file that is located in the app
directory. Add the contents shown in Example 11 to the Gradle file.

Example 11 Gradle Build Properties

repositories {
...
maven {
url "https://cardinalcommerceprod.jfrog.io/artifactory/android"
credentials {
username ''//Artifactory username
password ''//Artifactory user API Key
}
}
}
dependencies {
...
//Cardinal Mobile SDK
implementation
'org.jfrog.cardinalcommerce.gradle:cardinalmobilesdk:2.2.5-1'
}

If your project uses Progurad, add the lines shown in Example 12 to the proguard-
rules.pro file.

Example 12 Progurad

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

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

Payer Authentication Using the SCMP API | 41

 Chapter 3 Implementing SDK Payer Authentication

Configure the Android SDK

Get the instance of the cardinal object by Cardinal.getInstance(). You can set multiple
configuration options in the SDK; if not specified, they are set to default. See Example 13
to complete Cardinal.configure().

For more details on configuration options, see Table 6.

Example 13 Cardinal.configure

private Cardinal cardinal = Cardinal.getInstance();

@Override
protected void onCreate(Bundle savedInstanceState) {

CardinalConfigurationParameters cardinalConfigurationParameters = new

CardinalConfigurationParameters();

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

cardinalConfigurationParameters.setUiType(CardinalUiType.BOTH);

UiCustomization yourUICustomizationObject = new

UiCustomization();

cardinalConfigurationParameters.setUICustomization(yourUICustomizationO
bject);

cardinal.configure(this,cardinalConfigurationParameters);
}

Table 6 Android SDK Configuration Options

Method Description Default Values

setEnableDFSync On setting true, onSetupCompleted False
(boolean enableDFSync) will be called after device data
collected is sent to the server.
setEnableQuickAuth Sets enable quick auth false. False
(boolean enableQuickAuth)

Payer Authentication Using the SCMP API | 42

 Chapter 3 Implementing SDK Payer Authentication

Table 6 Android SDK Configuration Options (Continued)

Method Description Default Values

setEnvironment(Setting up Sets the environment to which the CardinalEnvironment.
Cardinal Mobile SDK - SDK must connect. PRODUCTION
Android- V
2.1#CardinalEnvironment
environment)
setProxyAddress(java.lang. Sets the proxy to which the SDK ““
String proxyAddress) must connect.
setRenderType(org.json.JS Sets renderLists all UI types that the JSONArray rType = new
ONArray renderType) device supports for displaying JSONArray();
specific challenge user interfaces
rType.put(Cardinal
within the SDK.
RenderType.OTP);
rType.put(Cardinal
RenderType.SINGLE_
SELECT);
rType.put(Cardinal
RenderType.MULTI_
SELECT);
rType.put(Cardinal
RenderType.OOB);
rType.put(Cardinal
RenderType.HTML);
setTimeout(int timeout) Sets the maximum amount of time 8000
(in milliseconds) for all exchanges.
setUICustomization Sets UICustomization Device Default Values
(UiCustomization UI
Customization)
setUiType(CardinalUiType Sets all UI types that the device CardinalUiType.BOTH
uiType) supports for displaying specific
challenge user interfaces within the
SDK.

Payer Authentication Using the SCMP API | 43

 Chapter 3 Implementing SDK Payer Authentication

Set Up the Initial Call

Calling Cardinal.init() 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 pre-processing is complete. Use the code
example shown in Example 14 for completing the cardinal.init().

Example 14 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 "Implementing SDK Payer Authentication" section for next steps.

Payer Authentication Using the SCMP API | 44

 Chapter 3 Implementing SDK Payer Authentication

Using the iOS SDK

Download and Import the SDK

Download the CardinalMobile.framework file using the cURL in Example 15.

Example 15 Download CardinalMobile.framework

curl -L -u <USER_NAME>
:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/
<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip
-o <LOCAL_FILE_NAME.EXT>

#Example:
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/
artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-
1.zip

Download the CardinalMobile.xcframework file using the cURL in Example 16.

Example 16 Download CardinalMobile.xcframework

curl -L -u <USER_NAME>
:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/
<VERSION>-<BUILD_NUMBER>/CardinalMobileiOSXC.zip
-o <LOCAL_FILE_NAME.EXT>

#Example:
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/
artifactory/ios/2.2.5-1/CardinalMobileiOSXC.zip" -o
cardinalmobile2.2.5-1.zip

In your XCode project, drag the CardinalMobile.framework file into the Frameworks group
in your Xcode Project. (Create the group if it 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 files are now available for linking in your project.

Payer Authentication Using the SCMP API | 45

 Chapter 3 Implementing SDK Payer Authentication

Set Up Your Build Environment

Step 1 Open Xcode and choose your project in the source list to the left of the main editor area.

Step 2 Select your application under the Targets section and open the General tab.

Step 3 Expand the Embedded Binaries section and click the small plus (+) at the bottom of the
list.

Step 4 Add CardinalMobile.framework from the list.

Payer Authentication Using the SCMP API | 46

 Chapter 3 Implementing SDK Payer Authentication

Configure the iOS SDK

Create a new instance of the cardinal object by CardinalSession new. You can set multiple
configuration options in the SDK; if not specified, they are set to default. See Example 17
or Example 18 to complete the iOS SDK configuration.

For more details on configuration options, see Table 7.

Objective-C Example
Example 17 CardinalSession new (iOS SDK - Objective-C)

#import <CardinalMobile/CardinalMobile.h>

CardinalSession *session;

//Setup can be called in viewDidLoad

- (void)setupCardinalSession {
session = [CardinalSession new];
CardinalSessionConfiguration *config = [CardinalSessionConfiguration
new];
config.deploymentEnvironment = CardinalSessionEnvironmentProduction;
config.timeout = CardinalSessionTimeoutStandard;
config.uiType = CardinalSessionUITypeBoth;

UiCustomization *yourCustomUi = [[UiCustomization alloc] init];

//Set various customizations here. See "iOS UI Customization"
documentation for detail.
config.uiCustomization = yourCustomUi;

CardinalSessionRenderTypeArray *renderType =
[[CardinalSessionRenderTypeArray alloc] initWithObjects:
CardinalSessionRenderTypeOTP,
CardinalSessionRenderTypeHTML,
nil];
config.renderType = renderType;

config.enableQuickAuth = false;
[session configure:config];
}

Payer Authentication Using the SCMP API | 47

 Chapter 3 Implementing SDK Payer Authentication

Swift Example
Example 18 CardinalSession new (iOS SDK - Swift)

import CardinalMobile

var session : CardinalSession!

//Setup can be called in viewDidLoad

func setupCardinalSession{
session = CardinalSession()
var config = CardinalSessionConfiguration()
config.deploymentEnvironment = .production
config.timeout = 8000
config.uiType = .both

let yourCustomUi = UiCustomization()

//Set various customizations here. See "iOS UI Customization"
documentation for detail.
config.uiCustomization = yourCustomUi

config.renderType = [CardinalSessionRenderTypeOTP,
CardinalSessionRenderTypeHTML]
config.enableQuickAuth = true
session.configure(config)
}

Table 7 iOS SDK Configuration Options

Method Description Default Values Possible Values

deploymentEnvironment The environment to CardinalSessionEnviron CardinalSessionEnvironment
which the SDK connects. mentProduction Staging
CardinalSessionEnvironment
Production
timeoutInMilliseconds Maximum amount of time 8000
(in milliseconds) for all
exchanges.
uiType Interface types that the CardinalSessionUIType CardinalSessionUITypeBoth
device supports for Both
CardinalSessionUITypeNative
displaying specific
challenge user interfaces CardinalSessionUITypeHTML
within the SDK.

Payer Authentication Using the SCMP API | 48

 Chapter 3 Implementing SDK Payer Authentication

Table 7 iOS SDK Configuration Options (Continued)

Method Description Default Values Possible Values

renderType List of all the render [CardinalSessionRender CardinalSessionRenderType
types that the device TypeOTP, OTP
supports for displaying
CardinalSessionRender CardinalSessionRenderType
specific challenge user
TypeHTML, HTML
interfaces within the
SDK. CardinalSessionRender CardinalSessionRenderType
TypeOOB, OOB
CardinalSessionRender CardinalSessionRenderType
TypeSingleSelect, SingleSelect
CardinalSessionRender CardinalSessionRenderType
TypeMultiSelect] MultiSelect
proxyServerURL Proxy server through nil
which the Cardinal SDK
Session operates.
enableQuickAuth Enable Quick false
Authentication
uiCustomization Set Custom nil
UICustomization for SDK
Controlled Challenge UI.
enableDFSync Enable DF Sync to get false
onSetupCompleted
called after collected
device data is sent to the
server.

Payer Authentication Using the SCMP API | 49

 Chapter 3 Implementing SDK Payer Authentication

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 pre-processing is complete.
Use the code example shown in Example 19 or Example 20 for completing the cardinal
session setup. The function call must be placed in your Checkout ViewController.

Objective-C Example
Example 19 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
}];

Swift Example
Example 20 Cardinal session setup (iOS SDK - Swift)

let accountNumberString = "1234567890123456"

let jwtString = "INSERT_YOUR_JWT_HERE"

session.setup(jwtString: jwtString, completed: { (consumerSessionId:

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

Payer Authentication Using the SCMP API | 50

 Chapter 3 Implementing SDK Payer Authentication

Implementing SDK Payer Authentication

Requesting the Check Enrollment Service (SDK)

After the SDK completes the device collection from your mobile application and once the
customer clicks the ‘buy now’ button, you must make a back-end, server-to-server call to
request the Enrollment Check service.

The Check Enrollment service verifies that the card is enrolled in a card authentication
program. The following fields are required:

 amount or grand_total_amount
 bill_address1
 bill_city
 bill_country
 bill_state
 bill_zip
 card_type
 currency
 customer_cc_expmo
 customer_cc_expyr
 customer_cc_number
 customer_email
 customer_firstname
 customer_lastname
 ics_applications
 merchant_id
 merchant_ref_number
 pa_reference_id

You can send additional request data in order to reduce your issuer step-up
authentication rates. It is best to send all available fields.

For further details on required and optional fields, see "Request-Level Fields," page 149.

Payer Authentication Using the SCMP API | 51

 Chapter 3 Implementing SDK Payer Authentication

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 if your customer is not
enrolled in a payer authentication program. In this case, the field values that are
required in order to prove that you attempted to check enrollment are passed
automatically to the authorization service. If authentication is required, processing
automatically stops.

 Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).

Table 8 lists these fields.

Table 8 Enrollment Check and Response Fields

Identifier Enrollment Check Response Card Authorization

Field Request Field
E-commerce indicator pa_enroll_e_commerce_indicator e_commerce_indicator
Collection indicator pa_enroll_ucaf_collection_indicator ucaf_collection_indicator
(Mastercard only)
Result of the enrollment pa_enroll_veres_enrolled veres_enrolled
check for Asia, Middle
East, and Africa Gateway
3D Secure version pa_enroll_specification_version pa_specification_version
Directory server pa_enroll_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Interpreting the Response

The responses are similar for all card types. See Appendix C, "Request and Response
Examples," on page 189 for examples of enrollment responses.

 Enrolled Cards

You receive response flag DAUTHENTICATE if the customer’s card is enrolled in a

payer authentication program. When you receive this response, you can proceed to
validate authentication.

Payer Authentication Using the SCMP API | 52

 Chapter 3 Implementing SDK Payer Authentication

 Cards Not Enrolled

You receive response flag SOK in the following cases:

 When the account number is not enrolled in a payer authentication program. The
other services in your request are processed normally.
 When payer authentication is not supported by the card type.

When you receive this response, you can proceed to card authorization.

Authenticating Enrolled Cards

In the response from the enrollment check service, confirm that you receive the following
fields and values:

 3D Secure version = 2.x

 VERes enrolled = Y
 PARes status = C

These values identify whether it is a 2.x transaction and that a challenge is required. If the
3D Secure version is 1.0, then the SDK is no longer applicable and you must open up a
WebView.

Once you validate these fields, you call Cardinal.cca_continue (Android SDK) or Cardinal
session continue (iOS SDK) in order for the SDK to perform the challenge between the
customer and the issuing bank.

Payer Authentication Using the SCMP API | 53

 Chapter 3 Implementing SDK Payer Authentication

Call Cardinal.cca_continue (Android SDK)

When you have verified that a customer’s card is enrolled in a card authentication
program, you must take the payload, and the pa_enroll_authentication_transaction_id
response field and include them in the Cardinal.cca_continue function in order to proceed
with the authentication session as shown in Example 21.

Example 21 Cardinal.cca_continue (Android SDK)

/**
* Cca continue.
*
* @param transactionId the transaction id
* @param payload the payload
* @param currentActivity the current activity
* @throws InvalidInputException the invalid input exception
* @throws JSONException the json exception
* @throws UnsupportedEncodingException the unsupported encoding
exception
*/
try {
cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", this, new
CardinalValidateReceiver() {
/**
* This method is triggered when the transaction
* has been terminated. This is how SDK hands back
* control to the merchant's application. This method will
* include data on how the transaction attempt ended and
* you should have your logic for reviewing the results of
* the transaction and making decisions regarding next steps.
* JWT will be empty if validate was not successful.
*
* @param validateResponse
* @param serverJWT
*/
@Override
public void onValidated(Context currentContext,
ValidateResponse validateResponse, String serverJWT) {
}
});
}
catch (Exception e) {
// Handle exception
}

Payer Authentication Using the SCMP API | 54

 Chapter 3 Implementing SDK Payer Authentication

Call Cardinal session continue (iOS SDK)

When you have verified that a customer’s card is enrolled in a card authentication
program, you must take the payload, and the pa_enroll_authentication_transaction_id
response field and include them in the Cardinal session continue function in order to
proceed 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. Example 22 or Example 24
show an example of class conforming to CardinalValidationDelegate protocol.

Objective-C Examples
Example 22 Cardinal session continue (iOS SDK - Objective-C)

@interface YourViewController()<CardinalValidationDelegate>{ //Conform

your ViewController or any other class to CardinalValidationDelegate
protocol

}
@end

@implementation YourViewController

/**
* This method is triggered when the transaction has
* been terminated.This is how SDK hands back
* control to the merchant's application. This method will
* include data on how the transaction attempt ended and
* you should have your logic for reviewing the results of
* the transaction and making decisions regarding next steps.
* JWT will be empty if validate was not successful
*
* @param session
* @param validateResponse
* @param serverJWT
*/
-(void)cardinalSession:(CardinalSession *)session
stepUpDidValidateWithResponse:(CardinalResponse *)validateResponse
serverJWT:(NSString *)serverJWT{

@end

Payer Authentication Using the SCMP API | 55

 Chapter 3 Implementing SDK Payer Authentication

If Continue is called in the same class, call the method shown in Example 23 to start
StepUpFlow.

Example 23 Cardinal.continue Call in the Same Class (Objective-C)

[session continueWithTransactionId: @"[TRANSACTION_ID]"

payload: @"[PAYLOAD]"
didValidateDelegate: self];

Swift Examples
Example 24 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 Example 25 to start
StepUpFlow.

Example 25 Cardinal.continue Call in the Same Class (Swift)

session.continueWith(transactionId: "[TRANSACTION_ID]", payload:

"[PAYLOAD]", validationDelegate: self)

The SDK displays the authentication window if necessary and the customer enters their
authentication information.

Payer Authentication Using the SCMP API | 56

 Chapter 3 Implementing SDK Payer Authentication

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 Example 26.

Example 26 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 pa_authentication_transaction_id request field

 Send the credit card information including the PAN, currency, and expiration date
(month and year).

The response that you receive contains the validation result.

Cybersource recommends that you request both payer authentication and card
authorization services at the same time. When you do so, Cybersource automatically
sends the correct information to your payment processor; Cybersource converts the
values of these fields to the proper format required by your payment processor:

 E-commerce indicator: pa_enroll_e_commerce_indicator

 CAVV: pa_validate_cavv
 AAV: pa_validate_ucaf_authentication_data
 XID: pa_enroll_xid and pa_validate_xid

Payer Authentication Using the SCMP API | 57

 Chapter 3 Implementing SDK Payer Authentication

If you request the services separately, you must manually include the validation result
values (Validation Check Response Fields) in the authorization service request (Card
Authorization Request Fields). To receive liability shift protection, you must ensure that
you pass all pertinent data for the card type and processor in your request. Failure to do
so may invalidate your liability shift for that transaction. Include the electronic commerce
indicator (ECI), the transaction ID (XID), the 3D Secure version, the directory server
transaction ID, and the following card-specific information in your authorization request:

 For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).

 For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.

Table 9 lists these fields.

Table 9 Validation Check and Response Fields

Identifier Validation Check Response Card Authorization

Field Request Field
E-commerce indicator pa_validate_e_commerce_indicator e_commerce_indicator
Collection indicator pa_validate_ucaf_collection_ ucaf_collection_indicator
(Mastercard only) indicator
CAVV (Visa and American pa_validate_cavv cavv
Express only)
AAV (Mastercard only. pa_validate_ucaf_authentication_ ucaf_authentication_data
Known as UCAF) data
XID pa_validate_xid xid
3D Secure version pa_validate_sepcification_version pa_specification_version
Directory server pa_validate_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Payer Authentication Using the SCMP API | 58

 Chapter 3 Implementing SDK Payer Authentication

Interpreting the Response

If the authentication fails, Visa, American Express, JCB, Diners Club, Discover,
China UnionPay, and Elo require that you do not accept the card. 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:

You receive the response flag SOK, and other service requests, including
authorization, are processed normally.

 Failure:

You receive the response flag DAUTHENTICATIONFAILED, so the other services in

your request are not processed.

 Error:

If you receive an error from the payment card company, process the order according
to your business rules. If the error occurs frequently, report it to Customer Support. If
you receive a Cybersource 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. You must ensure that all messages that display to customers are
accurate, complete, and that they address all possible scenarios for enrolled and
nonenrolled cards. For example, if the authentication fails, a message such as the
following 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.

Payer Authentication Using the SCMP API | 59

 CHAPTER
Upgrading Your
Payer Authentication
4
Implementation
This chapter provides information about upgrading to 3D Secure 2.x for merchants
currently using Cybersource Payer Authentication services.

Upgrading to 3D Secure 2.x

Benefits
3D Secure 2.x provides the following benefits:

 More secure transactions as additional data is available.

 3D Secure 2.x is backward compatible. Additional data will automatically be sent to

issuers as they upgrade to 3D 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 3D Secure 2.2 when it becomes available. 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 defined as they
become available.

Payer Authentication Using the SCMP API | 60

 Chapter 4 Upgrading Your Payer Authentication Implementation

PSD2 Impact
Upgrading to 3D Secure 2.x is necessary if you are affected by PSD2.

PSD2 requires additional security measures outlined in the Regulatory Technical

Standards (RTS) due to 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. It has
implications for merchants including:

 Two-factor authentication will be required for all electronic payments, although there
are exemptions to allow a frictionless flow.

 3-D Secure e-commerce merchants will have to integrate dynamic authentication

tools (such as 3D Secure 2.x).

If you are impacted by PSD2 changes, it is very important that you upgrade to 3D Secure
2.x.

Mandates
PSD2 includes mandates around strong customer authentication (SCA) and exemptions
and challenges. See the following page for more information on the mandates:

https://demos.cardinalcommerce.com/3DS_Info/Country_Mandates/index.html

Timelines
See the following page for PSD2 compliance timelines:

https://demos.cardinalcommerce.com/3DS_Info/Cardinal_Timelines/index.html

Recommended Integration
Four types of integration are available for 3D Secure 2.x:
 Cardinal Cruise Direct Connection API
 SDK integration for your mobile application
 Hybrid integration
 Standard integration

If you are currently using Payer Authentication services in your existing business
processes and need to upgrade to 3D Secure 2.x, Cybersource recommends using the
Cardinal Cruise Direct Connection API integration.

Payer Authentication Using the SCMP API | 61

 Chapter 4 Upgrading Your Payer Authentication Implementation

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 3D
Secure 2.x, the response includes a new value, the processor transaction ID.

For enrolled cards, include the 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 CAVV or AAV.

For more information about the Cardinal Cruise Direct Connection API, see Chapter 2,
Implementing Cardinal Cruise Direct Connection API Payer Authentication.

For details about the other integrations, see Chapter 3, Implementing SDK Payer
Authentication or Appendix H, Implementing Hybrid or Standard Payer Authentication.

If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.

Migration FAQ
Q: Do I need to send in a new JWT for each transaction?

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 pa_reference_id request field for the Check Enrollment service.

Payments.setupComplete returns a session ID and you can use that value for the pa_
reference_id request field for the Check Enrollment service.

Q: When will the Payer Authentication reports include the new fields for 3D 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.

Payer Authentication Using the SCMP API | 62

 Chapter 4 Upgrading Your Payer Authentication Implementation

Q: What testing should I conduct, to ensure that my code is working correctly?

A: Use the test cases ("Test Cases for 3D Secure 2.x," page 115) to test your preliminary
code and make the appropriate changes.

Q: How does 3D Secure 2.x authentication improve the experience for a customer who
uses a mobile or tablet device?

A: 3D Secure 2.x is agnostic to the device and you have control over the formatting of the
authentication form. 3D 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.

Payer Authentication Using the SCMP API | 63

 CHAPTER
Testing Payer
Authentication Services
5

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

Testing Process
Use the card number specified in the test with the card’s expiration date set to the month
of December and the current year plus three. For example, for 2021, use 2024. You also
need the minimum required fields 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 always 1234.

Depending on the user’s action, two results are possible:

 If the user submits the password for the enrolled card, you receive the URL of the
Access Control Server (ACS) where the customer can be authenticated.

 If the user clicks the Exit link and clicks OK in the verification window, authentication
does not occur.

Payer Authentication Using the SCMP API | 64

 Chapter 5 Testing Payer Authentication Services

Table 10 lists the response fields used in the test cases.

Table 10 Response Fields Used in the Enrollment Check Test Cases

Name Used in Test Cases API Field

ACS URL pa_enroll_acs_url
E-commerce indicator pa_enroll_e_commerce_indicator
ECI pa_enroll_eci
PAReq pa_enroll_pareq
proofXML pa_enroll_proofxml
Response flag pa_enroll_rflag
VERes enrolled pa_enroll_veres_enrolled
XID pa_enroll_xid

Authentication Validation
Table 11 lists only the response fields used in the test cases.

Table 11 Response Fields Used in the Authentication Validation Test Cases

Name Used in Test Cases API Field

Authentication result pa_validate_authentication_result
E-commerce indicator pa_validate_e_commerce_indicator
AAV (Mastercard only) pa_validate_ucaf_authentication_data
CAVV ((all card types except pa_validate_cavv
Mastercard)
Collection indicator pa_validate_ucaf_collection_indicator
ECI pa_validate_eci
PARes status pa_validate_pares_status
Response flag pa_validate_rflag
XID pa_validate_xid

Payer Authentication Using the SCMP API | 65

 Chapter 5 Testing Payer Authentication Services

Expected Results
These flowcharts summarize the payer authentication process based on the enrollment
status of the card and the subsequent customer experience with the authentication path.

Use this information with the test cases to determine how to process orders.

Figure 1 Authentication Path for Visa, American Express, JCB, Diners Club, Discover, China
UnionPay, and Elo

Payer Authentication Using the SCMP API | 66

 Chapter 5 Testing Payer Authentication Services

Figure 2 Authentication Path for Mastercard and Maestro

Payer Authentication Using the SCMP API | 67

 Chapter 5 Testing Payer Authentication Services

Test Cases for 3D Secure 1.0

Visa Secure
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.

Table 12 Possible Values for Visa Secure Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 vbv SOK

Recorded attempt to 1 06 vbv_ SOK

authenticate. attempted
Failure System error that prevents 6 1 —2 SOK
(Customer the completion of
not authentication: you can
responsible) proceed with authorization,
but there is no liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.
No response from the 07 internet
Directory Servers or Issuer
vbv_failure
because of a problem.
(processors:
AIBMS, Barclays,
Streamline, or
FDC Germany)
Invalid PARes. -1 — — DAUTHENTICATI
ONFAILED

Failure Authentication failed or 9 — — DAUTHENTICATI

(Customer cardholder did not complete ONFAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 68

 Chapter 5 Testing Payer Authentication Services

Test Case 1: Visa Secure Card Enrolled: Successful Authentication

Card Number 445653 With authentication window

00 0000 0007
445653 With 19-digit PAN
00 0000 0000 025
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator vbv
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 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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: PARes signature digest value
proceeding with authorization. mismatch. PARes message has been modified.
Details ACS URL URL value Authentication result -1
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.

Payer Authentication Using the SCMP API | 69

 Chapter 5 Testing Payer Authentication Services

Test Case 3: Visa Secure Card Enrolled: Attempts Processing

Card Number 445653 Without authentication window

00 0000 0106
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 1
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator vbv_attempted
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 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.
If you request the Validate Authentication and authorization services together, the process
described above occurs automatically. Test card 4000000000000127 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.

Payer Authentication Using the SCMP API | 70

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer  Issuer unable to perform authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value E-commerce indicator internet or 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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication.
authentication. Please authenticate before
 Payer cannot be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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.

Payer Authentication Using the SCMP API | 71

 Chapter 5 Testing Payer Authentication Services

Test Case 6: Visa Secure Card Enrolled: Unsuccessful Authentication (Customer Exited)

Card Number 445653

00 0000 0023
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  Customer prevents authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet or vbv_failure
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 72

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value E-commerce indicator internet or 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 9: Visa Secure Card Not Enrolled

Card Number 445653

00 0000 0056
Auth. Type Non-participating bank
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator vbv_attempted
ECI 06
proofXML proofXML value
VERes enrolled N
Action Submit your authorization request. Liability shift.

Payer Authentication Using the SCMP API | 73

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK
ics_pa_enroll service was successful.
Details E-commerce indicator internet or vbv_failure
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No liability shift.

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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet or 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.

Payer Authentication Using the SCMP API | 74

 Chapter 5 Testing Payer Authentication Services

Mastercard Identity Check

Table 13 Possible Values for Mastercard Identity Check and Maestro Response Fields

Result and Interpretation pa_validate_

authentication ucaf_ e_commerce_ rflag

_result collection_ indicator
indicator
Success Successful authentication. 0 2 spa 100

Recorded attempt to 1 1 spa 100

authenticate.
Authentication not completed. 1 0 spa 100

Failure System error (Issuer unable to 6 0 internet 100

(Customer perform authentication): you
not cannot authorize this card; no
responsible) liability shift.
Invalid PARes. -1 0 476
Failure Authentication failed or 9 0 – 476
(Customer cardholder did not complete
responsible) authentication.

Test Case 16: Mastercard Identity Check Card Enrolled: Successful Authentication

Card Number 520000 With authentication window

00 0000 0007
520000 Without authentication window
00 0000 0114
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The card is enrolled in payer authentication. ics_pa_validate service was successful.
Please authenticate before proceeding with
authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection indicator 2
VERes enrolled Y E-commerce indicator spa
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 required payer authentication values to your authorization request.

Payer Authentication Using the SCMP API | 75

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer Payer authentication problem: PARes
authentication. Please authenticate before signature digest value mismatch. PARes
proceeding with authorization. message has been modified.
Details ACS URL URL Authentication result -1
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.

Payer Authentication Using the SCMP API | 76

 Chapter 5 Testing Payer Authentication Services

Test Case 18: Mastercard Identity Check Card Enrolled: Attempts Processing

Card Number 520000 Card enrollment option during purchase process

00 0000 0122
520000
00 0000 0106
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication
Summary Response flag DAUTHENTICATE Response flag SOK
The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 1
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection indicator 1
VERes enrolled Y E-commerce indicator spa
XID XID value PARes status A
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 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 19: Mastercard Identity Check Card Enrolled: Incomplete Authentication

Card Number 520000 Without authentication window

00 0000 0031
Auth. Type Active authentication

Payer Authentication Using the SCMP API | 77

 Chapter 5 Testing Payer Authentication Services

Test Case 19: Mastercard Identity Check Card Enrolled: Incomplete Authentication

Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer  ics_pa_validate service was successful.
authentication. Please authenticate before
 Issuer unable to perform authentication.
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value Collection indicator 0
proofXML proofXML value E-commerce indicator internet
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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication
authentication. Please authenticate before
 Payer could not be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
PAReq PAReq value PARes status N
proofXML proofXML value
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.

Test Case 21: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
(Customer Exited)

Card Number 564182

10 0001 0028
Auth. Type Active authentication

Payer Authentication Using the SCMP API | 78

 Chapter 5 Testing Payer Authentication Services

Test Case 21: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
(Customer Exited)

Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  Customer prevents authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 22: Mastercard Identity Check Card Enrolled: Unavailable Authentication

Card Number 520000

00 0000 0064
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details Collection indicator 0
E-commerce indicator internet
proofXML proofXML value
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

Payer Authentication Using the SCMP API | 79

 Chapter 5 Testing Payer Authentication Services

Test Case 23: Mastercard Identity Check Card Enrolled: Authentication Error

Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value Collection indicator 0
PAReq PAReq value E-commerce indicator internet
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.

Payer Authentication Using the SCMP API | 80

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK

ics_pa_enroll service was successful.
Details Collection indicator 0
E-commerce indicator spa
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 Response flag SOK

ics_pa_enroll service was successful.
Details Collection indicator 0
E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 81

 Chapter 5 Testing Payer Authentication Services

Test Case 26: Mastercard Identity Check RIBA_PASS

Card Number 520018

00 0000 0007
Auth. Type Passive authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The card is enrolled in payer authentication. ics_pa_validate service was successful.
Please authenticate before proceeding with
authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection indicator 2
VERes enrolled Y E-commerce indicator spa
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 required payer authentication values to your authorization request.

Test Case 27: Mastercard Identity Check RIBA_PASS: Unsuccessful Authentication

Card Number 520018

00 0000 0023
Auth. Type Passive authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication
authentication. Please authenticate before
 Payer could not be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
PAReq PAReq value PARes status N
proofXML proofXML value
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.

Payer Authentication Using the SCMP API | 82

 Chapter 5 Testing Payer Authentication Services

Test Case 28: Mastercard Identity Check RIBA

Card Number 520026 With authentication window

00 0000 0007
Auth. Type Risk-based bank
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The card is enrolled in payer authentication. ics_pa_validate service was successful.
Please authenticate before proceeding with
authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection indicator 2
VERes enrolled Y E-commerce indicator spa
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 required payer authentication values to your authorization request.

Test Case 29: Mastercard Identity Check RIBA: Unsuccessful Authentication

Card Number 520026 With authentication window

00 0000 0023
Auth. Type Risk-based bank
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication
authentication. Please authenticate before
 Payer could not be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
PAReq PAReq value PARes status N
proofXML proofXML value
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.

Payer Authentication Using the SCMP API | 83

 Chapter 5 Testing Payer Authentication Services

Maestro
Test Case 30: Maestro Card Enrolled: Successful Authentication

Card Number 675941 Without authentication window

11 0000 0008
675941 With authentication window
00 0000 6404
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value AAV AAV value
proofXML proofXML value Collection indicator 2
VERes enrolled Y E-commerce indicator spa
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

Payer Authentication Using the SCMP API | 84

 Chapter 5 Testing Payer Authentication Services

Test Case 31: Maestro Card Enrolled: Successful Authentication but Invalid PARes

Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer Payer authentication problem: PARes
authentication. Please authenticate before signature digest value mismatch. PARes
proceeding with authorization. message has been modified.
Details ACS URL URL Authentication result -1
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 32: Maestro Card Enrolled: Attempts Processing

Card Number 560000 Card enrollment option during purchase process

00 0000 00 0193
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 1
PAReq PAReq value AAV AAV value
proofXML proofXML value E-commerce indicator spa
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.

Payer Authentication Using the SCMP API | 85

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer Issuer unable to perform authentication.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value Collection indicator 0
proofXML proofXML value E-commerce indicator spa
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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer User failed authentication
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 35: Maestro Card Enrolled: Unavailable Authentication

Card Number 633110

02 6697 7839
Auth. Type Active authentication

Payer Authentication Using the SCMP API | 86

 Chapter 5 Testing Payer Authentication Services

Test Case 35: Maestro Card Enrolled: Unavailable Authentication

Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details Collection indicator 0
E-commerce indicator spa
proofXML proofXML value
Action Submit the transaction. No liability shift.

Payer Authentication Using the SCMP API | 87

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value Collection indicator 0
PAReq PAReq value E-commerce indicator internet
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 Response flag SOK

ics_pa_enroll service was successful.
Details Collection indicator 0
E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 88

 Chapter 5 Testing Payer Authentication Services

American Express SafeKey

Table 14 Possible Values for American Express SafeKey Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 aesk SOK

Recorded attempt to 1 06 aesk_ SOK

authenticate. attempted
1
Failure System error that prevents the 6 —2 SOK
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but there is no
liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.
Incomplete or unavailable 07 internet
authentication.
Invalid PARes. -1 — — DAUTHENTICATI
ONFAILED
Failure Authentication failed or 9 — — DAUTHENTICATI
(Customer cardholder did not complete ONFAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 89

 Chapter 5 Testing Payer Authentication Services

Test Case 38: American Express SafeKey Card Enrolled: Successful Authentication

Card Number 340000 Without authentication window

00 0003 961
371449 With authentication window
11 1020 228
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 0
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator aesk
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 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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: PARes signature digest value
proceeding with authorization. mismatch. PARes message has been modified.
Details ACS URL URL value Authentication result -1
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.

Payer Authentication Using the SCMP API | 90

 Chapter 5 Testing Payer Authentication Services

Test Case 40: American Express SafeKey Card Enrolled: Attempts Processing

Card Number 340000 Without authentication window

00 0003 391
344400 Card enrollment option during purchase process
00 0000 569
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 1
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator aesk_attempted
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 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.
If you request the validation and authorization services together, the process described above
occurs automatically.

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

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 91

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication.
authentication. Please authenticate before
 Payer cannot be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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.

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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 92

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value ECI 07
PAReq PAReq value E-commerce Indicator internet
proofXML proofXML value
VERes enrolled Y
XID XID value
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.

Payer Authentication Using the SCMP API | 93

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK
ics_pa_enroll service was successful.
Details E-commerce indicator internet
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 94

 Chapter 5 Testing Payer Authentication Services

JCB J/Secure
Table 15 Possible Values for JCB J/Secure Response Fields

Result and Interpretation pa_validate_

authentication_ eci e_commerce_ rflag

result indicator
Success Successful authentication. 0 05 js 100

Recorded attempt to 1 06 js_attempted 100

authenticate
1
Failure System error that prevents the 6 —2
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but no liability
shift.
Issuer unable to perform 6 07 internet 100
authentication
Incomplete or unavailable 07 internet
authentication.
js_failure
Invalid PARes. -1 00 476
Failure Authentication failed or 9 — — 476
(Customer cardholder did not complete
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 95

 Chapter 5 Testing Payer Authentication Services

Test Case 48: JCB J/Secure Card Enrolled: Successful Authentication

Card Number 356999 Without authentication window

00 1008 3722
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator js
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
(Signature Failure)

Card Number 356999

00 1008 3748
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: PARes signature digest value
proceeding with authorization. mismatch. PARes message has been modified.
Details ACS URL URL value Authentication result -1
PAReq PAReq value XID XID value
VERes enrolled Y
Action Do not proceed with authorization. Instead ask the customer for another form of payment.

Payer Authentication Using the SCMP API | 96

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 1
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator js_attempted
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

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer  Issuer unable to perform authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 97

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication.
authentication. Please authenticate before
 Payer cannot be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 53: JCB J/Secure Card Enrolled: Unavailable Authentication

Card Number 354159

99 9910 3865
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 98

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value ECI 07
PAReq PAReq value E-commerce indicator internet
proofXML proofXML value
VERes enrolled Y
XID XID value
Action Ask the customer for another form of payment. No liability shift.

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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator js_attempted
ECI 06
proofXML proofXML value
VERes enrolled N
Action Submit your authorization request.

Payer Authentication Using the SCMP API | 99

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK
ics_pa_enroll service was successful.
Details E-commerce indicator internet
proofXML proofXML value
Action After 10-12 seconds, proceed with the authorization request. No liability shift.

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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 100

 Chapter 5 Testing Payer Authentication Services

Diners Club ProtectBuy

Table 16 Possible Values for Diners Club ProtectBuy Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 pb SOK

Recorded attempt to 1 06 pb_ SOK

authenticate. attempted
1
Failure System error that prevents the 6 —2 SOK
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but there is no
liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.

Incomplete or unavailable 07 internet

authentication.
Invalid PARes. -1 — — DAUTHENTICATI
ONFAILED
Failure Authentication failed or 9 — — DAUTHENTICATI
(Customer cardholder did not complete ONFAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 101

 Chapter 5 Testing Payer Authentication Services

Test Case 58: Diners Club ProtectBuy Card Enrolled: Successful Authentication

Card Number 300500

00 0000 6246
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator pb
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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: PARes signature digest value
proceeding with authorization. mismatch. PARes message has been modified.
Details ACS URL URL value Authentication result -1
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.

Payer Authentication Using the SCMP API | 102

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 1
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator pb_attempted
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 61: Diners Club ProtectBuy Card Enrolled: Incomplete Authentication

Card Number 300500

00 0000 7376
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer  Issuer unable to perform authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 103

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication.
authentication. Please authenticate before
 Payer cannot be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 63: Diners Club ProtectBuy Card Enrolled: Unavailable Authentication

Card Number 300500

00 0000 6030
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 104

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value E-commerce indicator internet
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.

Payer Authentication Using the SCMP API | 105

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK
ics_pa_enroll service was successful.
Details E-commerce indicator internet
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
300500 Incorrect Configuration: Unable to Authenticate
00 0000 4837
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 106

 Chapter 5 Testing Payer Authentication Services

Discover ProtectBuy
Table 17 Possible Values for Discover ProtectBuy Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 dipb SOK

Recorded attempt to 1 06 dipb_ SOK

authenticate. attempted
1
Failure System error that prevents the 6 —2 SOK
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but there is no
liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.

Incomplete or unavailable 07 internet

authentication.
Invalid PARes. -1 — — DAUTHENTICATI
ONFAILED
Failure Authentication failed or 9 — — DAUTHENTICATI
(Customer cardholder did not complete ONFAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 107

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL Authentication result 0
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator dipb
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 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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: PARes signature digest value
proceeding with authorization. mismatch. PARes message has been modified.
Details ACS URL URL value Authentication result -1
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.

Payer Authentication Using the SCMP API | 108

 Chapter 5 Testing Payer Authentication Services

Test Case 70: Discover ProtectBuy Card Enrolled: Attempts Processing

Card Number 601100 Card enrollment option during purchase process

00 0000 0038
Auth. Type Activation during shopping
Results Check Enrollment Validate Authentication

Summary Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer ics_pa_validate service was successful.
authentication. Please authenticate before
proceeding with authorization.
Details ACS URL URL value Authentication result 1
PAReq PAReq value CAVV CAVV value
proofXML proofXML value E-commerce indicator dipb_attempted
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 Response flag DAUTHENTICATE Response flag SOK

The cardholder is enrolled in payer  Issuer unable to perform authentication.
authentication. Please authenticate before
 ics_pa_validate service was successful.
proceeding with authorization.
Details ACS URL URL value Authentication result 6
PAReq PAReq value E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 109

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer  User failed authentication.
authentication. Please authenticate before
 Payer cannot be authenticated.
proceeding with authorization.
Details ACS URL URL value Authentication result 9
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
proofXML proofXML value
VERes enrolled U
Action Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 110

 Chapter 5 Testing Payer Authentication Services

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 Response flag DAUTHENTICATE Response flag DAUTHENTICATION

FAILED
The cardholder is enrolled in payer We encountered a payer authentication
authentication. Please authenticate before problem: Error Processing PARes.
proceeding with authorization.
Details ACS URL URL value E-commerce indicator internet
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 Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
ECI 07
proofXML proofXML value
VERes enrolled N
Action Submit the transaction.

Payer Authentication Using the SCMP API | 111

 Chapter 5 Testing Payer Authentication Services

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 Response flag SOK
ics_pa_enroll service was successful.
Details E-commerce indicator internet
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
601100 Incorrect Configuration: Unable to Authenticate
00 0000 0079
Auth. Type Active authentication
Results Check Enrollment Validate Authentication

Summary Response flag SOK

ics_pa_enroll service was successful.
Details E-commerce indicator internet
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.

Payer Authentication Using the SCMP API | 112

 Chapter 5 Testing Payer Authentication Services

Elo Compra Segura

Table 18 Possible Values for Elo Compra Segura Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 cs SOK

Recorded attempt to 1 06 cs_attempted SOK

authenticate.
1
Failure System error that prevents the 6 —2 SOK
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but there is no
liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.

Incomplete or unavailable 07 internet

authentication.
Invalid PARes. -1 — — DAUTHENTICATION
FAILED
Failure Authentication failed or 9 — — DAUTHENTICATION
(Customer cardholder did not complete FAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 113

 Chapter 5 Testing Payer Authentication Services

China UnionPay
Table 19 Possible Values for China UnionPay Response Fields

Result and Interpretation Validate Authentication Response

Authentication ECI Commerce Response Flag
Result Indicator
Success Successful authentication. 0 05 up3ds SOK

Recorded attempt to 1 06 up3ds_ SOK

authenticate. attempted
1
Failure System error that prevents the 6 —2 SOK
(Customer completion of authentication:
not you can proceed with
responsible) authorization, but there is no
liability shift.
Issuer unable to perform 6 07 internet SOK
authentication.

Incomplete or unavailable 07 internet

authentication.
up3ds_
failure
Invalid PARes. -1 — — DAUTHENTICATION
FAILED
Failure Authentication failed or 9 — — DAUTHENTICATION
(Customer cardholder did not complete FAILED
responsible) 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 field is blank or absent.

Payer Authentication Using the SCMP API | 114

 Chapter 5 Testing Payer Authentication Services

Test Cases for 3D Secure 2.x

Use the card number specified in the test with the card’s expiration date set to the month
of January and the current year plus three. For example, for 2021, use 2024. You also
need the minimum required fields for an order.

Remove spaces in card numbers when testing.

XID values are included in 3D Secure 2.x test cases for legacy reasons. XID
is not returned for Mastercard transactions only.
The 3D Secure version and directory server transaction ID fields are returned
for the Check Enrollment and Validate Authentication services but are not
included in the 3D Secure 2.x test cases.

Mastercard requires that the 3D Secure version and directory server

transaction ID are included along with all pertinent data in your authorization
request.

Payer Authentication Using the SCMP API | 115

 Chapter 5 Testing Payer Authentication Services

Test Case 2.1: Successful Frictionless

Authentication

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1005
CardType = 001
Visa 19-digit PAN 445653
00 0000 0001 007
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3001
CardType = 036
Mastercard 520000
00 0000 1005
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3001
CardType = 036
American Express 340000
00 0001 007
CardType = 003
Discover 601100
00 0000 1002
CardType = 004
Diners Club 601100
00 0000 1002
CardType = 005
JCB J/Secure 333700
00 0000 0008
CardType = 007
Elo 650505
00 0000 1000
CardType = 054
China UnionPay 620001
00 0020 0000
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = Y
PARes status = Y
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)

Payer Authentication Using the SCMP API | 116

 Chapter 5 Testing Payer Authentication Services

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

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 05
Cartes Bancaires Visa 05
American Express 05
Discover 05
Diners Club 05
JCB J/Secure 05
Elo 05
China UnionPay 05
Expected Collection Indicator
Mastercard 2
Cartes Bancaires Mastercard 2

Results for the Validation Authentication Service

No results are returned.

Payer Authentication Using the SCMP API | 117

 Chapter 5 Testing Payer Authentication Services

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.

Test Case 2.2: Unsuccessful Frictionless

Authentication

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1013
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3019
CardType = 036
Mastercard 520000
00 0000 1013
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3019
CardType = 036
American Express 340000
00 0001 015
CardType = 003
Discover 601100
00 0000 1010
CardType = 004
Diners Club 601100
00 0000 1010
CardType = 005
JCB J/Secure 333700
00 0000 0990
CardType = 007
Elo 650505
00 0000 1018
CardType = 054
China UnionPay 620001
00 0010 0010
CardType = 062

Payer Authentication Using the SCMP API | 118

 Chapter 5 Testing Payer Authentication Services

Results for the Check Enrollment Service

Response flag = DAUTHENTICATIONFAILED
 User failed authentication.
 Payer cannot be authenticated.
VERes enrolled = Y
PARes status = N

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

Results for the Validation Authentication Service

No results are returned.

Action
It is not recommended to submit this transaction for authorization. Instead ask the
customer for another form of payment.

Payer Authentication Using the SCMP API | 119

 Chapter 5 Testing Payer Authentication Services

Test Case 2.3: Attempts Processing Frictionless

Authentication

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1021
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3027
CardType = 036
Mastercard 520000
00 0000 1021
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3027
CardType = 036
American Express 340000
00 0001 023
CardType = 003
Discover 601100
00 0000 1028
CardType = 004
Diners Club 601100
00 0000 1028
CardType = 005
JCB J/Secure 333700
00 0000 7045
CardType = 007
Elo 650505
00 0000 1026
CardType = 054
China UnionPay 620001
00 0000 0020
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = Y
PARes status = A
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)
XID = <XID value>

Payer Authentication Using the SCMP API | 120

 Chapter 5 Testing Payer Authentication Services

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
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 Expected ECI
Visa 06
Cartes Bancaires Visa 06
American Express 06
Discover 06
Diners Club 06
JCB J/Secure 06
Elo 06
China UnionPay 06
Expected Collection Indicator
Mastercard 1
Cartes Bancaires Mastercard 1

Results for the Validation Authentication Service

No results are returned.

Payer Authentication Using the SCMP API | 121

 Chapter 5 Testing Payer Authentication Services

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.

Test Case 2.4: Unavailable Frictionless

Authentication

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1039
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3035
CardType = 036
Mastercard 520000
00 0000 1039
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3035
CardType = 036
American Express 340000
00 0001 031
CardType = 003
Discover 601100
00 0000 1036
CardType = 004
Diners Club 601100
00 0000 1036
CardType = 005
JCB J/Secure 333700
00 0000 0735
CardType = 007
Elo 650505
00 0000 1034
CardType = 054
China UnionPay 620001
00 0040 0030
CardType = 062

Payer Authentication Using the SCMP API | 122

 Chapter 5 Testing Payer Authentication Services

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = Y
PARes status = U

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 internet

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

Payer Authentication Using the SCMP API | 123

 Chapter 5 Testing Payer Authentication Services

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

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1047
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3043
CardType = 036
Mastercard 520000
00 0000 1047
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3043
CardType = 036
American Express 340000
00 0001 049
CardType = 003
Discover 601100
00 0000 1044
CardType = 004
Diners Club 601100
00 0000 1044
CardType = 005
JCB J/Secure 333700
00 0000 0321
CardType = 007
Elo 650505
00 0000 1042
CardType = 054
China UnionPay 620001
00 0030 0040
CardType = 062

Payer Authentication Using the SCMP API | 124

 Chapter 5 Testing Payer Authentication Services

Results for the Check Enrollment Service

Response flag = DAUTHENTICATIONFAILED
 User failed authentication.
 Payer cannot be authenticated.
VERes enrolled = Y
PARes status = R

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

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.

Payer Authentication Using the SCMP API | 125

 Chapter 5 Testing Payer Authentication Services

Test Case 2.6: Authentication not Available on

Lookup

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1054
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3050
CardType = 036
Mastercard 520000
00 0000 1054
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3050
CardType = 036
American Express 340000
00 0001 056
CardType = 003
Discover 601100
00 0000 1051
CardType = 004
Diners Club 601100
00 0000 1051
CardType = 005
JCB J/Secure 333700
00 0000 6765
CardType = 007
Elo 650505
00 0000 1059
CardType = 054
China UnionPay 620001
00 0060 0050
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = U

Payer Authentication Using the SCMP API | 126

 Chapter 5 Testing Payer Authentication Services

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 internet

Results for the Validation Authentication Service

No results are returned.

Action
Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 127

 Chapter 5 Testing Payer Authentication Services

Test Case 2.7: Enrollment Check Error

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1062
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3068
CardType = 036
Mastercard 520000
00 0000 1062
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3068
CardType = 036
American Express 340000
00 0001 064
CardType = 003
Discover 601100
00 0000 1069
CardType = 004
Diners Club 601100
00 0000 1069
CardType = 005
JCB J/Secure 333700
00 0000 0016
CardType = 007
Elo 650505
00 0000 1067
CardType = 054
China UnionPay 620001
00 0050 0060
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = U

Payer Authentication Using the SCMP API | 128

 Chapter 5 Testing Payer Authentication Services

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 internet

Results for the Validation Authentication Service

No results are 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.

Payer Authentication Using the SCMP API | 129

 Chapter 5 Testing Payer Authentication Services

Test Case 2.8: Time-Out (Cruise Direct and Hybrid

Only)

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1070
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3076
CardType = 036
Mastercard 520000
00 0000 1070
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3076
CardType = 036
American Express 340000
00 0001 072
CardType = 003
Discover 601100
00 0000 1077
CardType = 004
Diners Club 601100
00 0000 1077
CardType = 005
JCB J/Secure 333700
00 0000 0081
CardType = 007
Elo 650505
00 0000 1075
CardType = 054
China UnionPay 620001
00 0090 0070
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = U

Payer Authentication Using the SCMP API | 130

 Chapter 5 Testing Payer Authentication Services

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 internet

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

Results for the Validation Authentication Service

No results are returned.

Action
After 10-12 seconds, proceed with the authorization request. No liability shift.

Payer Authentication Using the SCMP API | 131

 Chapter 5 Testing Payer Authentication Services

Test Case 2.9: Bypassed Authentication

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1088
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3084
CardType = 036
Mastercard 520000
00 0000 1088
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3084
CardType = 036
American Express 340000
00 0001 080
CardType = 003
Discover 601100
00 0000 1085
CardType = 004
Diners Club 601100
00 0000 1085
CardType = 005
JCB J/Secure 333700
00 0000 0537
CardType = 007
Elo 650505
00 0000 1083
CardType = 054
China UnionPay 620001
00 0080 0080
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = B

Payer Authentication Using the SCMP API | 132

 Chapter 5 Testing Payer Authentication Services

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 internet

Results for the Validation Authentication Service

No results are returned.

Action
Submit your authorization request. No liability shift.

Payer Authentication Using the SCMP API | 133

 Chapter 5 Testing Payer Authentication Services

Test Case 2.10a: Successful Step-Up Authentication

(Cruise Direct and Hybrid)

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1096
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3134
CardType = 036
Mastercard 520000
00 0000 1096
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3092
CardType = 036
American Express 340000
00 0001 098
CardType = 003
Discover 601100
00 0000 1093
CardType = 004
Diners Club 601100
00 0000 1093
CardType = 005
JCB J/Secure 333700
00 0020 0004
CardType = 007
Elo 650505
00 0000 1091
CardType = 054
China UnionPay 620001
99 9980 0019
CardType = 062

Results for the Check Enrollment Service

Response flag = DAUTHENTICATE
The cardholder is enrolled in payer authentication. Please authenticate before proceeding
with authorization.
VERes enrolled = Y
PAReq = <PAReq value>
ACS URL = <URL value>

Payer Authentication Using the SCMP API | 134

 Chapter 5 Testing Payer Authentication Services

Results for the Validation Authentication Service

Response flag = SOK
ics_pa_validate service was successful.
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.
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

Payer Authentication Using the SCMP API | 135

 Chapter 5 Testing Payer Authentication Services

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 05
Cartes Bancaires Visa 05
American Express 05
Discover 05
Diners Club 05
JCB J/Secure 05
Elo 05
China UnionPay 05
Expected Collection Indicator
Mastercard 2
Cartes Bancaires Mastercard 2

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.

Payer Authentication Using the SCMP API | 136

 Chapter 5 Testing Payer Authentication Services

Test Case 2.10b: Successful Step-Up Authentication

(Standard)
See the "Process Flow for Standard Integration" for steps that you must perform before
you call the Check Enrollment service.

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1096
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3134
CardType = 036
Mastercard 520000
00 0000 1096
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3092
CardType = 036
American Express 340000
00 0001 098
CardType = 003
Discover 601100
00 0000 1093
CardType = 004
Diners Club 601100
00 0000 1093
CardType = 005
JCB J/Secure 333700
00 0020 0004
CardType = 007
Elo 650505
00 0000 1091
CardType = 054
China UnionPay 620001
99 9980 0019
CardType = 062

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = Y
PARes status = Y
CAVV = <CAVV value>
AVV = <AVV value> (Mastercard only)

Payer Authentication Using the SCMP API | 137

 Chapter 5 Testing Payer Authentication Services

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

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 05
Cartes Bancaires Visa 05
American Express 05
Discover 05
Diners Club 05
JCB J/Secure 05
Elo 05
China UnionPay 05
Expected Collection Indicator
Mastercard 2
Cartes Bancaires Mastercard 2

Results for the Validation Authentication Service

No results are returned.

Payer Authentication Using the SCMP API | 138

 Chapter 5 Testing Payer Authentication Services

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.

Test Case 2.11a: Unsuccessful Step-Up

Authentication (Cruise Direct and Hybrid)

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1104
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3092
CardType = 036
Mastercard 520000
00 0000 1104
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3100
CardType = 036
American Express 340000
00 0001 106
CardType = 003
Discover 601100
00 0000 1101
CardType = 004
Diners Club 601100
00 0000 1101
CardType = 005
JCB J/Secure 333700
00 0020 0087
CardType = 007
Elo 650505
00 0000 1109
CardType = 054
China UnionPay 620001
99 9970 0029
CardType = 062

Payer Authentication Using the SCMP API | 139

 Chapter 5 Testing Payer Authentication Services

Results for the Check Enrollment Service

Response flag = DAUTHENTICATE
The cardholder is enrolled in payer authentication. Please authenticate before proceeding
with authorization.
VERes enrolled = Y
PAReq = <PAReq value>
ACS URL = <URL value>

Results for the Validation Authentication Service

Response flag = DAUTHENTICATIONFAILED
 User failed authentication.
 Payer cannot be authenticated.
PARes status = N

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

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

Payer Authentication Using the SCMP API | 140

 Chapter 5 Testing Payer Authentication Services

Test Case 2.11b: Unsuccessful Step-Up

Authentication (Standard)
See the "Process Flow for Standard Integration" for steps that you must perform before
you call the Check Enrollment service.

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1104
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3092
CardType = 036
Mastercard 520000
00 0000 1104
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3100
CardType = 036
American Express 340000
00 0001 106
CardType = 003
Discover 601100
00 0000 1101
CardType = 004
Diners Club 601100
00 0000 1101
CardType = 005
JCB J/Secure 333700
00 0020 0087
CardType = 007
Elo 650505
00 0000 1109
CardType = 054
China UnionPay 620001
99 9970 0029
CardType = 062

Results for the Check Enrollment Service

Response flag = DAUTHENTICATIONFAILED
 User failed authentication.
 Payer cannot be authenticated.
VERes enrolled = Y
PARes status = N

Payer Authentication Using the SCMP API | 141

 Chapter 5 Testing Payer Authentication Services

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

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.

Payer Authentication Using the SCMP API | 142

 Chapter 5 Testing Payer Authentication Services

Test Case 2.12a: Unavailable Step-Up

Authentication (Cruise Direct and Hybrid)

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1112
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3100
CardType = 036
Mastercard 520000
00 0000 1112
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3118
CardType = 036
American Express 340000
00 0001 114
CardType = 003
Discover 601100
00 0000 1119
CardType = 004
Diners Club 601100
00 0000 1119
CardType = 005
JCB J/Secure 333700
00 0020 0079
CardType = 007
Elo 650505
00 0000 1117
CardType = 054
China UnionPay 620001
99 9960 0039
CardType = 062

Results for the Check Enrollment Service

Response flag = DAUTHENTICATE
The cardholder is enrolled in payer authentication. Please authenticate before proceeding
with authorization.
VERes enrolled = Y
PAReq = <PAReq value>
ACS URL = <URL value>

Payer Authentication Using the SCMP API | 143

 Chapter 5 Testing Payer Authentication Services

Results for the Validation Authentication Service

Response flag = SOK
ics_pa_validate service was successful.
PARes status = U

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 internet

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

Payer Authentication Using the SCMP API | 144

 Chapter 5 Testing Payer Authentication Services

Action
Retry authentication or process without liability shift.

Test Case 2.12b: Unavailable Step-Up

Authentication (Standard)
See the "Process Flow for Standard Integration" for steps that you must perform before
you call the Check Enrollment service.

Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1112
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3100
CardType = 036
Mastercard 520000
00 0000 1112
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3118
CardType = 036
American Express 340000
00 0001 114
CardType = 003
Discover 601100
00 0000 1119
CardType = 004
Diners Club 601100
00 0000 1119
CardType = 005
JCB J/Secure 333700
00 0020 0079
CardType = 007
Elo 650505
00 0000 1117
CardType = 054
China UnionPay 620001
99 9960 0039
CardType = 062

Payer Authentication Using the SCMP API | 145

 Chapter 5 Testing Payer Authentication Services

Results for the Check Enrollment Service

Response flag = SOK
ics_pa_enroll service was successful.
VERes enrolled = Y
PARes status = U

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 internet

ECI/Collection Indicator Values

The following table lists the expected ECI or Collection Indicator values for each network.
Network Expected ECI
Visa 07
Cartes Bancaires Visa 07
American Express 07
Discover 07
Diners Club 07
JCB J/Secure 07
Elo 07
China UnionPay 07
Expected Collection Indicator
Mastercard 0
Cartes Bancaires Mastercard 0

Payer Authentication Using the SCMP API | 146

 Chapter 5 Testing Payer Authentication Services

Results for the Validation Authentication Service

No results are returned.

Action
Retry authentication or process without liability shift.

Payer Authentication Using the SCMP API | 147

 APPENDIX
API Fields
A

This appendix describes the SCMP (Simple Commerce Message Protocol) API fields that
you can use to access Cybersource Payer Authentication services. SCMP API is a legacy
name-value pair API that is supported for merchants who have already implemented it. If
you are new to Cybersource and want to connect to services, use the Simple Order API.

Formatting Restrictions
Unless otherwise noted, all fields are order and case insensitive and the fields accept
special characters such as @, #, and %.

Request-level and offer-level field names and values must not contain carets
(^) or colons (:). However, they can contain embedded spaces and any other
printable characters. If you use more than one consecutive space, the extra
spaces will be removed.
For Atos, the bill_ fields must not contain colons (:).

Data Type Definitions

Table 20 Data Type Definitions

Data Type Description

Date and time The format is YYYY-MM-DDThhmmssZ. For example, 2018-08-
11T224757Z is equal to August 11, 2018, at 10:47:57 P.M. The T
separate the date and the time. The Z indicates Coordinated
Universal Time (UTC), which is also known as Greenwich Mean
Time.
Decimal Number that includes a decimal point. Examples: 23.45, -0.1, 4.0,
90809.0468.
Integer Whole number {…, -3, -2, -1, 0, 1, 2, 3, …}.
Nonnegative integer Whole number greater than or equal to zero {0, 1, 2, 3, …}.
Positive integer Whole number greater than zero {1, 2, 3, …}.
String Sequence of letters, numbers, spaces, and special characters, such
as @ and #.

Payer Authentication Using the SCMP API | 148

 Appendix A API Fields

Request-Level Fields
See Cybersource Credit Card Services Using the SCMP API and Getting Started with
Cybersource Advanced for more information about using the SCMP API to access the
Cybersource services.

The fields in the following table refer to the enroll and validate services only.
Please review Credit Card Services Using the SCMP API for more information
about the fields specific to the authorization.

Table 21 Request-Level Fields

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
airline_leg#_carrier_ International Air Transport Association (IATA) code ics_pa_enroll (O) String (2)
code for the carrier for this leg of the trip.
Required for each leg.
Required for American Express SafeKey (U.S.) for
travel-related requests.
airline_leg#_leg_ Departure date for the first leg of the trip. Format: ics_pa_enroll (O) Integer (8)
departure_date YYYYMMDD.
Required for American Express SafeKey (U.S.) for
travel-related requests.
airline_leg#_ International Air Transport Association (IATA) code ics_pa_enroll (O) String (5)
destination for the destination airport for this leg of the trip.
Required for each leg.
Required for American Express SafeKey (U.S.) for
travel-related requests.
airline_leg#_ International Air Transport Association (IATA) code ics_pa_enroll (O) String (5)
originating_airport_ for the originating airport for the first leg of the trip.
code
Required for American Express SafeKey (U.S.) for
travel-related requests.
airline_number_of_ Number of passengers for whom the ticket was ics_pa_enroll (O) Integer (3)
passengers issued. If you do not include this field in your request,
Cybersource uses a default value of 1.
Required for American Express SafeKey (U.S.) for
travel-related requests.

Payer Authentication Using the SCMP API | 149

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
airline_passenger#_ First name of the passenger to whom the ticket was ics_pa_enroll (O) String (60)
firstname issued. If there are multiple passengers, include all
listed on the ticket.
Do not include special characters such as commas,
hyphens, or apostrophes. Only ASCII characters are
supported.
Required for American Express SafeKey (U.S.) for
travel-related requests.
airline_passenger#_ Last name of the passenger to whom the ticket was ics_pa_enroll (O) String (60)
lastname issued. If there are multiple passengers, include all
listed on the ticket.
Do not include special characters such as commas,
hyphens, or apostrophes. Only ASCII characters are
supported.
Required for American Express SafeKey (U.S.) for
travel-related requests.
bill_address1 First line of the billing street address as it appears on ics_pa_enroll (R) String (60)
the credit card issuer’s records.
ics_pa_setup (R)
bill_address2 Additional address information, for example: ics_pa_enroll (O) String (60)
Attention: Accounts Payable
bill_city City of the billing address. ics_pa_enroll (R) String (50)
ics_pa_setup (R)
bill_country Billing country for the account. Use the two- ics_pa_enroll (R) String (2)
character country codes.
ics_pa_setup (R)
bill_state State or province of the customer. ics_pa_enroll (O) String (2)
Required for U.S., Canada, and China. For U.S. and ics_pa_setup (O)
Canada, use the two-character state, province, or
territory codes.
For China, use the ISO 3166-2 format.
If the value is not in the correct format, you may
experience authentication errors. It is recommended
not to send a value rather than format incorrectly.

Payer Authentication Using the SCMP API | 150

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
bill_zip Postal code for the billing address. The postal code ics_pa_enroll (R String (10)
must consist of 5 to 9 digits.
ics_pa_setup (O)
When the billing country is the U.S., the 9-digit postal
ics_pa_setup (R))
code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal
code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example A1B 2C3
Required if the bill_country field value is US or CA.
card_type Type of card. For more information, see the Credit ics_pa_enroll (R) String (3)
Card Services for the SCMP API (PDF | HTML). This
ics_pa_setup (O)
field contains one of these values:
ics_pa_validate
 001: Visa (R)
 002: Mastercard
 003: American Express
 004: Discover
 005: Diners Club
 007: JCB
 024: Maestro (UK Domestic)
 036: Cartes Bancaires
 042: Maestro (International)
 054: Elo
 062: China UnionPay
Note For the Payer Authentication Check
Enrollment Service and Payer Authentication
Validation Service, this field is required. You must
supply a value for it and include it in your request.
For the Payer Authentication Setup service, the field
is required when card type is Cartes Bancaires.
currency Currency used for the order. Use the standard ISO ics_pa_enroll (R) String (5)
codes located in the Support Center.
ics_pa_validate
(R)

Payer Authentication Using the SCMP API | 151

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
customer_account_ Date the cardholder’s account was last changed. ics_pa_enroll (O) Integer (8)
change_date This includes changes to the billing or shipping
address, new payment accounts or new users
added.
This field can contain one of these values:
 -1: Guest account
 0: Changed during this transaction
If neither applies, enter the date in YYYYMMDD
format.
Recommended for Discover ProtectBuy.
customer_account_ Date the cardholder opened the account. ics_pa_enroll (O) Integer (8)
create_date
This field can contain one of these values:
 -1: Guest account
 0: Opened during this transaction
If neither applies, enter the date in YYYYMMDD
format.
Recommended for Discover ProtectBuy.
customer_account_ Date the cardholder last changed or reset password ics_pa_enroll (O) Integer (8)
password_change_ on account.
date
This field can contain one of these values:
 -1: Guest account
 0: Changed during this transaction
If neither applies, enter the date in YYYYMMDD
format.
Recommended for Discover ProtectBuy.
customer_cc_expmo Expiration month (MM) of the card. Required if ics_pa_enroll (R) String (2)
customer_cc_number is included.
ics_pa_setup (R)
ics_pa_validate
(O)
customer_cc_expyr Expiration year (YYYY) of the card. Required if ics_pa_enroll (R) String (4)
customer_cc_number is included.
ics_pa_setup (R)
ics_pa_validate
(O)
customer_cc_number Customer’s card number. ics_pa_enroll (R) Non-
negative
ics_pa_setup (R)
integer (20)
ics_pa_validate
(O)

Payer Authentication Using the SCMP API | 152

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
customer_email Customer’s email address, including the full domain ics_pa_enroll (R) String (255)
name. Use the following format: [email protected]
ics_pa_setup (R)
(for example, [email protected]).
customer_firstname Customer’s first name.The value should be the same ics_pa_enroll (R) String (60)
as the value that appears on the card.
ics_pa_setup (R)
customer_ipaddress Customer’s IP address, such as 10.1.27.63, ics_pa_enroll (O) String (45)
reported by your web server via socket information.
customer_lastname Customer’s last name. The value should be the ics_pa_enroll (R) String (60)
same as the value that appears on the card.
ics_pa_setup (R)
customer_passport_ Issuing country for the cardholder’s passport. ics_pa_enroll (O) Integer (3)
country
Recommended for Discover ProtectBuy.
customer_passport_ The cardholder’s passport number. ics_pa_enroll (O) String (40)
number
Recommended for Discover ProtectBuy.
customer_phone Telephone number of the customer. ics_pa_enroll (O) String (15)
For countries other than US or CA, add the country
code at the beginning of the phone number, if
possible. Otherwise, the billing country is used to
determine the country code.
encrypted_payment_ The encrypted payment data value. ics_pa_setup (R)
data
encrypted_payment_ Format of the encrypted payment data. ics_pa_setup (O) String (128)
descriptor
grand_total_amount Grand total for the order. In your request, you must ics_pa_enroll (R) String (15)
include either this field or offer0 and the offer-level
ics_pa_validate
field amount. For more information, see the Credit
(R)
Card Services for the SCMP API (PDF | HTML).
Note This field is optional if you use the offer-level
field amount.
http_browser_color_ Indicates the bit depth of the color palette for ics_pa_enroll (O) String (2)
depth displaying images, in bits per pixel.
Example 24
For more information, see https://en.wikipedia.org/
wiki/Color_depth.
http_browser_ Indicates the browser language as defined in IETF ics_pa_enroll (O) String (8)
language BCP47.
Example en-US
For more information, see https://en.wikipedia.org/
wiki/IETF_language_tag.

Payer Authentication Using the SCMP API | 153

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
http_browser_java_ Indicates the ability of the cardholder browser to ics_pa_enroll (O) String (5)
enabled execute Java. The value is returned from the
navigator.javaEnabled property. This field can
contain one of these values:
 true
 false
http_browser_ Indicates the ability of the cardholder browser to ics_pa_enroll (O) String (5)
javascript_enabled execute JavaScript. This value is available from the
fingerprint details of the cardholder's browser. This
field can contain one of these values:
 true
 false
http_browser_screen_ Total height of the cardholder's screen in pixels. ics_pa_enroll (O) String (6)
height
Example 864
http_browser_screen_ Total width of the cardholder's screen in pixels. ics_pa_enroll (O) String (6)
width
Example 1536
http_browser_time_ Time difference between UTC time and the ics_pa_enroll (O) String (5)
difference cardholder browser local time, in minutes.
Example 300
ics_applications Comma-separated list of Cybersource services to ics_pa_enroll (R) String (255)
process.
ics_pa_setup (R)
Note You must request the Payer Authentication
ics_pa_validate
Setup service separately.
(R)
merchant_id Your Cybersource merchant ID. ics_pa_enroll (R) String (30)
ics_pa_setup (R)
ics_pa_validate
(R)

Payer Authentication Using the SCMP API | 154

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
merchant_defined_ Fields that you can use to store information. The ics_pa_enroll (O) String (255)
data1 to merchant_ value appears in the Case Management Details
defined_data5 window in the Business Center. The first four fields
are the same fields that are used by the Secure Data
services.
Warning Merchant-defined data fields are not
intended to and must not be used to capture
personally identifying information. Accordingly,
merchants are prohibited from capturing, obtaining,
and/or transmitting any personally identifying
information in or via the merchant-defined data
fields. Personally identifying information includes,
but is not limited to, address, credit card number,
social security number, driver's license number,
state-issued identification number, passport number,
and card verification numbers (CVV, CVC2, CVV2,
CID, CVN). In the event Cybersource discovers that
a merchant is capturing and/or transmitting
personally identifying information via the merchant-
defined data fields, whether or not intentionally,
Cybersource will immediately suspend the
merchant's account, which will result in a rejection of
any and all transaction requests submitted by the
merchant after the point of suspension.
merchant_ref_number Merchant-generated order reference or tracking ics_pa_enroll (R) String (50)
number.
ics_pa_setup (R)
ics_pa_validate
(R)
pa_account_ Number of purchases with this cardholder account ics_pa_enroll (O) Integer (4)
purchases during the previous six months.
Recommended for Discover ProtectBuy.
pa_acquirer_country Issuers should be aware of the acquirer's country ics_pa_enroll (O) String (2)
code when the acquirer country differs from the
merchant country, and the acquirer is in the EEA
(European Economic Area).

Payer Authentication Using the SCMP API | 155

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_acs_window_size You can send this override field to set the challenge ics_pa_enroll (O) Integer (2)
window size to display to the cardholder. The Access
Control Server (ACS) replies with content that is
formatted appropriately for this window size to allow
for the best user experience. The sizes are width x
height in pixels of the window displayed in the
cardholder browser.
Possible values:
 01: 250x400
 02: 390x400
 03: 500x600
 04: 600x400
 05: Full page
pa_add_card_ Number of add card attempts in the last 24 hours. ics_pa_enroll (O) Integer (3)
attempts
Recommended for Discover ProtectBuy.
pa_alternate_ Data that documents and supports a specific ics_pa_enroll (O) String
authentication_data authentication process. (2048)
pa_alternate_ Date and time in UTC of the cardholder ics_pa_enroll (O) Integer (12)
authentication_date authentication.
Format:
YYYYMMDDHHMM
pa_alternate_ Mechanism used by the cardholder to authenticate ics_pa_enroll (O) Integer (2)
authentication_method to the 3D Secure requestor.
Possible values:
 01: No authentication occurred
 02: Login using merchant system credentials
 03: Login using Federated ID
 04: Login using issuer credentials
 05: Login using third-party authenticator
 06: Login using FIDO Authenticator

Payer Authentication Using the SCMP API | 156

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_authentication_ Indicates the type of authentication request. ics_pa_enroll (O) Integer (2)
indicator
Possible values:
 01: Payment transaction
 02: Recurring transaction
 03: Installment transaction
 04: Add card
 05: Maintain card
 06: Cardholder verification as part of EMV token
ID&V (identity and verification)
pa_authentication_ Payer authentication transaction identifier passed to ics_pa_enroll (O) String (20)
transaction_id link the check enrollment and validate authentication
ics_pa_validate
messages.
(O)
Note Required for Standard integration for enroll
service. Required for Hybrid integration for validate
service.
pa_challenge_code Possible values: ics_pa_enroll (O) String (2)
 01: No preference
 02: No challenge request
 03: Challenge requested (3D Secure requestor
preference)
 04: Challenge requested (mandate)
 05: No challenge requested (transactional risk
analysis is already performed)
 06: No challenge requested (Data share only)
 07: No challenge requested (strong consumer
authentication is already performed)
 08: No challenge requested (utilize whitelist
exemption if no challenge required)
 09: Challenge requested (whitelist prompt
requested if challenge required)
Note This field will default to 01 on merchant
configuration and can be overridden by the
merchant. EMV 3D Secure version 2.1.0 supports
values 01-04. Version 2.2.0 supports values 01-
09.

Payer Authentication Using the SCMP API | 157

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_customer_cc_alias An alias that uniquely identifies the customer's ics_pa_enroll (O) String (128)
account and credit card on file.
Note This field is required if Tokenization is enabled
in the merchant profile settings.
pa_default_card Indicates that the card being used is the one ics_pa_enroll (O) String (5)
designated as the primary payment card for
purchase. This field can contain one of these values:
 true
 false
Recommended for Discover ProtectBuy.
pa_device_channel Indicates the channel used for the transaction. ics_pa_enroll (O) String (10)
Note Required for SDK integration.
Possible Values:
 SDK
 Browser
 3RI (3D Secure Integrator Request)
Note If you use the SDK integration, this field is
dynamically set to SDK. If you use the JavaScript
code, this field is dynamically set to Browser. For
merchant-initiated or 3RI transactions, you must set
the field to 3RI. If you use this field in addition to
JavaScript code, you must set the field to Browser.
pa_fraud_activity Indicates whether the merchant experienced ics_pa_enroll (O) String (2)
suspicious activity (including previous fraud) on the
account. This field can contain one of these values:
 01: No suspicious activity
 02: Suspicious activity observed
Recommended for Discover ProtectBuy.
pa_gift_card_amount The purchase amount total for prepaid gift cards in ics_pa_enroll (O) Integer (15)
major units
Example:
123.45 USD= 123
pa_gift_card_count Total count of individual prepaid gift cards ics_pa_enroll (O) Integer (2)
purchased.
pa_gift_card_currency Currency used for the gift card purchase. Use the ics_pa_enroll (O) Integer (3)
standard ISO codes located in the Support Center.

Payer Authentication Using the SCMP API | 158

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_http_accept Value of the Accept header sent by the customer’s ics_pa_enroll (O) String (255)
web browser.
Note If the customer’s browser provides a value,
you must include it in your request.
pa_http_user_accept The exact content of the HTTP accept header. ics_pa_enroll (O) String (256)
pa_http_user_agent Value of the User-Agent header sent by the ics_pa_enroll (O) String (255)
customer’s web browser.
Note If the customer’s browser provides a value,
you must include it in your request.
pa_installment_total_ An integer value greater than 1 indicating the ics_pa_enroll (O) Integer (4)
count maximum number of permitted authorizations for
installment payments.
Note This value is required if the merchant and
cardholder have agreed to installment payments.
pa_marketing_optin Indicates whether the customer has opted in for ics_pa_enroll (O) String (5)
marketing offers. This field can contain one of these
values:
 true
 false
Recommended for Discover ProtectBuy.
pa_marketing_source Indicates origin of the marketing offer. ics_pa_enroll (O) String (40)
Recommended for Discover ProtectBuy.
pa_mcc Merchant category code. ics_pa_enroll (O) Integer (4)
pa_merchant_fraud_ Calculated by merchants according to Payment ics_pa_enroll (O) Integer (2)
rate Service Directive 2 (PSD2) and Regulatory Technical
Standards (RTS). European Economic Area (EEA)
card fraud divided by all EEA card volumes.
Possible Values:
 1: Represents fraud rate <=1
 2:Represents fraud rate >1 and <=6
 3: Represents fraud rate >6 and <=13
 4: Represents fraud rate >13 and <=25
 5: Represents fraud rate >25
pa_merchant_name Your company’s name as you want it to appear to the ics_pa_enroll (O) String (25)
customer in the issuing bank’s authentication form.
This value overrides the value specified by your
merchant bank.

Payer Authentication Using the SCMP API | 159

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_merchant_new_ Indicates whether the consumer is a new or existing ics_pa_enroll (O) String (5)
customer customer with the merchant.
This field can contain one of these values:
 true
 false
pa_merchant_score Risk score provided by merchants. Required for ics_pa_enroll (O) String (20)
transactions processed in France.
pa_message_category Category of the message for a specific use case. ics_pa_enroll (O) String (2)
Possible values:
 01: PA (payment authentication)
 03-79: Reserved for EMVCo future use (values
invalid until defined by EMVCo)
 80-99: Reserved for directory server use
pa_mobile_phone Cardholder’s mobile phone number. ics_pa_enroll (O) Integer (25)
pa_override_ Specifies the payment account type used for the ics_pa_enroll (O) String (10)
payment_method transaction. This field overrides other payment types
that might be specified in the request.
Use one of the following values for this field:
 NA: Not applicable. Do not override other
payment types that are specified in the request.
 CR: Credit card
 DB: Debit card
 VSAVR: Visa Vale Refeicao
 VSAVA: Visa Vale Alimentacao
pa_payment_account_ Date the payment account was added to the ics_pa_enroll (O) Integer (8)
date cardholder account.
This field can contain one of these values:
 -1: Guest account
 0: Added during this transaction
If neither applies, enter the date in YYYYMMDD
format.
Recommended for Discover ProtectBuy.

Payer Authentication Using the SCMP API | 160

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_pre_order Indicates whether cardholder is placing an order with ics_pa_enroll (O) String (2)
a future availability or release date.
This field can contain one of these values:
 01: Merchandise available
 02: Future availability
pa_pre_order_date Expected date that a pre-ordered purchase will be ics_pa_enroll (O) Integer (8)
available.
Format:
YYYYMMDD
pa_prior_ This field contains data that the ACS can use to ics_pa_enroll (O) String
authentication_data verify the authentication process. (2048)
pa_prior_ Method the cardholder used previously to ics_pa_enroll (O) Integer (2)
authentication_method authenticate to the 3D Secure requester.
Possible values:
 01: Frictionless authentication occurred by ACS
 02: Cardholder challenge occurred by ACS
 03: AVS verified
 04: Other issuer methods
 05-79: Reserved for EMVCo future use (values
invalid until defined by EMVCo)
 80-99: Reserved for directory server use
pa_prior_ This field contains the ACS transaction ID for a prior ics_pa_enroll (O) String (36)
authentication_ authenticated transaction. For example, the first
reference_id recurring transaction that was authenticated with the
cardholder.
pa_prior_ Date and time in UTC of the prior cardholder ics_pa_enroll (O) Integer (12)
authentication_time authentication.
Format:
YYYYMMDDHHMM

Payer Authentication Using the SCMP API | 161

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_product_code Specifies the product code, which designates the ics_pa_enroll (O) String (3)
type of transaction. Specify one of the following
values for this field:
 AIR: Airline purchase
Important Required for American Express
SafeKey (U.S.).
 ACC: Accommodation Rental
 ACF: Account funding
 CHA: Check acceptance
 DIG: Digital Goods
 DSP: Cash Dispensing
 GAS: Fuel
 GEN: General Retail
 LUX: Luxury Retail
 PAL: Prepaid activation and load
 PHY: Goods or services purchase
 QCT: Quasi-cash transaction
 REN: Car Rental
 RES: Restaurant
 SVC: Services
 TBD: Other
 TRA: Travel
pa_recurring_end_ The date after which no further recurring ics_pa_enroll (O) Integer (8)
date authorizations should be performed. Format:
YYYYMMDD.
Note This field is required for recurring
transactions.

Payer Authentication Using the SCMP API | 162

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_recurring_ Integer value indicating the minimum number of ics_pa_enroll (O) Integer (4)
frequency days between recurring authorizations. A frequency
of monthly is indicated by the value 28. Multiple of 28
days will be used to indicate months.
Example:
6 months= 168
Example values accepted (31 days):
 31
 031
 0031
Note This field is required for recurring
transactions.
pa_recurring_original_ Date of original purchase. Required for recurring ics_pa_enroll (O) String (17)
purchase_date transactions.
Format:
YYYYMMDDHHMMSS
Note If this field is empty, the current date is used.
pa_reference_id Reference ID that corresponds to the device ics_pa_enroll (R) String (50)
fingerprinting data that was collected previously.
Note Required for Hybrid or Cardinal Cruise Direct
Connection API integration.
pa_reorder Indicates whether the cardholder is reordering ics_pa_enroll (O) String (2)
previously purchased merchandise.
This field can contain one of these values:
 01: First time ordered
 02: Reordered

Payer Authentication Using the SCMP API | 163

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_requestor_ Indicates the type of 3RI request (3D Secure ics_pa_enroll (O) Integer (2)
initiated_ Integrator Request).
authentication_
Possible Values:
indicator
 01: Recurring transaction
 02: Installment transaction
 03: Add card
 04: Maintain card
 05: Account verification
 06: Split/delayed shipment
 07: Top-up
 08: Mail Order
 09: Telephone Order
 10: Whitelist status check
 11: Other payment
Note EMV 3D Secure version 2.1.0 supports
values 01-05. Version 2.2.0 supports values 01-
11.
pa_response_access_ JSON Web Token (JWT) returned by the 3D Secure ics_pa_validate String
token provider when the authentication is complete. (O) (2048)
Note Required for Hybrid integration if you use the
Cybersource-generated access token.
pa_return_url The URL of the merchant’s return page. ics_pa_enroll (R) String
Cybersource adds this return URL to the step-up (2048)
JWT and returns it in the response of the Payer
Authentication enrollment call. The merchant's return
URL page serves as a listening URL. Cardinal sends
a POST response to the merchant’s return URL
when the bank session completes. This response
contains the completed bank session’s transaction
ID. The merchant’s return page should capture the
transaction ID and send it in the Payer
Authentication validation call.

Payer Authentication Using the SCMP API | 164

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_sdk_max_timeout This field indicates the maximum amount of time for ics_pa_enroll (O) String (2)
all 3D Secure 2.x messages to be communicated
between all components (in minutes).
Possible Values:
 Greater than or equal to 05 (05 is the minimum
timeout to set)
 Default is set to 15
Note This field is a required for 3D Secure 2.x. If
you do not send a value in this field, it defaults to 15.
pa_ship_address_ Date when the shipping address for this transaction ics_pa_enroll (O) Integer (8)
usage_date was first used.
This field can contain one of these values:
 -1: Guest account
 0: First used during this transaction
If neither applies, enter the date in YYYYMMDD
format.
Recommended for Discover ProtectBuy.
pa_signedpares Payer authentication result (PARes) message ics_pa_validate String (no
returned by the card-issuing bank. If you need to (O) limit, may
show proof of enrollment checking, you may need to be very
decrypt and parse the string for the information large)
required by the payment card company. For more
information, see "Storing Payer Authentication
Data," page 208.
Important The value is in Base64. You must
remove all carriage returns and line feeds before
adding the PARes to the request.
pa_transaction_count_ Number of transaction (successful or abandoned) for ics_pa_enroll (O) Integer (3)
day this cardholder account within the last 24 hours.
Recommended for Discover ProtectBuy.
pa_transaction_count_ Number of transactions (successful and abandoned) ics_pa_enroll (O) Integer (3)
year for this cardholder account within the last year.
Recommended for Discover ProtectBuy.

Payer Authentication Using the SCMP API | 165

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
pa_transaction_mode Transaction mode identifier. Identifies the channel ics_pa_enroll (O) String (1)
from which the transaction originates.
Possible values:
 M: MOTO (Mail Order Telephone Order)
 R: Retail
 S: eCommerce
 P: Mobile Device
 T: Tablet
pa_white_list_status Enables the communication of trusted beneficiary ics_pa_enroll (O) String (1)
and whitelist status among the ACS, the directory
server, and the 3D Secure requester.
Possible Values:
 Y: 3D Secure requester is whitelisted by
cardholder
 N: 3D Secure requester is not whitelisted by
cardholder
secure_corporate_ Indicates that dedicated payment processes and ics_pa_enroll (O) String (1)
payment_indicator procedures were used. Potential secure corporate
payment exemption applies.
Possible Values:
 0
 1
ship_to_address1 ics_pa_enroll (O) String (60)
First line of the shipping address.
Required if any shipping address information is
included.
Required for American Express SafeKey (U.S.).
ship_to_address2 Second line of the shipping address. ics_pa_enroll (O) String (60)
Required for American Express SafeKey (U.S.).
ship_to_city City of the shipping address. ics_pa_enroll (O) String (50)
Required if any shipping address information is
included.
Required for American Express SafeKey (U.S.).
ship_to_country Country of the shipping address. Use the two- ics_pa_enroll (O) String (2)
character ISO Standard Country Codes.
Required for American Express SafeKey (U.S.).

Payer Authentication Using the SCMP API | 166

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
ship_to_destination_ Indicates destination chosen for the transaction. ics_pa_enroll (O) Integer (2)
code Possible values:
 01: Ship to cardholder billing address
 02: Ship to another verified address on file with
merchant
 03: Ship to address that is different than billing
address
 04: Ship to store (store address should be
populated on request)
 05: Digital goods
 06: Travel and event tickets, not shipped
 07: Other
ship_to_destination_ Shipping destination. ics_pa_enroll (O) String (25)
types
Example Commercial, residential, store
ship_to_firstname First name of the recipient. ics_pa_enroll (O) String (60)

ship_to_lastname Last name of the recipient. ics_pa_enroll (O) String (60)

ship_to_phone Phone number for the shipping address. ics_pa_enroll (O) String (15)
For information on formatting, see customer_phone.
ship_to_state State or province of the shipping address. Use the ics_pa_enroll (O) String (2)
State, Province, and Territory Codes for the United
States and Canada.
Required if shipTo_country value is CA, US, or
China.
For China, use the ISO 3166-2 format.
If the value is not in the correct format, you may
experience authentication errors. It is recommended
not to send a value rather than format incorrectly.
Required for American Express SafeKey (U.S.).

Payer Authentication Using the SCMP API | 167

 Appendix A API Fields

Table 21 Request-Level Fields (Continued)

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
ship_to_zip Postal code for the shipping address. The postal ics_pa_enroll (O) String (10)
code must consist of 5 to 9 digits.
When the shipping country is the U.S., the 9-digit
postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the shipping country is Canada, the 6-digit
postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example A1B 2C3
Required only if the ship_to_country field is US or
CA.
Required for American Express SafeKey (U.S.).
shipping_method Shipping method for the product. Possible values: ics_pa_enroll (O) String (10)
 lowcost: Lowest-cost service
 sameday: Courier or same-day service
 oneday: Next-day or overnight service
 twoday: Two-day service
 threeday: Three-day service
 pickup: Store pick-up
 other: Other shipping method
 none: No shipping method because product is a
service or subscription
Required for American Express SafeKey (U.S.).
subscription_id Value that identifies the customer subscription for ics_pa_setup (O) String (26)
which the service is being requested. This value is
sent to you when the customer subscription is
created.
timeout Number of seconds the system waits before the ics_pa_enroll (O) Positive
transaction times out. The default is 110. integer (3)
ics_pa_validate
(O)
total_offers_count Total number of articles or items in the order as a ics_pa_enroll (O) Integer (2)
numeric decimal count.
Possible values: 00-99
transient_token A temporary ID that represents the customer's ics_pa_setup (O) String (64)
payment data (which is securely stored in Visa Data
Centers). Use this ID in place of the payment data in
an API request.

Payer Authentication Using the SCMP API | 168

 Appendix A API Fields

Offer-Level Fields
Each offer submitted in a request contains several fields that describe the product that the
customer ordered through your web store. The amount field is required. If multiple
products are ordered in a single purchase, a Cybersource service application request can
contain one or more offers, referred to as offer0 through offerN. If you use more than one
consecutive space, the extra spaces will be removed.

Do not use carets (^) and colons (:) in offer fields. These are reserved
characters. Carets separate name-value pairs, and colons separate field
names from values.

Table 22 Offer-Level Fields

Field Name Description Used By: Data Type

Required (R) & Length
or Optional (O)
amount Per-item price of the product. You can include a ics_pa_enroll (R) Decimal
decimal point (.) in this field, but you cannot include (15)
ics_pa_validate
any other special characters. The amount will be
(R)
truncated to the correct number of decimal places.
Note This field is optional if you use the request-
level field grand_total_amount.
merchant_product_sku Merchant’s product identifier code. ics_pa_enroll (O) String (255)
passenger_firstname Passenger's first name. ics_pa_enroll (O) String (60)
passenger_lastname Passenger's last name. ics_pa_enroll (O) String (60)
product_description Brief description of item. ics_pa_enroll (O) String (256)
product_name Name of the product. ics_pa_enroll (O) String (255)
quantity Quantity of the product being purchased. The default ics_pa_enroll (O) Non-
value is 1. negative
ics_pa_validate
integer (10)
(O)
shipping_destination_ Destination to which the item is shipped. ics_pa_enroll (O) String (50)
types
Example Commercial, residential, store
tax_amount Total tax to apply to the product. The tax_amount ics_pa_enroll (O) Decimal
field is additive. For example, if you send these offer (15)
ics_pa_validate
lines
(O)
offer0=amount:10.00^quantity:1^tax_
amount:0.80
offer1=amount:20.00^quantity:1^tax_
amount:1.60
the total amount authorized will be for $32.40, not
30.00 with 2.40 of tax included.
The tax_amount and the amount must be in the
same currency.

Payer Authentication Using the SCMP API | 169

 Appendix A API Fields

Response Fields
Table 23 Response Fields

Field Name Description Returned By Data Type

& Length
authorization_payload The Base64-encoded JSON Payload of ics_pa_enroll String (255)
Authorization Values returned in the challenge flow.
ics_pa_validate
card_bin Six-digit card issuer bank identification number. ics_pa_enroll String (6)
ics_pa_validate
card_type_name The card brand name associated with the ics_pa_enroll String (25)
cardholder’s card number.
ics_pa_validate
challenge_cancel_ Indicates why the transaction was canceled. ics_pa_enroll String (2)
code
Possible Values: ics_pa_validate
 01: Cardholder selected Cancel
 02: Reserved for future EMVCo use (values
invalid until defined by EMVCo).
 03: Transaction timed out—Decoupled
Authentication
 04: Transaction timed out at ACS—other timeouts
 05: Transaction timed out at ACS—First CReq not
received by ACS
 06: Transaction Error
 07: Unknown
 08: Transaction timed out at SDK
challenge_required Indicates whether a challenge is required in order to ics_pa_enroll String (1)
complete authentication.
Note Regional mandates might determine that a
challenge is required.
Possible values:
 Y: Challenge required
 N: Challenge not required
Note Used by the Hybrid integration.
client_lib_version Information about the client library used to request ics_pa_enroll String (255)
the transaction.
ics_pa_setup
ics_pa_validate
currency Currency used for the order. Use the standard ISO ics_pa_enroll String (255)
codes located in the Support Center.
ics_pa_validate

Payer Authentication Using the SCMP API | 170

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
effective_ The type of 3D Secure transaction flow that ics_pa_enroll String (2)
authentication_type occurred. It can be one of the following:
ics_pa_validate
 CH: Challenge
 FR: Frictionless
 FD: Frictionless with delegation, (challenge not
generated by the issuer but by the scheme on
behalf of the issuer).
Required for transactions processed in France.
ics_rcode One-digit code that indicates whether the entire ics_pa_enroll Integer (1)
request was successful. The field contains one of
ics_pa_setup
these values:
ics_pa_validate
 -1: An error occurred.
 0: The request was declined.
 1: The request was successful.
ics_rflag One-word description of the result of the entire ics_pa_enroll String (255)
request.
ics_pa_setup
ics_pa_validate
ics_rmsg Message that explains the response flag ics_rflag. ics_pa_enroll String (255)
ics_pa_setup
ics_pa_validate
merchant_ref_number Merchant-generated order or tracking number. ics_pa_enroll String (255)
ics_pa_setup
ics_pa_validate
pa_access_token JSON Web Token (JWT) used to authenticate the ics_pa_enroll String
customer with the authentication provider (for (2048)
ics_pa_setup
example, CardinalCommerce or RuPay).

Payer Authentication Using the SCMP API | 171

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_acs_rendering_ Identifies the UI type that the ACS will use to ics_pa_enroll String
type complete the challenge. (see
ics_pa_validate
description)
Note Available only for mobile application
transactions using the Cardinal Mobile SDK.
This field is a JSON object that comprises the
following two fields, each 2 characters in length.
 ACS Interface
Field Name: acsInterface
This is the ACS interface the challenge presents
to the cardholder.
Possible values:
 01: Native UI
 02: HTML UI
 ACS UI Template
Field Name: acsUiTemplate
Identifies the UI template format that the ACS first
presents to the consumer.
Possible values:
 01: Text
 02: Single select
 03: Multi select
 04: OOB (Out of Band)
 05: HTML other
Valid values for each interface:
 Native UI: 01-04
 HTML UI: 01-05
HTML other is valid only when combined with HTML
UI. If used with Native UI, it results in error=203.
JSON Object Example:
{
"acsRenderingType":{
"acsInterface";"02",
"acsUiTemplate":03" }
}
pa_acs_transaction_id Unique transaction identifier assigned by the ACS to ics_pa_enroll String (36)
identify a single transaction.
ics_pa_validate

Payer Authentication Using the SCMP API | 172

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_authentication_ Indicates the type of authentication that is used to ics_pa_enroll Integer (2)
type challenge the card holder.
ics_pa_validate
Possible Values:
 01: Static
 02: Dynamic
 03: OOB (Out of Band)
Note EMV 3D Secure version 2.1.0 supports values
01-03. Version 2.2.0 supports values 01-03.
pa_cardholder_ Text provided by the AC or issuer or both to the ics_pa_enroll String (128)
message cardholder during a frictionless or decoupled
transaction. The issuer can provide information to
the cardholder. For example, “Additional
authentication is needed for this transaction. Please
contact (Issuer Name) at xxx-xxx-xxxx.”. The issuing
bank can choose to support this value.
pa_directory_server_ The directory server error code indicating a problem ics_pa_enroll Integer (3)
error_code with the transaction.
ics_pa_validate
pa_directory_server_ Directory server text and additional detail about the ics_pa_enroll String
error_description error for the transaction. (4096)
ics_pa_validate
pa_enroll_acs_url URL for the card-issuing bank’s authentication form ics_pa_enroll String (no
that you receive when the card is enrolled. The value length limit)
can be very large.

Payer Authentication Using the SCMP API | 173

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_ Indicates what displays to the customer during the ics_pa_enroll String (255)
authentication_path authentication process. This field can contain one of
these values:
 ADS: (Card not enrolled) customer prompted to
activate the card during the checkout process.
 ATTEMPTS: (Attempts processing) Processing...
briefly displays before the checkout process is
completed.
 ENROLLED: (Card enrolled) the card issuer’s
authentication window displays.
 UNKNOWN: Card enrollment status cannot be
determined.
 NOREDIRECT: (Card not enrolled, authentication
unavailable, or error occurred) nothing displays to
the customer.
The following values can be returned if you are using
rules-based payer authentication. See "Rules-Based
Payer Authentication," page 224:
 RIBA: The card-issuing bank supports risk-based
authentication, but whether the cardholder is likely
to be challenged cannot be determined.
 RIBA_PASS: The card-issuing bank supports
risk-based authentication and it is likely that the
cardholder will not be challenged to provide
credentials, also known as silent authentication.
pa_enroll_ Raw authentication data that comes from the card- ics_pa_enroll String w/
authentication_result issuing bank. Primary authentication field that numbers
indicates if authentication was successful and if only (255)
liability shift occurred. You should examine first the
result of this field. This field contains one of these
values:
 -1: Invalid PARes.
 0: Successful validation.
 1: Cardholder is not participating, but the attempt
to authenticate was recorded.
 6: Issuer unable to perform authentication.
 9: Cardholder did not complete authentication.
pa_enroll_ Message that explains the pa_enroll_ ics_pa_enroll String (255)
authentication_status_ authentication_result response field.
msg

Payer Authentication Using the SCMP API | 174

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_ Payer authentication transaction identifier passed to ics_pa_enroll String (20)
authentication_ link the check enrollment and validate authentication
transaction_id messages.
pa_enroll_cavv Unique identifier generated by the card-issuing bank ics_pa_enroll String (255)
for Visa, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo transactions after
the customer is authenticated. The value is in
Base64. When you request the card authorization
service, Cybersource automatically converts the
value, not the field name, to the format required by
your payment processor.
pa_enroll_cavv_ Field that is returned only when the CAVV is ics_pa_enroll Integer (1)
algorithm generated, which occurs when pa_enroll_pares_
status contains the values Y (successful
authentication) or A (attempted authentication). If
you use the ATOS processor, send the value of this
field in the cavv_algorithm request field of the
authorization service. This field contains one of these
values:
 2: Visa, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo
 3: Mastercard
pa_enroll_directory_ The Directory server transaction ID is generated by ics_pa_enroll String (36)
server_transaction_id the directory server during authentication and
returned with the authentication results. Your card
brand might require you to send this field in the
authorization service request.

Payer Authentication Using the SCMP API | 175

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_e_ Indicator used to differentiate different types of ics_pa_enroll String (255)
commerce_indicator transactions. This field contains one of these values:
 aesk: American Express SafeKey authentication
verified successfully.
 aesk_attempted: Card not enrolled in
American Express SafeKey, but the attempt to
authenticate is recorded.
 cs: Elo Compra Segura authentication verified
successfully.
 cs_attempted: Elo Compra Segura card not
enrolled, but attempt to authenticate is recorded.
 dipb: Discover ProtectBuy authentication
verified successfully.
 dipb_attempted: Card not enrolled in
Discover ProtectBuy, but the attempt to
authenticate is recorded.
 internet: Card not enrolled, or card type not
supported by payer authentication. No liability
shift.
 js: J/Secure authentication verified successfully.
 js_attempted: Card not enrolled, but attempt
to authenticate is recorded. Liability shift.
 js_failure: J/Secure directory service is not
available. No liability shift.
 pb: Diners Club ProtectBuy authentication
verified successfully.
 pb_attempted: Card not enrolled in Diners
Club ProtectBuy, but the attempt to authenticate is
recorded.
 spa: Mastercard card not enrolled in the Identity
Check program. No liability shift.
 spa_failure: Mastercard Identity Check failed
authentication.
 up3ds: China UnionPay authentication verified
successfully.
 up3ds_attempted: China UnionPay card not
enrolled, but attempt to authenticate is recorded.
 up3ds_failure: China UnionPay
authentication unavailable.
 vbv: Visa Secure authentication verified
successfully.

Payer Authentication Using the SCMP API | 176

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_e_  vbv_attempted: Card not enrolled, but ics_pa_enroll String (255)
commerce_indicator attempt to authenticate is recorded. Liability shift.
(continued)
 vbv_failure: For payment processor Barclays,
Streamline, AIBMS, or FDC Germany, you receive
this result if Visa’s directory service is not
available. No liability shift.
pa_enroll_eci Note This field applies only to non-U.S-issued ics_pa_enroll String (255)
cards.
Numeric electronic commerce indicator (ECI)
returned only for Visa, American Express, JCB,
Diners Club, Discover, China UnionPay, and Elo
transactions when the card is not enrolled.
If you are not using the Cybersource payment
services, you must send this value to your payment
processor in the subsequent request for card
authorization. This field contains one of these values:
 06: The card can be enrolled. Liability shift.
 07: The card cannot be enrolled. No liability shift.
pa_enroll_eci_raw ECI value that can be returned for Visa, Mastercard, ics_pa_enroll String (255)
American Express, JCB, Diners Club, Discover,
China UnionPay, and Elo. The field is absent when
authentication fails. If your payment processor is
Streamline, you must pass the value of this field
instead of the value of pa_enroll_eci or pa_enroll_
ucaf_collection_indicator. This field can contain
one of these values:
 01: Authentication attempted (Mastercard)
 02: Successful authentication (Mastercard)
 05: Successful authentication (Visa, American
Express, JCB, Diners Club, Discover, China
UnionPay, and Elo)
 06: Authentication attempted (Visa, American
Express, JCB, Diners Club, Discover, China
UnionPay, and Elo)
pa_enroll_pareq Payer authentication request (PAReq) message that ics_pa_enroll String (No
you need to forward to the ACS. The value can be length limit)
very large. The value is in Base64.

Payer Authentication Using the SCMP API | 177

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_pares_ Raw result of the authentication check. This field can ics_pa_enroll String (255)
status contain one of these values:
 A: Proof of authentication attempt was generated.
 C: Card challenged.This status is a temporary
status for an in-flight transaction and can result in
other authentication statuses after transaction is
completed.
 N: Customer failed or canceled authentication.
Transaction denied.
 R: Authentication rejected (used for 3D Secure 2.x
transactions only)
 U: Authentication not completed regardless of the
reason.
 Y: Customer was successfully authenticated.
Note If you are configured for Asia, Middle East,
and Africa Gateway Processing, you must send the
value of this field in your authorization request.
pa_enroll_proofxml Date and time of the enrollment check combined with ics_pa_enroll String (no
the VEReq and VERes elements. If you ever need length limit)
to show proof of enrollment checking, you may need
to parse the string for the information required by the
payment card company. The value can be very large.
For more information, see "Storing Payer
Authentication Data," page 208.
 For cards issued in the U.S. or Canada, Visa may
require this data for specific merchant category
codes.
 For cards not issued in the U.S. or Canada, your
bank may require this data as proof of enrollment
checking for any payer authentication transaction
that you re-present because of a chargeback.
pa_enroll_proxypan Encrypted version of the card number used in the ics_pa_enroll String (255)
payer authentication request message.
pa_enroll_rcode Code that indicates whether the ics_pa_enroll ics_pa_enroll Integer (1)
request was successful. The field will contain one of
these values:
 -1: An error occurred.
 0: The request was declined.
 1: The request was successful.
pa_enroll_rflag One-word description of the result of the ics_pa_ ics_pa_enroll String (255)
enroll request.

Payer Authentication Using the SCMP API | 178

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_enroll_rmsg Message that explains the response flag pa_enroll_ ics_pa_enroll String (255)
rflag.
pa_enroll_ This field contains the 3D Secure version that was ics_pa_enroll String (8)
specification_version used to process the transaction. For example, 1.0.2
or 2.0.0.
pa_enroll_ucaf_ AAV is a unique identifier generated by the card- ics_pa_enroll String (255)
authentication_data issuing bank for Mastercard Identity Check
transactions after the customer is authenticated. The
value is in Base64. Include the data in the card
authorization request.
pa_enroll_ucaf_ Returned only for Mastercard transactions. Indicates ics_pa_enroll String (255)
collection_indicator that authentication is not required because the
customer is not enrolled. Add the value of this field to
the authorization field ucaf_collection_indicator.
This field can contain these values: 0, 1.
pa_enroll_veres_ Result of the enrollment check. This field can contain ics_pa_enroll String (255)
enrolled one of these values:
 N: Card not enrolled; proceed with authorization.
 U: Unable to authenticate regardless of the
reason. No liability shift.
 Y: Card enrolled or can be enrolled; you must
authenticate. Liability shift.
The following value can be returned if you are using
rules-based Payer Authentication. See "Rules-Based
Payer Authentication," page 224:
 B: Indicates that authentication was bypassed.
Note If you are configured for Asia, Middle East,
and Africa Gateway Processing, you must send the
value of this field in your authorization request.
pa_enroll_xid Transaction identifier generated by Cybersource for ics_pa_enroll String (255)
successful enrollment checks. Use this value to
match an outgoing PAReq with an incoming PARes.
If your payment processor is Barclays, Cybersource
forwards the XID with your card authorization service
request. The value is in Base64.

Payer Authentication Using the SCMP API | 179

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_interaction_ Indicates the number of authentication cycles that ics_pa_validate Integer (2)
counter the cardholder attempted. It is tracked by the issuing
bank’s ACS.
Example When the customer receives the
challenge window, enters their one-time password,
and clicks submit, the interaction counter equals 1.
When the customer receives the challenge window,
receives the bank message asking if they want the
one-time password sent to their phone or email, and
they choose before going to the next screen to enter
their one-time password, the interaction count equals
2. One count is to choose how to have their one-time
password delivered. The second count is for entering
the one-time password and clicking Submit.
pa_ivr_enabled_ Indicates whether a valid Interactive Voice Response ics_pa_enroll String (5)
message (IVR) transaction was detected.
pa_ivr_encryption_key Encryption key to be used in the event the ACS ics_pa_enroll String (16)
requires encryption of the credential field.
pa_ivr_encryption_ Indicates whether the ACS requires the credential to ics_pa_enroll String (5)
mandatory be encrypted.
pa_ivr_encryption_ An indicator from the ACS to inform the type of ics_pa_enroll String (20)
type encryption that should be used in the event the ACS
requires encryption of the credential field.
pa_ivr_label An ACS-provided label that can be presented to the ics_pa_enroll String (20)
cardholder. Recommended use with an application.
pa_ivr_prompt An ACS-provided string that can be presented to the ics_pa_enroll String (80)
cardholder. Recommended use with an application.
pa_ivr_status_ An ACS-provided message that can provide ics_pa_enroll String (80)
message additional information.
pa_network_score The global score calculated by the Cartes Bancaires ics_pa_enroll String (2)
scoring platform and returned to the merchant.
pa_sdk_transaction_id SDK unique transaction identifier that is generated ics_pa_enroll String (36)
on each new transaction.
ics_pa_validate
pa_setup_pa_device_ Location to send the authentication JWT when you ics_pa_setup String (100)
data_collection_url invoke device data collection.
pa_setup_pa_ This identifier indicates that the device data ics_pa_setup String (50)
reference_id collection session has started. The value must be
passed in the authentication JWT when you invoke
device data collection.

Payer Authentication Using the SCMP API | 180

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_setup_rcode Indicates whether the service request was ics_pa_setup Integer (1)
successful. Possible values:
 -1: An error occurred.
 0: The request was declined.
 1: The request was successful.
pa_setup_rflag If the service request is unsuccessful, this field ics_pa_setup String (50)
contains a one-word description of the error.
pa_setup_rmsg Message that explains the response flag. ics_pa_setup String (255)
pa_step_up_url The fully qualified URL that the merchant uses to ics_pa_enroll String
post a form to the cardholder in order to complete the (2048)
Consumer Authentication transaction for the
Cardinal Cruise Direct Connection API integration.
Note Used by the Cardinal Cruise Direct
Connection API integration.
pa_three_ds_server_ Unique transaction identifier assigned by the 3D ics_pa_enroll String (36)
transaction_id Secure Server to identify a single transaction.
ics_pa_validate
pa_validate_ Raw authentication data that comes from the card- ics_pa_validate String w/
authentication_result issuing bank. Primary authentication field that numbers
indicates if authentication was successful and if only (255)
liability shift occurred. You should examine first the
result of this field. This field contains one of these
values:
 -1: Invalid PARes.
 0: Successful validation.
 1: Cardholder is not participating, but the attempt
to authenticate was recorded.
 6: Issuer unable to perform authentication.
 9: Cardholder did not complete authentication.
pa_validate_ Message that explains the pa_validate_ ics_pa_validate String (255)
authentication_status_ authentication_result response field.
msg
pa_validate_cavv Unique identifier generated by the card-issuing bank ics_pa_validate String (255)
for Visa, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo transactions after
the customer is authenticated. The value is in
Base64. When you request the card authorization
service, Cybersource automatically converts the
value, not the field name, to the format required by
your payment processor.

Payer Authentication Using the SCMP API | 181

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_validate_cavv_ Field that is returned only when the CAVV is ics_pa_validate Integer (1)
algorithm generated, which occurs when pa_validate_pares_
status contains the values Y (successful
authentication) or A (attempted authentication). If
you use the ATOS processor, send the value of this
field in the cavv_algorithm request field of the
authorization service. This field contains one of these
values:
 2: Visa, American Express, JCB, Diners Club,
Discover, China UnionPay, and Elo
 3: Mastercard
pa_validate_directory_ The Directory server transaction ID is generated by ics_pa_validate String (36)
server_transaction_id the directory server during authentication and
returned with the authentication results. Your card
brand might require you to send this field in the
authorization service request.

Payer Authentication Using the SCMP API | 182

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_validate_e_ Indicator used to differentiate different types of ics_pa_validate String (255)
commerce_indicator transactions. The authentication failed if this field is
not returned. For Visa, if your payment processor is
Streamline, Barclays, AIBMS, or FDC Germany, you
receive the value vbv_failure instead of
internet when pa_validate_eci is 07.
The value of this field is passed automatically to the
authorization service if you request the services
together. This field contains one of these values:
 aesk: American Express SafeKey authentication
verified successfully.
 aesk_attempted: Card not enrolled in
American Express SafeKey, but the attempt to
authenticate is recorded.
 cs: Elo Compra Segura authentication verified
successfully.
 cs_attempted: Elo Compra Segura card not
enrolled, but attempt to authenticate is recorded. .
 dipb: Discover ProtectBuy authentication
verified successfully.
 dipb_attempted: Card not enrolled in
Discover ProtectBuy, but the attempt to
authenticate is recorded.
 internet: Authentication was not verified
successfully.
 js: J/Secure authentication verified successfully.
 js_attempted: Card not enrolled in J/Secure,
but the attempt to authenticate is recorded.
 js_failure: You receive this result if JCB’s
directory service is not available. No liability shift.
 pb: Diners Club ProtectBuy authentication
verified successfully.
 pb_attempted: Card not enrolled in Diners
Club ProtectBuy, but the attempt to authenticate is
recorded.
 spa: Mastercard Identity Check authentication
verified successfully.
 spa_failure: Mastercard Identity Check failed
authentication.

Payer Authentication Using the SCMP API | 183

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_validate_e_  up3ds: China UnionPay authentication verified ics_pa_validate String (255)
commerce_indicator successfully.
(continued)
 up3ds_attempted: China UnionPay card not
enrolled, but attempt to authenticate is recorded.
 up3ds_failure: China UnionPay
authentication unavailable.
 vbv: Visa Secure authentication verified
successfully.
 vbv_attempted: Card not enrolled in Visa
Secure, but the attempt to authenticate is
recorded.
 vbv_failure: Visa Secure authentication
unavailable.
pa_validate_eci Numeric electronic commerce indicator (ECI) ics_pa_validate String (255)
returned only for Visa, American Express, JCB,
Diners Club, Discover, China UnionPay, and Elo
transactions. The field is absent when authentication
fails.
You must send this value to your payment processor
in the subsequent request for card authorization.
This field contains one of these values:
 05: Successful authentication
 06: Authentication attempted
 07: Failed authentication (No response from the
merchant because of a problem.)
pa_validate_eci_raw ECI value that can be returned for Visa, Mastercard, ics_pa_validate String (255)
American Express, JCB, Diners Club, Discover,
China UnionPay, and Elo. The field is absent when
authentication fails. If your payment processor is
Streamline, you must pass the value of this field
instead of the value of pa_validate_eci or pa_
validate_ucaf_collection_indicator. This field can
contain one of these values:
 01: Authentication attempted (Mastercard)
 02: Successful authentication (Mastercard)
 05: Successful authentication (Visa, American
Express, JCB, Diners Club, Discover, China
UnionPay, and Elo)
 06: Authentication attempted (Visa, American
Express, JCB, Diners Club, Discover, China
UnionPay, and Elo)

Payer Authentication Using the SCMP API | 184

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_validate_pares_ Raw result of the authentication check. This field can ics_pa_validate String (255)
status contain one of these values:
 A: Proof of authentication attempt was generated.
 N: Customer failed or canceled authentication.
Transaction denied.
 U: Authentication not completed regardless of the
reason.
 Y: Customer was successfully authenticated.
Note If you are configured for Asia, Middle East,
and Africa Gateway Processing, you must send the
value of this field in your authorization request.
pa_validate_rcode One-digit code that indicates whether the ics_pa_ ics_pa_validate Integer (1)
validate request was successful. The field will
contain one of these values:
 -1: An error occurred
 0: The request was declined
 1: The request was successful
pa_validate_rflag One-word description of the result of the ics_pa_ ics_pa_validate String (255)
validate request.
pa_validate_rmsg Message that explains the response flag pa_ ics_pa_validate String (255)
validate_rflag.
pa_validate_ This field contains the 3D Secure version that was ics_pa_validate String (8)
specification_version used to process the transaction. For example, 1.0.2
or 2.0.0.
pa_validate_ucaf_ AAV is a unique identifier generated by the card- ics_pa_validate String (255)
authentication_data issuing bank for Mastercard Identity Check
transactions after the customer is authenticated. The
value is in Base64. Include the data in the card
authorization request.

Payer Authentication Using the SCMP API | 185

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
pa_validate_ucaf_ Numeric electronic commerce indicator (ECI) ics_pa_validate Non-
collection_indicator returned only for Mastercard Identity Check negative
transactions. The field is absent when authentication integer (1)
fails. You must send this value to your payment
processor in the request for card authorization. This
field contain one of these values:
 0: UCAF collection is not supported at your web
site. Customer authentication was not completed.
 1: UCAF collection is supported at your web site,
and UCAF was populated. Customer
authentication was not completed.
 2: UCAF collection is supported at your web site,
and UCAF was populated. Customer completed
authentication.
pa_validate_xid Transaction identifier generated by Cybersource for ics_pa_validate String (255)
validation checks. Use this value, which is in
Base64, to match an outgoing PAReq with an
incoming PARes. Cybersource forwards the XID with
the card authorization service to these payment
processors in these cases:
 Barclays
 Streamline when the commerce indicator is spa
pa_white_list_status Enables the communication of trusted beneficiary ics_pa_enroll String (1)
and whitelist status among the ACS, the directory
ics_pa_validate
server, and the 3D Secure requester.
Possible Values:
 Y: 3D Secure requester is whitelisted by
cardholder
 N: 3D Secure requester is not whitelisted by
cardholder
pa_white_list_status_ This field is populated by the system setting Whitelist ics_pa_enroll Integer (2)
source Status.
ics_pa_validate
Possible Values:
 01: 3D Secure Server
 02: Directory server
 03: ACS
pares_status_reason Provides additional information about the PARes ics_pa_enroll String (2)
status value.
ics_pa_validate
request_id Identifier for the request generated by the client. ics_pa_enroll String (255)
ics_pa_validate

Payer Authentication Using the SCMP API | 186

 Appendix A API Fields

Table 23 Response Fields (Continued)

Field Name Description Returned By Data Type

& Length
request_token Identifier for the request generated by Cybersource. ics_pa_enroll String (256)
Request token data created by Cybersource for each ics_pa_setup
reply. The field is an encoded string that contains no
ics_pa_validate
confidential information such as an account or card
verification number. The string can contain a
maximum of 256 characters.

Payer Authentication Using the SCMP API | 187

 APPENDIX
Response Flags
B

Table 24 Response Flags Returned by the SCMP API

Response Flag Description Services

DAUTHENTICATE The customer participates in payer authentication. ics_pa_enroll
Authenticate the customer, and verify the results of
authentication.
DAUTHENTICATIONFAILED The results of payer authentication cannot be validated. ics_pa_enroll
ics_pa_validate
DINVALIDCARD The card number is invalid. ics_pa_enroll
DINVALIDDATA The data provided is not consistent with the request. ics_pa_enroll
ics_pa_validate
DMISSINGFIELD The request is missing a required field. ics_pa_enroll
ics_pa_validate
ESYSTEM A system error. Wait several minutes, then try sending your ics_pa_enroll
request again.
ics_pa_validate
ETIMEOUT The request timed out. ics_pa_enroll
ics_pa_validate
SOK The transaction was successful. ics_pa_enroll
ics_pa_validate

Payer Authentication Using the SCMP API | 188

 APPENDIX
Request and Response
Examples
C

This appendix contains examples for the check enrollment service and the validate
authentication service. All examples are in name-value pair format.

These examples contain only the fields essential to the demonstration. Do not
prepare your implementation according to the fields shown in these examples.
They are provided for your information only.

Cardinal Cruise Direct Connection

API Integration Examples

Payer Authentication Setup Service Request

Example
Example 27 Payer Authentication Setup Service Request

bill_address1=1234 Gold Ave

bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
customer_cc_expmo=12
customer_cc_expyr=2030
customer_cc_number=xxxxxxxxxxxxxxxx
card_type=001
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
ics_applications=ics_pa_setup
merchant_id=patest
merchant_ref_number=cybs_test

Payer Authentication Using the SCMP API | 189

 Appendix C Request and Response Examples

Payer Authentication Setup Service Response

Example
Example 28 Payer Authentication Setup Service Response

merchant_ref_number=cybs_test
pa_setup_pa_device_data_collection_url=https://
centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
pa_setup_rcode=1
pa_setup_pa_reference_id=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
pa_access_
token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi0zYmEz
LTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6IjVkZDg
zYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElkIjoiNT
VlZjNmMTBmNzIzYWE0MzFjOTliNWViIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL
zBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIv
Y3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnR
aWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WV
c1elNVUWlPaUkzTkRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkRFM01Ea
GhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVmlMV0V5
WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNkl
qQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifSwiT2JqZW
N0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zd
GVwLXVwLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-
efavZTNM0tWInYLTfE
request_id=5982993692286989203011
request_token=AxjzbwSTRFa3h+A4wXZDABEBURwlqraRpAy7gDthk0
kyro9JLIYA8AAA2wK2

Payer Authentication Using the SCMP API | 190

 Appendix C Request and Response Examples

Check Enrollment Request Example

Example 29 Check Enrollment Request

bill_address1=1234 Gold Ave

bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2030
customer_cc_number=xxxxxxxxxxxxxxxx
card_type=001
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
customer_phone=5102345678
ics_applications=ics_pa_enroll,ics_auth
merchant_id=patest
merchant_ref_number=cybs_test
pa_return_url=https://example.com/step-up-return-url.jsp
offer0=amount:100.00^product_name:abc^merchant_product_
sku:112233^offer_id:0^quantity:1^passenger_
email:[email protected]^passenger_phone:4089127721
...
<Other 2.x optional fields>
pa_reference_id=CybsTester-8ccf7c8a

Payer Authentication Using the SCMP API | 191

 Appendix C Request and Response Examples

Check Enrollment Response Example

Example 30 Check Enrollment Response

merchant_ref_number=cybs_test
pa_access_
token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi0zYmEz
LTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6IjVkZDg
zYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElkIjoiNT
VlZjNmMTBmNzIzYWE0MzFjOTliNWViIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL
zBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIv
Y3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnR
aWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WV
c1elNVUWlPaUkzTkRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkRFM01Ea
GhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVmlMV0V5
WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNkl
qQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifSwiT2JqZW
N0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zd
GVwLXVwLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-
efavZTNM0tWInYLTfE
pa_acs_transaction_id=8a947b83-04b4-4beb-a2b3-dcc1a5f94a12
pa_enroll_acs_url=https://0merchantacsstag.cardinalcommerce.com/
MerchantACSWeb/creq.jsp
pa_enroll_authentication_transaction_id=TD5oS0o1FC65qav0xsx0
card_bin=400000
card_type_name=VISA
challenge_required=false
pa_enroll_directory_server_transaction_id=395fb036-cfc6-462b-b28d-
d6ed7c970cdd
pa_enroll_
pareq=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwid
GhyZWVEU1NlcnZlclRyYW5zSUQiOiI3NDMyYTYwMC04MzM2LTRmODctYWJlOS02NmY3NDE3
MDhhMWQiLCJhY3NUcmFuc0lEIjoiOGE5NDdiODMtMDRiNC00YmViLWEyYjMtZGNjMWE1Zjk
0YTEyIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0
ics_decision_reason_code=475
pa_enroll_specification_version=2.2.0
pa_step_up_url=https://centinelapistag.cardinalcommerce.com/V2/Cruise/
StepUp
pa_three_ds_server_transaction_id=7432a600-8336-4f87-abe9-66f741708a1d
pa_enroll_veres_enrolled=Y
request_id=5982995245816268803007
request_token=AxjzbwSTRFa9DM1xnUu/
ABEBURwlqsQ5pAy7gDtXb0kyro9JLIYA8AAA2wK2

Payer Authentication Using the SCMP API | 192

 Appendix C Request and Response Examples

Validate Authentication Request Example

Example 31 Validate Authentication Request With Authorization

bill_address1=1234 Gold Ave

bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2030
customer_cc_number=xxxxxxxxxxxxxxxx
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
customer_phone=5102345678
ics_applications=ics_pa_validate
merchant_id=patest
merchant_ref_number=cybs_test
offer0=amount:100.00^product_name:abc^merchant_product_
sku:112233^offer_id:0^quantity:1^passenger_
email:[email protected]^passenger_phone:4089127721
pa_authentication_transaction_id=x0Jpbq2uIT7o0tQqwd60
pa_product_code=PHY

Example 32 Validate Authentication Request

merchant_id=patest
merchant_ref_number=cybs_test
offer0=amount:100.00^product_name:abc^merchant_product_
sku:112233^offer_id:0^quantity:1^passenger_
email:[email protected]^passenger_phone:4089127721
pa_authentication_transaction_id=hejNPA0YQlL5gVwZ6OX0
pa_product_code=PHY

Payer Authentication Using the SCMP API | 193

 Appendix C Request and Response Examples

Validate Authentication Response Example

Example 33 Validate Authentication Response With Authorization

auth_auth_amount=30.00
auth_auth_code=888888
auth_auth_time=2020-08-24T20:06:35Z
auth_auth_avs=X
auth_avs_raw=I1
auth_cv_result=M
auth_cv_result_raw=M
auth_payment_network_transaction_id=123456789619999
auth_auth_response=100
currency=USD
merchant_ref_number=cybs_test
pa_acs_transaction_id=8a947b83-04b4-4beb-a2b3-dcc1a5f94a12
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_e_commerce_indicator=spa
pa_validate_eci_raw=02
pa_validate_pares_status=Y
pa_validate_rcode=1
pa_validate_return_code=1050001
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_specification_version=2.0.1
pa_three_ds_server_transaction_id=432a600-8336-4f87-abe9-66f741708a1d
pa_validate_ucaf_authentication_data=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
pa_validate_ucaf_collection_indicator=2
request_id=5241742759776645501541
request_token=Ahj/7wSTHCfLNBLOq1JlESDNozat2rVrDjWZsOfVhp/wIpruGBJ/
wIpruHpA6cQfrYZNscUcfKjVf4F5McJ8s0Es6rUmUAAAZwsK

Payer Authentication Using the SCMP API | 194

 Appendix C Request and Response Examples

Example 34 Validate Authentication Response

currency=USD
merchant_ref_number=cybs_test
pa_acs_transaction_id=8a947b83-04b4-4beb-a2b3-dcc1a5f94a12
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_e_commerce_indicator=spa
pa_validate_eci_raw=02
pa_validate_pares_status=Y
pa_validate_rcode=1
pa_validate_return_code=1050001
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_specification_version=2.0.1
pa_three_ds_server_transaction_id=432a600-8336-4f87-abe9-66f741708a1d
pa_validate_ucaf_authentication_data=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
pa_validate_ucaf_collection_indicator=2
request_id=5241742759776645501541
request_token=Ahj/7wSTHCfLNBLOq1JlESDNozat2rVrDjWZsOfVhp/wIpruGBJ/
wIpruHpA6cQfrYZNscUcfKjVf4F5McJ8s0Es6rUmUAAAZwsK

Payer Authentication Using the SCMP API | 195

 Appendix C Request and Response Examples

Standard Integration Examples

The following is an example of a request for the check enrollment service:

Check Enrollment Request Example

Example 35 Check Enrollment Request
bill_address1=1234 Gold Ave
bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
card_type=001
currency=USD
customer_cc_expmo=01
customer_cc_expyr=2020
customer_cc_number=xxxxxxxxxxxxxxxx
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
customer_phone=5102345678
grand_total_amount=10
ics_applications=ics_pa_enroll
merchant_id=patest
merchant_ref_number=cybs_test
pa_authentication_transaction_id=S2mJR91kjL3jkt1vCW30
pa_mcc=9889
pa_mobile_phone=8765432111
pa_override_payment_method=CR
pa_product_code=CHA
reason_code=475
standard_2.0=true

Payer Authentication Using the SCMP API | 196

 Appendix C Request and Response Examples

Check Enrollment Response Example

Example 36 Transaction Response for Visa Card with Visa Secure

ics_decision_reason_code=100
ics_rcode=1
ics_return_code=1000000
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=cybs_test
pa_enroll_authentication_result=0
pa_enroll_authentication_status_msg=Success
pa_enroll_authentication_transaction_id=S2mJR91kjL3jkt1vCW30
pa_enroll_cavv=Y2FyZGluYWxjb21tZXJjZWF1dGg=
pa_enroll_e_commerce_indicator=vbv
pa_enroll_eci=05
pa_enroll_eci_raw=05
pa_enroll_pares_status=Y
pa_enroll_rcode=1
pa_enroll_return_code=1050000
pa_enroll_rflag=SOK
pa_enroll_rmsg=ics_pa_enroll service was successful
pa_enroll_specification_version=2.0.1
pa_enroll_veres_enrolled=Y
request_id=5241736293196265601541
request_token=Ahj77wSTHCe0OsC8NroFEU/4EU07jAU/
4EU07j0gV9D9ajLtjijj5Uar+ALJjhPaHWBeG10CgAAA+gzb

Payer Authentication Using the SCMP API | 197

 Appendix C Request and Response Examples

Hybrid Integration Examples

Check Enrollment Request Example

Example 37 Check Enrollment

bill_address1=1234 Gold Ave

bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=01
customer_cc_expyr=2020
customer_cc_number=xxxxxxxxxxxxxxxx
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
customer_phone=5102345678
ics_applications=ics_pa_enroll
merchant_id=patest
merchant_ref_number=cybs_test
offer0=amount:100.00^product_name:abc^merchant_product_
sku:112233^offer_id:0^quantity:1^passenger_
email:[email protected]^passenger_phone:4089127721
pa_mcc=9021
pa_mobile_phone=8765432111
pa_override_payment_method=NA
pa_product_code=TRA
...
<Other 2.x optional fields>
pa_reference_id=CybsTester-8ccf7c8a

Payer Authentication Using the SCMP API | 198

 Appendix C Request and Response Examples

Check Enrollment Response Example

Example 38 Transaction Response for Mastercard with Identity Check

ics_decision_reason_code=475
ics_rcode=0
ics_return_code=1000000
ics_rflag=DAUTHENTICATE
ics_rmsg=The cardholder is enrolled in Payer Authentication. Please
authenticate before proceeding with authorization.
merchant_ref_number=cybs_test
pa_enroll_acs_url=https://www.example.com
pa_enroll_authentication_transaction_id=x0Jpbq2uIT7o0tQqwd60
pa_enroll_
pareq=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMC4xIiwid
GhyZWVEU1NlcnZlclRyYW5zSUQiOiI5YjEzMThlNi0wOWIwLTRmMjUtYTNiNi05NTgzYzNl
N2VkNTUiLCJhY3NUcmFuc0lEIjoiYWE5YmQ3MTUtNzFiYy00NzUxLWI4YjgtYjg4YmU1NGJ
hYjhkIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIiwibm90aWZpY2F0aW9uVVJMIjoiaH
R0cHM6Ly9jZW50aW5lbGFwaXN0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vVjEvVGVybVVST
C8yLjAvQ0NBIn0=
pa_enroll_rcode=0
pa_enroll_return_code=1052000
pa_enroll_rflag=DAUTHENTICATE
pa_enroll_rmsg=The cardholder is enrolled in Payer Authentication.
Please authenticate before proceeding with authorization.
pa_enroll_specification_version=2.0.1
pa_enroll_veres_enrolled=Y
request_id=5241742620586610501541
request_
token=AhjzbwSTHCfKtXsaE6elEQJP+BFNcZtIHTiD9au3tjijj5Uar+AuAAAAkAY5

Payer Authentication Using the SCMP API | 199

 Appendix C Request and Response Examples

Validate Authentication Request Example

Example 39 Validate Authentication Request

bill_address1=1234 Gold Ave

bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=01
customer_cc_expyr=2020
customer_cc_number=xxxxxxxxxxxxxxxx
[email protected]
customer_firstname=FirstName
customer_lastname=LastName
customer_phone=5102345678
ics_applications=ics_pa_validate
merchant_id=patest
merchant_ref_number=cybs_test
offer0=amount:100.00^product_name:abc^merchant_product_
sku:112233^offer_id:0^quantity:1^passenger_
email:[email protected]^passenger_phone:4089127721
pa_authentication_transaction_id=x0Jpbq2uIT7o0tQqwd60
pa_product_code=PHY
pa_reference_id=CybsTester-8ccf7c8a

Payer Authentication Using the SCMP API | 200

 Appendix C Request and Response Examples

Validate Authentication Response Example

Example 40 Transaction Response for Mastercard with Identity Check

currency=USD
ics_decision_reason_code=100
ics_rcode=1
ics_return_code=1000000
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=cybs_test
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_e_commerce_indicator=spa
pa_validate_eci_raw=02
pa_validate_pares_status=Y
pa_validate_rcode=1
pa_validate_return_code=1050001
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_specification_version=2.0.1
pa_validate_ucaf_authentication_data=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
pa_validate_ucaf_collection_indicator=2
request_id=5241742759776645501541
request_token=Ahj/7wSTHCfLNBLOq1JlESDNozat2rVrDjWZsOfVhp/wIpruGBJ/
wIpruHpA6cQfrYZNscUcfKjVf4F5McJ8s0Es6rUmUAAAZwsK

Payer Authentication Using the SCMP API | 201

 APPENDIX
Website Modification
Reference
D

This appendix contains information about modifying your website to integrate Cybersource
Payer Authentication services into your checkout process. It also provides links to
payment card company websites where you can download the appropriate logos.

Website Modification Checklist

1 Modify web page buttons:

 Order submission button: disable the final “buy” button until the customer completes
all payment and authentication requirements.

 Browser back button: account 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.

2 Add appropriate logos:

 Make sure you have downloaded the appropriate logos of the cards that you support
and place these logos next to the card information entry fields on your checkout
pages. For more information about obtaining logos and using them, see "3D Secure
Services Logos," page 203.

3 Add informational message:

 Add a message next to the final “buy” button and the card logo to inform your
customers that they may be prompted to provide their authentication password or to
sign up for the authentication program specific to their card. For examples of
messages you can use, see "Informational Message Examples," page 204.

Payer Authentication Using the SCMP API | 202

 Appendix D Website Modification Reference

3D Secure Services Logos

The following 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.

Table 25 3D Secure Services Logos Download Location

3D 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 https://brand.mastercard.com/brandcenter.html
Check and Maestro
This website contains information about Identity Check, links to logos for download, and
information about integrating the Identity Check information into your website checkout
page.
For information about Maestro logos, go to:
http://www.mastercardbrandcenter.com/us/howtouse/bms_mae.shtml
American Express https://network.americanexpress.com/uk/en/safekey/
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/customer-service
ProtectBuy
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.

Payer Authentication Using the SCMP API | 203

 Appendix D Website Modification Reference

Informational Message Examples

Add a brief message adjacent to your final buy button on your checkout page to inform
customers that they may be prompted to provide their authentication password or to enroll
in the authentication program for their card.

The following examples may be used, but consult your specific card authentication
program to make sure you conform to their messaging requirements.

Example 41

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 will be 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 42

Your card may be eligible for enrollment or is enrolled in the 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 for
your password before you complete your purchase.

Payer Authentication Using the SCMP API | 204

 APPENDIX
Payer Authentication
Transaction Details in the
E
Business Center
This appendix describes how to search the Business Center for details of transactions that
are screened by Cybersource Payer Authentication. Transaction data is stored for 12
months so that you can send it to payment card companies if necessary.

Searching for Payer Authentication Details

Payer authentication data that is returned in API response fields can be searched by using
Transaction Search in the Business Center.

With other services, green means that the service request was successful, red means that
it failed, and black means that the service request was not run. However, you need to
interpret the result of the enrollment check differently:

 If the card is enrolled, the application result is shown in red, which indicates that you
need to authenticate the user before you can request card authorization.

 If the card is not enrolled, the application result is shown in green because you do not
need to authenticate the user. You can authorize the card immediately.

Enrolled Card
When a card is enrolled, the process consists of two steps: after you check for enrollment,
you need to authenticate the customer.

Enrollment Check
For the enrollment check for an enrolled card, payer authentication data is located in the
Transaction Search Details window in the following 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 had been requested at the same time, it would not have been
run and would appear in black.

You can obtain additional information about related orders by clicking the links on the
right (Event Search and Details).

Payer Authentication Using the SCMP API | 205

 Appendix E Payer Authentication Transaction Details in the Business Center

 Order Information section: When authentication is required, save the XID for use later.
You do not receive an ECI or AAV_CAVV because the authentication is not complete.

You need to authenticate the user by requesting the validation service.

Events Related to Payer Authentication

When the XID value is available, you also have the option to search for other parts of the
transaction with the By Payer Authentication History under Similar Searches link.

You can use the link to find the details page that shows the associated card validation and
authorization results. On the results page:

 The most recent event is the successful authentication. If you click the request ID, the
authentication details page opens. If the event also returned an XID value, the By
Payer Authentication History link is present. If you click it, you return to the results
page.

 The older event is the enrollment check.

If the card authorization service had been requested at the same time as payer
authentication, authorization would not have run with the enrollment check but with the
validate authentication request. On the results page:

 The most recent event is the combined successful customer authentication and card
authorization. If you click the request ID, the details page opens.

 The older event is the enrollment check in red because the card is enrolled.

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 the following sections:

 Request Information section: The validation service succeeded. You receive the
reason code 100, and the corresponding response message. The necessary payer
authentication information was passed to the card authorization service, which was
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.

Payer Authentication Using the SCMP API | 206

 Appendix E Payer Authentication Transaction Details in the Business Center

Card Not Enrolled

When the card is not enrolled, the enrollment check service result is shown 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 the following sections:

 Request Information section: the service is shown 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:

 The ECI value is 1: authentication is not required because the customer’s

Mastercard card is not enrolled.

 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.

Payer Authentication Search

Search for transactions that used the payer authentication and card authorization
services. When searching for transactions, consider the following:

 Search options:

 Use the XID as search parameter to find both parts of a transaction processed
with an enrolled card. When using the XID as search option, make sure to keep
the = sign at the end of the string.

 The list of applications is simplified 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 XID and the customer’s account
number (PAN). Use the XID to find all parts of the transaction.

 Payer authentication details: all transaction details are discussed under "Searching for
Payer Authentication Details," page 205.

Payer Authentication Using the SCMP API | 207

 Appendix E Payer Authentication Transaction Details in the Business Center

Storing Payer Authentication Data

Payment card companies allow a certain number of days between the payer
authentication and the authorization requests. If you settle transactions older than the pre-
determined number of days, payment card companies may require that you send them the
AAV, CAVV, or the XID if a chargeback occurs. The requirements depend on the card type
and the region. For more information, see 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.

You may be required to show the values that you receive in the PARes, the proof XML,
and the PAReq fields as proof of enrollment checking for any payer authentication
transaction that you present again because of a chargeback. Your account provider may
require that you provide all data in human-readable format, so make sure that you can
decode the PAReq and PARes. For enrollment response examples, see Appendix C,
"Request and Response Examples," on page 189. The responses are similar for all card
types.

Payment card companies have implemented the 3D Secure protocol in different ways
throughout the world. Cybersource recommends that you contact your merchant account
provider to find out what is required. For more information on decrypting and providing the
PARes contact your account manager.

Payer Authentication Using the SCMP API | 208

 APPENDIX
Payer Authentication
Reports
F

This chapter describes the reports that you can download from the Business Center. All
reports on the production servers are retained for 16 months but the transaction history is
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 that resulted in system
error or time-out are not. For more information about API responses and their meanings,
see Appendix A, "API Fields," on page 148.

To obtain the reports, you must file a support ticket in the Support Center.

Payer Authentication Summary Report

This daily, weekly, and monthly summary report indicates the performance of the
enrollment and validation services as a number of transactions and a total amount for
groups of transactions. The report provides this information for each currency and type of
card that you support. You can use this information to estimate how your transactions are
screened by payer authentication: 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.

Payer Authentication Using the SCMP API | 209

 Appendix F Payer Authentication Reports

Downloading the Report

To view the Payer Authentication Summary report:

Step 1 In the left navigation panel, click the Reports icon.

Step 2 Under Transaction Reports, click Payer Auth Summary. The Payer Auth Summary
Report page appears.

Step 3 In the search toolbar, select Date Range you want to include in the report. Account level
users must select a merchant as well.

Step 4 Based on the Date Range selected, choose the specific 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 first, then choose the desired month.

To view results from the period prior to or following the selected period, click Previous or
Next below the search toolbar.

Matching the Report to the Transaction Search

Results
The figure below shows the search results that contain the transactions that appear in the
above report. For more information on search results, see "Searching for Payer
Authentication Details," page 205.

Figure 3 Payer Authentication Report Details

Payer Authentication Using the SCMP API | 210

 Appendix F Payer Authentication Reports

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, you
receive a summary of your payer authentication validation results displayed as total
amount and number of transactions.

Table 26 Payer Authentication Report Interpretation

Card Type Interpretation Protected? Reported

Commerce Indicator ECI
Visa, No authentication No Internet 7
American
Recorded attempt to authenticate Yes VbV, Aesk, or JS 6
Express, and
Attempted
JCB
Successful authentication Yes VbV, JS, or Aesk 5
Mastercard No authentication No Internet2 71
and Maestro
Recorded attempt to authenticate Yes SPA 1
Successful authentication Yes SPA 2
Diners Club No authentication No Internet 7
and Discover
Recorded attempt to authenticate Yes PB or DIPB Attempted 6
Successful authentication Yes PB or DIPB 5
China No authentication No Internet 7
UnionPay, and
Recorded attempt to authenticate Yes CS or Up3ds 6
Elo
Attempted
Successful authentication Yes
CS or Up3ds 5
1 Although the report heading is 7, you receive a collection indicator value of 1, or the response field is empty.
2 Although the report heading is Internet, you receive spa_failure in the commerce indicator response
field.

Transactions are divided into two groups: those for which you are protected and those for
which you are not:

 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

Payer Authentication Using the SCMP API | 211

 Appendix F Payer Authentication Reports

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 because this report shows the transactions
that were validated by payer authentication, not necessarily the transactions that were
authorized. There are more likely to be reconciliation discrepancies if you process your
authorizations outside of Cybersource.

Example 43 Payer Authentication Reports Compared to Payment Reports

For 10,000 orders, you may receive the following results:

 9900 successful enrollment checks (Payer Authentication report)
 9800 successful authentication checks (Payer Authentication report)
 9500 successful authorization checks (Payment report)

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 first 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 Using the SCMP API | 212

 Appendix F Payer Authentication Reports

Payer Authentication Detail Report

Refer to the Business Center Reporting User Guide for instructions to download the report
and additional report information.

Report Elements
<Report>
The <Report> element is the root element of the report.
<Report>
<PayerAuthDetails>
(PayerAuthDetail+)
</PayerAuthDetails>
</Report>

Table 27 Child Elements of <Report>

Element Name Description

<PayerAuthDetail> Contains the transaction in the report. For a list of child elements, see
<PayerAuthDetail>.

Example <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>

Payer Authentication Using the SCMP API | 213

 Appendix F Payer Authentication Reports

Table 28 Child Elements of <PayerAuthDetail>

Element Name Description Type &

Length
<RequestID> Unique identifier generated by Cybersource for the transaction. Numeric (26)
This field corresponds to the request_idAPI field.
<MerchantID> Cybersource merchant ID used for the transaction. String (30)

<RequestDate> Date on which the transaction was processed. DateTime (25)

<TransactionType> Cybersource service requested in SCMP format. This field can String (20)
contain one of the following values:
 ics_auth: Card authorization service
 ics_pa_enroll: Payer Authentication Enrollment Check
 ics_pa_validate: Payer Authentication Validation
<ProofXML> Data that includes the date and time of the enrollment check and String (1024)
the VEReq and VERes elements. This field corresponds to the
pa_enroll_proofxml API field.
<VEReq> Verify Enrollment Request (VEReq) sent by the merchant’s server
to the directory server and by the directory server to the ACS to
determine whether authentication is available for the customer’s
card number. For a list of child elements, see "<VEReq>,"
page 216.
<VERes> Verify Enrollment Response (VERes) sent by the directory server.
For a list of child elements, see "<VERes>," page 217.
<PAReq> Payer Authentication Request message that you send to the ACS
through the payment card company. Corresponds to the pa_
enroll_pareq API field.
For a list of child elements, see "<PAReq>," page 218.
<PARes> Payer Authentication Response message sent by the ACS. For a
list of child elements, see "<PARes>," page 219.
<AuthInfo> Address and card verification data. For a list of child elements, see
"<AuthInfo>," page 221.

Payer Authentication Using the SCMP API | 214

 Appendix F Payer Authentication Reports

Example <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>

<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 pa_enroll_
proofxml API field.

<ProofXML>
(Date)
(DSURL)
(PAN)
(AcqBIN)
(MerID)
(Password)
(Enrolled)
</ProofXML>

Table 29 Child Elements of <ProofXML>

Element Name Description Type & Length

<Date> Date when the proof XML is generated. DateTime (25)
Note 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 proof XML originated. String (50)

Payer Authentication Using the SCMP API | 215

 Appendix F Payer Authentication Reports

Table 29 Child Elements of <ProofXML> (Continued)

Element Name Description Type & Length

<PAN> Customer’s masked account number. This element corresponds to the String (19)
pa_enroll_proxypan API field.
<AcqBIN> First six digits of the acquiring bank’s identification number. Numeric (6)

<MerID> Identifier provided by your acquirer; used to log into the ACS URL. String (24)

<Password> Merchant's masked authentication password to the ACS; provided by String (8)
your acquirer. Applies only to cards issued outside the U.S.
<Enrolled> Result of the enrollment check. This field can contain one of these String (1)
values:
 Y: Authentication available.
 N: Cardholder not participating.
 U: Unable to authenticate regardless of the reason.

Example <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>

Table 30 Child Elements of <VEReq>

Element Name Description Type & Length

<PAN> Customer’s masked account number. This element corresponds to the String (19)
pa_enroll_proxypan API field.
<AcqBIN> First six digits of the acquiring bank’s identification number. Numeric (6)

<MerID> Identifier provided by your acquirer; used to log in to the ACS URL. String (24)

Payer Authentication Using the SCMP API | 216

 Appendix F Payer Authentication Reports

Example <VEReq> Element

<VEReq>
<PAN>XXXXXXXXXXXX0771</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>example</MerID>
</VEReq>

<VERes>
The <VERes> element contains the enrollment check response data.
<VERes>
(Enrolled)
(AcctID)
(URL)
</VERes>

Table 31 Child Elements of <VERes>

Element Name Description Type & Length

<Enrolled> Result of the enrollment check. This field can contain one of these String (1)
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 send the PAReq. This element String (1000)
corresponds to the pa_enroll_acs_url API field.

Example <VERes> Element

<VERes>
<Enrolled>Y</Enrolled>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<URL>https://www.example_url.com</URL>
</VERes>

Payer Authentication Using the SCMP API | 217

 Appendix F Payer Authentication Reports

<PAReq>
The <PAReq> element contains the payer authentication request message. This element
corresponds to the pa_enroll_pareq API field.
<PAReq>
(AcqBIN)
(MerID)
(Name)
(Country)
(URL)
(XID)
(Date)
(PurchaseAmount)
(AcctID)
(Expiry)
</PAReq>

Table 32 Child Elements of <PAReq>

Element Name Description Type & Length

<AcqBIN> First six digits of the acquiring bank’s identification number. Numeric (6)

<MerID> Identifier provided by your acquirer; used to log in to the ACS URL. String (24)

<Name> Merchant’s company name. String (25)

<Country> Two-character code for the merchant’s country of operation. String (2)

<URL> Merchant’s business website. String

<XID> Unique transaction identifier generated by Cybersource for each String (28)
Payment Authentication Request (PAReq) message. The PARes sent
back by the issuing bank contains the XID of the PAReq. To ensure that
both XIDs are the same, compare it to the XID in the response. To find
all requests related to a transaction, you can also search transactions
for a specific XID.
<Date> Date and time of request. DateTime (25)
Note 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 Authorization amount and currency for the transaction. This element Amount (15)
Amount> corresponds to the totals of the offer lines or from the following field:
 grand_total_amount (see Credit Card Services Using the SCMP
API [PDF | HTML]).
<AcctID> Masked string used by the ACS. String (28)

<Expiry> Expiration month and year of the customer’s card. Number (4)

Payer Authentication Using the SCMP API | 218

 Appendix F Payer Authentication Reports

Example <PAReq> Element

<PAReq>
<AcqBIN>123456</AcqBIN>
<MerID>444444</MerID>
<Name>example</Name>
<Country>US</Country>
<URL>http://www.example.com</URL>
<XID>fr2VCDrbEdyC37MOPfIzMwAHBwE=</XID>
<Date>2020-02-09T08:00:34-08:00</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<Expiry>2309</Expiry>
</PAReq>

<PARes>
The <PARes> element contains the payer authentication response message.
<PARes>
(AcqBIN)
(MerID)
(XID)
(Date)
(PurchaseAmount)
(PAN)
(AuthDate)
(Status)
(CAVV)
(ECI)
</PARes>

Table 33 Child Elements of <PARes>

Element Name Description Type & Length

<AcqBIN> First six digits of the acquiring bank’s identification number. Numeric (6)

<MerID> Identifier provided by your acquirer; used to log in to the ACS String (24)
URL.
<XID> XID value returned in the customer authentication response. This String (28)
element corresponds to the pa_enroll_xid and pa_validate_xid
API fields.
<Date> Date and time of request. DateTime (25)
Note 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.

Payer Authentication Using the SCMP API | 219

 Appendix F Payer Authentication Reports

Table 33 Child Elements of <PARes> (Continued)

Element Name Description Type & Length

<PurchaseAmount> Authorization amount and currency for the transaction. This Amount (15)
element corresponds to the totals of the offer lines or from the
following field:
 grand_total_amount (see Credit Card Services Using the
SCMP API [PDF | HTML])
<PAN> Customer’s masked account number. This element corresponds String (19)
to the pa_enroll_proxypan API field.
<AuthDate> Date and time of request. DateTime (25)
Note 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 field can contain one of String (1)
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, Discover, String (50)
China UnionPay, and Elo) cards = * below) or AAV (Mastercard,
and Maestro cards = ** below) returned in the customer
authentication response. This element corresponds to the pa_
validate_cavv (*) and pa_validate_ucaf_authentication_data
(**) API fields.
<ECI> Electronic commerce indicator returned in the customer Numeric (1)
authentication response. This element corresponds to the pa_
validate_eci (*) and pa_validate_ucaf_collection_indicator (**)
API fields.

Payer Authentication Using the SCMP API | 220

 Appendix F Payer Authentication Reports

Example <PARes> Element

<PARes>
<AcqBIN>123456</AcqBIN>
<MerID>4444444</MerID>
<XID>Xe5DcjrqEdyC37MOPfIzMwAHBwE=</XID>
<Date>2020-02-09T07:59:46-08:00</Date>
<PurchaseAmount>1002.00 USD</PurchaseAmount>
<PAN>0000000000000771</PAN>
<AuthDate>2020-02-09T07:59:46-08:00</AuthDate>
<Status>Y</Status>
<CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
<ECI>5</ECI>
</PARes>

<AuthInfo>
The <AuthInfo> element contains address and card verification information.
<AuthInfo>
(AVSResult)
(CVVResult)
</AuthInfo>

Table 34 Child Elements of <AuthInfo>

Element Name Description Type & Length

<AVSResult> Optional results of the address verification test. String (1)
See auth_auth_avs or avs (if from external data) in Credit Card
Services Using the SCMP API (PDF | HTML).
<CVVResult> Optional results of the card verification number test. String (1)
See auth_cv_result or cv_result (if from external data) in Credit
Card Services Using the SCMP API (PDF | HTML).

Example <AuthInfo> Element

<AuthInfo>
<AVSResult>Y</AVSResult>
<CVVResult/>
</AuthInfo>

Payer Authentication Using the SCMP API | 221

 Appendix F Payer Authentication Reports

Examples
These examples show a complete transaction: the failed enrollment check (enrolled card)
and the subsequent successful authentication.

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”
<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>

Payer Authentication Using the SCMP API | 222

 Appendix F Payer Authentication Reports

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>
<ECI>5</ECI>
</PARes>
</PayerAuthDetail>
</PayerAuthDetails>
</Report>

Payer Authentication Using the SCMP API | 223

 APPENDIX
Rules-Based Payer
Authentication
G

Rules-based payer authentication enables you to specify rules that define how
transactions are authenticated by a 3D Secure card authentication program. For example,
you can decide to turn off active authentication for transactions that would otherwise
require customer interaction to avoid degrading the customer experience. However, you
may decide to authenticate customers from card-issuing banks that use risk-based
authentication because the authentication is performed without customer interaction.

To enable your account for rules-based payer authentication, contact your Cybersource
sales representative.

Depending on the card type and country, active mandates supersede

rules-based payer authentication and revert to traditional 3D Secure.

Available Rules
By default, when payer authentication is enabled on your account, authentication is
attempted on all transactions.

For transaction types that are not bypassed, you may be required to complete
authentication.

You can enable one or more of the following authentication transaction types. Any
transaction types that are set to bypass authentication return the response flag SOK. If
you receive response flag DAUTHENTICATE from the enrollment check, you must
complete validation even if no customer participation is needed.

Payer Authentication Using the SCMP API | 224

 Appendix G Rules-Based Payer Authentication

Table 35 Rules-Based Payer Authentication Types

Authentication Type Description Test Case Example

Active Authentication Customer is prompted to authenticate. Test Case 1: Visa Secure
Card Enrolled: Successful Authentication
Attempts Processing Customer is prompted to enroll in a 3D Test Case 3: Visa Secure
Secure card authentication program. Card Enrolled: Attempts Processing
This transaction type provides full 3D
Secure benefits.
Non-Participating Bank Card-issuing bank does not participate Test Case 9: Visa Secure
in a 3D Secure program. When Card Not Enrolled
enrollment is checked, this transaction
type provides full 3D Secure benefits,
including fraud chargeback liability shift
for customer “I didn’t do it” transactions
and interchange reduction of 5-59 basis
points.
Passive Authentication Customer is not prompted to
authenticate. This transaction type
provides full 3D Secure benefits when
passive authentication is completed.
Risk-Based Bank Card-issuing bank uses risk-based
authentication. The likely outcome is that
the customer is not challenged to enter
credentials. Most authentications
proceed without customer interaction.
This transaction type provides full 3D
Secure benefits.

API Responses
By default, API responses that are specifically associated with rules-based
payer authentication are turned off. Contact Cybersource Customer Support to
enable these API responses when rules are triggered.

Bypassed Authentication Transactions

When card authentication is bypassed as a result of your rules-based payer authentication
configuration, you can receive the following value for enrollment checks:

 pa_enroll_veres_enrolled = B (indicates that authentication was bypassed)

Payer Authentication Using the SCMP API | 225

 Appendix G Rules-Based Payer Authentication

Risk-Based Bank Transactions

When a transaction involves a card-issuing bank that supports risk-based authentication,
you may receive the following authentication path responses, depending on whether the
card-issuing bank deems the transaction risky:

 pa_enroll_authentication_path

 = RIBA
The card-issuing bank supports risk-based authentication, but whether the
cardholder is likely to be challenged cannot be determined.

 = RIBA_PASS
The card-issuing bank supports risk-based authentication, and it is likely that the
cardholder will not be challenged to provide credentials; also known as silent
authentication.

Payer Authentication Using the SCMP API | 226

 APPENDIX
Implementing
Hybrid or Standard
H
Payer Authentication
This appendix summarizes the process of integrating Payer Authentication services into
your existing business processes with Hybrid or Standard integration. Cybersource Payer
Authentication services use CardinalCommerce JavaScript to leverage the authentication.
The JavaScript Documentation links in this section navigate to the Cardinal site.

The Cardinal Cruise Direct Connection API is the recommended integration

method. For more information, see Chapter 2, Implementing Cardinal Cruise
Direct Connection API Payer Authentication.

Hybrid Payer Authentication

If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.

Implementation Overview
Notify your Cybersource account representative that you want to implement payer
authentication (3D Secure). Give them the Cybersource merchant ID that you will use for
testing. For more information, see "Required Merchant Information," page 22.

Implementation tasks include:

 Add the JavaScript code to your checkout page

 For each purchase request

 Build the authentication request

 Call the ics_pa_enroll: Payer Authentication Enrollment Check service
 Invoke the authentication
 Handle declines

Payer Authentication Using the SCMP API | 227

 Appendix H Implementing Hybrid or Standard Payer Authentication

 Call the following services:

- ics_pa_validate: Payer Authentication Validation (only for Hybrid integration)
- ics_auth: Card Authorization service (optional)

 Use the test cases to test your preliminary code and make appropriate changes. You
can change to the test environment by changing the URL in your JavaScript code.
See Chapter 5, "Testing Payer Authentication Services," on page 64.

 Ensure that your account is configured for production.

Process Flow for Hybrid Integration

1 You generate a JSON Web Token (JWT).

2 You add the JavaScript tag to your checkout page.

3 Call Cardinal.setup().

4 Run BIN detection. If the BIN is eligible for 3D Secure 2.x, it gathers the proper Method
URL JavaScript required by the issuer to collect additional device data.

5 You request the Enrollment Check service, passing in transaction details and the pa_
reference_id request field.

6 If the issuing bank does not require authentication, you receive the following information in
the Enrollment Check response:
 E-commerce indicator
 CAVV (all card types except Mastercard)
 AAV (Mastercard only)
 Transaction ID
 3D Secure version
 Directory server transaction ID

7 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.

8 The JavaScript displays the authentication window, and the customer enters the
authentication information.

9 The bank validates the customer credentials, and a JWT is returned that the merchant is
required to validate server-side for security reasons.

Payer Authentication Using the SCMP API | 228

 Appendix H Implementing Hybrid or Standard Payer Authentication

10 You request the Validate Authentication service, extracting the processor transaction ID
value from the JWT and sending it in the pa_authentication_transaction_id request
field. You receive the e-commerce indicator, CAVV or AAV, transaction ID, 3D 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," page 236.

Before You Begin

Before you can implement payer authentication services, your business team must
contact your acquirer and Cybersource to establish the service. Your software
development team should become familiar with the API fields and technical details of this
service.

Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). For further
information, contact Cybersource Customer Support.

Create the JSON Web Token (JWT)

The Hybrid integration uses JWTs as the method of authentication.

For security reasons, all JWT creation must be done on the server side.

When creating the JWT, use your company API Key as the JWT secret. You can use any
JTW library that supports JSON Web Signature (JWS). For further information about
JWTs, see https://jwt.io/.

Payer Authentication Using the SCMP API | 229

 Appendix H Implementing Hybrid or Standard Payer Authentication

JWT Claims
Table 36 lists the standard claims that can be used in a JWT claim set.

Table 36 JWT Claims

Claim Name Description

Required Note Each claim key is case sensitive.
jti JWT ID - unique identifier for the JWT. This field should
change each time a JWT is generated.
iat Issued at - the epoch time in seconds beginning when the
JWT is issued. This value indicates how long a JWT has
existed and can be used to determine if it is expired.
iss Issuer - identifier of who is issuing the JWT. Contains the
API key identifier or name.
OrgUnitId The merchant SSO Org Unit Id.

Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Hybrid integration API and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.

exp Expiration - the numeric epoch time in which the JWT

should be considered expired. This value is ignored if it is
more than 4 hours.

Payer Authentication Using the SCMP API | 230

 Appendix H Implementing Hybrid or Standard Payer Authentication

JWT Examples
Example 44 shows the JSON content of a basic JWT payload that passes an object within
the payload claim.

Example 44 Raw JWT

{
"jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e",
"iat": 1448997865,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": {
"OrderDetails": {
"OrderNumber": "0e5c5bf2-ea64-42e8-9ee1-71fff6522e15",
"Amount": "1500",
"CurrencyCode": "840"
}
},
"ObjectifyPayload": true,
"ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15",
"exp": 1449001465,
}

Example 45 shows the JSON content of a basic JWT payload that passes a string within
the payload claim.

Example 45 Stringified JWT

{
"jti": "29311a10-5048-11e6-8c35-8789b865ff15",
"iat": 1448997875,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": "{\"OrderDetails\":{\"OrderNumber\":\"19ec6910-5048-11e6-
8c35-8789b865ff15\",\"Amount\":\"1500\",\"CurrencyCode\":\"840\"}}",
"ObjectifyPayload" false
"ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15"
"exp":1449001465,
}

Payer Authentication Using the SCMP API | 231

 Appendix H Implementing Hybrid or Standard Payer Authentication

Add the JavaScript

Add Songbird.js to your checkout page and complete the additional steps:

1 Configure it: create the configuration object and pass it to Cardinal.configure().

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 allows the card-issuing bank’s ACS provider to collect
additional device data; it can help speed up the authentication process by collecting this
data before the checkout page launches. This step occurs prior to authentication and must
occur before the Cardinal.start event (Standard integration) or Check Enrollment service
request (Hybrid integration). For further information, see the JavaScript Documentation.

Implementing Hybrid Payer Authentication

Requesting the Check Enrollment Service (Hybrid)

Request the Check Enrollment service to verify that the card is enrolled in a card
authentication program. The following fields are required:

 amount or grand_total_amount
 bill_address1
 bill_city
 bill_country
 bill_state
 bill_zip
 card_type
 currency
 customer_cc_expmo
 customer_cc_expyr

Payer Authentication Using the SCMP API | 232

 Appendix H Implementing Hybrid or Standard Payer Authentication

 customer_cc_number
 customer_email
 customer_firstname
 customer_lastname
 ics_applications
 merchant_id
 merchant_ref_number
 pa_reference_id

You can send additional request data in order to reduce your issuer step-up
authentication rates. It is best to send all available fields.

For further details on required and optional fields, see "Request-Level Fields," page 149.

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 if your customer is not
enrolled in a payer authentication program. In this case, the field values that are
required in order to prove that you attempted to check enrollment are passed
automatically to the authorization service. If authentication is required, processing
automatically stops.

 Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).

Table 37 lists these fields.

Table 37 Enrollment Check and Response Fields

Identifier Enrollment Check Response Card Authorization

Field Request Field
E-commerce indicator pa_enroll_e_commerce_indicator e_commerce_indicator
Collection indicator pa_enroll_ucaf_collection_indicator ucaf_collection_indicator
(Mastercard only)
Result of the enrollment pa_enroll_veres_enrolled veres_enrolled
check for Asia, Middle
East, and Africa Gateway
3D Secure version pa_enroll_specification_version pa_specification_version
Directory server pa_enroll_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Payer Authentication Using the SCMP API | 233

 Appendix H Implementing Hybrid or Standard Payer Authentication

Interpreting the Response

The responses are similar for all card types. See Appendix C, "Request and Response
Examples," on page 189 for examples of enrollment responses.

 Enrolled Cards

You receive response flag DAUTHENTICATE if the customer’s card is enrolled in a

payer authentication program. When you receive this response, you can proceed to
validate authentication.

 Cards Not Enrolled

You receive response flag SOK in the following cases:

 When the account number is not enrolled in a payer authentication program. The
other services in your request are processed normally.
 When payer authentication is not supported by the card type.
When you receive this response, you can proceed to card authorization.

Payer Authentication Using the SCMP API | 234

 Appendix H Implementing Hybrid or Standard Payer Authentication

Authenticating Enrolled Cards

When you have verified 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 pa_enroll_authentication_transaction_id response field in
the Cardinal.continue function in order to proceed with the authentication session as
shown in Example 46.

Example 46 Cardinal.continue

Cardinal.continue('cca',

"AcsUrl":"https://testcustomer34.cardinalcommerce.com/
merchantacsfrontend/pareq.jsp?vaa=b&amp;gold=AAAAAAAA...AAAAAAA",

"Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGO
cz/se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ=="

},

"OrderDetails":{

"TransactionId" :"123456abc"

);

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.

Payer Authentication Using the SCMP API | 235

 Appendix H Implementing Hybrid or Standard Payer Authentication

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 Example 47.

Example 47 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 pa_authentication_transaction_id request field

 Send the credit card information including the PAN, currency, and expiration date
(month and year).

The response that you receive contains the validation result.

Cybersource recommends that you request both payer authentication and card
authorization services at the same time. When you do so, Cybersource automatically
sends the correct information to your payment processor; Cybersource converts the
values of these fields to the proper format required by your payment processor:

 E-commerce indicator: pa_enroll_e_commerce_indicator

 CAVV: pa_validate_cavv
 AAV: pa_validate_ucaf_authentication_data
 XID: pa_enroll_xid and pa_validate_xid

If you request the services separately, you must manually include the validation result
values (Validation Check Response Fields) in the authorization service request (Card
Authorization Request Fields). To receive liability shift protection, you must ensure that

Payer Authentication Using the SCMP API | 236

 Appendix H Implementing Hybrid or Standard Payer Authentication

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 3D Secure version, the directory server
transaction ID, and the following card-specific information in your authorization request:

 For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).

 For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.

Table 38 lists these fields.

Table 38 Validation Check and Response Fields

Identifier Validation Check Response Card Authorization

Field Request Field
E-commerce indicator pa_validate_e_commerce_indicator e_commerce_indicator
Collection indicator pa_validate_ucaf_collection_ ucaf_collection_indicator
(Mastercard only) indicator
CAVV (Visa and American pa_validate_cavv cavv
Express only)
AAV (Mastercard only. pa_validate_ucaf_authentication_ ucaf_authentication_data
Known as UCAF) data
XID pa_validate_xid xid
3D Secure version pa_validate_sepcification_version pa_specification_version
Directory server pa_validate_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

Interpreting the Response

If the authentication fails, Visa, American Express, JCB, Diners Club, Discover,
China UnionPay, and Elo require that you do not accept the card. 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:

You receive the response flag SOK, and other service requests, including
authorization, are processed normally.

Payer Authentication Using the SCMP API | 237

 Appendix H Implementing Hybrid or Standard Payer Authentication

 Failure:

You receive the response flag DAUTHENTICATIONFAILED, so the other services in

your request are not processed.

 Error:

If you receive an error from the payment card company, process the order according
to your business rules. If the error occurs frequently, report it to Customer Support. If
you receive a Cybersource 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. You must ensure that all messages that display to customers are
accurate, complete, and that they address all possible scenarios for enrolled and
nonenrolled cards. For example, if the authentication fails, a message such as the
following 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.

Standard Payer Authentication

Implementation Overview
Notify your Cybersource account representative that you want to implement payer
authentication (3D Secure). Give them the Cybersource merchant ID that you will use for
testing. For more information, see "Required Merchant Information," page 22.

Implementation tasks include:

 Add the JavaScript code to your checkout page

 For each purchase request

 Build the authentication request

 Invoke the authentication
 Handle declines

Payer Authentication Using the SCMP API | 238

 Appendix H Implementing Hybrid or Standard Payer Authentication

 Call the following services:

- ics_pa_enroll: Payer Authentication Enrollment Check
- ics_auth: Card Authorization service (optional)

 Use the test cases to test your preliminary code and make appropriate changes. You
can change to the test environment by changing the URL in your JavaScript code.
See Chapter 5, "Testing Payer Authentication Services," on page 64.

 Ensure that your account is configured for production.

Process Flow for Standard Integration

1 You generate a JSON Web Token (JWT).

2 You add the JavaScript tag to your checkout page.

3 Call Cardinal.setup().

4 Run BIN detection. If the BIN is eligible for 3D Secure 2.x, it gathers the proper Method
URL JavaScript required by the issuer to collect additional device data.

5 When the customer places an order on your website, you call the cardinal.start function to
pass in the transaction level data including the full PAN and order details.

6 The JavaScript verifies with the bank that the card is enrolled in a 3D Secure card
authentication program by using a server-to-server call.

7 If the issuing bank requires authentication, the JavaScript displays the authentication
window.

8 If required, the customer enters the authentication information.

9 The bank validates the customer credentials, and a JWT is returned that the merchant is
required to validate server-side for security reasons.

10 You request the ICS Enrollment Check service, extracting the processor transaction ID
value from the JWT and sending it in the pa_authentication_transaction_id request
field. You receive this information:
 E-commerce indicator
 CAVV (all card types except Mastercard)
 AAV (Mastercard only)
 Transaction ID
 3D Secure version
 Directory server transaction ID

Verify that the authentication was successful and continue processing your order.

Payer Authentication Using the SCMP API | 239

 Appendix H Implementing Hybrid or Standard Payer Authentication

You must pass all pertinent data for the card type and processor in your authorization
request. For more information, see "Requesting the Check Enrollment Service
(Standard)," page 244.

Before You Begin

Before you can implement payer authentication services, your business team must
contact your acquirer and Cybersource to establish the service. Your software
development team should become familiar with the API fields and technical details of this
service.

Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). For further
information, contact Cybersource Customer Support.

Create the JSON Web Token (JWT)

The Standard integration uses JWTs as the method of authentication.

For security reasons, all JWT creation must be done on the server side.

When creating the JWT, use your company API Key as the JWT secret. You can use any
JTW library that supports JSON Web Signature (JWS). For further information about
JWTs, see https://jwt.io/.

JWT Claims
Table 36 lists the standard claims that can be used in a JWT claim set.

Table 39 JWT Claims

Claim Name Description

Required Note Each claim key is case sensitive.
jti JWT ID - unique identifier for the JWT. This field should
change each time a JWT is generated.
iat Issued at - the epoch time in seconds beginning when the
JWT is issued. This value indicates how long a JWT has
existed and can be used to determine if it is expired.
iss Issuer - identifier of who is issuing the JWT. Contains the
API key identifier or name.

Payer Authentication Using the SCMP API | 240

 Appendix H Implementing Hybrid or Standard Payer Authentication

Table 39 JWT Claims (Continued)

Claim Name Description

OrgUnitId The merchant SSO Org Unit Id.

Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Standard integration API and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.

exp Expiration - the numeric epoch time in which the JWT

should be considered expired. This value is ignored if it is
more than 4 hours.

JWT Examples
Example 44 shows the JSON content of a basic JWT payload that passes an object within
the payload claim.

Example 48 Raw JWT

{
"jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e",
"iat": 1448997865,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": {
"OrderDetails": {
"OrderNumber": "0e5c5bf2-ea64-42e8-9ee1-71fff6522e15",
"Amount": "1500",
"CurrencyCode": "840"
}
},
"ObjectifyPayload": true,
"ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15",
"exp": 1449001465,
}

Payer Authentication Using the SCMP API | 241

 Appendix H Implementing Hybrid or Standard Payer Authentication

Example 45 shows the JSON content of a basic JWT payload that passes a string within
the payload claim.

Example 49 Stringified JWT

{
"jti": "29311a10-5048-11e6-8c35-8789b865ff15",
"iat": 1448997875,
"iss": "56560a358b946e0c8452365ds",
"OrgUnitId": "565607c18b946e058463ds8r",
"Payload": "{\"OrderDetails\":{\"OrderNumber\":\"19ec6910-5048-11e6-
8c35-8789b865ff15\",\"Amount\":\"1500\",\"CurrencyCode\":\"840\"}}",
"ObjectifyPayload" false
"ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15"
"exp":1449001465,
}

Add the JavaScript

Add Songbird.js to your checkout page and complete the additional steps:

1 Configure it: create the configuration object and pass it to Cardinal.configure().

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 allows the card-issuing bank’s ACS provider to collect
additional device data; it can help speed up the authentication process by collecting this
data before the checkout page launches. This step occurs prior to authentication and must
occur before the Cardinal.start event (Standard integration) or Check Enrollment service
request (Hybrid integration). For further information, see the JavaScript Documentation.

Payer Authentication Using the SCMP API | 242

 Appendix H Implementing Hybrid or Standard Payer Authentication

Implementing Standard Payer Authentication

Starting Authentication
The JavaScript handles the device data collection, initiates the transaction for
authentication, displays the authentication window if required, and returns the
authentication results.

You initiate this authentication process, usually when the customer clicks the Place Order
or Submit Order button, by triggering Cardinal.start(). Cardinal.start() invokes the
authentication and authenticates the customer.

Create an order object to pass to the Cardinal.start() event. The more fields you include,
the less likely the cardholder will be challenged to provide credentials.

Initiate Cardinal.start() before the authorization as shown in Example 50. The second
argument of data is a Request Order Object. You can construct this object ahead of time
or pass it directly as shown.

Example 50 Cardinal.start with Request Order Object

Cardinal.start("cca", {
OrderDetails: {
OrderNumber: "1234567890"
},
Consumer: {
Account: {
AccountNumber: "4000000000001000",
ExpirationMonth: "01",
ExpirationYear: "2099"
...
<Other 2.x required/optional fields>

}
}
...
});

Payer Authentication Using the SCMP API | 243

 Appendix H Implementing Hybrid or Standard Payer Authentication

Payments.validated returns the authentication results and response JWT along with the
processor transaction ID as shown in Example 51.

Example 51 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"
}
}

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 all messages that display to customers are
accurate, complete, and that they address all possible scenarios for enrolled and
nonenrolled cards. For example, if the authentication fails, a message such as the
following 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.

Requesting the Check Enrollment Service (Standard)

Once the validation is complete, use the Check Enrollment service to obtain the values
needed for authorization.

To request the Check Enrollment service, extract the processor transaction ID value
from the JWT and send it in the pa_authentication_transaction_id request field. The
following fields are also required:

 amount or grand_total_amount
 bill_address1
 bill_city
 bill_country

Payer Authentication Using the SCMP API | 244

 Appendix H Implementing Hybrid or Standard Payer Authentication

 bill_state
 bill_zip
 card_type
 currency
 customer_cc_expmo
 customer_cc_expyr
 customer_cc_number
 customer_email
 customer_firstname
 customer_lastname
 ics_applications
 merchant_id
 merchant_ref_number
 pa_reference_id

You can send additional request data in order to reduce your issuer step-up
authentication rates. It is best to send all available fields.

For further details on required and optional fields, see "Request-Level Fields," page 149.

Cybersource recommends that you request both payer authentication and card
authorization services at the same time. When you do so, Cybersource automatically
sends the correct information to your payment processor; Cybersource converts the
values of these fields to the proper format required by your payment processor:

 E-commerce indicator: pa_enroll_e_commerce_indicator

 CAVV: pa_validate_cavv
 AAV: pa_validate_ucaf_authentication_data
 XID: pa_enroll_xid and pa_validate_xid

If you request the services separately, you must manually include the enrollment check
result values (Enrollment Check Response Fields) in the authorization service request
(Card Authorization Request Fields). To receive liability shift protection, you must ensure
that you pass all pertinent data for the card type and processor in your request. Failure to
do so may invalidate your liability shift for that transaction. Include the electronic
commerce indicator (ECI), the transaction ID (XID), the 3D Secure version, the directory
server transaction ID, and the following card-specific information in your authorization
request:

 For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).

Payer Authentication Using the SCMP API | 245

 Appendix H Implementing Hybrid or Standard Payer Authentication

 For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.

Table 40 lists these fields.

Table 40 Enrollment Check and Response Fields

Identifier Enrollment Check Response Card Authorization

Field Request Field
E-commerce indicator pa_enroll_e_commerce_indicator e_commerce_indicator
CAVV (Visa and American pa_enroll_cavv cavv
Express only)
AAV (Mastercard only. pa_enroll_ucaf_authentication_data ucaf_authentication_data
Known as UCAF)
XID pa_enroll_xid xid
3D Secure version pa_enroll_specification_version pa_specification_version
Directory server pa_enroll_directory_server_ directory_server_
transaction ID transaction_id transaction_id
Note Not required for 3D
Secure 1.0.

In most cases, you request card authorization only once for each purchase. However, you
must send multiple authorization requests if the original authorization expires before it is
captured, which can occur when order fulfillment is split or delayed. In these cases, you
must include in subsequent authorization requests the same payer authentication data
contained in the original request so that your acquiring bank can track all related requests
if a dispute occurs. Authentication data can only be used for one authorization and cannot
be used multiple times or on subsequent authorizations.

Payer Authentication Using the SCMP API | 246

 APPENDIX
Alternate Methods for
Device Data Collection
I

This appendix describes alternate methods for device data collection. You can also use
the Payer Authentication Setup service described in Chapter 2, Implementing Cardinal
Cruise Direct Connection API Payer Authentication.

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 3D Secure 2.x request and invoke the 3D Secure Method URL when it is available.

The Cardinal Cruise Direct Connection API places the required Method URL on the
merchant's site within an iframe if the issuing bank chooses to use one. (According to
EMV 3D Secure requirements, a merchant must place and run the Method URL on their
website if the issuing bank uses one.)

The Method URL is a concept in the EMV 3D Secure protocol that allows 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 3D Secure protocol. This
process also occurred in 3D 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:
 Obtain access to the card BIN (first 8 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

Payer Authentication Using the SCMP API | 247

 Appendix I Alternate Methods for Device Data Collection

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 (first 8 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.

Option 1: 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.

Step 1 Add the card BIN (first 8 digits or full card number) to the transactional JWT.

Step 2 Create a POST request to send the transactional JWT to the device data collection URL.

Step 3 Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.
Example 52 shows the return URL populated in the transactional JWT instead of a POST
parameter.

Example 52 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
specification" />
</form>
<script>window.onload = function() {
// Auto submit form on page load
document.getElementById('collectionForm').submit();
}
</script>
</iframe>

Payer Authentication Using the SCMP API | 248

 Appendix I Alternate Methods for Device Data Collection

Option 2: 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.

Step 1 Create a POST request to send the transactional JWT and the card BIN (first 8 digits or
full card number) to the device data collection URL.

Step 2 Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.

Example 53 shows the return URL populated in the transactional JWT along with a POST
parameter.

Example 53 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 8 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>

Payer Authentication Using the SCMP API | 249

 GLOSSARY
Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Numerics

3D 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 3D

Secure transaction. For Mastercard Identity Check, the AAV is named the UCAF.
For Visa Secure, the AAV is named the CAVV.

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

acquirer BIN A 6-digit number that uniquely identifies 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 that provides credit card processing, settlement, and services to
processor merchant banks.

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

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

ADS Activation During Shopping. The card issuer’s ability to ask the cardholder to
enroll in the card authentication service when the merchant posts to the ACS URL

Payer Authentication Using the SCMP API | 250

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A (Continued)

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

API Application Programming Interface. A specification that can be used by software

components to communicate with each other.

authentication Raw data sent by the card issuer that indicates the status of authentication. It is
result 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 specific 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-specific fields containing card enrollment details. If these fields 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 fines.

Base64 Standard encoding method for data transfer over the Internet.

BIN Bank Identification Number. The 6-digit number at the beginning of the card that
identifies the card issuer.

CAVV Cardholder Authentication Verification Value. A Base64-encoded string sent back

with Visa Secure-enrolled cards that specifically identifies the transaction with the
issuing bank and Visa. Standard for collecting and sending AAV data for Visa
Secure transactions. See AAV.

CAVV algorithm A one-digit response passed back when the PARes status is a Y or an A. If your
processor is ATOS, this must be passed in the authorization, if available.

Compra Segura Trademarked name for the Elo card authentication service.

Payer Authentication Using the SCMP API | 251

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

C (Continued)

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

Diners Club A globally issued card type that starts with a 3 or a 5. Cybersource identifies
Diners Club cards with a card type of 005. These cards participate in a card
authentication service (ProtectBuy) provided by 3D 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. Cybersource identifies Discover
cards with a card type of 004. These cards participate in a card authentication
service (ProtectBuy) provided by 3D 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 Alpha character value that indicates the transaction type, such as MOTO or
Indicator INTERNET.

Elo A globally issued card type that starts with a 5. Cybersource identifies Elo cards
with a card type of 054. These cards participate in a card authentication service
(Compra Segura) provided by 3D Secure.

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

HTTP Hypertext Transfer Protocol. An application protocol used for data transfer on the
Internet.

Payer Authentication Using the SCMP API | 252

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

H (Continued)

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

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

issuer The bank that issued a credit card.

J/Secure The 3D Secure program of JCB.

JCB Japan Credit Bureau. A globally issued card type that starts with a 3. Cybersource
identifies JCB cards with a card type of 007. These cards participate in a card
authentication service (J/Secure) provided by 3D 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. Cybersource identifies Maestro cards with the 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 SecureCode card authentication
program.

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

Mastercard Identity Trademarked name for Mastercard’s card authentication service.

Check

Payer Authentication Using the SCMP API | 253

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

M (Continued)

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

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

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

PAN Primary Account Number. Another term for 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 field 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. Pass this data into Cybersource for validation.

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

processor Financial entity that processes payments. Also see acquiring processor.

ProofXML Cybersource field that 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.

Payer Authentication Using the SCMP API | 254

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

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

risk-based Risk-based authentication is provided by the card-issuing bank. The card-issuing

authentication bank gathers a cardholder’s transaction data or leverages what data they have to
silently authenticate the cardholder based on the degree of risk that they perceive
the transaction to have. 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 Cybersource’s legacy name-value pair API that has been superseded by the
Simple Order API.

Simple Order API Cybersource’s current API, which provides three ways to access Cybersource
services: name-value pair (NVP), XML, and SOAP.

Solo A debit card type that was owned by Maestro. It was permanently discontinued
March 31, 2011.

Switch See Maestro.

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

Payer Authentication Using the SCMP API | 255

 Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

UCAF Universal Cardholder Authentication Field. A Base64-encoded string sent back

with Mastercard Mastercard Identity Check-enrolled cards that specifically
identifies the transaction with the issuing bank and Mastercard. Standard for
collecting and sending AAV data for Mastercard Identity Check transactions. See
AAV.

UCAF collection Value of 1 or 2 that indicates whether a Mastercard cardholder has authenticated
indicator themselves or not.

validate Cybersource 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. Cybersource identifies these cards as card type 001 for both credit and debit
cards. These cards participate in a card authentication service (Visa Secure)
provided by 3D Secure.

Visa Secure (VbV) Trademarked name for Visa’s card authentication service.

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

Payer Authentication Using the SCMP API | 256