CyberSource Payer Authentication

(1)

Using the Simple Order API

(2)

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

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

(3)

Recent Revisions to This Document

7 About This Guide

8

Audience 8

Purpose 8

Scope 8

Conventions 9

Note and Important Statements 9

Text and Command Conventions 9

Chapter 1 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

(4)

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 27

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

31

Testing Process 31 Enrollment Check 31 Authentication Validation 33 Expected Results 34 Test Cases 36 Verified by Visa 36 MasterCard SecureCode 45 Maestro SecureCode 54

American Express SafeKey 59

JCB J/Secure 64

Appendix A

API Fields

70

Formatting Restrictions 70

Data Type Definitions 70

Request Fields 71

Reply Fields 74

(5)

Appendix C

Request and Reply Examples

85

Check Enrollment 85

Transaction Reply for Visa with Verified by Visa 86

Transaction Reply for MasterCard with SecureCode 87

Transaction Reply for JCB with J/Secure 88

Validate Authentication 89

Transaction Reply for Visa with Verified by Visa 89

Transaction Reply for MasterCard with SecureCode 90

Transaction Reply for JCB with J/Secure 90

ProofXML 91

Appendix D

Web Site Modification Reference

92

Web Site Modification Checklist 92

3-D Secure Services Logos 93

Informational Message Examples 94

Appendix E

Payer Authentication Transaction Details in the Business Center

95

Searching for Payer Authentication Details 95

Enrolled Card 95

Enrollment Check 95

Authentication Validation 100

Card Not Enrolled 101

Payer Authentication Details 101

Transaction Details 103

Payer Authentication Search 104

(6)

Appendix F

Payer Authentication Reports

105

Payer Authentication Summary Report 105

Downloading the Report 106

Matching the Report to the Transaction Search Results 107

Interpreting the Report 108

Comparing Payer Authentication and Payment Reports 109

Payer Authentication Detail Report 110

Report 111 <Result> 111 <PayerAuthDetail> 111 <ProofXML> 113 <VEReq> 114 <VERes> 115 <PAReq> 116 <PARes> 117 <AuthInfo> 119 Examples 120

Failed Enrollment Check 120

Successful Authentication 121

Appendix G

Rules-Based Payer Authentication

122

Available Rules 122

API Replies 123

Bypassed Authentication Transactions 123

Risk-Based Bank Transactions 124

Glossary

125

(7)

Recent Revisions to This

Document

Release Changes

September 2015 Updated URL for testing. See "Phase 2: Implementation," page 20.

August 2015  Added new Visa and MasterCard test cases for passive authentication (RIBA_PASS) and risk-based bank authentication (RIBA), see "Test Cases," page 36.

 Added the Authentication Type to test cases, see "Test Cases," page 36.

 Updated the MasterCard reply fields, see "MasterCard SecureCode," page 45.

 Added information about the rules-based Payer Authentication feature. See "Rules-Based Payer Authentication," page 122.

December 2014 This revision contains only editorial changes and no technical updates.

October 2014 Corrected the returned ECI value in the authentication path diagram for Visa, American Express, and JCB. In the path where a customer is forced to enroll their card, they click Exit, and PAResStatus=N, ECI=06 are returned. The ECI value has been corrected from 06 to 07. See Figure 6, page 34.

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 "Rules-Based Payer Authentication," page 122.

(8)

Audience

This guide is written for application developers who want to use the CyberSource Simple Order 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 Simple Order API to integrate Payer Authentication services with your order management system. It does not describe how to get started using the Simple Order API nor does it explain how to use CyberSource services other than Payer Authentication. For that information, see "Related Documents," page 10.

(9)

Conventions

Note and Important Statements

Text and Command Conventions

Note

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

Important

An Important statement contains information essential to successfully completing a task or learning a concept.

Convention Usage

bold  Field and service names in text. For example: Include the ics_applications field.

 Items that you are instructed to act upon. For example: Click Save.

italic  Filenames and pathnames. For example:

Add the filter definition and mapping to your web.xml file.

 Placeholder variables for which you supply particular values.

monospace  XML elements.

 Code examples and samples.

(10)

Customer Support

For support information about any CyberSource service, visit the Support Center at:

(11)

1

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

(12)

Figure 1 Payer Authentication Process Overview

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 customer’s 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.

Your customer places an order on your Web

site. Check Enrollment service Card Authorization service Is the card enrolled? No

Yes Is the password

authenticated?

Yes

Validate Authentication service The customer enters

the authentication password.

You must refuse the card and request other

form of payment. No

(13)

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. Payment card company rules might vary over time and across geographical regions. CyberSource recommends that you contact your merchant account provider to find out exactly how to interpret chargeback requirements and which chargeback protections are offered.

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.

(14)

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:

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.

Table 1 Merchant Information Required for Payer Authentication Services Information Description

About your company  Your CyberSource merchant ID.

 URL of your company’s web site, for example:

http://www.example.com

 Two-character ISO code for your country. Bank Information  Name of your bank acquirer.

 Complete name and address of your bank contact, including email address.

Visa, MasterCard, Maestro, American Express, and JCB Information

Acquirer merchant ID

Information provided by your bank acquirer about each payment card company for which you are configured:

 6-digit BIN numbers.

 Acquirer merchant ID: merchant ID assigned by your acquirer.

(15)

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 Order Management System Your Customer

Card Association's

Directory Server Customer's card-issuing

Bank PAReq 1 2 3 4 5 Customer's Password 6 7 8 CyberSource Check Enrollment Service Yes Enrollment Authentication PARes No ACS URL PAReq ACS URL 9

(16)

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

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

6 If the card is enrolled, you send the PAReq message to the ACS URL of the card-issuing bank to request authentication.

7 The customer’s web browser displays the card-issuing bank’s authentication dialog box where the customer enters their password for the card.

8 The card-issuing bank replies to your order management system with a PARes

message that contains the results of the authentication.

9 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

(17)

Validate Authentication

The Validate Authentication service verifies and interprets the payment authentication response message returned by the card-issuing bank.

The steps in the following figure resume the process started in the "Enrollment and Authentication Process," page 15.

Figure 3 Validate Authentication Process

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

Important

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.

Your Order Management System Customer

10

Yes No

11

CyberSource Validation Service

12

PARes

9 Validation

PARes

(18)

2

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.

(19)

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

(20)

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 chapter’s 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 92.

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. For test transactions, send requests to the test URL:

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

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

10Confirm with your business contact or project manager that the code is complete (written and tested).

(21)

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 Developer Tasks 1 Provide to the merchant’s

developer team a test document that describes the accreditation tests and the expected test results.

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.

(22)

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:

 Visa Login ID

 Visa password

 MasterCard Merchant ID 1 CyberSource primary support

