CyberSource Business Center Simple Order API

Transcription

1 CyberSource Business Center Simple Order API User s Guide Simple Order API June 2006

2 CyberSource Contact Information For technical support questions, go to the Home page in the Business Center to see the contact information appropriate for your account. Visit the Business Center, your central location for managing your online payment transactions, at For general information about our company, products, and services, go to For sales questions about any CyberSource Service, or call or (toll-free in the United States). Copyright 2006 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document 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 Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 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 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Trademarks CyberSource, the Power Behind the Buy Button, the CyberSource logo, SmartCert, and PaylinX are registered trademarks of CyberSource Corporation in the U.S. and other countries. The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, and CyberSource Connect are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. ii CyberSource Corporation

3 Contents Documentation Changes...vii Chapter 1 Introduction...1 About the Business Center...1 About Processing Credit Cards...2 Supported Card Types...2 MasterCard and Diners Club Alliance...3 Reducing Your Chances of Fraud...4 Address Verification Service...4 Card Verification Number...5 Smart Authorization...5 $0 Authorization...6 Using This Guide...7 Processing Credit Card Orders Chapter 2 Processing Credit Card Orders...9 Downloading a Client...9 Using the Latest API Version...10 Understanding API Requests and Replies...10 API Requests...10 Using Items...11 Required Item-Level Fields...11 Specifying Tax...11 Specifying Freight Charges...11 Using a Grand Total...12 Example Request...12 API Replies...13 Decisions...13 Reason Codes...14 Missing and Invalid Request Fields...14 Example Replies...14 Order Identifiers...15 Order Number...15 Request ID...15 Reconciliation ID...15 Business Center Simple Order API User s Guide June 2006 iii

4 Processing a Credit Card Order...15 Requesting an Authorization...16 Requesting a Sale...16 Using Fraud Screening Tests...17 Address Verification Service...17 Card Verification Number...18 Smart Authorization...18 Using Additional Authorization Features...18 Capturing the Order...19 Refunding the Customer s Money...19 Reconciling Your Orders...20 Testing Your Implementation...20 Going Live...21 Authorization API Fields...21 Request Fields...21 Reply Fields...26 Chapter 3 Processing Electronic Check Orders Processing Electronic Check Orders...29 Preparing to Accept Electronic Checks...29 Processing Electronic Check Payments...30 Corporate Checks...30 Reconciliation ID...30 Coupons...31 Seeing When the Check Has Cleared...31 Refunding the Customer s Money...31 Testing Your Implementation...31 Electronic Check Debit API Fields...32 Request Fields...32 Reply Fields...38 Example Request and Reply...39 Appendix A Product Codes...41 Appendix B Description of Return Codes...43 Address Verification Service Codes...43 Card Verification Number Codes...44 Smart Authorization Factor Codes...45 Reason Codes for the Simple Order API...46 Reason Codes for Credit Card Services...46 Reason Codes for Electronic Check Services...49 Appendix C Advanced API Capabilities for Credit Cards...51 Additional Authorization Features...51 iv CyberSource Corporation

5 Contents Using a Subscription for a Payment...51 Performing a Forced Capture...52 Indicating a Visa Bill Payment...52 Indicating a Recurring Payment...53 Using Coupons...54 Using the API for Captures and Credits...55 Requesting a Capture...55 Processing a Verbal Authorization...55 Capture Request Fields...56 Requesting a Credit...59 Using a Subscription for a Credit...59 Indicating a Credit for a Visa Bill Payment...59 Credit Request Fields...60 Credit Reply Fields...63 Using the API for Voids...63 Void Request Fields...64 Void Reply Fields...65 Using Payer Authentication...65 Appendix D Advanced API Capabilities for Electronic Checks...69 Using a Subscription for a Debit or Credit...69 Processing Credits with the API...70 Follow-On Credits...70 Stand-Alone Credits...70 Reconciliation ID...70 Payment Events Report...71 Credit Request Fields...71 Credit Reply Fields...74 Reason Codes...75 Appendix E Using the XML API...77 Downloading a Client...77 About the XML API...77 Constructing Requests...78 Parsing Replies...78 Correlating Fields Names...78 Requesting Credit Card Authorization...79 Numbering Items...79 Example Request and Reply...80 Index...83 Business Center Simple Order API User s Guide June 2006 v

6 vi CyberSource Corporation

