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_ [email protected] 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_ [email protected] 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, [email protected]). 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, [email protected]). 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

30 Authorization API Fields Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Data Type & Length billto_postalcode Postal code of the billing address. The field must contain between five and nine digits. Required for U.S. or Canada String (10) If the value of billto_country is CA, the number of characters in billto_postalcode must follow these rules: If the number of characters is greater than three, the first three characters must be of the format [alpha][numeric][alpha]. If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric]. billto_state State or province of the billing address. Use the two-character codes. Required for U.S. and Canada String (2) billto_street1 First line of the billing street address. Required String (60) billto_street2 Second line of the billing street address. Used for additional address information, for example: Attention: Accounts Payable Optional String (60) card_accountnumber Customer s credit card number. Required String with numbers only (20) card_cardtype Type of card to authorize. This field is required if the card type is JCB (007), and optional for all other card types. See MasterCard and Diners Club Alliance on page 3 for important information. This field can contain one of the following values: 001: Visa 002: MasterCard 003: American Express 004: Discover 005: Diners Club 007: JCB (required) Optional (see description) String (3) 22 CyberSource Corporation

31 Chapter 2 Processing Credit Card Orders Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Data Type & Length card_cvindicator Card verification indicator used to indicate if a card verification value was sent. Accepted by FDMS Nashville and FDMS South. Optional String with numbers only (1) The field can contain one of the following values: 0: CV number service not requested. 1: CV number service requested and supported. 2: CV number on credit card is illegible. 9: CV number was not imprinted on credit card. The default value is 1 if you send the card_ cvnumber field in the request, and 0 if you do not send the card_cvnumber field. card_cvnumber Card verification number. See Card Verification Number on page 18 for more information. Do not include this field if FDMS South is your processor and you are performing a $0 authorization. Optional String with numbers only (4) card_expirationmonth Two-digit month (MM - 01 through 12, inclusive) that the credit card expires in. The leading 0 is required. Required String (2) card_expirationyear ccauthservice_ commerceindicator ccauthservice_run comments Four-digit year (YYYY) that the credit card expires in. Transaction channel type. This field can contain one of the following values: internet (default): ecommerce transaction. moto: Mail order or telephone order. See Indicating a Recurring Payment on page 53 for information about recurring payments. Set to true to include the credit card authorization service in your request. Optional comments you have about the authorization. These comments will not be shown to the customer. Required String (4) Optional String (13) Required String (5) Optional String (255) Business Center Simple Order API User s Guide June

32 Authorization API Fields Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Data Type & Length item_#_productcode item_#_productname item_#_productsku item_#_quantity item_#_taxamount Type of product, which is also used to determine the category that the product falls under (electronic, handling, physical, service, or shipping). The default value is default. See Product Codes on page 41 for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_quantity, item_#_ productname, and item_#_productsku fields are required. Name of the product. Required if item_#_ productcode is NOT default, stored_ value, or one of the values related to shipping and/or handling. Product s identifier code. Required if item_ #_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Quantity of the product being purchased. The default value is 1. Required if item_#_ productcode is NOT default, stored_ value, or one of the values related to shipping and/or handling. Total tax to apply to the product. This value cannot be negative. The item_#_taxamount field is additive. For example, if you send one item with unitprice of $10.00 and taxamount of $0.80, and you send another item with unitprice of $20.00 and taxamount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included. Optional String (30) See description String (30) See description String (15) See description Integer (10) Optional String (15) 24 CyberSource Corporation

33 Chapter 2 Processing Credit Card Orders Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Data Type & Length item_#_unitprice merchantdefineddata_ field1 merchantdefineddata_ field2 merchantdefineddata_ field3 merchantdefineddata_ field4 merchantid merchantreferencecode purchasetotals_currency purchasetotals_ grandtotalamount Per-item price of the product. You must provide either this field or purchasetotals_ grandtotalamount in your request. See Using a Grand Total on page 12 for more information. You can use a decimal if you want. For example, you can use either or 100 to represent one hundred dollars. Do not include any special characters, such as a dollar sign ($). If Vital is your processor, you may set this field to 0 to check if the card is lost or stolen. Open field that you can use to store any information. The value appears in the transaction s details in the Business Center and in the Order Detail Report. NOTE Do not use the field to store any sensitive customer information. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Merchant-generated order reference or tracking number. See Order Identifiers on page 15 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Grand total for the order. You must provide either this field or item_#_unitprice in your request. See Using a Grand Total on page 12 for more information. If Vital is your processor, you may set this field to 0 to check if the card is lost or stolen. See description String (15) Optional String (64) Optional String (64) Optional String (64) Optional String (64) Required String (30) Required String (50) Required String (5) See description String (15) Business Center Simple Order API User s Guide June

34 Authorization API Fields Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional shipto_city City to which to ship the product. Optional (Required if providing any shipping information) Data Type & Length String (50) shipto_country shipto_ shipto_firstname shipto_lastname shipto_phonenumber Country to which to ship the product. Use the two-character ISO codes. address of the person receiving the shipment (for example, [email protected]). First name of the person receiving the shipment. First name of the person receiving the shipment. Phone number for the person receiving the shipment. Optional String (2) Optional String (255) Optional String (60) Optional String (60) Optional String (15) shipto_postalcode Postal code to which to ship the product. Optional (Required if address is in U.S. and Canada) String (10) shipto_state State or province to which to ship the product. Use the two-character codes. Optional (Required if address is in U.S. and Canada) String (2) shipto_street1 First line of the address to which to ship the product. Optional (Required if providing any shipping information) String (60) shipto_street2 Second line of the address to which to ship the product. Optional String (60) Reply Fields Table 2 lists the credit card authorization reply fields. Table 2 Authorization Reply Fields Field Name Description Data Type & Length ccauthreply_amount Total amount of the authorization. String (15) 26 CyberSource Corporation

35 Chapter 2 Processing Credit Card Orders Field Name Table 2 Authorization Reply Fields (Continued) Description Data Type & Length ccauthreply_ authfactorcode ccauthreply_ authorizationcode ccauthreply_ authorizeddatetime ccauthreply_avscode ccauthreply_ avscoderaw ccauthreply_cvcode ccauthreply_ cvcoderaw ccauthreply_ processorresponse ccauthreply_ reasoncode ccauthreply_ reconciliationid decision Risk factor code from Smart Authorization. This field will contain one or more of the codes, separated by carets (^). See Smart Authorization Factor Codes on page 45 for a list of the codes. Authorization code. Returned only if a value if returned by the processor. For a Vital $0, the value you receive is PREATH. Time of authorization. The format is YYYY-MM-DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. Results of address verification. See Address Verification Service Codes on page 43 for a list of possible values. AVS result code sent directly from the processor. Returned only if a value is returned by the processor. Note Do not use this field to interpret the result of AVS. Use for debugging purposes only. Result of processing the card verification number. See Card Verification Number Codes on page 44 for a list of the possible values for this field. Card verification result code sent directly from the processor. Returned only if a value is returned by the processor. Note Do not use this field to interpret the result of card verification. Use for debugging purposes only. Processor s response code. Note Do not use this field to interpret the result of the authorization. Numeric value corresponding to the result of the credit card authorization request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Reference number for the transaction. Returned for Paymentech only. Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded ERROR: There was a system error REJECT: One or more of the services in the request was declined String (100) String (6) String (20) String (1) String (10) String (1) String (10) String (10) Integer (5) String (60) String (6) invalidfield_0...n Fields in the request that contained invalid data. String (100) Business Center Simple Order API User s Guide June

36 Authorization API Fields Table 2 Authorization Reply Fields (Continued) Field Name Description Data Type & Length merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) purchasetotals_currency Currency used for the order. For U.S. dollars, the value will be USD. String (5) reasoncode Numeric value corresponding to the result of the overall request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Integer (5) requestid Identifier for the request. String (26) 28 CyberSource Corporation

