cybersource (1)

CyberSource Business CenterSimple Order APIUser’s Guide

Simple Order API

June 2006

ii CyberSource Corporation

CyberSource Contact InformationFor 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 tohttp://www.cybersource.com.

For sales questions about any CyberSource Service, email [email protected] or call 650-965-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 LegendsFor 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.

TrademarksCyberSource, 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.

http://www.cybersource.com

mailto:[email protected]

https://businesscenter.cybersource.com

Contents

Business Center S

Processing Credit Card Orders

Documentation Changes............................................................................................................vii

Chapter 1Introduction.....................................................................................................................................1About the Business Center.............................................................................................................1About Processing Credit Cards.....................................................................................................2

Supported Card Types ............................................................................................................2MasterCard and Diners Club Alliance..................................................................................3

Reducing Your Chances of Fraud .................................................................................................4Address Verification Service ..................................................................................................4Card Verification Number ......................................................................................................5Smart Authorization ................................................................................................................5$0 Authorization.......................................................................................................................6

Using This Guide.............................................................................................................................7

Chapter 2Processing Credit Card Orders ....................................................................................................9Downloading a Client.....................................................................................................................9Using the Latest API Version.......................................................................................................10Understanding API Requests and Replies.................................................................................10

API Requests ...........................................................................................................................10Using Items ......................................................................................................................11Required Item-Level Fields ...........................................................................................11Specifying Tax .................................................................................................................11Specifying Freight Charges............................................................................................11Using a Grand Total .......................................................................................................12Example Request.............................................................................................................12

API Replies..............................................................................................................................13Decisions ..........................................................................................................................13Reason Codes...................................................................................................................14Missing and Invalid Request Fields .............................................................................14Example Replies ..............................................................................................................14

Order Identifiers.....................................................................................................................15Order Number.................................................................................................................15Request ID........................................................................................................................15Reconciliation ID.............................................................................................................15

imple Order API User’s Guide • June 2006 iii

Processing a Credit Card Order ..................................................................................................15Requesting an Authorization ...............................................................................................16Requesting a Sale ...................................................................................................................16Using Fraud Screening Tests ................................................................................................17

Address Verification Service.........................................................................................17Card Verification Number.............................................................................................18Smart Authorization.......................................................................................................18

Using Additional Authorization Features..........................................................................18Capturing the Order ..............................................................................................................19Refunding the Customer’s Money ......................................................................................19Reconciling Your Orders.......................................................................................................20Testing Your Implementation ..............................................................................................20

Going Live ......................................................................................................................................21Authorization API Fields .............................................................................................................21

Request Fields.........................................................................................................................21Reply Fields ............................................................................................................................26

Chapter 3Processing Electronic Check Orders.........................................................................................29Preparing to Accept Electronic Checks......................................................................................29Processing Electronic Check Payments......................................................................................30

Corporate Checks...................................................................................................................30Reconciliation ID....................................................................................................................30Coupons ..................................................................................................................................31

Seeing When the Check Has Cleared.........................................................................................31Refunding the Customer’s Money..............................................................................................31Testing Your Implementation .....................................................................................................31Electronic Check Debit API Fields..............................................................................................32

Request Fields.........................................................................................................................32Reply Fields ............................................................................................................................38

Example Request and Reply........................................................................................................39

Appendix AProduct Codes ...............................................................................................................................41

Appendix BDescription of Return Codes .....................................................................................................43Address Verification Service Codes ...........................................................................................43Card Verification Number Codes ...............................................................................................44Smart Authorization Factor Codes .............................................................................................45Reason Codes for the Simple Order API ...................................................................................46

Reason Codes for Credit Card Services ..............................................................................46Reason Codes for Electronic Check Services .....................................................................49

Appendix CAdvanced API Capabilities for Credit Cards .........................................................................51Additional Authorization Features ............................................................................................51

Processing Electronic Check Orders

iv CyberSource Corporation

Contents

Business Center S

Using a Subscription for a Payment ....................................................................................51Performing a Forced Capture...............................................................................................52Indicating a Visa Bill Payment .............................................................................................52Indicating a Recurring Payment ..........................................................................................53Using Coupons .......................................................................................................................54

Using the API for Captures and Credits ....................................................................................55Requesting a Capture ............................................................................................................55

Processing a Verbal Authorization...............................................................................55Capture Request Fields ..................................................................................................56

Requesting a Credit................................................................................................................59Using a Subscription for a Credit .................................................................................59Indicating a Credit for a Visa Bill Payment.................................................................59Credit Request Fields .....................................................................................................60Credit Reply Fields .........................................................................................................63

Using the API for Voids ...............................................................................................................63Void Request Fields ...............................................................................................................64Void Reply Fields ...................................................................................................................65

Using Payer Authentication.........................................................................................................65

Appendix DAdvanced API Capabilities for Electronic Checks ................................................................69Using a Subscription for a Debit or Credit ................................................................................69Processing Credits with the API .................................................................................................70

Follow-On Credits..................................................................................................................70Stand-Alone Credits...............................................................................................................70Reconciliation ID ....................................................................................................................70Payment Events Report .........................................................................................................71Credit Request Fields.............................................................................................................71Credit Reply Fields ................................................................................................................74

Reason Codes .................................................................................................................................75

Appendix EUsing the XML API ......................................................................................................................77Downloading a Client...................................................................................................................77About the XML API ......................................................................................................................77

Constructing Requests...........................................................................................................78Parsing Replies .......................................................................................................................78

Correlating Fields Names.............................................................................................................78Requesting Credit Card Authorization......................................................................................79Numbering Items ..........................................................................................................................79Example Request and Reply ........................................................................................................80

Index ...............................................................................................................................................83

imple Order API User’s Guide • June 2006 v

vi CyberSource Corporation

R

M

Fe

No

Documentation Changes

Business Center S

elease C

ay 2996 •

•

•

bruary 2006 •

•

•vember 2005 •

•

•

•

The following table lists changes made in the last six releases of this document:

hanges

Corrected an error: Through the API, you can request a credit card credit (“Requesting a Credit” on page 59) or check debit refund (“Refunding the Customer’s Money” on page 31) only within 60 days of the original authorization or debit, not 120 days as stated. In addition, in the Business Center, you can request a credit card credit within 120 days of the authorization (“Refunding the Customer’s Money” on page 19).

Reorganized Chapter 2, “Processing Credit Card Orders,” on page 9. For an outline of the changes, see the Table of Contents: Processing Credit Card Orders.

Moved to the end of the chapter the list of API fields. For the new layout for the chapter, see the Table of Contents: Processing Electronic Check Orders.

Moved the information about Level III transactions, retail transactions, and the test simulator to separate supplements to this guide. See the Level III Supplement, the Retail Supplement, and the Testing Simulator Supplement.

Added information about processing payments and credits with a subscription ID. For credit cards, see “Using a Subscription for a Payment” on page 51 and “Using a Subscription for a Credit” on page 59. For electronic checks, see “Using a Subscription for a Debit or Credit” on page 69.

Added information about using JCB J/Secure Payer Authentication. See “Using Payer Authentication” on page 65.

Removed from the guide information that cites the current version of the Simple Order API. See “Using the Latest API Version” on page 10 to determine the current version of the API.

Added information about processing voiding a credit card order through the API. See “Using the API for Voids” on page 63.

Updated the information about how long authorizations stay in the CyberSource database and thus how long you have to perform follow-on transactions such as credits. See “Requesting a Credit” on page 59 and “Processing Credits with the API” on page 70.

Moved the information about optional credit card authorization features to an appendix. See Appendix C, “Additional Authorization Features,” on page 51.

imple Order API User’s Guide • June 2006 vii

http://apps.cybersource.com/library/documentation/sbc/SB_API_Level3/html/

http://apps.cybersource.com/library/documentation/sbc/SB_API_Retail/html/

http://apps.cybersource.com/library/documentation/sbc/SB_API_Testing/html/


g Coupons” on

nsactions. See these

and thus how long you 59 and “Processing

s. See the field

ment.

guide: ld3, and tion about using the

nformation about using 0 for information about r information about ge 71 for information

Payment” on page 53.

about using a total .

October 2005 • Updated the Simple Order API version to 1.17.

• Added information about using coupons with credit cards and electronic checks. See “Usinpage 54.

• Changed the required/optional status for the fields below when you use them with retail trafields’ descriptions in the Retail Supplement.

billTo_firstNamebillTo_lastNamebillTo_emailbillTo_street1billTo_citybillTo_statebillTo_postalCodebillTo_country

• Updated the information about how long authorizations stay in the CyberSource database have to perform follow-on transactions such as credits. See “Requesting a Credit” on pageCredits with the API” on page 70.

• Added the billTo_customerID and comments fields as optional fields for all of the servicedescriptions in Table 1 on page 21.

August 2005 • Updated the Simple Order API version to 1.16.

• Added information about processing retail point of sale transactions. See the Retail Supple

July 2005 • 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 merchantDefinedData_field1, merchantDefinedData_field2, merchantDefinedData_fiemerchantDefinedData_field4. See the field descriptions in Table 1 on page 21 for informafields with a credit card authorization. See the field descriptions in Table 11 on page 56 for ithe fields with a credit card capture. See the field descriptions in Table Table 13 on page 6using the fields with a credit card credit. See the field descriptions in Table 3 on page 32 fousing the fields with an electronic check debit. See the field descriptions in Table 18 on paabout using the fields with an electronic check credit.

• Added information about how to process recurring payments. See “Indicating a Recurring

• 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 informationfreight amount and total tax amount for the order. See “Using a Grand Total” on page 12

Release Changes

viii CyberSource Corporation



Chapter 1

Introduction

Business Center S

This document is for users of the Business Center, and it covers processing credit card orders with CyberSource’s Simple Order API.

You may want to use the API instead of CyberSource’s Virtual Terminal or Hosted Order Page for many reasons such as these:

• You want more flexibility and control over the customer’s buying experience at your Web store.

• Your business has grown, and your order volume warrants a higher level of order processing automation.

You should use the API and this guide only if:

• You have an ISP or hosting provider to host your online store.

• You store uses a secure (SSL) online payment form.

• Your store does not already have a shopping cart to process payments.

• You have programming skills in Java, ASP, .NET, PHP, or Perl.

If you are a developer with XML experience and want to use CyberSource’s XML API instead of the Simple Order API, start here, but also see Appendix E, “Using the XML API,” on page 77.

This chapter includes these sections:

About the Business CenterAbout Processing Credit CardsReducing Your Chances of FraudUsing This Guide

About the Business CenterThe 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

imple Order API User’s Guide • June 2006 1

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 CardsYou may have already learned something about credit card processing from reading the Business Center User’s Guide. You will use the API to call CyberSource’s credit card authorization service. The service contacts the bank that issued the card, checks to see if the card has enough funds for the order, and reserves those funds. It also performs some basic fraud checks that are discussed in the next section.