7 Documentation Changes The following table lists changes made in the last six releases of this document: Release May 2996 February 2006 November 2005 Changes Corrected an error: Through the API, you can request a credit card credit ( Requesting a Credit on page 59) or check debit refund ( Refunding the Customer s Money on page 31) only within 60 days of the original authorization or debit, not 120 days as stated. In addition, in the Business Center, you can request a credit card credit within 120 days of the authorization ( Refunding the Customer s Money on page 19). Reorganized Chapter 2, Processing Credit Card Orders, on page 9. For an outline of the changes, see the Table of Contents: Processing Credit Card Orders. Moved to the end of the chapter the list of API fields. For the new layout for the chapter, see the Table of Contents: Processing Electronic Check Orders. Moved the information about Level III transactions, retail transactions, and the test simulator to separate supplements to this guide. See the Level III Supplement, the Retail Supplement, and the Testing Simulator Supplement. Added information about processing payments and credits with a subscription ID. For credit cards, see Using a Subscription for a Payment on page 51 and Using a Subscription for a Credit on page 59. For electronic checks, see Using a Subscription for a Debit or Credit on page 69. Added information about using JCB J/Secure Payer Authentication. See Using Payer Authentication on page 65. Removed from the guide information that cites the current version of the Simple Order API. See Using the Latest API Version on page 10 to determine the current version of the API. Added information about processing voiding a credit card order through the API. See Using the API for Voids on page 63. Updated the information about how long authorizations stay in the CyberSource database and thus how long you have to perform follow-on transactions such as credits. See Requesting a Credit on page 59 and Processing Credits with the API on page 70. Moved the information about optional credit card authorization features to an appendix. See Appendix C, Additional Authorization Features, on page 51. Business Center Simple Order API User s Guide June 2006 vii

8 Release Changes October 2005 Updated the Simple Order API version to Added information about using coupons with credit cards and electronic checks. See Using Coupons on page 54. Changed the required/optional status for the fields below when you use them with retail transactions. See these fields descriptions in the Retail Supplement. billto_firstname billto_lastname billto_ billto_street1 billto_city billto_state billto_postalcode billto_country Updated the information about how long authorizations stay in the CyberSource database and thus how long you have to perform follow-on transactions such as credits. See Requesting a Credit on page 59 and Processing Credits with the API on page 70. Added the billto_customerid and comments fields as optional fields for all of the services. See the field descriptions in Table 1 on page 21. August 2005 Updated the Simple Order API version to Added information about processing retail point of sale transactions. See the Retail Supplement. July 2005 Updated the Simple Order API version to Added four new API fields that can be used with any of the ICS services discussed in this guide: merchantdefineddata_field1, merchantdefineddata_field2, merchantdefineddata_field3, and merchantdefineddata_field4. See the field descriptions in Table 1 on page 21 for information about using the fields with a credit card authorization. See the field descriptions in Table 11 on page 56 for information about using the fields with a credit card capture. See the field descriptions in Table Table 13 on page 60 for information about using the fields with a credit card credit. See the field descriptions in Table 3 on page 32 for information about using the fields with an electronic check debit. See the field descriptions in Table 18 on page 71 for information about using the fields with an electronic check credit. Added information about how to process recurring payments. See Indicating a Recurring Payment on page 53. Clarified how to perform a sale. See Requesting a Sale on page 16. Clarified the information about using a grand total for the order and removed information about using a total freight amount and total tax amount for the order. See Using a Grand Total on page 12. viii CyberSource Corporation

9 Chapter 1 Introduction This document is for users of the Business Center, and it covers processing credit card orders with CyberSource s Simple Order API. You may want to use the API instead of CyberSource s Virtual Terminal or Hosted Order Page for many reasons such as these: You want more flexibility and control over the customer s buying experience at your Web store. Your business has grown, and your order volume warrants a higher level of order processing automation. You should use the API and this guide only if: You have an ISP or hosting provider to host your online store. You store uses a secure (SSL) online payment form. Your store does not already have a shopping cart to process payments. You have programming skills in Java, ASP,.NET, PHP, or Perl. If you are a developer with XML experience and want to use CyberSource s XML API instead of the Simple Order API, start here, but also see Appendix E, Using the XML API, on page 77. This chapter includes these sections: About the Business Center About Processing Credit Cards Reducing Your Chances of Fraud Using This Guide About the Business Center The CyberSource Business Center is a secure, Web-based tool that enables you to process credit cards online. CyberSource provides an easy-to-use Internet payment gateway fully integrated with popular shopping-cart software. To seamlessly integrate payment and fraud controls into your Web site, you can use a Virtual Terminal to process mail and Business Center Simple Order API User s Guide June

