Cybersource

CyberSource Business Center Simple Order API
Users Guide Simple Order API

June 2006
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 https://businesscenter.cybersource.com. For general information about our company, products, and services, go to http://www.cybersource.com. For sales questions about any CyberSource Service, email sales@cybersource.com or call 650965-6000 or 888-330-2300 (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 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations 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
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 Users Guide June 2006
iii
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 Customers 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 Customers 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
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
vi
Documentation Changes
The following table lists changes made in the last six releases of this document:
Release
May 2996
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 Customers 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 Customers 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.

February 2006
November 2005
vii
Release
October 2005
Changes
Updated the Simple Order API version to 1.17. 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_email billTo_street1 billTo_city billTo_state billTo_postalCode billTo_country

August 2005
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. Updated the Simple Order API version to 1.16. Added information about processing retail point of sale transactions. See the Retail Supplement. Updated the Simple Order API version to 1.15. 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.
July 2005
viii
Chapter 1
Introduction
This document is for users of the Business Center, and it covers processing credit card orders with CyberSources Simple Order API. You may want to use the API instead of CyberSources Virtual Terminal or Hosted Order Page for many reasons such as these:
You want more flexibility and control over the customers 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 CyberSources 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
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 Users Guide. You will use the API to call CyberSources 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 customers 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 Users 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:
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 14digit 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 2005. 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:
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.

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 Users 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.
Figure 1 Example of a Visa Card Verification Number
1234567890123456 789
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 Users 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. 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.
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 Chapter 2 Chapter 3 Introduction Processing Credit Card Orders Processing Electronic Check Orders Gives information about supported credit card types, payment processors, and features for preventing fraud. 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.
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 Appendix B Product Codes Description of Return Codes Describes the values you can use for an items product code. Describes the Address Verification Service (AVS) codes, Card Verification (CVN) codes, Smart Authorization factor codes, and Simple Order API reason codes you can receive. 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. Describes how to use the XML variation of the Simple Order API.
Appendix C
Advanced API Capabilities for Credit Cards
Appendix D Appendix E
Advanced API Capabilities for Electronic Checks Using the XML API
Additional Resources
Business Center Users 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 Users Guide This guide describes the many reports available in the Business Center. Business Center Subscription Payments Users Guide If you decide to use CyberSources subscriptions payments services, you should read this guide to learn how to create and manage subscriptions. Business Center PayPal Users Guide If you decide to use CyberSources PayPal services, you should read this guide to learn how to process PayPal payments.
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 Users Guide or the Business Center Users 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.
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 https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/. 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 2 3 4 You collect information about the order (the items being bought, the customers name and address, the credit card information, and so on). You send us a request with the information and ask us to perform the credit card authorization service. We process your request and send you a response. 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 1.
10
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 customers 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) + 4.00 = 54.00.
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
11
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.00 + (4.95 * 1) = 58.95.
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 transactions 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 $49.95.
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=650-965-6000 billTo_email=jdoe@example.com item_0_unitPrice=49.95 item_0_quantity=1 purchaseTotals_currency=USD card_expirationMonth=12
12
card_expirationYear=2015 card_accountNumber=4111111111111111
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 customers 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.
13
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=0305782650000167905080 merchantReferenceCode=482046C3A7E94F5 decision=ACCEPT reasonCode=100 ccAuthReply_reasonCode=100 ccAuthReply_amount=49.95 ccAuthReply_authorizationCode=123456 ccAuthReply_avsCode=Y ccAuthReply_avsCodeRaw=YYY
14
ccAuthReply_authorizedDateTime=2004-02-28T23: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=0305782650000167905080 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)
15
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 customers 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=650-965-6000 billTo_email=jdoe@example.com item_0_unitPrice=49.95 item_0_quantity=1 purchaseTotals_currency=USD card_expirationMonth=12 card_expirationYear=2015
16
card_accountNumber=4111111111111111
This is an example sale reply where both services are successful:

requestID=0305782490000167905080 merchantReferenceCode=482046C3A7E94F5 decision=ACCEPT reasonCode=100 ccAuthReply_reasonCode=100 ccAuthReply_amount=49.95 ccAuthReply_authorizationCode=123456 ccAuthReply_avsCode=Y ccAuthReply_avsCodeRaw=YYY ccAuthReply_authorizedDateTime=2004-02-28T23:44:27Z ccAuthReply_processorResponse=A ccCaptureReply_reasonCode=100 ccCaptureReply_amount=49.95 ccCaptureReply_requestDateTime=2004-02-28T23:44:27Z ccCaptureReply_reconciliationID=39208984930 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 customers 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 Users 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.
17
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 customers 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 Users 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
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 2 After you have shipped the order, log into the Business Center. Search for authorizations that have not been captured. Your order will look similar to this:
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 Customers Money

If you need to refund the customers money, we suggest that you use the Business Center. See the Business Center Users Guide for information about crediting the customers 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 businesss 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.
19
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 Users 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 customers email address (for example, random@example.com). Make sure your client is configured to send requests to the test server (https:// 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 Visa MasterCard American Express Discover JCB Diners Club Test Account Number 4111 1111 1111 1111 5555 5555 5555 4444 3782 8224 6310 005 6011 1111 1111 1117 3566 1111 1111 1113 3800 000000 0006
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
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 Users 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 billTo_city billTo_country billTo_customerID billTo_email
Description City of the billing address. Country of the billing address. Use the twocharacter ISO codes. Your identifier for the customer. Customers email address, including the full domain name (for example, jdoe@example.com). Customers first name.The value should be the same as the one that appears on the card. Customers last name. The value should be the same as the one that appears on the card. Customers phone number.
Required / Optional Required Required Optional Required
Data Type & Length String (50) String (2) String (50) String (255)
billTo_firstName
Required
String (60)
billTo_lastName
Required
String (60)
billTo_phoneNumber
Optional
String (15)
21
Table 1 Authorization Request Fields (Continued)
Field Name billTo_postalCode
Description 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].
Required / Optional Required for U.S. or Canada
Data Type & Length String (10)
If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric]. Required for U.S. and Canada Required Optional String (2) String (60) String (60)
billTo_state billTo_street1 billTo_street2
State or province of the billing address. Use the two-character codes. First line of the billing street address. Second line of the billing street address. Used for additional address information, for example: Attention: Accounts Payable
card_accountNumber
Customers credit card number.
Required
String with numbers only (20) String (3)
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
Optional (see description)
002: MasterCard 003: American Express 004: Discover 005: Diners Club 007: JCB (required)
22
Field Name card_cvIndicator
Description Card verification indicator used to indicate if a card verification value was sent. Accepted by FDMS Nashville and FDMS South. The field can contain one of the following values: 0: CV number service not requested.
Required / Optional Optional
Data Type & Length String with numbers only (1)
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. 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. Transaction channel type. This field can contain one of the following values: internet (default): eCommerce transaction. Optional String with numbers only (4)
card_expirationMonth
Required
String (2)
card_expirationYear ccAuthService_ commerceIndicator
Required Optional
String (4) String (13)
moto: Mail order or telephone order.
See Indicating a Recurring Payment on page 53 for information about recurring payments. ccAuthService_run comments 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 Optional String (5) String (255)
23
Field Name item_#_productCode
Description 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.
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. Products 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.
See description
String (30)
item_#_productSKU
See description
String (15)
item_#_quantity
See description
Integer (10)
item_#_taxAmount
Optional
String (15)
24
Field Name item_#_unitPrice
Description 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 100.00 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.
Required / Optional See description
merchantDefinedData_ field1
Open field that you can use to store any information. The value appears in the transactions details in the Business Center and in the Order Detail Report. NOTE Do not use the field to store any sensitive customer information.
Optional
String (64)
merchantDefinedData_ field2 merchantDefinedData_ field3 merchantDefinedData_ field4 merchantID
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 email 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.
Optional Optional Optional Required
String (64) String (64) String (64) String (30)
merchantReferenceCode
Required
String (50)
purchaseTotals_currency purchaseTotals_ grandTotalAmount
Required See description
25
Field Name shipTo_city
Description City to which to ship the product.
Required / Optional Optional (Required if providing any shipping information) Optional Optional
shipTo_country shipTo_email
Country to which to ship the product. Use the two-character ISO codes. Email 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. Postal code to which to ship the product.
shipTo_firstName shipTo_lastName shipTo_phoneNumber shipTo_postalCode
Optional Optional Optional Optional (Required if address is in U.S. and Canada) Optional (Required if address is in U.S. and Canada) Optional (Required if providing any shipping information) Optional
shipTo_state
State or province to which to ship the product. Use the two-character codes. First line of the address to which to ship the product.
String (2)
shipTo_street1
String (60)
shipTo_street2
Second line of the address to which to ship the product.
String (60)
Reply Fields
Table 2 lists the credit card authorization reply fields.
Table 2 Authorization Reply Fields
Field Name ccAuthReply_amount
Description Total amount of the authorization.
26
Table 2 Authorization Reply Fields (Continued)
Field Name ccAuthReply_ authFactorCode ccAuthReply_ authorizationCode
Description 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.
String (6)
ccAuthReply_ authorizedDateTime
Time of authorization. The format is YYYY-MM-DDThh:mm:ssZ. For example, 2003-08-11T22: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.
String (20)
ccAuthReply_avsCode ccAuthReply_ avsCodeRaw
ccAuthReply_cvCode
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.
String (1)
ccAuthReply_ cvCodeRaw
String (10)
ccAuthReply_ processorResponse ccAuthReply_ reasonCode ccAuthReply_ reconciliationID decision
Processors 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
String (10)
Integer (5)