37 Chapter 3 Processing Electronic Check Orders This chapter describes the Simple Order API fields that you use to process electronic check payments. Before reading this chapter, make sure to read the Business Center User s Guide. That guide explains important information about processing electronic checks. Also, this chapter assumes you have experience using the Simple Order API to process credit card payments. If you are not familiar with the API already, read Chapter 2, Processing Credit Card Orders, on page 9 to understand the basic concepts of processing requests and replies with the API. This chapter includes these sections: Preparing to Accept Electronic Checks Processing Electronic Check Payments Seeing When the Check Has Cleared Refunding the Customer s Money Testing Your Implementation Electronic Check Debit API Fields Example Request and Reply Preparing to Accept Electronic Checks To process electronic checks, you must add two items to your Web store: 1 On your Web site, add a link to the table of current state returned check fees ( Because this table is updated regularly, we recommend that you link directly to it. You can display the state fees table in a pop-up window, a full browser window, or directly on the checkout page. 2 At the end of the checkout process on your Web site, display the following consent statement for the check authorization that your customer must accept before submitting the order: By clicking Authorize, you authorize an electronic debit from your checking account that will be processed through the regular banking system. If your full order is not available at the same time, you authorize partial debits to your account, not to exceed the total authorized amount. The partial debits will take place upon each shipment of partial goods. If any of your payments are returned unpaid, you will be charged a returned item fee up to the maximum allowed by law. To exit without authorizing, click Cancel. Click here to view your state s returned item fee. Business Center Simple Order API User s Guide June

38 Processing Electronic Check Payments Processing Electronic Check Payments To process an order that uses an electronic check, you use the ecdebitservice. To request the service, set the ecdebitservice_run field to true. See Table 3 on page 32 for a list and description of the API fields to use when requesting the service. See Example Request and Reply on page 39 for an example request and reply. Many of the API fields that you use to process an electronic check are the same ones that you use to process a credit card. The difference is in the account information: Instead of collecting credit card information, you collect bank account information (including the bank account number and bank routing number). As a reminder, here is an image showing the location of the bank account number, bank routing number, and check number on a paper check: Figure 3 Location of Bank Routing Number, Bank Account Number, and Check Number NAME ADDRESS CITY, STATE ZIP DATE /6789 PAY TO THE ORDER OF $ BANK NAME ADDRESS CITY, STATE ZIP DOLLARS FOR Bank Routing Number You can use either AmeriNet or TeleCheck as your electronic check processor. Depending on which payment processor you use, you might need to collect other personal information from the customer. For example, AmeriNet requires the customer s date of birth, and TeleCheck requires the customer s driver s license information. Corporate Checks If you are processing corporate checks with TeleCheck, you must include either both billto_driverslicensenumber and billto_driverslicensestate, or both billto_company and billto_companytaxid. If you are processing corporate checks with AmeriNet, set the billto_dateofbirth to Reconciliation ID Bank Account Number Check Number In the electronic check debit reply, you receive a unique reconciliation ID that is assigned by CyberSource. You use it to reconcile the transactions in your CyberSource reports with 30 CyberSource Corporation

39 Chapter 3 Processing Electronic Check Orders the transactions in your processor reports. This number appears in the ecdebitreply_ reconciliationid field. Coupons You can accept coupons with electronic check orders just as you can with credit card orders. For information about using coupons, see Using Coupons on page 54. Seeing When the Check Has Cleared To determine when your electronic checks have cleared, use the Payment Events Report, which is available in the Business Center. For TeleCheck, when the check clears, the event type listed in the report is Payment. If you use AmeriNet, the report shows an event type of Payment when AmeriNet receives your debit request. AmeriNet then waits for six days, and if they receive no word from the bank of any problems transferring the funds, they consider the check cleared. You then see an event type of Completed for the check. CyberSource does not guarantee that the check has truly cleared. The report also shows when other events occur. For example, it shows if the bank has any problems processing the check (insufficient funds, errors, and so on), and when refunds clear. For more information about the Payment Events Report, see the Business Center Reporting User s Guide. Refunding the Customer s Money If you need to refund the customer s money, we suggest you use the Business Center. See the Business Center User s Guide for information about how to credit the customer s bank account. If your business s order and credit volume is large enough, you might instead consider processing credits by using the API. See Processing Credits with the API on page 70 for more information about using the API to process credits. Testing Your Implementation To test your electronic check implementation, you may use the test server or production server: Test: Production: Business Center Simple Order API User s Guide June

40 Electronic Check Debit API Fields You select which server to use in the CyberSource client configuration (see the documentation for your client for more information). Your status in the Business Center will typically already be live when testing electronic checks, so only transactions that you send to the production server will appear in the Business Center. You may, however, send transactions to the test server to verify your requests and responses. CyberSource recommends that you test on the production server, using your own bank account and debits for small amounts such as $2.00. Check your bank statements to verify that the money moves as you expect. You should also test the credit function in the Business Center (and with the API if you are using the API for credits). Electronic Check Debit API Fields Request Fields Table 3 lists the request fields you use when requesting an electronic check debit. Table 3 Electronic Check Debit Request Fields Field Name Description Required / Optional Data Type & Length billto_city City of the billing address. Required String (50) billto_company Name of the customer s company. Used only for TeleCheck corporate checks. For these checks, either both billto_driverslicensenumber and billto_driverslicensestate are required, or both billto_company and billto_companytaxid are required. See field description String (40) billto_companytaxid Company s tax identifier. Used only for TeleCheck corporate checks. For these checks, either both billto_driverslicensenumber and billto_ driverslicensestate are required, or both billto_company and billto_companytaxid are required. See field description String with numbers only (9) 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) 32 CyberSource Corporation

41 Chapter 3 Processing Electronic Check Orders Table 3 Electronic Check Debit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length billto_dateofbirth Customer s date of birth. Use format YYYY-MM- DD or YYYYMMDD. NOTE If using AmeriNet, check with them to see if they require you to provide this field. Optional (For AmeriNet, see field description) String (10) For AmeriNet corporate checks, use the value billto_ driverslicensenumber Customer s driver s license number. Required for TeleCheck personal checks. See field description String (30) For TeleCheck corporate checks, either both billto_driverslicensenumber and billto_ driverslicensestate are required, or both billto_company and billto_companytaxid are required. billto_ driverslicensestate State or province where the customer s driver s license was issued. Used only for TeleCheck. Use the two-character codes. See field description String (2) Required for TeleCheck personal checks. For TeleCheck corporate checks, either both billto_driverslicensenumber and billto_ driverslicensestate are required, or both billto_company and billto_companytaxid are required. billto_ billto_firstname billto_ipaddress billto_lastname Customer s address, including the full domain name (for example, [email protected]). Customer s first name. If the first name is unavailable or inapplicable (for example, for a corporate account), enter a dummy value such as NA. Customer s IP address (for example, ). Customer s last name. If the transaction is for a corporate account, use the company name. Required String (255) Required String (60) Optional String (15) Required String (60) billto_phonenumber Customer s phone number. Required String (15) Business Center Simple Order API User s Guide June

42 Electronic Check Debit API Fields Table 3 Electronic Check Debit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length billto_postalcode billto_state Postal code of the billing address. The field must contain between five and nine digits. If the value of billto_country is CA, the number of characters in billto_postalcode must follow these rules: If the number of characters is greater than three, the first three characters must be of the format [alpha][numeric][alpha]. If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric]. State or province of the billing address. Use the two-character codes. Required String (10) Required String (2) billto_street1 First line of the billing street address. Required String (60) billto_street2 Second line of the billing street address. Used for additional address information, for example: Attention: Accounts Payable Optional String (60) check_accountnumber Customer s checking account number. Required String with numbers only (17) check_accounttype Checking account type. This field can contain one of the following values: C: Checking S: Savings X: Corporate checking Required String (1) check_banktransitnumber Bank routing number (also known as the transit number ). Required String with numbers only (9) check_checknumber Check number. NOTE If using AmeriNet, check with them to see if they require you to provide this field. Optional (for AmeriNet, see field description) String with numbers only (8) comments Optional comments you have about the debit. These comments will not be shown to the customer. Optional String (255) 34 CyberSource Corporation

43 Chapter 3 Processing Electronic Check Orders Table 3 Electronic Check Debit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length ecdebitservice_ referencenumber For TeleCheck, this is an optional merchantgenerated reference number that TeleCheck uses to track the transaction in their system. If you do not send this field in your request, CyberSource generates a unique value for you and returns it in the reply field ecdebitreply_reconciliationid. See field description String (25) Not used for AmeriNet. ecdebitservice_run item_#_productcode Whether to include ecdebitservice in your request. The field can contain one of the following values: true: Include the service in your request. false (default): Do not include the service in your request. Type of product, which is also used to determine the category that the product falls under (electronic, handling, physical, service, or shipping). The default value is default. See Product Codes on page 41 for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_quantity, item_#_productname, and item_#_ productsku fields are required. Required String (5) Optional String (30) item_#_productname Name of the product. Required if item_#_ productcode is NOT default, stored_ value, or one of the values related to shipping and/or handling. See description String (30) item_#_productsku Product s identifier code. Required if item_#_ productcode is NOT default, stored_ value, or one of the values related to shipping and/or handling. See description String (15) item_#_quantity Quantity of the product being purchased. The default value is 1. Required if item_#_ productcode is NOT default, stored_ value, or one of the values related to shipping and/or handling. See description Integer (10) Business Center Simple Order API User s Guide June

44 Electronic Check Debit API Fields Table 3 Electronic Check Debit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length item_#_taxamount Total tax to apply to the product. This value cannot be negative. The item_#_taxamount field is additive. For example, if you send one item with unitprice of $10.00 and taxamount of $0.80, and you send another item with unitprice of $20.00 and taxamount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included. Optional String (15) item_#_unitprice Per-item price of the product. You must provide either this field or purchasetotals_ grandtotalamount in your request. See Using a Grand Total on page 12 for more information. See description String (15) You can use a decimal if you want. For example, you can use either or 100 to represent one hundred dollars. Do not include any special characters, such as a dollar sign ($). merchantdefineddata_ field1 merchantdefineddata_ field2 merchantdefineddata_ field3 merchantdefineddata_ field4 merchantid merchantreferencecode purchasetotals_currency Open field that you can use to store any information. The value appears in the transaction s details in the Business Center and in the Order Detail Report. NOTE Do not use the field to store any sensitive customer information. See the description for merchantdefineddata_ field1 above. See the description for merchantdefineddata_ field1 above. See the description for merchantdefineddata_ field1 above. Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Use the same merchantid for evaluation, testing, and production. Merchant-generated order reference or tracking number. See Order Identifiers on page 15 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Optional String (64) Optional String (64) Optional String (64) Optional String (64) Required String (30) Required String (50) Required String (5) 36 CyberSource Corporation