10 About Processing Credit Cards telephone orders, a hosted payment order form if you do not use a shopping cart, or a Simple Order API. The CyberSource Business Center offers the following advantages: Easy to implement. CyberSource is integrated into a number of popular shopping carts; however, if you prefer, you can integrate a hosted payment order form into your web site, or you can use our Simple Order API. Easy to manage. With the Business Center, you can submit orders via telephone or fax by using the Virtual Terminal, search for an order, view reports, and use the online help. Reliable and scalable technology. The CyberSource Business Center is based on technology designed for the largest online businesses to accept a high volume of transactions 24 hours a day. As your business grows, you can be confident that you have a reliable and fully tested payment service. Combined payment and fraud control tools. The CyberSource Business Center enables you to combine payment with fraud control tools. You can configure the fraud controls to create a simple but effective tool to minimize your exposure to online fraud. This tool uses address verification, card number verification, and transaction amount limit to review and match the billing and shipping addresses of your customers. About Processing Credit Cards You may have already learned something about credit card processing from reading the Business Center User s Guide. You will use the API to call CyberSource s credit card authorization service. The service contacts the bank that issued the card, checks to see if the card has enough funds for the order, and reserves those funds. It also performs some basic fraud checks that are discussed in the next section. Once your authorization is complete, you still must move the money from the customer s account into your account. You should move the money only after you have shipped the goods to the customer. To get the money to move, you must perform a capture of the authorization. You do not need to do this through the CyberSource API, though. Instead, you can do it by using the Business Center. For instructions on how to perform a capture, see the Business Center User s Guide. Note If you are an advanced user with large order volume, you may want to use the API to perform captures. See Appendix C, Advanced API Capabilities for Credit Cards, on page 51 for more information. Supported Card Types When you are using the CyberSource API, these are the card types available for each processor: 2 CyberSource Corporation

11 Chapter 1 Introduction Concord EFS: Visa, MasterCard, American Express, Discover, Diners Club FDMS Nashville: Visa, MasterCard, American Express, Discover, Diners Club, Carte Blanche, JCB FDMS South: Visa, MasterCard, American Express, Discover, Diners Club, Carte Blanche, JCB Paymentech New Hampshire: Visa, MasterCard, American Express, Discover, Diners Club, Carte Blanche, JCB Vital: Visa, MasterCard, American Express, Discover, Diners Club, Carte Blanche, JCB Note Carte Blanche cards can be authorized only through the API; they are not available in the Virtual Terminal in the Business Center. MasterCard and Diners Club Alliance In 2004, MasterCard and Diners Club announced an alliance that allows Diners Club cards to be processed as MasterCard cards. This alliance enables merchants who accept MasterCard cards to automatically accept Diners Club cards. MasterCard cards have a 16-digit number that begins with 5. Diners Club has two types of cards: Those issued in North America (by Diners Club North America), which have a 14- digit number that begins with either 30 or 38 Those issued outside of North America (by Diners Club International), which have a 14-digit number that begins with 36 The Diners Club cards issued in North America will be replaced with MasterCard cards (with the 16-digit number starting with 5) by the end of June During the transition period while the North American cards are being replaced, you do not need to do anything differently; continue to process North America Diners Club cards as Diners Club cards. If after June 2005 you process a North American Diners Club card that has a 14-digit number that begins with 30 or 38, the issuer will decline the authorization. The Diners Club cards issued outside North America are not being replaced by MasterCard cards; they will continue to have the 14-digit number that begins with 36. If you are a merchant outside North America, you should continue to process these cards as Diners Club cards. However, if you are a North American merchant, you must now process these cards as MasterCard cards (by setting the card type to MasterCard). It is up to you, the merchant, to determine whether you should process a Diners Club card as a Diners Club card or as a MasterCard card. If you are a North American merchant, you should review your code to ensure that you indicate the card type correctly to CyberSource: Business Center Simple Order API User s Guide June

12 Reducing Your Chances of Fraud If you explicitly set the card type in your request to CyberSource, you should use the card number to determine the card type and not the card type indicated by the customer. It is acceptable for you to NOT set the card type in the request to CyberSource and let CyberSource determine the card type based on the card number EXCEPT when the card is a Diners Club International card (with the 14-digit number that begins with 36). In this case you must explicitly set the card type field in the request to indicate a MasterCard card. If you are a merchant outside North America, you do not need to change how you process MasterCard or Diners Club cards. Reducing Your Chances of Fraud You have several ways to reduce the chance of accepting a fraudulent credit card order. This section describes these features, and the next chapter explains how to use the API for the features. Address Verification Service Depending on your payment processor and the type of credit card that you are processing, the issuing bank might use the Address Verification Service (AVS) to confirm that your customer has provided the correct billing address. If the customer provides incorrect information, the order might be fraudulent. AVS occurs automatically with the authorization request. You can use the Smart Authorization settings (discussed on page 5) to control which AVS results cause CyberSource to decline the order. Use the Business Center to change your Smart Authorization settings. See the Business Center User s Guide for more information. CyberSource returns AVS results for these processors and card types: Concord EFS: Visa, MasterCard, American Express, Discover, Diners Club FDMS Nashville: Visa, MasterCard, American Express, Discover FDMS South: Visa, MasterCard, American Express, Discover, Diners Club Paymentech New Hampshire: Visa (billing country must be U.S., Canada, or Great Britain) American Express (billing country must be U.S. or Canada) MasterCard, Discover, Diners Club (billing country must be U.S.) Vital: Visa, MasterCard, American Express, Diners Club (billing country must be U.S.) 4 CyberSource Corporation