Once your authorization is complete, you still must move the money from the customer’s account into your account. You should move the money only after you have shipped the goods to the customer.

To get the money to move, you must perform a capture of the authorization. You do not need to do this through the CyberSource API, though. Instead, you can do it by using the Business Center. For instructions on how to perform a capture, see the Business Center User’s Guide.

Note If you are an advanced user with large order volume, you may want to use the API to perform captures. See Appendix C, “Advanced API Capabilities for Credit Cards,” on page 51 for more information.

Supported Card TypesWhen you are using the CyberSource API, these are the card types available for each processor:

2 CyberSource Corporation

http://apps.cybersource.com/library/documentation/sbc/SB_UG/html/



Chapter 1 Introduction

Business Center S

• 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 AllianceIn 2004, MasterCard and Diners Club announced an alliance that allows Diners Club cards to be processed as MasterCard cards. This alliance enables merchants who accept MasterCard cards to automatically accept Diners Club cards.

MasterCard cards have a 16-digit number that begins with 5. Diners Club has two types of cards:

• Those issued in North America (by Diners Club North America), which have a 14-digit number that begins with either 30 or 38

• Those issued outside of North America (by Diners Club International), which have a 14-digit number that begins with 36

The Diners Club cards issued in North America will be replaced with MasterCard cards (with the 16-digit number starting with 5) by the end of June 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.

Reducing Your Chances of FraudYou 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 ServiceDepending on your payment processor and the type of credit card that you are processing, the issuing bank might use the Address Verification Service (AVS) to confirm that your customer has provided the correct billing address. If the customer provides incorrect information, the order might be fraudulent. AVS occurs automatically with the authorization request.

You can use the Smart Authorization settings (discussed on page 5) to control which AVS results cause CyberSource to decline the order. Use the Business Center to change your Smart Authorization settings. See the Business Center User’s Guide for more information.

CyberSource returns AVS results for these processors and card types:

• Concord EFS: Visa, MasterCard, American Express, Discover, Diners Club

• FDMS Nashville: Visa, MasterCard, American Express, Discover

• FDMS South: Visa, MasterCard, American Express, Discover, Diners Club

• Paymentech New Hampshire:

• Visa (billing country must be U.S., Canada, or Great Britain)

• American Express (billing country must be U.S. or Canada)

• MasterCard, Discover, Diners Club (billing country must be U.S.)

• Vital: Visa, MasterCard, American Express, Diners Club (billing country must be U.S.)




Business Center S

Card Verification NumberMany 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

You can use the Smart Authorization settings (discussed on page 5) to control which card verification results cause CyberSource to decline the order. Use the Business Center to change your Smart Authorization settings. See the Business Center User’s Guide for more information.

CyberSource supports card verification numbers for these processors and card types:

• FDMS Nashville: Visa, MasterCard

• FDMS South: Visa, MasterCard, American Express, Discover

• Paymentech New Hampshire: Visa, MasterCard, American Express, Discover

• Vital: Visa, MasterCard, American Express, Discover

Smart AuthorizationThe 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)

1234567890123456 789

Card verification number



Reducing Your Chances of Fraud

• Transaction amount

You should consider, however, signing up to use Advanced Smart Authorization, which screens your credit card authorizations based on the following additional, more sophisticated criteria:

• The order contains obscenities.

• The order contains nonsensical input. For example, if the customer enters their last name as “zqmmmmz”.

• The billing or shipping address is not verified. The system could not verify that the billing or shipping address exists.

• The billing and shipping addresses do not match.

• USA PATRIOT Act compliance. The person or organization placing the order, or the country in the shipping address, are on a list of “denied parties or places” to whom the United States prohibits commercial sale according to the USA PATRIOT Act.

Important You must configure the Smart Authorization settings in the Business Center before you accept orders. See Figure 2 on page 7 for what the settings look like.

Smart Authorization analyzes each credit card authorization based on your settings. If you have configured the service to reject orders failing any or all of the Smart Authorization tests, the service will respond to your authorization request with a “decline” message, even if the card issuer itself approved the purchase.

$0 AuthorizationIf 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.



Business Center S

Chapter 1

Chapter 2

Chapter 3

Figure 2 Smart Authorization Settings in the Business Center

Using This GuideThis 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.

Introduction 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

duct

codes, n factor n receive.

ess credit Payer l credit

cess

ple Order

Appendices. The appendices provide general reference information and additional API information for merchants who want to access other credit card and electronic check services.

Additional Resources• Business Center User’s Guide — This guide shows you how to perform the various

functions available in the Business Center, such as configuring your settings and searching for orders. We recommend that you read this guide before you start implementing the Simple Order API to process orders.

• Business Center Reporting User’s Guide — This guide describes the many reports available in the Business Center.

• Business Center Subscription Payments User’s Guide — If you decide to use CyberSource’s subscriptions payments services, you should read this guide to learn how to create and manage subscriptions.

• Business Center PayPal User’s Guide — If you decide to use CyberSource’s PayPal services, you should read this guide to learn how to process PayPal payments.

Appendix A Product Codes Describes the values you can use for an item’s procode.

Appendix B Description of Return Codes Describes the Address Verification Service (AVS) Card Verification (CVN) codes, Smart Authorizatiocodes, and Simple Order API reason codes you ca

Appendix C Advanced API Capabilities for Credit Cards

Describes how to use the Simple Order API to proccard captures, credits, and authorizations that useAuthentication. Also describes how to use optionacard authorization features.

Appendix D Advanced API Capabilities for Electronic Checks

Describes how to use the Simple Order API to proelectronic check credits.

Appendix E Using the XML API Describes how to use the XML variation of the SimAPI.


http://apps.cybersource.com/library/documentation/sbc/SB_Reporting_UG/html/


http://apps.cybersource.com/library/documentation/sbc/SB_Sub_Payments_UG/html/

http://apps.cybersource.com/library/documentation/sbc/SB_PayPal_UG/html/

Chapter 2


Business Center S

This chapter describes how to process a basic credit card order by using the CyberSource Simple Order API. The information in this chapter covers card-not-present transactions (for example, transactions you accept through a Web store or through mail order/telephone). For information about retail transactions, see the Retail Supplement to this guide. For information about processing electronic check orders, see Chapter 3, “Processing Electronic Check Orders,” on page 29.

Important Before going any further, make sure you are accepting orders using a secure connection (SSL). If you do not use SSL to take orders on your Web site, do not use the API. Instead, use the Hosted Order Page or the Virtual Terminal. See the Hosted Order Page User’s Guide or the Business Center User’s Guide for more information about how to use them.

This chapter includes these sections:

Downloading a ClientUsing the Latest API VersionUnderstanding API Requests and RepliesProcessing a Credit Card OrderGoing LiveAuthorization API Fields

Downloading a ClientTo use the API to process orders, the first thing you need to do is pick one of our clients (SDKs):

You can download your chosen client and its related documentation from the Support Center.

• Java

• .NET

• ASP

• PHP

• Perl



http://www.cybersource.com/support_center/implementation/downloads/simple_order/matrix.html


http://apps.cybersource.com/library/documentation/sbc/HOP_UG/html/

http://apps.cybersource.com/library/documentation/sbc/HOP_UG/html/


Using the Latest API Version

Using the Latest API VersionCyberSource 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 RepliesIn general, you process a credit card order through CyberSource like this:

1 You collect information about the order (the items being bought, the customer’s name and address, the credit card information, and so on).

2 You send us a request with the information and ask us to perform the credit card authorization service.

3 We process your request and send you a response. 4 You look at the response and then tell your customer the results of their order.

For example, the bank that issued the card may decide not to authorize the payment. You then need to tell your customer that the credit card has been denied, and possibly ask them for another form of payment.

API RequestsA 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.


http://www.cybersource.com/support_center/support_documentation/ws_release_notes/

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/

Chapter 2 Processing Credit Card Orders

Business Center S

Using ItemsFor the items being purchased, you number each item and call them item_0, item_1, item_2, and so on. You have fields that you can use to help describe the customer’s order for that item. These include item_#_quantity, item_#_unitPrice, item_#_productCode, item_#_taxAmount, and others. CyberSource uses the information you provide for each item to calculate the total amount for the order.

Important Do not include any carets (^) or colons (:) in the values you send in the request for any of the item_#_ fields. Carets and colons are reserved for use by the CyberSource services. Do not put any newlines or carriage returns into the values of any of the request fields. However, you can put embedded spaces and any other printable characters in the values. We will remove all leading and trailing spaces.

Required Item-Level FieldsTypically, 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 TaxTo 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=5item_0_taxAmount=4.00

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

Specifying Freight ChargesTo 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


Understanding API Requests and Replies

• shipping_and_handling

For example:

item_0_unitPrice=10.00item_0_quantity=5

item_0_taxAmount=4.00


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 TotalAlternately, 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 item-level, tax, or freight information and just want to use a transaction total that covers everything.

You may send this field instead of or in addition to the item-level information discussed in the previous section. If you send purchaseTotals_grandTotalAmount, CyberSource uses your value and does not use the item-level information to calculate the transaction’s grand total. Note that the item information (if you provide it) still appears in the Transaction Detail page for the order in the Business Center.

Example RequestSee 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=infodevmerchantReferenceCode=482046C3A7E94F5

billTo_firstName=John

billTo_lastName=DoebillTo_street1=1295 Charleston Rd.

billTo_city=Mountain View

billTo_state=CAbillTo_postalCode=94043

billTo_country=US

billTo_phoneNumber=650-965-6000

[email protected]_0_unitPrice=49.95

item_0_quantity=1

purchaseTotals_currency=USDcard_expirationMonth=12



Business Center S

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 RepliesThe 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.

DecisionsIn the reply, you receive a field named decision, which summarizes the overall result of your request. Look at this field first to determine what to do with the order. The decision can be one of the following:

• ACCEPT: The request succeeded

• ERROR: There was a system error

• REJECT: The request was rejected

If you get an ACCEPT, then you should proceed taking the customer’s order.

You get errors typically because of CyberSource system issues unrelated to the content of your request. Errors are very rare; however, you must design your system to include a way to correctly handle them. Depending on which payment processor is handling the order, the error may indicate a valid CyberSource system error, or it may indicate a processor rejection because of some type of invalid data. In either case, we recommend that you do not design your system to endlessly retry sending a request in the case of a system error. See the documentation for the CyberSource client (SDK) you are using for more information about how to handle system errors and retries.

You can get a REJECT for different reasons. Your request can be rejected by CyberSource, the payment processor, or the issuing bank. For example, CyberSource will reject a request if it is missing required fields or a value is invalid. The issuing bank will reject a request if the card limit has been reached and funds are not available. To determine why a request was rejected, look at the reasonCode field (discussed below).

