User s Guide Simple Order API Version 1.14 May 2005

Transcription

1 CyberSource Business Center Simple Order API User s Guide Simple Order API Version 1.14 May 2005

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 2005 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 and Enhancements...vii Chapter 1 Introduction...1 Welcome!...1 About the Business Center...1 Where You Can Get More Information...2 About Processing Credit Cards...2 MasterCard and Diners Club Alliance...3 Reducing Your Chances of Fraud...4 Address Verification Service...4 Card Verification Number...4 Smart Authorization...5 $0 Authorization...6 Chapter 2 Processing Orders with the API...9 Downloading a Client...9 Using the Latest API Version...9 Understanding API Requests and Replies...10 A Few Details about Requests...10 Using Items...10 Using a Grand Total, Total Tax, or Total Freight Amount...11 A Few Details about Replies...13 Decisions...13 Reason Codes...13 Example Replies...14 Processing a Credit Card Order...15 Requesting the Authorization...15 Using the Address Verification Service...15 Using the Card Verification Number...15 Using Smart Authorization...16 Performing a Forced Capture...16 Indicating a Bill Payment...17 API Fields...17 Authorization Request Fields...17 Business Center Simple Order API User s Guide May 2005 iii

4 Authorization Reply Fields...23 Testing Your Implementation...25 Capturing the Order...26 Refunding the Customer s Money...27 Going Live...27 Chapter 3 Additional Useful Information...29 Order Identifiers...29 Reconciling Your Orders...29 Missing and Invalid Request Fields...29 Chapter 4 Processing Orders with Electronic Checks...31 Preparing to Accept Electronic Checks...31 Processing Electronic Check Payments...32 Corporate Checks...32 Reconciliation ID...32 Electronic Check Debit Fields...33 Request Fields...33 Reply Fields...39 Seeing When the Check Has Cleared...41 Refunding the Customer s Money...41 Testing Your Implementation...41 Example Request and Reply...43 Appendix A Product Codes...45 Appendix B Reason Codes...47 Reason Codes for Credit Card Services...47 Reason Codes for Electronic Check Services...50 Appendix C Codes for Fraud Tests...53 Address Verification Service Codes...53 Card Verification Codes...54 Smart Authorization Codes...55 Appendix D Advanced API Capabilities for Credit Cards...57 Why Use the API for Captures and Credits?...57 Requesting a Capture...57 Processing a Verbal Authorization...57 Capture Request Fields...58 Capture Reply Fields...60 iv CyberSource Corporation

5 Contents Requesting a Credit...61 Indicating a Bill Payment...62 Credit Request Fields...62 Credit Reply Fields...65 Processing a Sale with the API...66 Using Payer Authentication...67 Appendix E Advanced API Capabilities for Electronic Checks...71 Why Use the API for Credits?...71 Requesting a Credit...71 Follow-On Credits...71 Stand-Alone Credits...72 Reconciliation ID...72 Payment Events Report...72 Credit Request Fields...72 Credit Reply Fields...76 Reason Codes...77 Appendix F Level III with Vital...79 About Level III Processing with CyberSource...79 Prerequisites...79 Processor Specification Used...80 Indicating the Request Is for Level III...80 Level II Fields Needed for Level III...81 Field to Send with the Authorization...81 About Using Decimals and Strings...82 Level III Fields...82 Order-Level Fields...83 Item-Level Fields...87 Example Requests...91 Appendix G Using the XML API...95 Downloading a Client...95 About the XML API...95 Constructing Requests...95 Parsing Replies...96 Correlating Fields Names...97 Requesting Credit Card Authorization...97 Numbering Items...97 Example Authorization Request...99 Example Authorization Reply Appendix H Using the Testing Simulator Business Center Simple Order API User s Guide May 2005 v

6 General Testing Information FDMS Nashville Testing Information FDMS Nashville General Error Triggers FDMS Nashville AVS Triggers FDMS Nashville CVV Triggers FDMS South Testing Information FDMS South Error Triggers FDMS South Visa AVS Triggers FDMS South MasterCard AVS Triggers FDMS South American Express AVS Triggers FDMS South Discover AVS Triggers FDMS South CVV Triggers Paymentech Testing Information Paymentech Error Triggers Paymentech AVS Triggers Paymentech CVV Triggers Vital Testing Information Vital Error Triggers Vital AVS Triggers Vital CVV Triggers Index vi CyberSource Corporation

7 Documentation Changes and Enhancements The following changes were made to this guide since its last publication: Added information about performing forced captures. See Performing a Forced Capture on page 16. Added information about using the bill payment indicator for Visa. See Indicating a Bill Payment on page 17. Added information about the Payment Events Report. See Seeing When the Check Has Cleared on page 41. Clarified how to perform credits through the API, and added information about stand-alone credits with TeleCheck. See Requesting a Credit on page 71. Added information about performing a $0 authorization with FDMS South. See $0 Authorization on page 6. Added information about using CyberSource s test simulator. See Appendix H, Using the Testing Simulator, on page 101. Business Center Simple Order API User s Guide May 2005 vii