team asks your acquiring bank to upload data to the Directory Servers.

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 Plug-in (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.

(23)

Implementing Payer

Authentication Services

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: payerAuthValidateReply_cavv

 AAV: payerAuthValidateReply_ucafAuthenticationData

 XID: payerAuthEnrollReply_xid and payerAuthValidateReply_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 customer’s authentication is valid.

 Multiple Authorizations: In these cases, you need to include in subsequent

Warning

Do not use Payer Authentication services for subscription payments because you cannot receive chargeback protection for these transactions.

(24)

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

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 Fields," page 71. 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 (reason code 100 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:

Important

Before requesting payerAuthEnrollService, 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.

Identifiers Enrollment Check Reply Fields Card Authorization Request Fields

E-commerce indicator payerAuthEnrollReply_ commerceIndicator ccAuthService_ commerceIndicator Collection indicator (MasterCard only) payerAuthEnrollReply_ ucafCollectionIndicator ucaf_collectionIndicator

Result of the enrollment check for Asia, Middle East, and Africa Gateway

payerAuthEnrollReply_veresEnrolled ccAuthService_ veresEnrolled

(25)

B. Interpreting the Reply

The replies are similar for all card types. See Appendix C, "Request and Reply Examples," on page 85 for examples of enrollment replies.

Enrolled Cards

You receive reason code 475 if the customer’s card is enrolled in a payer authentication program:

If you receive this reply, you can proceed to validate authentication.

Cards Not Enrolled

You receive reason code 100 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. decision=REJECT reasonCode=475 payerAuthEnrollReply_reasonCode=475 decision=Accept reasonCode=100 payerAuthEnrollReply_reasonCode=100

(26)

Step 2: Authenticating Enrolled Cards

When you have verified that a customer’s card is enrolled in a card authentication program, you must redirect the customer to the URL of the card-issuing bank’s 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

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 bank’s 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-issuer’s authentication form or the activation form, and text that describes the process to customers.

if card is enrolled == TRUE Then

variable acsURL = <acsURL reply field> variable paReq = <paReq reply field>

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

(27)

 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

click the Back button or refresh the page. Otherwise, this transaction may be interrupted.”

Payment card companies 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 93. 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:

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.

 MD

Merchant data, which is included only if you provided it in the outgoing page when you sent the enrollment authentication request (PAReq).

variable paRes = <signedPARes reply field>

Important

The field name has a lowercase “a” (PaRes), but the message name has an uppercase “A” (PARes).

(28)

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 customer’s 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 businessRules_ignoreValidateResult request field is set to yes and you request the validation and card authorization services together, the authorization service attempts to authorize the customer’s card even if validation fails. Therefore, CyberSource recommends that you use this request field only when using other services and fraud tools.

(29)

 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

(For the Asia, Middle East, and African Gateway and ATOS only)

payerAuthValidateReply_ paresStatus

ccAuthService_paresStatus

XID payerAuthValidateReply_xid ccAuthService_xid

E-commerce indicator payerAuthValidateReply_ commerceIndicator

ccAuthService_ commerceIndicator

ECI raw PayerAuthValidateReply_

eciRaw

ccAuthService_eciRaw

CAVV (Visa and American Express only)

PayerAuthValidateReply_cavv ccAuthService_cavv

CAVV algorithm (ATOS only)

payerAuthValidateReply_ cavvAlgorithm

ccAuthService_cavvAlgorithm

AAV (MasterCard only. Known as UCAF) payerAuthValidateReply_ ucafAuthenticationData ucaf_authenticationData Collection indicator (MasterCard only) payerAuthValidateReply_ ucafCollectionIndicator ucaf_collectionIndicator 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).

(30)

B. Interpreting the Reply

Proceed with the order according to the validation response that you receive. The replies are similar for all card types:

 Success:

You receive the reason code 100, and other service requests, including authorization, are processed normally.

 Failure:

You receive reason code 476 indicating that the authentication failed, so the other services in your request are not processed. If you want to process the other services or fraud tools despite the failure, set the request field businessRules_

ignoreValidateResult to true.

 Error:

If you receive an error from the payment card company, process the order according to your business rules. If the error occurs frequently, report it to Customer Support. If you receive a CyberSource system error, determine the cause, and proceed with card authorization only if appropriate.

To verify that the enrollment and validation checks are for the same transaction, ensure that the XID in the enrollment check and validation 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.

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.

(31)

3

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 card’s expiration date set as follows: the month of December and the current year plus two. For example, for 2015, use 2017. 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.

Note

To see the authentication window, you must enable your browser to display popup windows.

(32)

Figure 4 Verified by Visa Authentication Window

1 Your merchant ID.

2 Last four digits of the card number. 3 Password to enter in the below text box. 4 Default user name for all tests.

5 This Exit link enables the customer to prevent the authentication process. Depending on the user’s action, two results are possible:

 If the user submits the password for the enrolled card, you receive the URL of the

Access Control Server (ACS) where the customer can be authenticated.

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

(33)

Table 6 lists the reply fields used in the test cases.