invalidField_0...N
ERROR: There was a system error REJECT: One or more of the services in the request was declined String (100)
Fields in the request that contained invalid data.
27
Table 2 Authorization Reply Fields (Continued)
Field Name merchantReferenceCode missingField_0...N purchaseTotals_currency reasonCode
Description Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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 for the Simple Order API on page 46 for a list of possible values. Identifier for the request.
Data Type & Length String (50) String (100) String (5) Integer (5)
requestID
String (26)
28
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 Users 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 Customers 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 (http:// www.achex.com/html/NSF_pop.jsp). 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. 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 states returned item fee.
29
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
PAY TO THE ORDER OF
0123
01-2345/6789
$
DOLLARS
BANK NAME ADDRESS CITY, STATE ZIP

FOR
Bank Routing Number
Bank Account Number
Check 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 customers date of birth, and TeleCheck requires the customers drivers 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 1970-01-01.
Reconciliation ID
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
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 Users Guide.
Refunding the Customers Money

If you need to refund the customers money, we suggest you use the Business Center. See the Business Center Users Guide for information about how to credit the customers bank account. If your businesss 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: https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/ Production: https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/
31
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).

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 billTo_city billTo_company
Description City of the billing address. Name of the customers 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. Companys 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. Country of the billing address. Use the twocharacter ISO codes. Your identifier for the customer.
Required / Optional Required See field description
Data Type & Length String (50) String (40)
billTo_companyTaxID
See field description
String with numbers only (9)
billTo_country billTo_customerID
Required Optional
32
Table 3 Electronic Check Debit Request Fields (Continued)
Field Name billTo_dateOfBirth
Description Customers date of birth. Use format YYYY-MMDD or YYYYMMDD. NOTE If using AmeriNet, check with them to see if they require you to provide this field. For AmeriNet corporate checks, use the value 1970-01-01.
Required / Optional Optional (For AmeriNet, see field description)
billTo_ driversLicenseNumber
Customers drivers license number. 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.
String (30)
billTo_ driversLicenseState
State or province where the customers drivers license was issued. Used only for TeleCheck. Use the two-character codes. 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.
String (2)
billTo_email
Customers email address, including the full domain name (for example, jdoe@example.com). Customers first name. If the first name is unavailable or inapplicable (for example, for a corporate account), enter a dummy value such as NA. Customers IP address (for example, 10.1.27.63). Customers last name. If the transaction is for a corporate account, use the company name. Customers phone number.
Required
String (255)
billTo_firstName
Required
String (60)
billTo_ipAddress billTo_lastName billTo_phoneNumber
Optional Required Required
String (15) String (60) String (15)
33
Field Name billTo_postalCode
Description 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].
Required / Optional Required
If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric]. Required Required Optional String (2) String (60) String (60)
billTo_state billTo_street1 billTo_street2
State or province of the billing address. Use the two-character codes. First line of the billing street address. Second line of the billing street address. Used for additional address information, for example: Attention: Accounts Payable
check_accountNumber
Customers checking account number.
Required
String with numbers only (17) String (1)
check_accountType
Checking account type. This field can contain one of the following values: C: Checking
Required