13 Chapter 1 Introduction Card Verification Number Many credit cards have a card verification number printed on the card. To reduce your risk of fraud, you can ask the customer for that number and then send it with your credit card authorization request. This number does not appear on receipts and should be known only by the cardholder. For Visa, MasterCard, and Discover, the card verification number is 3 digits long and is printed in the signature area on the back of the card. For American Express, the number is 4 digits long and is printed on the front of the card, typically up and to the right of the embossed card number. Figure 1 Example of a Visa Card Verification Number Card verification number You can use the Smart Authorization settings (discussed on page 5) to control which card verification results cause CyberSource to decline the order. Use the Business Center to change your Smart Authorization settings. See the Business Center User s Guide for more information. CyberSource supports card verification numbers for these processors and card types: FDMS Nashville: Visa, MasterCard FDMS South: Visa, MasterCard, American Express, Discover Paymentech New Hampshire: Visa, MasterCard, American Express, Discover Vital: Visa, MasterCard, American Express, Discover Smart Authorization The Smart Authorization service can help you validate your customers identities and guard against fraud losses. Your credit card authorizations are automatically screened using Smart Authorization, which allows you to detect fraud based on the following criteria: Address Verification Service (AVS) result (as described above) Card verification (CV) result (as described above) Business Center Simple Order API User s Guide June

14 Reducing Your Chances of Fraud Transaction amount You should consider, however, signing up to use Advanced Smart Authorization, which screens your credit card authorizations based on the following additional, more sophisticated criteria: The order contains obscenities. The order contains nonsensical input. For example, if the customer enters their last name as zqmmmmz. The billing or shipping address is not verified. The system could not verify that the billing or shipping address exists. The billing and shipping addresses do not match. USA PATRIOT Act compliance. The person or organization placing the order, or the country in the shipping address, are on a list of denied parties or places to whom the United States prohibits commercial sale according to the USA PATRIOT Act. Important You must configure the Smart Authorization settings in the Business Center before you accept orders. See Figure 2 on page 7 for what the settings look like. Smart Authorization analyzes each credit card authorization based on your settings. If you have configured the service to reject orders failing any or all of the Smart Authorization tests, the service will respond to your authorization request with a decline message, even if the card issuer itself approved the purchase. $0 Authorization If you are using FDMS South or Vital as your processor, you can perform an authorization for $0 to check if the card account is valid and whether the card is lost or stolen. You may not process a capture for a $0 authorization. For Vital, in the reply you receive authorization code=preath instead of the normal authorization code. For FDMS South, you receive the normal authorization code. You may not include the card verification number in the $0 authorization request for FDMS South. If you do, the request will be rejected. 6 CyberSource Corporation

15 Chapter 1 Introduction Figure 2 Smart Authorization Settings in the Business Center Using This Guide This guide contains the following chapters and appendices. Chapters. The chapters discuss how to perform an authorization and electronic check debit with the Simple Order API. Chapter 1 Introduction Gives information about supported credit card types, payment processors, and features for preventing fraud. Chapter 2 Chapter 3 Processing Credit Card Orders Processing Electronic Check Orders Describes how to use the Simple Order API to process credit card authorizations. Describes how to use the Simple Order API to process electronic check payments. Business Center Simple Order API User s Guide June

16 Using This Guide Appendices. The appendices provide general reference information and additional API information for merchants who want to access other credit card and electronic check services. Appendix A Product Codes Describes the values you can use for an item s product code. Appendix B Description of Return Codes Describes the Address Verification Service (AVS) codes, Card Verification (CVN) codes, Smart Authorization factor codes, and Simple Order API reason codes you can receive. Appendix C Appendix D Advanced API Capabilities for Credit Cards Advanced API Capabilities for Electronic Checks Describes how to use the Simple Order API to process credit card captures, credits, and authorizations that use Payer Authentication. Also describes how to use optional credit card authorization features. Describes how to use the Simple Order API to process electronic check credits. Appendix E Using the XML API Describes how to use the XML variation of the Simple Order API. Additional Resources Business Center User s Guide This guide shows you how to perform the various functions available in the Business Center, such as configuring your settings and searching for orders. We recommend that you read this guide before you start implementing the Simple Order API to process orders. Business Center Reporting User s Guide This guide describes the many reports available in the Business Center. Business Center Subscription Payments User s Guide If you decide to use CyberSource s subscriptions payments services, you should read this guide to learn how to create and manage subscriptions. Business Center PayPal User s Guide If you decide to use CyberSource s PayPal services, you should read this guide to learn how to process PayPal payments. 8 CyberSource Corporation

