Transcription

Title PageChase PayUsing 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 [email protected] or call 650-432-7350or 888-330-2300 (toll free in the United States).For support information about any CyberSource service, visit the Support Center:http://www.cybersource.com/supportCopyright 2020. 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 errorsthat may appear in this document. The copyrighted software that accompanies this document is licensed to Youfor use 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,and CyberSource Connect are trademarks and/or service marks of CyberSource Corporation. Visa, VisaInternational, CyberSource, the Visa logo, and the CyberSource logo are the registered trademarks of VisaInternational in the United States and other countries. All other trademarks, service marks, registered marks, orregistered service marks are the property of their respective owners.Revision: May 20202

CONTENTSContentsRecent Revisions to This DocumentAbout This Guide5Audience and Purpose5Conventions 5Important Statements 5Text and Command ConventionsRelated DocumentsCustomer SupportChapter 1IntroductionChase Pay56677Authorizations with Payment Network TokensRequirements8How Chase Pay Works8Requesting the CyberSource ServiceAuthorization ServiceRecurring PaymentsAppendix A API Fields10101213Data Type DefinitionsRequest FieldsReply Fields88Supported Card TypeChapter 24131316Chase Pay Using the Simple Order API 3

ReleaseChangesMay 2020Updated information about recurring payments. See "Recurring Payments,"page 12.January 2020Changed payment network tokenization to authorizations with paymentnetwork tokens throughout this document.REVISIONSRecent Revisions to ThisDocumentUpdated the requirements. See "Requirements," page 8.Updated the purchaseTotals grandTotalAmount request field length. SeepurchaseTotals grandTotalAmount, page 15.May 2019This revision contains only editorial changes and no technical updates.July 2018Updated information about recurring payments. See "Recurring Payments,"page 12.December 2017This revision contains only editorial changes and no technical updates.March 2016Initial release.Chase Pay Using the Simple Order API 4

ABOUT GUIDEAbout This GuideAudience and PurposeThis document is written for merchants who want to enable customers to use Chase Payto pay for in-app transactions. This document provides an overview of integrating ChasePay and CyberSource services into an order management system and describes how torequest the CyberSource API to process authorizations and recurring payments.ConventionsImportant StatementsAn Important statement contains information essential to successfullycompleting a task or learning a concept.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.screen text XML elements. Code examples and samples. Text that you enter in an API environment; for example:Set the ics applications field to ics auth.Chase Pay Using the Simple Order API 5

About This GuideRelated DocumentsCyberSource Documents: Getting Started with CyberSource Advanced for the Simple Order API (PDF HTML) Simple Order API and SOAP Toolkit API Documentation and Downloads page Credit Card Services Using the Simple Order API (PDF HTML) Authorizations with Payment Network Tokens Using the Simple Order API (PDF HTML)Chase Pay documents on the Chase Paymentech developer center: Chase Pay Service Specification Chase Pay Companion GuideRefer to the Support Center for complete CyberSource technical documentation:http://www.cybersource.com/support center/support documentationCustomer SupportFor support information about any CyberSource service, visit the Support Center:http://www.cybersource.com/supportChase Pay Using the Simple Order API 6

CHAPTERIntroduction1Chase PayChase Pay enables registered Chase customers to use credit cards that are stored in theirdigital wallet as payment methods when making purchases using their mobile device.Chase Pay requires the customer to enter only a username and password to pay forgoods. It eliminates the need to enter account, shipping, and billing information. Thecustomer logs in to their Chase Pay account and chooses the card with which to pay.To process Chase Pay transactions:Step 1Integrate the Chase Pay lightbox (iFrame).Step 2Request the Chase Pay API to retrieve the payment network token, the expiration date,the cryptogram, and other payment data associated with the transaction. See"Authorizations with Payment Network Tokens," page 8.Step 3Request the CyberSource authorization service and include the payment network token,the expiration date, the cryptogram, and other payment data associated with thetransaction.This method is best if your business has a fraud management solution or a recordsmanagement system that requires payment data relating to transactions.Chase Pay Using the Simple Order API 7