check_bankTransitNumber
S: Savings X: Corporate checking

Required String with numbers only (9) String with numbers only (8) String (255)
Bank routing number (also known as the transit number). Check number. NOTE If using AmeriNet, check with them to see if they require you to provide this field.
check_checkNumber
Optional (for AmeriNet, see field description) Optional
comments
Optional comments you have about the debit. These comments will not be shown to the customer.
34
Field Name ecDebitService_ referenceNumber
Description 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. Not used for AmeriNet.
Required / Optional See field description
ecDebitService_run
Whether to include ecDebitService in your request. The field can contain one of the following values: true: Include the service in your request.
Required
String (5)
item_#_productCode
false (default): Do not include the service in

your request. Optional String (30)
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.
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. Products 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.
See description
String (30)
item_#_productSKU
See description
String (15)
item_#_quantity
See description
Integer (10)
35
Field Name item_#_taxAmount
Description 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.
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. You can use a decimal if you want. For example, you can use either 100.00 or 100 to represent one hundred dollars. Do not include any special characters, such as a dollar sign ($).
See description
String (15)
Open field that you can use to store any information. The value appears in the transactions details in the Business Center and in the Order Detail Report. NOTE Do not use the field to store any sensitive customer information.
Optional
String (64)
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 email 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.
Required
String (50)
purchaseTotals_currency
Required
String (5)
36
Field Name purchaseTotals_ grandTotalAmount
Description 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. City to which to ship the product.
Required / Optional See field description
shipTo_city
Optional (Required if providing any shipping information) Optional Optional Optional Optional Optional Optional (Required if address is in U.S. and Canada) Optional (Required if address is in U.S. and Canada) Optional (Required if providing any shipping information) Optional
String (50)
shipTo_country shipTo_email shipTo_firstName shipTo_lastName shipTo_phoneNumber shipTo_postalCode
Country to which to ship the product. Use the twocharacter ISO codes. Email 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. Postal code to which to ship the product.
String (2) String (255) String (60) String (60) String (15) String (10)
shipTo_state
State or province to which to ship the product. Use the two-character codes.
String (2)
shipTo_street1
First line of the address to which to ship the product.
String (60)
shipTo_street2
Second line of the address to which to ship the product.
String (60)
37
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:

ecDebitReply_amount ecDebitReply_ processorTransactionID ecDebitReply_reasonCode
ACCEPT ERROR REJECT

String (15) String (87) Integer (5)
Total amount submitted to the payment processor. Transaction identifier or tracking ID returned by AmeriNet. 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-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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. Result code returned by the payment processor. 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. Fields in the request that contained invalid data. Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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 75 for a list of possible values. Identifier for the request.
ecDebitReply_ reconciliationID ecDebitReply_ requestDateTime
ecDebitReply_ processorResponse ecDebitReply_ settlementMethod ecDebitReply_ verificationLevel invalidField_0...N merchantReferenceCode missingField_0...N purchaseTotals_currency reasonCode requestID
String (6) String (1) Integer (1) String (100) String (50) String (100) String (5) Integer (5) String (26)
38
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=650-965-6000 billTo_email=jdoe@example.com billTo_dateOfBirth=19680923 item_0_unitPrice=100.00 purchaseTotals_currency=USD check_accountNumber=4100 check_accountType=C
check_bankTransitNumber=071923284
Example Electronic Check Debit Reply