17 Chapter 2 Processing Credit Card Orders This chapter describes how to process a basic credit card order by using the CyberSource Simple Order API. The information in this chapter covers card-not-present transactions (for example, transactions you accept through a Web store or through mail order/ telephone). For information about retail transactions, see the Retail Supplement to this guide. For information about processing electronic check orders, see Chapter 3, Processing Electronic Check Orders, on page 29. Important Before going any further, make sure you are accepting orders using a secure connection (SSL). If you do not use SSL to take orders on your Web site, do not use the API. Instead, use the Hosted Order Page or the Virtual Terminal. See the Hosted Order Page User s Guide or the Business Center User s Guide for more information about how to use them. This chapter includes these sections: Downloading a Client Using the Latest API Version Understanding API Requests and Replies Processing a Credit Card Order Going Live Authorization API Fields Downloading a Client To use the API to process orders, the first thing you need to do is pick one of our clients (SDKs): Java.NET ASP PHP Perl You can download your chosen client and its related documentation from the Support Center. Business Center Simple Order API User s Guide June

18 Using the Latest API Version Using the Latest API Version CyberSource updates the Simple Order API on a regular basis to introduce new API fields and functionality. To take advantage of the full functionality of the ICS services, you should use the latest version. See the Simple Order API Release Notes for information about the changes to the API. With each update, the API receives a new version number (for example, 1.19). To determine the latest version of the API, go to This represents the version of the server-side code for the ICS services. When configuring your Simple Order API client SDK, indicate the version of the API that you want to use (see the documentation for your client for instructions). Note The API version is different from the version of the CyberSource client SDK that you are using. See the CHANGES or README documentation for the SDK if you need to know which version of the client SDK you are using. The Simple Order API was originally referred to as the Web Services API in the CyberSource documentation. You may still see old references to the Web Services API in some locations. Understanding API Requests and Replies In general, you process a credit card order through CyberSource like this: 1 You collect information about the order (the items being bought, the customer s name and address, the credit card information, and so on). 2 You send us a request with the information and ask us to perform the credit card authorization service. 3 We process your request and send you a response. 4 You look at the response and then tell your customer the results of their order. For example, the bank that issued the card may decide not to authorize the payment. You then need to tell your customer that the credit card has been denied, and possibly ask them for another form of payment. API Requests A request includes information about the customer, their payment method, the items they are buying, and the service you are requesting. All of the fields you use in a credit card authorization are listed in Table CyberSource Corporation

19 Chapter 2 Processing Credit Card Orders Using Items For the items being purchased, you number each item and call them item_0, item_1, item_ 2, and so on. You have fields that you can use to help describe the customer s order for that item. These include item_#_quantity, item_#_unitprice, item_#_productcode, item_ #_taxamount, and others. CyberSource uses the information you provide for each item to calculate the total amount for the order. Important Do not include any carets (^) or colons (:) in the values you send in the request for any of the item_#_ fields. Carets and colons are reserved for use by the CyberSource services. Do not put any newlines or carriage returns into the values of any of the request fields. However, you can put embedded spaces and any other printable characters in the values. We will remove all leading and trailing spaces. Required Item-Level Fields Typically, only the item_#_unitprice field is required. The item_#_productcode field is optional and defaults to the value default. See Product Codes on page 41 for a list of product codes you can use. The item_#_quantity field is optional and defaults to 1 ONLY when you do one of these: Omit item_#_productcode from the request Set item_#_productcode to default, stored_value, or one of the values related to shipping and handling Otherwise, item_#_quantity is required, along with item_#_productname and item_#_ productsku. Specifying Tax To include tax for an item, use the item_#_taxamount field. This value is not the per-item tax amount; it is the total amount applicable to that item. The value is not multiplied by the item_#_quantity. For example: item_0_unitprice=10.00 item_0_quantity=5 item_0_taxamount=4.00 The grand total for this transaction is (10.00 * 5) = Specifying Freight Charges To include a shipping and handling charge for the order, you must include a separate item with item_#_productcode set to one of these values: shipping_only handling_only Business Center Simple Order API User s Guide June