45 Chapter 3 Processing Electronic Check Orders Table 3 Electronic Check Debit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length purchasetotals_ grandtotalamount Grand total for the order. You must provide either this field or item_#_unitprice in your request. See Using a Grand Total on page 12 for more information. See field description String (15) shipto_city City to which to ship the product. Optional (Required if providing any shipping information) String (50) shipto_country shipto_ Country to which to ship the product. Use the twocharacter ISO codes. address of the person receiving the shipment (for example, [email protected]). Optional String (2) Optional String (255) shipto_firstname First name of the person receiving the shipment. Optional String (60) shipto_lastname First name of the person receiving the shipment. Optional String (60) shipto_phonenumber Phone number for the person receiving the shipment. Optional String (15) shipto_postalcode Postal code to which to ship the product. Optional (Required if address is in U.S. and Canada) String (10) shipto_state State or province to which to ship the product. Use the two-character codes. Optional (Required if address is in U.S. and Canada) String (2) shipto_street1 First line of the address to which to ship the product. Optional (Required if providing any shipping information) String (60) shipto_street2 Second line of the address to which to ship the product. Optional String (60) Business Center Simple Order API User s Guide June

46 Electronic Check Debit API Fields Reply Fields Table 4 lists the electronic check debit reply fields. Table 4 Electronic Check Debit Reply Fields Field Name decision Description Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT ERROR REJECT Data Type & Length String (6) ecdebitreply_amount Total amount submitted to the payment processor. String (15) ecdebitreply_ processortransactionid Transaction identifier or tracking ID returned by AmeriNet. String (87) ecdebitreply_reasoncode ecdebitreply_ reconciliationid ecdebitreply_ requestdatetime A numeric value corresponding to the result of the debit request. See Reason Codes for Electronic Check Services on page 49 for a list of possible values. Reference number that you use to reconcile your CyberSource reports with your processor reports. Time when debit is requested. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. Integer (5) String (60) String (20) ecdebitreply_ processorresponse Result code returned by the payment processor. String (6) ecdebitreply_ settlementmethod ecdebitreply_ verificationlevel Method used to settle the debit. This field will contain B to indicate best possible method (best of either ACH or facsimile). Level of screening for the request. This field will contain 1 to indicate validation. String (1) Integer (1) invalidfield_0...n Fields in the request that contained invalid data. String (100) merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) purchasetotals_currency Currency used for the order. For U.S. dollars, the value will be USD. String (5) reasoncode Numeric value corresponding to the result of the overall request. See Reason Codes on page 75 for a list of possible values. Integer (5) requestid Identifier for the request. String (26) 38 CyberSource Corporation

47 Chapter 3 Processing Electronic Check Orders Example Request and Reply The following examples show a request and reply for processing a payment with an electronic check. Example Electronic Check Debit Request ecdebitservice_run=true merchantid=infodev merchantreferencecode=482046c3a7e94f7 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_ [email protected] billto_dateofbirth= item_0_unitprice= purchasetotals_currency=usd check_accountnumber=4100 check_accounttype=c check_banktransitnumber= Example Electronic Check Debit Reply requestid= merchantreferencecode=482046c3a7e94f7 decision=accept reasoncode=100 ecdebitreply_reasoncode=100 ecdebitreply_settlementmethod=a ecdebitreply_requestdatetime= t23:48:09z ecdebitreply_amount= ecdebitreply_verificationlevel=1 ecdebitreply_reconciliationid=02ryxspgcqh60nwa ecdebitreply_processorresponse= purchasetotals_currency=usd Business Center Simple Order API User s Guide June

48 Example Request and Reply 40 CyberSource Corporation

49 Appendix A Product Codes This table lists the values you can use for the product code, which you can specify by using the item_#_productcode request field. Table 5 Product Code Values Product Code adult_content default electronic_good electronic_software gift_certificate handling_only service shipping_and_handling shipping_only stored_value subscription Definition Adult content. Default value for the product code. CyberSource uses default when a request provides no value for the product code. Electronic product other than software. Software distributed electronically rather than on tapes, disks, or other media. Gift certificate not issued with CyberSource Stored Value Services. Separate charge that is generally a fee imposed by the seller on the customer. The fee pays for the seller s administrative selling costs. Service that you perform for the customer. Shipping is a separate charge for shipping the product to the purchaser. Handling is generally a fee imposed by the seller to pay for administrative selling costs. Charge for transporting tangible personal property from the seller to the purchaser. Documentation must be maintained that clearly establishes where title to the tangible personal property passed from the seller to the purchaser. Stored Value certificate. Subscription to a Web site or other content. Business Center Simple Order API User s Guide June

50 42 CyberSource Corporation

51 Appendix B Description of Return Codes This appendix describes these result codes that you can receive: Address Verification Service Codes Card Verification Number Codes Smart Authorization Factor Codes Reason Codes for the Simple Order API Address Verification Service Codes The following table lists the possible result codes for the Address Verification Service. See Address Verification Service on page 4 for general information about AVS. Some of the codes have the same meaning. All codes are valid for any type of merchant to receive. You should be prepared to receive any of them. The alphabetic values in the table below are the Visa standard AVS codes. AVS codes for other types of credit cards are mapped to the Visa standard codes. Some codes are returned only for Visa cards issued outside the U.S. You receive these codes in the ccauthreply_avscode reply field. Table 6 Address Verification Service Codes Code Summary Description A Partial match Street address matches, but 5- and 9-digit postal codes do not match. B Partial match Street address matches, but postal code not verified. Returned only for non-u.s.-issued Visa cards. C No match Street address and postal code not verified. Returned only for non-u.s.-issued Visa cards. D Match Street address and postal code match. Returned only for non- U.S.-issued Visa cards. E Invalid AVS data is invalid. G Not supported Non-U.S. issuing bank does not support AVS. Business Center Simple Order API User s Guide June

52 Card Verification Number Codes Table 6 Address Verification Service Codes (Continued) Code Summary Description I No match Address not verified. Returned only for non-u.s.-issued Visa cards. N No match Street address, 5-digit postal code, and 9-digit postal code do not match. P Partial match Postal code matches, but street address not verified. Returned only for non-u.s.-issued Visa cards. R System unavailable System unavailable. S Not supported U.S.-issuing bank does not support AVS. U System unavailable Address information unavailable. Returned if non-u.s. AVS is not available or if the AVS in a U.S. bank is not functioning properly. W Partial match Street address does not match, but 9-digit postal code matches. X Match Exact match. Street address and 9-digit postal code match. Y Match Exact match. Street address and 5-digit postal code match. Z Partial Match Street address does not match, but 5-digit postal code matches. 1 Not supported CyberSource AVS code. AVS is not supported for this processor or card type. 2 Invalid CyberSource AVS code. The processor returned an unrecognized value for the AVS response. Card Verification Number Codes The following table lists the possible result codes for the Card Verification Number check. See Card Verification Number on page 5 for general information. You receive these codes in the ccauthreply_cvcode reply field. Table 7 Card Verification Codes Code D I M Description The issuing bank determined that the transaction is suspicious. Card verification number failed processor's data validation check. Card verification number matched. 44 CyberSource Corporation

53 Appendix B Description of Return Codes Table 7 Card Verification Codes (Continued) Code N P S U X Description Card verification number not matched. The processor did not process the card verification number for an unspecified reason. Card verification number is on the card but was not included in the request. Card verification is not supported by the issuing bank. Card verification is not supported by the card association. 1 Card verification is not supported for this processor or card type. 2 The processor returned an unrecognized value for the card verification response. 3 The processor did not return a card verification result code. Smart Authorization Factor Codes The following table lists the possible factor codes for Smart Authorization. See Smart Authorization on page 5 for general information. You receive these codes in the ccauthreply_authfactorcode reply field. Table 8 Smart Authorization Codes Code J M N O U X Description Billing and shipping address do not match. Cost of the order exceeds the maximum transaction amount. Nonsensical input in the customer name or address fields. Obscenities in the order form. Unverifiable billing or shipping address. Order does not comply with the USA PATRIOT Act. Business Center Simple Order API User s Guide June

54 Reason Codes for the Simple Order API Reason Codes for the Simple Order API This section lists the reason codes returned for the credit card and electronic check services. See API Replies on page 13 for a discussion of replies, decisions, and reason codes. 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. Reason Codes for Credit Card Services Table 9 Reason Codes for Credit Card Services Reason Code Description 100 Successful transaction. 101 The request is missing one or more required fields. Possible action: See the reply fields missingfield_0...n for which fields are missing. Resend the request with the complete information. 102 One or more fields in the request contains invalid data. Possible action: See the reply fields invalidfield_0...n for which fields are invalid. Resend the request with the correct information. 104 The merchantreferencecode sent with this authorization request matches the merchantreferencecode of another authorization request that you sent in the last 15 minutes. Possible action: Resend the request with a unique merchantreferencecode value. 150 Error: General system failure. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. 151 Error: The request was received but there was a server timeout. This error does not include timeouts between the client and the server. Possible action: To avoid duplicating the order, do not resend the request until you have reviewed the order status in the Business Center. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. 152 Error: The request was received, but a service did not finish running in time. Possible action: To avoid duplicating the order, do not resend the request until you have reviewed the order status in the Business Center. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. 46 CyberSource Corporation

