activation guide: consumer authentication guide: consumer authentication ... more information about...

Activation Guide: Consumer Authentication (March 23, 2017) (Version 5.0.0)

Cardinal: One Connection to Drive Digital Commerce

Consumer Authentication Activation Guide

2 | P a g e A c t i v a t i o n G u i d e : C o n s u m e r A u t h e n t i c a t i o n ( V e r s i o n 5 . 0 . 0 )

1. INTRODUCTION ............................................................................................................................................................................ 5

2. WHAT HAS CHANGED ................................................................................................................................................................... 5

3. OVERVIEW .................................................................................................................................................................................... 6

3.1 CONSUMER AUTHENTICATION TRANSACTION FLOW .................................................................................................................................... 6 3.1.1 Consumer Authentication Transaction Steps ........................................................................................................................... 6

4. ACTIVATION CHECKLIST ................................................................................................................................................................ 8

5. THIN CLIENT .................................................................................................................................................................................. 8

6. THIN CLIENT ARCHITECTURE ......................................................................................................................................................... 9

7. ACTIVATION NOTES .................................................................................................................................................................... 10

7.1 LOGO PLACEMENT ............................................................................................................................................................................. 10 7.2 CONSUMER AUTHENTICATION INTEGRATION MESSAGING .......................................................................................................................... 11

7.2.1 Pre-Authentication Messaging .............................................................................................................................................. 11 7.2.2 Authentication Result Messaging .......................................................................................................................................... 11

7.3 IMPLEMENTATION CONSIDERATIONS ...................................................................................................................................................... 12 7.3.1 Disable the Submit Button ..................................................................................................................................................... 12 7.3.2 Atomic Actions ....................................................................................................................................................................... 12 7.3.3 Browser Back Button ............................................................................................................................................................. 12 7.3.4 Authorization Settlement Integration ................................................................................................................................... 12

7.4 IVR EXTENSION IMPLEMENTATION (INDIA ONLY) ...................................................................................................................................... 13 7.4.1 IVR Lookup Request ............................................................................................................................................................... 13 7.4.2 IVR Lookup Response ............................................................................................................................................................. 13 7.4.3 Direct Integration .................................................................................................................................................................. 13 7.4.4 Redirect Integration............................................................................................................................................................... 14

7.5 BRAZIL EXTENSIONS LOOKUP REQUEST ................................................................................................................................................... 14

8. FRAMED INLINE AUTHENTICATION WINDOW.............................................................................................................................. 14

9. THIN CLIENT INTEGRATION .......................................................................................................................................................... 15

9.1 LOOKUP MESSAGE INTEGRATION .......................................................................................................................................................... 16 9.1.1 cmpi_lookup Request Message .............................................................................................................................................. 16 9.1.2 Consumer Authentication 2.0 Lookup Request Fields ............................................................................................................ 21 9.1.3 Extension Support for Amex SafeKey Enhanced Lookup Request Fields ............................................................................... 27 9.1.4 Additional ProtectBuy 2.0 Lookup Request Fields .................................................................................................................. 28 9.1.5 Extension Support for Brazil and IVR Lookup Request Fields ................................................................................................ 28 9.1.6 cmpi_lookup Response Message ........................................................................................................................................... 31

9.2 AUTHENTICATE MESSAGE INTEGRATION ................................................................................................................................................. 35 9.2.1 cmpi_authenticate Request Message ................................................................................................................................... 36 9.2.2 cmpi_authenticate Response Message ................................................................................................................................. 37

10. CONFIGURING HIGH AVAILABILITY OPTIONS ............................................................................................................................. 39

11. CONSUMER AUTHENTICATION DECISION TABLE ........................................................................................................................ 40

11.1.1 CONSUMER AUTHENTICATION LOOKUP RESPONSE VALUES ............................................................................................................. 40 11.1.2 CONSUMER AUTHENTICATION AUTHENTICATE RESPONSE VALUES .................................................................................................... 41

APPENDIX A: VERSION CHANGES..................................................................................................................................................... 42

APPENDIX B: 3DS FLOW DIAGRAMS ................................................................................................................................................ 43



CARDINAL CRUISE WEB COMBINED STEPUP ................................................................................................................................................... 43 CARDINAL CRUISE WEB COMBINED FRICTIONLESS .......................................................................................................................................... 44

APPENDIX C: API KEY USAGE ........................................................................................................................................................... 45

APPENDIX D: FIELD LEVEL ENCRYPTION FOR CARDNUMBER ........................................................................................................... 47



Acknowledgements

CardinalCommerce Corporation acknowledges with gratitude the contribution of its associates who developed the Cardinal Payment Authentication Platform.

© 2017 by CardinalCommerce Corporation. All rights reserved.

Trademark Information

CardinalCommerce, Cardinal Centinel Authentication Software for Merchants, and Centinel are trademarks of CardinalCommerce Corporation.

Microsoft is a registered trademark of Microsoft Corporation. Microsoft Internet Explorer is a trademark of the Microsoft Corporation.

Visa is a registered trademark of Visa. Verified by Visa and VbV are trademarks of Visa. MasterCard is a registered trademark of

MasterCard International Incorporated. MasterCard SecureCode and SecureCode are registered trademarks of MastercCard International Incorporated.

JCB is a registered trademark of JCB. JCB J/Secure is a registered trademark of JCB.

Diners Club is a registered trademark of Diners Club International. Diners Club ProtectBuy is a registered trademark of Diners Club International.

American Express is a registered trademark of American Express. American Express SafeKey is a registered trademark of American Express.

Discover is a registered trademark of Discover. Discover ProtectBuy is a registered trademark of Discover.

All other trademarks are the properties of their respective owners.

This manual may not, in whole or in part, be copied, photocopied, reproduced, translated, or converted to any electronic or machine readable form without prior written consent of CardinalCommerce Corporation.

Contact Information

CardinalCommerce Corporation 8100 Tyler Blvd. Suite 100 Mentor, OH 44060 USA www.cardinalcommerce.com

http://www.cardinalcommerce.com/



1. Introduction Welcome to Cardinal Consumer Authentication, we’re excited to get you started on activating your services with us. This guide provides an overview of the Cardinal Centinel Thin Client technology that includes: general integration, testing, and API usage instructions. Integrating the Thin Client supports the current 1.0.2 3-D Secure protocol which supports web specific applications. Connecting to Cardinal Consumer Authentication will enable you to participate in the individual card authentication programs such as: Verified by Visa, MasterCard SecureCode/Identity Check, American Express SafeKey, Discover ProtectBuy, JCB J/Secure, and Diners Club ProtectBuy. This guide will also cover API fields necessary for the new EMVco 2.0 requirements that will support in-app purchasing beginning in 2017. As our solution develops, more information about 2.0 readiness will be available to you via our Developer’s Center located here: https://developer.cardinalcommerce.com/ This document assumes you are familiar with your website and payment processing procedures as well as a proficiency using the technologies and programming languages used by your eCommerce website and non-web based applications.

2. What Has Changed This section describes the most recent changes that have occurred since the last publication of the guide. A listing of previous

version changes can be found in the appendix.

Date Description Version

March 23, 2017 Content updates to reflect 2.0 field requirements and flow diagrams Additional section added for Discover ProtectBuy 2.0 specific lookup request fields Amex SafeKey Extension fields included Api Key Usage section updated with example of SHA-512 and SHA-256

5.0.0

January 24, 2017 Token field name added to Lookup Request ThirdPartyToken field added to Lookup Response Generating a Signature Value example included within Appendix B RecurringFrequency field definition edited to N(4) on cmpi_lookup request

4.36.15

January 5, 2017 Edited field name 3dsVersion to ThreeDSVersion on lookup response Edited ShippingMethod field on lookup request to Required ‘N’ Updated description for ShippingPhone to reference shipping address Added BillingFullName field to the lookup request Added ShippingFullName field to the lookup request

4.35.15

December 27, 2016 Added Appendix C: Field Level Encryption for CardNumber Removed Password field name from cmpi_lookup request message Added character set to the beginning of field sections Edited IvrEncryptionMandatory within the cmpi_lookup response Updated description for CardType field name removing Laser, Solo, and GE Money

UK Card Added description of ECI values to EciFlag on cmpi_lookup and cmpi_authenticate

response ErrorNo field definition edited to (AN)255 on cmpi_lookup response ErrorDesc description edited CountryCode field definition edited to AN(3) MerchantReferenceNumber field added to cmpi_lookup request, cmpi_lookup

response, cmpi_authenticate request, and cmpi_authenticate response RecurringFrequency field definition edited to N(3) on cmpi_lookup request IVR Credential field definition edited from Boolean to AN(128)

4.34.15

https://developer.cardinalcommerce.com/



3. Overview The Verified by Visa, MasterCard SecureCode/Identity Check, American Express SafeKey, Discover ProtectBuy, JCB J/Secure, and Diners Club ProtectBuy authentication programs are based off the 1.0.2 and 2.0 3-D Secure Protocols. The Consumer Authentication transaction is divided into the following 3-D Secure domains.

Issuer Domain: Systems and functions of Card Issuers and Cardholders Card Issuers enroll and activate Consumer Cardholder accounts to participate in the Consumer Authentication programs. The Card Issuer is responsible for authenticating the card holder during the checkout process.

Acquirer Domain: Systems and functions of Acquirers and Merchants Merchants communicate with Centinel to initiate the authentication process. Once authentication is completed, the authentication data is appended to the financial transaction that is sent to the Gateway or Processor.

Interoperability Domain: Systems and functions allowing the Issuer Domain to inter-operate with the Acquirer Domain Centinel communicates with the various directory servers to facilitate the communication between the Cardholder and their Card Issuer. Once the Cardholder is redirected to their Card Issuer, the Cardholder will be prompted for their authentication credentials.

The 3DS Flow Diagrams can be found in Appendix B.

3.1 Consumer Authentication Transaction Flow Below is a Cardinal specific detailed description and diagram of the Consumer Authentication message flow for an Enrolled Consumer, in a web-based environment.