requestID=9980055975450167905139
merchantReferenceCode=482046C3A7E94F7
decision=ACCEPT reasonCode=100 ecDebitReply_reasonCode=100 ecDebitReply_settlementMethod=A ecDebitReply_requestDateTime=2004-08-16T23:48:09Z ecDebitReply_amount=100.00 ecDebitReply_verificationLevel=1 ecDebitReply_reconciliationID=02RYXSPGCQH60NWA ecDebitReply_processorResponse=123456
purchaseTotals_currency=USD
39
40
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
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 sellers 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.
adult_content default electronic_good electronic_software gift_certificate handling_only service shipping_and_handling shipping_only
stored_value subscription
41
42
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 A B C D E G
Summary Partial match Partial match No match Match Invalid Not supported
Description Street address matches, but 5- and 9-digit postal codes do not match. Street address matches, but postal code not verified. Returned only for non-U.S.-issued Visa cards. Street address and postal code not verified. Returned only for non-U.S.-issued Visa cards. Street address and postal code match. Returned only for nonU.S.-issued Visa cards. AVS data is invalid. Non-U.S. issuing bank does not support AVS.
43
Card Verification Number Codes
Table 6 Address Verification Service Codes (Continued)
Code I N P R S U W X Y Z 1 2
Summary No match No match Partial match System unavailable Not supported System unavailable Partial match Match Match Partial Match Not supported Invalid
Description Address not verified. Returned only for non-U.S.-issued Visa cards. Street address, 5-digit postal code, and 9-digit postal code do not match. Postal code matches, but street address not verified. Returned only for non-U.S.-issued Visa cards. System unavailable. U.S.-issuing bank does not support AVS. 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. Street address does not match, but 9-digit postal code matches. Exact match. Street address and 9-digit postal code match. Exact match. Street address and 5-digit postal code match. Street address does not match, but 5-digit postal code matches. CyberSource AVS code. AVS is not supported for this processor or card type. 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
Appendix B Description of Return Codes
Table 7 Card Verification Codes (Continued)
Code N P S U X 1 2 3
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. Card verification is not supported for this processor or card type. The processor returned an unrecognized value for the card verification response. 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.
45
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 100 101
Description Successful transaction. 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
Table 9 Reason Codes for Credit Card Services (Continued)
Reason Code 201
Description 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 customers 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 processors 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.
47
Reason Code 234
Description 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
Reason Code 247
Description 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 100 101
Description Successful transaction. 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.
49
Table 10 Reason Codes for Electronic Check Services
Reason Code 152
Description 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 customers account. Possible action: Request a different form of payment.
221
The customer matched an entry on the processors negative file. Possible action: Review the order and contact the payment processor.
222
The customers 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
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 CyberSources 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
51
All the information stored in the subscription will be used for the payment or credit, including required information such as the customers 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 Visas 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 Users 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 Centers 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
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 customers 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. CyberSources 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
53
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! Were 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
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=349209
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.
55
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 CyberSources 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 billTo_customerID ccCaptureService_ authRequestID ccCaptureService_ authType ccCaptureService_run ccCaptureService_ verbalAuthCode
Description Your identifier for the customer. Value of requestID returned from the credit card authorization reply. Set to verbal to indicate a verbal authorization. See Processing a Verbal Authorization on page 55. Set to true to include the credit card capture service in your request. Verbally obtained authorization code. See Processing a Verbal Authorization on page 55.
Required / Optional Optional Required Required for a verbal authorization Required Required for a verbal authorization
Data Type & Length String (50) String (26) String (6)
56
Table 11 Capture Request Fields (Continued)
Field Name comments
Description 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.
item_#_productCode item_#_productName item_#_productSKU item_#_quantity item_#_taxAmount item_#_unitPrice
Optional Optional Optional Optional Optional
String (30) String (30) String (15) Integer (10) String (15) String (15)
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. 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 authorizations values in the Business Center and the Order Detail Report and not the values you provided with the capture.
See description
Optional
String (64)
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 email 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.
Required
String (50)
purchaseTotals_currency
Required
String (5)
57
Table 11 Capture Request Fields (Continued)
Field Name purchaseTotals_ grandTotalAmount
Description 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.
Capture Reply Fields

Table 12 lists the capture reply fields.
Table 12 Capture Reply Fields
Field Name ccCaptureReply_amount ccCaptureReply_ reasonCode ccCaptureReply_ reconciliationID ccCaptureReply_ requestDateTime
Description Total amount of the capture. 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-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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
Data Type & Length String (15) Integer (5)
decision
String (6)