55 Appendix B Description of Return Codes Table 9 Reason Codes for Credit Card Services (Continued) Reason Code Description 201 The issuing bank has questions about the request. You do not receive an authorization code programmatically, but you might receive one verbally by calling the processor. Possible action: Call your processor or the issuing bank to possibly receive a verbal authorization. For contact phone numbers, refer to your merchant bank information. 202 Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file. Possible action: Request a different card or other form of payment. 203 General decline of the card. No other information provided by the issuing bank. Possible action: Request a different card or other form of payment. 204 Insufficient funds in the account. Possible action: Request a different card or other form of payment. 205 Stolen or lost card. Possible action: Review the customer s information and determine if you want to request a different card from the customer. 207 Issuing bank unavailable. Possible action: Wait a few minutes and resend the request. 208 Inactive card or card not authorized for card-not-present transactions. Possible action: Request a different card or other form of payment. 210 The card has reached the credit limit. Possible action: Request a different card or other form of payment. 211 Invalid card verification number. Possible action: Request a different card or other form of payment. 221 The customer matched an entry on the processor s negative file. Possible action: Review the order and contact the payment processor. 231 Invalid account number. Possible action: Request a different card or other form of payment. 232 The card type is not accepted by the payment processor. Possible action: Request a different card or other form of payment. Also, check with CyberSource Customer Support to make sure your account is configured correctly. 233 General decline by the processor. Possible action: Request a different card or other form of payment. Business Center Simple Order API User s Guide June

56 Reason Codes for the Simple Order API Table 9 Reason Codes for Credit Card Services (Continued) Reason Code Description 234 There is a problem with your CyberSource merchant configuration. Possible action: Do not resend the request. Contact Customer Support to correct the configuration problem. 235 The requested amount exceeds the originally authorized amount. Occurs, for example, if you try to capture an amount larger than the original authorization amount. This reason code only applies if you are processing a capture through the API. See Using the API for Captures and Credits on page 55. Possible action: Issue a new authorization and capture request for the new amount. 236 Processor failure. Possible action: Tell the customer the payment processing system is unavailable temporarily, and to try their order again in a few minutes. 238 The authorization has already been captured. This reason code only applies if you are processing a capture through the API. See Using the API for Captures and Credits on page 55. Possible action: No action required. 239 The requested transaction amount must match the previous transaction amount. This reason code only applies if you are processing a capture or credit through the API. See Using the API for Captures and Credits on page 55. Possible action: Correct the amount and resend the request. 240 The card type sent is invalid or does not correlate with the credit card number. Possible action: Ask your customer to verify that the card is really the type that they indicated in your Web store, then resend the request. 241 The request ID is invalid. This reason code only applies when you are processing a capture or credit through the API. See Using the API for Captures and Credits on page 55. Possible action: Request a new authorization, and if successful, proceed with the capture. 242 You requested a capture through the API, but there is no corresponding, unused authorization record. Occurs if there was not a previously successful authorization request or if the previously successful authorization has already been used by another capture request. This reason code only applies when you are processing a capture through the API. See Using the API for Captures and Credits on page 55. Possible action: Request a new authorization, and if successful, proceed with the capture. 246 The capture or credit is not voidable because the capture or credit information has already been submitted to your processor. Or, you requested a void for a type of transaction that cannot be voided. This reason code applies only if you are processing a void through the API. See Using the API for Voids on page 63 for information about voids. Possible action: No action required. 48 CyberSource Corporation

57 Appendix B Description of Return Codes Table 9 Reason Codes for Credit Card Services (Continued) Reason Code Description 247 You requested a credit for a capture that was previously voided. This reason code applies only if you are processing a void through the API. See Using the API for Voids on page 63 for information about voids. Possible action: No action required. 250 Error: The request was received, but there was a timeout at the payment processor. Possible action: To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. 520 The authorization request was approved by the issuing bank but declined by CyberSource based on your Smart Authorization settings. Possible action: Do not capture the authorization without further review. Review the ccauthreply_avscode, ccauthreply_cvcode, and ccauthreply_authfactorcode fields to determine why CyberSource rejected the request. Reason Codes for Electronic Check Services Table 10 lists the reason codes returned for the electronic check services. Table 10 Reason Codes for Electronic Check Services Reason Code Description 100 Successful transaction. 101 The request is missing one or more required fields. Possible action: See the reply fields missingfield_0...n for which fields are missing. Resend the request with the complete information. 102 One or more fields in the request contains invalid data. Possible action: See the reply fields invalidfield_0...n for which fields are invalid. Resend the request with the correct information. 150 Error: General system failure. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. 151 Error: The request was received, but there was a server timeout. This error does not include timeouts between the client and the server. Possible action: To avoid duplicating the order, do not resend the request until you have reviewed the order status in the Business Center. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. Business Center Simple Order API User s Guide June

58 Reason Codes for the Simple Order API Table 10 Reason Codes for Electronic Check Services Reason Code Description 152 Error: The request was received, but a service did not finish running in time. Possible action: To avoid duplicating the order, do not resend the request until you have reviewed the order status in the Business Center. See the documentation for your CyberSource client (SDK) for information about how to handle retries in the case of system errors. 220 The processor declined the request based on a general issue with the customer s account. Possible action: Request a different form of payment. 221 The customer matched an entry on the processor s negative file. Possible action: Review the order and contact the payment processor. 222 The customer s bank account is frozen. Possible action: Review the order or request a different form of payment. 233 The processor declined the request based on an issue with the request itself. Possible action: Request a different form of payment. 234 There is a problem with your CyberSource merchant configuration. Possible action: Do not resend the request. Contact Customer Support to correct the configuration problem. 236 Processor failure. Possible action: Wait a few minutes and resend the request. 241 The request ID is invalid for the follow-on request. This reason code is returned for follow-on credits only (see Appendix D, Advanced API Capabilities for Electronic Checks, on page 69). Possible action: Verify the request ID is valid and resend the request. 250 Error: The request was received, but there was a timeout at the payment processor. Possible action: To avoid duplicating the order, do not resend the request until you have reviewed the order status in the Business Center. 50 CyberSource Corporation

59 Appendix C Advanced API Capabilities for Credit Cards This appendix describes several advanced API topics: Additional Authorization Features Using the API for Captures and Credits Using the API for Voids Using Payer Authentication Additional Authorization Features This section describes several other credit card authorization features that you may want to 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 Using a Subscription for a Payment If you are using CyberSource s Subscription Payment Services, you can process an authorization, sale, or credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database. Simply request the service(s) you want to run and include recurringsubscriptioninfo_ subscriptionid. When you provide recurringsubscriptioninfo_subscriptionid, you must provide these other fields in the request: merchantid merchantreferencecode item_0_unitprice or purchasetotals_grandtotalamount to indicate the amount of the payment or credit Business Center Simple Order API User s Guide June

60 Additional Authorization Features All the information stored in the subscription will be used for the payment or credit, including required information such as the customer s name, billing address, and credit card information. Any optional information you stored in the subscription will also be used, including the shipping address and whether the transaction is part of Visa s Bill Payment program (see Indicating a Visa Bill Payment on page 52). Note that you can override most of the information stored in the subscription (except the credit card number) by including the relevant API fields in the request. For example, you could provide a different billing or shipping address with the request. For information about subscriptions, see the Business Center Subscription Payments User s Guide. Performing a Forced Capture If you are using Vital as your processor, you can perform forced captures. A forced capture occurs when you process an authorization outside the CyberSource system but capture the order by using CyberSource. Note You can perform a forced capture in the Business Center s Virtual Terminal. There, when you select the transaction type, select Capture with Verbal Auth. The Business Center automatically performs both the authorization and capture. Follow these steps to perform a forced capture through the API: 1 After you have processed the authorization outside the CyberSource system, request a CyberSource authorization (ccauthservice) as described in Requesting an Authorization on page 16. As part of the request, include these fields: ccauthservice_authtype=verbal ccauthservice_verbalauthcode=<the authorization code you received> This authorization request does not get sent to the processor; CyberSource simply stores the information so that it can be used later for the capture. 2 When ready, request the capture just like you would a normal capture. You do not need to provide the authorization code in the capture because CyberSource already has it in the database. The forced capture is processed. Indicating a Visa Bill Payment Customers may pay bills (for example, their monthly utilities bills) by using their Visa cards. Visa has a special Bill Payment program for this that you can take part in. If you do, Visa requests that you flag the bill payments and credits so they can be easily identified. Although we accept the bill payment indicator no matter which processor you are using, currently we forward the information only to Vital. Note that you should not use this indicator if you have not signed up with Visa to take part in the program. 52 CyberSource Corporation

61 Appendix C Advanced API Capabilities for Credit Cards To flag a payment with the indicator, request an authorization as described in Requesting an Authorization on page 16, and include ccauthservice_billpayment=y. The default value is N (not a bill payment). Indicating a Recurring Payment Depending on the type of products or services you sell, you may want to process recurring payments for a customer. For example, you may want to charge a customer $19.95 each month to access a service that you offer. Note A customer s recurring payment does not have to be for the exact same amount each time. Make sure that you disclose clearly to your customers when they purchase the product or service what the amount will be for the recurring payments. If the amount varies based on usage, make this clear. To create a recurring payment: 1 For the first payment, send a regular request for credit card authorization. Only if the first authorization is successful should you then submit authorizations for recurring payments for that card. 2 For each subsequent recurring payment, send an authorization request with ccauthservice_commerceindicator=recurring to indicate the payment is a recurring payment. CyberSource supports recurring payments for the following processors: FDMS South: Visa, MasterCard FDMS Nashville: Visa, MasterCard, American Express, Discover Paymentech: Visa, MasterCard, American Express, Discover Vital: Visa, MasterCard, American Express, Discover Note American Express and Discover have programs that you must sign up for if you want to process recurring payments. Contact American Express and Discover for details about their programs. CyberSource also offers a recurring billing service that allows you to create a payment subscription for a customer in the CyberSource system. CyberSource then automatically bills the customer for you according to your instructions. CyberSource s system eliminates the need for you to create your own system to regularly bill customers and to store their account information. For more information about the service, see the Business Center Subscription Payments User Guide. AVS and Recurring Payments. The Address Verification Service is run for every authorization request that you submit. For recurring payments, you should check the AVS Business Center Simple Order API User s Guide June