Table 6 Reply Fields Used in the Enrollment Check Test Cases

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

ACS URL payerAuthEnrollReply_acsURL

E-commerce indicator payerAuthEnrollReply_commerceIndicator

ECI payerAuthEnrollReply_eci

PAReq payerAuthEnrollReply_paReq

proofXML payerAuthEnrollReply_proofXML

Reason code payerAuthEnrollReply_reasonCode

VERes enrolled payerAuthEnrollReply_veresEnrolled

XID payerAuthEnrollReply_xid

Names Used in Test Cases API Field

Authentication result payerAuthValidateReply_authenticationResult E-commerce indicator payerAuthValidateReply_commerceIndicator AAV (MasterCard only) payerAuthValidateReply_ucafAuthenticationData CAVV (Visa only) payerAuthValidateReply_cavv

Collection indicator payerAuthValidateReply_ucafCollectionIndicator

ECI payerAuthValidateReply_eci

PARes status payerAuthValidateReply_

authenticationStatusMessage

Reason code payerAuthValidateReply_reasonCode

(34)

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

(35)

(36)

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 Validate Authentication Reply

Authentication Result

ECI Commerce Indicator

Reason Code

Success Successful authentication. 0 05 vbv 100

Recorded attempt to authenticate. 1 06 vbv_ attempted 100 Failure (Customer not responsible)

System error that prevents the completion of authentication: you can proceed with authorization, but there is no liability shift.

6 a — b 100

Issuer unable to perform authentication.

6 07 internet 100

No response from the Directory Servers or Issuer because of a problem. 07 internet vbv_failure (processors: AIBMS, Barclays, Streamline, or FDC Germany) Invalid PARes. -1 — — 476 Failure (Customer responsible) Authentication failed or cardholder did not complete authentication.

If the authentication fails, Visa requires that you do not accept the card. You must ask the customer to use another payment method.

9 — — 476

a. The eci value can vary depending on the reason for the failure. b. A dash (—) indicates that the field is blank or absent.

(37)

Test Case 1: Verified by Visa Card Enrolled: Successful Authentication

Test Case 2: Verified by Visa Card Enrolled: Successful Authentication But Invalid PARes

Card Number 4000000000000002 4000000000000000022

With authentication window

4000000000000119 Without authentication window Auth. Type Active authentication

Results Check Enrollment Validate Authentication

Summary Reason code 475 Reason code 100

The cardholder is enrolled in Payer Authentication. Please authenticate before proceeding with authorization.

ics_pa_validate service was successful.

Details ACS URL URL Authentication result 0

PAReq PAReq value CAVV CAVV value

proofXML proofXML value E-commerce indicator vbv

VERes enrolled Y ECI 05

XID XID value PARes status Y

XID XID value

Action 1 Add the signed PARes to the Validate Authentication request.

2 Ensure that the XID from the enrollment check matches that from the authentication validation. 3 Add the CAVV and ECI values to your authorization request.

Card Number 4000000000000010 4000000000000000071

Auth. Type Active authentication

We encountered a Payer Authentication problem: PARes signature digest value mismatch. PARes message has been modified.

(38)

Test Case 3: Verified by Visa Card Enrolled: Attempts Processing Card Number 4000000000000101

4000000000000000063 4000000000000127

Without authentication window With authentication window

Card enrollment option during purchase process Auth. Type Activation during shopping

Details ACS URL URL value Authentication result 1

proofXML proofXML value E-commerce indicator vbv_attempted

XID XID value PARes status A

XID XID value

Action If you request Validate Authentication and authorization services separately, follow these steps: 1 Add the signed PARes to the Validate Authentication request.

If you request the Validate Authentication and authorization services together, the process described above occurs automatically. Test card 4000000000000127 enables you to reproduce the process by which the customer enrolls the card during the purchase. If the card is not enrolled, a card enrollment option windows appears in the customer’s browser after the enrollment check. The customer can activate the card at that time or later. In both cases, the card is authenticated, and validation is successful.

(39)