3.1.1 Consumer Authentication Transaction Steps 1. Consumer shops online at Merchant website. At the point of checkout, the Cardholder fills out the checkout form including

the payment details and clicks the 'Buy' button.

2. Based on the payment information, the Merchant, via the Thin Client, passes a Lookup message to Centinel Merchant

Authentication Processing System (MAPS). This message contains all the required information provided by the Cardholder in

order to check the enrollment of the Cardholder.

3. A Verify Enrollment Request (VEReq) message will be sent to the Enrollment Directory Server.

4. The Enrollment Directory Server will send the VEReq to the Cardholders Issuing Bank Access Control Server (ACS) to

determine the enrollment status.

5. The Issuing Bank (ACS) sends the enrollment status to the Processor.

6. The Processor sends a response back through to the Issuing Bank (ACS).

7. The Verify Enrollment Response (VERes) is returned to the Directory Server with the corresponding ACS URL, if applicable.

8. Centinel receives the response from the Directory Server, interprets the response and conditionally creates the Payment

Authentication Request (PAReq) based on the enrollment status. The Lookup response is returned to the Thin Client with an

Enrolled status and conditionally with the PAReq for further authentication processing. 9. Based on the Enrolled value returned on the Lookup response, the Merchant will either redirect the Cardholders browser to

the corresponding Issuing Bank ACS (ACSUrl) or process the authorization transaction as a non-authenticated order. Within the redirect to the ACSUrl, the Merchant specifies a return URL location for the Consumer to be redirected to after authentication completes (TermUrl). The Card Issuer displays the authentication form to the Cardholder. The Cardholder enters their authentication data and initiates the authentication process directly with the ACS. The Issuing Bank ACS authenticates the Cardholder. The authentication result is represented by the Consumer Authentication Response (PARes) generated by the Card Issuer ACS.

Once authentication is completed, the ACS redirects the consumer back to the Merchant website (TermUrl).

The PARes is returned to the Merchant through the Consumer’s web browser. The Merchant receives the PARes value and

initiates the Authenticate message, via the Thin Client, which is sent to the Centinel MAPS for processing. Centinel decrypts

the authentication result (PARes), validates the message format, verifies the digital signatures of the transaction, and stores

the transaction details within the Centinel reporting system. Centinel formats the Authenticate response message and

sends the ECI and CAVV/UCAF data elements on the response back to the Merchant.



10. The Merchant processes the Authenticate response message, extracts the ECI and CAVV/UCAF data values, and processes

the real time authorization transaction by sending the Authorization Request to the Gateway. Note that batch authorization

processing is also permitted.

11. The Gateway sends the Authorization Request to the Processor.

12. The Issuing Bank receives the Authorization Request and provides the Authorization Response which is sent back through to

the Merchant.



4. Activation Checklist

A successful activation is dependent on a few key components. The following checklist is intended to highlight these items and define a clear set of tasks covering installation, integration, and configuration. During the activation process, use this checklist to track progress and address any remaining open items prior to deployment.

Consumer Authentication Activation Checklist

☐ Install the Thin Client on your test and production servers. Refer to the Thin Client Installation Guide included with the Thin Client download for additional information.

☐ Integrate the Thin Client into the eCommerce website to perform the Lookup and Authentication message transactions. Refer to section 9 for integration information.

☐

Modify the Order Management System to ensure that all authorization transactions to the Gateway or Processor include the Authentication data elements (CAVV, XID, and ECI). Without these data elements, the Merchant will not receive the benefits of the Authentication programs.

Refer to your Gateway documentation.

☐

Display the Visa, MasterCard, American Express, Discover ProtectBuy, JCB, and Diners Club "Learn More" logos on the home and checkout pages of your website. These logos alert the Consumer to your participation in the Consumer Authentication programs. These logos can be found in the Thin Client sample code files. In the event they are not available contact your Activation Manager.

☐

Ensure that the website properly notifies the Consumer of the various outcomes of the Authentication

transactions. Verify that the Consumer experience is handled properly.

See the integration samples included with the Thin Client for sample Result messaging.

☐ Educate the customer support staff on the CardinalCommerce Support procedures and Reporting using the Merchant Support Guide.

5. Thin Client To assist Merchants with the activation of our services with their eCommerce website, the Thin Client technology is available to minimize any custom development required by the Merchant. The Thin Client integration enables Merchants to quickly communicate with the CardinalCommerce Application Service Provider (ASP) platform. This communication allows all the changing business rules and configuration information to be managed centrally within the ASP platform. As business rules or payment initiative programs evolve, these modifications are made centrally and do not affect the Merchant's eCommerce website directly. The hosted services minimizes any ongoing maintenance, further allowing Merchants to focus on their business objectives instead of maintaining software. NOTE: The Cardinal Thin Client version number does not correspond to the Cardinal Centinel Authentication Software for Merchant version number. The Thin Client versions available for download will always be the most current version of the Thin Client software. The following Centinel Thin Clients are currently available:

Cold Fusion JSP Microsoft.Net Perl PHP

Included with the Thin Client technology are integration samples. These samples can be used as templates for integration and provide code samples for processing the API messages with the hosted service. The code samples include comments that highlight error handling and general usage examples.



NOTE: If one of the available Thin Clients does not meet your system requirements a direct XML integration solution is available. An XML Integration Guide is available for Merchants who wish to explore this option. In addition to the Thin Client offerings, we work closely with Shopping Cart vendors and Order Management System vendors to develop cartridges that handle all Thin Client integration requirements. If you happen to use a product that can be Centinel enabled through one of these cartridges, then your technical development requirements are minimized. Typically, enabling the Centinel service using a cartridge requires a simple configuration within the product's administration console. NOTE: The available cartridges only support Verified by Visa, American Express SafeKey, MasterCard Secure Code, Discover ProtectBuy, Diners Club ProtectBuy, and JCB J/Secure transaction processing.

6. Thin Client Architecture The Thin Client has a common API for message handling. Each Thin Client exposes methods for request message creation, the sending and receiving of transaction data, and response message interpretation. NOTE: Detailed API information is available for each Thin Client in the Thin Client installation guides.

Request Object Method Description

Add

Adds name/value pairs used to construct the XML messages. Usage: void Add(String name, String Value) Parameters: name – name of the parameter value – value of the parameter Returns: void

SendHTTP

Sends the request message to the Centinel MAPS. MAPS returns a response message. The response message is deserialized into name / value pairs and returned from the method in the form of a Thin Client response object. Usage: ResponseObject SendHTTP(String transactionURL) Parameters: transactionURL – fully qualified transaction URL Returns: ResponseObject NOTE: The various platform versions of the Thin Client may overload this method and allow you to specify optional timeout parameters for the MAPS message communication.



Response Object Method Description

GetValue

Returns the value for a named element returned on the response message. Usage: StringGetValue(String name) Parameters: name – name of the parameter Returns: String value of the name parameter

GetUnparsedResponse

Returns the entire raw XML response message. Useful for debugging purposes. Usage: String GetUnparsedResponse() Parameters: none Returns: String value of the XML response

7. Activation Notes In addition to the API integration to facilitate the Consumer Authentication process, the Merchant must also make some important enhancements to the website to support the Consumer Authentication transaction.

7.1 Logo Placement The Consumer Authentication program "Learn More" logos are required to be placed on the payment details page of the checkout process. The usage guidelines require that each of these logos link to their respective websites to enable the Consumer to learn more about each of the programs. The usage guidelines and "Learn More" links are outlined within the Visa, MasterCard, American Express, Discover, JCB, and Diners Club Merchant Toolkits that are available from your CardinalCommerce Representative.

NOTE: These logos should be linked to the HTML pages provided in the samples and hosted by the Merchant.



7.2 Consumer Authentication Integration Messaging In support of the Consumer Authentication usage guidelines, Merchants must provide a brief message regarding Consumer Authentication to Cardholders on the checkout page. The intention of the messaging is to notify the Cardholder that they may be prompted either to provide their authentication password or possibly be prompted to activate their card in the authentication program. The pre-authentication message is most effective and most likely to be read by Cardholders when placed immediately next to the final order button.

7.2.1 Pre-Authentication Messaging The pre-authentication messaging is intended to provide a further reminder and reassurance to the Cardholder, beyond the

presence of the "Learn More" logos, that the Merchant participants in the respective authentication programs.

NOTE: Any messaging must not state affirmatively that the Cardholder will have an authentication experience, and it should also not

state that the Merchant requires the Cardholder to authenticate themselves.

Sample Message Your card may be eligible or enrolled in Verified by Visa, MasterCard SecureCode,

American Express SafeKey, Discover ProtectBuy, JCB J/Secure, or Diners Club ProtectBuy

Consumer Authentication programs. After clicking the 'Submit Order' button, your Card

Issuer may prompt you for your Consumer Authentication password to complete your

purchase.

NOTE: The Pre-Authentication message should be adjusted to only reference those programs integrated by the Merchant.

The following graph highlights pre-authentication messaging and logo placement on the Commerce checkout page.

7.2.2 Authentication Result Messaging

Merchants must ensure that they account for all possible response scenarios and verify the user experience is handled properly in all cases. These scenarios include successful authentication, failed authentications, signature verification failures, not enrolled cards, as well as others. Each of these possible scenarios are outlined in the Consumer Authentication Test Cases guide.



Authentication Failure Messaging When Merchants receive a failed authentication response value, Merchants must immediately display a message or page to advise the Cardholder that the purchase will not be completed with the credit card information provided. The recommended wording for the failed authentication message is shown below: Sample Message Authentication Failed

Your financial institution has indicated that it could not successfully authenticate

this transaction. To protect against unauthorized use, this card cannot be used to

complete your purchase. You may complete the purchase by selecting another form of

payment.

7.3 Implementation Considerations During the activation process, be sure to address the following items to increase the success of your integration efforts. It is also highly recommended that Merchants review these tasks in the event that any significant changes are made to the checkout process within their website.

7.3.1 Disable the Submit Button It is highly recommended that the final "Buy" button is disabled using JavaScript to limit the impact that a double submit of the

purchase form has on the authentication process. Instances may arise where a double submit may have a negative impact on the