invalidField_0...N merchantReferenceCode missingField_0...N purchaseTotals_ currency reasonCode
ERROR: There was a system error REJECT: One or more of the services in the request was declined
String (100) String (50) String (100) String (5) Integer (5)
Fields in the request that contained invalid data. Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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 for the Simple Order API on page 46 for a list of possible values.
58
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.
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 customers 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 CyberSources 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).
59
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 billTo_city billTo_country billTo_customerID billTo_email billTo_firstName billTo_lastName billTo_phoneNumber billTo_postalCode
Description For descriptions for all of the billTo_ fields, see Table 1 on page 21.
Required / Optional Required ** Required **
Data Type & Length String (50) String (2) String (50) String (255) String (60) String (60) String (15) String (10)
Your identifier for the customer.
Optional Required ** Required ** Required ** Optional Required for U.S. and Canada ** Required for U.S. and Canada ** Required ** Optional
billTo_state
String (2)
billTo_street1 billTo_street2 card_accountNumber Customers credit card number.
String (60) String (60) String with numbers only (20) String (2)
Required **
card_expirationMonth
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 **
card_expirationYear
** Optional for follow-on credits
Required **
String (4)
60
Table 13 Credit Request Fields (Continued)
Field Name ccCreditService_billPayment
Description 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. 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 customers name, the billing address, or the credit card information. 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. Required for a follow-on credit String (26)
ccCreditService_ commerceIndicator
Optional
String (13)
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.
Required Optional String (5) String (255)
ccCreditService_run comments
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.
item_#_productCode item_#_productName item_#_productSKU item_#_quantity item_#_taxAmount

Optional Optional Optional Optional Optional
String (30) String (30) String (15) Integer (10) String (15)
61
Field Name item_#_unitPrice
Description 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. 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 authorizations values in the Business Center and the Order Detail Report and not the values you provided with the credit.
merchantDefinedData_field1
Optional
String (64)
merchantDefinedData_field2 merchantDefinedData_field3 merchantDefinedData_field4 merchantID
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 email 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 credit and use a subscription ID to reference the subscription information. See Using a Subscription for a Credit on page 59.
Required
String (50)
recurringSubscriptionInfo_ subscriptionID
Optional
String (26)
62
Credit Reply Fields

Table 14 lists the credit reply fields.
Table 14 Credit Reply Fields
Field Name ccCreditReply_amount ccCreditReply_ reasonCode ccCreditReply_ reconciliationID ccCreditReply_ requestDateTime
Description Total amount of the credit. 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-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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
Data Type & Length String (15) Integer (5)
decision
String (6)

invalidField_0...N merchantReferenceCode missingField_0...N purchaseTotals_ currency reasonCode
String (100) String (50) String (100) String (5) Integer (5)
Fields in the request that contained invalid data. Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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 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.
requestID
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
63
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 merchantID
Description Your CyberSource merchant ID. You received this in the registration email 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. Set to true to include the void service in your request. The requestID of the capture or credit you want to void.
Required / Optional Required
Required
String (50)
voidService_run voidService_ voidRequestID
Required Required
64
Void Reply Fields

Table 16 lists the void reply fields.
Table 16 Void Reply Fields
Reply Field decision
Brief Description Summarizes the result of the overall request. The field can contain one of the following values: ACCEPT: The request succeeded

invalidField_0...N merchantReferenceCode missingField_0...N reasonCode
ERROR: There was a system error REJECT: One or more of the services in the request was
declined String (100) String (50) String (100) Integer (5)
Fields in the request that contained invalid data. Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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. Total amount of the void. 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-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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.
requestID voidReply_amount voidReply_currency voidReply_reasonCode
String (26) String (15) String (5) Integer (5)
voidReply_ requestDateTime
String (20)
Using Payer Authentication

CyberSource supports Verified by VisaSM and MasterCard SecureCode, and JCB J/ Secure Payer Authentication for these processors:
65
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 cardmembers enrollment in the program and validate the cardmembers 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 ccAuthService_cavv
Description Transaction identifier generated by the issuing bank for Verified by Visa and JCB J/Secure transactions. Must be 28character 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.
Used By (Required/ Optiona) ccAuthService See field description
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.
ccAuthService (required for all Payer Authentication transactions)
String (13)
js_attempted: JCB J/Secure

transaction was attempted but not authenticated. Supported for Vital. If selected, then ccAuthService_cavv and ccAuthService_xid are optional.
66
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 40character hex-binary. 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) ccAuthService See field description String (40)
67
Table 17 Additional Authorization Fields for Payer Authentication (Continued)
Field Name ucaf_collectionIndicator
Description 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.
Used By (Required/ Optiona) ccAuthService (required for MasterCard SecureCode transactions)
Data Type & Length String with numbers only (1)
1: UCAF collection is supported, but