62 Additional Authorization Features result for the initial payment to ensure the information is accurate and to reduce the risk of fraud. You must decide, however, how to handle the AVS results for the subsequent recurring payments. You may want to ignore the AVS results for the recurring payments, as you have already confirmed with the initial payment whether the credit card number is valid and non-fraudulent. If you need to change the credit card number used for a series of recurring payments, treat the first authorization with the new credit card number as a non-recurring payment, and closely evaluate the AVS results. You may then flag the subsequent payments as recurring and consider ignoring the AVS results. Replacement Expiration Date for Recurring Payments. Normally when you request a credit card authorization, you must supply a valid expiration date for the credit card. If you are processing a recurring payment and the credit card that you have on file for the customer has expired, you might still be able to request the authorization, depending on which processor you use. Instead of sending the out-of-date expiration date, you can send a replacement expiration date of month=12 and year=2021. Important Do not use the replacement expiration date for cards that have not yet expired. Use the replacement expiration date only for recurring payments. Using the replacement expiration date for a recurring payment does not guarantee that the authorization will be successful. The issuing bank ultimately determines if a card is authorized; some issuing banks will not accept an expiration date that does not match what they have in their database. CyberSource supports the replacement expiration date for the following processors: FDMS South: Visa, MasterCard Paymentech: Visa, MasterCard Using Coupons You can offer your customers virtual coupons at your Web store. CyberSource defines a coupon as a non-taxable, fixed amount deducted from an order total. Coupon examples you might implement include: Register now and get $100 off your purchase! Spring clearance! Get $10 off any order! Thank you for ordering again within 30 days! We re taking $5 off your order! CyberSource processes the coupon by totaling all of the line items and then deducting the amount of the coupon(s). The total coupon amount cannot be greater than the order grand 54 CyberSource Corporation

63 Appendix C Advanced API Capabilities for Credit Cards total. Precalculate your order totals before you send your requests to CyberSource so that you do not send orders with negative subtotals (which will result in an error). You cannot use coupons to do the following: Apply a discount to a specific item in a multi-item order Apply a percentage discount To request a coupon with an order, include in the authorization request an item with the product code set to coupon. For example, if your request contains two items, item_0 and item_1, request a coupon by adding item_2. The example below show how to specify a $10 coupon. The quantity, productname, and productsku fields are required. item_2_unitprice=10.00 item_2_quantity=1 item_2_productcode=coupon item_2_productname=spring Clearance item_2_productsku= Using the API for Captures and Credits The main chapters in this guide say to use the Business Center to perform captures and credits. You can, however, perform captures and credits through the API. Whether you do this depends on the volume of orders you have and how you have structured your fulfillment system. If you want to process Level III transactions with Vital, see the Level III Supplement to this guide. Requesting a Capture To request a capture, send a request and set the cccaptureservice_run field to true. Also include all the required fields listed in Table 11. Processing a Verbal Authorization A verbal authorization occurs when you request an authorization through CyberSource, and the issuing bank asks you to call the payment processor to answer questions about the order (reasoncode=201). In this case, you do not receive an authorization code programmatically in the reply, but you may be able to receive one verbally over the phone. Once you have the code, you may then request a capture through the API and include the verbal authorization code as part of the capture request. Note For normal authorizations, you receive the authorization code programmatically. For verbal authorizations, you receive the code manually. Make sure you can enter verbal authorization codes manually into your order system. Business Center Simple Order API User s Guide June

64 Using the API for Captures and Credits Important Do not confuse the verbal authorization discussed here with a forced capture. The difference is that with a verbal authorization, you get the authorization code directly from the processor or issuing bank after requesting an authorization through CyberSource and receiving a CyberSource decline. With a forced capture, you get the authorization code by performing an authorization outside of CyberSource. In both cases, you follow up with a capture that uses CyberSource s system. For information about processing forced captures, see Performing a Forced Capture on page 52. Using verbal authorization, you can request to capture an authorization that was declined for any of the following reasons: Verbal authorization required Card expired Card refused Invalid card To capture an authorization with a verbal authorization code, send the authorization code in the cccaptureservice_verbalauthcode request field. Also, include the word verbal in the cccaptureservice_authtype field. Note You must set the cccaptureservice_authtype field to verbal or else the cccaptureservice_verbalauthcode field will be ignored. Capture Request Fields Table 11 lists the fields you use to request a capture. Table 11 Capture Request Fields Field Name Description Required / Optional Data Type & Length billto_customerid Your identifier for the customer. Optional String (50) cccaptureservice_ authrequestid Value of requestid returned from the credit card authorization reply. Required String (26) cccaptureservice_ authtype Set to verbal to indicate a verbal authorization. See Processing a Verbal Authorization on page 55. Required for a verbal authorization String (6) cccaptureservice_run Set to true to include the credit card capture service in your request. Required String (5) cccaptureservice_ verbalauthcode Verbally obtained authorization code. See Processing a Verbal Authorization on page 55. Required for a verbal authorization String (6) 56 CyberSource Corporation

65 Appendix C Advanced API Capabilities for Credit Cards Table 11 Capture Request Fields (Continued) Field Name Description Required / Optional Data Type & Length comments item_#_productcode Optional comments you have about the capture. These comments will not be shown to the customer. For descriptions for all of the item_#_ fields, see Table 1 on page 21. Optional String (255) Optional String (30) item_#_productname Optional String (30) item_#_productsku Optional String (15) item_#_quantity Optional Integer (10) item_#_taxamount Optional String (15) item_#_unitprice Per-item price of the product. You must provide either this field or purchasetotals_ grandtotalamount in your request. See Using a Grand Total on page 12 for more information. See description String (15) merchantdefineddata_ field1 merchantdefineddata_ field2 merchantdefineddata_ field3 merchantdefineddata_ field4 merchantid merchantreferencecode purchasetotals_currency Open field that you can use to store any information. Do not use the field to store any sensitive customer information. NOTE If you provided these fields with the authorization, you will see the authorization s values in the Business Center and the Order Detail Report and not the values you provided with the capture. See the description for merchantdefineddata_ field1 above. See the description for merchantdefineddata_ field1 above. See the description for merchantdefineddata_ field1 above. Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Merchant-generated order reference or tracking number. Use the same value that you used for the authorization. See Order Identifiers on page 15 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Optional String (64) Optional String (64) Optional String (64) Optional String (64) Required String (30) Required String (50) Required String (5) Business Center Simple Order API User s Guide June

66 Using the API for Captures and Credits Table 11 Capture Request Fields (Continued) Field Name Description Required / Optional Data Type & Length purchasetotals_ grandtotalamount Grand total for the order. You must provide either this field or item_#_unitprice in your request. See Using a Grand Total on page 12 for more information. See description String (15) Capture Reply Fields Table 12 lists the capture reply fields. Table 12 Capture Reply Fields Field Name Description Data Type & Length cccapturereply_amount Total amount of the capture. String (15) cccapturereply_ reasoncode cccapturereply_ reconciliationid cccapturereply_ requestdatetime decision Numeric value corresponding to the result of the capture request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Reference number that you use to reconcile your CyberSource reports with your processor reports. Time when capture is requested. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded ERROR: There was a system error REJECT: One or more of the services in the request was declined Integer (5) String (60) String (20) String (6) invalidfield_0...n Fields in the request that contained invalid data. String (100) merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) purchasetotals_ currency Currency used for the order. For U.S. dollars, the value will be USD. String (5) reasoncode Numeric value corresponding to the result of the overall request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Integer (5) 58 CyberSource Corporation

67 Appendix C Advanced API Capabilities for Credit Cards Table 12 Capture Reply Fields (Continued) Field Name requestid Description Identifier for the request. Note that this request ID is different than the request ID you received for the authorization request. Data Type & Length String (26) Requesting a Credit Normally you will process credits through the Business Center. There, you search for the original order, CyberSource retrieves the order information from the database, and then you click a button to perform the credit. This type of credit is called a follow-on credit because it references the order information stored in our database. You can also perform a follow-on credit through the API. You provide the request ID from the authorization in the cccreditservice_capturerequestid field and we use that to reference the order information from the authorization. However, the order data is available for only 60 days after the authorization. If you need to refund a customer s money after that period, you can request a credit in the Business Center where the data retention is 120 days or perform a stand-alone credit. It is called stand-alone because it does not rely on previous order information stored in our database. Instead, you must get from the customer their credit card number and billing address, and provide that information to CyberSource in a credit request through the API. To request either type of credit, send a request and set the cccreditservice_run field to true. Also include all the required fields as listed in Table 13. Using a Subscription for a Credit If you are using CyberSource s Subscription Payment Services, you can process a credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database. Simply provide the subscription ID in recurringsubscriptioninfo_subscriptionid. See Using a Subscription for a Payment on page 51 for more information about the other fields that are required. Indicating a Credit for a Visa Bill Payment Customers may pay bills (for example, their monthly utilities bills) by using their Visa cards. Visa has a special Bill Payment program for this that you can take part in. If you do, Visa requests that you flag the bill payments and credits so they can be easily identified. Although we accept the bill payment indicator no matter which processor you are using, currently we forward the information only to Vital. Note that you should not use this indicator if you have not signed up with Visa to take part in the program. To flag a credit with the indicator, request a credit as described in Requesting a Credit on page 59, and include cccreditservice_billpayment=y. The default value is N (not a bill payment). Business Center Simple Order API User s Guide June