session management within the eCommerce system and prevent authentication from completing successfully.

7.3.2 Atomic Actions Security solutions are only as secure as the weakest link in the transaction chain. The transaction processing sequences are designed

with transaction signature and fraud checks to ensure that the transaction results have not been manipulated. It is important to

carry these strict processing techniques over to the Merchant website to ensure that once the data is returned to the Merchant it is

interpreted and used properly.

Implementing atomic actions within the transaction processing pages will ensure that the results of the authentication and payment

processing are handled properly. Be sure to process the Lookup and Authenticate messages and immediately perform the

recommended action using the response values. Avoid passing the authentication results through hidden form fields or through the

URL as query string parameters. Passing sensitive data using these techniques can be easily manipulated by the Consumer.

7.3.3 Browser Back Button Ensure that your integration handles unexpected user behaviors gracefully, specifically back button activity. The use of session

checks at various points throughout the authentication flow can prevent an authenticated transaction from re-entering the

authentication processing flow subsequent times. Testing and handling these cases will lead to an optimal checkout experience for

your Consumers.

7.3.4 Authorization Settlement Integration The Consumer Authentication process generates additional data elements (CAVV, ECI, XID) that MUST be sent to the Gateway or Processor on the authorization request (CAVV, ECI and, optionally XID). For some Gateways and Processors the settlement request may also require the ECI value to be appended to the settlement transaction. The presence of these values on the authorization and settlement transactions will determine the protection or benefit that will be provided to the Merchant. Refer to your Gateway vendor's documentation regarding how to pass the authentication data elements to various Gateways. It is highly recommended that each Merchant confirm that their Gateway or Processor is properly receiving these data elements once activation is completed.



7.4 IVR Extension Implementation (India only) There are two basic ways to integrate the IVR extensions, the direct method and the redirect method. The cmpi_lookup message for both methods is the same, the difference lies with how the Merchant plans on collecting the authentication details and passing this information to CardinalCommerce. A direct integration is designed for automated systems where a program takes the Consumers authentication details, whereas the redirect method is used when a human is going to take the Consumer's authentication details. For more information on what IVR is, or test cases for IVR, contact your Cardinal Activation Manager.

7.4.1 IVR Lookup Request To use IVR, additional fields are required to be passed in on the standard 3DS Lookup request. Omission of these fields will result in

IVR not being executed on the request. Refer to section 9.1.1 of this guide for details on these fields.

Additional required fields on cmpi_lookup request:

MobileIdFormat

MobileId

PareqChannel

ShoppingChannel

AuthenticationChannel

TtpCredential (Optional)

NOTE: As of the publication of this manual the TTP functionality of the IVR program has not been adopted by any ACS. The TTP

functionality has been included for completeness but may not be used.

7.4.2 IVR Lookup Response In the event of a valid IVR request additional fields will be included on the response. These values give the Merchant detailed

information on the IVR transaction and in some cases require the Merchant to do additional processing. Refer to section 9.1.2 for

detailed information on these response fields.

Additional required fields on cmpi_lookup response:

IvrLabel

IvrPrompt

IvrStatusMessage

IvrEncryptionMandatory

IvrEncryptionKey

IvrEncryptionType

IvrEnabledMessage

NOTE: In the event the IvrEncryptionMandatory flag is returned true, the Merchant is expected to encrypt the 3DS credential and

pass this encrypted value on the cmpi_authenticate. As of the production of this manual, encryption in IVR has not been adopted

due to the lack of specific details in the IVR spec. Visa has this functionality listed as not enabled, though this could change at any

time once the specification has been expanded.

7.4.3 Direct Integration The direct integration is used when an automated system is going to process the Consumer's authentication details. The automated

system will receive the Consumer's 3DS authentication detail and pass it to CardinalCommerce for authentication.

CardinalCommerce connects directly with the ACS to authenticate the user's credential and returns the results. The direct method

differs from the redirect method by skipping the middle step of redirecting to a URL to capture the Consumer's authentication

details. In the direct method the Merchant is expected to capture the Consumer's authentication credential at the same point,

between the cmpi_lookup and cmpi_authenticate message, and pass this credential on the cmpi_authenticate message.



Direct Transactional Flow: 1. Lookup including IVR fields. 2. Merchant captures Consumer authentication credentials.

3. Authenticate including credentials.

The direct method requires the Merchant to pass two additional fields on the cmpi_authenticate. Please refer to section 9.2.1 of

this guide for details on these fields.

Additional required fields on cmpi_authenticate message:

Credential

CredentialEncrypted

7.4.4 Redirect Integration The redirect integration is designed to have a human sit in between the Consumer and the authentication process. In this flow a

person working with the Consumer would enter the Consumers OTP (one time password) into a form and submit this for

authentication. This flow works best in a call center scenario.

The redirect flow differs from the direct flow by staying in the normal 3DS flow. A Lookup is run, including the IVR extension fields. If

the Cardholder is enrolled, the Merchant redirects to the ACSUrl. With IVR the ACSUrl will be a CardinalCommerce hosted page for

collecting the OTP. Once the OTP is submitted, CardinalCommmerce will send the OTP and PaReq to the ACS on behalf of the

Merchant and return the PARes back to the Merchant. The Merchant should then run in the cmpi_authenticate message into

CardinalCommerce to receive the results of authentication.

Redirect Transactional Flow:

1. Lookup including IVR fields.

2. Cardinal Widget redirects to ACS URL and enters OTP. Merchant submits this form and is redirected back to the term URL.

3. The term URL completes an Authenticate message.

7.5 Brazil Extensions Lookup Request To use Brazil Extensions additional fields are required to be passed in on the standard 3DS Lookup request for VISA and MasterCard. Additional fields required on cmpi_lookup request:

OverridePaymentMethod

MobilePhone

CategoryCode

ProductCode

8. Framed Inline Authentication Window The framed inline presentation of the Card Issuer’s authentication form within an HTML ‘frameset’ or iFrame allows the Merchant to maintain site branding and provide a consistent look and feel through the authentication process. The inline approach does NOT pop up a new browser window, therefore the authentication process is not impacted by pop-up blocking software. The header portion of the frameset should contain text similar to the following: For your security, please fill out the form below to complete your order.

Do not click the refresh or back button or this transaction may be interrupted or cancelled.



The portion of the frameset that displays the Card Issuer authentication form must be large enough to display the entire form

without scrolling (400x400 pixels). Verify the frameset size is large enough while testing the Centinel Test System.

NOTE: In some regions with dual-language requirements (e.g. Quebec, Canada) it will not be possible to display the entire

authentication form without scrolling. In this case it will be necessary to ensure that the framed authentication is scrollable.

9. Thin Client Integration The Thin Client provides a communication shell that accepts name / value pairs. The name / value pairs are serialized to an XML message and communicated to the Centinel MAPS. The Centinel MAPS communicates the response message to the Thin Client which makes the message elements available to the Merchant as a name / value pairs. The core transaction integration involves the implementation of two messages, the Lookup Message (cmpi_lookup) and the

Authenticate Message (cmpi_authenticate). Each message requires the Merchant to collect data from the Consumer, construct the

message using the Thin Client, and send the request message to the Centinel platform for processing. Merchants must utilize the

response values to control the flow of the Consumer's transaction.



TIP: Included with each of the Thin Clients are integration samples and marketing materials needed to complete the Consumer

Authentication Integration. Included within the code samples are additional comments on how to construct and process the

required API messages.

Consumer Authentication integrations also require a modification to the authorization processing. In addition to the authentication

of the Consumer, at checkout it is also required that the data elements resulting from the authentication processing be passed along

to the Gateway on the authorization and settlement transactions. Each Gateway API supports the passing of these data elements in

slightly different ways. Refer to section 7.3.4 on passing the authentication data elements.

9.1 Lookup Message Integration The Lookup Message is responsible for initiating the Consumer Authentication. The Integration point for the Lookup message is immediately following the capture of the payment information, including the final order amount and the credit card information. NOTE: Authentication is REQUIRED to take place prior to authorization. Data resulting from the authentication process MUST be represented on the authorization transaction to ensure the Merchant will be provided the benefits from the program.

The Lookup Message is constructed and sent to the Centinel MAPS for processing. The Lookup Message requires transaction specific

data elements to be formatted on the request message. Refer to the following sections, for the complete list of required message

elements.

The response message is returned from the Centinel MAPS, and the Merchant invokes the Thin Client API to reference the response

values. In the event that the Enrolled value is Y, the ACSUrl element will contain a fully qualified URL that the Consumer should be

redirected to for authentication with the Card Issuer.

9.1.1 cmpi_lookup Request Message This is the first transaction of the Lookup / Authenticate pair that is used to process the Consumer Authentication transaction

request. The TransactionType value represented on the transaction request will dictate how the transaction will be processed.

The CardNumber value dictates the program that will be used in processing the transaction. Currently Verified by Visa, MasterCard

SecureCode/Identity Check, American Express SafeKey, Discover ProtectBuy, JCB J/Secure, and Diners Club ProtectBuy are supported

by Centinel.

Merchants must ensure that Cardinal has the proper Acquiring Merchant Identification Number and corresponding Acquiring Bank

Identification Numbers (BINs) configured in your account. The identifiers may vary based on card acceptance with your acquirer and

processor. Please contact us to verify your credentials.

TIP:

All fields use ASCII character set (0-9, A-Z, a-z, special characters $%&@!_ ect.)

The required field contains one of the following values

Y = Yes (Required field) C= Conditional (Based on conditions of transaction determines if this field will be returned or not) O = Optional (Not required but highly recommended) N = No (Not required)

Field Name Description Required Field

Definition

AcquirerId

Override the acquiring institution identification code (the Acquirer BIN) that is currently configured in the Centinel profile. TIP: This field is numeric only

N N(6)




Definition

AcquirerMerchantId Override the Acquirer Merchant identifier configured in the Centinel Merchant profile.

N AN(25)

AcquirerPassword

The value in this field is used to facilitate Merchant Authentication File (MAF) authentication processing. NOTE: This is required only when processing within certain VISA regions. If this value is passed it will override the password value configured on the Merchants configuration profile.