You are charged for all accepted and rejected requests. You are not charged for requests that result in errors.

card_expirationYear=2015card_accountNumber=4111111111111111


Understanding API Requests and Replies

Reason CodesAfter 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 FieldsWhen 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 RepliesSee 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=482046C3A7E94F5decision=ACCEPT

reasonCode=100

ccAuthReply_reasonCode=100

ccAuthReply_amount=49.95ccAuthReply_authorizationCode=123456

ccAuthReply_avsCode=Y

ccAuthReply_avsCodeRaw=YYY



Business Center S

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.

Order IdentifiersEach order you process has three identifiers:

Order NumberThis 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 IDThis 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 IDThis 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 OrderWhen 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)

ccAuthReply_authorizedDateTime=2004-02-28T23:44:27ZccAuthReply_processorResponse=A

purchaseTotals_currency=USD

requestID=0305782650000167905080

decision=REJECT

reasonCode=204ccAuthReply_reasonCode=204


Processing a Credit Card Order

If you process only the authorization, you can do the capture later in the Business Center (see page 19). Or, if your business volume warrants it, you can process your captures later through the API (see “Requesting a Capture” on page 55).

Requesting an AuthorizationTo 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 SaleA sale is a bundled authorization and capture. You might use a sale instead a separate authorization and capture if there is no delay between when you take the customer’s order and when you ship the goods. A typical use for a sale is if you are selling electronic goods or a service that you can turn on immediately.

To request a sale, request both the authorization and the capture services at the same time (set both ccAuthService_run and ccCaptureService_run to true). Include all of the request fields for an authorization.

If the authorization is successful, CyberSource immediately processes the capture. The reply gives you an overall result for the request (the decision and reasonCode) as well as the results for the individual services (ccAuthReply_reasonCode and ccCaptureReply_reasonCode). If the authorization is declined, CyberSource does not process the capture, and the reply includes the results for the authorization only.

This is an example sale request:

ccAuthService_run=trueccCaptureService_run=true

merchantID=infodev

merchantReferenceCode=482046C3A7E94F5billTo_firstName=John

billTo_lastName=Doe

billTo_street1=1295 Charleston Rd.billTo_city=Mountain View

billTo_state=CA

billTo_postalCode=94043billTo_country=US

billTo_phoneNumber=650-965-6000

[email protected]



card_expirationMonth=12card_expirationYear=2015



Business Center S

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

Using Fraud Screening TestsThese next few sections describe how to use the authorization API fields related to the fraud screening tests described in Chapter 1, “Reducing Your Chances of Fraud,” on page 4.

Note If your authorization is flagged for one of the fraud checks described below, but you received a valid authorization code from the bank, you can still choose to accept the customer’s order and capture the authorization. However, consider reviewing the order first to make sure that it is legitimate.

Address Verification ServiceThe Address Verification Service (AVS) looks at the billing address the customer provided and checks if it matches the address that the issuing bank has on file. See “Address Verification Service” on page 4 for more information.

You can configure your Smart Authorization settings in the Business Center to control which AVS results cause CyberSource to reject the order (see the Business Center User’s Guide for more information). If your Smart Authorization settings for AVS cause CyberSource to reject the order, you get decision=REJECT and ccAuthReply_reasonCode=520.

card_accountNumber=4111111111111111

requestID=0305782490000167905080


reasonCode=100

ccAuthReply_reasonCode=100ccAuthReply_amount=49.95

ccAuthReply_authorizationCode=123456

ccAuthReply_avsCode=YccAuthReply_avsCodeRaw=YYY

ccAuthReply_authorizedDateTime=2004-02-28T23:44:27Z

ccAuthReply_processorResponse=AccCaptureReply_reasonCode=100

ccCaptureReply_amount=49.95

ccCaptureReply_requestDateTime=2004-02-28T23:44:27ZccCaptureReply_reconciliationID=39208984930






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 NumberYou can request the card verification number from your customer and send it in your authorization request to help reduce the risk of fraud. See “Card Verification Number” on page 5 for more information.

Use the card_cvNumber field in the request to send the customer’s card verification number.

Note If your processor is FDMS Nashville or FDMS South, and you decide to use card verification numbers, you can use the request field card_cvIndicator to indicate if you are sending a card verification number in the request. The field is described below in Table 1.

You can configure your Smart Authorization settings in the Business Center to control which card verification results cause CyberSource to reject the order (see the Business Center User’s Guide for more information). If your Smart Authorization settings cause CyberSource to reject the order, you get decision=REJECT and ccAuthReply_reasonCode=520.

You can get details about the CV result in the ccAuthReply_cvCode field. See Appendix B, “Card Verification Number Codes,” on page 44 for descriptions of the codes that you can receive in this field.

Smart AuthorizationSmart 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 FeaturesCyberSource also offers several other authorization features that you can use depending on your business needs:

Using a Subscription for a PaymentPerforming a Forced CaptureIndicating a Visa Bill PaymentIndicating a Recurring PaymentUsing Coupons





Business Center S

For more information about those features, see “Additional Authorization Features” on page 51.

Capturing the OrderIf you performed an authorization only instead of a sale, you still need to capture the order to move money into your bank account.

Important If you do not capture the authorization, you do not receive payment.

You can do this in the Business Center (this section) or through the API (see “Requesting a Capture” on page 55). To capture in the Business Center:

1 After you have shipped the order, log into the Business Center. 2 Search for authorizations that have not been captured.

Your order will look similar to this:

3 Capture the authorization.You will receive payment in your bank account within two to four days.

Note If you want to process Level III captures with Vital, see the Level III Supplement to this guide.

Refunding the Customer’s MoneyIf you need to refund the customer’s money, we suggest that you use the Business Center. See the Business Center User’s Guide for information about crediting the customer’s card.

Important Because the authorization information necessary to perform a follow-on action is available in the CyberSource database for a limited time only, you can issue a credit card refund as follows:

- Through the API: up to 60 days after the authorization- In the Business Centers: up to 120 days after the authorization

If your business’s order and credit volume is large enough, you might instead consider processing credits using the API. See “Requesting a Credit” on page 59 for more information.


https://businesscenter.cybersource.com




Reconciling Your OrdersAn important part of processing your orders is reconciliation. This is the process of verifying that the list of your processed orders matches the deposits into your bank account.

For information about using CyberSource reports to reconcile your orders, see the Business Center User’s Guide.

Testing Your ImplementationTo make sure that your requests are completed correctly, you need to test the basic success and error conditions for each ICS service you plan to use. When testing, follow these rules:

• Use your regular CyberSource merchant ID to perform testing.

• Use a non-existent account and domain name for the customer’s email address (for example, [email protected]).

• 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:

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.

Credit Card Type Test Account Number

Visa 4111 1111 1111 1111

MasterCard 5555 5555 5555 4444

American Express 3782 8224 6310 005

Discover 6011 1111 1111 1117

JCB 3566 1111 1111 1113

Diners Club 3800 000000 0006





Business Center S

Field Name

billTo_city

billTo_countr

billTo_custom

billTo_email

billTo_firstNa

billTo_lastNam

billTo_phoneN

Going LiveWhen you are ready to accept orders from customers, you can use the Business Center Web site to go live. See the Business Center User’s Guide for more information.

Important You must also configure your client so that it sends transactions to the production server and not the test server. See the documentation for your client for information about how to do this.

After you go live, use real card numbers and other data to test every card type you support. Because these are real transactions in which you are buying from yourself, use small amounts, such as one dollar, to do the tests. Process an authorization, then capture the authorization, and later refund the money. Use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account as expected. If you have more than one CyberSource merchant ID, test each one separately.

Authorization API Fields

Request FieldsTable 1 lists the fields you use to request credit card authorization.Table 1 Authorization Request Fields

Description Required / Optional

Data Type & Length

City of the billing address. Required String (50)

y Country of the billing address. Use the two-character ISO codes.

Required String (2)

erID Your identifier for the customer. Optional String (50)

Customer’s email address, including the full domain name (for example, [email protected]).

Required String (255)

me Customer’s first name.The value should be the same as the one that appears on the card.


e Customer’s last name. The value should be the same as the one that appears on the card.


umber Customer’s phone number. Optional String (15)


http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf



String (10)

String (2)

String (60)

String (60)

String with numbers only (20)

String (3)

Data Type & Length

billTo_postalCode Postal code of the billing address. The field must contain between five and nine digits.

If the value of billTo_country is CA, the number of characters in billTo_postalCode must follow these rules:• If the number of characters is greater

than three, the first three characters must be of the format [alpha][numeric][alpha].

• If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric].

Required for U.S. or Canada

billTo_state State or province of the billing address. Use the two-character codes.

Required for U.S. and Canada

billTo_street1 First line of the billing street address. Required

billTo_street2 Second line of the billing street address. Used for additional address information, for example:

Attention: Accounts Payable

Optional

card_accountNumber Customer’s credit card number. Required

card_cardType Type of card to authorize. This field is required if the card type is JCB (007), and optional for all other card types. See “MasterCard and Diners Club Alliance” on page 3 for important information. This field can contain one of the following values:• 001: Visa

• 002: MasterCard

• 003: American Express

• 004: Discover

• 005: Diners Club

• 007: JCB (required)

Optional (see description)

Table 1 Authorization Request Fields (Continued)

Field Name Description Required / Optional


http://apps.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf


Business Center S

card_cvIndica

card_cvNumb

card_expirati

card_expirati

ccAuthServiccommerceInd

ccAuthServic

comments

Field Name

tor 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.

• 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.

Optional String with numbers only (1)

er Card verification number. See “Card Verification Number” on page 18 for more information. Do not include this field if FDMS South is your processor and you are performing a $0 authorization.

Optional String with numbers only (4)

onMonth Two-digit month (MM - 01 through 12, inclusive) that the credit card expires in. The leading 0 is required.

Required String (2)

onYear Four-digit year (YYYY) that the credit card expires in.

Required String (4)

e_icator

Transaction channel type. This field can contain one of the following values:• internet (default): eCommerce

transaction.

• moto: Mail order or telephone order.

See “Indicating a Recurring Payment” on page 53 for information about recurring payments.

Optional String (13)

e_run Set to true to include the credit card authorization service in your request.

Required String (5)

Optional comments you have about the authorization. These comments will not be shown to the customer.




Data Type & Length



String (30)

String (30)

String (15)

Integer (10)

String (15)

Data Type & Length

item_#_productCode Type of product, which is also used to determine the category that the product falls under (electronic, handling, physical, service, or shipping). The default value is default. See “Product Codes” on page 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.

Optional

item_#_productName Name of the product. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

item_#_productSKU Product’s identifier code. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

item_#_quantity Quantity of the product being purchased. The default value is 1. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

