Transcription
Title PageSecure Acceptance Hosted CheckoutIntegration Guide
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.Revision: 21.022
CONTENTSContentsRecent Revisions to This DocumentAbout This Guide79Audience and Purpose9Web Site Requirements9Conventions 10Important and Warning Statements 10Text and Command Conventions 10Related DocumentsCustomer SupportChapter 11112Secure Acceptance Hosted CheckoutRequired Browsers1314Secure Acceptance Profile14Secure Acceptance Transaction Flow15Payment Tokens 16Tokens That Represent a Card or Bank Account OnlyOne-click Checkout17Subscription PaymentsLevel II and III Data1718BIN Lookup 19Requirement 19Request BIN LookupPayouts Payment Tokens1919Go-Live with Secure AcceptanceChapter 217Payment Configuration2021Creating a Hosted Checkout Profile21Payment Method Configuration 22Adding Card Types and Currencies 23Payer Authentication Configuration 24Configuring Payer Authentication 24Secure Acceptance Hosted Checkout Integration Guide 3
ContentsEnabling Automatic Authorization Reversals 25Enabling Echecks 26Visa Click to Pay Configuration 26Configuring Visa Click to Pay 27Enabling the Payment Method for Visa Click to PayEnabling PayPal Express Checkout 28Security Keys 29Creating Security Keys2730Checkout Configuration 31Configuring the Payment Form 31Configuring Billing Information Fields 32Configuring Shipping Information Fields 33Configuring Echeck Information Fields 34Configuring Order Review Details 34Merchant Notifications 35Configuring Merchant Notifications35Customer Receipts 36Configuring Customer Notifications36Customer Response Page 37Configuring a Cybersource Hosted Response Page 38Configuring a Custom Hosted Response Page 38Configuring a Custom Cybersource Hosted Response PageConfiguring a Custom Cancel Response Page 3939Custom Checkout Appearance 40Changing Header Content 40Changing Body Color and Font Settings 40Changing Background and Text Color of the Total Amount 41Changing the Progress Bar Color 42Changing Color and Text on Pay or Finish Button 42Changing Footer Color and Uploading a Small Logo or Image 43Checkout Language LocalizationActivating a Profile 45Additional Profile Options4346Samples in Scripting Languages 46Sample Transaction Process Using JSPChapter 3Portfolio Management for ResellersCreating a Hosted Checkout Profile464848Payment Method Configuration 49Adding Card Types and Currencies 50Payer Authentication Configuration 51Configuring Payer Authentication 51Enabling Automatic Authorization Reversals52Secure Acceptance Hosted Checkout Integration Guide 4
ContentsEnabling Echecks 53Visa Click to Pay Configuration 53Configuring Visa Click to Pay 54Enabling PayPal Express Checkout 55Service Fees 55Enabling Service Fees 56Security Keys 56Creating Security Keys57Checkout Configuration 58Configuring the Payment Form 58Configuring Billing Information Fields 59Configuring Shipping Information Fields 60Configuring Echeck Information Fields 61Configuring Order Review Details 61Merchant Notifications 62Configuring Merchant Notifications62Customer Receipts 63Configuring Customer Notifications63Customer Response Page 64Configuring a Cybersource Hosted Response Page 65Configuring a Custom Hosted Response Page 65Configuring a Custom Cybersource Hosted Response PageConfiguring a Custom Cancel Response Page 6666Custom Checkout Appearance 67Changing Header Content 67Changing Body Color and Font Settings 68Changing Background and Text Color of the Total Amount 68Changing the Progress Bar Color 69Changing Color and Text on Pay or Finish Button 69Changing Footer Color and Uploading a Small Logo or Image 70Activating a Profile 71Additional Profile OptionsChapter 4Payment Transactions7172Endpoints and Transaction TypesRequired Signed Fields7274Payment Tokens 74Creating a Payment Card TokenCreating an Echeck Token 7774Payment Token Transactions 79One-Click 79Requesting an Echeck Transaction with a TokenRecurring Payments8183Secure Acceptance Hosted Checkout Integration Guide 5
ContentsInstallment Payments85Payment Token Updates 87Updating a Payment Card TokenUpdating an Echeck Token 89Chapter 5Chapter 6Decision Manager91Test and View TransactionsTesting Transactions879393Viewing Transactions in the Business CenterAppendix A API Fields9495Data Type DefinitionsRequest Fields96Response FieldsReason Codes95137175Types of Notifications178AVS Codes 179International AVS Codes 179U.S. Domestic AVS Codes 180CVN Codes182Appendix B American Express SafeKey Response CodesAppendix C Iframe ImplementationClickjacking PreventionEndpoints183184185185Appendix D Visa Secure Response Codes186Secure Acceptance Hosted Checkout Integration Guide 6
ReleaseChanges21.02Added the request field cryptocurrency purchase, page 104.21.01Changed the name of Visa Checkout to Visa Click to Pay and removed Visa Secure RemoteCommerce.REVISIONSRecent Revisions to ThisDocumentUpdated the first important note in "Secure Acceptance Hosted Checkout," page 13.Updated the request field payer authentication challenge code.Added the profile id and req profile id fields. See Chapter 4, "Payment Transactions," onpage 72, and Appendix A, "API Fields," on page 95.20.05Added the following healthcare request fields. See "Request Fields," page 96. health care # amount health care # amount type industry datatypeUpdated the first Important note in Appendix C, "Iframe Implementation," on page 184.Removed support for PINless debit cards.Removed support for unsigned fields.Removed support for the profile id and req profile id fields.20.04Changed CyberSource through VisaNet to Visa Platform Connect.Updated the customer ip address request field.Added the following request fields. See "Request Fields," page 96. customer browser color depth customer browser java enabled customer browser javascript enabled customer browser language customer browser screen height customer browser screen width customer browser time difference payer authentication acquirer country payer authentication acs window size payer authentication indicator payer authentication merchant fraud rate payer authentication merchant name payer authentication merchant score payer authentication prior authentication dataSecure Acceptance Hosted Checkout Integration Guide 7
Recent Revisions to This DocumentReleaseChanges20.04 (continued) payer authentication prior authentication method payer authentication prior authentication reference id payer authentication prior authentication timeAdded the following response fields. See "Response Fields," page 137.20.03 card type name payer authentication acs transaction id payer authentication challenge type payer authentication network score payer authentication pares status reason payer authentication type payer authentication white list status payer authentication white list status source payment account referenceAdded endpoints and Business Center URLs for transactions in India.Secure Acceptance Hosted Checkout Integration Guide 8
ABOUT GUIDEAbout This GuideAudience and PurposeThis guide is written for merchants who want to accept payments using SecureAcceptance Hosted Checkout and who do not want to handle or store sensitive paymentinformation on their own servers.Using Secure Acceptance Hosted Checkout requires minimal scripting skills. You mustcreate a security script and modify your HTML form to invoke Secure Acceptance. You willalso use the Business Center to review and manage orders.Web Site RequirementsYour web site must meet the following requirements: It must have a shopping-cart, customer order creation software, or an application forinitiating disbursements to send funds to payment accounts. It must contain product pages in one of the supported scripting languages. See"Sample Transaction Process Using JSP," page 46. The IT infrastructure must be Public Key Infrastructure (PKI) enabled to useSSL-based form POST submissions. The IT infrastructure must be capable of digitally signing customer data prior tosubmission to Secure Acceptance Hosted Checkout.Secure Acceptance Hosted Checkout Integration Guide 9
About This GuideConventionsImportant and Warning StatementsAn 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 transaction type field. Items that you are instructed to act upon; for example:Click Save.Screen text Code examples and samples. Text that you enter in an API environment; for example:Set the transaction type field to create payment token.Secure Acceptance Hosted Checkout Integration Guide 10
About This GuideRelated DocumentsRefer to the Support Center for complete Cybersource technical pport/technical-documentation.htmlTable 1Related DocumentsSubjectDescriptionBusiness CenterBusiness Center User Guide (PDF HTML)—describes how to use theBusiness Center.DecisionManagerThe following documents describe how to integrate and use the DecisionManager services.Electronic checks Decision Manager Using the SCMP API Developer Guide (PDF HTML) Decision Manager Using the Simple Order API Developer Guide (PDF HTML)The following documents describe how to integrate and use the electroniccheck services: Electronic Check Services Using the SCMP API (PDF HTML) Electronic Check Services Using the Simple Order API (PDF HTML)Level II andLevel IIILevel II and Level III Processing Using Secure Acceptance (PDF HTML)—describes each Level II and Level III field and processing Level II and LevelIII transactions using Secure Acceptance.PayerAuthenticationThe following documents describe how to integrate and use the payerauthentication services:Payment cards Payer Authentication Using the SCMP API (PDF HTML) Payer Authentication Using the Simple Order API (PDF HTML)The following documents describe how to integrate payment cardprocessing into an order management system: Credit Card Services Using the SCMP API (PDF HTML) Credit Card Services Using the Simple Order API (PDF HTML)Payment securitystandardsPayment Card Industry Data Security Standard (PCI DSS)—web site offersstandards and supporting materials to enhance payment card data security.PayoutsThe following documents describe how to integrate and use the Payoutsfunctionality:PayPal ExpressCheckout Payouts Using the SCMP API (PDF HTML) Payouts Using the Simple Order API (PDF HTML)The following documents describe how to integrate and use the PayPalExpress Checkout services: PayPal Express Checkout Services Using the SCMP API (PDF HTML) PayPal Express Checkout Services Using the Simple Order API (PDF HTML).Secure Acceptance Hosted Checkout Integration Guide 11
About This GuideTable 1Related Documents (Continued)SubjectDescriptionRecurring BillingThe following documents describe how to create customer subscriptionsand use payment tokens for recurring and installment payments: Recurring Billing Using the Business Center (PDF HTML) Recurring Billing Using the SCMP API (PDF HTML) Recurring Billing Using the Simple Order API (PDF HTML)ReportingBusiness Center Reporting User Guide (PDF HTML)—describes how toview and configure custom reports in the Business Center.SecureAcceptanceThe following documents describe how to integrate and use the SecureAcceptance Checkout API, along with processing a transaction with theservice fee sa Click to Pay Secure Acceptance Checkout API Integration Guide (PDF HTML) Secure Acceptance Checkout API Service Fee Guide (PDF)The following documents describe how to create tokens with a third-partyprovider and are available from Cybersource Customer Support: Tokenization with a Third-Party Provider Using the SCMP API Tokenization with a Third-Party Provider Using the Simple Order APIThe following documents describe how to integrate and use the tokenmanagement service: Token Management Service Using the SCMP API (PDF HTML) Token Management Service Using the Simple Order API (PDF HTML)Getting Started with Visa Click to Pay (PDF HTML)—describes how toenroll in Visa Click to Pay and create a Visa Click to Pay profile.Customer SupportFor support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportSecure Acceptance Hosted Checkout Integration Guide 12
CHAPTERSecure Acceptance HostedCheckout1Cybersource Secure Acceptance Hosted Checkout is your secure hosted customercheckout experience. It consists of securely managed payment forms or as a single pagepayment form for capturing payment card data, processing transactions, enabling you tosimplify your Payment Card Industry Data Security Standard (PCI DSS) compliance andreduce risks associated with handling and/or storing sensitive payment card information.You, the merchant, out-source capturing and managing sensitive payment card data toSecure Acceptance, which is designed to accept card payments.Secure Acceptance is designed to process transaction requests directly fromthe customer browser so that sensitive payment data does not pass throughyour servers. If you do intend to send payment data from your servers, use theREST API, SOAP Toolkit API, or the Simple Order API. Sending server-sidepayments using Secure Acceptance incurs unnecessary overhead and couldresult in the suspension of your Secure Acceptance profile and subsequentfailure of transactions.To create your customer’s Secure Acceptance experience, you take these steps:1Create and configure Secure Acceptance profiles.2Update the code on your web site to render the Secure Acceptance Hosted Checkout andimmediately process card transactions (see "Samples in Scripting Languages," page 46).Sensitive card data bypasses your network and is accepted by Secure Acceptancedirectly from the customer. Secure Acceptance processes the transaction on your behalfby sending an approval request to your payment processor in real time. See "SecureAcceptance Transaction Flow," page 15.3Use the response information to display an appropriate transaction response page to thecustomer. You can view and manage all orders in the Business Center (see "ViewingTransactions in the Business Center," page 94).Secure Acceptance Hosted Checkout Integration Guide 13
Chapter 1Secure Acceptance Hosted CheckoutRequired BrowsersYou must use one of these browsers in order to ensure that the checkout flow is fast andsecure:Desktop browsers: IE 10 or later Edge 13 or later Firefox 42 or later Chrome 48 or later Safari 7.1 or later Opera 37 or laterMobile browsers: iOS Safari 7.1 or later Android Browser 4.4 or later Chrome Mobile 48 or laterSecure Acceptance ProfileA Secure Acceptance profile consists of settings that you configure to create a customercheckout experience. You can create and edit multiple profiles, each offering a customcheckout experience (see "Custom Checkout Appearance," page 40). For example, youmight need multiple profiles for localized branding of your web sites.You can display amulti-step checkout process or a single page checkout (see "Checkout Configuration,"page 31) to the customer as well as configure the appearance and branding, paymentoptions, languages, and customer notifications.Secure Acceptance Hosted Checkout Integration Guide 14
Chapter 1Secure Acceptance Hosted CheckoutSecure Acceptance Transaction FlowThe Secure Acceptance Hosted Checkout transaction flow is illustrated in Figure 1 anddescribed below.Figure 11Secure Acceptance Hosted Checkout Transaction FlowThe customer clicks the pay button on your web site, which triggers an HTTPS POST thatdirects the customer to the hosted Secure Acceptance page that you configured in theBusiness Center. The HTTPS POST includes the signature and signed data fieldscontaining the order information.Hosted Checkout works best with JavaScript and cookies enabled in the customerbrowser.Your system should sign only Secure Acceptance request fields. To preventmalicious actors from impersonating Cybersource, do not allow unauthorizedaccess to the signing function.2Hosted Checkout verifies the signature to ensure that the order details were not amendedor tampered with and displays the Hosted Checkout page. The customer enters andsubmits payment details and/or their billing and shipping information. The customerconfirms the payment, and the transaction is processed.3It is recommended that you configure a custom receipt page in the Business Center (see"Merchant Notifications," page 35) so that the signed transaction response is sent back toSecure Acceptance Hosted Checkout Integration Guide 15
Chapter 1Secure Acceptance Hosted Checkoutyour merchant server through the browser. You must validate the response signature toconfirm that the response data was not amended or tampered with. Hosted Checkout canalso display a standard receipt page to your customer, and you can verify the result of thetransaction using the
Secure Acceptance Hosted Checkout Integration Guide 4 Contents Enabling Automatic Authorization Reversals 25 Enabling Echecks 26 Visa Click to Pay Configuration 26 Configuring Visa Click to Pay 27 Enabling the Payment Method for Visa Click to Pay 27 Enabling PayPal Express Checkout 28 Security Keys 29 Creating Security Keys 30