N AN(50)

Alias

An alias that uniquely identifies the account. NOTE: This field is required if Tokenization is enabled in the Merchant profile settings.

N AN(128)

Amount

Unformatted total transaction amount without any decimalization. Example: $100.00= 10000, $123.67= 12367, $.99= 99

Y N(20)

BillingAddress1 Consumer's billing address information. Y AN(50)

BillingAddress2 Consumer's billing address information. O AN(50)

BillingCity Consumer's city of their billing address. Y AN(50)

BillingCountryCode

Consumer's alpha 2 digit ISO 3166 country code. Example: United States= US

Y AN(2)

BillingFirstName Consumer's first name. Y AN(50)

BillingLastName Consumer's last name. Y AN(50)

BillingMiddleName Consumer's middle name. O AN(50)

BillingPhone

Consumer's phone number for billing address. This should be unformatted without hyphens. Example: 222-234-5678= 2222345678

Y N(20)

BillingPostalCode Consumer's postal code of their billing address. Y AN(10)

BillingState

Consumer's state or province of their billing address. Example: Ohio= OH Texas= TX

Y AN(50)

BrowserHeader The exact content of the HTTP accept header. C AN(256)

CardExpMonth

Card number expiration month. Formatted MM

Example: January = 01

Y N(2)

CardExpYear

Card number expiration year. Formatted YYYY

Example: YYYY= 2016

Y N(4)

CardNumber Consumer’s credit card number. Y N(19)




Definition

CardType

Type of cards used for purchase. Possible Values: VSA - Visa MSC - MasterCard VSD - Visa Delta/Debit (UK) VSE - Visa Electron MAE - Maestro (UK, Spain & Austria) AMX - American Express DSC - Discover DIN - Diners CBLA - Carte Blanche JCB - JCB ENR - EnRoute JAL - JAL CTB - Carte Bleue DNK - Dankort CSI - CartaSi EAN - Encoded Account Number UATP - UATP MAEI - Maestro (International)

N AN(20)

CountryCodeOverride Override the country code configured in the Centinel Merchant profile. N AN(2)

CurrencyCode 3 digit numeric ISO 4217 currency code for the sale amount. Y N(3)

CustomerId Id used by Merchant to identify customer. N AN(20)

DFReferenceId Reference Id that relates to the device fingerprinting data that was previously collected.

N AN(50)

Email Consumer's email address. Y AN(255)

Installment

An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. NOTE: This is required if the Merchant and Cardholder have agreed to installment payments.

N N(4)

IPAddress The IP address of the Consumer. NOTE: IPv4 and IPv6 are supported

C AN(50)

Item_Desc_X Brief description of item. N AN(256)

Item_Name_X Name of item purchased. Y AN(128)

Item_Price_X Unformatted price of item X transaction amount without any decimalization.

Y N(20)

Item_Quantity_X Number of items purchased. Y N(20)

Item_ShippingAddress1_X Address where item will be shipped. N AN(50)

Item_ShippingAddress2_X Address where item will be shipped. N AN(128)

Item_ShippingCity_X City where item will be shipped. N AN(50)

Item_ShippingCountryCode_X Country where item will be shipped. N AN(2)

Item_ShippingDestination_X

Shipping destination of item. Example: Commercial, Residential, Store

N AN(50)

Item_ShippingFirstName_X Consumer's first name. N AN(128)

Item_ShippingLastName_X Consumer’s last name. N AN(128)




Definition

Item_ShippingMiddleName_X Consumer’s middle name. N AN(128)

Item_ShippingPhone_X Phone number where item will be shipped. N N(20)

Item_ShippingPostalCode_X Postal code where item will be shipped. N AN(10)

Item_ShippingState_X State where item will be shipped. N AN(50)

Item_SKU_X Item SKU number. Y AN(20)

MerchantId Merchant identification code. This value is assigned to the Merchant by CardinalCommerce.

Y AN(50)

MerchantName Override the Merchant name configured in the Centinel Merchant profile.

N AN(25)

MerchantReferenceNumber Merchant specified data. N AN(20)

MerchantUrl Override the Merchant URL configured in the Centinel Merchant profile.

N AN(100)

MobilePhone Cardholder's mobile phone number. NOTE: This field is required for VISA Brazil extensions

Y N(25)

MsgType cmpi_lookup Y AN(50)

NewCustomer

Indicates whether the Consumer is a new or existing customer with the Merchant. Possible Values: Y- Yes N- No

Y AN(1)

OrderDescription Brief Description of items purchased. N AN(256)

OrderNumber Order Number or transaction identifier from the Merchant commerce website.

Y AN(50)

ProcessorId Merchant Processor identification code. This value is assigned to the Merchant by CardinalCommerce.

Y AN(20)

Recurring

Flag used to specify if the Merchant and Consumer have agreed to recurring payments. Possible Values: Y- Yes N- No

N AN(1)

RecurringEnd

The date after which no further recurring authorizations should be performed. This is formatted as YYYYMMDD. NOTE: This field is required if Recurring = Y

N N(8)

RecurringFrequency

Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months. Example: 6 months= 168 NOTE: This field is required if Recurring = Y

N N(3)

ShippingAddress1 Consumer's shipping address information. Y AN(50)

ShippingAddress2 Consumer's shipping address information. O AN(50)




Definition

ShippingAmount

Value represents the shipping amount without decimalization. Example: $123.67= 12367, $1,500.00= 150000

N N(20)

ShippingCity Consumer's city of their shipping address. Y AN(50)

ShippingCountryCode

Consumer's alpha 2 digit ISO 3166 country code. Example: United States= US

Y AN(2)

ShippingDestination_X

Destination to where the item will be shipped. Example: Commercial, Residential, Store

O AN(25)

ShippingFirstName Consumer's first name. Y AN(50)

ShippingLastName Consumer's last name. Y AN(50)

ShippingMethod

Name of the shipping method that was selected by the customer. Possible Values: 01 Same Day 02 Overnight / Expedited 03 Priority (2-3 Days) 04 Ground 05 Electronic Delivery 06 Ship to Store NOTE: This field is used for Amex SafeKey enhanced auth extension support specific to retail

N AN(50)

ShippingMiddleName Consumer's middle name. O AN(50)

ShippingPhone

Consumer's phone number for shipping address. This should be unformatted without hyphens. Example: 222-234-5678= 2222345678

Y N(20)

ShippingPostalCode Consumer's postal code of their shipping address. Y AN(10)

ShippingState

Consumer's state or province of their shipping address. Example: Ohio= OH Texas= TX

Y AN(50)

TaxAmount

Unformatted tax amount without any decimalization. Example: $100.00= 1000, $123.67= 12367, $.99= 99

N N(20)

Token

The third party token that will be used to process the transaction in place of the actual card number. NOTE: This field is required if Tokenization is enabled in the Merchant profile setting AND the Merchant is using a third party token in place of the Cardinal token.

N AN(100)




Definition

TransactionMode

Transaction mode identifier. Identifies the channel the transaction originates from. Available Options: M – MOTO (Mail Order Telephone Order) R – Retail S – eCommerce P – Mobile Device T – Tablet

Y A(1)

TransactionPwd A password to secure and verify the transaction originated from Merchant represented by the transaction details. The password value is configured through the Merchant profile.

Y AN(50)

TransactionType

Identifies the transaction type used for processing. Possible Values: C- Credit Card/Debit Card Authentication

Y AN(3)

TTPToken Trusted Third Party Authentication used. N AN(50)

UserAgent The exact content of the HTTP user agent header. C AN(500)

Version Application message identifier. Current Version – 1.7

Y AN(3)

9.1.2 Consumer Authentication 2.0 Lookup Request Fields To ensure your integration to Cardinal is as seamless as possible for the 2017 production release of the EMVco 3DS 2.0 protocols,

there are additional fields below that we highly recommend you integrate to at this time. Though they are not required for the 1.0.2

protocols, this will FutureProof™ your business ensuring all the required fields are passed to Cardinal.

NOTE: As the protocols develop over time there may be additional integration efforts such as a merchant SDK to be installed in your

application systems and the fields below may expand.

Consumer Authentication 2.0 Fields

Field Name Description

Required Field Definition

AccountAgeIndicator

Length of time cardholder has had account Possible Values: 0- No Account (guest checkout) 1- Created during transaction 2- Less than 30 days 3- 30-60 days 4- More than 60 days NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)






AccountCreateDate

Date the cardholder opened the account. Format: YYYYMMDD NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(8)

AccountChangeIndicator

Length of time since the last change to the cardholder account. This includes shipping address, new payment account, or new user added Possible Values: 1- Changed during transaction 2- Less than 30 days 3- 30-60 days 4- More than 60 days NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)

AccountChangeDate

Date the cardholder’s account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added. Format: YYYYMMDD NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(8)

AccountPwdChangeIndicator

Length of time since the cardholder changed or reset the password on the account Possible Values: 0- No change 1- Changed during transaction 2- Less than 30 days 3- 30-60 days 4- More than 60 days NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)






AccountPwdChangeDate

Date the cardholder last changed or reset password on account Format: YYYYMMDD NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(8)

ShippingAddressUsageIndicator

Indicates when the shipping address used for transaction was first used Possible Values: 1- This transaction 2- Less than 30 days 3- 30-60 days 4- More than 60 days NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)

ShippingAddressUsageDate

Date when the shipping address used for this transaction was first used Format: YYYYMMDD NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(8)

TransactionCountDay

Number of transaction (successful or abandoned) for this cardholder account within the last 24 hours NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(3)

TransactionCountYear

Number of transactions (successful and abandoned) for this cardholder account within the last year NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(3)

AddCardAttempts

Number of add card attempts in the last 24 hours NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(3)

AccountPurchases

Number of purchases with this cardholder account during the previous six months NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(4)






FraudActivity

Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account Possible Values: 0- No suspicious activity 1- Suspicious activity observed NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)

ShippingNameIndicator

Indicates if the cardholder name on the account is identical to the shipping name used for the transaction Possible Values: 0- Account and shipping name identical 1- Account and shipping name differ NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)