20 Understanding API Requests and Replies shipping_and_handling For example: item_0_unitprice=10.00 item_0_quantity=5 item_0_taxamount=4.00 item_1_unitprice=4.95 item_1_quantity=1 item_1_productcode=shipping_only The grand total for this transaction is (10.00 * 5) (4.95 * 1) = Using a Grand Total Alternately, you may send a grand total amount for the order using the purchasetotals_ grandtotalamount field. You might want to do this if you do not want to specify itemlevel, tax, or freight information and just want to use a transaction total that covers everything. You may send this field instead of or in addition to the item-level information discussed in the previous section. If you send purchasetotals_grandtotalamount, CyberSource uses your value and does not use the item-level information to calculate the transaction s grand total. Note that the item information (if you provide it) still appears in the Transaction Detail page for the order in the Business Center. Example Request See the example below for what a basic request for credit card authorization looks like. Note that it uses name-value pairs. In this example, John Doe is buying one item that costs $ ccauthservice_run=true merchantid=infodev merchantreferencecode=482046c3a7e94f5 billto_firstname=john billto_lastname=doe billto_street1=1295 Charleston Rd. billto_city=mountain View billto_state=ca billto_postalcode=94043 billto_country=us billto_phonenumber= billto_ =jdoe@example.com item_0_unitprice=49.95 item_0_quantity=1 purchasetotals_currency=usd card_expirationmonth=12 12 CyberSource Corporation

21 Chapter 2 Processing Credit Card Orders card_expirationyear=2015 card_accountnumber= Notice that the first field (ccauthservice_run) tells CyberSource to run the credit card authorization service. For a complete list of the fields you use with a credit card authorization, see Request Fields on page 21. API Replies The reply you receive from CyberSource gives you the results of your request. To use the reply information, you need to integrate it into your system and any other system that uses that data. You should write an error handler to interpret the information that you get in the reply. Do not show the reply information from CyberSource directly to the customer. Instead, show an appropriate response that tells the customer the result of the order. Decisions In the reply, you receive a field named decision, which summarizes the overall result of your request. Look at this field first to determine what to do with the order. The decision can be one of the following: ACCEPT: The request succeeded ERROR: There was a system error REJECT: The request was rejected If you get an ACCEPT, then you should proceed taking the customer s order. You get errors typically because of CyberSource system issues unrelated to the content of your request. Errors are very rare; however, you must design your system to include a way to correctly handle them. Depending on which payment processor is handling the order, the error may indicate a valid CyberSource system error, or it may indicate a processor rejection because of some type of invalid data. In either case, we recommend that you do not design your system to endlessly retry sending a request in the case of a system error. See the documentation for the CyberSource client (SDK) you are using for more information about how to handle system errors and retries. You can get a REJECT for different reasons. Your request can be rejected by CyberSource, the payment processor, or the issuing bank. For example, CyberSource will reject a request if it is missing required fields or a value is invalid. The issuing bank will reject a request if the card limit has been reached and funds are not available. To determine why a request was rejected, look at the reasoncode field (discussed below). You are charged for all accepted and rejected requests. You are not charged for requests that result in errors. Business Center Simple Order API User s Guide June

22 Understanding API Requests and Replies Reason Codes After looking at the decision field, look at the reasoncode field to determine the reason for the decision and to decide if you want to take further action. If the decision was ERROR, the reasoncode tells you what type of error occurred. If the decision was REJECT, the reasoncode tells you the reason for the reject and whether you can take action that might still result in a successful order. For descriptions of the reason codes for the credit card service, see Reason Codes for the Simple Order API on page 46. You also receive ccauthreply_reasoncode in the reply. If you are requesting only credit card authorization and no additional services, you can ignore this field, as its value will always be the same as the reasoncode value. Note CyberSource reserves the right to add new reason codes at any time. If your error handler receives a reason code that it does not recognize, it should use the decision field to determine the result. Missing and Invalid Request Fields When you are first setting up your integration with the API, you might accidentally forget to include a required field, or you might send invalid data in a field. If your request is missing required fields, you receive reason code 101. If the request contains invalid data, you receive reason code 102. You also receive reply fields named missingfield_0...n and invalidfield_0...n, which list the fields that you need to correct. For example, if your request is missing three required fields, you receive the reply fields missingfield_0, missingfield_1, and missingfield_2. You should correct your code to make sure that you are providing all of the required fields and that the values you pass are valid. Example Replies See the example below for a basic reply showing an ACCEPT decision. After this first example is another that shows a REJECT decision. All the fields you see in these replies are described in Table 2 on page 26. requestid= merchantreferencecode=482046c3a7e94f5 decision=accept reasoncode=100 ccauthreply_reasoncode=100 ccauthreply_amount=49.95 ccauthreply_authorizationcode= ccauthreply_avscode=y ccauthreply_avscoderaw=yyy 14 CyberSource Corporation