8 viii CyberSource Corporation

9 Chapter 1 Introduction Welcome! This document is for users of the Business Center, and it covers processing credit card orders with CyberSource s Simple Order API. You might want to use the API (as opposed to CyberSource s Virtual Terminal or Hosted Order Page) if you want more flexibility and control over the customer s buying experience at your Web store. You might want to use the API also if 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, or.net If you are a developer with XML experience and you want to use CyberSource s XML API instead of the Simple Order API, start here, but also see Appendix G, Using the XML API, on page 95. 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 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. Business Center Simple Order API User s Guide May

10 Where You Can Get More Information 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. Where You Can Get More Information You can get more information about processing orders with CyberSource in these guides: Introduction to Processing Orders, available on the Business Center. We recommend that you read this particular guide and understand how order processing works before you start implementing the CyberSource API. The Business Center User s Guide, also available on the Business Center. This guide shows you how to perform the various functions available in the Business Center. About Processing Credit Cards You have probably already learned something about credit card processing from reading Introduction to Processing Orders. 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 D, Advanced API Capabilities for Credit Cards, on page 57 for more information. 2 CyberSource Corporation

11 Chapter 1 Introduction 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: 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. Business Center Simple Order API User s Guide May

12 Reducing Your Chances of Fraud 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 who your payment processor is and what type of credit card 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.) 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. 4 CyberSource Corporation

13 Chapter 1 Introduction 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) 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. Business Center Simple Order API User s Guide May

14 Reducing Your Chances of Fraud 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 Business Center Simple Order API User s Guide May

16 Reducing Your Chances of Fraud 8 CyberSource Corporation

17 Chapter 2 Processing Orders with the API This chapter describes how to process a credit card order by using the CyberSource Simple Order API. For information about processing electronic check orders, see Chapter 4, Processing Orders with Electronic Checks, on page 31. 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 Introduction to Processing Orders for more information about how to use them. Downloading a Client To use the API to process orders, the first thing you need to do is pick one of our clients: Java.NET ASP PHP Perl You can download your chosen client and its related documentation from the Developer Center. Using the Latest API Version CyberSource updates the Simple Order API on a regular basis to introduce new API fields and functionality and assigns a new version number each time it is updated. The latest API version at the time of this guide s publication is This represents the version of the server-side code for the ICS services. Business Center Simple Order API User s Guide May

18 Understanding API Requests and Replies 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. When configuring the CyberSource client SDK, you indicate which version of the API you want to use. CyberSource suggests you use the latest version of the API. To determine the latest version, go to To see what has changed from version to version of the API, see the Simple Order API Release Notes. Note 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. A Few Details about 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 1. 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, and others. CyberSource uses the information you provide for each item to calculate the total amount for the order, the total tax amount for the order (if you provide tax information), and the freight amount for the order (if you provide freight information). 10 CyberSource Corporation

19 Chapter 2 Processing Orders with the API 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. Using a Grand Total, Total Tax, or Total Freight Amount Alternately, you may send a grand total amount, a total tax amount, or a total freight amount for the order using these fields: purchasetotals_grandtotalamount purchasetotals_taxamount purchasetotals_freightamount You may send these fields instead of or in addition to the item information discussed above. If you send these fields, CyberSource does not use the item information to calculate the grand total, total tax, or freight amount for the order. Instead, we use the values you give in the above fields. Note that the item information (if you provide it) still appears in the Transaction Detail page for the order in the Business Center. Important If you provide either purchasetotals_taxamount or purchasetotals_ freightamount, then you must also provide purchasetotals_grandtotalamount in your request. But, if you provide purchasetotals_grandtotalamount, you are not required to provide purchasetotals_taxamount or purchasetotals_freightamount. The following sections further explain how to use items and order totals. Grand Total Amount To specify the grand total for the order, you can do either of these: Use the item_#_unitprice field to specify the unit price for each item. CyberSource uses these values for the items to calculate the grand total for the order. Use the purchasetotals_grandtotalamount field. CyberSource uses this value as the grand total for the order. Total Tax Amount To specify the total tax amount for the order, you can do either of these: Use the item_#_taxamount field to specify the total tax amount for each item ordered (not the per-item tax amount). CyberSource uses these values for the items to calculate the total tax for the order, and thus the grand total amount for the order. Use this method if you do not plan to use the purchasetotals_grandtotalamount field in the request, but you want to specify tax amounts for the items in the order. Business Center Simple Order API User s Guide May