68 Using the API for Captures and Credits Credit Request Fields Table 13 lists the fields you use to request a credit. The fields with asterisks (**) are optional for follow-on credits. Table 13 Credit Request Fields Field Name Description Required / Optional Data Type & Length billto_city For descriptions for all of the billto_ fields, see Table 1 on page 21. Required ** String (50) billto_country Required ** String (2) billto_customerid Your identifier for the customer. Optional String (50) billto_ Required ** String (255) billto_firstname Required ** String (60) billto_lastname Required ** String (60) billto_phonenumber Optional String (15) billto_postalcode billto_state Required for U.S. and Canada ** Required for U.S. and Canada ** String (10) String (2) billto_street1 Required ** String (60) billto_street2 Optional String (60) card_accountnumber Customer s credit card number. Required ** String with numbers only (20) card_expirationmonth card_expirationyear ** Optional for follow-on credits Two-digit month (MM - 01 through 12, inclusive) that the credit card expires in. The leading 0 is required. Four-digit year (YYYY) that the credit card expires in. Required ** String (2) Required ** String (4) 60 CyberSource Corporation

69 Appendix C Advanced API Capabilities for Credit Cards Table 13 Credit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length cccreditservice_billpayment Indicates to Visa if the credit is part of the Visa Bill Payment program. Currently supported only for Vital. Use one of the following values: N (default): Not a bill payment Y: Bill payment See Indicating a Credit for a Visa Bill Payment on page 59. Optional String (1) cccreditservice_ capturerequestid The requestid returned from a previous request for capture. Creates a follow-on credit by linking the credit to the previous capture. If you send this field, you do not need to send the customer s name, the billing address, or the credit card information. Required for a follow-on credit String (26) cccreditservice_ commerceindicator cccreditservice_run comments item_#_productcode Type of transaction. Use with stand-alone credits. Certain card associations use this information when determining discount rates. This field can contain one of the following values: internet (default): ecommerce order placed using a Web site. moto: Mail order or telephone order. recurring: Recurring mail order or telephone transaction. See Indicating a Recurring Payment on page 53 for a list of processors that support this value. Set to true to include the credit service in your request. Optional comments you have about the credit. These comments will not be shown to the customer. For descriptions for all of the item_#_ fields, see Table 1 on page 21. Optional String (13) Required String (5) Optional String (255) Optional String (30) item_#_productname Optional String (30) item_#_productsku Optional String (15) item_#_quantity Optional Integer (10) item_#_taxamount Optional String (15) ** Optional for follow-on credits Business Center Simple Order API User s Guide June

70 Using the API for Captures and Credits Table 13 Credit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length item_#_unitprice Per-item price of the product. You must provide either this field or purchasetotals_ grandtotalamount in your request. See Using a Grand Total on page 12 for more information. See description String (15) merchantdefineddata_field1 merchantdefineddata_field2 merchantdefineddata_field3 merchantdefineddata_field4 merchantid merchantreferencecode purchasetotals_currency Open field that you can use to store any information. Do not use the field to store any sensitive customer information. NOTE If you are performing a follow-on credit and you provided these fields with the authorization, you will see the authorization s values in the Business Center and the Order Detail Report and not the values you provided with the credit. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See Order Identifiers on page 15 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Optional String (64) Optional String (64) Optional String (64) Optional String (64) Required String (30) Required String (50) Required String (5) purchasetotals_ grandtotalamount Grand total for the order. You must provide either this field or item_#_unitprice in your request. See Using a Grand Total on page 12 for more information. See description String (15) recurringsubscriptioninfo_ subscriptionid ** Optional for follow-on credits Subscription ID). If you are using the Subscription Payment Services, you can request a credit and use a subscription ID to reference the subscription information. See Using a Subscription for a Credit on page 59. Optional String (26) 62 CyberSource Corporation

71 Appendix C Advanced API Capabilities for Credit Cards Credit Reply Fields Table 14 lists the credit reply fields. Table 14 Credit Reply Fields Field Name Description Data Type & Length cccreditreply_amount Total amount of the credit. String (15) cccreditreply_ reasoncode cccreditreply_ reconciliationid cccreditreply_ requestdatetime decision Numeric value corresponding to the result of the credit request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Reference number that you use to reconcile your CyberSource reports with your processor reports. Time when credit is requested. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded ERROR: There was a system error REJECT: One or more of the services in the request was declined Integer (5) String (60) String (20) String (6) invalidfield_0...n Fields in the request that contained invalid data. String (100) merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) purchasetotals_ currency Currency used for the order. For U.S. dollars, the value will be USD. String (5) reasoncode requestid Numeric value corresponding to the result of the overall request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Identifier for the request. Note that this request ID is different from the ones you received for the authorization and capture requests. Integer (5) String (26) Using the API for Voids You can void captures and credits in the Business Center or by using the Simple Order API. This section describes how to use the API to process voids. You request a void when you want to cancel a capture or credit request that you have submitted to CyberSource. A transaction can be voided only if we have not already Business Center Simple Order API User s Guide June

72 Using the API for Voids submitted the capture or credit information to your processor. Usually we submit that type of information to your processor once a day, so your window for successfully performing a void is relatively small. We will decline your void request if we have already sent the capture or credit information to the processor. When you void a transaction, the transaction is at the end of its life and cannot be the source of another follow-on capture or credit. For example, if you authorize and capture a transaction, and then you void the capture, you cannot submit another capture request that uses the authorization code or CyberSource request ID from the original authorization. If you still want to capture that transaction, you must re-authorize the transaction and capture the new authorization. You cannot undo a void. Also, you cannot perform a follow-on credit for a transaction that has been voided. To request a void, set the voidservice_run field to true and set the other fields described in Table 15 below. When you request a void, do not request any other ICS services. You can receive two additional reason codes for void requests: 246: The capture or credit is not voidable because the capture or credit information has already been submitted to your processor. Or, you requested a void for a type of transaction that cannot be voided. 247: You requested a credit for a capture that was previously voided. Void Request Fields Table 15 lists the fields you use to request a void. Table 15 Void Request Fields Field Name Description Required / Optional Data Type & Length merchantid merchantreferencecode Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See Order Identifiers on page 15 for more information. Required String (30) Required String (50) voidservice_run Set to true to include the void service in your request. Required String (5) voidservice_ voidrequestid The requestid of the capture or credit you want to void. Required String (26) 64 CyberSource Corporation

73 Appendix C Advanced API Capabilities for Credit Cards Reply Field decision Void Reply Fields Table 16 lists the void reply fields. Table 16 Void Reply Fields Brief Description Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded ERROR: There was a system error REJECT: One or more of the services in the request was declined Data Type & Length String (6) invalidfield_0...n Fields in the request that contained invalid data. String (100) merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) reasoncode requestid Numeric value corresponding to the result of the overall request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Identifier for the request. Note that this request ID is different from the ones you received for the authorization and capture requests. Integer (5) String (26) voidreply_amount Total amount of the void. String (15) voidreply_currency voidreply_reasoncode voidreply_ requestdatetime Currency used for the order. For U.S. dollars, the value will be USD. Numeric value corresponding to the result of the void request. See Reason Codes for the Simple Order API on page 46 for a list of possible values. Time when void was requested. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. String (5) Integer (5) String (20) Using Payer Authentication CyberSource supports Verified by Visa SM and MasterCard SecureCode, and JCB J/ Secure Payer Authentication for these processors: Business Center Simple Order API User s Guide June

74 Using Payer Authentication Verified by Visa: FDMS Nashville, FDMS South, Paymentech New Hampshire, and Vital MasterCard SecureCode: FDMS Nashville, FDMS South, and Vital JCB J/Secure: Vital If you are using Payer Authentication, you have additional fields that you must supply when you request an authorization. You receive the values for these fields from the Payer Authentication services when you check a cardmember s enrollment in the program and validate the cardmember s authentication. For more information about Payer Authentication, see the Payer Authentication Implementation Guide. Table 17 lists the additional fields to use with the authorization. Table 17 Additional Authorization Fields for Payer Authentication Field Name Description Used By (Required/ Optiona) Data Type & Length ccauthservice_cavv Transaction identifier generated by the issuing bank for Verified by Visa and JCB J/Secure transactions. Must be 28- character base64 or 40-character hex binary. Required for Verified by Visa transactions if ccauthservice_ commerceindicator = vbv or vbv_attempted. Required for JCB J/Secure transactions if ccauthservice_commerceindicator = js. Optional if ccauthservice_ commerceindicator = js_attempted. ccauthservice See field description String (40) ccauthservice_ commerceindicator Type of transaction. Use one of these values for transactions that use Payer Authentication: js: Successful JCB J/Secure transaction. Supported for Vital. If selected, then ccauthservice_cavv and ccauthservice_xid are required. js_attempted: JCB J/Secure transaction was attempted but not authenticated. Supported for Vital. If selected, then ccauthservice_cavv and ccauthservice_xid are optional. ccauthservice (required for all Payer Authentication transactions) String (13) 66 CyberSource Corporation

