Payer Authentication SCMP API
Uploaded by
yadbhavishyaPayer Authentication SCMP API
Uploaded by
yadbhavishyaTitle Page
CyberSource Payer Authentication
Using the SCMP API
June 2014
CyberSource Corporation HQ | P.O. Box 8999 | San Francisco, CA 94128-8999 | Phone: 800-530-9095
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 at
http://www.cybersource.com/support.
Copyright
2014 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
CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager,
CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and eCheck.net are trademarks and/or
service marks of CyberSource Corporation. All other brands and product names are trademarks or registered
trademarks of their respective owners.
CONTENTS
Contents
Recent Revisions to This Document
About This Guide
Audience
Purpose
Scope
8
8
Conventions 9
Note and Important Statements 9
Text and Command Conventions 9
Related Documents
Customer Support
Chapter 1
10
10
Introducing Payer Authentication
11
Payer Authentication Overview 11
Overview of Chargeback Protection
13
Prerequisites for Implementing Payer Authentication 13
Required Merchant Information 14
Joint e-Commerce Framework Testing (JEF Tests) 14
Payer Authentication Process 15
Enrollment and Authentication 15
Validate Authentication 17
Chapter 2
Integrating Payer Authentication into Your Business
Process Overview 19
Phase 1: Prerequisites 19
Phase 2: Implementation 20
Phase 3: Formal Testing 21
Phase 4: Code Deployment to Production Environment
Implementing Payer Authentication Services 23
Step 1: Checking Enrollment 24
A. Requesting the Check Enrollment Service
Payer Authentication Using the SCMP API | June 2014
18
22
24
Contents
B. Interpreting the Reply 25
Step 2: Authenticating Enrolled Cards 26
A. Creating the HTTP POST Form 26
B. Creating the HTML Frame for Authentication 26
C. Receiving the PARes Message from the Card-Issuing Bank
Step 3: Validating Authentication 28
A. Requesting the Validation Service 28
B. Interpreting the Reply 30
C. Redirecting Customers to Pass or Fail Message Page 30
Chapter 3
Testing Payer Authentication Services
Testing Process 31
Enrollment Check 31
Authentication Validation
Expected Results
27
31
33
34
Test Cases 36
Verified by Visa 36
MasterCard SecureCode 43
Maestro SecureCode 49
American Express SafeKey 55
JCB J/Secure 60
Appendix A API Fields
66
Formatting Restrictions
66
Data Type Definitions
66
Request-Level Fields
67
Offer-Level Fields
Reply Fields
Appendix B Reply Flags
70
71
79
Payer Authentication Using the SCMP API | June 2014
Contents
Appendix C Request and Reply Examples
80
Check Enrollment 80
Transaction Reply for Visa with Verified by Visa 81
Transaction Reply for MasterCard with SecureCode 82
Transaction Reply for JCB with J/Secure 83
Validate Authentication 84
Transaction Reply for Visa with Verified by Visa 85
Transaction Reply for MasterCard with SecureCode 85
Transaction Reply for JCB with J/Secure 86
ProofXML
87
Appendix D Web Site Modification Reference
Web Site Modification Checklist
3-D Secure Services Logos
88
89
Informational Message Examples
Appendix E
88
90
Payer Authentication Transaction Details in the Business Center
Searching for Payer Authentication Details
Enrolled Card 91
Enrollment Check 91
Authentication Validation 96
Card Not Enrolled 97
Payer Authentication Details 97
Transaction Details 99
Payer Authentication Search
91
100
Storing Payer Authentication Data
Appendix F
Payer Authentication Reports
100
101
Payer Authentication Summary Report 101
Downloading the Report 102
Matching the Report to the Transaction Search Results
Interpreting the Report 104
Comparing Payer Authentication and Payment Reports
Payer Authentication Detail Report
Report 107
<Result> 107
<PayerAuthDetail> 107
<ProofXML> 109
<VEReq> 110
Payer Authentication Using the SCMP API | June 2014
91
103
105
106
Contents
<VERes> 111
<PAReq> 112
<PARes> 113
<AuthInfo> 115
Examples 116
Failed Enrollment Check 116
Successful Authentication 117
Appendix G Rules-Based Payer Authentication
Available Rules
118
API Replies 119
Bypassed Authentication Transactions
Risk-Based Bank Transactions 119
Glossary
Index
118
119
120
127
Payer Authentication Using the SCMP API | June 2014
REVISIONS
Recent Revisions to This
Document
Release
Changes
June 2014
This revision contains only editorial changes and no technical updates.
May 2014
Added more information about the new rules-based Payer Authentication service. See "RulesBased Payer Authentication," page 118.
April 2014
This revision contains only editorial changes and no technical updates.
March 2014
February 2014
January 2014
Added four new API request fields to support Payer Authentication for Brazilian transactions:
pa_mcc, page 68
pa_mobile_phone, page 69
pa_override_payment_method, page 69
pa_product_code, page 69
Added information about the new rules-based Payer Authentication service. See "RulesBased Payer Authentication," page 118.
Changed length of API reply fields of the String data type to 255 characters. See "Reply
Fields," page 71.
Corrected several American Express SafeKey test cases:
Added information Without authentication window to Table 44, "American Express
SafeKey Card Enrolled: Incomplete Authentication," on page 56.
Changed returned values for E-commerce indicator and ECI in Table 48, "American
Express SafeKey Card Not Enrolled," on page 58.
Added ECI return value for check enrollment to Table 49, "American Express SafeKey
Enrollment Check: Time-Out," on page 59.
Updated the card number in Table 50, "American Express SafeKey
Enrollment Check Error," on page 59.
Corrected a JCB/JSecure test case. Removed the ECI value, which is not returned for this
test. See Table 56, "JCB J/Secure Card Enrolled: Failed Authentication," on page 63.
Editorial changes.
Payer Authentication Using the SCMP API | June 2014
ABOUT GUIDE
About This Guide
Audience
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.
Implementing CyberSource Payer Authentication services requires software development
skills. You must write code that uses the API request and reply fields to integrate Payer
Authentication services into your existing order management system.
Purpose
This guide describes tasks you must complete 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 10.
Payer Authentication Using the SCMP API | June 2014
About This Guide
Conventions
Note and Important Statements
A Note contains helpful suggestions or references to material not contained in
this document.
Note
An Important statement contains information essential to successfully
completing a task or learning a concept.
Important
Text and Command Conventions
Convention
Usage
bold
Field and service names; 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.
monospace
Payer Authentication Using the SCMP API | June 2014
Placeholder variables for which you supply particular values.
XML elements.
Code examples and samples.
Text that you enter in an API environment; for example:
Set the davService_run field to true.
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 Web/Mobile Configuration Guide describes how to create Secure
Acceptance Web/Mobile profiles, which enable you to integrate your order
management system with the Secure Acceptance Web/Mobile checkout. (PDF |
HTML)
Secure Acceptance Silent Order POST Development Guide describes how to create
Secure Acceptance Silent Order POST profiles, which enable you to integrate your
order management system with a web site to process transactions. (PDF | HTML)
Reporting Developer Guide describes how to view and configure Business Center
reports. (PDF | HTML)
Refer to the Support Center for complete CyberSource technical documentation:
http://www.cybersource.com/support_center/support_documentation
Customer Support
For support information about any CyberSource service, visit the Support Center at:
http://www.cybersource.com/support
Payer Authentication Using the SCMP API | June 2014
10
CHAPTER
Introducing Payer
Authentication
CyberSource Payer Authentication services enable you to add support to your web store
for card authentication services, including Visa Verified by VisaSM, MasterCard and
Maestro SecureCode (UK Domestic and international), American Express SafeKeySM,
and JCB J/Secure.
These card authentication services deter unauthorized card use and protect you from
fraudulent chargeback activity referred to as liability shift. However, Payer Authentication
is not a fraud management service, such as Decision Manager 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).
Payer Authentication Overview
Payer Authentication provides the following services:
Check Enrollment: Determines whether the customer is enrolled in one of the card
authentication programs.
Validate Authentication: Ensures that the authentication that you receive from the
issuing bank is valid.
Figure 1 shows the Payer Authentication process after a customer places an order on your
web site. CyberSource provides the Check Enrollment, Card Authorization, and the
Validate Authentication services.
Payer Authentication Using the SCMP API | June 2014
11
Chapter 1
Figure 1
Introducing Payer Authentication
Payer Authentication Process Overview
Your customer places
an order on your Web
site.
Check Enrollment
service
Is the card
enrolled?
Yes
The customer enters
the authentication
password.
Is the password
authenticated?
No
Yes
Card Authorization
service
Validate Authentication
service
No
You must refuse the
card and request other
form of payment.
The Check Enrollment service determines whether the customer is enrolled in one of the
card authentication services:
No
If the card is not enrolled, you can process the authorization immediately.
Yes
If the card is enrolled, the customers browser displays a window where the customer
can enter the password associated with the card. This is how the customer
authenticates their card with the issuing bank.
If the password matches the password stored by the bank, you need to verify that
the information is valid with the Validate Authentication service. If the identity of
the sender is verified, you can process the payment with the Card Authorization
service.
If the password does not match the password stored by the bank, the customer
may be fraudulent. You must refuse the card and can request another form of
payment.
Payer Authentication Using the SCMP API | June 2014
12
Chapter 1
Introducing Payer Authentication
Overview of Chargeback Protection
Visa, MasterCard, Maestro, American Express, and JCB may offer chargeback protection
if merchants participate in 3-D Secure card authentication programs, such as Verified by
Visa or MasterCard SecureCode.
Chargebacks occur after a transaction is processed, and how they are handled varies
according to the region that issued the card. Card association 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.
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 specific data to your API requests to CyberSource.
Validate the necessary data.
Provide the additional data to the authorization request.
Modify your web site to help the customer understand the process.
Payer Authentication Using the SCMP API | June 2014
13
Chapter 1
Introducing Payer Authentication
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 companys web site, for example:
http://www.example.com
Bank Information
Visa, MasterCard, Maestro,
American Express, and JCB
Information
Acquirer merchant ID
Two-character ISO code for your country.
Name of your bank acquirer.
Complete name and address of your bank contact,
including email address.
Information provided by your bank acquirer about each card
association for which you are configured:
6-digit BIN numbers.
Acquirer merchant ID: merchant ID assigned by your
acquirer.
All currencies that you are set up to process.
Joint e-Commerce Framework Testing (JEF
Tests)
This section applies to all card types: Visa, MasterCard, Maestro, American Express, and
JCB.
This type of testing was formerly known as PIT testing. JEF is a set of payment integration
tests that simulates realistic scenarios that would have an impact on your business in a
production environment. Each test is designed to ensure that your implementation of
Payer Authentication services processes the data correctly. CyberSource provides you
with a test plan that describes expected results. After your implementation is ready to
deploy to your production environment, you must notify your CyberSource contact to
schedule the formal testing.
For more information, see "Phase 3: Formal Testing," page 21.
Payer Authentication Using the SCMP API | June 2014
14
Chapter 1
Introducing Payer Authentication
Payer Authentication Process
This section describes the Payer Authentication process. Figure 2 describes the
enrollment and authentication process. Figure 3 describes the steps for validating card
authentication.
Enrollment and Authentication
The goal is to verify that the customer is enrolled in a card authentication program and to
create the authentication request message (PAReq) for enrolled cards. The enrollment
check is shown in Steps 2 to 5; the authentication is shown in Steps 6 to 8.
Figure 2
Enrollment and Authentication Process
Your Customer
7
1
Customer's
Password
Your Order Management
System
2
Enrollment
PARes
PAReq
ACS URL
CyberSource
Authentication
PAReq
Check Enrollment
Service
5
Yes No
Card Association's
Directory Server
ACS URL
Customer's card-issuing
Bank
When the customer places an order on your web site, your order management system
extracts the purchase information from the POST of the final page of the order.
To verify that the customer is enrolled in one of the card authentication programs, you
request the Enrollment Check service.
CyberSource contacts the appropriate Directory Server for the card type.
Payer Authentication Using the SCMP API | June 2014
15
Chapter 1
Introducing Payer Authentication
The Directory Server verifies with the bank that issued the card that the card is
enrolled. If the card is enrolled, the directory server receives the URL of the Access
Control Server (ACS) where the customer can be authenticated.
The Directory Server replies to CyberSource and to your Order Management System
as follows:
If the customer is enrolled, you receive this information:
-
A payer authentication request (PAReq) message, which contains a unique
transaction ID (XID).
The ACS URL of the issuing bank where you need to send the PAReq
message.
If the card is not enrolled, authentication and validation are omitted and the
process proceeds with card authorization.
If the card is enrolled, you send the PAReq message to the ACS URL of the cardissuing bank to request authentication.
The customers web browser displays the card-issuing banks authentication dialog
box where the customer enters their password for the card.
The card-issuing bank replies to your order management system with a PARes
message that contains the results of the authentication.
You verify that the signature in the PARes is the same as that in the PAReq.
This final check verifies that the enrollment and validation checks are for the same
transaction. The rest of the process is described in the following "Validate
Authentication" section.
Payer Authentication Using the SCMP API | June 2014
16
Chapter 1
Introducing Payer Authentication
Validate Authentication
The Validate Authentication service verifies and interprets the payment authentication
response message returned by the card-issuing bank.
If the authentication fails, Visa and JCB require that you do not accept the card.
Instead, you must ask the customer to use another payment method.
Important
The steps in the following figure resume the process started in the "Enrollment and
Authentication Process," page 15.
Figure 3
Validate Authentication Process
Customer
Your Order Management
System
PARes
12
Validation
11
Yes No
10
PARes
CyberSource
Validation Service
10 You extract the PARes message from the form and request the CyberSource Validate
Authentication service, which uses the message's digital signature to verify the
sender's identity.
11 You receive a reply with the authentication result.
12 You verify that the XID in the PARes is the same as that in the PAReq.
This final check verifies that the enrollment and validation checks are for the same
transaction.
Payer Authentication Using the SCMP API | June 2014
17
CHAPTER
Integrating Payer
Authentication into Your
Business
The integration process takes approximately 10 weeks from the initial stages of contacting
your acquirer until you can use Payer Authentication in your production environment.
Important
Add 1 week for each Joint e-Commerce Framework (JEF) testing attempt. For
example, if your Payer Authentication implementation passes the JEF test on
the first attempt, the Payer Authentication process should take approximately
10 weeks to complete. However, if your implementation fails during the first test
attempt, expect to add an additional week to the schedule, and expect
integration to take approximately 11 weeks. For more information about JEF
testing, see "Joint e-Commerce Framework Testing (JEF Tests)," page 14.
Payer Authentication Using the SCMP API | June 2014
18
Chapter 2
Integrating Payer Authentication into Your Business
Process Overview
The following tables summarize the process of integrating Payer Authentication services
into your existing business processes.
Phase 1: Prerequisites
Before implementing Payer Authentication services, your business team must contact
your acquirer and CyberSource to begin setting up the service. Your software
development team should become familiar with the API fields and technical details of this
service.
Table 2
Prerequisite Tasks (approximate time to complete is 2 weeks)
Project Manager Tasks
Developer Tasks
1 Contact your acquirer about using 3-D Secure
Services (Verified by Visa, MasterCard SecureCode,
American Express SafeKey, and JCB J/Secure).
Discuss liability shift to understand the protections
offered for your region.
1 Review Credit Card Services Using the SCMP API.
2 Go to www.cybersource.com/register to create a
CyberSource merchant ID that you will use for testing
your Payer Authentication implementation.
2 Review CyberSource Payer Authentication Using the
SCMP API.
3 Notify your CyberSource account representative that
you want to implement Payer Authentication (3-D
Secure). Give them the CyberSource merchant ID
you created in step 2 that you will use for testing. For
more information, see "Required Merchant
Information," page 14.
Note Set up for testing can take up to 3 business days.
Payer Authentication Using the SCMP API | June 2014
19
Chapter 2
Integrating Payer Authentication into Your Business
Phase 2: Implementation
Implementation includes modifying your web site front end and developing the software
code to integrate with Payer Authentication services. For a detailed discussion of the
steps in this phase, see this chapters sections starting with "Implementing Payer
Authentication Services," page 23.
Table 3
Implementation Tasks (approximate time to complete is 4 weeks)
Project Manager Tasks
Developer Tasks
1 Develop code to modify your web site checkout page
appearance. For information about requirements for
modifying your web site checkout page, see
Appendix D, "Web Site Modification Reference," on
page 88.
2 Develop code to send a request (VEReq) to verify
card enrollments. See "A. Requesting the Check
Enrollment Service," page 24.
3 If required, enable API logging for debugging
purposes.
4 Display the Access Control Server URL (ACS URL)
correctly, and capture the return data for the PAReq.
See "B. Interpreting the Reply," page 25.
5 Add code to the HTTP POST request to send the
required data, including the PAReq, to the ACS URL.
6 Develop code to send a validate request to
CyberSource and include the correct data sent to the
TermURL from the ACS URL. See "A. Requesting the
Validation Service," page 28.
7 Where applicable, develop code to pass appropriate
data into the authorization requests. See "B.
Interpreting the Reply," page 30.
8 Use the test cases in Chapter 3, "Testing Payer
Authentication Services," on page 31 to test your
preliminary code and make the appropriate changes.
Run tests to the following test environment:
https://icstest.ic3.com
9 If not activated previously, enable API logging for the
formal testing phase.
1 After code complete has been confirmed, contact
your CyberSource account representative to arrange
a time to begin formal testing with the CyberSource
technical team.
Payer Authentication Using the SCMP API | June 2014
10Confirm with your business contact or project
manager that the code is complete (written and
tested).
20
Chapter 2
Integrating Payer Authentication into Your Business
Phase 3: Formal Testing
To ensure that your implementation of Payer Authentication services is coded correctly,
CyberSource recommends that you complete Joint e-Commerce Framework Testing for
all card types: Visa, MasterCard, Maestro, American Express, and JCB. Ensure that you
run only accreditation tests during formal testing.
Table 4
Formal Testing Tasks (approximate time to complete is 1 week)
CyberSource Technical Team
Tasks
Project Manager Tasks
1 Provide to the merchants
developer team a test document
that describes the accreditation
tests and the expected test
results.
Developer Tasks
1 During the scheduled test time,
run the accreditation tests in the
exact sequence as described in
the testing document provided by
CyberSource.
2 Record the test results as
described in the testing
document, and send the
completed tests to the
CyberSource technical team.
Important Only send your test
results when they match the
required results as described in the
testing document. Send API logs for
each test run.
2 Mark and review the test results,
which takes up to 3 working days.
If your testing does not meet the
criteria for successful Payer
Authentication processing,
CyberSource provides a list of
improvements.
3 Repeat Steps 1 and 2 until
successful completion of JEF
testing.
Note Each additional formal test run attempt requires approximately 1 additional week.
Payer Authentication Using the SCMP API | June 2014
21
Chapter 2
Integrating Payer Authentication into Your Business
Phase 4: Code Deployment to Production
Environment
Table 5
Code Deployment Tasks (approximate time to complete is 3 weeks)
CyberSource Tasks
Project Manager Tasks
Developer Tasks
1 Provide banking information to
CyberSource so your account
can be created on the production
Directory Servers.
Note Account creation on the
production Directory Servers takes 2
weeks. Provide your banking
information as soon as possible to
avoid delays.
Barclays Barclays performs this
step on your behalf. Notify them in
advance to avoid delays. When they
provide the following information,
send it to your CyberSource account
representative:
1 CyberSource primary support
team asks your acquiring bank to
upload data to the Directory
Servers.
Visa Login ID
Visa password
MasterCard Merchant ID
2 Request that CyberSource
enable your production account
for Payer Authentication services.
2 After the CyberSource team
receives confirmation that the
data has been uploaded to the
Directory Servers, the team loads
the data on to the Merchant Plugin (MPI) for processing.
1 Verify logging capabilities in
production. Some acquiring
banks require that you maintain a
log of the response fields (for
example ProofXML, PAReq,
PARes, CAVV, and ECI).
Typically this data must be
presented in decompressed,
decoded form to dispute
chargebacks.
3 When the third parties notify
CyberSource of successful
activation, Payer Authentication
services are turned on for your
account.
Note This step takes
approximately 3 days.
Payer Authentication Using the SCMP API | June 2014
22
Chapter 2
Integrating Payer Authentication into Your Business
Implementing Payer
Authentication Services
Do not use Payer Authentication services for subscription payments because
you cannot receive chargeback protection for these transactions.
Warning
To reduce your development time, CyberSource recommends that you request both payer
authentication and the card authorization services at the same time. When you do so,
CyberSource automatically sends the correct information to your payment processor. For
example, CyberSource converts the values of these fields, which are in base64, to the
proper format required by your payment processor:
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 need to include the value of these fields, not
the field name, in the subsequent card authorization service request.
In most cases, you request card authorization only once for each purchase. However, you
need to send multiple authorization requests if the original authorization expires before it is
captured, which can occur when order fulfillment is split or delayed.
Single authorizations: For most purchases, you request authorization only once with
either one or both Payer Authentication services:
With Check Enrollment: the authorization is processed only if the customer is not
enrolled in a card authentication program. If the customer is enrolled, you must
validate the authentication before the card can be authorized.
With Validate Authentication: the authorization is processed only if the customers
authentication is valid.
Multiple Authorizations: In these cases, you need to 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.
Payer Authentication Using the SCMP API | June 2014
23
Chapter 2
Integrating Payer Authentication into Your Business
Step 1: Checking Enrollment
When the customer places an order on your web site, your order management system
processes the purchase information from the POST of the final page of the order. The goal
is to verify that the card is enrolled and to authenticate the results if it is enrolled. To do so,
you request the Enrollment Check service (VEReq), and then proceed as follows:
If the card is enrolled, the VERes reply field indicates enrollment. The reply also
contains the URL of the Access Control Server and the PAReq.
If the card is not enrolled, proceed directly to card authorization.
A. Requesting the Check Enrollment Service
Important
Before requesting ics_pa_enroll service, check the first digit of the card
number to verify the card type. The first digit for Visa is 4, the first digit for
MasterCard is 5, Maestro can start with 5 or 6, and the first digit for American
Express and JCB is 3. Specifying the card type is required for all Payer
Authentication services.
Use the Check Enrollment service to verify that the card is enrolled in a card
authentication program. For a list of the fields used when requesting the service, see
"Request-Level Fields," page 67. 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 (reply flag SOK is returned). In this case,
the field values that are required to prove you attempted to check enrollment are
passed automatically to the authorization service.
Separate requests: You must manually include the enrollment check result values
(Enrollment Check Reply Fields) in the authorization service request (Card
Authorization Request Fields). The following table lists these fields:
Identifiers
Enrollment Check Reply Fields
Card Authorization
Request Fields
E-commerce indicator
pa_enroll_e_commerce_indicator
e_commerce_indicator
Collection indicator
(MasterCard only)
pa_enroll_ucaf_collection_indicator
ucaf_collection_indicator
Result of the enrollment
check for Asia, Middle
East, and Africa
Gateway
pa_enroll_veres_enrolled
veres_enrolled
Payer Authentication Using the SCMP API | June 2014
24
Chapter 2
Integrating Payer Authentication into Your Business
B. Interpreting the Reply
The replies are similar for all card types. See Appendix C, "Request and Reply Examples,"
on page 80 for examples of enrollment replies.
Enrolled Cards
You receive reply flag DAUTHENTICATE if the customers card is enrolled in a payer
authentication program.
If you receive this reply, you can proceed to validate authentication.
Cards Not Enrolled
You receive reply flag SOK in the following cases:
If the account number is not enrolled in a payer authentication program. The other
services in your request are processed normally.
If payer authentication is not supported by the card type, such as Diners Club and
Discover.
If you receive this reply, you can proceed to card authorization.
Payer Authentication Using the SCMP API | June 2014
25
Chapter 2
Integrating Payer Authentication into Your Business
Step 2: Authenticating Enrolled Cards
When you have verified that a customers card is enrolled in a card authentication
program, you must redirect the customer to the URL of the card-issuing banks Access
Control Server (ACS URL) by using an HTTP POST request web form that contains the
PAReq data, the Termination URL (TermURL), and merchant data (MD).
A. Creating the HTTP POST Form
Example
POST Form
if card is enrolled == TRUE Then
variable acsURL = <acsURL reply field>
variable paReq = <paReq reply field>
<body onload=document.PAEnrollForm.submit ();>
<form id=PAEnrollForm name=PAEnrollForm action=acsURL value
method=post target=paInlineFrame>
<input type=hidden name=PaReq value=paReq value
<input type=hidden name=TermUrl value=http://
myPAValidationPage.ext /
<input type=hidden name=MD value=<xid value> />
</form>
else
/* If the card is not enrolled, do not submit the form. Instead, skip the
authentication and validation processes. Proceed directly to card
authorization. */
The page typically includes JavaScript that automatically posts the form. This code
provides the following:
A page that receives the reply fields for the enrollment check service.
A form that contains the required data for the card-issuing bank.
B. Creating the HTML Frame for Authentication
When your customers are redirected to the ACS URL, their browsers display the frame
that contains the card-issuing banks password authentication dialog box or the option to
sign up for the program (activation form).
On the page that contains the in-line frame for the ACS URL, add the following:
HTML frame large enough to accommodate the card-issuers authentication form or
the activation form, and text that describes the process to customers.
Outside the HTML frame, you must provide a brief message that guides customers
through the process. For example, Please wait while we process your request. Do not
Payer Authentication Using the SCMP API | June 2014
26
Chapter 2
Integrating Payer Authentication into Your Business
click the Back button or refresh the page. Otherwise, this transaction may be
interrupted.
Card associations provide guidance on their web sites about using their logos and
accommodating their authentication/activation forms. For information about downloading
this information, see Appendix D, "3-D Secure Services Logos," on page 89. When testing
your integration, verify that the frames you use are large enough.
C. Receiving the PARes Message from the Card-Issuing
Bank
The card-issuing bank sends a PARes message to your TermURL in response to the
PAReq data that you sent with the web form. The PARes message is sent by using an
HTTP POST request and contains the result of the authentication you requested:
variable paRes = <signedPARes reply field>
The signed PARes field contains a base64-encoded string that contains the following
information:
PaRes
Digitally signed payer authentication response message that contains the
authentication result.
The field name has a lowercase a (PaRes), but the message name has
an uppercase A (PARes).
Important
MD
Merchant data, which is included only if you provided it in the outgoing page when you
sent the enrollment authentication request (PAReq).
Note
For card types that accept attempts processing in addition to card enrollment in
a 3-D Secure program, you might receive a response message that is identical
to a successful authentication message except that the status in the
authentication result field indicates a successful attempt instead of a
successful authentication.
Payer Authentication Using the SCMP API | June 2014
27
Chapter 2
Integrating Payer Authentication into Your Business
Step 3: Validating Authentication
For enrolled cards, the next step is to request the validation service to verify the
authentication message (PARes) returned by the card-issuing bank.
A. Requesting the Validation Service
When you make the validation request, you must:
Extract the PARes message from the form received from the card-issuing bank.
Remove all white spaces created by tabs, spaces, or line breaks from the PaRes field.
Do not modify any other part of the PaRes field. If you do not remove these white
space characters, the validation and subsequent authorization service requests fail.
Send the PaRes to CyberSource in the signed PaRes field of the validation service.
The reply that you receive contains the validation result.
You can use the validation and card authorization services in the same request or in
separate requests:
Same request: CyberSource automatically attempts to authorize your customers card
if validation succeeds. The values of the required fields are added automatically to the
authorization service. If you use this method, do not pass into your request any fields
that CyberSource derives from the PARes because that data could be overwritten.
Note
If the ignore_validate_result request field is set to yes and you request
the validation and card authorization services together, the authorization
service attempts to authorize the customers card even if validation fails.
Therefore, CyberSource recommends that you use this request field only
when using other services and fraud tools.
Payer Authentication Using the SCMP API | June 2014
28
Chapter 2
Integrating Payer Authentication into Your Business
Separate requests: You must manually include the validation result values (Payer
Authentication Reply Fields) in the authorization service request (Card Authorization
Request Fields), which are listed in the following table:
Identifiers
Payer Authentication Reply
Fields
Card Authorization
Request Fields
Result of the validation
check
pa_validate_pares_status
pares_status
XID
pa_validate_xid
xid
E-commerce indicator
pa_validate_e_commerce_
indicator
e_commerce_indicator
ECI raw
pa_validate_eci_raw
eci_raw
CAVV (Visa and
American Express only)
pa_validate_cavv
cavv
CAVV algorithm (ATOS
only)
pa_validate_cavv_algorithm
cavv_algorithm
AAV (MasterCard only.
Known as UCAF)
pa_validate_ucaf_
authentication_data
ucaf_authentication_data
Collection indicator
(MasterCard only)
pa_validate_ucaf_collection_
indicator
ucaf_collection_indicator
(For the Asia, Middle
East, and African
Gateway and ATOS only)
Important
To increase the likelihood that you will receive liability shift protection, you must
ensure that you pass all the pertinent data for the card type and processor into
your request. Failure to do so may invalidate your liability shift for that
transaction. Include the electronic commerce indicator (ECI), the transaction ID
(XID), and the following card-specific information in your authorization request:
For Visa, American Express, and JCB, 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 | June 2014
29
Chapter 2
Integrating Payer Authentication into Your Business
B. Interpreting the Reply
Important
If the authentication fails, Visa, American Express, and JCB 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 replies
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. If you want to process the other services or fraud tools
despite the failure, set the request field ignore_validate_result to yes.
Error:
If you receive an error from the card association, 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 replies are identical.
C. Redirecting Customers to Pass or Fail Message Page
After authentication is completed, 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 | June 2014
30
CHAPTER
Testing Payer
Authentication Services
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 reply.
Testing Process
Use the card number specified in the test with the cards expiration date set as follows: the
month of December and the current year plus two. For example, for 2012, use 2014. 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. Figure 4 shows an authentication window for Verified by Visa. The
window for MasterCard is similar.
To see the authentication window, you must enable your browser to display
popup windows.
Note
The test password is always 1234.
Payer Authentication Using the SCMP API | June 2014
31
Chapter 3
Figure 4
Testing Payer Authentication Services
Verified by Visa Authentication Window
Your merchant ID.
Last four digits of the card number.
Password to enter in the below text box.
Default user name for all tests.
This Exit link enables the customer to prevent the authentication process.
Depending on the users 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 (Figure 5),
authentication does not occur.
Figure 5
Verified by Visa Verification Window
Table 6 lists the reply fields used in the test cases.
Payer Authentication Using the SCMP API | June 2014
32
Chapter 3
Table 6
Testing Payer Authentication Services
Reply Fields Used in the Enrollment Check Test Cases
Names 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
Reply flag
pa_enroll_rflag
VERes enrolled
pa_enroll_veres_enrolled
XID
pa_enroll_xid
Authentication Validation
Table 7 lists only the reply fields used in the test cases.
Table 7
Reply Fields Used in the Authentication Validation Test Cases
Names 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 (Visa only)
pa_validate_cavv
Collection indicator
pa_validate_ucaf_collection_indicator
ECI
pa_validate_eci
PARes status
pa_validate_pares_status
Reply flag
pa_validate_rflag
XID
pa_validate_xid
Payer Authentication Using the SCMP API | June 2014
33
Chapter 3
Testing Payer Authentication Services
Expected Results
These flowcharts provide an overview of 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 6
Authentication Path for Visa, American Express, and JCB
Payer Authentication Using the SCMP API | June 2014
34
Chapter 3
Figure 7
Testing Payer Authentication Services
Authentication Path for MasterCard and Maestro
Payer Authentication Using the SCMP API | June 2014
35
Chapter 3
Testing Payer Authentication Services
Test Cases
Verified by Visa
You can use Payer Authentication services with 16- and 19-digit Visa cards if these are
supported by your processor.
Table 8
Possible Values for Verified by Visa Reply Fields
Result and Interpretation
Success
Failure
(Customer
not
responsible)
Validate Authentication Reply
Authentication ECI Commerce
Result
Indicator
Reply Flag
Successful authentication.
05
vbv
SOK
Recorded attempt to
authenticate.
06
vbv_
attempted
SOK
System error that prevents the
completion of authentication:
you can proceed with
authorization, but there is no
liability shift.
SOK
Issuer unable to perform
authentication.
07
internet
SOK
07
internet
No response from the Directory
Servers or Issuer because of a
problem.
Failure
(Customer
responsible)
vbv_failure
(processors:
AIBMS, Barclays,
Streamline, or
FDC Germany)
Invalid PARes.
-1
DAUTHENTICATION
FAILED
Authentication failed or
cardholder did not complete
authentication.
DAUTHENTICATION
FAILED
If the authentication fails, Visa
requires that you do not accept
the card. You must ask the
customer to use another
payment method.
a.The eci value can vary depending on the reason for the failure.
b.A dash () indicates that the field is blank or absent.
Payer Authentication Using the SCMP API | June 2014
36
Chapter 3
Table 9
Testing Payer Authentication Services
Verified by Visa Card Enrolled: Successful Authentication
Card Number 4000000000000002
With authentication window
4000000000000000022
4000000000000119
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
vbv
VERes enrolled
ECI
05
XID
XID value
PARes status
XID
XID value
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.
Table 10
Verified by Visa Card Enrolled: Successful Authentication But Invalid
PARes
Card Number 4000000000000010
With authentication window
4000000000000000071
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: PARes signature digest value
mismatch. PARes message has been modified.
URL value
Authentication result
-1
PAReq
PAReq value
XID
XID value
proofXML
proofXML value
VERes enrolled
XID
XID value
Do not proceed with authorization. Instead, ask the customer for another form of payment.
Payer Authentication Using the SCMP API | June 2014
37
Chapter 3
Table 11
Testing Payer Authentication Services
Verified by Visa Card Enrolled: Attempts Processing
With authentication window
4000000000000000063
4000000000000127
Card enrollment option during purchase process
Card Number 4000000000000101
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
vbv_attempted
VERes enrolled
ECI
06
XID
XID value
PARes status
XID
XID value
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 customers 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 | June 2014
38
Chapter 3
Table 12
Testing Payer Authentication Services
Verified by Visa Card Enrolled: Incomplete Authentication
Card Number 4000000000000036
4000000000000000055
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
Issuer unable to perform authentication.
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
ECI
07
VERes enrolled
PARes status
XID
XID value
XID
XID value
Ask the customer for another form of payment, or submit the transaction. No liability shift.
Table 13
Verified by Visa Card Enrolled: Unsuccessful Authentication
Card Number 4000000000000028
With authentication window
4000000000000000048
Results
Summary
Check Enrollment
Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
User failed authentication.
Payer cannot be authenticated.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
XID
XID value
VERes enrolled
XID
XID value
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 | June 2014
39
Chapter 3
Table 14
Testing Payer Authentication Services
Verified by Visa Card Enrolled: Unsuccessful Authentication (Customer
Exited)
Card Number 4000008531947799
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
Customer prevents authentication.
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
XID
XID value
VERes enrolled
XID
XID value
You are not permitted to submit this transaction for authorization. Instead ask the customer for
another form of payment.
Table 15
Verified by Visa Card Enrolled: Unavailable Authentication
Card Number 4000000000000069
4000000000000000014
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
Submit your authorization request. No liability shift.
Payer Authentication Using the SCMP API | June 2014
40
Chapter 3
Table 16
Testing Payer Authentication Services
Verified by Visa Card Enrolled: Authentication Error
Card Number 4000000000000093
4000000000000000006
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: Error Processing PARes.
URL value
E-commerce indicator
internet
PAReq
PAReq value
ECI
07
proofXML
proofXML value
VERes enrolled
XID
XID value
Ask the customer for another form of payment. No liability shift.
Table 17
Verified by Visa Card Not Enrolled
Card Number 4000000000000051
4000000000000000030
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
vbv_attempted
ECI
06
proofXML
proofXML value
VERes enrolled
Submit your authorization request. Liability shift.
Table 18
Verified by Visa Enrollment Check: Time-Out
Card Number 4000000000000044
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
proofXML
Action
internet
proofXML value
After 10 12 seconds, proceed with the authorization request. No liability shift.
Payer Authentication Using the SCMP API | June 2014
41
Chapter 3
Table 19
Verified by Visa Enrollment Check Error
Card Number 4000000000000085
4000000000000077
Results
Testing Payer Authentication Services
Error response
Incorrect Configuration: Unable to Authenticate
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
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 | June 2014
42
Chapter 3
Testing Payer Authentication Services
MasterCard SecureCode
Table 20
Possible Values for MasterCard and Maestro SecureCode Reply Fields
pa_validate_
Result and Interpretation
Success
Failure
(Customer
not
responsible)
Failure
(Customer
responsible)
authentication
_result
ucaf_
collection_
indicator
e_commerce_
indicator
rflag
Successful authentication.
spa
100
Authentication not completed.
spa
100
System error (Issuer unable to
perform authentication): you
cannot authorize this card; no
liability shift.
internet
100
Invalid PARes.
-1
Authentication failed or
cardholder did not complete
authentication.
Table 21
5200000000000114
476
With authentication window
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The card is enrolled in Payer Authentication.
Please authenticate before proceeding with
authorization.
Details ACS URL
Action
MasterCard SecureCode Card Enrolled: Successful Authentication
Card Number 5200000000000007
Results
476
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
AAV
AAV value
proofXML
proofXML value
Collection indicator
VERes enrolled
E-commerce indicator
spa
XID
XID value
PARes status
XID
XID value
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 | June 2014
43
Chapter 3
Table 22
MasterCard SecureCode Card Enrolled: Successful Authentication But
Invalid PARes
Card Number 5200000000000015
Results
With authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
Payer Authentication problem: PARes
signature digest value mismatch. PARes
message has been modified.
URL
Authentication result
-1
PAReq
PAReq value
XID
XID value
proofXML
proofXML value
VERes enrolled
XID
XID value
Do not process the authorization request. Instead ask the customer for another form of payment.
Payer Authentication Using the SCMP API | June 2014
44
Chapter 3
Table 23
Testing Payer Authentication Services
MasterCard SecureCode Card Enrolled: Attempts Processing
Card Number 5200000000000122
Card enrollment option during purchase process
5200000000000106
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
AAV
AAV value
proofXML
proofXML value
E-commerce indicator
spa
VERes enrolled
PARes status
XID
XID value
XID
XID value
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
customers 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 reply, ensure that the XID from the enrollment check matches that from the validation.
3 Add the required payer authentication values to your authorization request.
Payer Authentication Using the SCMP API | June 2014
45
Chapter 3
Table 24
MasterCard SecureCode Card Enrolled: Incomplete Authentication
Card Number 5200000000000031
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
Issuer unable to perform authentication.
URL value
Authentication result
PAReq
PAReq value
Collection indicator
01
proofXML
proofXML value
E-commerce indicator
internet
VERes enrolled
PARes status
XID
XID value
XID
XID value
Ask the customer for another form of payment, or submit the transaction. No liability shift.
Table 25
MasterCard SecureCode Card Enrolled: Unsuccessful Authentication
Card Number 5200000000000023
Results
With authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
User failed authentication
Payer could not be authenticated.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
VERes enrolled
XID
XID value
XID
XID value
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 | June 2014
46
Chapter 3
Table 26
Testing Payer Authentication Services
MasterCard SecureCode Card Enrolled: Unsuccessful Authentication
(Customer Exited)
Card Number 5641821000010028
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
Customer prevents authentication.
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
XID
XID value
VERes enrolled
XID
XID value
You are not permitted to submit this transaction for authorization. Instead ask the customer for
another form of payment.
Table 27
MasterCard SecureCode Card Enrolled: Unavailable Authentication
Card Number 5200000000000064
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
VERes enrolled
Submit the transaction. No liability shift.
Payer Authentication Using the SCMP API | June 2014
47
Chapter 3
Table 28
MasterCard SecureCode Card Enrolled: Authentication Error
Card Number 5200000000000098
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: Error Processing PARes.
URL value
Collection indicator
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
VERes enrolled
XID
XID value
Ask the customer for another form of payment. No liability shift.
Table 29
MasterCard SecureCode Card Not Enrolled
Card Number 5200000000000056
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
E-commerce indicator
spa
proofXML
proofXML value
VERes enrolled
Submit the transaction.
Action
Table 30
MasterCard SecureCode Enrollment Check Time-Out
Card Number 5200000000000049
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
After 10 12 seconds, proceed with the authorization message. No liability shift.
Payer Authentication Using the SCMP API | June 2014
48
Chapter 3
Table 31
Testing Payer Authentication Services
MasterCard SecureCode Enrollment Check Error
Card Number 5200000000000080
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
VERes enrolled
Proceed with the authorization request, and contact your support representative to resolve the
issue. No liability shift. If you requested payer authentication and authorization together, the
authorization is processed automatically.
Maestro SecureCode
Table 32
Maestro SecureCode Card Enrolled: Successful Authentication
Card Number 6759411100000008
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
AAV
AAV value
proofXML
proofXML value
Collection indicator
VERes enrolled
E-commerce indicator
spa
XID
XID value
PARes status
XID
XID value
1 Add the signed PARes to the validation request.
2 In the reply, ensure that the XID from the enrollment check matches that from the validation.
3 Add the required payer authentication values to your authorization request.
Payer Authentication Using the SCMP API | June 2014
49
Chapter 3
Table 33
Maestro SecureCode Card Enrolled:
Successful Authentication But Invalid PARes
Card Number 6331101234567892
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
Payer Authentication problem: PARes
signature digest value mismatch. PARes
message has been modified.
URL
Authentication result
-1
PAReq
PAReq value
XID
XID value
proofXML
proofXML value
VERes enrolled
XID
XID value
Do not process the authorization request. Instead ask the customer for another form of payment.
Payer Authentication Using the SCMP API | June 2014
50
Chapter 3
Table 34
Maestro SecureCode Card Enrolled: Attempts Processing
Card Number 560000000000000193
Results
Card enrollment option during purchase process
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
AAV
AAV value
proofXML
proofXML value
E-commerce indicator
spa
VERes enrolled
PARes status
XID
XID value
XID
XID value
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
customers 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 | June 2014
51
Chapter 3
Table 35
Maestro SecureCode Card Enrolled: Incomplete Authentication
Card Number 6331101250353227
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
Issuer unable to perform authentication.
URL value
Authentication result
PAReq
PAReq value
Collection indicator
proofXML
proofXML value
E-commerce indicator
internet
VERes enrolled
PARes status
XID
XID value
XID
XID value
Ask the customer for another form of payment, or submit the transaction. No liability shift.
Table 36
Maestro SecureCode Card Enrolled: Unsuccessful Authentication
Card Number 6331100610194313
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
User failed authentication
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
XID
XID value
VERes enrolled
XID
XID value
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 | June 2014
52
Chapter 3
Table 37
Testing Payer Authentication Services
Maestro SecureCode Card Enrolled: Unavailable Authentication
(Time-out)
Card Number 6331100266977839
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
Submit the transaction. No liability shift.
Table 38
Maestro SecureCode Card Enrolled: Authentication Error
Card Number 560000511607577094
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: Error Processing PARes.
URL value
Collection indicator
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
VERes enrolled
XID
XID value
Do not request authorization. Instead ask the customer for another form of payment. No liability
shift.
Payer Authentication Using the SCMP API | June 2014
53
Chapter 3
Table 39
Testing Payer Authentication Services
Maestro SecureCode Card Not Enrolled
Card Number 560000227571480302
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
VERes enrolled
Submit the transaction.
Table 40
Maestro SecureCode Enrollment Check Error
Card Number 560000841211092515
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details Collection indicator
Action
E-commerce indicator
spa
proofXML
proofXML value
VERes enrolled
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 | June 2014
54
Chapter 3
Testing Payer Authentication Services
American Express SafeKey
Table 41
American Express SafeKey Card Enrolled: Successful Authentication
Card Number 340000000003961
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
aesk
VERes enrolled
ECI
05
XID
XID value
PARes status
XID
XID value
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.
Table 42
American Express SafeKey Card Enrolled: Successful Authentication
But Invalid PARes
Card Number 340000000006022
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: PARes signature digest value
mismatch. PARes message has been modified.
URL value
Authentication result
-1
PAReq
PAReq value
XID
XID value
proofXML
proofXML value
VERes enrolled
XID
XID value
Do not proceed with authorization. Instead, ask the customer for another form of payment.
Payer Authentication Using the SCMP API | June 2014
55
Chapter 3
Table 43
American Express SafeKey Card Enrolled: Attempts Processing
Card Number 340000000003391
344400000000569
Results
Without authentication window
Card enrollment option during purchase process
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
SOK
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
aesk_attempted
VERes enrolled
ECI
06
XID
XID value
PARes status
XID
XID value
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.
Table 44
American Express SafeKey Card Enrolled: Incomplete Authentication
Card Number 340000000002302
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
ECI
07
VERes enrolled
PARes status
XID
XID value
XID
XID value
Ask the customer for another form of payment, or submit the transaction. No liability shift.
Payer Authentication Using the SCMP API | June 2014
56
Chapter 3
Table 45
American Express SafeKey Card Enrolled: Unsuccessful Authentication
Card Number 340000000000033
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
User failed authentication.
Payer cannot be authenticated.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
ECI
07
VERes enrolled
XID
XID value
XID
XID value
You are not permitted to submit this transaction for authorization. Instead ask the customer for
another form of payment.
Table 46
American Express SafeKey Card Enrolled: Unavailable Authentication
Card Number 340000000007780
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
Submit your authorization request. No liability shift.
Payer Authentication Using the SCMP API | June 2014
57
Chapter 3
Table 47
Testing Payer Authentication Services
American Express SafeKey Card Enrolled: Authentication Error
Card Number 340000000009299
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: Error Processing PARes.
URL value
ECI
07
PAReq
PAReq value
E-commerce Indicator
internet
proofXML
proofXML value
VERes enrolled
XID
XID value
Ask the customer for another form of payment. No liability shift.
Table 48
American Express SafeKey Card Not Enrolled
Card Number 340000000008135
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
ECI
07
proofXML
proofXML value
VERes enrolled
Submit your authorization request. Liability shift.
Payer Authentication Using the SCMP API | June 2014
58
Chapter 3
Table 49
Testing Payer Authentication Services
American Express SafeKey Enrollment Check: Time-Out
Card Number 340000000008309
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
ECI
07
proofXML
proofXML value
After 10 12 seconds, proceed with the authorization request. No liability shift.
Table 50
American Express SafeKey Enrollment Check Error
Card Number 340000000007244
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
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 | June 2014
59
Chapter 3
Testing Payer Authentication Services
JCB J/Secure
Table 51
Possible Values for JCB J/Secure Reply Fields
Result and Interpretation
Success
Failure
(Customer
not
responsible)
pa_validate_
authentication_
result
eci
e_commerce_
indicator
rflag
05
js
100
Recorded attempt to authenticate 1
06
js_attempted
100
Successful authentication.
System error that prevents the
completion of authentication: you
can proceed with authorization,
but no liability shift.
Issuer unable to perform
authentication
07
internet
07
internet
Incomplete or unavailable
authentication.
Failure
(Customer
responsible)
100
js_failure
Invalid PARes.
-1
00
Authentication failed or
cardholder did not complete
authentication.
476
476
If the authentication fails, Visa
requires that you do not accept
the card. You must ask the
customer to use another payment
method.
a.The eci value can vary depending on the reason for the failure.
b.A dash () indicates that the field is blank or absent.
Payer Authentication Using the SCMP API | June 2014
60
Chapter 3
Table 52
JCB J/Secure Card Enrolled: Successful Authentication
Card Number 3569990010083722
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
SOK
ics_pa_validate service was successful.
URL
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
js
VERes enrolled
ECI
05
XID
XID value
PARes status
XID
XID value
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.
Table 53
JCB J/Secure Card Enrolled: Successful Authentication But Invalid
PARes (Signature Failure)
Card Number 3569990010083748
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: PARes signature digest value
mismatch. PARes message has been modified.
URL value
Authentication result
-1
PAReq
PAReq value
XID
XID value
VERes enrolled
Do not proceed with authorization. Instead ask the customer for another form of payment.
Payer Authentication Using the SCMP API | June 2014
61
Chapter 3
Table 54
Testing Payer Authentication Services
JCB J/Secure Card Enrolled: Attempted Authentication
Card Number 3569960010083758
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
CAVV
CAVV value
proofXML
proofXML value
E-commerce indicator
js_attempted
VERes enrolled
ECI
06
XID
XID value
PARes status
XID
XID value
If you request Validate Authentication and authorization services separately, follow these steps:
1 Add the signed PARes to the validation request.
2 In the reply, 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 steps described
above occurs automatically.
Table 55
JCB J/Secure Card Enrolled: Incomplete Authentication (Unavailable)
Card Number 3541599998103643
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
SOK
Issuer unable to perform authentication.
ics_pa_validate service was successful.
URL value
Authentication result
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
ECI
07
VERes enrolled
PARes status
XID
XID value
XID
XID value
Ask the customer for another form of payment, or submit the transaction. No liability shift.
Payer Authentication Using the SCMP API | June 2014
62
Chapter 3
Table 56
JCB J/Secure Card Enrolled: Failed Authentication
Card Number 3569990110083721
Results
Without authentication window
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Testing Payer Authentication Services
Reply flag
DAUTHENTICATION
FAILED
User failed authentication.
Payer cannot be authenticated.
URL value
Authentication result
PAReq
PAReq value
PARes status
proofXML
proofXML value
XID
XID value
VERes enrolled
XID
XID value
You are not permitted to submit this transaction for authorization. Instead ask the customer for
another form of payment.
Table 57
JCB J/Secure Card Enrolled: Unavailable Authentication
Card Number 3541599999103865
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
Submit your authorization request. No liability shift.
Payer Authentication Using the SCMP API | June 2014
63
Chapter 3
Table 58
Testing Payer Authentication Services
JCB J/Secure Card Enrolled: Authentication Error Processing PARes
Card Number 3541599999103881
Results
Check Enrollment
Summary Reply flag
Validate Authentication
DAUTHENTICATE
The cardholder is enrolled in Payer
Authentication. Please authenticate before
proceeding with authorization.
Details ACS URL
Action
Reply flag
DAUTHENTICATION
FAILED
We encountered a Payer Authentication
problem: Error Processing PARes.
URL value
ECI
07
PAReq
PAReq value
E-commerce indicator
internet
proofXML
proofXML value
VERes enrolled
XID
XID value
Ask the customer for another form of payment. No liability shift.
Table 59
JCB J/Secure Card Not Enrolled
Card Number 3569970010083724
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
js_attempted
ECI
06
proofXML
proofXML value
VERes enrolled
Submit your authorization request. Liability shift.
Action
Table 60
JCB J/Secure Enrollment Check: Time-Out
Card Number 3569980010083723
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
proofXML
Action
internet
proofXML value
After 10 12 seconds, proceed with the authorization request. No liability shift.
Payer Authentication Using the SCMP API | June 2014
64
Chapter 3
Table 61
Testing Payer Authentication Services
JCB J/Secure Enrollment Check: Lookup Error Processing Message
Request
Card Number 3541599969103614
Results
Check Enrollment
Summary Reply flag
Validate Authentication
SOK
ics_pa_enroll service was successful.
Details E-commerce indicator
Action
internet
proofXML
proofXML value
VERes enrolled
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 | June 2014
65
APPENDIX
API Fields
This appendix describes the SCMP (Simple Commerce Message Protocol) API fields that
you can use to access 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 %.
Note
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 62
Data Type Definitions
Data Type
Description
Date and time
The format is YYYY-MM-DDThhmmssZ. For example, 2012-0811T224757Z is equal to August 11, 2012, 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, }.
Payer Authentication Using the SCMP API | June 2014
66
Appendix A
API Fields
Data Type
Description
Positive integer
Whole number greater than zero {1, 2, 3, }.
String
Sequence of letters, numbers, spaces, and special characters, such
as @ and #.
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.
Note
Table 63
Request-Level Fields
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
card_type
Type of card. For more information, see the Credit
Card Services for the SCMP API (PDF | HTML). This
field contains one of these values:
ics_pa_enroll (R)
String (3)
001: Visa
002: MasterCard
003: American Express
007: JCB
024: Maestro (UK Domestic)
042: Maestro (International)
ics_pa_validate
(R)
Note This field is required. You must supply a value
for it and include it in your request.
currency
customer_cc_expmo
customer_cc_expyr
Currency used for the order. Use the standard ISO
codes located in the Support Center.
ics_pa_enroll (R)
Expiration month (MM) of the card. Required if
customer_cc_number is included
ics_pa_enroll (R)
Expiration year (YYYY) of the card. Required if
customer_cc_number is included
ics_pa_enroll (R)
Payer Authentication Using the SCMP API | June 2014
String (5)
ics_pa_validate
(R)
String (2)
ics_pa_validate
(O)
String (4)
ics_pa_validate
(O)
67
Appendix A
Table 63
API Fields
Request-Level Fields (Continued)
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
customer_cc_number
Customers card number.
ics_pa_enroll (R)
Nonnegative
integer (20)
ics_pa_validate
(O)
grand_total_amount
Grand total for the order. In your request, you must
include either this field or offer0 and the offer-level
field amount. For more information, see the Credit
Card Services for the SCMP API (PDF | HTML).
ics_pa_enroll (O)
String (15)
ics_pa_validate
(O)
Note This field is required if you do not use the
offer-level field "amount."
ics_applications
ignore_validate_result
String (255)
Comma-separated list of CyberSource services to
process.
ics_pa_enroll (R)
Enables you to continue processing the request
even if payer authentication cannot be validated. For
example, if the PARes is invalid, you would receive
the SOK reply flag, which enables you to process the
authorization. This field can contain one of these
values:
ics_pa_validate
(O)
String (5)
ics_pa_enroll (R)
String (30)
ics_pa_validate
(R)
yes: Ignore the results of validation and continue
to process the request.
no: (default) If payer authentication cannot be
validated, stop processing the request.
merchant_id
Your CyberSource merchant ID.
ics_pa_validate
(R)
merchant_ref_number
pa_http_accept
Merchant-generated order reference or tracking
number.
ics_pa_enroll (R)
String (50)
Value of the Accept header sent by the customers
web browser.
ics_pa_enroll (O)
String (255)
ics_pa_enroll (O)
String (255)
ics_pa_enroll (R)
Integer (4)
ics_pa_validate
(R)
Note If the customers browser provides a value,
you must include it in your request.
pa_http_user_agent
Value of the User-Agent header sent by the
customers web browser.
Note If the customers browser provides a value,
you must include it in your request.
pa_mcc
Merchant category code.
Important Required only for Verified by Visa
transactions in Brazil. Do not use this request field
for any other types of transactions.
Payer Authentication Using the SCMP API | June 2014
68
Appendix A
Table 63
API Fields
Request-Level Fields (Continued)
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
pa_mobile_phone
Cardholders mobile phone number.
ics_pa_enroll (R)
Integer (25)
ics_pa_enroll (R)
String (10)
ics_pa_enroll (R)
String (3)
ics_pa_validate
(R)
String (no
limit, may
be very
large)
Important Required only for Verified by Visa
transactions in Brazil. Do not use this request field
for any other types of transactions.
pa_override_
payment_method
Specifies the Brazilian payment account type used
for the 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
Important Required only for Verified by Visa
transactions in Brazil. Do not use this request field
for any other types of transactions.
pa_product_code
Specifies the product code, which designates the
type of transaction. Specify one of the following
values for this field:
PHY: Goods or services purchase
CHA: Check acceptance
ACF: Account funding
QCT: Quasi-cash transaction
PAL: Prepaid activation and load
Important Required only for Verified by Visa
transactions in Brazil. Do not use this request field
for any other types of transactions.
pa_signedpares
Payer authentication result (PARes) message
returned by the card-issuing bank. If you need to
show proof of enrollment checking, you may need to
decrypt and parse the string for the information
required by the card association. For more
information, see "Storing Payer Authentication
Data," page 100.
Important The value is in base64. You must
remove all carriage returns and line feeds before
adding the PARes to the request.
Payer Authentication Using the SCMP API | June 2014
69
Appendix A
Table 63
API Fields
Request-Level Fields (Continued)
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
timeout
Number of seconds the system waits before the
transaction times out. The default is 110.
ics_pa_enroll (O)
Positive
integer (3)
ics_pa_validate
(O)
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.
Note
Table 64
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.
Offer-Level Fields
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
amount
Per-item price of the product. You can include a
decimal point (.) in this field, but you cannot include
any other special characters. The amount will be
truncated to the correct number of decimal places.
ics_pa_enroll (R)
Decimal
(15)
ics_pa_validate
(R)
Note This field is not required if you use the
request-level field grand_total_amount.
quantity
Quantity of the product being purchased. The default
value is 1.
Payer Authentication Using the SCMP API | June 2014
ics_pa_enroll (O)
ics_pa_validate
(O)
Nonnegative
integer (10)
70
Appendix A
Table 64
API Fields
Offer-Level Fields (Continued)
Field Name
Description
Used By:
Required (R)
or Optional (O)
Data Type
& Length
tax_amount
Total tax to apply to the product. The tax_amount
field is additive. For example, if you send these offer
lines
ics_pa_enroll (O)
Decimal
(15)
ics_pa_validate
(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.
Reply Fields
Table 65
Reply Fields
Field Name
Description
Returned By
Data Type
& Length
client_lib_version
Information about the client library used to request
the transaction.
ics_pa_enroll
String (255)
Currency used for the order. Use the standard ISO
codes located in the Support Center.
ics_pa_enroll
One-digit code that indicates whether the entire
request was successful. The field contains one of
these values:
ics_pa_enroll
currency
ics_rcode
ics_rflag
ics_rmsg
-1: An error occurred.
0: The request was declined.
1: The request was successful.
ics_pa_validate
String (255)
ics_pa_validate
Integer (1)
ics_pa_validate
One-word description of the result of the entire
request.
ics_pa_enroll
Message that explains the reply flag ics_rflag.
ics_pa_enroll
String (255)
ics_pa_validate
String (255)
ics_pa_validate
merchant_ref_number
Merchant-generated order or tracking number.
ics_pa_enroll
String (255)
ics_pa_validate
pa_enroll_acs_url
URL for the card-issuing banks authentication form
that you receive when the card is enrolled. The value
can be very large.
Payer Authentication Using the SCMP API | June 2014
ics_pa_enroll
String (no
length limit)
71
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_enroll_
authentication_path
Indicates what the customer sees during the
authentication process. This field can contain one of
these values:
ics_pa_enroll
String (255)
ics_pa_enroll
String (255)
ADS: (card not enrolled) customer prompted to
activate the card during the checkout process.
ATTEMPTS: (attempts processing) customer
briefly sees Processing... before the checkout
process is completed.
ENROLLED: (card enrolled) customer sees the
card issuers authentication window.
UNKNOWN: card enrollment status cannot be
determined.
NOREDIRECT: (card not enrolled, authentication
unavailable, or error occurred) customer sees
nothing.
The following values can be returned if you are using
rules-based Payer Authentication. See "Rules-Based
Payer Authentication," page 118:
RIBA: The card-issuing bank supports risk-based
authentication, but whether the cardholder is likely
to be challenged cannot be determined.
pa_enroll_e_
commerce_indicator
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.
Commerce indicator for cards not enrolled. This field
contains one of these values:
internet: Card not enrolled, or card type not
supported by payer authentication. No liability
shift.
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.
spa: MasterCard card not enrolled in the
SecureCode program. No liability shift.
vbv_attempted: Card not enrolled, but
attempt to authenticate is recorded. Liability shift.
vbv_failure: For payment processor Barclays,
Streamline, AIBMS, or FDC Germany, you receive
this result if Visas directory service is not
available. No liability shift.
Payer Authentication Using the SCMP API | June 2014
72
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
pa_enroll_eci
Description
Returned By
Data Type
& Length
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, and JCB
transactions when the card is not enrolled. For more
information, see "B. Interpreting the Reply," page 25.
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_pareq
Payer authentication request (PAReq) message that
you need to forward to the ACS. The value can be
very large. The value is in base64.
ics_pa_enroll
String (No
length limit)
pa_enroll_proofxml
Date and time of the enrollment check combined with
the VEReq and VERes elements. If you ever need
to show proof of enrollment checking, you may need
to parse the string for the information required by the
card association. The value can be very large. For
more information, see "Storing Payer Authentication
Data," page 100.
ics_pa_enroll
String (no
length limit)
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
payer authentication request message.
ics_pa_enroll
String (255)
pa_enroll_rcode
Code that indicates whether the ics_pa_enroll
request was successful. The field will contain one of
these values:
ics_pa_enroll
Integer (1)
-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_
enroll request.
ics_pa_enroll
String (255)
pa_enroll_rmsg
Message that explains the reply flag pa_enroll_
rflag.
ics_pa_enroll
String (255)
Payer Authentication Using the SCMP API | June 2014
73
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_enroll_ucaf_
collection_indicator
Returned only for MasterCard transactions. Indicates
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 this value: 1.
ics_pa_enroll
String (255)
pa_enroll_veres_
enrolled
Result of the enrollment check. This field can contain
one of these values:
ics_pa_enroll
String (255)
Y: Card enrolled or can be enrolled; you must
authenticate. Liability shift.
N: Card not enrolled; proceed with authorization.
Liability shift.
U: Unable to authenticate regardless of the
reason. No liability shift.
Note This field only applies to the Asia, Middle
East, and Africa Gateway. If you are configured for
this processor, you must send the value of this field
in your authorization request.
The following value can be returned if you are using
rules-based Payer Authentication. See "Rules-Based
Payer Authentication," page 118:
B: Indicates that authentication was bypassed.
pa_enroll_xid
Transaction identifier generated by CyberSource for
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.
ics_pa_enroll
String (255)
pa_validate_
authentication_result
Raw authentication data that comes from the cardissuing bank. Primary authentication field that
indicates if authentication was successful and if
liability shift occurred. You should examine first the
result of this field. This field contains one of these
values:
ics_pa_validate
String w/
numbers
only (255)
ics_pa_validate
String (255)
-1: Invalid PARes.
0: Successful validation.
1: Cardholder is not participating, but the attempt
to authenticate was recorded.
pa_validate_
authentication_status_
msg
6: Issuer unable to perform authentication.
9: Cardholder did not complete authentication.
Message that explains the pa_validate_
authentication_result reply field. Returned only for
Visa and JCB transactions.
Payer Authentication Using the SCMP API | June 2014
74
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_validate_cavv
Unique identifier generated by the card-issuing bank
for Visa and American Express 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.
ics_pa_validate
String (255)
pa_validate_cavv_
algorithm
Field that is returned only when the CAVV is
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:
ics_pa_validate
Integer (1)
2: Visa, American Express, and JCB
3: MasterCard
Payer Authentication Using the SCMP API | June 2014
75
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_validate_e_
commerce_indicator
Indicator used to differentiate Internet transactions
from other types. 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.
ics_pa_validate
String (255)
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 was 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 was recorded.
moto: Mail or telephone order.
recurring: Recurring transaction.
spa: MasterCard SecureCode authentication
verified successfully.
spa_failure: MasterCard SecureCode failed
authentication.
vbv: Verified by Visa authentication verified
successfully.
vbv_attempted: Card not enrolled in Verified
by Visa, but the attempt to authenticate was
recorded.
vbv_failure: Verified by Visa authentication
unavailable.
Payer Authentication Using the SCMP API | June 2014
76
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_validate_eci
Numeric electronic commerce indicator (ECI)
returned only for Visa, American Express, and JCB
transactions. The field is absent when authentication
fails.
ics_pa_validate
String (255)
ics_pa_validate
String (255)
ics_pa_validate
String (255)
ics_pa_validate
Integer (1)
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,
American Express, and JCB. 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: Incomplete authentication (MasterCard)
02: Successful authentication (MasterCard)
05: Successful authentication (Visa, American
Express, and JCB)
pa_validate_pares_
status
pa_validate_rcode
06: Authentication attempted (Visa, American
Express, and JCB)
Raw result of the authentication check. If you are
configured for Asia, Middle East, and Africa Gateway
Processing, you need to send the value of this field
in your authorization request. This field can contain
one of these values:
A: Proof of authentication attempt was generated.
N: Customer failed or cancelled authentication.
Transaction denied.
U: Authentication not completed regardless of the
reason.
Y: Customer was successfully authenticated.
One-digit code that indicates whether the ics_pa_
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
Payer Authentication Using the SCMP API | June 2014
77
Appendix A
Table 65
API Fields
Reply Fields (Continued)
Field Name
Description
Returned By
Data Type
& Length
pa_validate_rflag
One-word description of the result of the ics_pa_
validate request.
ics_pa_validate
String (255)
pa_validate_rmsg
Message that explains the reply flag pa_validate_
rflag.
ics_pa_validate
String (255)
pa_validate_ucaf_
authentication_data
AAV is a unique identifier generated by the cardissuing bank for MasterCard SecureCode
transactions after the customer is authenticated. The
value is in base64. Include the data in the card
authorization request.
ics_pa_validate
String (255)
pa_validate_ucaf_
collection_indicator
Numeric electronic commerce indicator (ECI)
returned only for MasterCard SecureCode
transactions. The field is absent when authentication
fails. You must send this value to your payment
processor in the request for card authorization. This
field contain one of these values:
ics_pa_validate
Nonnegative
integer (1)
ics_pa_validate
String (255)
ics_pa_enroll
String (255)
pa_validate_xid
request_id
0: Authentication data not collected, and customer
authentication was not completed.
1: Authentication data not collected because
customer authentication was not completed.
2: Authentication data collected because
customer completed authentication.
Transaction identifier generated by CyberSource for
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
Identifier for the request generated by the client.
ics_pa_validate
request_token
Identifier for the request generated by CyberSource.
ics_pa_enroll
Request token data created by CyberSource for
each reply. The field is an encoded string that
contains no confidential information such as an
account or card verification number. The string can
contain a maximum of 256 characters.
ics_pa_validate
Payer Authentication Using the SCMP API | June 2014
String (256)
78
APPENDIX
Reply Flags
Table 66
Reply Flags Returned by the SCMP API
Reply Flag
Description
Services
DAUTHENTICATE
The customer participates in payer authentication.
Authenticate the customer, and verify the results of
authentication.
ics_pa_enroll
DAUTHENTICATIONFAILED
The results of payer authentication cannot be validated.
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
ETIMEOUT
A system error. Wait several minutes, then try sending your
request again.
ics_pa_enroll
The request timed out.
ics_pa_enroll
ics_pa_validate
ics_pa_validate
SOK
The transaction was successful.
ics_pa_enroll
ics_pa_validate
Payer Authentication Using the SCMP API | June 2014
79
APPENDIX
Request and Reply
Examples
This appendix contains examples for the check enrollment service and the validate
authentication service for all card types. All examples are in name-value pair format.
Warning
These examples contain only the fields essential to the demonstration. Do not
prepare your implementation according to the fields that you see in these
examples. They are provided for your information only.
Check Enrollment
The following is an example of a request for the check enrollment service:
Example
Check Enrollment Example
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2015
customer_cc_number=xxxxxxxxxxxxxxxx
card_type=001
ics_applications=ics_pa_enroll
merchant_id=infodev
merchant_ref_number=23AB6B62FF6DEEEE077F2A8C6
offer0=amount:19.99
Payer Authentication Using the SCMP API | June 2014
80
Appendix C
Request and Reply Examples
Transaction Reply for Visa with Verified by
Visa
The pa_enroll_proofxml field is returned in replies for both enrolled and unenrolled
cards. For more information on this field, see "Storing Payer Authentication Data,"
page 100. For an example, see "ProofXML," page 87.
Enrolled card: The rflags and the rmsgs mean that the card is enrolled and that you must
proceed with validation.
Example
Transaction Reply for Visa Card Enrolled in Verified by Visa
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.8
pa_enroll_acs_url=https://www.example.com
pa_enroll_pareq=value in base64: eJxVUuFygjAMfhXPw9Tkv9g6...
pa_enroll_proofxml=see example "ProofXML," page 87.
pa_enroll_proxypan=Cpj25JL53E9sqNKj
pa_enroll_xid=dOaE6u0nNpCBQHzAebKyADw4aQE=
ics_rcode=0
ics_rflag=DAUTHENTICATE
ics_rmsg=The cardholder is enrolled in Payer Authentication. Please
authenticate before proceeding with authorization.
pa_enroll_rcode=0
pa_enroll_rflag=DAUTHENTICATE
pa_enroll_rmsg=The cardholder is enrolled in Payer Authentication.
Please authenticate before proceeding with authorization.
request_id=0340290070000167905080
merchant_ref_number=23AB6B62FF6DEEEE077F2A8C6
currency=USD
Unenrolled card: The rflags and the rmsgs mean that the card is unenrolled and that you
can proceed with the transaction.
Example
Transaction Reply for Unenrolled Visa Card
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.8
request_id=023983672038997689279827
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=9319570
pa_enroll_e_commerce_indicator=vbv_attempted
pa_enroll_eci=06
pa_enroll_proofxml=see example "ProofXML," page 87.
pa_enroll_rcode=1
pa_enroll_rflag=SOK
pa_enroll_rmsg=ics_pa_enroll service was successful
Payer Authentication Using the SCMP API | June 2014
81
Appendix C
Request and Reply Examples
Transaction Reply for MasterCard with
SecureCode
The pa_enroll_proofxml field is returned in replies for both enrolled and unenrolled
cards. For more information on this field, see "Storing Payer Authentication Data,"
page 100. For an example, see "ProofXML," page 87.
Enrolled: The rflags and the rmsgs mean that the card is enrolled and that you must
proceed with validation.
Example
Transaction Reply for MasterCard Enrolled in SecureCode
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.8
request_id=0340290070000167905080
merchant_ref_number=23AB6B62FF6DEEEE077F2A8C6
pa_enroll_acs_url=https://www.example.com
pa_enroll_pareq=value in base64: eJxVUuFygjAMfhXPw9Tkv9g6...
ics_rcode=0
ics_rflag=DAUTHENTICATE
ics_rmsg=The cardholder is enrolled in Payer Authentication. Please
authenticate before proceeding with authorization.
pa_enroll_rcode=0
pa_enroll_rflag=DAUTHENTICATE
pa_enroll_rmsg=The cardholder is enrolled in Payer Authentication.
Please authenticate before proceeding with authorization.
pa_enroll_proofxml=see example "ProofXML," page 87.
pa_enroll_proxypan=Cpj25JL53E9sqNKj
pa_enroll_xid=dOaE6u0nNpCBQHzAebKyADw4aQE=
Unenrolled card: The rflags and the rmsgs mean that the card is unenrolled and that you
can proceed with the transaction.
Payer Authentication Using the SCMP API | June 2014
82
Appendix C
Example
Request and Reply Examples
Transaction Reply for Unenrolled MasterCard
client_lib_version=Perl5.0/solaris2.6/sol25/C/3.4.8
request_id=0682437000000167904548
merchant_ref_number=cybs_test
ics_rcode=0
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
pa_enroll_e_commerceIndicator=spa
pa_enroll__ucafCollectionIndicator=1
pa_enroll_rcode=0
pa_enroll_rflag=SOK
pa_enroll_rmsg=Request was processed successfully.
pa_enroll_proofxml=see example "ProofXML," page 87.
Transaction Reply for JCB with J/Secure
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.8
pa_enroll_acs_url=https://www.example.com
pa_enroll_pareq=value in base64: eJxVUuFygjAMfhXPw9Tkv9g6...
pa_enroll_proxypan=Cpj25JL53E9sqNKj
pa_enroll_xid=dOaE6u0nNpCBQHzAebKyADw4aQE=
ics_rcode=0
ics_rflag=DAUTHENTICATE
ics_rmsg=The cardholder is enrolled in Payer Authentication. Please
authenticate before proceeding with authorization.
pa_enroll_rcode=0
pa_enroll_rflag=DAUTHENTICATE
pa_enroll_rmsg=The cardholder is enrolled in Payer Authentication.
Please authenticate before proceeding with authorization.
currency=USD
request_id=0340290070000167905080
merchant_ref_number=23AB6B62FF6DEEEE077F2A8C6
Payer Authentication Using the SCMP API | June 2014
83
Appendix C
Request and Reply Examples
Validate Authentication
This example shows a request for the Validate Authentication service.
customer_cc_expmo=12
customer_cc_expyr=2015
customer_cc_number=xxxxxxxxxxxxxxxx
card_type=001
currency=USD
ics_applications=ics_pa_validate
merchant_id=infodev
merchant_ref_number=23AEE8CB6B62EE2AF077FF6D6
pa_signedpares=value in base64: HTNH2esM9VG0NbwDAEk9BmEG4F8e...
Payer Authentication Using the SCMP API | June 2014
84
Appendix C
Request and Reply Examples
Transaction Reply for Visa with Verified by
Visa
client_lib_version=Perl3.2/solaris2.6/sol25/C/3.4.8
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=USD
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_cavv=KuptWQm6guKE7DJNzDaBrlCD1B0=
pa_validate_e_commerce_indicator=vbv
pa_validate_eci=05
pa_validate_rcode=1
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_xid=dOaE6u0nNpCBQHzAebKyADw4aQE=
request_id=0348277000000167904548
merchant_ref_number=23AEE8CB6B62EE2AF077FF6D6
Transaction Reply for MasterCard with
SecureCode
client_lib_version=Perl5.0/solaris2.6/sol25/C/3.4.8
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=USD
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_e_commerce_indicator=spa
pa_validate_rcode=1
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_ucaf_authentication_data=jCqc1hsECvWZABEAAANrTB+itZU=
pa_validate_ucaf_collection_indicator=2
request_id=0682438330010167904548
merchant_ref_number=cybs_test
Payer Authentication Using the SCMP API | June 2014
85
Appendix C
Request and Reply Examples
Transaction Reply for JCB with J/Secure
client_lib_version=Perl3.2/solaris2.6/sol25/C/3.4.8
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=USD
pa_validate_authentication_result=0
pa_validate_authentication_status_msg=Success
pa_validate_cavv=KuptWQm6guKE7DJNzDaBrlCD1B0=
pa_validate_e_commerce_indicator=js
pa_validate_eci=05
pa_validate_rcode=1
pa_validate_rflag=SOK
pa_validate_rmsg=ics_pa_validate service was successful
pa_validate_xid=dOaE6u0nNpCBQHzAebKyADw4aQE=
request_id=0348277000000167904548
merchant_ref_number=23AEE8CB6B62EE2AF077FF6D6
Payer Authentication Using the SCMP API | June 2014
86
Appendix C
Request and Reply Examples
ProofXML
ProofXML usually appears in code as a string. It is provided in the following form to
enhance readability.
<AuthProof>
<Time>2009 Jan 19 11:01:52</Time>
<DSUrl>https:216.150.137.86:443/merchantacsfrontend/VeReq.jsp</
DSUrl>
<VEReqProof>
<Message id="xfm5_3_0.6784">
<VEReq>
<version>1.0.2</version>
<pan>XXXXXXXXXXXX0051</pan>
<Merchant>
<acqBIN>123456</acqBIN>
<merID>123456780000000</merID>
</Merchant>
<Browser>
<accept>null</accept>
<userAgent>null</userAgent>
</Browser>
</VEReq>
</Message>
</VEReqProof>
<VEResProof>
<Message id="xfm5_3_0.6784">
<VERes>
<version>1.0.2</version>
<CH>
<enrolled>N</enrolled>
</CH>
</VERes>
</Message>
</VEResProof>
</AuthProof>
Payer Authentication Using the SCMP API | June 2014
87
APPENDIX
Web Site Modification
Reference
This appendix contains information about modifying your web site to integrate Payer
Authentication services into your checkout process. It also provides links to card
association web sites where you can download the appropriate logos.
Web Site 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.
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 "3-D Secure Services Logos,"
page 89.
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 90.
Payer Authentication Using the SCMP API | June 2014
88
Appendix D
Web Site Modification Reference
3-D Secure Services Logos
The following table contains links to card association web sites where you can download
logos and information about how to incorporate them into your online checkout process.
3-D Secure service
Where to download logos and information
Verified by Visa
http://usa.visa.com/merchants/risk_management/vbv.html
This web site contains information about Verified by Visa and links where you can
download logos. The page also contains links to a best practice guide for implementing
Verified by Visa and a link to a Merchant Toolkit. See the list of links at the right margin of
the web page to download these files.
MasterCard and
Maestro SecureCode
http://www.mastercard.us/merchants/securecode.html
This web site contains information about SecureCode, links where you can download
logos, and information about integrating the SecureCode information into your web site
checkout page.
For information about Maestro logos, go to: http://www.mastercardbrandcenter.com/us/
howtouse/bms_mae.shtml
American Express
SafeKey
http://enroll.amexsafekey.com/aesklogos
JCB J/Secure
http://partner.jcbcard.com/security/jsecure/logo.html
This web site contains information about SafeKey and links where you can download
logos.
This web site contains information about J/Secure and links where you can download
logos.
Payer Authentication Using the SCMP API | June 2014
89
Appendix D
Web Site 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 specific 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 1
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 2
Your card may be eligible for enrollment or is enrolled in the Verified by Visa,
MasterCard or Maestro SecureCode, American Express SafeKey, or JCB J/Secure
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 | June 2014
90
APPENDIX
Payer Authentication
Transaction Details in the
Business Center
This appendix describes how to search the Business Center for details of transactions that
are screened by Payer Authentication. Transaction data is stored for 12 months so that
you can send it to card associations if necessary.
Searching for Payer
Authentication Details
Payer Authentication data that is returned in API reply 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
The following figure shows the details page of an enrollment check for an enrolled card.
You receive Payer Authentication information in several locations:
Request Information section: The enrollment check service is shown in red because
the card is enrolled. You receive the corresponding reply information (blue boxes). If
Payer Authentication Using the SCMP API | June 2014
91
Appendix E
Payer Authentication Transaction Details in the Business Center
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).
Payment Information section: When authentication is required, save the XID for use
later. You do not receive an ECI because the authentication is not complete, and you
do not receive an AAV_CAVV for an enrollment check.
When you receive a result similar to the following figure, you need to authenticate the user
by requesting the validation service.
Related Events
Details
Payer Authentication Using the SCMP API | June 2014
92
Appendix E
Payer Authentication Transaction Details in the Business Center
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.
For example, in the previous figure, you can use the link to find the details page that
shows the associated card validation and authorization results. The following figure shows
the results page:
The most recent event is the successful authentication. If you click the request ID, you
see the authentication details page. Because this event also returned an XID value,
the By Payer Authentication History link is present. If you click it, you are returned 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. The following figure shows these events:
The most recent event is the combined successful customer authentication and card
authorization. If you click the request ID, you see the details page.
The older event is the enrollment check in red because the card is enrolled.
Payer Authentication Using the SCMP API | June 2014
93
Appendix E
Payer Authentication Transaction Details in the Business Center
Payer Authentication Details
You also can search for the Payer Authentication data with the View Payer Authentication
Details link located under Extended Views. The following figure and the XML code that
follows shows details for the above transaction. The XML code is returned if you click
Export to XML File. CyberSource stores Payer Authentication information for 12 months
after the transaction. For more information about this XML report, see "Payer
Authentication Detail Report," page 106.
example
1234567
special_id
1234567
special_id
1234567
special_id
Payer Authentication Using the SCMP API | June 2014
94
Appendix E
Payer Authentication Transaction Details in the Business Center
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Result SYSTEM "https://ebc.cybersource.com/ebc/reports/dtd/
payerauthdetails.dtd">
<Result>
<PayerAuthDetail>
<RequestID>1889453160000167904548</RequestID>
<MerchantID>example</MerchantID>
<TransactionDate>Sep 04 2007 03:35:16 PM</TransactionDate>
<TransactionType>ics_pa_enroll</TransactionType>
<ProofXML>
<Date>20070904 15:30:21</Date>
<DSURL>https:123.456.789.01:234</DSURL>
<PAN>XXXXXXXXXXXX1007</PAN>
<AcqBIN>1234567</AcqBIN>
<MerID>00032805455400000</MerID>
<Password>XXXXXXXX</Password>
<Enrolled>Y</Enrolled>
</ProofXML>
<VEReq>
<PAN>XXXXXXXXXXXX1007</PAN>
<AcqBIN>1234567</AcqBIN>
<MerID>special_id</MerID>
</VEReq>
<VERes>
<Enrolled>Y</Enrolled>
<AcctID>G7XnvRUvB6jKH5/KxVBwYnx6cyw=</AcctID>
<URL>https://www.example_url.com</URL>
</VERes>
<PAReq>
<AcqBIN>1234567</AcqBIN>
<MerID>00032805455400000</MerID>
<Name>Example_Merchant</Name>
<Country>US</Country>
<URL>http://www.example_merchant.com</URL>
<XID>a/Q7zFs2EdyKlZjve2/X4gEAAAc=</XID>
<Date>Sep 04 2007 03:30:21 PM</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<AcctID>G7XnvRUvB6jKH5/KxVBwYnx6cyw=</AcctID>
<Expiry>0905</Expiry>
</PAReq>
</PayerAuthDetail>
</Result>
Payer Authentication Using the SCMP API | June 2014
95
Appendix E
Payer Authentication Transaction Details in the Business Center
Authentication Validation
The following figure shows a details page in which the validation and the card
authorization services were processed successfully. The red boxes show where Payer
Authentication data is located in the Transaction Search Details window:
Request Information section: The validation service succeeded. You receive the
reason code 100, and the corresponding reply message. The necessary Payer
Authentication information was passed to the card authorization service, which was
processed successfully. Both services are shown in green.
Payment 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 | June 2014
96
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.
Payer Authentication Details
You can also search for the Payer Authentication data by using the View Payer
Authentication Details link located under Extended Views. The following figure and the
XML code that follows shows those details for the above transaction. The XML code is
returned if you click Export to XML File. Payer Authentication information is stored for 12
months after the transaction. For more information on this XML report, see "Payer
Authentication Detail Report," page 106.
example
123456
special_id
123456
special_id
Payer Authentication Using the SCMP API | June 2014
97
Appendix E
Payer Authentication Transaction Details in the Business Center
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Result SYSTEM "https://ebc.cybersource.com/ebc/reports/dtd/
payerauthdetails.dtd">
<Result>
<PayerAuthDetail>
<RequestID>1897243130000167904548</RequestID>
<MerchantID>example</MerchantID>
<TransactionDate>Sep 13 2007 03:58:36 PM</TransactionDate>
<TransactionType>ics_pa_enroll</TransactionType>
<ProofXML>
<Date>20070913 15:53:37</Date>
<DSURL>https:123.456.789.01:234</DSURL>
<PAN>XXXXXXXXXXXX0008</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>special_id</MerID>
<Password />
<Enrolled>N</Enrolled>
</ProofXML>
<VEReq>
<PAN>XXXXXXXXXXXX0008</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>special_id</MerID>
</VEReq>
<VERes>
<Enrolled>N</Enrolled>
<AcctID />
<URL />
</VERes>
</PayerAuthDetail>
</Result>
Payer Authentication Using the SCMP API | June 2014
98
Appendix E
Payer Authentication Transaction Details in the Business Center
Transaction Details
The red boxes show where Payer Authentication data is located in the Transaction Search
Details window:
Request Information section: The service is shown in green. You can obtain additional
information about related orders by clicking the link on the right.
Payment Information section: You see the detailed information for the authorization
service:
The ECI value is 1: Authentication is not required because the customers
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 Using the SCMP API | June 2014
99
Appendix E
Payer Authentication Transaction Details in the Business Center
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 customers 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 91.
Storing Payer Authentication Data
Card associations 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, card associations 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 card association. 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 example enrollment replies, see "Transaction Reply
for Visa with Verified by Visa," page 81. The replies are similar for all card types. Although
the proof XML field is shown only in the Visa card replies, this field is returned for all card
types.
Card associations have implemented the 3-D Secure protocol differently 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 | June 2014
100
APPENDIX
Payer Authentication
Reports
This chapter describes the reports that you can download from the Business Center. All
reports on the production servers are retained for 16 months although the transaction
history is kept in the database for six months only. All reports on the test servers are
deleted after two weeks. Only transactions that were processed are reported. Those that
resulted in system error or time-out are not. For more information about API replies and
their meanings, see Appendix A, "API Fields," on page 66.
To obtain the reports, you must file a support ticket in the Support Center.
Important
Payer Authentication Summary
Report
This daily, weekly, and monthly summary report shows for each currency and type of card
that you support the performance of the enrollment and validation services as number of
transactions and total amount for groups of transactions. 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, JCB,
and Maestro. This daily report is generally available by 7:00 AM Eastern Time. The data in
this report remains available for six months.
Payer Authentication Using the SCMP API | June 2014
101
Appendix F
Payer Authentication Reports
Downloading the Report
To view a report, follow these steps:
Step 1
In the navigation pane, select Reports > Report Search.
The figure below shows the Reports Search page.
Step 2
Select the report and the type that you want to see.
The type of report that you choose (daily, weekly, or monthly) determines the date or time
range that appears below.
Step 3
Select the appropriate date or time range and submit your search request.
If reports are available, a list appears.
If no reports are available, the Business Center displays the message No Reports
Available.
Payer Authentication Using the SCMP API | June 2014
102
Appendix F
Step 4
Payer Authentication Reports
Click Payer Authentication Report.
The report opens.
This report shows three successfully authenticated Visa transactions.
You can look at the report online by navigating between pages, but to store the content,
export the report either in PDF format or as a spreadsheet as shown on the figure.
Matching the Report to the Transaction Search
Results
You can find the transactions that are reported in the Transaction Search section of the
Business Center. The figure below shows the search results that contain the transactions
that appear in the above report. For more information on the search results and their
details, see "Searching for Payer Authentication Details," page 91.
Payer Authentication Using the SCMP API | June 2014
103
Appendix F
Payer Authentication Reports
Interpreting the Report
The header of all reports 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 divided by card type.
In each section, all 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. The table below summarizes in the last two columns.
Card Type
Visa and JCB
MasterCard
and Maestro
Interpretation
Protected? Reported
Commerce Indicator
ECI
Internet
Recorded attempt to authenticate Yes
VbV or JS Attempted
Successful authentication
Yes
VbV or JS
No authentication
No
Internet2
71
Incomplete authentication
No
SPA Failure3
Successful authentication
Yes
SPA
No authentication
No
Although the report heading is 7, you receive a collection indicator value of 1, or the reply field is empty.
Although the report heading is Internet, you receive spa_failure in the commerce indicator reply field.
3
Although the report heading is SPA Failure, you receive spa in the commerce indicator reply field.
2
Transactions are divided into two groups: those for which you are protected and those for
which you are not:
For Visa and JCB: 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 | June 2014
104
Appendix F
Payer Authentication Reports
Comparing Payer Authentication and Payment
Reports
You may see differences between the Payer Authentication report and the payment
reports because an authenticated transaction may not be authorized.
The values (amounts and counts) that you see 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. You are even more likely to see reconciliation discrepancies if you
process your authorizations outside of CyberSource.
Example
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, you would see 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 | June 2014
105
Appendix F
Payer Authentication Reports
Payer Authentication Detail Report
This section describes the XML report that you download when you click the Export to
XML feature in the Payer Authentication details page of the Business Center. The data in
this report remains available for 12 months. You can obtain the DTD in the
Reports > DTDs section of the Business Center.
File Name
The file that you download is named according to this format:
<MerchantID>-<RequestID>-<TransactionType>.xml
Example
example_merchant-1884340770000167904548-ics_pa_
enroll.xml
Date and Time
In the report, the date and time are shown in this format:
YYYY-MM-DDTHH:MM:SS[+ | -]HH:MM:
YYYY-MM-DD is the year, month, and day.
THH:MM:SS is the time (hours, minutes, and seconds).
[+ | -]HH:MM is the time zones offset from Greenwich Mean Time (GMT), with HH
representing hours and MM representing minutes. The number is prefixed by either a
plus (+) or minus (-) to indicate whether the offset adds to or subtracts from GMT. For
example, the offset for Pacific Daylight Time (PDT) is -07:00.
Example
2006-07-31T16:31:18-07:00 represents July 31, 2006 at 4:31:18 PM
PDT
Payer Authentication Using the SCMP API | June 2014
106
Appendix F
Payer Authentication Reports
Report
<Result>
The <Result> element is the root element of the report.
<Result>
(PayerAuthDetail+)
</Result>
Table 67
Child Elements of <Report>
Element Name
Description
<PayerAuthDetail>
Contains the transaction in the report. For a list of child elements, see
<PayerAuthDetail>.
Example
<Report> Element
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Report SYSTEM "https://ebctest.cybersource.com/ebctest/reports/dtd/
payerauthdetails.dtd">
<Result>
<PayerAuthDetail>
...
</PayerAuthDetail>
</Result>
<PayerAuthDetail>
The <PayerAuthDetail> element contains information about a single transaction.
<PayerAuthDetail>
(RequestID)
(MerchantID)
(TransactionDate)
(TransactionType)
(ProofXML)?
(VEReq)?
(VERes)?
(PAReq)?
(PARes)?
(AuthInfo)?
</PayerAuthDetail>
Payer Authentication Using the SCMP API | June 2014
107
Appendix F
Table 68
Payer Authentication Reports
Child Elements of <PayerAuthDetail>
Element Name
Description
Type &
Length
<RequestID>
Unique identifier generated by CyberSource for the transaction.
This field corresponds to the request_idAPI field.
Numeric (26)
<MerchantID>
CyberSource merchant ID used for the transaction.
String (30)
<TransactionDate>
Date on which the transaction was processed.
DateTime
(25)
<TransactionType>
CyberSource service requested in SCMP format. This field can
contain one of the following values:
String (20)
<ProofXML>
ics_auth: Card authorization service
ics_pa_enroll: Payer Authentication Enrollment Check
ics_pa_validate: Payer Authentication Validation
Data that includes the date and time of the enrollment check and
the VEReq and VERes elements. This field corresponds to the
pa_enroll_proofxml API field.
String (1024)
For a list of child elements, see "ProofXML," page 87.
<VEReq>
Verify Enrollment Request (VEReq) sent by the merchants
server to the directory server and by the directory server to the
ACS to determine whether authentication is available for the
customers card number. For a list of child elements, see
"<VEReq>," page 110.
<VERes>
Verify Enrollment Response (VERes) sent by the directory server.
For a list of child elements, see "<VERes>," page 111.
<PAReq>
Payer Authentication Request message that you send to the ACS
through the card association. Corresponds to the pa_enroll_
pareq API field.
For a list of child elements, see "<PAReq>," page 112.
<PARes>
Payer Authentication Response message sent by the ACS. For a
list of child elements, see "<PARes>," page 113.
<AuthInfo>
Address and card verification data. For a list of child elements,
see "<AuthInfo>," page 115.
Payer Authentication Using the SCMP API | June 2014
108
Appendix F
Example
Payer Authentication Reports
<PayerAuthDetail> Element
<PayerAuthDetail>
<RequestID>0004223530000167905139</RequestID>
<MerchantID>example_merchant</MerchantID>
<TransactionDate>2007-07-25T18:23:22-07:00</TransactionDate>
<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 69
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.
Payer Authentication Using the SCMP API | June 2014
String (50)
109
Appendix F
Table 69
Payer Authentication Reports
Child Elements of <ProofXML> (Continued)
Element Name
Description
Type & Length
<PAN>
Customers masked account number. This element corresponds to the
pa_enroll_proxypan API field.
String (19)
<AcqBIN>
First six digits of the acquiring banks identification number.
Numeric (6)
<MerID>
Identifier provided by your acquirer; used to log in to the ACS URL.
String (24)
<Password>
Merchant's masked authentication password to the ACS; provided by
your acquirer. Applies only to cards issued outside the U.S.
String (8)
<Enrolled>
Result of the enrollment check. This field can contain one of these
values:
String (1)
Y: Authentication available.
N: Cardholder not participating.
U: Unable to authenticate regardless of the reason.
Example
<ProofXML> Element
<ProofXML>
<Date>20070725 11:18:51</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 70
Child Elements of <VEReq>
Element Name
Description
Type & Length
<PAN>
Customers masked account number. This element corresponds to the
pa_enroll_proxypan API field.
String (19)
<AcqBIN>
First six digits of the acquiring banks 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 | June 2014
110
Appendix F
Example
Payer Authentication Reports
<VEReq> Element
<VEReq>
<PAN>XXXXXXXXXXXX0771</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>example</MerID>
</VEReq>
<VERes>
The <VERes> element contains the enrollment check reply data.
<VERes>
(Enrolled)
(AcctID)
(URL)
</VERes>
Table 71
Child Elements of <VERes>
Element Name
Description
Type & Length
<Enrolled>
Result of the enrollment check. This field can contain one of these
values:
String (1)
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
corresponds to the pa_enroll_acs_url API field.
String (1000)
Example
<VERes> Element
<VERes>
<Enrolled>Y</Enrolled>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<URL>https://www.example_url.com</URL>
</VERes>
Payer Authentication Using the SCMP API | June 2014
111
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 72
Child Elements of <PAReq>
Element Name
Description
Type & Length
<AcqBIN>
First six digits of the acquiring banks identification number.
Numeric (6)
<MerID>
Identifier provided by your acquirer; used to log in to the ACS URL.
String (24)
<Name>
Merchants company name.
String (25)
<Country>
Two-character code for the merchants country of operation.
String (2)
<URL>
Merchants business web site.
String
<XID>
Unique transaction identifier generated by CyberSource for each
Payment Authentication Request (PAReq) message. The PARes sent
back by the issuing bank contains the XID of the PAReq. To ensure that
both XIDs are the same, compare it to the XID in the reply. To find all
requests related to a transaction, you can also search transactions for a
specific XID.
String (28)
<Date>
Date and time of request.
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
Amount>
Authorization amount and currency for the transaction. This element
corresponds to the totals of the offer lines or from the following field:
Amount (15)
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 customers card.
Number (4)
Payer Authentication Using the SCMP API | June 2014
112
Appendix F
Example
Payer Authentication Reports
<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>2007-07-25T18:18:51-07:00</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<Expiry>0811</Expiry>
</PAReq>
<PARes>
The <PARes> element contains the payer authentication reply message.
<PARes>
(AcqBIN)
(MerID)
(XID)
(Date)
(PurchaseAmount)
(PAN)
(AuthDate)
(Status)
(CAVV)
(ECI)
</PARes>
Table 73
Child Elements of <PARes>
Element Name
Description
Type & Length
<AcqBIN>
First six digits of the acquiring banks identification number.
Numeric (6)
<MerID>
Identifier provided by your acquirer; used to log in to the ACS
URL.
String (24)
<XID>
XID value returned in the customer authentication reply. This
element corresponds to the pa_enroll_xid and pa_validate_xid
API fields.
String (28)
<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 | June 2014
113
Appendix F
Table 73
Payer Authentication Reports
Child Elements of <PARes> (Continued)
Element Name
Description
Type & Length
<PurchaseAmount>
Authorization amount and currency for the transaction. This
element corresponds to the totals of the offer lines or from the
following field:
Amount (15)
grand_total_amount (see Credit Card Services Using the
SCMP API [PDF | HTML])
<PAN>
Customers masked account number. This element corresponds
to the pa_enroll_proxypan API field.
String (19)
<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
these values:
Y: Customer was successfully authenticated.
N: Customer failed or cancelled authentication. Transaction
denied.
U: Authenticate not completed regardless of the reason.
A: Proof of authentication attempt was generated.
String (1)
<CAVV>
CAVV (Visa and JCB cards = * below) or AAV (MasterCard, and
Maestro cards = ** below) returned in the customer authentication
reply. This element corresponds to the pa_validate_cavv (*) and
pa_validate_ucaf_authentication_data (**) API fields.
String (50)
<ECI>
Electronic commerce indicator returned in the customer
authentication reply. This element corresponds to the pa_
validate_eci (*) and pa_validate_ucaf_collection_indicator (**)
API fields.
Numeric (1)
Payer Authentication Using the SCMP API | June 2014
114
Appendix F
Example
Payer Authentication Reports
<Card> Element
<PARes>
<AcqBIN>123456</AcqBIN>
<MerID>4444444</MerID>
<XID>Xe5DcjrqEdyC37MOPfIzMwAHBwE=</XID>
<Date>2007-07-25T20:05:18-07:00</Date>
<PurchaseAmount>1002.00 USD</PurchaseAmount>
<PAN>0000000000000771</PAN>
<AuthDate>2007-07-25T20:05:18-07: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 74
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).
Optional results of the card verification number test.
<CVVResult>
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 | June 2014
115
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://ebc.cybersource.com/ebc/reports/dtd/
payerauthdetails.dtd">
<Result>
<PayerAuthDetail>
<RequestID>1895549430000167904548</RequestID>
<MerchantID>sample_merchant_id</MerchantID>
<TransactionDate>Sep 11 2007 04:55:44 PM</TransactionDate>
<TransactionType>ics_pa_enroll</TransactionType>
<ProofXML>
<Date>20070911 16:51:00</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>Sep 11 2007 04:51:00 PM</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<Expiry>0811</Expiry>
</PAReq>
</PayerAuthDetail>
</Result>
Payer Authentication Using the SCMP API | June 2014
116
Appendix F
Payer Authentication Reports
Successful Authentication
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Result SYSTEM "https://ebc.cybersource.com/ebc/reports/dtd/
payerauthdetails.dtd">
<Result>
<PayerAuthDetail>
<RequestID>1895549900000167904548</RequestID>
<MerchantID>ics2test</MerchantID>
<TransactionDate>Sep 11 2007 04:56:31 PM</TransactionDate>
<TransactionType>ics_pa_validate</TransactionType>
<PARes>
<AcqBIN>469216</AcqBIN>
<MerID>6678516</MerID>
<XID>2YNaNGDBEdydJ6WI6aFJWAAHBwE=</XID>
<Date>Sep 11 2007 04:51:00 PM</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<PAN>0000000000000771</PAN>
<AuthDate>Sep 11 2007 04:51:00 PM</AuthDate>
<Status>Y</Status>
<CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
<ECI>5</ECI>
</PARes>
</PayerAuthDetail>
</Result>
Payer Authentication Using the SCMP API | June 2014
117
APPENDIX
Rules-Based Payer
Authentication
Rules-based Payer Authentication enables you to specify rules that define how
transactions are authenticated by a 3-D 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.
Available Rules
By default, when Payer Authentication is enabled on your account, authentication is
attempted on all transactions.
If you enable the rules-based Payer Authentication service on your account, you can
bypass authentication for one or more of the following transaction types:
Table 75
Rules-Based Payer Authentication Transaction Types
Transaction Type
Description
Non-Participating Banks
Card-issuing bank does not participate in a 3-D Secure program.
When enrollment is checked, this transaction type provides full 3-D
Secure benefits, including fraud chargeback liability shift for
customer I didnt do it transactions and interchange reduction of 559 basis points.
Passive Authentication
Customer is not prompted to authenticate. This transaction type
provides full 3-D Secure benefits when passive authentication is
completed.
Risk-Based Banks
Card-issuing bank uses risk-based authentication. The likely
outcome is the customer is not challenged to enter credentials. Most
authentications proceed without customer interaction. This
transaction type provides full 3-D Secure benefits.
Active Authentication
Customer is prompted to authenticate.
Payer Authentication Using the SCMP API | June 2014
118
Appendix G
Table 75
Rules-Based Payer Authentication
Rules-Based Payer Authentication Transaction Types
Transaction Type
Description
Activation During Shopping
Customer is prompted to enroll in a 3-D Secure card authentication
program. This transaction type provides full 3-D Secure benefits.
API Replies
Note
By default, API replies that are specifically associated with rules-based Payer
Authentication are turned off. Contact CyberSource Customer Support to
enable these API replies 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)
Risk-Based Bank Transactions
When a transaction involves a card-issuing bank that supports risk-based authentication,
you may receive the following authentication path replies, depending on whether the cardissuing 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 | June 2014
119
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
3-D Secure
Security protocol for online credit card and debit card transactions used by
Verified by Visa, MasterCard SecureCode, American Express SafeKey, and JCB
J/Secure.
A
AAV
Account Authentication Value. Unique 32-character transaction token for a 3-D
Secure transaction. For MasterCard SecureCode, the AAV is named the "UCAF."
For Verified by Visa, 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
Processor that provides credit card processing, settlement, and services to
merchant banks.
ACS
Access Control Server. The card-issuing banks 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 reply to the request to check enrollment. This is where you must send the
"PAReq" so that the customer can be authenticated.
Payer Authentication Using the SCMP API | June 2014
120
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)
ADS
Activation During Shopping. The card issuers ability to ask the cardholder to
enroll in the card authentication service when the merchant posts to the "ACS
URL."
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 "3-D Secure."
API
Application Programming Interface. A specification that can be used by software
components to communicate with each other.
authentication
result
Raw data sent by the card issuer that indicates the status of authentication. It is
not required to pass this data into the authorization.
authorization
A request sent to the card issuing bank that ensures a cardholder has the funds
available on their credit card for a 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 card association fines.
B
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.
C
CAVV
Cardholder Authentication Verification Value. A base64-encoded string sent back
with "Verified by Visa"-enrolled cards that specifically identifies the transaction
with the issuing bank and Visa. Standard for collecting and sending AAV data for
Verified by Visa transactions. See "AAV."
CAVV algorithm
A one-digit reply 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.
Payer Authentication Using the SCMP API | June 2014
121
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 3-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.
D
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 do not participate in a card
authentication service provided by 3-D Secure.
Directory Servers
The Visa and MasterCard servers that are used to verify enrollment in a card
authentication service.
Discover
Primarily, a U.S. card type that starts with a 6. CyberSource identifies Discover
cards with a card type of 004. These cards do not participate in a card
authentication service provided by 3-D Secure.
E
ECI (ECI Raw)
The numeric commerce indicator that indicates to the bank the degree of liability
shift achieved during payer authentication processing.
E-Commerce
Indicator
Alpha character value that indicates the transaction type, such as MOTO or
INTERNET.
Enroll
CyberSource transaction type used for verifying whether a card is enrolled in the
"SecureCode" or "Verified by Visa" service.
H
HTTP
Hypertext Transfer Protocol. An application protocol used for data transfer on the
Internet.
HTTP POST
request
POST is one of the request methods supported by the HTTP protocol. The POST
request method is used when the client needs to send data to the server as part of
the request, such as when uploading a file or submitting a completed form.
Payer Authentication Using the SCMP API | June 2014
122
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)
HTTPS
Hypertext Transfer Protocol combined with SSL/TLS (Secure Sockets Layer/
Transport Layer Security) to provide secure encryption of data transferred over
the Internet.
I
issuer
The bank that issued a credit card.
J
J/Secure
The "3-D 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 "3-D Secure."
Joint e-Commerce
Framework Testing
Formerly known as PIT testing. This is a set of payment integration tests that
simulate realistic scenarios that would have an impact on your business in a
production environment. Each test is designed to ensure that your implementation
of Payer Authentication services processes the data correctly. CyberSource
provides you with a test plan that includes descriptions of expected results. You
must schedule time with your CyberSource contact to review your test results.
These tests may also be called JEF tests.
M
Maestro
A card brand owned by MasterCard that includes several debit card "BIN"s 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, MasterCards 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 ("SecureCode")
provided by "3-D Secure."
Payer Authentication Using the SCMP API | June 2014
123
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 customers specific order. Although
card associations 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."
P
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.
PIT testing
See "Joint e-Commerce Framework Testing."
Payer Authentication Using the SCMP API | June 2014
124
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
R
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
authentication
Risk-based authentication is provided by the card-issuing bank. The card-issuing
bank gathers a cardholders 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.
S
SafeKey
Trademarked name for the American Express card authentication service.
SCMP API
CyberSources legacy name-value pair API that has been superceded by the
"Simple Order API."
SecureCode
Trademarked name for MasterCards card authentication service.
Simple Order API
CyberSources 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."
T
TermURL
Termination URL on a merchants web site where the card-issuing bank posts the
payer authentication response (PARes) message.
U
UCAF
Universal Cardholder Authentication Field. A base64-encoded string sent back
with MasterCard "SecureCode"-enrolled cards that specifically identifies the
transaction with the issuing bank and MasterCard. Standard for collecting and
sending AAV data for MasterCard SecureCode transactions. See "AAV."
Payer Authentication Using the SCMP API | June 2014
125
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
U (Continued)
UCAF collection
indicator
Value of 1 or 2 that indicates whether a MasterCard cardholder has authenticated
themselves or not.
V
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.
Verified by Visa
(VbV) Trademarked name for Visas card authentication service.
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 ("Verified by Visa")
provided by "3-D Secure."
X
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
transactions history.
Payer Authentication Using the SCMP API | June 2014
126
INDEX
Index
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
CAVV 75
Numerics
chargeback protection
subscription payments 23
16- and 19-digit Visa cards 36
check enrollment service 11, 15
credit card, types accepted 67
A
AAV 33, 78
accepted credit card types 67
data storage 100
Access Control Server (ACS) 16
detail report 106
AIBMS
commerce indicator, validation 76
American Express
formal payer authentication implementation
testing 14
SafeKey 11
application results in Business Center 91
Asia, Middle East, and Africa Gateway 74, 77
enrolled card
password 12
enrollment data storage 100
example code
payerAuthEnrollService 80
payerAuthValidateService 84
authentication form from issuing bank 16
authorizations, expired or multiple 23
FDC Germany
commerce indicator, validation 76
Barclays
commerce indicator, validation 76
Barclays, enrollment XID 74
Barclays, validation XID 78
base64 format, converting 23
Brazil transactions (Verified by Visa) 68, 69
C
card authorization with payer authentication 23
Payer Authentication Using the SCMP API | June 2014
issuing bank
authentication form 16
CAVV 75
enrollment check 16
J
J/Secure 11
J/Secure, validation results 60
127
Index
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
JCB
formal payer authentication implementation
testing 14
J/Secure 11
tests 60
JEF tests 14
payer authentication search options 100
payerAuthEnrollService
example code 80
payerAuthValidateService
example code 84
PIT tests, see JEF tests
proofXML storage 100
Maestro
(U.K. domestic) tests 43
formal payer authentication implementation
testing 14
tests 49
Maestro cards
SecureCode 11
MasterCard
formal payer authentication implementation
testing 14
SecureCode 11
reports
detail 106
detail, XML format 107
downloading summary report 102
retention time limit 101
summary 101
risk-based authentication 118
MasterCard Directory Server 15
SafeKey 11
MasterCard SecureCode
validation results 43
SecureCode 11
MasterCard tests 43
storing payer authentication data 94
P
PAReq 16
PAReq and PARes storage 100
settling transactions, time limit 100
Streamline
commerce indicator, validation 76
SCMP API
ECI raw 77
PARes 125
subscription payments, chargeback
protection 23
password
for enrolled card 12
summary report 101
password, enrolled card 16
payer authentication details
enrolled card 94
storage duration 94
unenrolled card 97
payer authentication report
comparing to payment reports 105
frequency 101
interpreting 103
transactions reported 101
Payer Authentication Using the SCMP API | June 2014
testing 31
tests
JCB J/Secure 60
Maestro cards 49
MasterCard cards 43
Visa cards 36
transaction details
enrollment check information 91
128
Index
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
transaction history, retention time limit 101
transaction search 91
authenticated card 96
enrolled card 91
unenrolled card 97
U
UCAF data 33
unenrolled card, payer authentication details 97
V
validate authentication service 11, 17
vbv_attempted 36
Verified by Visa
Brazilian transaction requirements 68, 69
validation results 36
Visa
formal payer authentication implementation
testing 14
Verified by Visa 11
Visa card tests 36
Visa Directory Server 15
Visa Vale Alimentacao (VSAVA) 69
Visa Vale Refeicao (VSAVR) 69
Visa, 16- and 19-digit cards 36
X
XID 74
XID, validate 78
XML report sample 116
Payer Authentication Using the SCMP API | June 2014
129
You might also like
- Developer Center - Orbital To Stratus Test ConditionsNo ratings yetDeveloper Center - Orbital To Stratus Test Conditions16 pages
- Owasp Api Security Top 10 Cheat Sheet A4No ratings yetOwasp Api Security Top 10 Cheat Sheet A43 pages
- Enterprise Chargeback Management EguideNo ratings yetEnterprise Chargeback Management Eguide17 pages
- EMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDFNo ratings yetEMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDF154 pages
- Prepaid Card Processing With A Platform-as-a-Service (PaaS) Delivery ModelNo ratings yetPrepaid Card Processing With A Platform-as-a-Service (PaaS) Delivery Model21 pages
- Credit Card Chargebacks and Friendly Fraud: Apoorv JoshiNo ratings yetCredit Card Chargebacks and Friendly Fraud: Apoorv Joshi6 pages
- Unified Standard For Quick Response Code - QRNo ratings yetUnified Standard For Quick Response Code - QR45 pages
- ATMIA - Next-Gen ATM Blueprint v1.5 Public Draft, Jun-2019No ratings yetATMIA - Next-Gen ATM Blueprint v1.5 Public Draft, Jun-20191 page
- M/Chip Functional Architecture For Debit and Credit: Applies To: SummaryNo ratings yetM/Chip Functional Architecture For Debit and Credit: Applies To: Summary12 pages
- As 2805.14.2-2009 Electronic Funds Transfer - Requirements For Interfaces Secure Cryptographic Devices (RetaiNo ratings yetAs 2805.14.2-2009 Electronic Funds Transfer - Requirements For Interfaces Secure Cryptographic Devices (Retai8 pages
- Oracle FLEXCUBE Direct Banking Parameter SheetNo ratings yetOracle FLEXCUBE Direct Banking Parameter Sheet200 pages
- Visa Canada Acquiring Network Assessment FeesNo ratings yetVisa Canada Acquiring Network Assessment Fees2 pages
- CAF 03 ExaminableSupplement BusinessLaw2015No ratings yetCAF 03 ExaminableSupplement BusinessLaw201515 pages
- Payment Processing KPI Library - BlueSnap PDFNo ratings yetPayment Processing KPI Library - BlueSnap PDF14 pages
- Kal Atm Software Trends and Analysis 2014 PDFNo ratings yetKal Atm Software Trends and Analysis 2014 PDF61 pages
- Integrated Circuit Card Specifications For Payment Systems: Cardholder, Attendant, and Acquirer Interface RequirementsNo ratings yetIntegrated Circuit Card Specifications For Payment Systems: Cardholder, Attendant, and Acquirer Interface Requirements104 pages
- Visa Approved Dual Chip Cards - January 2022No ratings yetVisa Approved Dual Chip Cards - January 202223 pages
- The Globetrotter'S Guide To: Multi-Currency Travel CardNo ratings yetThe Globetrotter'S Guide To: Multi-Currency Travel Card22 pages
- CARDTEK Ocean Payment Processing SolutionNo ratings yetCARDTEK Ocean Payment Processing Solution39 pages
- Pin Managment For IC Card Member Implementation GuideNo ratings yetPin Managment For IC Card Member Implementation Guide66 pages
- 2025-Global-Payments-PaymentTrends-Annual-Report_FinalNo ratings yet2025-Global-Payments-PaymentTrends-Annual-Report_Final55 pages
- Heartland Newsroom: What Is Interchange, and Why Is It Important To You?No ratings yetHeartland Newsroom: What Is Interchange, and Why Is It Important To You?2 pages
- Verified by Visa Acquirer Merchant Implementation GuideNo ratings yetVerified by Visa Acquirer Merchant Implementation Guide114 pages
- Chapter 1 Digital Systems and Binary NumbersNo ratings yetChapter 1 Digital Systems and Binary Numbers13 pages
- EV 11.0 SQL Best Practices Guide DOC6863No ratings yetEV 11.0 SQL Best Practices Guide DOC686354 pages
- CSC2411 - Linear Programming and Combinatorial Optimization Lecture 1: Introduction To Optimization Problems and Mathematical ProgrammingNo ratings yetCSC2411 - Linear Programming and Combinatorial Optimization Lecture 1: Introduction To Optimization Problems and Mathematical Programming9 pages
- T4020-T5020-Z5020 Gauge Configuration - Step by Step Guide Rev.01No ratings yetT4020-T5020-Z5020 Gauge Configuration - Step by Step Guide Rev.018 pages
- Unix and AIX Commands For Basis and Oracle DBA ConsultantNo ratings yetUnix and AIX Commands For Basis and Oracle DBA Consultant11 pages
- Zenoss Core 4 Event Architecture: Jane CurryNo ratings yetZenoss Core 4 Event Architecture: Jane Curry47 pages
- Support Vector and Multilayer Perceptron Neural Networks Applied To Power Systems Transient Stability Analysis With Input Dimensionality ReductionNo ratings yetSupport Vector and Multilayer Perceptron Neural Networks Applied To Power Systems Transient Stability Analysis With Input Dimensionality Reduction6 pages
- Denormalization in Databases: Recommended PostsNo ratings yetDenormalization in Databases: Recommended Posts1 page
- GE6161 Computer Practices Laboratory LTPC 0 0 3 2 List of ExperimentsNo ratings yetGE6161 Computer Practices Laboratory LTPC 0 0 3 2 List of Experiments2 pages
- Generating HDL Code Using The GUI - Introduction To HDL Code..No ratings yetGenerating HDL Code Using The GUI - Introduction To HDL Code..9 pages
- Control Your Arduino From Your PC With The QT GuiNo ratings yetControl Your Arduino From Your PC With The QT Gui10 pages
- Autocad 3D Modeling-Tips and Tricks: Learning ObjectivesNo ratings yetAutocad 3D Modeling-Tips and Tricks: Learning Objectives14 pages
- Lesson Ten: Introduction To ProgrammingNo ratings yetLesson Ten: Introduction To Programming75 pages
- Developer Center - Orbital To Stratus Test ConditionsDeveloper Center - Orbital To Stratus Test Conditions
- EMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDFEMV v4.3 Book 4 Other Interfaces 20120607062305603-1 PDF
- Prepaid Card Processing With A Platform-as-a-Service (PaaS) Delivery ModelPrepaid Card Processing With A Platform-as-a-Service (PaaS) Delivery Model
- Credit Card Chargebacks and Friendly Fraud: Apoorv JoshiCredit Card Chargebacks and Friendly Fraud: Apoorv Joshi
- ATMIA - Next-Gen ATM Blueprint v1.5 Public Draft, Jun-2019ATMIA - Next-Gen ATM Blueprint v1.5 Public Draft, Jun-2019
- M/Chip Functional Architecture For Debit and Credit: Applies To: SummaryM/Chip Functional Architecture For Debit and Credit: Applies To: Summary
- As 2805.14.2-2009 Electronic Funds Transfer - Requirements For Interfaces Secure Cryptographic Devices (RetaiAs 2805.14.2-2009 Electronic Funds Transfer - Requirements For Interfaces Secure Cryptographic Devices (Retai
- Integrated Circuit Card Specifications For Payment Systems: Cardholder, Attendant, and Acquirer Interface RequirementsIntegrated Circuit Card Specifications For Payment Systems: Cardholder, Attendant, and Acquirer Interface Requirements
- The Globetrotter'S Guide To: Multi-Currency Travel CardThe Globetrotter'S Guide To: Multi-Currency Travel Card
- Pin Managment For IC Card Member Implementation GuidePin Managment For IC Card Member Implementation Guide
- 2025-Global-Payments-PaymentTrends-Annual-Report_Final2025-Global-Payments-PaymentTrends-Annual-Report_Final
- Canada's Role in the Payment Processing IndustryFrom EverandCanada's Role in the Payment Processing Industry
- Payment processor Complete Self-Assessment GuideFrom EverandPayment processor Complete Self-Assessment Guide
- Heartland Newsroom: What Is Interchange, and Why Is It Important To You?Heartland Newsroom: What Is Interchange, and Why Is It Important To You?
- Verified by Visa Acquirer Merchant Implementation GuideVerified by Visa Acquirer Merchant Implementation Guide
- CSC2411 - Linear Programming and Combinatorial Optimization Lecture 1: Introduction To Optimization Problems and Mathematical ProgrammingCSC2411 - Linear Programming and Combinatorial Optimization Lecture 1: Introduction To Optimization Problems and Mathematical Programming
- T4020-T5020-Z5020 Gauge Configuration - Step by Step Guide Rev.01T4020-T5020-Z5020 Gauge Configuration - Step by Step Guide Rev.01
- Unix and AIX Commands For Basis and Oracle DBA ConsultantUnix and AIX Commands For Basis and Oracle DBA Consultant
- Support Vector and Multilayer Perceptron Neural Networks Applied To Power Systems Transient Stability Analysis With Input Dimensionality ReductionSupport Vector and Multilayer Perceptron Neural Networks Applied To Power Systems Transient Stability Analysis With Input Dimensionality Reduction
- GE6161 Computer Practices Laboratory LTPC 0 0 3 2 List of ExperimentsGE6161 Computer Practices Laboratory LTPC 0 0 3 2 List of Experiments
- Generating HDL Code Using The GUI - Introduction To HDL Code..Generating HDL Code Using The GUI - Introduction To HDL Code..
- Autocad 3D Modeling-Tips and Tricks: Learning ObjectivesAutocad 3D Modeling-Tips and Tricks: Learning Objectives