20 Understanding API Requests and Replies Use the purchasetotals_taxamount field. CyberSource uses this value as the total tax amount for the order. Use this method if you plan to use the purchasetotals_ grandtotalamount field in the request. Freight Amount To specify the freight amount, you can do either of these: Add an additional item to the order specifically to send the freight information for the order. You set item_#_unitprice to the freight amount and item_#_productcode to shipping_only, handling_only, or shipping_and_handling (see the list of product codes in Product Codes on page 45). Use this method if you do not plan to use the purchasetotals_grandtotalamount in your request but you want to specify a freight amount for the order. Set the purchasetotals_freightamount field to the total shipping and handling amount for the order. Use this method if you plan to use the purchasetotals_ grandtotalamount field in the request. See the example below for what a basic request for credit card authorization looks like. Note that it uses name-value pairs. In this example, John Doe is buying one item that costs $ ccauthservice_run=true merchantid=infodev merchantreferencecode=482046c3a7e94f5 billto_firstname=john billto_lastname=doe billto_street1=1295 Charleston Rd. billto_city=mountain View billto_state=ca billto_postalcode=94043 billto_country=us billto_phonenumber= billto_ =jdoe@example.com item_0_unitprice=49.95 item_0_quantity=1 purchasetotals_currency=usd card_expirationmonth=12 card_expirationyear=2015 card_accountnumber= CyberSource Corporation

21 Chapter 2 Processing Orders with the API 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 Authorization Request Fields on page 17. A Few Details about Replies The reply you get 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. 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. Business Center Simple Order API User s Guide May

22 Understanding API Requests and Replies 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 Appendix B, Reason Codes, on page 47. 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. 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 24. requestid= merchantreferencecode=482046c3a7e94f5 decision=accept ccauthreply_ ccauthreply_amount=49.95 ccauthreply_authorizationcode= ccauthreply_avscode=y ccauthreply_avscoderaw=yyy 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= CyberSource Corporation

23 Chapter 2 Processing Orders with the API Processing a Credit Card Order The only part of processing the order that you do through the API is the authorization. You do the capture and a refund (if necessary) in the Business Center (see page 26). Requesting the 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 17. These next few sections describe how to use the API fields related to the fraud screening tests described in Chapter 1, Reducing Your Chances of Fraud, on page 4. Note If your order 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. Using the 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. You can get details about the AVS result in the ccauthreply_avscode reply field. See Appendix C, Address Verification Service Codes, on page 53 for descriptions of the codes that you can receive in this field. Using the 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 4 for more information. Use the card_cvnumber field in the request to send the customer s card verification number. Business Center Simple Order API User s Guide May

24 Processing a Credit Card Order 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 C, Card Verification Codes, on page 54 for descriptions of the codes that you can receive in this field. Using 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 C, Smart Authorization Codes, on page 55 for descriptions of the codes you can receive in this field. 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 this chapter. 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. 16 CyberSource Corporation

25 Chapter 2 Processing Orders with the API 2 When ready, request the capture just like you would a normal capture (see Requesting a Capture on page 57). 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 Bill Payment You can indicate in the authorization request that the transaction is a bill that the customer is paying with a Visa card. Visa requests that you identify bill payments so that Visa can separate them from normal credit card purchases. Use the ccauthservice_billpayment field to do this. Although CyberSource accepts the ccauthservice_billpayment field no matter which processor you are using, currently CyberSource forwards the information only to Vital. API Fields Authorization Request Fields Table 1 lists the fields you use to request credit card authorization. If you are using Payer Authentication, see Using Payer Authentication on page 67 for additional authorization request fields that you must use. Table 1 Authorization Request Fields Field Name Description Required / Optional Datatype and Max Length billto_city City of the billing address. Required String (50) billto_country billto_ billto_firstname billto_lastname Country of the billing address. Use the two-character ISO codes (see the Support Center for a list of codes). Customer s address, including the full domain name (for example, jdoe@example.com). Customer s first name.the value should be the same as the one that appears on the card. Customer s last name. The value should be the same as the one that appears on the card. Required String (2) 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 May

26 Processing a Credit Card Order Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max 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 (see the Support Center for a list of 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) 18 CyberSource Corporation

27 Chapter 2 Processing Orders with the API Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max Length 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) 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 Using the Card Verification Number on page 15 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) Business Center Simple Order API User s Guide May