75 Appendix C Advanced API Capabilities for Credit Cards Table 17 Additional Authorization Fields for Payer Authentication (Continued) Field Name Description Used By (Required/ Optiona) Data Type & Length spa: MasterCard SecureCode transaction. If selected, then ucaf_ collectionindicator is required. If authentication is successful, ucaf_ authenticationdata is also required. vbv: Successful Verified by Visa transaction. If selected, then ccauthservice_cavv and ccauthservice_xid are required. vbv_attempted: Verified by Visa transaction was attempted but not authenticated. If selected, then ccauthservice_cavv is required and ccauthservice_xid is optional. ccauthservice_xid Transaction identifier value for Verified by Visa and JCB J/Secure transactions, generated during Payer Authentication. Must be 28-character base-64 or 40- character hex-binary. ccauthservice See field description String (40) Required for Verified by Visa transactions if ccauthservice_ commerceindicator = vbv. Optional if ccauthservice_commerceindicator = vbv_attempted. Required for JCB J/Secure transactions if ccauthservice_commerceindicator = js. Optional if ccauthservice_ commerceindicator = js_attempted. ucaf_authenticationdata MasterCard SecureCode UCAF authentication data. Required for MasterCard SecureCode transactions only if ucaf_ collectionindicator = 2. ccauthservice See field description String (32) Business Center Simple Order API User s Guide June

76 Using Payer Authentication Table 17 Additional Authorization Fields for Payer Authentication (Continued) Field Name Description Used By (Required/ Optiona) Data Type & Length ucaf_collectionindicator Indicates whether the MasterCard SecureCode UCAF data is collected. This field can contain one of the following values: 0: UCAF collection is not supported at your Web site. 1: UCAF collection is supported, but UCAF was not populated. 2: UCAF collection is supported, and UCAF was populated. Successful MasterCard SecureCode transaction. ccauthservice (required for MasterCard SecureCode transactions) String with numbers only (1) Required for all MasterCard SecureCode transactions (ccauthservice_commerceindicator = spa). 68 CyberSource Corporation

77 Appendix D Advanced API Capabilities for Electronic Checks This appendix describes how to use the API to perform electronic check credits and includes these sections: Using a Subscription for a Debit or Credit Processing Credits with the API Reason Codes Using a Subscription for a Debit or Credit If you are using CyberSource s Subscription Payment Services, you can process a debit or credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database. Simply request the service you want to run and include recurringsubscriptioninfo_ subscriptionid. When you provide recurringsubscriptioninfo_subscriptionid, the only other fields you must provide in the request are: merchantid merchantreferencecode item_0_unitprice or purchasetotals_grandtotalamount to indicate the amount of the debit or credit All the information stored in the subscription will be used for the debit or credit, including required information such as the customer s name, billing address, and bank account information. Any optional information you stored in the subscription will also be used, including the shipping address. Note that you can override most of the information stored in the subscription (except the bank account number) by including the relevant API fields in the request. For example, you could provide a different billing or shipping address with the request. For information about subscriptions, see the Business Center Subscription Payments User s Guide. Business Center Simple Order API User s Guide June

78 Processing Credits with the API Processing Credits with the API The chapter in this guide on processing electronic checks says to use the Business Center to perform electronic check credits. You can, however, perform credits through the API. In general, you would use the API if you want to request credits programmatically instead of through the Business Center. Whether you do this depends on the volume of orders you have and how you have structured your fulfillment system. When you process credits through the Business Center, you search for the original order, we retrieve the order information from our database, and then you click a button to perform the credit. Or, you can bypass searching for the original debit and just perform a plain credit. In this case you have to provide all of the customer s billing and account information, and any other information the processor requires. These two methods are called follow-on or stand-alone credits. You can process both types of credits through the API. Follow-On Credits This type of credit is called a follow-on credit because you provide the request ID from the debit so that we can locate the original debit information for you, and because you must request the credit within 60 days of when you requested the debit. In the request, include the eccreditservice_debitrequestid field with the value of the requestid that you received in the debit reply. We use this value to retrieve the order information from our database, reducing the amount of information you must supply in the credit request. Stand-Alone Credits With a stand-alone credit, you do not provide the request ID from the previous debit, and you have no limit on the timing of the credit. You must provide CyberSource the customer s name, billing address, and bank account information in the credit request (see Table 18 on page 71). For TeleCheck, you must also provide the request field eccreditservice_ referencenumber with the value that you received in the ecdebitreply_ reconciliationid reply field. TeleCheck uses this value to associate the credit with the associated debit. Reconciliation ID In the electronic check credit reply, you receive a reconciliation ID that is assigned by CyberSource. You use it to reconcile the transactions in your CyberSource reports with the transactions in your processor reports. For credits, this number appears in the eccreditreply_reconciliationid. 70 CyberSource Corporation

79 Appendix D Advanced API Capabilities for Electronic Checks Payment Events Report The Payment Events Report shows when your credit is processed. For more information about the Payment Events Report, see the Business Center Reporting User s Guide. Credit Request Fields Table 18 lists the fields you use to request an electronic check credit. Table 18 Credit Request Fields Field Name Description Required / Optional Data Type & Length billto_city For descriptions for all of the billto_ fields, see Table 3 on page 32. Required ** String (50) billto_country Required ** String (2) billto_customerid Your identifier for the customer. Optional String (50) billto_dateofbirth NOTE If you use AmeriNet, check with them to see if they require you to provide this field. Used by AmeriNet only ** String (10) billto_ Required ** String (255) billto_firstname Required ** String (60) billto_lastname Required ** String (60) billto_phonenumber Required ** String (15) billto_postalcode Required ** String (10) billto_state Required ** String (2) billto_street1 Required ** String (60) billto_street2 Optional ** String (60) check_accountnumber Checking account number. Required ** String with numbers only (17) check_accounttype Checking account type. This field can contain one of the following values: C: Checking S: Savings X: Corporate checking ** Field not needed if performing a follow-on credit (which requires eccreditservice_debitrequestid) Required ** String (1) Business Center Simple Order API User s Guide June

80 Processing Credits with the API Table 18 Credit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length check_banktransitnumber Bank routing number (also known as the transit number ). Required ** String with numbers only (9) check_checknumber Check number. Note If you use AmeriNet, check with them to see if they require you to provide this field. Used by AmeriNet only ** See field description String with numbers only (8) comments Optional comments you have about the credit. These comments will not be shown to the customer. Optional String (255) eccreditservice_ debitrequestid The requestid from the previous debit. Creates a follow-on credit by linking the credit to the previous debit. For a follow-on credit, you do not need to send the customer s name, the billing address, or the bank account information. Required only for a follow-on credit (see Follow-On Credits on page 70) String (26) eccreditservice_ referencenumber For stand-alone credits with TeleCheck, set this field to the value that you received in the ecdebitreply_reconciliationid field in the associated debit s reply. See Stand-Alone Credits on page 70 for more information. Required for CyberSource stand-alone credits with TeleCheck String (60) For TeleCheck, The maximum length is 25. eccreditservice_run item_#_productcode Set to true to include the credit service in your request. For descriptions of the item_#_ fields, see Table 3 on page 32. Required String (5) Optional String (30) item_#_productname Optional String (30) item_#_productsku Optional String (15) item_#_quantity Optional Integer (10) item_#_taxamount Optional String (15) item_#_unitprice Per-item price of the product. You must provide either this field or purchasetotals_ grandtotalamount in your request. See Using a Grand Total on page 12 for more information. See description String (15) ** Field not needed if performing a follow-on credit (which requires eccreditservice_debitrequestid) 72 CyberSource Corporation

81 Appendix D Advanced API Capabilities for Electronic Checks Table 18 Credit Request Fields (Continued) Field Name Description Required / Optional Data Type & Length merchantdefineddata_field1 merchantdefineddata_field2 merchantdefineddata_field3 merchantdefineddata_field4 merchantid merchantreferencecode purchasetotals_currency purchasetotals_ grandtotalamount recurringsubscriptioninfo_ subscriptionid Open field that you can use to store any information. NOTE If you are performing a follow-on credit and you provided these fields with the debit, you will see the debit s values in the Business Center and the Order Detail Report and not the values you provided with the credit. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. See the description for merchantdefineddata_field1 above. Your CyberSource merchant ID. You received this in the registration from CyberSource after you registered for a Business Center account. Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See Order Identifiers on page 15 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Grand total for the order. You must provide either this field or item_#_unitprice in your request. See Using a Grand Total on page 12 for more information. Subscription ID). If you are using the Subscription Payment Services, you can request a debit or credit and use a subscription ID to reference the subscription information. See Using a Subscription for a Debit or Credit on page 69. Optional String (64) Optional String (64) Optional String (64) Optional String (64) Required String (30) Required String (50) Required String (5) See description String (15) Optional String (26) ** Field not needed if performing a follow-on credit (which requires eccreditservice_debitrequestid) Business Center Simple Order API User s Guide June