item_#_taxAmount Total tax to apply to the product. This value cannot be negative.

The item_#_taxAmount field is additive. For example, if you send one item with unitPrice of $10.00 and taxAmount of $0.80, and you send another item with unitPrice of $20.00 and taxAmount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included.

Optional





Business Center S

item_#_unitP

merchantDefifield1

merchantDefifield2

merchantDefifield3

merchantDefifield4

merchantID

merchantRefe

purchaseTota

purchaseTotagrandTotalAm

Field Name

rice 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.

See description String (15)

nedData_ Open field that you can use to store any information. The value appears in the transaction’s details in the Business Center and in the Order Detail Report.

NOTE Do not use the field to store any sensitive customer information.


nedData_ 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.


renceCode Merchant-generated order reference or tracking number. See “Order Identifiers” on page 15 for more information.


ls_currency Currency used for the order. All orders must use U.S. dollars. Use USD for this field.

Required String (5)

ls_ount

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.




Data Type & Length



String (50)

String (2)

String (255)

String (60)

String (60)

String (15)

String (10)

String (2)

String (60)

String (60)

Data Type & Length

String (15)

Data Type & Length

Reply FieldsTable 2 lists the credit card authorization reply fields.

shipTo_city City to which to ship the product. Optional (Required if providing any shipping information)

shipTo_country Country to which to ship the product. Use the two-character ISO codes.

Optional

shipTo_email Email address of the person receiving the shipment (for example, [email protected]).

Optional

shipTo_firstName First name of the person receiving the shipment.

Optional

shipTo_lastName First name of the person receiving the shipment.

Optional

shipTo_phoneNumber Phone number for the person receiving the shipment.

Optional

shipTo_postalCode Postal code to which to ship the product. Optional (Required if address is in U.S. and Canada)

shipTo_state State or province to which to ship the product. Use the two-character codes.

Optional (Required if address is in U.S. and Canada)

shipTo_street1 First line of the address to which to ship the product.

Optional (Required if providing any shipping information)

shipTo_street2 Second line of the address to which to ship the product.

Optional

Table 2 Authorization Reply Fields

Field Name Description

ccAuthReply_amount Total amount of the authorization.







Business Center S

ccAuthReply_authFactorCo

ccAuthReply_authorization

ccAuthReply_authorizedDa

ccAuthReply_

ccAuthReply_avsCodeRaw

ccAuthReply_

ccAuthReply_cvCodeRaw

ccAuthReply_processorRes

ccAuthReply_reasonCode

ccAuthReply_reconciliation

decision

invalidField_0

Field Name

deRisk 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.

String (100)

CodeAuthorization code. Returned only if a value if returned by the processor.

For a Vital $0, the value you receive is PREATH.

String (6)

teTimeTime 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.

String (20)

avsCode Results of address verification. See “Address Verification Service Codes” on page 43 for a list of possible values.

String (1)

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 (10)

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.

String (1)

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 (10)

ponseProcessor’s response code.

Note Do not use this field to interpret the result of the authorization.

String (10)

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.

Integer (5)

IDReference number for the transaction. Returned for Paymentech only.

String (60)

Summarizes the result of the overall request. The field can contain one of the following values:• ACCEPT: The request succeeded


• REJECT: One or more of the services in the request was declined

String (6)

...N Fields in the request that contained invalid data. String (100)

Table 2 Authorization Reply Fields (Continued)

Description Data Type & Length



String (50)

String (100)

String (5)

Integer (5)

String (26)

Data Type & Length

merchantReferenceCode Order reference or tracking number that you provided in the request.

missingField_0...N Required fields that were missing from the request.

purchaseTotals_currency Currency used for the order. For U.S. dollars, the value will be USD.

reasonCode Numeric value corresponding to the result of the overall request. See “Reason Codes for the Simple Order API” on page 46 for a list of possible values.

requestID Identifier for the request.

Table 2 Authorization Reply Fields (Continued)



Chapter 3


Business Center S

This chapter describes the Simple Order API fields that you use to process electronic check payments. Before reading this chapter, make sure to read the Business Center User’s Guide. That guide explains important information about processing electronic checks.

Also, this chapter assumes you have experience using the Simple Order API to process credit card payments. If you are not familiar with the API already, read Chapter 2, “Processing Credit Card Orders,” on page 9 to understand the basic concepts of processing requests and replies with the API. This chapter includes these sections:

Preparing to Accept Electronic ChecksProcessing Electronic Check PaymentsSeeing When the Check Has ClearedRefunding the Customer’s MoneyTesting Your ImplementationElectronic Check Debit API FieldsExample Request and Reply

Preparing to Accept Electronic ChecksTo 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.

2 At the end of the checkout process on your Web site, display the following consent statement for the check authorization that your customer must accept before submitting the order:

By clicking Authorize, you authorize an electronic debit from your checking account that will be processed through the regular banking system. If your full order is not available at the same time, you authorize partial debits to your account, not to exceed the total authorized amount. The partial debits will take place upon each shipment of partial goods. If any of your payments are returned unpaid, you will be charged a returned item fee up to the maximum allowed by law. To exit without authorizing, click Cancel.

Click here to view your state’s returned item fee.


http://www.achex.com/html/NSF_pop.jsp



Processing Electronic Check Payments

Processing Electronic Check PaymentsTo 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

You can use either AmeriNet or TeleCheck as your electronic check processor. Depending on which payment processor you use, you might need to collect other personal information from the customer. For example, AmeriNet requires the customer’s date of birth, and TeleCheck requires the customer’s driver’s license information.

Corporate ChecksIf 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 IDIn 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

NAMEADDRESSCITY, STATE ZIP

012301-2345/6789

DATE

PAY TO THEORDER OF $

DOLLARS

BANK NAMEADDRESSCITY, STATE ZIP

FOR

Bank Routing Number

Bank AccountNumber

Check Number


Chapter 3 Processing Electronic Check Orders

Business Center S

the transactions in your processor reports. This number appears in the ecDebitReply_reconciliationID field.

CouponsYou 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 ClearedTo determine when your electronic checks have cleared, use the Payment Events Report, which is available in the Business Center.

For TeleCheck, when the check clears, the event type listed in the report is “Payment.”

If you use AmeriNet, the report shows an event type of “Payment” when AmeriNet receives your debit request. AmeriNet then waits for six days, and if they receive no word from the bank of any problems transferring the funds, they consider the check cleared. You then see an event type of “Completed” for the check. CyberSource does not guarantee that the check has truly cleared.

The report also shows when other events occur. For example, it shows if the bank has any problems processing the check (insufficient funds, errors, and so on), and when refunds clear.

For more information about the Payment Events Report, see the Business Center Reporting User’s Guide.

Refunding the Customer’s MoneyIf you need to refund the customer’s money, we suggest you use the Business Center. See the Business Center User’s Guide for information about how to credit the customer’s bank account.

If your business’s order and credit volume is large enough, you might instead consider processing credits by using the API. See “Processing Credits with the API” on page 70 for more information about using the API to process credits.

Testing Your ImplementationTo 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/





Electronic Check Debit API Fields

Data Type & Length

String (50)

String (40)


String (2)

String (50)

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 FieldsTable 3 lists the request fields you use when requesting an electronic check debit.Table 3 Electronic Check Debit Request Fields


billTo_city City of the billing address. Required

billTo_company Name of the customer’s company. Used only for TeleCheck corporate checks. For these checks, either both billTo_driversLicenseNumber and billTo_driversLicenseState are required, or both billTo_company and billTo_companyTaxID are required.

See field description

billTo_companyTaxID Company’s tax identifier. Used only for TeleCheck corporate checks. For these checks, either both billTo_driversLicenseNumber and billTo_driversLicenseState are required, or both billTo_company and billTo_companyTaxID are required.


billTo_country Country of the billing address. Use the two-character ISO codes.

Required

billTo_customerID Your identifier for the customer. Optional




Business Center S

billTo_dateOf

billTo_driversLicens

billTo_driversLicens

billTo_email

billTo_firstNa

billTo_ipAddr

billTo_lastNa

billTo_phone

Field Name

Birth Customer’s date of birth. Use format YYYY-MM-DD or YYYYMMDD.

NOTE If using AmeriNet, check with them to see if they require you to provide this field.

For AmeriNet corporate checks, use the value 1970-01-01.

Optional (For AmeriNet, see field description)

String (10)

eNumberCustomer’s driver’s 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)

eStateState or province where the customer’s driver’s 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)

Customer’s email address, including the full domain name (for example, [email protected]).


me Customer’s first name. If the first name is unavailable or inapplicable (for example, for a corporate account), enter a dummy value such as NA.


ess Customer’s IP address (for example, 10.1.27.63).


me Customer’s last name. If the transaction is for a corporate account, use the company name.


Number Customer’s phone number. Required String (15)

Table 3 Electronic Check Debit Request Fields (Continued)


Data Type & Length




String (10)

String (2)

String (60)

String (60)


String (1)



String (255)

Data Type & Length

billTo_postalCode Postal code of the billing address. The field must contain between five and nine digits.

If the value of billTo_country is CA, the number of characters in billTo_postalCode must follow these rules:• If the number of characters is greater than

three, the first three characters must be of the format [alpha][numeric][alpha].

• If the number of characters is seven, the last three characters must be of the format [numeric][alpha][numeric].

Required

billTo_state State or province of the billing address. Use the two-character codes.

Required

billTo_street1 First line of the billing street address. Required

billTo_street2 Second line of the billing street address. Used for additional address information, for example:

Attention: Accounts Payable

Optional

check_accountNumber Customer’s checking account number. Required

check_accountType Checking account type. This field can contain one of the following values:• C: Checking

• S: Savings

• X: Corporate checking

Required

check_bankTransitNumber Bank routing number (also known as the “transit number”).

Required

check_checkNumber Check number.

NOTE If using AmeriNet, check with them to see if they require you to provide this field.

Optional (for AmeriNet, see field description)

comments Optional comments you have about the debit. These comments will not be shown to the customer.

Optional






Business Center S

ecDebitServicreferenceNum

ecDebitServic

item_#_produ

item_#_produ

item_#_produ

item_#_quant

Field Name

e_ber

For TeleCheck, this is an optional merchant-generated 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.


String (25)

e_run Whether to include ecDebitService in your request. The field can contain one of the following values:• true: Include the service in your request.

• false (default): Do not include the service in your request.

Required String (5)

ctCode 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.


ctName Name of the product. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

String (30)

ctSKU Product’s identifier code. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

String (15)

ity Quantity of the product being purchased. The default value is 1. Required if item_#_productCode is NOT default, stored_value, or one of the values related to shipping and/or handling.

See description

Integer (10)



Data Type & Length



String (15)

String (15)

String (64)

String (64)

String (64)