PaymentAccountIndicator

Indicates the length of time that the payment account was enrolled in the merchant account Possible Values: 0- No account (guest checkout) 1- During this transaction 2- Less than 30 days 3- 30-60 days 4- More than 60 days NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(1)

PaymentAccountAge

Date the payment account was added to the cardholder account Format: YYYYMMDD NOTE: This field is required for Discover ProtectBuy processing An AcctInfo field

C N(8)

AccountId Additional card holder account information. N AN(64)

AddressMatch

Indicates whether cardholder billing and shipping addresses match. Possible Values: Y- Shipping address matches billing address N- Shipping address does not match billing address

N AN(1)






AlternateAuthenticationMethod

Mechanism used by the Cardholder to authenticate to the 3DS requestor Possible Values: 01- No authentication occurred 02- Login using Merchant system credentials 03- Login using Federated ID 04- Login using FIDO Authenticator An AuthenticationInfo field

N N(2)

AlternateAuthenticationDate

Date and time in UTC of the cardholder authentication Format: YYYYMMDDHHMM An AuthenticationInfo field

N N(12)

AlternateAuthenticationData Data that documents and supports a specific authentication process An AuthenticationInfo field

N AN(2048)

BillingFullName Consumer’s billing name. This field can be used by systems that do not support separate field names and is used in place of the BillingFirstName, BillingMiddleName, and BillingLastName fields.

N AN(150)

ChallengeRequired

Indicates whether a challenge is required to complete authentication (region mandates). Possible Values: Y- Challenge required N- Challenge not required

N AN(1)

ChallengeIndicator

Possible Values: 01- No preference 02- No challenge request 03- Challenge requested (3DS requestor preference) 04- Challenge requested (mandate) NOTE: Default configuration on Merchant account, or can be overridden on transaction.

N N(2)

ShipMethodIndicator

Indicates shipping method chosen for the transaction Possible Values: 01- Ship to cardholder billing address 02- Ship to another verified address on file with merchant 03- Ship to address that is different than billing address 04- Ship to store (store address should be populated on request) 05- Digital goods 06- Travel and event tickets, not shipped 07- Other A MerchantRiskInfo field

N N(2)






DeliveryTimeframe

Indicates the delivery timeframe Possible Values: 0- Electronic Delivery 1- Same day shipping 2- Overnight shipping 3- Two or more day shipping A MerchantRiskInfo field

N N(1)

DeliveryEmail

For electronic delivery, email address to which the merchandise was delivered A MerchantRiskInfo field

N AN(254)

PreOrderIndicator

Indicates whether cardholder is placing an order with a future availability or release date Possible Values: 0- Merchandise available 1- Future availability A MerchantRiskInfo field

N N(1)

ReorderIndicator

Indicates whether the cardholder is reordering previously purchased merchandise Possible Values: 0- First time ordered 1- Reordered A MerchantRiskInfo field

N N(1)

PreOrderDate

Expected date that a pre-ordered purchase will be available Format: YYYYMMDD A MerchantRiskInfo field

N N(8)

GiftCardAmount

The purchase amount total for prepaid gift cards in major units Example: $123.45 USD= 123 A MerchantRiskInfo field

N N(15)

GiftCardCurrencyCode ISO 4217 currency code for the gift card purchased A MerchantRiskInfo field

N N(3)

GiftCardCount Total count of individual prepaid gift cards purchased A MerchantRiskInfo field

N N(2)






MessageCategory

Category of the message for a specific use case. Possible Values: 01- PA 02- NPA

NOTE: Configured on Merchant account, or can be overridden on transaction.

N N(2)

NPAIndicator

Non-Payer Authentication Indicator. Possible Values: 01- Add card 02- Maintain card information 03- Cardholder verification for EMV token 04- 80 Reserved for EMVCo, 80-90 Reserved DS NOTE: Configured on Merchant account, or can be overridden on transaction.

N N(2)

PurchaseDate

Date of original purchase. Required for recurring transactions. Format: YYYYMMDD:HH:MM:SS NOTE: If not passed, Centinel will use current date.

C AN(17)

ShippingFullName

Consumer’s shipping name. This field can be used by systems that do not support separate field names and is used in place of the ShippingFirstName, ShippingMiddleName, and ShippingLastName fields.

N AN(150)

9.1.3 Extension Support for Amex SafeKey Enhanced Lookup Request Fields

Consumer Authentication Amex SafeKey Enhanced Airline Required Fields

Field Name Description Required Field Definition

ProductCode Merchant product code Possible Values: AIR – Airline GEN - General Retail DIG - Digital Goods SVC - Services RES - Restaurant TRA - Travel DSP - Cash Dispensing REN - Car Rental GAS - Fuel LUX - Luxury Retail ACC - Accommodation Rental TBD - Other

Y AN(3)



NOTE: This is required Amex SafeKey enhanced fields

TravelDepartureDate The date of departure in the departure location time zone Format: YYYYYMMDD NOTE: Required when ProductCode=AIR and transaction amount is $200 or more

C

N(8)

TravelPassenger_X_FirstName Billing first name of the Cardholder Y AN(99)

TravelPassenger_X_LastName Billing last name of the Cardholder Y AN(99)

TravelOrigin The airport code of the originating airport NOTE: Required when ProductCode=AIR and transaction amount is $200 or more

C

AN(5)

TravelDestination The airport code of the destination airport NOTE: Required when ProductCode=AIR and transaction amount is $200 or more

C

AN(5)

TravelAirlineCarriers The selected airline carrier C AN(256)

9.1.4 Additional ProtectBuy 2.0 Lookup Request Fields Consumer Authentication Discover ProtectBuy Specific Fields

Field Name Description Required Field Definition

MarketingOptIn Indicates whether the customer has opted in for marketing offers Possible Values: True False

N AN(5)

MarketingSource Indicates where the marketing offer originated N AN(40)

DefaultCard Indicates that the card being used is the one setup to be used as the primary payment card for purchase. Possible Values: True False

N AN(5)

CardSequence Indicates the card sequence number within the stored payment if an add-on card is used instead of the default card on file

N N(2)

PassportNumber The cardholder’s passport number. N AN(40)

PassportCountry Issuing country for the cardholder’s passport. 3 digit ISO 8583 numeric code.

N N(3)

9.1.5 Extension Support for Brazil and IVR Lookup Request Fields Consumer Authentication Extension Support for Brazil and IVR


Required Field

Definition

Brazil Extensions

CategoryCode Merchant category code. NOTE: This field is required by MasterCard and Visa Brazil extensions.

Y N(4)



Consumer Authentication Extension Support for Brazil and IVR


Required Field

Definition

MobilePhone Cardholder's mobile phone number. NOTE: This field is optional by MasterCard and Visa Brazil extensions.

N N(25)

OverridePaymentMethod

Override the payment method. Possible Values: NA - Not applicable CR - Credit DB - Debit VSAVR - Visa Vale Refeicao VSAVA - Visa Vale Alimentacao NOTE: This field is required by MasterCard and Visa Brazil extensions.

Y AN(10)

ProductCode

Merchant category code. Possible Values: PHY - Goods/Service Purchase CHA - Check Acceptance ACF - Account Funding QCT - Quasi-Cash Transaction PAL - Prepaid Activation and Load NOTE: This field is required by MasterCard, but optional by Visa Brazil extensions.

Y AN(3)

IVR Extensions (India only)

AuthenticationChannel

Indicates the available mediums supported by the device for authentication. Possible Values: SMS – Via Short Messaging Service IVR – Via Interactive Voice Response USSD – Via Unstructured Supplementary Service Data WAP – Via Wireless Application Protocol

Y AN(15)

MobileFormat

Designates the format of the MobileId field. Possible Values: D- Domestic I- International Example: D= AAANNNNNNNNNN I= CCCAAANNNNNNNNNN NOTE: C= Country Code, A= Area Code, N= Subscriber Number

Y A(1)

MobileId The phone number or mobile Id used to authenticate the device. This is the number/id registered with the ACS.

Y N(25)



Consumer Authentication Extension Support for Brazil and IVR


Required Field

Definition

PareqChannel

Indicates how the transaction is being routed between the Merchant and the issuer bank during authentication. Possible Values: Blank value - indicates to the ACS to assume URL redirection Communications with the MPI/client will be using server to server communication over the internet. Direct value – Value indicates to the ACS to communicate directly with the MPI via server to server communication over the internet. NOTE: At time of publication these options are not valid.

Y AN(15)

ShoppingChannel

Indicates how the transaction is being initiated. Possible Values: IVR – Via Interactive Voice Response CLIENT – Via J2ME (Java2 Micro Edition) or STK application ITP – Via Issuer Trusted Party SMS – Via Short Messaging Service (SMS) or via Unstructured Supplementary Service Data (USSD) WAP – Via Wireless Application Protocol native-app – Other native application

Y AN(15)

TtpCredential

Value sent by the ITP (Issuer Trusted Party) to the issuer in order to prove its relationship. NOTE: This field is only used if the Merchant has an ITP with the ACS. At the time of publication ITP has not been implemented by any IVR ACS.

N AN(80)

Sample Lookup Request Message <CardinalMPI>

