Transcription
Title PageSecure Acceptance Checkout APIIntegration 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 Checkout APIRequired Browsers1314Secure Acceptance Profile14Secure Acceptance Transaction Flow15Payment Tokens 16Tokens That Represent a Card or Bank Account OnlySubscription PaymentsLevel II and III Data1718BIN Lookup 18Requirement 18Request BIN LookupPayouts Payment Tokens1919Go-Live with Secure AcceptanceChapter 217Payment Configuration2021Creating a Checkout API Profile21Payment Method Configuration 22Adding Card Types and Currencies 22Payer Authentication Configuration 23Secure Acceptance Checkout API Integration Guide 3
ContentsConfiguring Payer Authentication 23Enabling Automatic Authorization ReversalsEnabling Echecks 25Enabling PayPal Express Checkout 25Security Keys 26Creating Security Keys27Merchant Notifications 28Configuring Merchant Notifications28Customer Receipts 29Configuring Customer Notifications29Customer Response Page 30Configuring a Transaction Response PageActivating a Profile 31Additional Profile OptionsPortfolio Management for ResellersCreating a Checkout API Profile3131Samples in Scripting Languages 32Sample Transaction Process Using JSPChapter 324323333Payment Method Configuration 34Adding Card Types and Currencies 34Payer Authentication Configuration 35Configuring Payer Authentication 35Enabling Automatic Authorization ReversalsEnabling Echecks 37Enabling PayPal Express Checkout 38Service Fees 38Enabling Service Fees 38Security Keys 39Creating Security Keys40Merchant Notifications 41Configuring Merchant Notifications41Customer Receipts 42Configuring Customer Notifications42Customer Response Page 43Configuring a Transaction Response PageActivating a Profile 44Additional Profile Options364344Secure Acceptance Checkout API Integration Guide 4
ContentsChapter 4Payment Transactions45Endpoints and Transaction TypesRequired Signed Fields4546Payment Tokens 47Creating a Payment Card TokenCreating an Echeck Token 4947Payment Token Transactions 51Requesting a Payment Card Transaction with a TokenRecurring Payments55Installment Payments57Payment Token Updates 59Updating a Payment Card TokenUpdating an Echeck Token 61Chapter 5Decision ManagerChapter 6Test and View TransactionsTesting Transactions59636565Viewing Transactions in the Business CenterAppendix A API Fields516667Data Type DefinitionsRequest Fields68Response FieldsReason Codes67111151Types of Notifications154AVS Codes 155International AVS Codes 155U.S. Domestic AVS Codes 155CVN Codes157Appendix B American Express SafeKey Response CodesAppendix C Iframe ImplementationClickjacking Prevention158159159Secure Acceptance Checkout API Integration Guide 5
ContentsIframe Transaction Endpoints160Appendix D Visa Secure Response Codes161Secure Acceptance Checkout API Integration Guide 6
ReleaseChanges21.02Added the request field cryptocurrency purchase, page 79.21.01Updated the first important note in "Secure Acceptance Checkout API," page 13.REVISIONSRecent Revisions to ThisDocumentUpdated the request field payer authentication challenge code.Added the profile id and req profile id fields. See Chapter 4, "Payment Transactions," onpage 45, and Appendix A, "API Fields," on page 67.20.04Added the following healthcare request fields. See "Request Fields," page 68. health care # amount health care # amount type industry datatypeUpdated the first Important note in Appendix C, "Iframe Implementation," on page 159.Removed support for PINless debit cards.Removed support for the profile id and req profile id fields.20.03Changed CyberSource through VisaNet to Visa Platform Connect.Updated the customer ip address request field.Added the following request fields. See "Request Fields," page 68. 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 Checkout API Integration Guide 7
Recent Revisions to This DocumentReleaseChanges20.03 (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 111. 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 reference20.02Added endpoints and Business Center URLs for transactions in India.20.01Updated Example 11, "Request: Create a Payment Token for Installment Payments," onpage 57 and Example 11, "Request: Create a Payment Token for Installment Payments," onpage 57.Secure Acceptance Checkout API Integration Guide 8
ABOUT GUIDEAbout This GuideAudience and PurposeThis guide is written for merchants who want to customize and control their own customercheckout experience, including receipt and response pages. After the customization, youwill have full control to store and control customer information before sending it toCybersource to process transactions, and to use the Business Center to review andmanage all of your orders.Using the Secure Acceptance Checkout API requires moderate scripting skills. You mustcreate a security script and modify your HTML form to pass order information toCybersource.Web Site RequirementsYour web site must meet the following requirements: It must have a shopping-cart or customer order creation software. It must contain product pages in one of the supported scripting languages. See"Sample Transaction Process Using JSP," page 32. 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.Secure Acceptance Checkout API 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 Checkout API 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.PayPal ExpressCheckoutThe following documents describe how to integrate and use the PayPalExpress Checkout services:Recurring Billing PayPal Express Checkout Services Using the SCMP API (PDF HTML) PayPal Express Checkout Services Using the Simple Order API (PDF HTML).The 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)Secure Acceptance Checkout API Integration Guide 11
About This GuideTable 1Related Documents (Continued)SubjectDescriptionReportingBusiness Center Reporting User Guide (PDF HTML)—describes how toview and configure custom reports in the Business Center.Service FeesSecure Acceptance Checkout API Service Fee Guide (PDF)—describeshow to process a transaction with the service fee included.SecureAcceptanceThe following documents describe how to create a Secure Acceptanceprofile and render the Secure Acceptance Hosted Checkout, along withprocessing a transaction with the service fee included: Third-partytokensTokenManagementServiceSecure Acceptance Hosted Checkout Integration Guide (PDF HTML)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)Customer SupportFor support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportSecure Acceptance Checkout API Integration Guide 12
CHAPTERSecure AcceptanceCheckout API1Cybersource Secure Acceptance Checkout API provides a seamless customer checkoutexperience that keeps your branding consistent. You can create a Secure AcceptanceCheckout API profile and configure the required settings to set up your customer checkoutexperience.Secure Acceptance Checkout API can significantly simplify your Payment Card IndustrySecurity Standard (PCI DSS) compliance by sending sensitive payment card data directlyfrom your customer’s browser to Cybersource servers. Your web application infrastructuredoes not come into contact with the sensitive payment data and the transition is silent.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 checkout experience you will take these steps:1Create and configure Secure Acceptance Checkout API profiles.2Update the code on your web site to POST payment data directly to Cybersource fromyour secure payment form (see "Sample Transaction Process Using JSP," page 32).Cybersource processes the transaction on your behalf by sending an approval request toyour payment processor in real time. See "Secure Acceptance Transaction Flow,"page 15.3Use the response information to generate an appropriate transaction response page todisplay to the customer. You can view and manage all orders in the Business Center. Youcan configure the payment options, response pages, and customer notifications. See"Creating a Checkout API Profile," page 21.Secure Acceptance Checkout API Integration Guide 13
Chapter 1Secure Acceptance Checkout APIRequired 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. For example, you might want to offer different payment options fordifferent geographic locationsSecure Acceptance Checkout API Integration Guide 14
Chapter 1Secure Acceptance Checkout APISecure Acceptance Transaction FlowThe Secure Acceptance Checkout API transaction flow is illustrated in Figure 1 anddescribed below.Figure 11Secure Acceptance Checkout API Transaction FlowDisplay the checkout page on your customer’s browser with a form to collect their paymentinformation and include a signature to validate their order information (signed data fields).Your system should only sign Secure Acceptance request fields. To preventmalicious actors from impersonating Cybersource, do not allow unauthorizedaccess to the signing function.2The customer enters and submits their payment details (the unsigned data fields). Thetransaction request message, the signature, and the signed and unsigned data fields aresent directly from your customer’s browser to the Cybersource servers. The unsigned datafields do not pass through your network.Cybersource reviews and validates the transaction request data to confirm it has not beenamended or tampered with and that it contains valid authentication credentials.Cybersource processes the transaction and creates and signs the response message.The response message is sent to the customer’s browser as an automated HTTPS formPOST.Secure Acceptance Checkout API Integration Guide 15
Chapter 1Secure Acceptance Checkout APIIf the response signature in the response field does not match the signaturecalculated based on the response data, treat the POST as malicious anddisregard it.Secure Acceptance signs every response field. Ignore any response fields inthe POST that are not in the signed fields field.3The response HTTPS POST data contains the transaction result in addition to the maskedpayment data that was collected outside of your domain. Validate the response signatureto confirm that the response data has not been amended or tampered with.If the transaction type is sale, it is immediately submitted for settlement. If the transactiontype is authorization, use the Simple Order API to submit a capture request when goodsare shipped.4It is recommended that you implement the merchant POST URL notification (see"Merchant Notifications," page 28) as a backup means of determining the transactionresult. This method does not rely on your customer’s browser. You receive the transactionresult even if your customer lost connection after confirming the payment.Payment TokensContact Cybersource Customer Support to activate your merchant account forToken Management Services. You cannot use payment tokens until youraccount is activated and you have enabled payment tokens for SecureAcceptance (see "Creating a Checkout API Profile," page 21).Payment tokens are unique identifiers that replace sensitive payment information and thatcannot be mathematically reversed. Cybersource securely stores all the card information,replacing it with the payment token. The token is also known as a subscription ID, whichyou store on your server.The payment tokenization solution is compatible with the Visa and Mastercard AccountUpdater service. Card data stored with Cybersource is automatically updated byparticipating banks, thereby reducing payment failures. See the Account Updater UserGuide (PDF HTML).The payment token replaces the card or electronic check bank account number, andoptionally the associated billing, shipping, and card information. No sensitive cardinformation is stored on your servers, thereby reducing your PCI DSS obligations.For more information about tokens, see "Related Documents," page 11.Secure Acceptance Checkout API Integration Guide 16
Chapter 1Secure Acceptance Checkout APITokens That Represent a Card
Secure Acceptance Checkout API Integration Guide 3 CONTENTS Contents Recent Revisions to This Document 7 About This Guide 9 Audience and Purpose 9 Web Site Requirements 9 Conventions 10 Important and Warning Statements 10 Text and Command Conventions 10 Related Documents 11 Custom
![API Ballot: [Ballot ID] – API 510 & API 570, Deferrals, Rev05](/img/5/api510andapi570deferralsrev5.jpg)