82 Processing Credits with the API Credit Reply Fields Table 19 lists the electronic check credit reply fields. Table 19 Credit Reply Fields Field Name cccreditreply_ reasoncode decision Description Numeric value corresponding to the result of the credit request. See Reason Codes for Electronic Check Services on page 49 for a list of possible values. Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded ERROR: There was a system error REJECT: One or more of the services in the request was declined Data Type & Length Integer (5) String (6) eccreditreply_amount Total amount of the credit. String (15) eccreditreply_ processorresponse eccreditreply_ processortransactionid Result code returned by the payment processor. String (6) Transaction identifier or tracking ID returned by AmeriNet. String (87) eccreditreply_ reasoncode eccreditreply_ reconciliationid eccreditreply_ requestdatetime eccreditreply_ settlementmethod A numeric value corresponding to the result of the credit request. See Reason Codes for Electronic Check Services on page 49 for a list of possible values. Reference number that you use to reconcile your CyberSource reports with your processor reports. Time when credit is requested. The format is YYYY-MM- DDThh:mm:ssZ. For example, T22:47:57Z is equal to August 11, 2003, at 10:47:57 P.M. The T separates the date and the time, and the Z indicates UTC. Method used to settle the credit. This field will contain B to indicate best possible method (best of either ACH or facsimile). Integer (5) String (60) String (20) String (1) invalidfield_0...n Fields in the request that contained invalid data. String (100) merchantreferencecode Order reference or tracking number that you provided in the request. String (50) missingfield_0...n Required fields that were missing from the request. String (100) purchasetotals_currency Currency used for the order. For U.S. dollars, the value will be USD. String (5) reasoncode Numeric value corresponding to the result of the overall request. See Reason Codes for Electronic Check Services on page 49 for a list of possible values. Integer (5) 74 CyberSource Corporation

83 Appendix D Advanced API Capabilities for Electronic Checks Table 19 Credit Reply Fields (Continued) Field Name requestid Description Identifier for the request. Note that this request ID is different from the one you received for the debit request. Data Type & Length String (26) Reason Codes You have already seen the list of reason codes that CyberSource returns for electronic check debits (Table 10 on page 49). Note that one of the reason codes in that table is returned only for credits: Table 20 Additional Reason Code for Credits Reason Code Description 241 The request ID is invalid for the follow-on request. This reason code is returned for follow-on credits only. Possible action: Verify the request ID is valid and resend the request. Business Center Simple Order API User s Guide June

84 Reason Codes 76 CyberSource Corporation

85 Appendix E Using the XML API For merchants with more advanced programming skills and experience with XML, CyberSource offers an XML API to use instead of the Simple Order API. This appendix discusses how to get started and how to translate the Simple Order API information in this guide into the corresponding XML API information that you need. The appendix includes these sections: Downloading a Client About the XML API Correlating Fields Names Requesting Credit Card Authorization Numbering Items Example Request and Reply Downloading a Client If you plan to use the XML API, 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 here. About the XML API To use the API, you create an XML message that contains the information for calling the ICS services you want to use (in this case, credit card authorization). The client digitally Business Center Simple Order API User s Guide June

86 Correlating Fields Names signs and sends your request. You only need to create the request XML message and parse the XML reply message. See page 80 for an example XML request and reply. Constructing Requests The schema for the XML API is located at In general, the schema s structure is separated into a request message and a reply message. Inside the request message are elements for the basic invoice information, tender information, and then service-specific information. The element that contains the servicespecific information for a credit card authorization is <ccauthservice>. To indicate in the request that you want to run a service, set the run attribute for the service s element to "true". For example, to request credit card authorization, set the run attribute for the <ccauthservice> element to "true". You can send either live or test transactions. For live transactions, you send your request to where the XML schema is located. For test transactions, you send your requests to commerce/1.x/transactionprocessor. Parsing Replies The reply message includes general information for the entire request, and then information relevant to the results of each service you requested. For example, the reply information relevant to the credit card authorization is in the <ccauthreply> element. XML replies from CyberSource always contain the namespace prefix c:. You need to use an XML parser that supports namespaces. Correlating Fields Names The main chapters of this guide discuss using the Simple Order API, which uses namevalue pairs. The name-value pair field names correlate directly to element names in the XML API. The relationship between the XML element names and the Simple Order API field names is as follows: Each Simple Order API field name matches the corresponding XML element name. The Simple Order API indicates XML schema hierarchy with an underscore ( _ ) separating the name of the parent element from the name of the child element. 78 CyberSource Corporation

87 Appendix E Using the XML API For example, the XML schema has a <card> element with several child elements. Table 21 shows the <card> child element names in the XML schema, and the corresponding Simple Order API field names. Table 21 Example of Schema Names and Simple Order API Names Schema Names <card> <accountnumber> <expirationmonth> <expirationyear> </card> Corresponding Simple Order API Names card_accountnumber card_expirationmonth card_expirationyear The same convention is used for reply fields. Requesting Credit Card Authorization To indicate in the request that you want to run credit card authorization, set the run attribute for the <ccauthservice> element to "true". Numbering Items The XML schema includes an <item> element that you use to describe a single item that the customer is purchasing. If the customer s order contains more than one item, you number the items, starting with 0. The XML schema uses an id attribute in the item s opening tag to indicate the number. For example: <item id="0"> In the Simple Order API field names, this is represented as item_0. Note that in this situation, the underscore before the number does not indicate hierarchy in the XML schema. The item fields are generically referred to as item_#_<element name> in the documentation. Table 22 shows an example of the numbered <item> element and the corresponding Simple API field names. Table 22 Numbered Items Schema Names <item id="0"> <unitprice> <quantity> </item> Corresponding Simple Order API Names item_0_unitprice item_0_quantity Business Center Simple Order API User s Guide June

88 Example Request and Reply Table 22 Numbered Items Schema Names <item id="1"> <unitprice> <quantity> </item> Corresponding Simple Order API Names item_1_unitprice item_1_quantity Example Request and Reply Request: <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.19"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f5</merchantreferencecode> <billto> <firstname>john</firstname> <lastname>doe</lastname> <street1>1295 Charleston Rd.</street1> <city>mountain View</city> <state>ca</state> <postalcode>94043</postalcode> <country>us</country> <phonenumber> </phonenumber> </billto> <item id="0"> <unitprice>49.95</unitprice> <quantity>1</quantity> </item> <purchasetotals> <currency>usd</currency> </purchasetotals> <card> <accountnumber> </accountnumber> <expirationmonth>12</expirationmonth> <expirationyear>2015</expirationyear> </card> <ccauthservice run="true"/> </requestmessage> 80 CyberSource Corporation

89 Appendix E Using the XML API Reply For information about why each element in the reply contains c: at the beginning (for example, <c:requestid>), see the information about namespaces in Constructing Requests and Parsing Replies on page 78. <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.19"> <c:merchantreferencecode>482046c3a7e94f5</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>usd</c:currency> </c:purchasetotals> <c:ccauthreply> <c:reasoncode>100</c:reasoncode> <c:amount>49.95</c:amount> <c:authorizationcode>123456</c:authorizationcode> <c:avscode>y</c:avscode> <c:avscoderaw>yyy</c:avscoderaw> <c:authorizeddatetime> t23:44:27z</c:authorizeddatetime> <c:processorresponse>a</c:processorresponse> </c:ccauthreply> </c:replymessage> Business Center Simple Order API User s Guide June

90 Example Request and Reply 82 CyberSource Corporation

91 Index Symbols $0 authorization 6 A ACCEPT decision 13 American Express 4, 5 authorizations and subscriptions 51 described 2 for $0 6 reply fields 26 request fields 21 requesting 16 AVS and recurring payments 53 API for 17 codes 43 described 4 B bill payment 52, 59 C capture with verbal auth 52 captures described 2 in Business Center 19 reply fields 58 request fields 56 through API 55 card verification number API for 18 described 5 changes to document vii check authorization consent 29 checks. See electronic checks clients 9 Concord EFS 4 consent statement 29 coupons 31, 54 credits and subscriptions 59 in Business Center 19 through API 59 D decisions 13 declines 6 Diners Club 3, 4 Discover 4, 5 E electronic checks 29 and subscriptions 69 corporate checks 30 credits through API 70 example request and reply 39 payments 29 refunds in Business Center 31 ERROR decision 13 errors, described 13 examples replies 14 request 12 Business Center Simple Order API User s Guide June

92 F U F FDMS Nashville 4, 5, 53 FDMS South 4, 5, 6, 53, 54 forced capture 52 fraud 4 freight charges 11 G going live 21 grand total amount 12 H Hosted Order Page 1 I invalid fields 14 items described 11 numbering in XML API 79 J JCB J/Secure 65 M MasterCard 3, 4, 5 MasterCard SecureCode 65 missing fields 14 N numbered items in XML API 79 O order identifiers 15 order number 15 P payer authentication 65 Payment Events Report 31 Paymentech 4, 5, 53, 54 product codes 41 R reason codes 49 described 14 reconciliation ID 15 reconciling orders 20 recurring payments 53 refunds in Business Center 19 through API 59 REJECT decision 13 replies described 10 example 14 request ID 15 requests described 10 example 12 returned check fees table 29 S sale, processing through the API 16 shipping and handling 11 Smart Authorization API for 18 described 5 result codes 45 settings 4 special characters in fields 11 SSL 1, 9 state returned check fees table 29 subscription ID credit cards 51, 59, 62 electronic checks 69, 73 syntax of fields 11 T tax 11 testing 20 U USA PATRIOT Act compliance 6 84 CyberSource Corporation

93 Index V verbal authorization 55 Verified by Visa 65 Virtual Terminal 1 Visa 4, 43, 52, 59, 65 Vital 4, 5, 6, 53 voids 63 W Web Services API 10 X XML API 1, 77 Z zero-dollar authorization 6 Business Center Simple Order API User s Guide June

94 Z Z 86 CyberSource Corporation