Transcription
Title PageCybersource Payer AuthenticationUsing the Simple Order API
Cybersource Contact InformationFor general information about our company, products, and services, go to http://www.cybersource.com.For sales questions about any Cybersource service, email sales@cybersource.com or call 650-432-7350 or 888330-2300 (toll free in the United States).For support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportCopyright 2021. Cybersource Corporation. All rights reserved. Cybersource Corporation ("Cybersource") furnishes thisdocument and the software described in this document under the applicable agreement between the reader ofthis document ("You") and Cybersource ("Agreement"). You may use this document and/or software only inaccordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the informationcontained in this document is subject to change without notice and therefore should not be interpreted in any wayas a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability for any errors thatmay appear in this document. The copyrighted software that accompanies this document is licensed to You foruse only in strict accordance with the Agreement. You should read the Agreement carefully before using thesoftware. Except as permitted by the Agreement, You may not reproduce any part of this document, store thisdocument in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical,recording, or otherwise, without the prior written consent of Cybersource.Restricted Rights LegendsFor Government or defense agencies: Use, duplication, or disclosure by the Government or defense agenciesis subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a)through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations setforth in Cybersource Corporation's standard commercial agreement for this software. Unpublished rightsreserved under the copyright laws of the United States.TrademarksAuthorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation.Cybersource, Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, andCybersource Connect are trademarks and/or service marks of Cybersource Corporation. Visa, Visa International,Cybersource, the Visa logo, and the Cybersource logo are the registered trademarks of Visa International in theUnited States and other countries. All other trademarks, service marks, registered marks, or registered servicemarks are the property of their respective owners.Version: 21.052
CONTENTSContentsRecent Revisions to This DocumentAbout This Guide13Audience and PurposeScope111313Conventions 14Note, Important, and Warning StatementsText and Command Conventions 14Related DocumentsCustomer SupportChapter 1141515Introducing Payer Authentication16Overview of Chargeback Protection 16PSD2 173D Secure 2.x 17Prerequisites for Implementing Payer Authentication17Integrating Payer Authentication into Your Business 18Implementing 3D Secure 2.x 19Scenario 1: You are a New Merchant 19Scenario 2: You Use the Cybersource Simple Order API and Payer AuthenticationServices for 3D Secure 1.0 20Scenario 3: You Want to Integrate Using an SDK for your Mobile Application 21Using Secure Acceptance with Payer Authentication 22Required Merchant Information 22Chapter 2Implementing Cardinal Cruise Direct Connection API PayerAuthentication 23Prerequisites23After Implementation and Before Go Live23Process Flow for Cardinal Cruise Direct Connection APIStep 1: Payer Authentication Setup Service 2424Payer Authentication Using the Simple Order API 3
ContentsRequest Fields 24Important Response Fields 24Field Definitions and Details 24Request and Response API Examples 25Step 2: Device Data Collection Iframe 25Building the Iframe 25Step 3: Payer Authentication Check Enrollment Service 27Request Fields 27Field Definitions and Details 28Combining Services 29Interpreting the Response 29Important Response Fields 30Field Definitions and Details 30Step 4: Step-Up IFrame 30Building the Iframe 30Receiving the Step-Up Results 32Step 5: Payer Authentication Validation Service 33Request Fields 33Field Definitions and Details 33Request and Response API Examples 33Combining Services or Mapping Authorization Fields 33Interpreting the Response 34Redirecting Customers to Pass or Fail Message Page 35Chapter 3Implementing SDK Payer AuthenticationImplementation Overview3636Process Flow for SDK Integration37Before You Begin 38Credentials/API Keys 38Create the JSON Web Token (JWT)JWT Claims 39JWT Examples 40Using the Android SDK 41Update the Gradle Build PropertiesConfigure the Android SDK 42Set Up the Initial Call 443941Using the iOS SDK 45Download and Import the SDK 45Set Up Your Build Environment 46Configure the iOS SDK 47Set Up the Initial Call 50Implementing SDK Payer Authentication 51Requesting the Check Enrollment Service (SDK)51Payer Authentication Using the Simple Order API 4
ContentsInterpreting the Response 52Authenticating Enrolled Cards 53Call Cardinal.cca continue (Android SDK) 54Call Cardinal session continue (iOS SDK) 55Receiving the Authentication Results 57Requesting the Validation Service 57Interpreting the Response 59Redirecting Customers to Pass or Fail Message PageChapter 4Upgrading Your Payer Authentication ImplementationUpgrading to 3D Secure 2.xBenefits 60PSD2 Impact 61Mandates 61Timelines 61Recommended IntegrationMigration FAQChapter 55960606162Testing Payer Authentication ServicesTesting Process 64Enrollment Check 64Authentication ValidationExpected Results646566Test Cases for 3D Secure 1.0 68Visa Secure 68Mastercard Identity Check 75Maestro 84American Express SafeKey 88JCB J/Secure 94Diners Club ProtectBuy 100Discover ProtectBuy 106Elo Compra Segura 112China UnionPay 113Test Cases for 3D Secure 2.x 114Test Case 2.1: Successful Frictionless Authentication 115Card Numbers 115Results for the Check Enrollment Service 115Results for the Validation Authentication Service 116Action 117Test Case 2.2: Unsuccessful Frictionless Authentication 117Card Numbers 117Payer Authentication Using the Simple Order API 5
ContentsResults for the Check Enrollment Service 118Results for the Validation Authentication Service 118Action 118Test Case 2.3: Attempts Processing Frictionless Authentication 119Card Numbers 119Results for the Check Enrollment Service 119Results for the Validation Authentication Service 120Action 121Test Case 2.4: Unavailable Frictionless Authentication 121Card Numbers 121Results for the Check Enrollment Service 122Results for the Validation Authentication Service 123Action 123Test Case 2.5: Rejected Frictionless Authentication 123Card Numbers 123Results for the Check Enrollment Service 124Results for the Validation Authentication Service 124Action 124Test Case 2.6: Authentication not Available on Lookup 125Card Numbers 125Results for the Check Enrollment Service 125Results for the Validation Authentication Service 126Action 126Test Case 2.7: Enrollment Check Error 127Card Numbers 127Results for the Check Enrollment Service 127Results for the Validation Authentication Service 128Action 128Test Case 2.8: Time-Out (Cruise Direct and Hybrid Only) 129Card Numbers 129Results for the Check Enrollment Service 129Results for the Validation Authentication Service 130Action 130Test Case 2.9: Bypassed Authentication 131Card Numbers 131Results for the Check Enrollment Service 131Results for the Validation Authentication Service 132Action 132Test Case 2.10a: Successful Step-Up Authentication (Cruise Direct and Hybrid)Card Numbers 133Results for the Check Enrollment Service 133Results for the Validation Authentication Service 134Action 135Test Case 2.10b: Successful Step-Up Authentication (Standard) 136Card Numbers 136133Payer Authentication Using the Simple Order API 6
ContentsResults for the Check Enrollment Service 136Results for the Validation Authentication Service 137Action 138Test Case 2.11a: Unsuccessful Step-Up Authentication (Cruise Direct andHybrid) 138Card Numbers 138Results for the Check Enrollment Service 139Results for the Validation Authentication Service 139Action 139Test Case 2.11b: Unsuccessful Step-Up Authentication (Standard) 140Card Numbers 140Results for the Check Enrollment Service 140Results for the Validation Authentication Service 141Action 141Test Case 2.12a: Unavailable Step-Up Authentication (Cruise Direct and Hybrid)Card Numbers 142Results for the Check Enrollment Service 142Results for the Validation Authentication Service 143Action 144Test Case 2.12b: Unavailable Step-Up Authentication (Standard) 144Card Numbers 144Results for the Check Enrollment Service 145Results for the Validation Authentication Service 146Action 146Appendix A API Fields142147Formatting RestrictionsData Type DefinitionsNumbered ElementsRequest FieldsResponse FieldsAppendix B Reason Codes147147148149172194Appendix C Request and Response Examples195Cardinal Cruise Direct Connection API Integration Examples 195Payer Authentication Setup Service Request Example 195Payer Authentication Setup Service Response Example 196Check Enrollment Request Example 197Check Enrollment Response Example 198Payer Authentication Using the Simple Order API 7
ContentsValidate Authentication Request Example 199Validate Authentication Response Example 200Standard Integration Examples 201Check Enrollment Request Example 201Check Enrollment Response Example 202Hybrid Integration Examples 203Check Enrollment Request Example 203Check Enrollment Response Example 204Validate Authentication Request Example 205Validate Authentication Response Example 206Appendix D Website Modification ReferenceWebsite Modification Checklist3D Secure Services Logos207208Informational Message ExamplesAppendix E207209Payer Authentication Transaction Details in the Business CenterSearching for Payer Authentication DetailsEnrolled Card 210Enrollment Check 210Authentication Validation 211Card Not Enrolled 212Transaction Details 212Payer Authentication Search210212Storing Payer Authentication DataAppendix F210Payer Authentication Reports213214Payer Authentication Summary Report 214Downloading the Report 215Matching the Report to the Transaction Search ResultsInterpreting the Report 216Comparing Payer Authentication and Payment ReportsPayer Authentication Detail ReportReport Elements 218 Report 218 PayerAuthDetail 219 ProofXML 220 VEReq 221 VERes 222 PAReq 223215217218Payer Authentication Using the Simple Order API 8
Contents PARes 224 AuthInfo 226Examples 227Failed Enrollment Check 227Successful Authentication 228Appendix G Rules-Based Payer AuthenticationAvailable Rules229229API Responses 230Bypassed Authentication TransactionsRisk-Based Bank Transactions 231230Appendix H Implementing Hybrid or Standard Payer AuthenticationHybrid Payer Authentication 232Implementation Overview 232Process Flow for Hybrid Integration 233Before You Begin 234Credentials/API Keys 234Create the JSON Web Token (JWT) 234Add the JavaScript 237BIN Detection 237Implementing Hybrid Payer Authentication 237Requesting the Check Enrollment Service (Hybrid)Authenticating Enrolled Cards 240Requesting the Validation Service 241237Standard Payer Authentication 243Implementation Overview 243Process Flow for Standard Integration 244Before You Begin 245Credentials/API Keys 245Create the JSON Web Token (JWT) 245Add the JavaScript 247BIN Detection 247Implementing Standard Payer Authentication 248Starting Authentication 248Requesting the Check Enrollment Service (Standard)Appendix IAlternate Methods for Device Data CollectionDevice Data Collection OverviewPrerequisites 252Endpoints 252232249252252Payer Authentication Using the Simple Order API 9
ContentsCollecting Device Data 253Option 1: Card BIN in JWT 253Option 2: Card BIN as a POST Parameter Plus JWTGlossary254255Payer Authentication Using the Simple Order API 10
ReleaseChanges21.05 Updated the process to obtain credentials to generate your API keys for the Cardinal MobileSDK integration. See "Credentials/API Keys." Updated "Test Case 38: American Express SafeKey Card Enrolled: SuccessfulAuthentication" to fix a missing credit card digit. Added note that XID is not returned for Mastercard transactions. See "Test Cases for 3DSecure 2.x." Updated "Test Case 2.8: Time-Out (Cruise Direct and Hybrid Only)" from PARes status Uto VERes enrolled U. Updated the card cardType field description to specify it is required for the PayerAuthentication Setup service when the card type is Cartes Bancaires. Updated the length of the payerAuthEnrollService sdkMaxTimeout field from 1 to 2. Updated the size of the device data collection iframe to 10x10. See "Step 2: Device DataCollection Iframe," page 25. Added support for China UnionPay and Elo cards, including new test cases and updated APIfields. See "Elo Compra Segura," "China UnionPay," "Test Cases for 3D Secure 2.x," andAppendix A, "API Fields," on page 147. Added JCB, Elo, and China UnionPay card numbers to 2.x test cases. See "Test Cases for3D Secure 2.x." Updated the 2.x test cases to include all card types in a single set of test cases. See "TestCases for 3D Secure 2.x." Updated the following field descriptions to specify required for China and add additionalinformation: billTo state21.0421.03 REVISIONSRecent Revisions to ThisDocumentshipTo statePayer Authentication Using the Simple Order API 11
Recent Revisions to This DocumentReleaseChanges21.02 Updated 3D Secure requestor ID and 3D Secure requestor name to be optional. See"Required Merchant Information." Added vbv failure as a possible value along with internet for the e-commerce indicator for1.0 Visa test cases 4, 7, 8, 10, and 11. See "Test Cases for 3D Secure 1.0." Added card numbers for Cartes Bancaires Visa and Mastercard. See "Test Cases for 3DSecure 2.x." Updated the following field descriptions to specify they are not limited to Cartes Bancairestransactions: payerAuthEnrollService merchantScore payerAuthEnrollReply authorizationPayload payerAuthEnrollReply effectiveAuthentication Type payerAuthValidateReply authorizationPayload payerAuthValidateReply effectiveAuthentication TypeUpdated the length of following fields from 20 to 8 to match the EMV Specifications. payerAuthEnrollReply specificationVersion 21.01 Reformatted all card numbers with line breaks and spacing. See Chapter 5, "Testing PayerAuthentication Services," on page 64. Updated the following fields to change the data type from integer to string: payerAuthEnrollReply authenticationStatus Reason 20.05payerAuthValidateReply specificationVersion payerAuthEnrollReply challengeCancelCode payerAuthEnrollReply networkScore payerAuthValidateReply authenticationStatus Reason payerAuthValidateReply challengeCancelCodeUpdated the following field descriptions to remove required for transactions in Brazil: payerAuthEnrollService MCC payerAuthEnrollService mobilePhone payerAuthEnrollService overridePaymentMethod payerAuthEnrollService productCode Revised Chapter 2, "Implementing Cardinal Cruise Direct Connection API PayerAuthentication," on page 23. Added new request fields for the Payer Authentication Setup service: payerAuthEnrollService returnURL Added new response fields for the Payer Authentication Setup service: payerAuthEnrollReply accessToken payerAuthValidateService responseAccessTokenpayerAuthSetupReply accessTokenAdded new examples for the Payer Authentication Setup service and Cardinal Cruise DirectConnection API. See Appendix C, "Request and Response Examples," on page 195.Payer Authentication Using the Simple Order API 12
ABOUT GUIDEAbout This GuideAudience and PurposeThis guide is written for application developers who want to use the Cybersource SimpleOrder API to integrate Payer Authentication services into their order management system.It describes the tasks you must perform in order to complete this integration.Implementing Cybersource Payer Authentication services requires software developmentskills. You must write code that uses the API request and response fields to integratepayer authentication services into your existing order management system.ScopeThis guide describes how to use the Simple Order API to integrate payer authenticationservices with your order management system. It does not describe how to get startedusing the Simple Order API nor does it explain how to use Cybersource services otherthan payer authentication. For that information, see "Related Documents," page 15.Payer Authentication Using the Simple Order API 13
About This GuideConventionsNote, Important, and Warning StatementsA Note contains helpful suggestions or references to material not contained inthis document.An Important statement contains information essential to successfullycompleting a task or learning a concept.A Warning contains information or instructions, which, if not heeded, can resultin a security risk, irreversible loss of data, or significant cost in time or revenueor both.Text and Command ConventionsConventionUsagebold Field and service names in text. For example:Include the ics applications field. Items that you are instructed to act upon. For example:Click Save.italic Filenames and pathnames. For example:Add the filter definition and mapping to your web.xml file.Screen text Placeholder variables for which you supply particular values. XML elements. Code examples and samples. Text that you enter in an API environment. For example: Set the davService run field to true.Payer Authentication Using the Simple Order API 14
About This GuideRelated Documents Getting Started with Cybersource Advanced for the Simple Order API describes howto get started using the Simple Order API. (PDF HTML) Decision Manager Developer Guide Using the Simple Order API describes how tointegrate Decision Manager, a fraud detection service, with your order managementsystem. (PDF HTML) Credit Card Services Using the Simple Order API describes how to integrateCybersource payment processing services into your business. (PDF HTML) Secure Acceptance Hosted Checkout Integration Guide describes how to createSecure Acceptance profiles, which enable you to integrate your order managementsystem with the Secure Acceptance web/mobile checkout. (PDF HTML) Secure Acceptance Checkout API Integration Guide describes how to create SecureAcceptance profiles, which enable you to integrate your order management systemwith a website to process transactions. (PDF HTML) Reporting Developer Guide describes how to view and configure Business Centerreports. (PDF HTML) The Cybersource API Versions page provides information about the API versions.Refer to the Support Center for complete pport/technical-documentation.htmlCustomer SupportFor support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportPayer Authentication Using the Simple Order API 15
CHAPTERIntroducing PayerAuthentication1Cybersource Payer Authentication services use JavaScript and the ICS services toprovide authentication.Payer Authentication services enable you to add support to your web store for cardauthentication services, including Visa SecureSM, Mastercard Identity Check , Maestro (UK Domestic and international), American Express SafeKeySM, JCB J/Secure , DinersClub ProtectBuy, Discover ProtectBuy, China UnionPay, and Elo Compra Segura.These card authentication services deter unauthorized card use and protect you fromfraudulent chargeback activity referred to as liability shift. However, Cybersource PayerAuth
Payer Authentication Using the Simple Order API 4 Contents Request Fields 24 Important Response Fields 24 Field Definitions and Details 24 Request and Response API Examples 25 Step 2: Device Data Collection Iframe 25 Building the Iframe 25 Step 3: Payer Authentication Check Enrollment Service 27 Request Fields 27 Field Definitions and Details 28 Combining Services 29 .