String (64)

String (30)

String (50)

String (5)

Data Type & Length

item_#_taxAmount Total tax to apply to the product. This value cannot be negative.

The item_#_taxAmount field is additive. For example, if you send one item with unitPrice of $10.00 and taxAmount of $0.80, and you send another item with unitPrice of $20.00 and taxAmount of $1.60, the total amount authorized will be for $32.40, not $30.00 with $2.40 of tax included.

Optional

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

merchantDefinedData_field1

Open field that you can use to store any information. The value appears in the transaction’s details in the Business Center and in the Order Detail Report.

NOTE Do not use the field to store any sensitive customer information.

Optional


See the description for merchantDefinedData_field1 above.

Optional



Optional



Optional

merchantID 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.

Required

merchantReferenceCode Merchant-generated order reference or tracking number. See “Order Identifiers” on page 15 for more information.

Required

purchaseTotals_currency Currency used for the order. All orders must use U.S. dollars. Use USD for this field.

Required





Business Center S


shipTo_city

shipTo_coun

shipTo_email

shipTo_firstN

shipTo_lastN

shipTo_phon

shipTo_posta

shipTo_state

shipTo_stree

shipTo_stree

Field Name

ls_ount



String (15)

City to which to ship the product. Optional (Required if providing any shipping information)

String (50)

try Country to which to ship the product. Use the two-character ISO codes.

Optional String (2)

Email address of the person receiving the shipment (for example, [email protected]).


ame First name of the person receiving the shipment. Optional String (60)

ame First name of the person receiving the shipment. Optional String (60)

eNumber Phone number for the person receiving the shipment.


lCode Postal code to which to ship the product. Optional (Required if address is in U.S. and Canada)

String (10)

State or province to which to ship the product. Use the two-character codes.

Optional (Required if address is in U.S. and Canada)

String (2)

t1 First line of the address to which to ship the product.

Optional (Required if providing any shipping information)

String (60)

t2 Second line of the address to which to ship the product.




Data Type & Length





Data Type & Length

String (6)

String (15)

String (87)

Integer (5)

String (60)

String (20)

String (6)

String (1)

Integer (1)

String (100)

String (50)

String (100)

String (5)

Integer (5)

String (26)

Reply FieldsTable 4 lists the electronic check debit reply fields.Table 4 Electronic Check Debit Reply Fields


decision Summarizes the result of the overall request. The field can contain one of the following values:• ACCEPT

• ERROR

• REJECT

ecDebitReply_amount Total amount submitted to the payment processor.

ecDebitReply_processorTransactionID

Transaction identifier or tracking ID returned by AmeriNet.

ecDebitReply_reasonCode 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.

ecDebitReply_reconciliationID

Reference number that you use to reconcile your CyberSource reports with your processor reports.

ecDebitReply_requestDateTime

Time when debit is requested. 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.

ecDebitReply_processorResponse

Result code returned by the payment processor.

ecDebitReply_settlementMethod

Method used to settle the debit. This field will contain B to indicate best possible method (best of either ACH or facsimile).

ecDebitReply_verificationLevel

Level of screening for the request. This field will contain 1 to indicate validation.

invalidField_0...N Fields in the request that contained invalid data.




reasonCode Numeric value corresponding to the result of the overall request. See “Reason Codes” on page 75 for a list of possible values.

requestID Identifier for the request.



Business Center S

Example Request and ReplyThe following examples show a request and reply for processing a payment with an electronic check.

Example Electronic Check Debit Request

Example Electronic Check Debit Reply

ecDebitService_run=truemerchantID=infodevmerchantReferenceCode=482046C3A7E94F7billTo_firstName=JohnbillTo_lastName=DoebillTo_street1=1295 Charleston Rd.billTo_city=Mountain ViewbillTo_state=CAbillTo_postalCode=94043billTo_country=USbillTo_phoneNumber=650-965-6000billTo_email=jdoe@example.combillTo_dateOfBirth=19680923item_0_unitPrice=100.00purchaseTotals_currency=USDcheck_accountNumber=4100check_accountType=Ccheck_bankTransitNumber=071923284

requestID=9980055975450167905139


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



Example Request and Reply


Appendix A

Product Codes

Business Center S

Product Code

adult_cont

default

electronic

electronic

gift_certi

handling_o

service

shipping_a

shipping_o

stored_val

subscripti

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

Definition

ent Adult content.

Default value for the product code. CyberSource uses default when a request provides no value for the product code.

_good Electronic product other than software.

_software Software distributed electronically rather than on tapes, disks, or other media.

ficate Gift certificate not issued with CyberSource Stored Value Services.

nly Separate charge that is generally a fee imposed by the seller on the customer. The fee pays for the seller’s administrative selling costs.

Service that you perform for the customer.

nd_handling 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.

nly 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.

ue Stored Value certificate.

on Subscription to a Web site or other content.


Appendix B

Description of Return Codes

Business Center S

This appendix describes these result codes that you can receive:

Address Verification Service CodesCard Verification Number CodesSmart Authorization Factor CodesReason Codes for the Simple Order API

Address Verification Service CodesThe following table lists the possible result codes for the Address Verification Service. See “Address Verification Service” on page 4 for general information about AVS.

Some of the codes have the same meaning. All codes are valid for any type of merchant to receive. You should be prepared to receive any of them.

The alphabetic values in the table below are the Visa standard AVS codes. AVS codes for other types of credit cards are mapped to the Visa standard codes. Some codes are returned only for Visa cards issued outside the U.S.

You receive these codes in the ccAuthReply_avsCode reply field.Table 6 Address Verification Service Codes

Code Summary Description

A Partial match Street address matches, but 5- and 9-digit postal codes do not match.

B Partial match Street address matches, but postal code not verified. Returned only for non-U.S.-issued Visa cards.

C No match Street address and postal code not verified. Returned only for non-U.S.-issued Visa cards.

D Match Street address and postal code match. Returned only for non-U.S.-issued Visa cards.

E Invalid AVS data is invalid.

G Not supported Non-U.S. issuing bank does not support AVS.


Card Verification Number Codes

Card Verification Number CodesThe 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.

I No match Address not verified. Returned only for non-U.S.-issued Visa cards.

N No match Street address, 5-digit postal code, and 9-digit postal code do not match.

P Partial match Postal code matches, but street address not verified. Returned only for non-U.S.-issued Visa cards.

R System unavailable System unavailable.

S Not supported U.S.-issuing bank does not support AVS.

U System unavailable Address information unavailable. Returned if non-U.S. AVS is not available or if the AVS in a U.S. bank is not functioning properly.

W Partial match Street address does not match, but 9-digit postal code matches.

X Match Exact match. Street address and 9-digit postal code match.

Y Match Exact match. Street address and 5-digit postal code match.

Z Partial Match Street address does not match, but 5-digit postal code matches.

1 Not supported CyberSource AVS code. AVS is not supported for this processor or card type.

2 Invalid CyberSource AVS code. The processor returned an unrecognized value for the AVS response.

Table 7 Card Verification Codes

Code Description

D The issuing bank determined that the transaction is suspicious.

I Card verification number failed processor's data validation check.

M Card verification number matched.

Table 6 Address Verification Service Codes (Continued)

Code Summary Description


Appendix B Description of Return Codes

Business Center S

Smart Authorization Factor CodesThe 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.

N Card verification number not matched.

P The processor did not process the card verification number for an unspecified reason.

S Card verification number is on the card but was not included in the request.

U Card verification is not supported by the issuing bank.

X Card verification is not supported by the card association.

1 Card verification is not supported for this processor or card type.

2 The processor returned an unrecognized value for the card verification response.

3 The processor did not return a card verification result code.

Table 8 Smart Authorization Codes

Code Description

J Billing and shipping address do not match.

M Cost of the order exceeds the maximum transaction amount.

N Nonsensical input in the customer name or address fields.

O Obscenities in the order form.

U Unverifiable billing or shipping address.

X Order does not comply with the USA PATRIOT Act.

Table 7 Card Verification Codes (Continued)

Code Description


Reason Codes for the Simple Order API

. Resend the

esend the

15 minutes.

.

to handle

t include

ave reviewed ce client


Reason Codes for the Simple Order APIThis 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 ServicesTable 9 Reason Codes for Credit Card Services

Reason Code Description

100 Successful transaction.

101 The request is missing one or more required fields.

Possible action: See the reply fields missingField_0...N for which fields are missingrequest 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. Rrequest 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

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 howretries in the case of system errors.

151 Error: The request was received but there was a server timeout. This error does notimeouts between the client and the server.

Possible action: To avoid duplicating the order, do not resend the request until you hthe order status in the Business Center. See the documentation for your CyberSour(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.




Business Center S

201

202

203

204

205

207

208

210

211

221

231

232

233

Reason Code

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.

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.

General decline of the card. No other information provided by the issuing bank.


Insufficient funds in the account.


Stolen or lost card.

Possible action: Review the customer’s information and determine if you want to request a different card from the customer.

Issuing bank unavailable.

Possible action: Wait a few minutes and resend the request.

Inactive card or card not authorized for card-not-present transactions.


The card has reached the credit limit.


Invalid card verification number.


The customer matched an entry on the processor’s negative file.

Possible action: Review the order and contact the payment processor.

Invalid account number.


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.

General decline by the processor.


Table 9 Reason Codes for Credit Card Services (Continued)

Description



e

ple, if you try e only applies d Credits” on

.

porarily, and

re processing 5.

is reason ng the API for

indicated in

capture or

pture.

thorization e previously ason code I for Captures

pture.

lready been cannot be See “Using

234 There is a problem with your CyberSource merchant configuration.

Possible action: Do not resend the request. Contact Customer Support to correct thconfiguration problem.

235 The requested amount exceeds the originally authorized amount. Occurs, for examto capture an amount larger than the original authorization amount. This reason codif you are processing a capture through the API. See “Using the API for Captures anpage 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 temto try their order again in a few minutes.

238 The authorization has already been captured. This reason code only applies if you aa capture through the API. See “Using the API for Captures and Credits” on page 5

Possible action: No action required.

239 The requested transaction amount must match the previous transaction amount. Thcode only applies if you are processing a capture or credit through the API. See “UsiCaptures 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 theyyour Web store, then resend the request.

241 The request ID is invalid. This reason code only applies when you are processing acredit 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 ca

242 You requested a capture through the API, but there is no corresponding, unused aurecord. Occurs if there was not a previously successful authorization request or if thsuccessful authorization has already been used by another capture request. This reonly applies when you are processing a capture through the API. See “Using the APand Credits” on page 55.

Possible action: Request a new authorization, and if successful, proceed with the ca

246 The capture or credit is not voidable because the capture or credit information has asubmitted to your processor. Or, you requested a void for a type of transaction that voided. This reason code applies only if you are processing a void through the API.the API for Voids” on page 63 for information about voids.






Business Center S

247

250

520

Reason Code

100

101

102

150

151

Reason Code

Reason Codes for Electronic Check ServicesTable 10 lists the reason codes returned for the electronic check services.

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.


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.

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.

Table 10 Reason Codes for Electronic Check Services

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.

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.

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.

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.


Description




ccount.

e

follow-on page 69).