Chapter 1IntroductionAuthorizations with Payment NetworkTokensAuthorizations with payment network tokens enable you to request a payment transactionwith a payment network token instead of a primary account number (PAN).For in-app transactions, authorizations with payment network tokens use some of theCyberSource payer authentication request fields. This approach simplifies yourimplementation if your order management system already uses payer authentication. SeeAuthorizations with Payment Network Tokens Using the Simple Order API (PDF HTML).RequirementsYou must: Create a CyberSource merchant evaluation account, if you do not have one already:https://www.cybersource.com/register/ Have a merchant account with Chase Paymentech Solutions. Chase Pay is supportedonly on Chase Paymentech Solutions. Install the CyberSource Simple Order API client.Supported Card TypeCyberSource supports the Visa card type for Chase Pay transactions.How Chase Pay Works1You choose the Chase Pay button. A JavaScript tag embedded within the checkout pagerenders the button.2The browser sends a POST request for the purchase selection to the merchant webserver.3Your (merchant) web server begins a MerchantSession request to the Chase PayServices.4Chase Pay Services returns a Digital Session ID to the merchant web server, and it isused in all subsequent request messages.Chase Pay Using the Simple Order API 8

Chapter 1Introduction5Your web server returns the Digital Session ID to the browser, which sends a POSTrequest to the Chase Pay site including the Digital Session ID.6The Digital Session ID is validated against the open session.7A lightbox is returned and displayed to the customer. The customer authenticates usingtheir Chase Pay credentials, which initiates a session with their Chase Pay wallet.8The customer confirms their payment options and shipping preferences, and the lightboxcloses. The browser sends a POST request to your web server, which includes theresulting Digital Session ID.9Your web server initiates a GetCheckoutData request to the Chase Pay Services andincludes the Digital Session ID. The GetCheckoutData request retrieves the customer’spayment and address information.10 Chase Pay Services returns the requested data to your web server, including: Digital primary account number (DPAN). Cryptogram (authentication verification value). ECI (transaction type). Address information (optional).11 Your web server formats and displays the payment confirmation page and displays it to thecustomer. The customer reviews and confirms their final payment details using thecredentials and the address information that is displayed.12 The browser sends a POST request to your web server.13 Instead of including all of the normally required fields for an authorization request, youshould include the following fields: card accountNumber ccAuthService cavv and ccAuthService xid—set to the cryptogram (authenticationverification value). paymentNetworkToken transactionType14 CyberSource processes the authorization, and the response is sent back to you. It isdisplayed to the customer, confirming the purchase.Chase Pay Using the Simple Order API 9

CHAPTERRequesting theCyberSource Service2Authorization ServiceYour payment processor can include API reply fields that are not documented in thisguide. See Credit Card Services Using the Simple Order API for detailed descriptions ofany additional API reply fields.See "Request Fields," page 14, and "Reply Fields," page 16, for detailed descriptions ofeach API.To request an authorization using a Visa card:Step 1Set the card accountNumber field to the payment network token value.Step 2Set the card expirationMonth and card expirationYear fields to the payment networktoken expiration date fields.Step 3Set the ccAuthService cavv field to the 3D Secure cryptogram of the payment networktoken.For a 40-byte cryptogram, split the cryptogram into two 20-byte binary values(block A and block B). Send the first 20-byte value (block A) in the cardholderauthentication verification value (CAVV) field. Send the second 20-byte value(block B) in the transaction ID (XID) field.Step 4Set the ccAuthService xid field to the 3D Secure cryptogram of the payment networktoken.Step 5Set the paymentNetworkToken transactionType field to 1.Step 6Set the ccAuthService commerceIndicator field to internet.Step 7Set the paymentSolution field to 007.Chase Pay Using the Simple Order API 10

Chapter 2Example 1Requesting the CyberSource ServiceAuthorization Request requestMessage xmlns 1" merchantID demomerchant /merchantID merchantReferenceCode demorefnum /merchantReferenceCode purchaseTotals currency USD /currency grandTotalAmount 5.00 /grandTotalAmount /purchaseTotals card accountNumber 4650100000000839 /accountNumber expirationMonth 12 /expirationMonth expirationYear 2020 /expirationYear cardType 001 /cardType /card ccAuthService run "true" cavv ABCDEFabcdefABCDEFabcdef0987654321234567 /cavv commerceIndicator internet /commerceIndicator xid ABCDEFabcdefABCDEFabcdef0987654321234567 /xid /ccAuthService paymentNetworkToken transactionType 1 /transactionType requestorID 1234567890 /requestorID /paymentNetworkToken paymentSolution 007 /paymentSolution /requestMessage Example 2Authorization Response c:replyMessage c:merchantReferenceCode demorefnum /c:merchantReferenceCode c:requestID 4465840340765000001541 /c:requestID c:decision ACCEPT /c:decision c:reasonCode 100 /c:reasonCode c:requestToken Ahj/7wSR5C/4Icd2fdAKakGLadfg5535r/ghx3Z90AoBj3u /c:requestToken c:purchaseTotals c:currency USD /c:currency /c:purchaseTotals c:ccAuthReply c:reasonCode 100 /c:reasonCode c:amount 5.00 /c:amount c:authorizationCode 888888 /c:authorizationCode c:avsCode X /c:avsCode c:avsCodeRaw I1 /c:avsCodeRaw c:authorizedDateTime 2015-11-03T20:53:54Z /c:authorizedDateTime c:processorResponse 100 /c:processorResponse c:reconciliationID 11267051CGJSMQDC /c:reconciliationID /c:ccAuthReply /c:replyMessage Chase Pay Using the Simple Order API 11