<Amount>12345</Amount> <BillingAddress1>123 Main Street</BillingAddress1> <BillingCity>Cleveland</BillingCity> <BillingCountryCode>US</BillingCountryCode> <BillingFirstName>John</BillingFirstName> <BillingLastName>Consumer</BillingLastName> <BillingPhone>4403528444</BillingPhone> <BillingPostalCode>44111</BillingPostalCode> <BillingState>OH</BillingState> <BrowserHeader>*/*</BrowserHeader> <CardExpMonth>02</CardExpMonth> <CardExpYear>2009</CardExpYear> <CardNumber>4111111111111111</CardNumber> <CurrencyCode>840</CurrencyCode> <Email>[email protected]</Email> <IPAddress>207.48.141.20</IPAddress> <Item_Name_1>2GB MP3 Player</Item_Name_1>



<Item_Price_1>1000</Item_Price_1> <Item_Quantity_1>1</Item_Quantity_1> <Item_SKU_1>112233</Item_SKU_1> <MerchantId>123456</MerchantId> <MobilePhone>4402211234</MobilePhone> <MsgType>cmpi_lookup</MsgType> <NewCustomer>Y</NewCustomer> <ProcessorId>100</ProcessorId> <ShippingAddress1>123 Main Street</ShippingAddress1> <ShippingCity>Cleveland</ShippingCity> <ShippingCountryCode>US</ShippingCountyCode> <ShippingFirstName>John</ShippingFirstName> <ShippingLastName>Consumer</ShippingLastName> <ShippingMethod></ShippingMethod> <ShippingPhone>4403528444</ShippingPhone> <ShippingPostalCode>44111</ShippingPostalCode> <ShippingState>OH</ShippingState> <TransactionPwd>passw0rd</TransactionPwd> <TransactionType>C</TransactionType> <UserAgent>Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)</UserAgent> <Version>1.7</Version>

</CardinalMPI>

9.1.6 cmpi_lookup Response Message

This message is generated in response to the cmpi_lookup message.

TIP:

All fields use ASCII character set. (0-9, A-Z, a-z, special characters $%&@!_ ect.)


Y = Yes (This will be returned on the response)

C = Conditional (Based on conditions of transaction determines if this field will be returned or not)

O = Optional (Not required but highly recommended) N = No (This field is not required)

Boolean = True or False


Definition

ThreeDSVersion

This field contains the 3DS version that was used to process the transaction. Possible Values: 1.0.2 2.0.0

N AN(10)

ACSUrl

The fully qualified URL to redirect the Consumer to complete the Consumer Authentication transaction. NOTE: Available if Enrolled= Y

C AN(2048)




Definition

Cavv

Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication Field (UCAF) This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the Merchant's configuration in either Base64 encoding or Hex encoding. A Base64 encoding Merchant configuration will produce values of 28 or 32 characters. A Hex encoding Merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).

C AN(40)

CavvAlgorithm

Indicates the algorithm used to generate the CAVV value. Possible Values: 2- CVV with ATN 3- MasterCard SPA algorithm

N N(1)

EciFlag

Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor. Possible Values: 02 or 05- Fully Authenticated Transaction 01 or 06- Attempted Authentication Transaction 00 or 07- Non 3-D Secure Transaction

MasterCard VISA AMEX JCB DINERS CLUB

00 05 05 05 05

01 06 06 06 06

02 07 07 07 07

Y AN(2)

Enrolled

Status of Authentication eligibility. Possible Values: Y- Yes- Bank is participating in 3D Secure protocol and will return the ACSUrl N- No - Bank is not participating in 3D Secure protocol U- Unavailable - The DS or ACS is not available for authentication at the

time of the request B- Bypass- Merchant authentication rule is triggered to bypass

authentication in this use case NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication.

Y AN(1)

ErrorDesc Application error description for the associated error number(s). NOTE: Multiple error descriptions are separated by a comma.

Y AN(255)




Definition

ErrorNo

Application error number(s). A non-zero value represents the error encountered while attempting to process the message request. NOTE: Multiple error numbers are separated by a comma.

Y AN(255)


OrderId Centinel generated order identifier. Used to link multiple actions on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services.

Y N(16)

PAResStatus

Transactions status result identifier. Possible Values: Y – Successful Authentication N – Failed Authentication U – Unable to Complete Authentication A – Successful Attempts Transaction C – Challenge Required for Authentication R – Authentication Rejected NOTE: Statuses of C and R only apply to Consumer Authentication 2.0

C AN(1)

Payload The encoded payment request generated by MAPS. NOTE: Available if Enrolled= Y

C AN(2048)

SignatureVerification

Transaction Signature status identifier. Possible Values: Y – Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. N – Indicates that the PARes could not be validated. This result could be for a variety of reasons; tampering, certificate expiration, etc., and the result should not be trusted.

C AN(1)

ThirdPartyToken

Third Party Token that is returned from the token provider after a card number is specified on the request. NOTE: This field is returned if Tokenization is enabled in the Merchant profile setting AND the Merchant is using a third party token provider.

N AN(100)

Token

Centinel generated order identifier. NOTE: This field is returned if Tokenization is enabled in the Merchant profile settings.

N AN(26)

TransactionId

Centinel transaction identifier. This value identifies the transaction within the Centinel system. To complete the transaction, the value is required to be passed on the Authenticate message to link the Lookup and Authenticate message together. NOTE: The TransactionId is the preferred identifier for linking the Lookup and Authenticate message.

Y AN(20)

TransactionType

Identifies the transaction type used for processing. Possible Values: C – Credit Card/Debit Card Authentication

Y AN(3)




Definition

UCAFIndicator

Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer. Possible Values: 0- Non-SecureCode transaction, bypassed by the Merchant 1- Merchant-Only SecureCode transaction 2- Fully authenticated SecureCode transaction NOTE: This field is only returned for MasterCard transactions.

N N(1)

Xid

Transaction identifier resulting from authentication processing. NOTE: Gateway/Processor API specification may require this value to be appended to the authorization message. This value will be encoded according to the Merchant's configuration in either Base64 encoding or Hex encoding. A Base64 encoding Merchant configuration will produce values of 28 characters. A Hex encoding Merchant configuration will produce values of 40 characters.

C AN(40)

3DS Extenstion Support

IVR Extensions (India only) IvrEnabledMessage

Flag to indicate if a valid IVR transaction was detected.

N

Boolean

IvrEncryptionKey Encryption key to be used in the event the ACS requires encryption of the credential field.

N AN(16)

IvrEncryptionMandatory Flag to indicate if the ACS requires the credential to be encrypted. N Boolean

IvrEncryptionType An indicator from the ACS to inform the type of encryption that should be used in the event the ACS requires encryption of the credential field.

N AN(20)

IvrLabel An ACS Provided label that can be presented to the Consumer. Recommended use with an application.

N AN(20)

IvrPrompt An ACS provided string that can be presented to the Consumer. Recommended use with an application.

N AN(80)

IvrStatusMessage An ACS provided message that can provide additional information or details.

N AN(80)

Sample Lookup Response Message <CardinalMPI> <ACSUrl>https://www.somewebsite.com/acs</ACSUrl> <EciFlag>07</EciFlag> <Enrolled>Y</Enrolled> <ErrorDesc></ErrorDesc> <ErrorNo>0</ErrorNo> <OrderId>2584</OrderId> <Payload>eNpVUk1TwjAQ/SsM402nSUuKwSC/3gSoH5PL</Payload> <TransactionId>75f986t76f6</TransactionId> <TransactionType>C</TransactionType> </CardinalMPI>

Processing the Lookup Response Verify that the transaction is eligible for Authentication by evaluating the Enrolled element on the cmpi_lookup response message. In the event that the Enrolled element contains a Y value, Authentication is available and the Consumer should be redirected to the ACSUrl to complete the transaction. The ACSUrl element contains the fully qualified URL to the Card Issuer Authentication system. It is required that the Consumer authenticates themselves directly with the Card Issuer. If the Enrolled value is NOT Y, then the



Consumer is NOT eligible for Authentication. The ECI value represented on the Lookup response should be passed on the authorization transaction to the Gateway / Processor. Redirect the Consumer to the ACSUrl via a HTTP Form POST and construct the following form populated with the values returned on the cmpi_lookup response message.

NOTE: The form field names are case sensitive.

<html>

<body onload="document.frmLaunch.submit();">

<form name="frmLaunch" method="POST" action="ACSUrl Value">

<input type="hidden" name="PaReq" value="Payload Value">

<input type="hidden" name="TermUrl" value="Fully Qualified URL">

<input type="hidden" name="MD" value="Session Tracking Value">

</form>

</body>

</html>

Form Field Descriptions


ACSUrl The fully qualified URL to redirect the Consumer to complete authentication. Value should be retrieved from the ACSUrl field within the cmpi_lookup response message and inserted into the form.

PaReq The encoded authentication request generated by MAPS. This value should be retrieved from the Payload field within the cmpi_lookup response message and inserted into the form.

TermUrl The fully qualified URL of the Merchant webpage. This is configured to receive the Consumer returning from completing authentication. This URL will represent the webpage that will process the cmpi_authenticate message.

MD Merchant session tracking identifier. The value will be returned to the TermUrl when the Consumer is returned after completing authentication or PayPal payment. The field is available if necessary. If not needed pass an empty value on the form.

9.2 Authenticate Message Integration

NOTE: If you are in the process of considering readiness for EMVco 3DS 2.0 protocols, the authenticate message may not be required. You should consider migrating to our Cardinal Cruise Java Script where a hybrid approach may be used. Please contact your activation or sales engineering team to discuss your next steps. https://developer.cardinalcommerce.com/cardinal-cruise-activation.shtml The Authenticate Message is responsible for returning the Consumer Authentication outcome to the Merchant. The message will return the status of the Authentication to the Merchant, enabling the Merchant to handle the order / authorization processing according to the outcome. Once Authentication is completed, the Consumer will be redirected back to the TermUrl representing a webpage on the Merchant

website. The Merchant is required to receive this form POST, and construct the Authenticate Message to complete the transaction

and determine the status of the Authentication. Centinel will receive the Authenticate Message, decrypt the Authentication data

and perform data validation checks on the Authentication result. Centinel will return a response indicating the status of the

Authentication transaction.

In the event a non-zero ErrorNo value is returned or the SignatureVerification element is not "Y", the transaction should not be

authorized, and the Consumer should be prompted for another method of payment.

https://developer.cardinalcommerce.com/cardinal-cruise-activation.shtml



In the event the ErrorNo element is 0 (zero) and the SignatureVerification element is Y, indicating all fraud checks were satisfied,

then the PAResStatus value will define how the transaction should be processed. Based on the transaction outcome the Merchant's

order management system should be updated and the appropriate message should be displayed to the Consumer.

9.2.1 cmpi_authenticate Request Message Second message of the Lookup / Authenticate pair used in processing Consumer Authentication transactions. The values are posted

to the TermUrl from the external systems involved in processing the transactions. The webpage represented by the TermUrl should

retrieve the PARes value from the HTTP Request object for use in creating this message.

The message is used to communicate the PARes generated by the Issuer ACS software to Centinel. Centinel will verify the digital

signature within the PARes to validate that the authentication results were properly generated and not altered. The authentication

data values including the transaction status, XID, CAVV/AAV and the ECI are extracted from the PARes and returned to the

Merchant on the response message.

TIP:

All fields use ASCII character set (0-9, A-Z, a-z, special characters $%&@!_ ect.)


Y = Yes (Required field) C= Conditional (Based on conditions of transaction determines if this field will be returned or not) O = Optional (Not required but highly recommended) N = No (Not required) Boolean = True or False


Definition

MerchantId Merchant identification code. This value is assigned to the Merchant. Y AN(50)


MsgType cmpi_authenticate Y AN(50)

PAResPayload PARes generated transaction identifier. This value links the request message to the cmpi_lookup message.

C AN(10240)

ProcessorId Merchant Processor identification code. This value is assigned to the Merchant.

Y AN(20)

TransactionId

Centinel generated transaction identifier. This value links the request message to the cmpi_lookup message. NOTE: The TransactionId is the preferred identifier for linking the Lookup and Authenticate message.

Y AN(20)

TransactionPwd A password to secure and verify the transaction originated from the Merchant represented by the transaction details. The password value is configured the Merchant profile.

Y AN(50)

TransactionType

Identifies the Transaction Type used for processing.

Possible Values: C – Credit Card/ Debit Card Authentication

Y AN(3)

Version Application message version identifier Current Version – 1.7

Y AN(3)

3DS Extension Support

IVR Extensions (India only)

Credential The authentication credential used to authenticate the Consumer with the ACS. This will be an OTP (One Time Password) or SP (Static Password).

N AN(128)




Definition

CredentialEncrypted A flag to indicate if the passed credential has been encrypted by the Merchant.

N Boolean

Sample Authenticate Request Message <CardinalMPI> <MerchantId>123456</MerchantId> <MsgType>cmpi_authenticate</MsgType> <PAResPayload>********* Payload Message *********</PAResPayload> <ProcessorId>100</ProcessorId> <TransactionId>7fDSaySnCmDGCjPglzqX</TransactionId> <TransactionPwd>Passw0rd</TransactionPwd> <TransactionType>C</TransactionType>

<Version>1.7</Version> </CardinalMPI>

9.2.2 cmpi_authenticate Response Message This message is generated in response to the cmpi_authenticate request message. TIP:

All fields use ASCII character set. (0-9, A-Z, a-z, special characters $%&@!_ ect.)


Y = Yes (This field will be returned)

C = Conditional (Based on conditions of transaction determines if this field will be returned or not)

O = Optional (Not required but highly recommended) N = No (This field is not required)

Boolean = True or False


Definition

Cavv

Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication Field (UCAF) This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the Merchant's configuration in either Base64 encoding or Hex encoding. A Base64 encoding Merchant configuration will produce values of 28 or 32 characters. A Hex encoding Merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).

C AN(40)

CavvAlgorithm

Indicates the algorithm used to generate the CAVV value. Possible Values: 2- CVV with ATN 3- MasterCard SPA algorithm

N N(1)




Definition

EciFlag

Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor. Possible Values: 02 or 05- Fully Authenticated Transaction 01 or 06- Attempted Authentication Transaction 00 or 07- Non 3-D Secure Transaction

MasterCard VISA AMEX JCB DINERS CLUB

00 05 05 05 05

01 06 06 06 06

02 07 07 07 07

Y AN(2)

ErrorDesc Application error description for the associated error number. NOTE: Multiple error descriptions are separated by a comma.

Y AN(255)

ErrorNo

Application error number. A non-zero value represents the error encountered while attempting the process the message request. NOTE: Multiple error numbers are separated by a comma.

Y AN(255)


PAResStatus

Transaction status result identifier. Possible Values: Y – Successful Authentication N – Failed Authentication B – Bypassed Authentication U – Unable to Complete Authentication A – Successful Attempts Transaction

Y AN(1)

SignatureVerification

Transaction Signature status identifier. Possible Values: Y - Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. N - Indicates that the PARes could not be validated. This result could be for a variety of reasons; tampering, certificate expiration, etc., and the result should not be trusted.

Y AN(1)

UCAFIndicator

Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer. Possible Values: 0- Non-SecureCode transaction, bypassed by the Merchant 1- Merchant-Only SecureCode transaction 2- Fully authenticated SecureCode transaction NOTE: This field is only returned for MasterCard transactions.

N N(1)




Definition

Xid

Transaction identifier resulting from authentication processing. NOTE: Gateway/Processor API specification may require this value to be appended to the authorization message. This value will be encoded according to the Merchant's configuration in either Base64 encoding or Hex encoding. A Base64 encoding Merchant configuration will produce values of 28 characters. A Hex encoding Merchant configuration will produce values of 40 characters.

C AN(40)

Sample Authenticate Response Message <CardinalMPI> <Cavv>AAAAAAAAAAAAAAAAAAAAAAAAA=</Cavv> <EciFlag>05</EciFlag> <ErrorDesc></ErrorDesc> <ErrorNo>0</ErrorNo> <PAResStatus>Y</PAResStatus> <SignatureVerification>Y</SignatureVerification> <Xid>k4Vf36ijnJX54kwHQNqUr8/ruvs=</Xid> </CardinalMPI>

10. Configuring High Availability Options In addition to the New York Data Center, Cardinal has implemented a Data Center located in Cleveland, OH. This facility provides a significant increase in capacity and represents our commitment to unparalleled customer service. In the event the New York Data Center is unavailable due to maintenance or any other unforeseen reason, we have provided two

options for transitioning between data centers. The options available are listed below:

Option 1: Customer-Controlled (Recommended)

Allows Merchants/Partners the ability to control the transition process by utilizing two transaction processing URLs. This option

allows the direction of traffic to either facility. With this option the appropriate redundancy configuration will be implemented

based upon business operating needs.

Option 2: DNS Failover This option is accomplished through DNS updates. Cardinal will transition the IP address for transaction URLs.

NOTE: Using this option increases the risk in transition delay in the event the primary data center being used becomes unavailable. NOTE: Customers with specific procedural requirements for Data transfers can work with a Cardinal Activation Manager to address their needs. To utilize each of the data centers, there are preliminary requirements that need to be in place, these requirements are listed below:

The DNS Failover option requires CardinalCommerce to control the transaction URL and Merchant / Partners must honor the TTL (Time to Live) for DNS updates. Cardinal's current TTL configurations are set to 1 minute.

Your firewall and network configurations must allow connectivity to each data center. This must be in place for each option.

Your systems must be configured with the required certificate trust chains. This must be in place for each option.



11. Consumer Authentication Decision Table Based on the Lookup and Authenticate Message response values Merchants are required to control transaction flow in a variety of ways. The following decision table outlines the recommended actions for the list of possible outcomes scenarios that Consumer Authentication integrations must support. Each Merchant integration is required to handle each of the following response values. NOTE: The Decision Table only covers transaction responses that contain a zero ErrorNo value.

11.1.1 Consumer Authentication Lookup Response Values

ECI Value ECI Description

02 or 05 Fully Authenticated Transaction

01 or 06 Attempted Authentication Transaction

00 or 07 Non 3-D Secure Transaction

Enrolled Value

Description Recommended Action

Y Cardholder authentication is available Redirect the Consumer to the ACS URL to perform authentication.

N Cardholder not enrolled in authentication program

Complete the order as a non-authenticated transaction. Specify the proper ECI value on the authorization transactions.

Visa/JCB Diners Club/AMEX MasterCard

ECI - 06 ECI - 07 ECI - 00

U Cardholder authentication is unavailable.

Complete the order as a non-authenticated transaction. Specify the proper ECI value on the authorization transaction.

Visa/JCB/ AMEX/Diners Club

MasterCard

ECI - 07 ECI – 00

B Authentication bypassed.

Complete the order as a non-authenticated transaction. Specify the proper ECI value on the authorization transaction.

Visa/JCB/AMEX/ Diners Club

MasterCard

ECI - 07 ECI – 00



11.1.2 Consumer Authentication Authenticate Response Values

PAResStatus Signature

Verfication Description Recommended Action

Y Y Cardholder Authentication completed successfully

Complete the order as an authenticated transaction.


MasterCard

ECI - 05 ECI – 02

A Y Cardholder attempts authentication completed successfully.

Complete the order as an authenticated transaction.


MasterCard

ECI – 06 ECI – 01

N Y Cardholder failed authentication.

Redirect the Cardholder to payment details page. Display the recommended failed authentication message to the Consumer, and prompt for another form of payment to complete the transaction.

U Y Cardholder was unable to be authenticated.

Complete the order as a non-authenticated transaction.


MasterCard

ECI – 07 ECI – 00

Y,A,N,U N Fraud check failure indicates that the transaction results cannot be trusted.

Redirect the Cardholder to payment details page. Display the recommended failed authentication message to the Consumer, and prompt for another form of payment to complete the transaction.

NOTE: Refer to the Consumer Authentication test case guide to complete the Activation process.



Appendix A: Version Changes

This section of the guide provides a history of the changes made with each version update.

Date Description Version

December 16, 2016 Added values to the ShippingMethod definition TransactionId field definition updated to AN(20) Removed reference to Elo Compra Segura

4.33.15

December 14, 2016 The PaResPayload value on the cmpi_authenticate request edited to Conditional (C) UserAgent, BrowserHeader, and IPAddress on the cmpi_lookup request edited to

Conditional (C) Update spelling of ChallangeRequired field to ChallengeRequired under 2.0 section of

cmpi_lookup request Removed the AccountInfo field from the 2.0 section of the cmpi_lookup and replaced

with additional fields Removed the AuthenticationInfo field from the 2.0 section of the cmpi_lookup and

replaced with additional fields Removed the MerchantRiskInfo field from the 2.0 section of the cmpi_lookup and

replaced with additional fields Removed Elo Compra Segura references

4.34.15

November 29, 2016 Consumer Authentication 2.0 section has been added to the Lookup Request message outlining new field names

4.33.15

November 21, 2016 Field name MerchantReferenceNumber removed from the cmpi_lookup request 4.32.15

November 18, 2016 API Key Usage section included within guide 4.31.15

November 9, 2016 Updated definition for MerchantReferenceNumber and Item_ShippingDestination_X Edited field name for Item_ShippingCountryCode_X

4.30.15

August 26, 2016 Updates made to the Brazil Market Extension 4.29.15

August 17, 2016 Edits made to the Consumer Authentication transaction steps 4.28.15

August 9, 2016 Updated ECIFlag field order in cmpi_authenticate response message 4.27.15

July 25, 2016 Field Name DFReferenceId added to cmpi_lookup request message 4.26.15

June 15, 2016 Discover ProtectBuy logo added to guide Updated Consumer Authentication Transaction Diagram

4.25.15

May 23, 2016 Cavv and Xid field names edited in the Lookup and Authentication Response message Updated description of ShippingPostalCode and ShippingDestination_X

4.24.15

May 2, 2016 Removed SecureCode+ field names from Lookup Response message Updated MasterCard ECI values in Section 11 Consumer Authentication Decision Table

4.23.15

April 4, 2016 The possible values for the UCAFIndicator field name updated to 0-Non-SecureCode transaction, bypassed by the Merchant, 1- Merchant-Only SecureCode transaction, 2- Fully authenticated SecureCode transaction

4.22.15

March 29, 2016 Additional field names, UCAFIndicator, CaavAlgorithm, XID, and CAVV added to cmpi_lookup response message

Additional field names, UCAFIndicator and CavvAlgorithm, added to cmpi_authenticate

response message

Shipping and Billing fields updated to be required in the cmpi_lookup request

Removed Widget integration instructions

4.21.15

October 21, 2015 • Updated the MasterCard ECI Value in the Authenticate Response message 4.20.15

June 23, 2015 • Updated the form post under Processing the Lookup Response 4.21.15

February 23, 2015 • Updated the Browserheader and UserAgent fields adding a note indicating the fields are not required but highly recommended. • Updated OrderNumber field to a required field.

4.20.15

February 18, 2015 • Added Enrolled values to the Enrolled field name under the cmpi_lookup message • Updated the Consumer Authentication Implementation Checklist with Elo Compra Segura

4.19.15



Appendix B: 3DS Flow Diagrams

Cardinal Cruise Web Combined Step-up



Cardinal Cruise Web Combined Frictionless



Appendix C: API Key Usage

Summary Centinel has added support for submitting requests using an API Key. In the past, a request was submitted using a MerchantId,

ProcessorId, and TransactionPwd value within the request. In order to provide more flexibility with submitting requests and rotating

keys, functionality has been added to support using an API Key when submitting requests. In place of the MerchantId, ProcessorId,

and TransactionPwd fields, a request will instead be submitted with identifier, OrgUnit, Algorithm, Timestamp, and Signature fields.

NOTE: A merchant wanting to authenticate with Centinel using API Keys will need to do so on both the cmpi_lookup and

cmpi_authenticate.

New Fields


Algorithm The hash algorithm that was used to generate the Signature for the request. Valid Options are SHA-256 or SHA-512

Identifier The unique identifier representing the API Key being used to generate the Signature that is specified on the request. This value will be provided by Cardinal at the time the API Key is generated.

OrgUnit The unique organizational unit for which the request is being processed for. Each merchant within the system will be assigned a unique OrgUnit value by Cardinal.

Signature The signature for the request being submitted. This value is generated by hashing the combination of the Timestamp and the API Key. For additional information, please see the specific section on generating signature values.

Timestamp The unix epoch time in milliseconds for the point in time that the request is generated. Example: 1467122891960

Example Request <CardinalMPI>

<Algorithm>SHA-256</Algorithm>

<Amount>12345</Amount>

<BillingAddress1>123 Main Street</BillingAddress1>

<BillingCity>Cleveland</BillingCity>

<BillingCountryCode>US</BillingCountryCode>

<BillingFirstName>John</BillingFirstName>

<BillingLastName>Consumer</BillingLastName>

<BillingPhone>4403528444</BillingPhone>

<BillingPostalCode>44111</BillingPostalCode>

<BillingState>OH</BillingState>

<BrowserHeader>*/*</BrowserHeader>