.

ave reviewed

152 Error: The request was received, but a service did not finish running in time.


220 The processor declined the request based on a general issue with the customer’s a

Possible action: Request a different form of payment.

221 The customer matched an entry on the processor’s negative file.

Possible action: Review the order and contact the payment processor.

222 The customer’s bank account is frozen.

Possible action: Review the order or request a different form of payment.

233 The processor declined the request based on an issue with the request itself.

Possible action: Request a different form of payment.

234 There is a problem with your CyberSource merchant configuration.

Possible action: Do not resend the request. Contact Customer Support to correct thconfiguration 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 credits only (see Appendix D, “Advanced API Capabilities for Electronic Checks,” on

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 hthe order status in the Business Center.

Table 10 Reason Codes for Electronic Check Services



Appendix C

Advanced API Capabilities for Credit Cards

Business Center S

This appendix describes several advanced API topics:

Additional Authorization FeaturesUsing the API for Captures and CreditsUsing the API for VoidsUsing Payer Authentication

Additional Authorization FeaturesThis section describes several other credit card authorization features that you may want to use depending on your business needs.

Using a Subscription for a PaymentPerforming a Forced CaptureIndicating a Visa Bill PaymentIndicating a Recurring PaymentUsing Coupons

Using a Subscription for a PaymentIf you are using CyberSource’s Subscription Payment Services, you can process an authorization, sale, or credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database.

Simply request the service(s) you want to run and include recurringSubscriptionInfo_subscriptionID.

When you provide recurringSubscriptionInfo_subscriptionID, you must provide these other fields in the request:

• merchantID

• merchantReferenceCode

• item_0_unitPrice or purchaseTotals_grandTotalAmount to indicate the amount of the payment or credit


Additional Authorization Features

All the information stored in the subscription will be used for the payment or credit, including required information such as the customer’s name, billing address, and credit card information. Any optional information you stored in the subscription will also be used, including the shipping address and whether the transaction is part of Visa’s Bill Payment program (see “Indicating a Visa Bill Payment” on page 52). Note that you can override most of the information stored in the subscription (except the credit card number) by including the relevant API fields in the request. For example, you could provide a different billing or shipping address with the request.

For information about subscriptions, see the Business Center Subscription Payments User’s Guide.

Performing a Forced CaptureIf you are using Vital as your processor, you can perform forced captures. A forced capture occurs when you process an authorization outside the CyberSource system but capture the order by using CyberSource.

Note You can perform a forced capture in the Business Center’s Virtual Terminal. There, when you select the transaction type, select “Capture with Verbal Auth.” The Business Center automatically performs both the authorization and capture.

Follow these steps to perform a forced capture through the API:

1 After you have processed the authorization outside the CyberSource system, request a CyberSource authorization (ccAuthService) as described in “Requesting an Authorization” on page 16. As part of the request, include these fields:ccAuthService_authType=verbalccAuthService_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 PaymentCustomers 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.





Business Center S

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 PaymentDepending on the type of products or services you sell, you may want to process recurring payments for a customer. For example, you may want to charge a customer $19.95 each month to access a service that you offer.

Note A customer’s recurring payment does not have to be for the exact same amount each time.

Make sure that you disclose clearly to your customers when they purchase the product or service what the amount will be for the recurring payments. If the amount varies based on usage, make this clear.

To create a recurring payment:

1 For the first payment, send a regular request for credit card authorization.Only if the first authorization is successful should you then submit authorizations for recurring payments for that card.

2 For each subsequent recurring payment, send an authorization request with ccAuthService_commerceIndicator=recurring to indicate the payment is a recurring payment.

CyberSource supports recurring payments for the following processors:

• FDMS South: Visa, MasterCard

• FDMS Nashville: Visa, MasterCard, American Express, Discover

• Paymentech: Visa, MasterCard, American Express, Discover

• Vital: Visa, MasterCard, American Express, Discover

Note American Express and Discover have programs that you must sign up for if you want to process recurring payments. Contact American Express and Discover for details about their programs.

CyberSource also offers a recurring billing service that allows you to create a payment subscription for a customer in the CyberSource system. CyberSource then automatically bills the customer for you according to your instructions. CyberSource’s system eliminates the need for you to create your own system to regularly bill customers and to store their account information. For more information about the service, see the Business Center Subscription Payments User Guide.

AVS and Recurring Payments. The Address Verification Service is run for every authorization request that you submit. For recurring payments, you should check the AVS




Additional Authorization Features

result for the initial payment to ensure the information is accurate and to reduce the risk of fraud.

You must decide, however, how to handle the AVS results for the subsequent recurring payments. You may want to ignore the AVS results for the recurring payments, as you have already confirmed with the initial payment whether the credit card number is valid and non-fraudulent.

If you need to change the credit card number used for a series of recurring payments, treat the first authorization with the new credit card number as a non-recurring payment, and closely evaluate the AVS results. You may then flag the subsequent payments as recurring and consider ignoring the AVS results.

Replacement Expiration Date for Recurring Payments. Normally when you request a credit card authorization, you must supply a valid expiration date for the credit card. If you are processing a recurring payment and the credit card that you have on file for the customer has expired, you might still be able to request the authorization, depending on which processor you use. Instead of sending the out-of-date expiration date, you can send a replacement expiration date of month=12 and year=2021.

Important Do not use the replacement expiration date for cards that have not yet expired. Use the replacement expiration date only for recurring payments.

Using the replacement expiration date for a recurring payment does not guarantee that the authorization will be successful. The issuing bank ultimately determines if a card is authorized; some issuing banks will not accept an expiration date that does not match what they have in their database.

CyberSource supports the replacement expiration date for the following processors:

• FDMS South: Visa, MasterCard

• Paymentech: Visa, MasterCard

Using CouponsYou can offer your customers virtual coupons at your Web store. CyberSource defines a coupon as a non-taxable, fixed amount deducted from an order total.

Coupon examples you might implement include:

• Register now and get $100 off your purchase!

• Spring clearance! Get $10 off any order!

• Thank you for ordering again within 30 days! We’re taking $5 off your order!

CyberSource processes the coupon by totaling all of the line items and then deducting the amount of the coupon(s). The total coupon amount cannot be greater than the order grand



Business Center S

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.

Using the API for Captures and CreditsThe 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 CaptureTo 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 AuthorizationA 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.

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

Data Type & Length

String (50)

String (26)

String (6)

String (5)

String (6)

Important Do not confuse the verbal authorization discussed here with a forced capture. The difference is that with a verbal authorization, you get the authorization code directly from the processor or issuing bank after requesting an authorization through CyberSource and receiving a CyberSource decline. With a forced capture, you get the authorization code by performing an authorization outside of CyberSource. In both cases, you follow up with a capture that uses CyberSource’s system. For information about processing forced captures, see “Performing a Forced Capture” on page 52.

Using verbal authorization, you can request to capture an authorization that was declined for any of the following reasons:

• Verbal authorization required

• Card expired

• Card refused

• Invalid card

To capture an authorization with a verbal authorization code, send the authorization code in the ccCaptureService_verbalAuthCode request field. Also, include the word verbal in the ccCaptureService_authType field.

Note You must set the ccCaptureService_authType field to verbal or else the ccCaptureService_verbalAuthCode field will be ignored.

Capture Request FieldsTable 11 lists the fields you use to request a capture.

Table 11 Capture Request Fields



ccCaptureService_authRequestID

Value of requestID returned from the credit card authorization reply.

Required

ccCaptureService_authType

Set to verbal to indicate a verbal authorization. See “Processing a Verbal Authorization” on page 55.

Required for a verbal authorization

ccCaptureService_run Set to true to include the credit card capture service in your request.

Required

ccCaptureService_verbalAuthCode

Verbally obtained authorization code. See “Processing a Verbal Authorization” on page 55.

Required for a verbal authorization



Business Center S

comments

item_#_produ

item_#_produ

item_#_produ

item_#_quant

item_#_taxAm

item_#_unitPr

merchantDefifield1

merchantDefifield2

merchantDefifield3

merchantDefifield4

merchantID

merchantRefe

purchaseTota

Field Name

Optional comments you have about the capture. These comments will not be shown to the customer.


ctCode For descriptions for all of the item_#_ fields, see Table 1 on page 21.


ctName Optional String (30)

ctSKU Optional String (15)

ity Optional Integer (10)

ount Optional String (15)

ice Per-item price of the product. You must provide either this field or purchaseTotals_grandTotalAmount in your request. See “Using a Grand Total” on page 12 for more information.

See description

String (15)

nedData_ Open field that you can use to store any information. Do not use the field to store any sensitive customer information.

NOTE If you provided these fields with the authorization, you will see the authorization’s values in the Business Center and the Order Detail Report and not the values you provided with the capture.










renceCode 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.



Required String (5)

Table 11 Capture Request Fields (Continued)


Data Type & Length



String (15)

Data Type & Length

String (15)

Integer (5)

String (60)

String (20)

String (6)

String (100)

String (50)

String (100)

String (5)

Integer (5)

Data Type & Length

Capture Reply FieldsTable 12 lists the capture reply fields.

purchaseTotals_grandTotalAmount


See description

Table 12 Capture Reply Fields


ccCaptureReply_amount Total amount of the capture.

ccCaptureReply_reasonCode

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.

ccCaptureReply_reconciliationID


ccCaptureReply_requestDateTime

Time when capture is requested. 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.

decision Summarizes the result of the overall request. The field can contain one of the following values:• ACCEPT: The request succeeded






purchaseTotals_currency

Currency used for the order. For U.S. dollars, the value will be USD.

reasonCode Numeric value corresponding to the result of the overall request. See “Reason Codes for the Simple Order API” on page 46 for a list of possible values.

Table 11 Capture Request Fields (Continued)




Business Center S

requestID

Field Name

Requesting a CreditNormally you will process credits through the Business Center. There, you search for the original order, CyberSource retrieves the order information from the database, and then you click a button to perform the credit. This type of credit is called a follow-on credit because it references the order information stored in our database. You can also perform a follow-on credit through the API. You provide the request ID from the authorization in the ccCreditService_captureRequestID field and we use that to reference the order information from the authorization.

However, the order data is available for only 60 days after the authorization. If you need to refund a customer’s money after that period, you can request a credit in the Business Center where the data retention is 120 days or perform a stand-alone credit. It is called stand-alone because it does not rely on previous order information stored in our database. Instead, you must get from the customer their credit card number and billing address, and provide that information to CyberSource in a credit request through the API.

To request either type of credit, send a request and set the ccCreditService_run field to true. Also include all the required fields as listed in Table 13.

Using a Subscription for a CreditIf you are using CyberSource’s Subscription Payment Services, you can process a credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database. Simply provide the subscription ID in recurringSubscriptionInfo_subscriptionID. See “Using a Subscription for a Payment” on page 51 for more information about the other fields that are required.

Indicating a Credit for a Visa Bill PaymentCustomers 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).