23 Chapter 2 Processing Credit Card Orders ccauthreply_authorizeddatetime= t23:44:27z ccauthreply_processorresponse=a purchasetotals_currency=usd The example reply below shows a REJECT decision. The payment was rejected for reason code 204, which indicates that the card had insufficient funds. You may receive other reply fields depending on the type of REJECT that occurs. requestid= decision=reject reasoncode=204 ccauthreply_reasoncode=204 Order Identifiers Each order you process has three identifiers: Order Number This is a number that you assign to each order. You send this value in the merchantreferencecode field in the request. CyberSource recommends you use a unique number for each order as you use this value to track your order through the CyberSource system. You can later use the order number to search for an order in the Business Center. Request ID This is an identifier that CyberSource assigns to the request. You receive it in the reply in the requestid field. You can use the request ID to search for an order in the Business Center. Reconciliation ID This is an identifier that the payment processor assigns to your order. You receive this in the reply in the ccauthreply_reconciliationid field. You might use this value when you need to do research on an order. You do not need to store this value as you can retrieve it from the Business Center. Processing a Credit Card Order When you process a credit card payment with the API, you can choose between these two transaction types: Authorization only Sale (which is the authorization and the capture in the same request) Business Center Simple Order API User s Guide June

24 Processing a Credit Card Order If you process only the authorization, you can do the capture later in the Business Center (see page 19). Or, if your business volume warrants it, you can process your captures later through the API (see Requesting a Capture on page 55). Requesting an Authorization To indicate to CyberSource in your request that you want to run credit card authorization, set the ccauthservice_run field to true. Also include all the required fields listed in Table 1 on page 21. See Example Request on page 12 for an example authorization request. Requesting a Sale A sale is a bundled authorization and capture. You might use a sale instead a separate authorization and capture if there is no delay between when you take the customer s order and when you ship the goods. A typical use for a sale is if you are selling electronic goods or a service that you can turn on immediately. To request a sale, request both the authorization and the capture services at the same time (set both ccauthservice_run and cccaptureservice_run to true). Include all of the request fields for an authorization. If the authorization is successful, CyberSource immediately processes the capture. The reply gives you an overall result for the request (the decision and reasoncode) as well as the results for the individual services (ccauthreply_reasoncode and cccapturereply_ reasoncode). If the authorization is declined, CyberSource does not process the capture, and the reply includes the results for the authorization only. This is an example sale request: ccauthservice_run=true cccaptureservice_run=true merchantid=infodev merchantreferencecode=482046c3a7e94f5 billto_firstname=john billto_lastname=doe billto_street1=1295 Charleston Rd. billto_city=mountain View billto_state=ca billto_postalcode=94043 billto_country=us billto_phonenumber= billto_ =jdoe@example.com item_0_unitprice=49.95 item_0_quantity=1 purchasetotals_currency=usd card_expirationmonth=12 card_expirationyear= CyberSource Corporation

25 Chapter 2 Processing Credit Card Orders card_accountnumber= This is an example sale reply where both services are successful: requestid= merchantreferencecode=482046c3a7e94f5 decision=accept reasoncode=100 ccauthreply_reasoncode=100 ccauthreply_amount=49.95 ccauthreply_authorizationcode= ccauthreply_avscode=y ccauthreply_avscoderaw=yyy ccauthreply_authorizeddatetime= t23:44:27z ccauthreply_processorresponse=a cccapturereply_reasoncode=100 cccapturereply_amount=49.95 cccapturereply_requestdatetime= t23:44:27z cccapturereply_reconciliationid= purchasetotals_currency=usd Using Fraud Screening Tests These next few sections describe how to use the authorization API fields related to the fraud screening tests described in Chapter 1, Reducing Your Chances of Fraud, on page 4. Note If your authorization is flagged for one of the fraud checks described below, but you received a valid authorization code from the bank, you can still choose to accept the customer s order and capture the authorization. However, consider reviewing the order first to make sure that it is legitimate. Address Verification Service The Address Verification Service (AVS) looks at the billing address the customer provided and checks if it matches the address that the issuing bank has on file. See Address Verification Service on page 4 for more information. You can configure your Smart Authorization settings in the Business Center to control which AVS results cause CyberSource to reject the order (see the Business Center User s Guide for more information). If your Smart Authorization settings for AVS cause CyberSource to reject the order, you get decision=reject and ccauthreply_ reasoncode=520. Business Center Simple Order API User s Guide June