Chapter 2Requesting the CyberSource ServiceRecurring PaymentsThe recurring payments feature is described in Credit Card Services Using the SimpleOrder API (PDF HTML).Chase Pay Using the Simple Order API 12

APPENDIXAPI FieldsAData Type DefinitionsFor more information about these data types, see the World Wide Web Consortium (W3C)XML Schema Part 2: Datatypes Second Edition.Table 1Data Type DefinitionsData TypeDescriptionDate and timeFormat is YYYY-MM-DDThh:mm:ssZ, where: T separates the date and the time Z indicates Coordinated Universal Time (UTC), also known as GreenwichMean Time (GMT)Example 2020-01-11T22:47:57Z equals January 11, 2020, at 22:47:57(10:47:57 p.m.).IntegerWhole number {., -3, -2, -1, 0, 1, 2, 3, .}StringSequence of letters, numbers, spaces, and special charactersRequest FieldsUnless otherwise noted, all field names are case sensitive and all fields accept specialcharacters such as @, #, and %.Chase Pay Using the Simple Order API 13

Appendix ATable 2API FieldsRequest FieldsFieldDescriptionUsed By:Required (R) orOptional (O)Data Type(Length)card accountNumberThe payment network token value.ccAuthService (R)Nonnegativeinteger (20)Populate this field with the decrypted DPAN value.card cardTypeType of card to authorize. Value: 001 for VisaccAuthService (R)String (3)card cvNumberCVN.ccAuthService (R)Nonnegativeinteger (4)card expirationMonthTwo-digit month in which the payment network tokenexpires.ccAuthService (R)String (2)ccAuthService (R)Nonnegativeinteger (4)Format: MM.Possible values: 01 through 12.card expirationYearFour-digit year in which the payment network tokenexpires.Format: YYYY.ccAuthService cavvCryptogram for payment network token transactions.The value for this field must be 28-character base64or 40-character hex binary. All cryptograms use oneof these formats.ccAuthService (R)String (40)ccAuthServicecommerceIndicatorFor a payment network token transaction.ccAuthService (R)String (20)ccAuthService runWhether to include ccAuthService in your request.Possible values:Value: internet for the Visa card type true: Include the service in your request. false (default): Do not include the service inccAuthService (R)your request.ccAuthService xidCryptogram for payment network token transactions.The value for this field must be 28-character base64or 40-character hex binary. All cryptograms use oneof these formats.ccAuthService (R)String (40)merchantIDYour CyberSource merchant ID. Use the samemerchant ID for evaluation, testing, and production.ccAuthService (R)String (30)merchantReferenceCodeMerchant-generated order reference or trackingnumber. CyberSource recommends that you send aunique value for each transaction so that you canperform meaningful searches for the transaction. Forinformation about tracking orders, see GettingStarted with CyberSource Advanced for the SimpleOrder API.ccAuthService (R)String (50)Chase Pay Using the Simple Order API 14