Identifier for the request. Note that this request ID is different than the request ID you received for the authorization request.

String (26)

Table 12 Capture Reply Fields (Continued)




Data Type & Length

String (50)

String (2)

String (50)

String (255)

String (60)

String (60)

String (15)

String (10)

String (2)

String (60)

String (60)


String (2)

String (4)

Credit Request FieldsTable 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


billTo_city For descriptions for all of the billTo_ fields, see Table 1 on page 21.

Required **

billTo_country Required **


billTo_email Required **

billTo_firstName Required **

billTo_lastName Required **

billTo_phoneNumber Optional

billTo_postalCode Required for U.S. and Canada **

billTo_state Required for U.S. and Canada **

billTo_street1 Required **

billTo_street2 Optional

card_accountNumber Customer’s credit card number. Required **

card_expirationMonth Two-digit month (MM - 01 through 12, inclusive) that the credit card expires in. The leading 0 is required.

Required **

card_expirationYear Four-digit year (YYYY) that the credit card expires in.

Required **

** Optional for follow-on credits



Business Center S

ccCreditServi

ccCreditServicaptureReque

ccCreditServicommerceInd

ccCreditServi

comments

item_#_produ

item_#_produ

item_#_produ

item_#_quant

item_#_taxAm

Field Name

** Optional for fo

ce_billPayment Indicates to Visa if the credit is part of the Visa Bill Payment program. Currently supported only for Vital. Use one of the following values:• N (default): Not a bill payment

• Y: Bill payment

See “Indicating a Credit for a Visa Bill Payment” on page 59.

Optional String (1)

ce_stID

The requestID returned from a previous request for capture. Creates a follow-on credit by linking the credit to the previous capture. If you send this field, you do not need to send the customer’s name, the billing address, or the credit card information.

Required for a follow-on credit

String (26)

ce_icator

Type of transaction. Use with stand-alone credits. Certain card associations use this information when determining discount rates. This field can contain one of the following values:• internet (default): eCommerce order

placed using a Web site.

• moto: Mail order or telephone order.

• recurring: Recurring mail order or telephone transaction. See “Indicating a Recurring Payment” on page 53 for a list of processors that support this value.


ce_run Set to true to include the credit service in your request.

Required String (5)

Optional comments you have about the credit. These comments will not be shown to the customer.


ctCode For descriptions for all of the item_#_ fields, see Table 1 on page 21.


ctName Optional String (30)

ctSKU Optional String (15)

ity Optional Integer (10)

ount Optional String (15)

Table 13 Credit Request Fields (Continued)


Data Type & Length

llow-on credits



String (15)

String (64)

String (64)

String (64)

String (64)

String (30)

String (50)

String (5)

String (15)

String (26)

Data Type & Length


See description

merchantDefinedData_field1 Open field that you can use to store any information. Do not use the field to store any sensitive customer information.

NOTE If you are performing a follow-on credit and you provided these fields with the authorization, you will see the authorization’s values in the Business Center and the Order Detail Report and not the values you provided with the credit.

Optional

merchantDefinedData_field2 See the description for merchantDefinedData_field1 above.

Optional


Optional


Optional

merchantID Your CyberSource merchant ID. You received this in the registration email from CyberSource after you registered for a Business Center account.

Required

merchantReferenceCode Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See “Order Identifiers” on page 15 for more information.

Required

purchaseTotals_currency Currency used for the order. All orders must use U.S. dollars. Use USD for this field.

Required

purchaseTotals_grandTotalAmount


See description

recurringSubscriptionInfo_subscriptionID

Subscription ID). If you are using the Subscription Payment Services, you can request a credit and use a subscription ID to reference the subscription information. See “Using a Subscription for a Credit” on page 59.

Optional



** Optional for follow-on credits



Business Center S

Field Name

ccCreditReply

ccCreditReplyreasonCode

ccCreditReplyreconciliation

ccCreditReplyrequestDateTi

decision

invalidField_0

merchantRefe

missingField_

purchaseTotacurrency

reasonCode

requestID

Credit Reply FieldsTable 14 lists the credit reply fields.

Using the API for VoidsYou 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

Table 14 Credit Reply Fields


_amount Total amount of the credit. String (15)

_ 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.

Integer (5)

_ID


String (60)

_me

Time when credit is requested. 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.

String (20)




String (6)


renceCode Order reference or tracking number that you provided in the request. String (50)

0...N Required fields that were missing from the request. String (100)

ls_ Currency used for the order. For U.S. dollars, the value will be USD. String (5)

Numeric value corresponding to the result of the overall request. See “Reason Codes for the Simple Order API” on page 46 for a list of possible values.

Integer (5)

Identifier for the request. Note that this request ID is different from the ones you received for the authorization and capture requests.

String (26)


Using the API for Voids

Data Type & Length

String (30)

String (50)

String (5)

String (26)

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 FieldsTable 15 lists the fields you use to request a void.

Table 15 Void Request Fields

Field Name Description Required /Optional

merchantID Your CyberSource merchant ID. You received this in the registration email from CyberSource after you registered for a Business Center account.

Required

merchantReferenceCode Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See “Order Identifiers” on page 15 for more information.

Required

voidService_run Set to true to include the void service in your request. Required

voidService_voidRequestID

The requestID of the capture or credit you want to void.

Required



Business Center S

Reply Field

decision

invalidField_0

merchantRefe

missingField_

reasonCode

requestID

voidReply_am

voidReply_cu

voidReply_re

voidReply_requestDateT

Void Reply FieldsTable 16 lists the void reply fields.

Using Payer AuthenticationCyberSource supports Verified by VisaSM and MasterCard® SecureCode™, and JCB J/Secure™ Payer Authentication for these processors:

Table 16 Void Reply Fields

Brief Description Data Type & Length




String (6)


renceCode Order reference or tracking number that you provided in the request.

String (50)

0...N Required fields that were missing from the request. String (100)

Numeric value corresponding to the result of the overall request. See “Reason Codes for the Simple Order API” on page 46 for a list of possible values.

Integer (5)

Identifier for the request. Note that this request ID is different from the ones you received for the authorization and capture requests.

String (26)

ount Total amount of the void. String (15)

rrency Currency used for the order. For U.S. dollars, the value will be USD.

String (5)

asonCode 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.

Integer (5)

imeTime when void was requested. 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.

String (20)


Using Payer Authentication

Data Type & Length

String (40)

String (13)

• Verified by Visa: FDMS Nashville, FDMS South, Paymentech New Hampshire, and Vital

• MasterCard SecureCode: FDMS Nashville, FDMS South, and Vital

• JCB J/Secure: Vital

If you are using Payer Authentication, you have additional fields that you must supply when you request an authorization. You receive the values for these fields from the Payer Authentication services when you check a cardmember’s enrollment in the program and validate the cardmember’s authentication. For more information about Payer Authentication, see the Payer Authentication Implementation Guide.

Table 17 lists the additional fields to use with the authorization.

Table 17 Additional Authorization Fields for Payer Authentication

Field Name Description Used By (Required/Optiona)

ccAuthService_cavv Transaction identifier generated by the issuing bank for Verified by Visa and JCB J/Secure transactions. Must be 28-character base64 or 40-character hex binary.

Required for Verified by Visa transactions if ccAuthService_commerceIndicator = vbv orvbv_attempted.

Required for JCB J/Secure transactions if ccAuthService_commerceIndicator = js. Optional if ccAuthService_commerceIndicator = js_attempted.

ccAuthService


ccAuthService_commerceIndicator

Type of transaction. Use one of these values for transactions that use Payer Authentication:• js: Successful JCB J/Secure

transaction. Supported for Vital. If selected, then ccAuthService_cavv and ccAuthService_xid are required.

• js_attempted: JCB J/Secure transaction was attempted but not authenticated. Supported for Vital. If selected, then ccAuthService_cavv and ccAuthService_xid are optional.

ccAuthService (required for all Payer Authentication transactions)


http://apps.cybersource.com/library/documentation/dev_guides/Payer_Authentication_IG/html/


Business Center S

ccAuthServic

ucaf_authent

Field Name

• 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.

e_xid Transaction identifier value for Verified by Visa and JCB J/Secure transactions, generated during Payer Authentication. Must be 28-character base-64 or 40-character hex-binary.

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.

ccAuthService


String (40)

icationData MasterCard SecureCode UCAF authentication data.

Required for MasterCard SecureCode transactions only if ucaf_collectionIndicator = 2.

ccAuthService


String (32)

Table 17 Additional Authorization Fields for Payer Authentication (Continued)

Description Used By (Required/Optiona)

Data Type & Length


Using Payer Authentication


Data Type & Length

ucaf_collectionIndicator Indicates whether the MasterCard SecureCode UCAF data is collected. This field can contain one of the following values:• 0: UCAF collection is not supported

at your Web site.

• 1: UCAF collection is supported, but UCAF was not populated.

• 2: UCAF collection is supported, and UCAF was populated. Successful MasterCard SecureCode transaction.

Required for all MasterCard SecureCode transactions (ccAuthService_commerceIndicator = spa).

ccAuthService (required for MasterCard SecureCode transactions)

Table 17 Additional Authorization Fields for Payer Authentication (Continued)

Field Name Description Used By (Required/Optiona)


Appendix D

Advanced API Capabilities for Electronic Checks

Business Center S

This appendix describes how to use the API to perform electronic check credits and includes these sections:

Using a Subscription for a Debit or CreditProcessing Credits with the APIReason Codes

Using a Subscription for a Debit or CreditIf you are using CyberSource’s Subscription Payment Services, you can process a debit or credit that uses a subscription. We use the subscription ID to reference the subscription information in the our database.

Simply request the service you want to run and include recurringSubscriptionInfo_subscriptionID.

When you provide recurringSubscriptionInfo_subscriptionID, the only other fields you must provide in the request are:

• merchantID

• merchantReferenceCode

• item_0_unitPrice or purchaseTotals_grandTotalAmount to indicate the amount of the debit or credit

All the information stored in the subscription will be used for the debit or credit, including required information such as the customer’s name, billing address, and bank account information. Any optional information you stored in the subscription will also be used, including the shipping address. Note that you can override most of the information stored in the subscription (except the bank account number) by including the relevant API fields in the request. For example, you could provide a different billing or shipping address with the request.