26 Processing a Credit Card Order You can get details about the AVS result in the ccauthreply_avscode reply field. See Appendix B, Address Verification Service Codes, on page 43 for descriptions of the codes that you can receive in this field. Card Verification Number You can request the card verification number from your customer and send it in your authorization request to help reduce the risk of fraud. See Card Verification Number on page 5 for more information. Use the card_cvnumber field in the request to send the customer s card verification number. Note If your processor is FDMS Nashville or FDMS South, and you decide to use card verification numbers, you can use the request field card_cvindicator to indicate if you are sending a card verification number in the request. The field is described below in Table 1. You can configure your Smart Authorization settings in the Business Center to control which card verification results cause CyberSource to reject the order (see the Business Center User s Guide for more information). If your Smart Authorization settings cause CyberSource to reject the order, you get decision=reject and ccauthreply_ reasoncode=520. You can get details about the CV result in the ccauthreply_cvcode field. See Appendix B, Card Verification Number Codes, on page 44 for descriptions of the codes that you can receive in this field. Smart Authorization Smart Authorization automatically screens all of your orders to flag ones that appear risky. See Smart Authorization on page 5 for more information. If Smart Authorization flags your order, in the reply you get decision=reject and ccauthreply_reasoncode=520. You can get details about why Smart Authorization flagged the order in the ccauthreply_authfactorcode reply field. See Appendix B, Smart Authorization Factor Codes, on page 45 for descriptions of the codes you can receive in this field. Using Additional Authorization Features CyberSource also offers several other authorization features that you can use depending on your business needs: Using a Subscription for a Payment Performing a Forced Capture Indicating a Visa Bill Payment Indicating a Recurring Payment Using Coupons 18 CyberSource Corporation

27 Chapter 2 Processing Credit Card Orders For more information about those features, see Additional Authorization Features on page 51. Capturing the Order If you performed an authorization only instead of a sale, you still need to capture the order to move money into your bank account. Important If you do not capture the authorization, you do not receive payment. You can do this in the Business Center (this section) or through the API (see Requesting a Capture on page 55). To capture in the Business Center: 1 After you have shipped the order, log into the Business Center. 2 Search for authorizations that have not been captured. Your order will look similar to this: 3 Capture the authorization. You will receive payment in your bank account within two to four days. Note If you want to process Level III captures with Vital, see the Level III Supplement to this guide. Refunding the Customer s Money If you need to refund the customer s money, we suggest that you use the Business Center. See the Business Center User s Guide for information about crediting the customer s card. Important Because the authorization information necessary to perform a follow-on action is available in the CyberSource database for a limited time only, you can issue a credit card refund as follows: - Through the API: up to 60 days after the authorization - In the Business Centers: up to 120 days after the authorization If your business s order and credit volume is large enough, you might instead consider processing credits using the API. See Requesting a Credit on page 59 for more information. Business Center Simple Order API User s Guide June

28 Processing a Credit Card Order Reconciling Your Orders An important part of processing your orders is reconciliation. This is the process of verifying that the list of your processed orders matches the deposits into your bank account. For information about using CyberSource reports to reconcile your orders, see the Business Center User s Guide. Testing Your Implementation To make sure that your requests are completed correctly, you need to test the basic success and error conditions for each ICS service you plan to use. When testing, follow these rules: Use your regular CyberSource merchant ID to perform testing. Use a non-existent account and domain name for the customer s address (for example, random@example.com). Make sure your client is configured to send requests to the test server ( ics2wstest.ic3.com/commerce/1.x/transactionprocessor). See the documentation for your client for information about how to do this. Unless otherwise specified, use the following test credit card numbers (without the spaces), not real ones: Credit Card Type Test Account Number Visa MasterCard American Express Discover JCB Diners Club Important The test credit card numbers are valid only when testing on the test server. CyberSource has created a simulator that allows you to use specific amounts in the test authorization request to trigger specific responses. This allows you to test your system with the different responses you might receive. For more information about using the simulator, see the Testing Simulator Supplement to this guide. 20 CyberSource Corporation

29 Chapter 2 Processing Credit Card Orders Going Live When you are ready to accept orders from customers, you can use the Business Center Web site to go live. See the Business Center User s Guide for more information. Important You must also configure your client so that it sends transactions to the production server and not the test server. See the documentation for your client for information about how to do this. After you go live, use real card numbers and other data to test every card type you support. Because these are real transactions in which you are buying from yourself, use small amounts, such as one dollar, to do the tests. Process an authorization, then capture the authorization, and later refund the money. Use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account as expected. If you have more than one CyberSource merchant ID, test each one separately. Authorization API Fields Request Fields Table 1 lists the fields you use to request credit card authorization. Table 1 Authorization Request Fields Field Name Description Required / Optional Data Type & Length billto_city City of the billing address. Required String (50) billto_country Country of the billing address. Use the twocharacter ISO codes. Required String (2) billto_customerid Your identifier for the customer. Optional String (50) billto_ billto_firstname billto_lastname Customer s address, including the full domain name (for example, jdoe@example.com). Customer s first name.the value should be the same as the one that appears on the card. Customer s last name. The value should be the same as the one that appears on the card. Required String (255) Required String (60) Required String (60) billto_phonenumber Customer s phone number. Optional String (15) Business Center Simple Order API User s Guide June