Transcription
Title PageCyberSource Simple Order API ClientDeveloper 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-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: July 20202
CONTENTSContentsRecent Revisions to This DocumentAbout This GuideAudiencePurposeScope1112121212Conventions 13Note, Important, and Warning StatementsText and Command Conventions 13Related Documents 14Client Package Documentation 14CyberSource Services DocumentationCustomer Support131414Chapter 1Introduction15Chapter 2C/C Client16Choosing Your API and ClientAPI Variation 16Client Versions 16Sample Code 17Basic C/C Page Example1617Installing and Testing the Client 19Minimum System Requirements 19For Linux 19For Windows 19Transaction Security Keys 19Installing the Client 20Configuring Client Settings 21Testing the Client 23Simple Order API Client Developer Guide 3
ContentsGoing Live 24CyberSource Essentials Merchants 24CyberSource Advanced Merchants 25Updating the Client to Use a Later API Version25C/C API for the Client 26CybsMap Structure 26Available Functions 26cybs load config() 26cybs create map() 27cybs destroy map() 27cybs set add behavior() 27cybs get() 28cybs get first() 29cybs get next() 29cybs get count() 30cybs create map string() 30cybs destroy map string() 30cybs run transaction() 31Using Name-Value Pairs 36Requesting CyberSource Services 36Sample Code 36Creating and Sending Requests 36Adding the Use Statement 36Loading the Configuration Settings 37Creating the Empty Request and Reply 37Adding the Merchant ID 37Adding Services to the Request Structure 37Requesting a Sale 37Adding Service-Specific Fields to the Request 38Sending the Request 38Interpreting Replies 39Handling the Return Status 39Processing the Reason Codes 42Handling Decision Manager Reviews 44Requesting Multiple Services 45Retrying When System Errors Occur 45Using XML 46Requesting CyberSource Services 46Sample Code 47Creating a Request Document 47Creating an Empty Request 48Adding the Merchant ID 48Adding Services to the Request 48Requesting a Sale 49Simple Order API Client Developer Guide 4
ContentsAdding Service-Specific Fields to the RequestSending Requests 50Adding the Use Statement 50Loading the Configuration Settings 50Creating the Empty Request and Reply 50Reading the XML Document 51Sending the Request 51Interpreting Replies 51Handling the Return Status 51Processing the Reason Codes 55Handling Decision Manager Reviews 57Requesting Multiple Services 58Retrying When System Errors Occur 59Advanced Configuration Information 60Using Alternate Server Configuration SettingsConfiguring for Multiple Merchant IDs 61Chapter 3.NET 4.0 or Later Client62Choosing an API and ClientAPI Variation 62Client Versions 6362Basic C# Program Example634960Installing and Testing the Client 65Minimum System Requirements 65Transaction Security Keys 65Installing the Client 66Using the NuGet Package Manager 66Installing Individual Files 66Upgrading from a Previous Version 67Migrating from .NET Framework 1.x 67Migrating from .NET Framework 2.x 68Testing the Client 70Using the Test Applications 70Configuring the Test Applications 70Configuring Your Settings for Multiple MerchantsRunning the Test Applications 73Deploying the Client to Another Computer 73Going Live 74CyberSource Essentials Merchants 74CyberSource Advanced Merchants 74Updating the Client to Use a Later API Version 75Name-Value Pair Client 75SOAP Client 7573Simple Order API Client Developer Guide 5
ContentsXML Client76Using Name-Value Pairs 76Requesting CyberSource Services 76Creating and Sending the Request 77Creating a New Visual Studio .NET Project 77Importing the Client Classes 77Creating an Empty Request 77Adding the Merchant ID 77Adding Services to the Request 78Requesting a Sale 78Adding Service-Specific Fields to the Request 78Sending the Request 79Interpreting the Reply 79Using the Decision and Reason Code 81For CyberSource Advanced Merchants: Handling Decision Manager ReviewsRequesting Multiple Services 84Retrying When System Errors Occur 85Creating an Application Settings File 85Using XML 86Requesting CyberSource Services 86Creating a Request Document 87Creating an Empty Request 87Adding the Merchant ID 88Adding Services to the Request 88Requesting a Sale 88Adding Service-Specific Fields to the Request 89Sending the Request 89Creating a New Visual Studio .NET Project 89Importing the Client Classes 90Sending the Request 90Interpreting the Reply 91Using the Decision and Reason Code 93For CyberSource Advanced Merchants: Handling Decision Manager ReviewsRequesting Multiple Services 96Retrying When System Errors Occur 97Creating an Application Settings File 97Using SOAP 98Requesting CyberSource Services 98Creating and Sending the Request 98Creating a New Visual Studio .NET ProjectImporting the Client Classes 99Creating an Empty Request 99Adding the Merchant ID 99Adding Services to the Request 99839598Simple Order API Client Developer Guide 6
ContentsRequesting a Sale 100Adding Service-Specific Fields to the Request 100Sending the Request 101Interpreting the Reply 102Using the Decision and Reason Code 103For CyberSource Advanced Merchants: Handling Decision ManagerReviews 105Requesting Multiple Services 106Retrying When System Errors Occur 107Creating an Application Settings File 107Setting the Connection LimitExamples 108References 109108Sample ASP.NET Code Using Visual BasicChapter 4Java Client110114Choosing Your API and ClientAPI Variations 114Client Versions 115114Sample Code 115Basic Java Program Example116Installing and Testing the Client 118Minimum System Requirements 118Transaction Security Keys 118Installing the Client 119Using a Package Manager 119Installing Individual Files 120Configuring Client Properties 120Testing the Client 122Running the SDK Integration Tests 122Running the Samples 123Going Live 123CyberSource Essentials Merchants 123CyberSource Advanced Merchants 124Using Name-Value Pairs 124Requesting CyberSource Services 124Creating and Sending Requests 125Importing the Client Classes 125Loading the Configuration File 125Creating an Empty Request 126Adding Services to the Request 126Adding Service-Specific Fields to the RequestSending the Request 127127Simple Order API Client Developer Guide 7
ContentsInterpreting Replies 128Using the Decision and Reason Code Fields 129Handling Decision Manager Reviews (CyberSource Advanced ServicesOnly) 131Using XML 133Requesting CyberSource Services 133Creating Requests 134Creating an Empty Request 134Adding Services to the Request 135Adding Service-Specific Fields to the Request 136Sending Requests 136Importing the Client Classes 136Loading the Configuration File 137Sending the Request 137Interpreting Replies 138Using the Decision and Reason Code 139Handling Decision Manager Reviews (CyberSource Advanced Merchants)Handling System Errors 141Advanced Configuration Information 143Using Alternate Server Properties 143Configuring for Multiple Merchant IDs 143Using System Properties 144Resolving Connection Issues 144Oracle Java SDK version earlier than 1.4.0IBM Java SDK 145Importing the Root CA Certificate 146Chapter 5PHP Client141144147Using PHP in a Hosted EnvironmentChoosing Your API and ClientAPI Variation 148Client Versions 148Sample Code 149Basic PHP Page ExampleSample Scripts 150Sample PHP Pages 150147148149Installing and Testing the Client 152Minimum System Requirements 152For Linux 152For Windows 152Transaction Security Keys 153Installing the Client 153Configuring Client Settings 156Simple Order API Client Developer Guide 8
ContentsTesting the Client 158Going Live 160CyberSource Essentials Merchants 160CyberSource Advanced Merchants 160Updating the Client to Use a Later API Version 161Special Installation Instructions for Oracle Users 161PHP API for the Client 162Summary of Functions 162cybs load config() 162cybs run transaction() 163Reply Key Descriptions 163Possible Return Status Values164Using Name-Value Pairs 168Requesting CyberSource Services 168Creating and Sending the Request 169Loading the Configuration Settings 169Creating an Empty Request Array 169Adding the Merchant ID 169Adding Services to the Request Array 170Requesting a Sale 170Adding Service-Specific Fields to the Request ArraySending the Request 170Interpreting the Reply 171Handling the Return Status 171Processing the Reason Codes 173Handling Decision Manager Reviews 175Requesting Multiple Services 176Retrying When System Errors Occur 177Using XML 178Requesting CyberSource Services 178Sample Code 178Creating a Request Document 179Creating an Empty Request 179Adding the Merchant ID 180Adding Services to the Request 180Requesting a Sale 180Adding Service-Specific Fields to the RequestSending the Request 181Loading the Configuration Settings 181Reading the XML Document 182Sending the Request 182Interpreting the Reply 183Handling the Return Status 183Processing the Reason Codes 185170181Simple Order API Client Developer Guide 9
ContentsHandling Decision Manager Reviews 187Requesting Multiple Services 188Retrying When System Errors Occur 189Advanced Configuration Settings 190Using Alternate Server Configuration Settings 190Configuring Your Settings for Multiple Merchant IDs 191Appendix A Using the Client Application Fields192Simple Order API Client Developer Guide 10
ReleaseChangesJuly 2020Added endpoints for merchants in India.September 2019Deprecated and deleted Perl and ASP sections and removed ASP and Perlsection references from About this Guide and Introduction sections.April 2019Updated .NET 4.0 to .NET 4.0 or later.REVISIONSRecent Revisions to ThisDocumentUpdated the types of endpoints: C/C : "Using Alternate Server Configuration Settings," page 60 Java: "Using Alternate Server Properties," page 143 PHP: "Using Alternate Server Configuration Settings," page 190Updated the following sections in the .NET 4.0 or Later chapter: "Installing the Client," page 66 "Testing the Client," page 70Updated the following sections in the Java chapter: "Installing the Client," page 119 "Testing the Client," page 122September 2015Updated the production server URL and the test server URL.September 2014Added the new .NET 4.0 client chapter. See ".NET 4.0 or Later Client,"page 62.April 2013Noted that all of the Simple Order API clients except the .NET 4.0 client aresupported only on 32-bit operating systems.Combined all Simple Order API client documents into this developer guide,which covers all supported programming languages.Simple Order API Client Developer Guide 11
ABOUT GUIDEAbout This GuideAudienceThis guide is written for application developers who want to use the CyberSource SimpleOrder API client to integrate the following CyberSource services into their ordermanagement system: CyberSource Essentials CyberSource AdvancedUsing the Simple Order API client SDK requires programming skills in one of the followingprogramming languages: C, C Java/Cold Fusion .NET PHPTo use these SDKs, you must write code that uses the API request and reply fields tointegrate CyberSource services into your existing order management system.PurposeThis guide describes tasks you must complete to install, test, and use the CyberSourceSimple Order API client software.ScopeThis guide describes how to install, test, and use all available Simple Order API clients. Itdoes not describe how to implement CyberSource services with the Simple Order API. Forinformation about how to use the API to implement CyberSource services, see "RelatedDocuments," page 14.Simple Order API Client Developer Guide 12
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; 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.The Simple Order API was originally referred to as the Web Services API inCyberSource documentation. References to the Web Services API may stillappear in some locations.Simple Order API Client Developer Guide 13
About This GuideRelated DocumentsClient Package DocumentationThe following documentation is available in the client package download: README file CHANGES file Sample code filesCyberSource Services DocumentationThis guide (Simple Order API Client Developer Guide) contains information about how to: Create the request Send the request Receive the replyIn contrast, CyberSource services documentation listed in Table 1 contains informationabout how to: Determine what to put in requests sent to CyberSource. Interpret what is contained in the reply from CyberSource.Each type of CyberSource service has associated documentation:Table 1CyberSource Services DocumentationType of ServiceAvailable DocumentationCyberSource Essentials Credit Card Services User Guide (PDF HTML) Electronic Check Services User Guide (PDF HTML) Credit Card Services Using the Simple Order API(PDF HTML) Reporting User Guide (PDF HTML)CyberSource AdvancedIf you use other CyberSource services, the documentation can be found on theCyberSource Essentials or CyberSource Advanced (Global Payment Services) sectionsof the CyberSource web site.Customer SupportFor support information about any CyberSource service, visit the Support Center:http://www.cybersource.com/supportSimple Order API Client Developer Guide 14
CHAPTERIntroduction1Only the .NET 4.0 or later client for the Simple Order API is supported on both32-bit and 64-bit operating systems. All of the other Simple Order API clientsare supported on 32-bit operating systems only.The CyberSource Simple Order API enables you to access CyberSource services usingname-value pairs, XML, or the Simple Object Access Protocol (SOAP). The Simple OrderAPI SDKs provide the client software for the following programming languages: C, C .NET version 1.1 and version 2.0 Java PHPThe Simple Order API is a good choice for businesses who: Must access CyberSource services that can only be accessed with APIs Have high volumes of transactions that warrant high levels of automation Must control and customize their customers’ buying experience Have an order page that is secured with Secure Sockets Layer (SSL) Can provide skilled software programmers to implement CyberSource services withthe APISimple Order API Client Developer Guide 15
CHAPTERC/C Client2 The C/C client for the Simple Order API is supported on 32-bit operating systemsonly. If you are building an application to sell to others, see Appendix A, "Using the ClientApplication Fields," on page 192. This appendix has a list of API fields you can usein your request that describe the application, its version, and its user. If you usethese fields in your request, you can view their values in the Transaction SearchDetails window of the Business Center.Choosing Your API and ClientAPI VariationWith this client package, you can use either of these variations of the Simple Order API: Name-value pairs, which are simpler to use than XML XML, which requires you to create and parse XML documentsThe test that you run immediately after installing the client uses name-value pairs.Client VersionsCyberSource updates the Simple Order API on a regular basis to introduce new API fieldsand functionality. To identify the latest version of the API, go nProcessorFor transactions in India, go ionProcessorThis represents the version of the server-side code for the CyberSource services.The Simple Order API Client for C/C also has a version, but it is not the same as theAPI version. The client version represents the version of the client-side code that you useto access the CyberSource services.Simple Order API Client Developer Guide 16
Chapter 2C/C ClientWhen configuring the client, you indicate which version of the API you want to use. Whensetting this parameter, do not use the current version of the client; use the current versionof the API.Sample CodeThe client contains two sets of sample code, one for using name-value pairs and one forusing XML. See "Testing the Client," page 23, or see the README file for moreinformation about using the sample code to test the client. Name-value pairs: See authCaptureSample.c in installationdirectory /samples/nvp. XML: We suggest that you examine the name-value pair sample code listed abovebefore implementing your code to process XML requests.For the XML sample code, see authSample.c in installation directory /samples/xml. Also see the auth.xml XML do
Simple Order API Client Developer Guide 6 Contents XML Client 76 Using Name-Value Pairs 76 Requesting CyberSource Services 76 Creating and Sending the Request 77 Creating a New Visual Studio .NET Project 77 Importing the Client Classes 77 Creating an Empty Request 77 Adding the Merchant ID 77 Adding Services to the Request 78 Requesting a Sale 78 Adding Service-Specific