For information about subscriptions, see the Business Center Subscription Payments User’s Guide.




Processing Credits with the API

Processing Credits with the APIThe chapter in this guide on processing electronic checks says to use the Business Center to perform electronic check credits. You can, however, perform credits through the API. In general, you would use the API if you want to request credits programmatically instead of through the Business Center. Whether you do this depends on the volume of orders you have and how you have structured your fulfillment system.

When you process credits through the Business Center, you search for the original order, we retrieve the order information from our database, and then you click a button to perform the credit. Or, you can bypass searching for the original debit and just perform a plain credit. In this case you have to provide all of the customer’s billing and account information, and any other information the processor requires. These two methods are called follow-on or stand-alone credits. You can process both types of credits through the API.

Follow-On CreditsThis 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 CreditsWith a stand-alone credit, you do not provide the request ID from the previous debit, and you have no limit on the timing of the credit. You must provide CyberSource the customer’s name, billing address, and bank account information in the credit request (see Table 18 on page 71).

For TeleCheck, you must also provide the request field ecCreditService_referenceNumber with the value that you received in the ecDebitReply_reconciliationID reply field. TeleCheck uses this value to associate the credit with the associated debit.

Reconciliation IDIn 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.



Business Center S

Field Name

billTo_city

billTo_country

billTo_custom

billTo_dateOfB

billTo_email

billTo_firstNam

billTo_lastNam

billTo_phoneN

billTo_postalC

billTo_state

billTo_street1

billTo_street2

check_accoun

check_accoun

** Field not need

Payment Events ReportThe Payment Events Report shows when your credit is processed. For more information about the Payment Events Report, see the Business Center Reporting User’s Guide.

Credit Request FieldsTable 18 lists the fields you use to request an electronic check credit.Table 18 Credit Request Fields


Data Type & Length

For descriptions for all of the billTo_ fields, see Table 3 on page 32.

Required ** String (50)


erID Your identifier for the customer. Optional String (50)

irth NOTE If you use AmeriNet, check with them to see if they require you to provide this field.

Used by AmeriNet only **

String (10)


e Required ** String (60)

e Required ** String (60)

umber Required ** String (15)

ode Required ** String (10)



Optional ** String (60)

tNumber Checking account number. Required ** String with numbers only (17)

tType Checking account type. This field can contain one of the following values:• C: Checking

• S: Savings

• X: Corporate checking


ed if performing a follow-on credit (which requires ecCreditService_debitRequestID)






String (255)

String (26)

String (60)

String (5)

String (30)

String (30)

String (15)

Integer (10)

String (15)

String (15)

Data Type & Length

check_bankTransitNumber Bank routing number (also known as the “transit number”).

Required **

check_checkNumber Check number.

Note If you use AmeriNet, check with them to see if they require you to provide this field.

Used by AmeriNet only **


comments Optional comments you have about the credit. These comments will not be shown to the customer.

Optional

ecCreditService_debitRequestID

The requestID from the previous debit. Creates a follow-on credit by linking the credit to the previous debit. For a follow-on credit, you do not need to send the customer’s name, the billing address, or the bank account information.

Required only for a follow-on credit (see “Follow-On Credits” on page 70)

ecCreditService_referenceNumber

For stand-alone credits with TeleCheck, set this field to the value that you received in the ecDebitReply_reconciliationID field in the associated debit’s reply. See “Stand-Alone Credits” on page 70 for more information.

For TeleCheck, The maximum length is 25.

Required for CyberSource stand-alone credits with TeleCheck

ecCreditService_run Set to true to include the credit service in your request.

Required

item_#_productCode For descriptions of the item_#_ fields, see Table 3 on page 32.

Optional

item_#_productName Optional

item_#_productSKU Optional

item_#_quantity Optional

item_#_taxAmount Optional


See description



** Field not needed if performing a follow-on credit (which requires ecCreditService_debitRequestID)



Business Center S

merchantDefi

merchantDefi

merchantDefi

merchantDefi

merchantID

merchantRefe

purchaseTota


recurringSubssubscriptionID

Field Name

** Field not need

nedData_field1 Open field that you can use to store any information.

NOTE If you are performing a follow-on credit and you provided these fields with the debit, you will see the debit’s values in the Business Center and the Order Detail Report and not the values you provided with the credit.


nedData_field2 See the description for merchantDefinedData_field1 above.








renceCode Merchant-generated order reference or tracking number. Use the same value that you used for the authorization and capture. See “Order Identifiers” on page 15 for more information.



Required String (5)

ls_ount



criptionInfo_ 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.




Data Type & Length

ed if performing a follow-on credit (which requires ecCreditService_debitRequestID)



Data Type & Length

Integer (5)

String (6)

String (15)

String (6)

String (87)

Integer (5)

String (60)

String (20)

String (1)

String (100)

String (50)

String (100)

String (5)

Integer (5)

Credit Reply FieldsTable 19 lists the electronic check credit reply fields.Table 19 Credit Reply Fields


ccCreditReply_reasonCode

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.

decision Summarizes the result of the overall request. The field can contain one of the following values:• ACCEPT: The request succeeded



ecCreditReply_amount Total amount of the credit.

ecCreditReply_processorResponse

Result code returned by the payment processor.

ecCreditReply_processorTransactionID

Transaction identifier or tracking ID returned by AmeriNet.

ecCreditReply_reasonCode

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.

ecCreditReply_reconciliationID


ecCreditReply_requestDateTime

Time when credit is requested. 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.

ecCreditReply_settlementMethod

Method used to settle the credit. This field will contain B to indicate best possible method (best of either ACH or facsimile).





reasonCode Numeric value corresponding to the result of the overall request. See “Reason Codes for Electronic Check Services” on page 49 for a list of possible values.



Business Center S

requestID

Field Name

Reason CodesYou 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:

Identifier for the request. Note that this request ID is different from the one you received for the debit request.

String (26)

Table 20 Additional Reason Code for Credits


241 The request ID is invalid for the follow-on request. This reason code is returned for follow-on credits only.

Possible action: Verify the request ID is valid and resend the request.

Table 19 Credit Reply Fields (Continued)



Reason Codes


Appendix E

Using the XML API

Business Center S

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 ClientAbout the XML APICorrelating Fields NamesRequesting Credit Card AuthorizationNumbering ItemsExample Request and Reply

Downloading a ClientIf 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 APITo 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



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 RequestsThe schema for the XML API is located athttps://ics2ws.ic3.com/commerce/1.x/transactionProcessor.

In general, the schema’s structure is separated into a request message and a reply message. Inside the request message are elements for the basic invoice information, tender information, and then service-specific information. The element that contains the service-specific information for a credit card authorization is <ccAuthService>.

To indicate in the request that you want to run a service, set the run attribute for the service’s element to "true". For example, to request credit card authorization, set the run attribute for the <ccAuthService> element to "true".

You can send either live or test transactions. For live transactions, you send your request to 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 RepliesThe 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 NamesThe main chapters of this guide discuss using the Simple Order API, which uses name-value 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.


https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Appendix E Using the XML API

Business Center S

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.

The same convention is used for reply fields.

Requesting Credit Card AuthorizationTo indicate in the request that you want to run credit card authorization, set the run attribute for the <ccAuthService> element to "true".

Numbering ItemsThe XML schema includes an <item> element that you use to describe a single item that the customer is purchasing. If the customer’s order contains more than one item, you number the items, starting with 0.

The XML schema uses an id attribute in the item’s opening tag to indicate the number. For example: <item id="0">

In the Simple Order API field names, this is represented as item_0. Note that in this situation, the underscore before the number does not indicate hierarchy in the XML schema. The item fields are generically referred to as item_#_<element name> in the documentation.

Table 22 shows an example of the numbered <item> element and the corresponding Simple API field names.

Table 21 Example of Schema Names and Simple Order API Names

Schema Names Corresponding Simple Order API Names

<card>

<accountNumber>

<expirationMonth>

<expirationYear>

</card>

card_accountNumbercard_expirationMonthcard_expirationYear

Table 22 Numbered Items


<item id="0">

<unitPrice>

<quantity>

</item>

item_0_unitPriceitem_0_quantity



Example Request and ReplyRequest:

<item id="1">

<unitPrice>

<quantity></item>

item_1_unitPriceitem_1_quantity

<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>[email protected]</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>

Table 22 Numbered Items



Appendix E Using the XML API

Business Center S

<c:

</c

ReplyFor 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.

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>

:replyMessage>


Index

Business Center S

Symbols$0 authorization 6

AACCEPT decision 13American Express 4, 5authorizations

and subscriptions 51described 2for $0 6reply fields 26request fields 21requesting 16

AVSand recurring payments 53API for 17codes 43described 4

Bbill payment 52, 59

Ccapture with verbal auth 52captures

described 2in Business Center 19reply fields 58request fields 56through API 55

card verification numberAPI for 18

described 5changes to document viicheck authorization consent 29checks. See electronic checksclients 9Concord EFS 4consent statement 29coupons 31, 54credits

and subscriptions 59in Business Center 19through API 59

Ddecisions 13declines 6Diners Club 3, 4Discover 4, 5

Eelectronic checks 29

and subscriptions 69corporate checks 30credits through API 70example request and reply 39payments 29refunds in Business Center 31

ERROR decision 13errors, described 13examples

replies 14request 12


F – U

FFDMS Nashville 4, 5, 53FDMS South 4, 5, 6, 53, 54forced capture 52fraud 4freight charges 11

Ggoing live 21grand total amount 12

HHosted Order Page 1

Iinvalid fields 14items

described 11numbering in XML API 79

JJCB J/Secure 65

MMasterCard 3, 4, 5MasterCard SecureCode 65missing fields 14

Nnumbered items in XML API 79

Oorder identifiers 15order number 15

Ppayer authentication 65Payment Events Report 31Paymentech 4, 5, 53, 54product codes 41

Rreason codes 49

described 14reconciliation ID 15reconciling orders 20recurring payments 53refunds

in Business Center 19through API 59

REJECT decision 13replies

described 10example 14

request ID 15requests

described 10example 12

returned check fees table 29

Ssale, processing through the API 16shipping and handling 11Smart Authorization

API for 18described 5result codes 45settings 4

special characters in fields 11SSL 1, 9state returned check fees table 29subscription ID

credit cards 51, 59, 62electronic checks 69, 73

syntax of fields 11

Ttax 11testing 20

UUSA PATRIOT Act compliance 6


Index

Business Center S

Vverbal authorization 55Verified by Visa 65Virtual Terminal 1Visa 4, 43, 52, 59, 65Vital 4, 5, 6, 53voids 63

WWeb Services API 10

XXML API 1, 77

Zzero-dollar authorization 6


Z – Z


cybersource (1)

Documents