UCAF was not populated.
2: UCAF collection is supported, and

UCAF was populated. Successful MasterCard SecureCode transaction.
Required for all MasterCard SecureCode transactions (ccAuthService_commerceIndicator = spa).
68
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 CyberSources 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 customers 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 Users Guide.
69
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 customers 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 customers 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
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 Users Guide.
Credit Request Fields

Table 18 lists the fields you use to request an electronic check credit.
Table 18 Credit Request Fields
Field Name billTo_city billTo_country billTo_customerID billTo_dateOfBirth billTo_email billTo_firstName billTo_lastName billTo_phoneNumber billTo_postalCode billTo_state billTo_street1 billTo_street2 check_accountNumber
Description For descriptions for all of the billTo_ fields, see Table 3 on page 32.
Required / Optional Required ** Required **
Data Type & Length String (50) String (2) String (50) String (10) String (255) String (60) String (60) String (15) String (10) String (2) String (60) String (60) String with numbers only (17) String (1)
Your identifier for the customer. NOTE If you use AmeriNet, check with them to see if they require you to provide this field.
Optional Used by AmeriNet only ** Required ** Required ** Required ** Required ** Required ** Required ** Required ** Optional **
Checking account number.
Required **
check_accountType
Checking account type. This field can contain one of the following values: C: Checking
Required **
S: Savings X: Corporate checking
** Field not needed if performing a follow-on credit (which requires ecCreditService_debitRequestID)
71
Field Name check_bankTransitNumber
Description Bank routing number (also known as the transit number). Check number.
Required / Optional Required **
Data Type & Length String with numbers only (9) String with numbers only (8)
check_checkNumber
Note If you use AmeriNet, check with them to see if they require you to provide this field.
comments Optional comments you have about the credit. These comments will not be shown to the customer. 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 customers name, the billing address, or the bank account information. For stand-alone credits with TeleCheck, set this field to the value that you received in the ecDebitReply_reconciliationID field in the associated debits reply. See Stand-Alone Credits on page 70 for more information. For TeleCheck, The maximum length is 25. ecCreditService_run item_#_productCode item_#_productName item_#_productSKU item_#_quantity item_#_taxAmount 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. Set to true to include the credit service in your request. For descriptions of the item_#_ fields, see Table 3 on page 32.
Used by AmeriNet only ** See field description Optional
String (255)
ecCreditService_ debitRequestID
Required only for a follow-on credit (see Follow-On Credits on page 70) Required for CyberSource stand-alone credits with TeleCheck
String (26)
ecCreditService_ referenceNumber
String (60)
Required Optional Optional Optional Optional Optional See description
String (5) String (30) String (30) String (15) Integer (10) String (15) String (15)
72
Field Name merchantDefinedData_field1
Description 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 debits values in the Business Center and the Order Detail Report and not the values you provided with the credit.
merchantDefinedData_field2 merchantDefinedData_field3 merchantDefinedData_field4 merchantID
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 email 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.
Required
String (50)
recurringSubscriptionInfo_ subscriptionID
Optional
String (26)
73
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
Data Type & Length Integer (5)
String (6)