<CardExpMonth>02</CardExpMonth>

<CardExpYear>2009</CardExpYear>

<CardNumber>4111111111111111</CardNumber>

<CurrencyCode>840</CurrencyCode>

<Email>[email protected]</Email>

<Identifier>Merchant123-Key</Identifier>

<IPAddress>207.48.141.20</IPAddress>

<Item_Name_1>2GB MP3 Player</Item_Name_1>



<Item_Price_1>1000</Item_Price_1>

<Item_Quantity_1>1</Item_Price_1>

<Item_SKU_1>112233<Item_SKU_1>

<MobilePhone>4402211234</MobilePhone>

<MsgType>cmpi_lookup</MsgType>

<NewCustomer>Y</NewCustomer>

<OrgUnit>55e34656babcca109cef8ee4</OrgUnit>

<ShippingAddress1>123 Main Street</ShippingAddress1>

<ShippingCity>Cleveland</ShippingCIty>

<ShippingCOuntryCOde>US</ShippingCOuntryCode>

<ShippingFirstName>John</ShippingFirstName>

<ShippingLastName>Consumer</ShippingLastName>

<ShippingMethod></ShippingMethod>

<ShippingPhone>4403528444</ShippingPhone>

<ShippingPostalCode>44111</ShippingPostalCode>