Test Case 4: Verified by Visa Card Enrolled: Incomplete Authentication

Test Case 5: Verified by Visa Card Enrolled: Unsuccessful Authentication Card Number 4000000000000036

4000000000000000055 Auth. Type Active authentication

 Issuer unable to perform authentication.

 ics_pa_validate service was successful.

Details ACS URL URL value Authentication result 6 PAReq PAReq value E-commerce indicator internet

proofXML proofXML value ECI 07

VERes enrolled Y PARes status U

XID XID value XID XID value

Action Ask the customer for another form of payment, or submit the transaction. No liability shift.

Card Number 4000000000000028 4000000000000000048

Summary Reason code 475 Reason code 476

 User failed authentication.

 Payer cannot be authenticated.

PAReq PAReq value PARes status N

proofXML proofXML value XID XID value

VERes enrolled Y

(40)

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

Test Case 7: Verified by Visa Card Enrolled: Unavailable Authentication Card Number 4000008531947799

 Customer prevents authentication.

VERes enrolled Y

XID XID value

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

Card Number 4000000000000069 4000000000000000014 Auth. Type Non-participating bank

Summary Reason code 100

ics_pa_enroll service was successful. Details E-commerce indicator internet

proofXML proofXML value

VERes enrolled U

(41)

Test Case 8: Verified by Visa Card Enrolled: Authentication Error

Test Case 9: Verified by Visa Card Not Enrolled Card Number 4000000000000093

4000000000000000006 Auth. Type Active authentication

We encountered a Payer Authentication problem: Error Processing PARes.

Details ACS URL URL value E-commerce indicator internet

PAReq PAReq value ECI 07

VERes enrolled Y

XID XID value

Action Ask the customer for another form of payment. No liability shift.

Card Number 4000000000000051 4000000000000000030 Auth. Type Non-participating bank

ics_pa_enroll service was successful. Details E-commerce indicator vbv_attempted

ECI 06

VERes enrolled N

(42)

Test Case 10: Verified by Visa Enrollment Check: Time-Out

Test Case 11: Verified by Visa Enrollment Check Error Card Number 4000000000000044

Auth. Type Non-participating bank

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

Card Number 4000000000000085 4000000000000077

Error response

Incorrect Configuration: Unable to Authenticate Auth. Type Non-participating bank

VERes enrolled U

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

(43)

Test Case 12: Verified by Visa Enrollment RIBA_PASS

Test Case 13: Verified by Visa Enrollment RIBA_PASS: Unsuccessful Authentication

Card Number 4000180000000002 Auth. Type Passive authentication

XID XID value

(44)

Test Case 14: Verified by Visa Enrollment RIBA

Test Case 15: Verified by Visa Enrollment RIBA: Unsuccessful Authentication Card Number 4000260000000002 With authentication window

Auth. Type Risk-based bank

XID XID value

Card Number 4000260000000028 With authentication window Auth. Type Risk-based bank

Results Reason code 475 Reason code 476

Summary The cardholder is enrolled in Payer Authentication. Please authenticate before proceeding with authorization.

ACS URL URL value Authentication result 9

Details PAReq PAReq value PARes status N

VERes enrolled Y

XID XID value

(45)

MasterCard SecureCode

Table 9 Possible Values for MasterCard and Maestro SecureCode Reply Fields

Test Case 16: MasterCard SecureCode Card Enrolled: Successful Authentication Result and Interpretation payerAuthValidateReply_

authentication Result ucafCollection Indicator commerce Indicator reason Code

Success Successful authentication. 0 2 spa 100

Authentication not completed. 1 1 spa 100

Failure (Customer not responsible)

System error (Issuer unable to perform authentication): you cannot authorize this card; no liability shift. 6 1 spa 100 Invalid PARes. -1 0 476 Failure (Customer responsible) Authentication failed or cardholder did not complete authentication.

9 1 – 476

Card Number 5200000000000007 5200000000000114

With authentication window Without authentication window Auth. Type Active authentication