Appendix ATable 2API FieldsRequest Fields (Continued)FieldDescriptionUsed By:Required (R) orOptional (O)Data Type(Length)paymentNetworkTokentransactionTypeType of transaction that provided the token data. Thisvalue does not specify the token service provider; itspecifies the entity that provided you with informationabout the token.ccAuthService (R)String (1)Set the value for this field to 1.paymentNetworkTokenrequestorIDValue that identifies your business and indicates thatthe cardholder’s account number is tokenized. Thisvalue is assigned by the token service provider and isunique within the token service provider’s database.ccAuthService (R)String (1)paymentSolutionIdentifies Chase Pay as the payment solution that isbeing used for the transaction:ccAuthService (R)String (3)Set the value for this field to 007.Note This unique ID differentiates digital solutiontransactions within the CyberSource platform forreporting purposes.purchaseTotals currencyCurrency used for the order: Value: USDccAuthService (R)String (5)purchaseTotalsgrandTotalAmountGrand total for the transaction. This value cannot benegative. You can include a decimal point (.), but youcannot include any other special characters.CyberSource truncates the amount to the correctnumber of decimal places.ccAuthService (R)String (15)Chase Pay Using the Simple Order API 15

Appendix AAPI FieldsReply FieldsBecause CyberSource can add reply fields and reason codes at any time: You must parse the reply data according to the names of the fieldsinstead of the field order in the reply. For more information about parsingreply fields, see the documentation for your client. Your error handler should be able to process new reason codes withoutproblems. Your error handler should use the decision field to determine the result ifit receives a reply flag that it does not recognize.Your payment processor can include API reply fields that are not documented in thisguide. See Credit Card Services Using the Simple Order API for detailed descriptions ofadditional API reply fields.Table 3Reply FieldsFieldDescriptionReturned ByData Type& LengthccAuthReply amountAmount that was authorized.ccAuthReplyString (15)ccAuthReplyauthorizationCodeAuthorization code. Returned only when theprocessor returns this value.ccAuthReplyString (7)ccAuthReplyauthorizedDateTimeTime of authorization.ccAuthReplyDate andtime (20)ccAuthReply avsCodeAVS results. See Credit Card Services Using theSimple Order API for a detailed list of AVS codes.ccAuthReplyString (1)ccAuthReplyavsCodeRawAVS result code sent directly from the processor.Returned only when the processor returns thisvalue.ccAuthReplyString (10)ccAuthReply cvCodeCVN result code. See Credit Card Services Usingthe Simple Order API for a detailed list of CVNcodes.ccAuthReplyString (1)ccAuthReplycvCodeRawCVN result code sent directly from the processor.Returned only when the processor returns thisvalue.ccAuthReplyString (10)ccAuthReplyprocessorResponseFor most processors, this is the error message sentdirectly from the bank. Returned only when theprocessor returns this value.ccAuthReplyString (10)ccAuthReplyreasonCodeNumeric value corresponding to the result of thecredit card authorization request. See Credit CardServices Using the Simple Order API for a detailedlist of reason codes.ccAuthReplyInteger (5)Chase Pay Using the Simple Order API 16

Appendix ATable 3API FieldsReply Fields (Continued)FieldDescriptionReturned ByData Type& LengthccAuthReplyreconciliationIDReference number for the transaction. This value isnot returned for all processors.ccAuthReplyString (60)decisionSummarizes the result of the overall request.Possible values:ccAuthReplyString (6)ccAuthReplyString (100)invalidField 0.N ACCEPT ERROR REJECT REVIEW: Returned only when you useCyberSource Decision Manager.Fields in the request that contained invalid data.For information about missing or invalid fields, seeGetting Started with CyberSource Advanced for theSimple Order API.merchantReferenceCodeOrder reference or tracking number that youprovided in the request. If you included multi-bytecharacters in this field in the request, the returnedvalue might include corrupted characters.ccAuthReplyString (50)missingField 0.NRequired fields that were missing from the request.ccAuthReplyString (100)For information about missing or invalid fields, seeGetting Started with CyberSource Advanced for theSimple Order API.purchaseTotals currencyCurrency used for the order. For the possiblevalues, see the ISO Standard Currency Codes.ccAuthReplyString (5)reasonCodeNumeric value corresponding to the result of theoverall request. See Credit Card Services Using theSimple Order API for a detailed list of reason codes.ccAuthReplyInteger (5)requestIDIdentifier for the request.ccAuthReplyString (26)requestTokenRequest token data created by CyberSource foreach reply. The field is an encoded string thatcontains no confidential information such as anaccount or card verification number. The string cancontain a maximum of 256 characters.ccAuthReplyString (256)Chase Pay Using the Simple Order API 17

customer logs in to their Chase Pay account and chooses the card with which to pay. To process Chase Pay transactions: Step 1 Integrate the Chase Pay lightbox (iFrame). Step 2 Request the Chase Pay API to retrieve the payment network token, the expiration date, the cryptogram, an