ecCreditReply_amount ecCreditReply_ processorResponse ecCreditReply_ processorTransactionID ecCreditReply_ reasonCode ecCreditReply_ reconciliationID ecCreditReply_ requestDateTime
String (15) String (6) String (87) Integer (5)
Total amount of the credit. Result code returned by the payment processor. Transaction identifier or tracking ID returned by AmeriNet. 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-MMDDThh:mm:ssZ. For example, 2003-08-11T22: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). Fields in the request that contained invalid data. Order reference or tracking number that you provided in the request. Required fields that were missing from the request. 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 for Electronic Check Services on page 49 for a list of possible values.
ecCreditReply_ settlementMethod invalidField_0...N merchantReferenceCode missingField_0...N purchaseTotals_currency reasonCode
String (1) String (100) String (50) String (100) String (5) Integer (5)
74
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.
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 241
Description 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.
75
Reason Codes
76
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
77
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 https://ics2ws.ic3.com/commerce/1.x/transactionProcessor. In general, the schemas 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 services 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 https://ics2ws.ic3.com/commerce/1.x/transactionProcessor where the XML schema is located. For test transactions, you send your requests to https://ics2wstest.ic3.com/ 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
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 customers order contains more than one item, you number the items, starting with 0. The XML schema uses an id attribute in the items 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>
item_0_unitPrice item_0_quantity
79
Table 22 Numbered Items
Schema Names
<item id="1"> <unitPrice>
<quantity> </item>
item_1_unitPrice item_1_quantity

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>650-965-6000</phoneNumber> <email>jdoe@example.com</email> </billTo> <item id="0"> <unitPrice>49.95</unitPrice> <quantity>1</quantity> </item> <purchaseTotals> <currency>USD</currency> </purchaseTotals> <card> <accountNumber>4111111111111111</accountNumber> <expirationMonth>12</expirationMonth> <expirationYear>2015</expirationYear> </card> <ccAuthService run="true"/> </requestMessage>
80
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>0305782650000167905080</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>2004-02-28T23:44:27Z</c:authorizedDateTime> <c:processorResponse>A</c:processorResponse> </c:ccAuthReply> </c:replyMessage>
81
82
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
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
B
bill payment 52, 59
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
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
83
FU
F
FDMS Nashville 4, 5, 53 FDMS South 4, 5, 6, 53, 54 forced capture 52 fraud 4 freight charges 11
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
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
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
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
T
tax 11 testing 20
P
payer authentication 65 Payment Events Report 31 Paymentech 4, 5, 53, 54 product codes 41
84
U
USA PATRIOT Act compliance 6
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
85
ZZ
86

Cybersource

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cybersource

Uploaded by

Copyright:

Available Formats

CyberSource Business Center Simple Order API

Users Guide Simple Order API

CyberSource Contact Information

Restricted Rights Legends

Business Center Simple Order API Users Guide June 2006

Processing Electronic Check Orders

Business Center Simple Order API Users Guide June 2006

Business Center Simple Order API Users Guide June 2006

About the Business Center

Business Center Simple Order API Users Guide June 2006

About Processing Credit Cards

About Processing Credit Cards

Supported Card Types

MasterCard and Diners Club Alliance

Business Center Simple Order API Users Guide June 2006

Reducing Your Chances of Fraud

Reducing Your Chances of Fraud

Address Verification Service

Card Verification Number

Card verification number

Business Center Simple Order API Users Guide June 2006

Reducing Your Chances of Fraud

Figure 2 Smart Authorization Settings in the Business Center

Using This Guide

Business Center Simple Order API Users Guide June 2006

Using This Guide

Advanced API Capabilities for Credit Cards

Processing Credit Card Orders

Java .NET ASP

Business Center Simple Order API Users Guide June 2006

Using the Latest API Version

Using the Latest API Version

Understanding API Requests and Replies

Chapter 2 Processing Credit Card Orders

Required Item-Level Fields

Otherwise, item_#_quantity is required, along with item_#_productName and item_#_ productSKU.

The grand total for this transaction is (10.00 * 5) + 4.00 = 54.00.

Specifying Freight Charges

Business Center Simple Order API Users Guide June 2006

Understanding API Requests and Replies

Using a Grand Total

Chapter 2 Processing Credit Card Orders

Business Center Simple Order API Users Guide June 2006

Understanding API Requests and Replies

Missing and Invalid Request Fields

Chapter 2 Processing Credit Card Orders

ccAuthReply_authorizedDateTime=2004-02-28T23:44:27Z ccAuthReply_processorResponse=A purchaseTotals_currency=USD

Processing a Credit Card Order

Business Center Simple Order API Users Guide June 2006

Processing a Credit Card Order

Chapter 2 Processing Credit Card Orders

This is an example sale reply where both services are successful:

Using Fraud Screening Tests

Address Verification Service

Business Center Simple Order API Users Guide June 2006

Processing a Credit Card Order

Card Verification Number

Using Additional Authorization Features

Chapter 2 Processing Credit Card Orders

Capturing the Order

Refunding the Customers Money

Business Center Simple Order API Users Guide June 2006