The card is enrolled in Payer Authentication. Please authenticate before proceeding with authorization.

PAReq PAReq value AAV AAV value

proofXML proofXML value Collection indicator 2

VERes enrolled Y E-commerce indicator spa

(46)

Test Case 17: MasterCard SecureCode Card Enrolled: Successful Authentication But Invalid PARes

Card Number 5200000000000015 With authentication window Auth. Type Active authentication

Payer Authentication problem: PARes signature digest value mismatch. PARes message has been modified.

Details ACS URL URL Authentication result -1

PAReq PAReq value XID XID value

VERes enrolled Y

XID XID value

(47)

Test Case 18: MasterCard SecureCode Card Enrolled: Attempts Processing Card Number 5200000000000122

5200000000000106

Card enrollment option during purchase process

Auth. Type Authentication during shopping

proofXML proofXML value E-commerce indicator spa

VERes enrolled Y PARes status A

Action This test card enables you to reproduce the process by which the customer enrolls the card during the purchase. If the card is not enrolled, a card enrollment option windows appears in the customer’s browser after the enrollment check. The customer can activate the card at that time or later. In both cases, the card is authenticated, and validation is successful.

1 Add the signed PARes to the validation request.

2 In the 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.

(48)

Test Case 19: MasterCard SecureCode Card Enrolled: Incomplete Authentication

Test Case 20: MasterCard SecureCode Card Enrolled: Unsuccessful Authentication Card Number 5200000000000031 Without authentication window

 Issuer unable to perform authentication.

PAReq PAReq value Collection indicator 01

proofXML proofXML value E-commerce indicator spa

VERes enrolled Y PARes status U

Action Ask the customer for another form of payment, or submit the transaction. Liability shift.

Card Number 5200000000000023 With authentication window Auth. Type Active authentication

 User failed authentication

 Payer could not be authenticated.

VERes enrolled Y XID XID value

XID XID value

(49)

Test Case 21: MasterCard SecureCode Card Enrolled: Unsuccessful Authentication (Customer Exited)

Test Case 22: MasterCard SecureCode Card Enrolled: Unavailable Authentication Card Number 5641821000010028

 Customer prevents authentication.

VERes enrolled Y

XID XID value

Card Number 5200000000000064 Auth. Type Active authentication

ics_pa_enroll service was successful. Details Collection indicator 1

E-commerce indicator spa

VERes enrolled U

(50)

Test Case 23: MasterCard SecureCode Card Enrolled: Authentication Error

Test Case 24: MasterCard SecureCode Card Not Enrolled Card Number 5200000000000098 Without authentication window

We encountered a Payer Authentication problem: Error Processing PARes.

Details ACS URL URL value Collection indicator 1

PAReq PAReq value E-commerce indicator internet

VERes enrolled Y

XID XID value

Action Ask the customer for another form of payment. No liability shift.

Card Number 5200000000000056 Auth. Type Non-participating bank

VERes enrolled N Action Submit the transaction.

(51)

Test Case 25: MasterCard SecureCode Enrollment Check Time-Out

Test Case 26: MasterCard SecureCode Enrollment Check Error Card Number 5200000000000049

Action After 10 – 12 seconds, proceed with the authorization message. No liability shift.

Card Number 5200000000000080 Auth. Type Active authentication

VERes enrolled U

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

(52)

Test Case 27: MasterCard SecureCode RIBA_PASS

Test Case 28: MasterCard SecureCode RIBA_PASS: Unsuccessful Authentication Card Number 5200180000000007

Auth. Type Passive authentication

XID XID value

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.

VERes enrolled Y XID XID value

XID XID value

(53)

Test Case 29: MasterCard SecureCode RIBA

Test Case 30: MasterCard SecureCode RIBA: Unsuccessful Authentication Card Number 5200260000000007 With authentication window

Auth. Type Risk-based bank

XID XID value

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.

Card Number 5200260000000023 With authentication window Auth. Type Risk-based bank