<ShippingState>OH</ShippingState>

<Signature>F1NNxfY6xZYlj4nq2T3YXFWi+9mk570XH|YLwDc5oE4=</Signature>

<Timestamp>1467122891960</Timestamp>

<TransactionType>C</TransactionType>

<UserAgent>Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)</UserAgent>

<Version>1.7</Version>

</CardinalMPI>

Generating a Signature Value The API Key Signature is generated by concatenating the Unix Epoch Time in Milliseconds with the API Key, hashing the result, and

then Base64 encoding the final result.

Base64(Hash(Timestamp + ApiKey))

SHA-256 Example Values:

Milliseconds Since Epoch: 1485534293321

Demo ApiKey: 13f1fd1b-ab2d-4c1f-8e2c-ca61878f2a44

ApiKey Signature: X5TupwjjpO9hg5qIHG2h9aMCekWiqbYkzPkXkPopFMw=

SHA-512 Example Values:

Milliseconds Since Epoch: 1485534293321

Demo ApiKey: 13f1fd1b-ab2d-4c1f-8e2c-ca61878f2a44

ApiKey Signature: 21rO7Y+71hmSJSiJ2O4zo7xnaVg6ALwA0KaWtrQiOJBfOFgTqZaV0+6deiemF8sWzlfaUGnUF1pX21QCXpHdMA==



Appendix D: Field Level Encryption for CardNumber Summary Cardinal has added field level encryption support for the CardNumber field within our API. To encrypt the CardNumber, the merchant will use a public key provided by Cardinal and provide the alias of the key when sending in the request to Cardinal. There are no specific libraries or .jars required to encrypt the CardNumber (in Java). The two new fields added to our API are EncryptedCardNumber and EncryptedCardNumberParameters.


EncryptedCardNumber The EncryptedCardNumber is the Base64 encoded value of the encrypted bytes of the CardNumber using a 2048bit RSA key

EncryptedCardNumberParameters The EncryptedCardNumberParameters field is made up pf four required values. NOTE: These values should be separated by semicolons (;) or colons (:). All values are required and must be presented in this specific order 1. The transformation used

a. Cardinal currently supports the following flavors of OAEP outlined in the table below and requires the merchant to pass in specific values representing each one

Tip: If different values are passed in, Cardinal will be unable to decrypt the CardNumber 2. The alias of the key 3. SUBSTRING- Used to indicate that certain information should be ignored from the

decrypted value a. Cardinal has a feature that allows the Merchant to specify a certain number of

characters that should be truncated off the front of the card number after decryption

This tool is useful in situations where a merchant may be using an HSM to handle the card. At times, extra data could be included on the front of the card number when it is encrypted

Tip: SUBSTRING should be included even if the merchant has no need for this feature. In such an instance a “0” is passed as the fourth parameter (see table below) 4. The number of digits to be ignored from the decrypted value

a. If there is no need to utilize this feature, the merchant should pass in a “0”

Example <EncryptedCardNumber>SL1SK9dUn1zzwW3UuB0JvBL938ho4qr+nyUQ0J9ipWmQciV/CD+FUP1NDzi7u4mBMRscQPoL

YznPiy+6D0uR5prGsBNZ4z+IfihD6rm6Rn7MkgSjj/+olGrNLm4F+2jfObWOmF3/pq/jrDvx

ObQqQMN/vBsryEE/H7TCnFDmzxgyzZ4iGlaYEuUaLSoL3CYHpOq9a5gBNG1opmOATyDDjw3K

fBmCGJShiiwI60NEysyAnlLWdKQQ6iGHx8oHV8YpF5Ex62xWSUYQcknB7ov83oJ61eJoixRz

LFXJ22oXHcdPFz/eEBdQCLHBfN0/c+8H8C5G+/6rj36LHN/ykrbrhQ==</EncryptedCardNumber>

<EncryptedCardNumberParameters>RSAOAEP1:testkeyalias;SUBSTRING:0</EncryptedCardNumberParameters> If Cardinal has errors in processing the EncryptedCardNumber or the EncryptedCardNumberParameters fields, Centinel may return an ErrorCode 3534, “XML Encryption- Error Decryption XML.”



Transformation Used for Encryption Passed in first Parameter of the EncryptedCardNumber Field

RSA/ECB/OAEPWithSHA1AndMGF1Padding RSAOAEP1

RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING RSAOAEP256



activation guide: consumer authentication guide: consumer authentication ... more information about...

Documents