28 Processing a Credit Card Order Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max Length card_expirationmonth Two-digit month (MM - 01 through 12, inclusive) that the credit card expires in. The leading 0 is required. Required Integer (2) card_expirationyear Four-digit year (YYYY) that the credit card expires in. Required Integer (4) ccauthservice_authtype Set this field to verbal to indicate that you are performing a forced capture (that you received the authorization code outside the CyberSource system). See Performing a Forced Capture on page 16. Required for a forced capture. String (6) ccauthservice_ billpayment ccauthservice_ commerceindicator ccauthservice_run Indicates to Visa if the transaction is a bill that the customer is paying with a Visa card. Currently supported only for Vital. Use one of the following values: N (default): Not a bill payment Y: Bill payment See Indicating a Bill Payment on page 17. Transaction channel type. This field can contain one of the following values: internet (default): ecommerce transaction. moto: Mail order or telephone order. recurring: Recurring mail order or telephone order transaction. Set to true to include the credit card authorization service in your request. Optional String (1) Optional String (13) Required String (5) ccauthservice_ verbalauthcode The authorization code you received from an authorization that you performed outside the CyberSource system. See Performing a Forced Capture on page 16. Required for a forced capture String (6) 20 CyberSource Corporation

29 Chapter 2 Processing Orders with the API Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max Length item_#_productcode 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 45 for a list of valid values. Optional String (30) item_#_productname Name of the product. Optional String (30) item_#_productsku Product s identifier code. Optional String (15) item_#_quantity item_#_taxamount item_#_unitprice 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. Per-item price of the product. You must provide either this field or purchasetotals_grandtotalamount in your request. See Using a Grand Total, Total Tax, or Total Freight Amount on page 11 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. See description Integer (10) Optional String (15) See description String (15) Business Center Simple Order API User s Guide May

30 Processing a Credit Card Order Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max Length merchantid merchantreferencecode purchasetotals_currency purchasetotals_ freightamount purchasetotals_ grandtotalamount purchasetotals_taxamount 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 29 for more information. Currency used for the order. All orders must use U.S. dollars. Use USD for this field. Total freight amount for the order. If you include this field, purchasetotals_grandtotalamount is required. See Using a Grand Total, Total Tax, or Total Freight Amount on page 11 for more information. Grand total for the order. You must provide either this field or item_#_ unitprice in your request. See Using a Grand Total, Total Tax, or Total Freight Amount on page 11 for more information. If Vital is your processor, you may set this field to 0 to check if the card is lost or stolen. Total tax for the order. If you include this field, purchasetotals_ grandtotalamount is required. See Using a Grand Total, Total Tax, or Total Freight Amount on page 11 for more information. Required String (30) Required String (50) Required String (5) Optional String (15) See description String (15) Optional String (15) shipto_city City to which to ship the product. Optional (Required if providing any shipping information) String (50) 22 CyberSource Corporation

31 Chapter 2 Processing Orders with the API Table 1 Authorization Request Fields (Continued) Field Name Description Required / Optional Datatype and Max Length shipto_country shipto_ shipto_firstname shipto_lastname shipto_phonenumber Country to which to ship the product. Use the two-character ISO codes (see the Support Center for a list of codes). address of the person receiving the shipment (for example, jdoe@example.com). 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 (see the Support Center for a list of 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) Authorization Reply Fields Table 2 lists the credit card authorization reply fields. Business Center Simple Order API User s Guide May

32 Processing a Credit Card Order Table 2 Authorization Reply Fields Field Name Description Datatype and Max Length ccauthreply_amount Total amount of the authorization. String (15) ccauthreply_ authfactorcode ccauthreply_ authorizationcode ccauthreply_ authorizeddatetime ccauthreply_avscode ccauthreply_ avscoderaw ccauthreply_cvcode ccauthreply_ cvcoderaw ccauthreply_ processorresponse ccauthreply_ reasoncode ccauthreply_ reconciliationid Risk factor code from Smart Authorization. This field will contain one or more of the codes, separated by carets (^). See Smart Authorization Codes on page 55 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 53 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 Codes on page 54 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 on page 47 for a list of possible values. Reference number for the transaction. Returned for Paymentech only. String (100) String (6) String (20) String (1) String (10) String (1) String (10) String (10) Integer (5) String (60) 24 CyberSource Corporation

33 Chapter 2 Processing Orders with the API Table 2 Authorization Reply Fields (Continued) Field Name decision 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 Datatype and Max 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) purchasetotals_ currency reasoncode Currency used for the order. For U.S. dollars, the value will be USD. Numeric value corresponding to the result of the overall request. See Reason Codes on page 47 for a list of possible values. String (5) Integer (5) requestid Identifier for the request. String (26) Testing Your Implementation To make sure that your requests are completed correctly, you need to test the basic success and error conditions for each ICS service you plan to use. When testing, follow these rules: Use your regular CyberSource merchant ID to perform testing. Use a non-existent account and domain name for the customer s address (for example, random@example.com). Make sure your client is configured to send requests to the test server ( ics2wstest.ic3.com/commerce/1.x/transactionprocessor). See the documentation for your client for information about how to do this. Business Center Simple Order API User s Guide May