Transcription
Visa Click to PaySimple Order APIDeveloper Guide
2021. Cybersource Corporation. All rights reserved.Cybersource Corporation (Cybersource) furnishes this document and the software described in this document underthe applicable agreement between the reader of this document (You) and Cybersource (Agreement). You may use thisdocument and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in theAgreement, the information contained in this document is subject to change without notice and therefore should not beinterpreted in any way as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liabilityfor any errors that may appear in this document. The copyrighted software that accompanies this document is licensedto You for 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 this documentin a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, orotherwise, without the prior written consent of Cybersource.Restricted Rights LegendsFor Government or defense agencies: Use, duplication, or disclosure by the Government or defense agencies is subject torestrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similarclauses in the FAR and NASA FAR Supplement.For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d)of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CybersourceCorporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws ofthe 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 the UnitedStates and other countries. All other trademarks, service marks, registered marks, or registered service marks are theproperty of their respective owners.Version: 21.02Visa Click to Pay 2
ContentsRecent Revisions to This Document. 4About This Guide. 5Audience and Purpose. 5Text and Command Conventions.5Related Documentation. 5Cybersource Documents. 5Visa Click to Pay Documents. 6Customer Support. 6Integrating Visa Click to Pay into Your System. 7Requirements.7Supported Countries. 7Visa Click to Pay Process. 8Getting Visa Click to Pay Data. 8Create a Visa Click to Pay Data Request.9Using 3D Secure with Visa Click to Pay.9Testing 3D Secure 2.x with Visa Click to Pay. 10Using Decision Manager with Visa Click to Pay. 11API Fields. 12Formatting Restrictions. 12Data Type Definitions. 12Simple Order API Fields. 13Request Fields.13Response Fields. 15Simple Order API Examples. 27Name-Value Pair Examples.27XML Examples. 28Reason Codes. 31Supported Countries, Regions, and Payment Currencies.32Visa Click to Pay - Contents 3
Recent Revisions to This DocumentReleaseChanges21.02Updated Using 3D Secure with Visa Click to Pay (on page9). Added Testing 3D Secure 2.x with Visa Click to Pay(on page 10).21.0119.0419.0319.0219.01Changed the name of Visa Checkout to Visa Click to Pay.Updated Supported Countries, Regions, and PaymentCurrencies (on page 32).Updated the enrollment URL. See Visa Click to PayDocuments (on page 6).Updated countries, regions, and currencies. SeeSupported Countries, Regions, and Payment Currencies(on page 32).Updated the XML request example. See Visa Click to PayData Request (on page 28).Added the vcReply newUser response field. SeevcReply newUser (on page 23).Changed the name of Mastercard SecureCode toMastercard Identity Check.Changed the name of Verified by Visa to Visa Secure.Added the following request fields. See Request Fields(on page 13). wallet discountAmount wallet eventType wallet giftWrapAmount wallet promotionCode wallet subtotalAmount wallet totalPurchaseAmountVisa Click to Pay - Recent Revisions to This Document 4
About This GuideAudience and PurposeThis guide is written for application developers who want to use the Cybersource Simple Order APIto integrate Visa Click to Pay into their order management system.Implementing Cybersource services requires software development skills. You must write code thatuses the API request and response fields to integrate the Cybersource services into your existingorder management system.Text and Command ConventionsConventionUsageboldField and service names in text; for example:screen textInclude the getVisaCheckoutDataService run field. XML elements Code examples Values for API fields; for example:Set the ccAuthService run field to true.Related DocumentationCybersource Documents Getting Started with Cybersource Advanced for the Simple Order API (PDF HTML) Credit Card Services Using the Simple Order API (PDF HTML) Payer Authentication Using the Simple Order API (PDF HTML)Visa Click to Pay - About This Guide 5
Refer to the Support Center for complete Cybersource technical documentation:http://www.cybersource.com/support center/support documentationVisa Click to Pay Documents Getting Started with Visa Click to Pay (published by Visa) Visa Click to Pay JavaScript Integration GuideTo obtain these documents, contact your local Cybersource sales sYou can also obtain these documents by signing up for a Visa Click to Pay developer account:https://developer.visa.com/#enrollCustomer SupportFor support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportVisa Click to Pay - About This Guide 6
Integrating Visa Click to Pay into Your SystemVisa Click to Pay is Visa’s solution for e-commerce payments based upon the EMV Secure RemoteCommerce (EMV SRC) standards and specifications. With EMV SRC, a single payment profile canbe used with a variety of consumer devices and participating online merchants. The standardsinclude a common payment icon and user experience for card-based digital transactions, supportfor cardholder verification methods, and a common data payload built on primary account numbers(PANs) and the ability to support network tokens.Requirements You must have a Visa Click to Pay merchant account. If you do not already have a Visa Clickto Pay merchant account, contact your local Cybersource sales representative: http://www.cybersource.com/locations You must have a Cybersource account. If you do not already have a Cybersource account,contact your local Cybersource sales representative. You must contact Cybersource Customer Support to have your account configured for Visa Clickto Pay. When you use the Simple Order API in XML format, you must use version 1.105 or later of theXML schema. You must be familiar with the Cybersource credit card services as described in Credit CardServices Using the Simple Order API. . If you are including payer authentication in your Visa Click to Pay implementation, youmust be familiar with the Cybersource payer authentication services as described in PayerAuthentication Using the Simple Order API. .Supported CountriesFor a list of the countries and associated currencies from which you can accept Visa Click to Paypayments, refer to Supported Countries, Regions, and Payment Currencies (on page 32).Visa Click to Pay - Integrating Visa Click to Pay into Your System 7
Visa Click to Pay ProcessVisa Click to Pay uses Visa Checkout services and API fields.1. You send data to Visa Click to Pay to display the Visa Click to Pay button on your checkout page.For details about this step, contact your Cybersource sales representative and consult GettingStarted with Visa Click to Pay (published by Visa). To obtain this document, see Visa Click toPay Documents (on page 6).2. You retrieve the Visa Click to Pay payment data so that you can display it to your customer.However, you cannot retrieve the PAN unless your account is configured for it. See Getting VisaClick to Pay Data (on page 8). The primary account number (PAN) is not required in orderto process a Visa Click to Pay transaction.3. Include the following required fields: ccAuthService run merchantID merchantReferenceCode paymentSolution purchaseTotals currency purchaseTotals grandTotalAmount or at least one item # unitPrice field vc orderIDFor descriptions of these fields, see Credit Card Services Using the Simple Order API.4. Cybersource obtains payment data from Visa Click to Pay and includes it in the authorizationrequest that is sent to the processor.5. For follow-on transactions such as full authorization reversal, capture, and credit, you mustinclude the following fields in your request in addition to the required fields documented inCredit Card Services Using the Simple Order API. paymentSolution vc orderIDGetting Visa Click to Pay DataVisa Click to Pay uses Visa Checkout services and API fields.Visa Click to Pay - Integrating Visa Click to Pay into Your System 8
The Visa Checkout data service enables you to receive the decrypted Visa Click to Pay data in theresponse message. However, you cannot retrieve the PAN unless your account is configured for it. Youcan use the retrieved data to help the customer confirm the purchase.See Simple Order API Fields (on page 13) for: Descriptions of these required request fields Descriptions of all response fieldsCreate a Visa Click to Pay Data Request1. Set the getVisaCheckoutDataService run field to true.2. Do not include any other Cybersource services in the request.3. Include the following required fields in the request: getVisaCheckoutDataService run merchantID merchantReferenceCode paymentSolution vc orderIDUsing 3D Secure with Visa Click to PayPayer authentication is the Cybersource implementation of 3D Secure.For Visa Click to Pay, Cybersource supports the following kinds of payer authentication: American Express SafeKey Mastercard Identity Check Visa SecureTo integrate payer authentication see: Credit Card Services Using the Simple Order API Payer Authentication Using the Simple Order APIVisa Click to Pay - Integrating Visa Click to Pay into Your System 9
When you implement 3D Secure 2.x with Visa Click to Pay, you must integrate the Cardinal CruiseDirect API version of Payer Authentication as described in the Payer Authentication Using the SimpleOrder API and include the following fields: paymentSolution –set to visacheckout vc orderID –set to callID field in the visacheckout reply payloadContact customer support to configure your account to support this integration to ensure the correctStepUpURL fields are returned by payer authentication. If you have previously on-boarded with 3DSecure 1 or 3D Secure 2.x Hybrid or Standard Payer Authentication methods you will still need tocontact customer support.Important: With Visa Click to Pay, you must include the payer authentication enrollmentservice payerAuthEnrollService and the credit card authorization service ccAuthService inthe same request message in order to decrypt the primary account number (PAN) and completethe rest of the payer authentication flow. When you submit a separate request message for eachservice, the payer authentication enrollment service payerAuthEnrollService request fails.Testing 3D Secure 2.x with Visa Click to PayUse the card number specified in the test with the card’s expiration date set to the month of Januaryand the current year plus three. For example, for 2021, use 2024. You also need the minimumrequired fields for an order. Be sure to remove spaces in card numbers when testing.Important: You must obtain credit card test card numbers from your Cybersource accountrepresentative.The XID values are included in 3D Secure 2.x test cases for legacy reasons. Only Mastercardtransactions do not return XID.While the 3D Secure version and directory server transaction ID fields are returned for the CheckEnrollment and Validate Authentication services, this data is not included in the 3D Secure 2.x testcases.Important: Mastercard requires that the 3D Secure version and directory server transactionID be included along with all pertinent data in your authorization request.Visa Click to Pay - Integrating Visa Click to Pay into Your System 10
Using Decision Manager with Visa Click to PayWhile the Visa Click to Pay response contains many of the fields necessary to run Decision Manager itdoes not include these essential Decision Manager fields: Device fingerprint True IP addressYou must capture these fields independently.Visa Click to Pay - Integrating Visa Click to Pay into Your System 11
API FieldsFormatting RestrictionsUnless otherwise noted, all field names are case sensitive and all fields accept special characters suchas @, #, and %.The values of the item # fields must not contain carets ( ) or colons (:) because these characters arereserved for use by the services.Values for request-level and item-level fields must not contain new lines or carriage returns.However, they can contain embedded spaces and any other printable characters. All leading andtrailing spaces are removed.For Moneris, values for request-level and item-level fields must not contain these special characters:ampersands (&), single quotes (‘), double quotes (“), less-than signs ( ), and greater-than signs ( ).Data Type DefinitionsFor more information about these data types, see the World Wide Web Consortium (W3C) XMLSchema Part 2: Datatypes Second Edition.Data TypeDate and timeDescriptionFormat is YYYY-MM-DDThh:mm:ssZwhere: T separates the date and the time. Z indicates Coordinated Universal Time (UTC), also known asGreenwich Mean Time (GMT).IntegerExample: 2021-01-11T22:47:57Z is January 11, 2021, at 22:47:57(10:47:57 p.m.).Whole number {., -3, -2, -1, 0, 1, 2, 3, .}Visa Click to Pay - API Fields 12
Data TypeStringDescriptionSequence of letters, numbers, spaces, and special charactersSimple Order API FieldsRequest FieldsRequest FieldsFieldDescriptionUsed By:Required (R)or Optional (O)Data Type& LengthgetVisaCheckoutDa Whether to includetaService rungetVisaCheckoutDataService inyour request. Possible values:getVisaCheckoutDataService (R)String (5) true: Include the service inyour tion false (default): Do not includethe service in your request.Your Cybersource merchant ID. Use getVisaCheckoutthe same merchant ID for evaluation, DataService (R)testing, and production.String (30)Type of payment solution that isbeing used for the transaction.The value for Visa Click to Pay isvisacheckout.String (12)Order reference number orgetVisaCheckouttracking number generated byDataService (R)you. Cybersource recommendsthat you send a unique value foreach transaction so that you canperform meaningful searches for thetransaction. For information abouttracking orders, see Getting Startedwith Cybersource Advanced for theSimple Order API.getVisaCheckoutDataService (R)String (50)Visa Click to Pay - API Fields 13
Request Fields (continued)FieldDescriptionUsed By:Required (R)or Optional (O)Data Type& Lengthvc orderIDIdentifier for the Visa Click to Payorder. Visa Click to Pay providesa unique order ID for everytransaction in the Visa Click to PaycallID field.getVisaCheckoutDataService (R)String (48)Type of transaction event. Possiblevalues:ics auth (O)String (15)ics auth (O)String (14)ics auth (O)String(100)wallet discountAm Total discount amount. The discount ics auth (O)ountamount must be a positive value.Includes a decimal point and amaximum of four decimal places.wallet eventTypeString (14) Create: Card-on-file saved(outside of a purchase flow). Confirm: Order placed. Confirm COF: Order placedusing a card-on-file. Cancel: Order canceled. Fraud: Order rejected by risk orfraud review. Other: None of the eventsabove, or a payment eventafter a Confirm or Confirm COForder event.The default value is Confirm.wallet giftWrapAm Gift-wrapping total that is sent afterounta successful authorization. Includesa decimal point and a maximum offour decimal places.wallet promotionC Promotion code that is sent after aodesuccessful authorization.The valid characters for the walletpromotion code are: NumbersVisa Click to Pay - API Fields 14
Request Fields (continued)FieldDescriptionUsed By:Required (R)or Optional (O)Data Type& Length Letters The following specialcharacters:asterisk (*), at (@), dash (-),dollar sign ( ), exclamationpoint (!), hash (#), parentheses( ( ) ), percent (%), plus ( ),underscore ( ), comma (,), andspace.wallet subtotalAmountwallet totalPurchaseAmountUse a period to separatemultiple promotion codes.Subtotal amount that containsics auth (O)purchase details. Cybersource doesnot validate this field. Includes adecimal point and a maximum of twodecimal places.Total purchase amount. By default,Cybersource uses the grand totalamount of the authorization.Includes a decimal point and amaximum of two decimal places.String (10)ics auth (O)String (10)Response FieldsVisa Click to Pay returns all decrypted data to you, except the PAN, unless your account is configuredto receive it. The purpose of the fields in the Visa Click to Pay encrypted payment data is to passinformation from Visa Click to Pay to the processor. Consequently, many decrypted fields and valuesmight not be useful to you.Response FieldsFieldDescriptionData Type& LengthbillTo cityDecrypted city in the billing address.String(100)billTo countyName of the municipality. This value is commonfor addresses in Mexico.String (80)Visa Click to Pay - API Fields 15
Response Fields (continued)FieldDescriptionData Type& LengthbillTo countryDecrypted country in the billing address. For thepossible values, see ISO Standard Country Codes.String (2)billTo defaultIndicatorShipping address is flagged as the default shippingaddress by the customer. Possible values:String (5) true: This billing address is the customer’sdefault address. false: This billing address is not thecustomer’s default billing address.billTo nameDecrypted customer name.billTo pointOfReferenceDecrypted location information. In some countries, Stringsuch as Mexico and India, it is common to ask for(140)a point of reference or landmark for the billing orshipping address. For example, “Across the streetfrom the grocery store.”billTo phoneNumberbillTo postalCodebillTo statebillTo street1billTo street2billTo street3billTo street4card accountNumberString(256)Decrypted customer phone number.String (30)Decrypted postal code in the billing address.String(100)Decrypted first line of the street address in thebilling address as it appears on the credit cardissuer’s records.String(100)Decrypted additional address information in thebilling address.String(100)Decrypted state or province in the billing address.For possible values, see State, Province, andTerritory Codes for the United States and Canada.Decrypted additional address information in thebilling address.Decrypted additional address information in thebilling address.Decrypted customer’s credit card number.Returned only when your account is configured toreceive it.String (3)String(100)String(100)String (20)Visa Click to Pay - API Fields 16
Response Fields (continued)Fieldcard expirationMonthcard expirationYearcard prefixcard suffixdecisionDescriptionData Type& LengthFor more information about receiving the PAN,see Getting Started with Visa Click to Pay (PDF HTML)Getting Started with Visa Secure RemoteCommerce (PDF HTML).Decrypted two-digit month in which the creditcard expires.Format: MM.Possible values: 01 through 12.Stringwithnumbersonly (2)Decrypted credit card prefix. This value is the firstsix digits of the cardholder’s account number.Stringwithnumbersonly (6)Decrypted four-digit year in which the credit cardexpires.Format: YYYY.Decrypted credit card suffix. This value is the lastfour digits of the cardholder’s account number.You can use this value on the receipt that you giveto the cardholder.Summarizes the result of the overall request.Possible values:Stringwithnumbersonly (4)Stringwithnumbersonly (4)String (6) ACCEPT ERROR REJECTFor details about these values, see theinformation about handling replies in GettingStarted with Cybersource Advanced for theSimple Order API.getVisaCheckoutDataRepl Numeric value corresponding to the result of they reasonCodeVisa Click to Pay decryption request. See ReasonCodes (on page 31).invalidField 0 throughinvalidField NInteger (5)Fields in the request that have invalid data. ForStringinformation about missing or invalid fields, see(100)Getting Started with Cybersource Advanced for theSimple Order API.Visa Click to Pay - API Fields 17
Response Fields (continued)FieldmerchantReferenceCodemissingField 0 throughmissingField NpersonalID numberpurchaseTotals currencyreasonCoderequestIDDescriptionData Type& LengthNote: These fields are included as an aidto software developers only. Do not use thesefields to interact with your customers.Order reference number or tracking numberString (50)that you provided in the request. If you includedmultibyte characters in this field in the request, thereturned value might include corrupted characters.Required fields that were missing from therequest. For information about missing or invalidfields, see Getting Started with CybersourceAdvanced for the Simple Order API.String(100)Note: These fields are included as an aidto software developers only. Do not use thesefields to interact with your customers.Personal ID number. Only returned if your account String (18)is configured to receive personally identifiableinformation (PII) such as a primary accountnumber (PAN).Decrypted currency used for the order. For thepossible values, see ISO Standard Currency Codes.Numeric value corresponding to the result of theoverall request. See Reason Codes (on page 31).String (3)Integer (5)Identifier for the request. This value is provided by String (26)Cybersource.shipTo addressVerificatio Decrypted verification status for the shippingnStatusaddress. The verification status is determined byVisa Click to Pay. Possible values:String (12) FAILED NOT VERIFIED VERIFIEDshipTo cityDecrypted city of the shipping address.String(100)Visa Click to Pay - API Fields 18
Response Fields (continued)FieldDescriptionshipTo countryDecrypted country of the shipping address. For the String (2)possible values, see ISO Standard Country Codes.shipTo defaultData Type& LengthStatus of the default shipping address. Determineswhether it is flagged as the default shippingaddress by the customer. Possible values:String (5) true: This shipping address is the customer’sdefault shipping address. false: This shipping address is not thecustomer’s default shipping address.shipTo idDecrypted identifier for the shipping address. Thisvalue is generated by Visa Click to Pay.shipTo phoneNumberDecrypted phone number for the shipping address. String (30)shipTo nameshipTo pointOfReferenceshipTo postalCodeshipTo stateshipTo street1shipTo street2shipTo street3shipTo street4vcReply ageOfAccountDecrypted name of the recipient.String (36)String(256)In some countries, such as Mexico and India,it is common to ask for a point of reference orlandmark for the billing or shipping address. Forexample, “Across the street from the grocerystore.”String(140)Decrypted state or province of the shippingaddress. For possible values, see State, Province,and Territory Codes for the United States andCanada.String (3)Decrypted postal code of the shipping address.Consists of 5 to 9 digits.String(100)Decrypted first line of the shipping address.String(100)Decrypted third line of the shipping address.String(100)Decrypted second line of the shipping address.Decrypted fourth line of the shipping address.String(100)String(100)Number of days since the Visa Click to Pay account Numericwas created.(9)Visa Click to Pay - API Fields 19
Response Fields (continued)FieldDescriptionData Type& LengthvcReply alternateShippingAddressCountryCodeDecrypted country code for the alternate shippingaddress.String (2)vcReply avsCodeRawDecrypted raw (unmapped) AVS code provided byVisa Click to Pay.String (10)vcReply alternateShippingAddressPostalCodeDecrypted postal code for the alternate shippingaddress.vcReply billingAddressAd Extracts and provides the additional locationditionalLocationfrom the first line of the billing address. In somecountries, such as Mexico and India, Visa Click toPay obtains street information as a separate lineitem from the customer.String (10)String(100)vcReply billingAddressStr Extracts and provides the street name from theeetNamefirst line of the billing address. In countries suchas Mexico and India, Visa Click to Pay obtainsstreet information as a separate line item from thecustomer.String(116)vcReply cardArt # height Decrypted height for the card art in pixels.Possible values: 1 through 4096. Visa Click toPay provides the card art values. Any numberof vcReply cardArt # height fields that can beincluded in the encrypted payment data.PositiveInteger (4)vcReply cardFirstNameString(256)vcReply cardArt # fileNamevcReply cardArt # widthvcReply cardGroupDecrypted URL, including file name, for the cardart. Visa Click to Pay provides the card art values.Any number of vcReply cardArt # fileNamefields that can be included in the encryptedpayment data.String(100)Decrypted width for the card art in pixels.Possible values: 1 through 4096. Visa Click toPay provides the card art values. Any numberof vcReply cardArt # width fields that can beincluded in the encrypted payment data.PositiveInteger (4)Decrypted card group. Possible values:String (12)Customer’s first name as printed on the card. CREDIT DEBIT DEBIT/CREDITVisa Click to Pay - API Fields 20
Response Fields (continued)FieldDescriptionData Type& Lengthv
Visa Click to Pay uses Visa Checkout services and API fields. 1.You send data to Visa Click to Pay to display the Visa Click to Pay button on your checkout page. For details about this step, contact your Cybersource sales representative and consult Getting Started with Visa Click to Pay (published by Visa). To obtain this document, see Visa .
