Chapter 2

Processing Credit Card Orders

This chapter describes how to process a basic credit card order by using the CyberSource Simple Order API. The information in this chapter covers card-not-present transactions, such as transactions you accept through a Web store or through mail order/telephone order. 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 .

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

This chapter includes these sections:

Downloading a Client

Using the Latest API Version

Overview of API Requests and Replies

Processing a Credit Card Order

Going Live

Authorization API Fields

Downloading a Client

To use the API to process orders, the first thing you need to do is choose one of the CyberSource clients (SDKs):

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

Using the Latest API Version

CyberSource updates the Simple Order API on a regular basis to introduce new API fields and functionality. To take advantage of the full functionality of the ICS services, you should use the latest version. See the Simple Order API Release Notes for information about the changes to the API.

With each update, the API receives a new version number, such as 1.22. 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.

Important If you are using the request token functionality as described in Request Tokens and if you use the Simple Order API in XML format, you must use version 1.23 or higher of the XML schema located at http://ics2ws.ic3.com/commerce/1.x/transactionProcessor.

Overview of API Requests and Replies

In general, you process a credit card order through CyberSource like this:

1   You collect information about the order, such as the items being bought, the customer’s name and address, and the credit card information.

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

3   CyberSource processes your request and send you a response.

4   You look at the response and then tell the 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 the customer that the credit card has been denied, and possibly ask them for another form of payment.

API Requests

A request includes information about the customer, their payment method, the items they are buying, and the service you are requesting. All of the fields you use in a credit card authorization are listed in Table 2. A request for a follow-on service has special requirements that are explained in Requesting a Follow-on Service.

Using Items or a Grand Total in the Request

For some services, you must specify the amount of the transaction. You can provide either the individual products the consumer is purchasing or a grand total for the transaction.

Note If you are using CyberSource’s Decision Manager, it is recommended that you provide individual item information instead of a grand total for the order. Decision Manager can be configured to use the individual item information to assess the risk of the order and determine if the purchaser is following your business rules. For more information about Decision Manager, see the Decision Manager Developer’s Guide.

Using Items

Items are the products that the consumer purchases from you. When you send a request for a service that requires an amount, you can send item-specific information, such as the quantity of each item ordered and the unit price for each item. The items are referred to as item_0, item_1, item_2, and so on. CyberSource uses the information you provide for each item to calculate the grand total for the order.

The values for the item_#_ fields must not contain carets (^) or colons (:) because these characters are reserved for use by the ICS services.

Required Item-Level Fields

If you are using the item-level fields, which fields are required depends on the value you use for item_#_productCode. If item_#_productCode is one of the following values:

•   default

•   stored_value

•   a value related to shipping and handling

or if you omit item_#_productCode, which causes it to default to the value default, then the only required field is item_#_unitPrice. If you do not set item_#_quantity, it defaults to 1.

If you do not set item_#_productCode to one of the values in the previous list, the following fields are required:

•   item_#_unitPrice

•   item_#_quantity

•   item_#_productName

•   item_#_productSKU

The item_#_taxAmount field is always optional.

Specifying Tax

To include tax for an item, use the item_#_taxAmount field. This value is the total tax for the entire quantity of that item. In other words, the value is not multiplied by item_#_quantity. For example:

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

Specifying Freight Charges

To include a shipping and handling charge for the order, you must include an additional item with item_#_productCode set to one of the following values:

•   shipping_only

•   handling_only

•   shipping_and_handling

For example:

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

Using a Grand Total

Instead of using items, you may send a grand total for the order in the purchaseTotals_grandTotalAmount field. This field is useful if you do not have information for each item or do not care about the information for each item and simply want to use a transaction total. If you include purchaseTotals_grandTotalAmount in your request, CyberSource uses this value and does not use item-level information to calculate the transaction’s grand total. If you provide item-level information, it still appears in the Transaction Detail page in the Business Center.

Important If you include purchaseTotals_grandTotalAmount in your request, you may not include the Tax Calculation service as part of the request. For more information about the Tax Calculation service, see the Tax Calculation Implementation Guide.

Requesting a Follow-on Service

You can start using the request token immediately, or you can do so at any time during the transition period:

•   After you start using the request token, you must do so for all future follow-on requests.

•   If you cannot use the request token immediately, CyberSource will store the request token data for you and retrieve it as necessary when you send follow-on requests. However, you will need to start using the request token before the end of the transition period.

•   You can read the migration guide that describes the request token.

Some follow-on services require a request token. This document covers the following follow-on services that require a request token:

•   ccCaptureService

•   ccCreditService

•   voidService

•   ecCreditService

To use one of these services, you must retrieve and save the request token and request ID from the reply for the primary service for which you are requesting the follow-on service. For example, when you request ccAuthService, you must save the request token and request ID you receive in the reply. If you subsequently request ccCaptureService as a follow-on for the ccAuthService transaction, you must provide the saved request token and request ID in the follow-on service request.

Example Request

See the example below for what a basic request for credit card authorization looks like. It uses name-value pairs. In this example, John Doe is buying one item that costs $49.95.

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.

API Replies

The reply you receive from CyberSource gives you the results of your request. To use the reply information, you need to integrate it into your system and any other system that uses that data.

You should write an error handler to interpret the information that you get in the reply. Do not show the reply information from CyberSource directly to the customer. Instead, show an appropriate response that tells the customer the result of the order.

Important Because CyberSource may add reply fields and reason codes at any time, proceed as follows:
- You should parse the reply data according to the names of the fields instead of their order in the reply. For more information on parsing reply fields, see the documentation for your client.
- Your error handler should use the decision field to determine the result if it receives a reason code that it does not recognize.

Decisions

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

•   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, CyberSource recommends 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, which is discussed below.

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

Reason Codes

After looking at the decision field, look at the reasonCode field to determine the reason for the decision and to decide if you want to take further action.

If the decision was ERROR, the reasonCode tells you what type of error occurred.

If the decision was REJECT, the reasonCode tells you the reason for the reject and whether you can take action that might still result in a successful order. For descriptions of the reason codes for the credit card service, see Appendix E, Reason Codes for the Simple Order API.

You also receive ccAuthReply_reasonCode in the reply. If you are requesting only credit card authorization and no additional services, you can ignore this field, as its value will always be the same as the reasonCode value.

Note CyberSource reserves the right to add new reason codes at any time. If your error handler receives a reason code that it does not recognize, it should use the decision field to determine the result.

Missing and Invalid Request Fields

You are responsible for ensuring that the data that you send to CyberSource is complete (no missing fields) and correct (no invalid data). To do this, verify the data entered on your Web sites and point-of-sale applications before sending the information to CyberSource.

If you send a request with missing or invalid information, you will receive the appropriate reason code(s) and one or more reply fields, invalidField_0...N or missingField_0…N, which list the fields that you need to correct. The service(s) that you requested and the nature of the missing or invalid information will be used to determine the number and the content of the reply fields. For example, if three required fields are missing from your request, you will receive at least one and up to three reply fields named missingField_0, missingField_1, and missingField_2. You should correct these fields and resubmit the request.

Because the API behavior pertaining to these reply fields is always subject to change, do not use these fields to communicate with consumers.

Note For XML, the <missingField> and <invalidField> elements are not numbered. Instead, you receive multiple <missingField> or <invalidField> elements in the reply.

For SOAP, you receive an array of the missing fields and an array of the invalid fields.

Request Tokens

You can start using the request token immediately, or you can do so at any time during the transition period:

•   After you start using the request token, you must do so for all future follow-on requests.

•   If you cannot use the request token immediately, CyberSource will store the request token data for you and retrieve it as necessary when you send follow-on requests. However, you will need to start using the request token before the end of the transition period.

•   You can read the migration guide that describes the request token.

A request token is an identifier that CyberSource returns in the reply for all services. You need to store the contents of the request token and request ID fields that you receive in the reply because you need these values when you send a request for a follow-on service, such as:

•   ccCaptureService

•   ccCreditService

•   voidService

•   ecCreditService

Important Although the name of the request token field that you receive is the same in each reply, the content of the field is different. Therefore, you must save each request token that you receive.

Example Replies

See the example below for a basic reply showing an ACCEPT decision. After this first example is another that shows a REJECT decision. All the fields you see in these replies are described in Table 3.

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 Identifiers

Each order you process has the following identifiers:

Order Number

This is a number that you assign to each order. You send this value in the merchantReferenceCode field in the request. CyberSource recommends you use a unique number for each order as you use this value to track your order through the CyberSource system. You can later use the order number to search for an order in the Business Center.

Request ID

This is an identifier that CyberSource assigns to the request. You receive it in the reply in the requestID field. You can use the request ID to search for an order in the Business Center.

Request Token

The request token is an identifier that CyberSource assigns to the request. You receive it in the reply in the requestToken field. You need to store the data. Depending on how you process follow-on requests, you may later need to retrieve and send the data in your follow-on service requests.

Reconciliation ID

This is an identifier that the payment processor assigns to your order. You receive this in the reply in the ccAuthReply_reconciliationID field. You might use this value when you need to do research on an order. You do not need to store this value as you can retrieve it from the Business Center.

Processing a Credit Card Order

When you process a credit card payment with the API, you can choose between the following two transaction types:

•   Authorization only

•   Sale: authorization and capture in the same request

If you process only the authorization, you can do the capture later in the Business Center. See this page. Or, if your business volume warrants it, you can process your captures later through the API. See Using the API for Captures .

Requesting an Authorization

To indicate to CyberSource in your request that you want to run credit card authorization, set the ccAuthService_run field to true. Also include all the required fields listed in Table 2. See Example Request for an example authorization request.

Requesting a Sale

A sale is a bundled authorization and capture. You might use a sale instead a separate authorization and capture if there is no delay between when you take the customer’s order and when you ship the goods. A typical use for a sale is if you are selling electronic goods or a service that you can turn on immediately.

To request a sale, request both the authorization and the capture services at the same time by setting 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 in decision and reasonCode, as well as the results for the individual services in 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:

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

Using Fraud Screening Tests

These next few sections describe how to use the authorization API fields related to the fraud screening tests described in Chapter 1, Reducing Your Chances of Fraud.

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

Address Verification Service

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

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

You can get details about the AVS result in the ccAuthReply_avsCode reply field. See Appendix B, Address Verification Service Codes for descriptions of the codes that you can receive in this field.

Card Verification Number

You can request the card verification number from the customer and send it in your authorization request to help reduce the risk of fraud. See Card Verification Numbers 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 2.

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

You can get details about the CV result in the ccAuthReply_cvCode field. See Appendix C, Card Verification Number Codes for descriptions of the codes that you can receive in this field.

Smart Authorization

Smart Authorization automatically screens all of your orders to flag ones that appear risky. See Smart Authorization 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 D, Smart Authorization Factor Codes for descriptions of the codes you can receive in this field.

Using Additional Authorization Features

CyberSource also offers several other authorization features that you can use depending on your business needs:

Using a Subscription for a Payment

Performing a Forced Capture

Indicating a Bill Payment with Visa

Indicating a Recurring Payment

Using Coupons

American Express Prepaid Cards

For more information about those features, see Additional Authorization Features.

Capturing the Order

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

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

You can do this in the Business Center, which is described in this section, or through the API, which is described in Using the API for Captures . 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.

Automatic Partial Authorization Reversals

CyberSource supports automatic partial authorization reversals for the following processors and card types:

If the capture amount is less than the authorization amount, CyberSource automatically performs a partial authorization reversal when it sends the capture request to the processor. As a result of the partial authorization reversal:

•   The settlement amount matches the authorization amount.

•   The hold on the unused credit card funds is released.

Note Not all issuers act on a request for a partial authorization reversal. Therefore CyberSource cannot guarantee that the funds will be released.

The automatic partial authorization feature can be disabled for any merchant who requests it. To do so, contact CyberSource Customer Support.

Refunding the Customer’s Money

If you need to refund the customer’s money, CyberSource suggests 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 Using the API for Captures for more information.

Reconciling Your Orders

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

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

Testing Your Implementation

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

•   Use your regular CyberSource merchant ID to perform testing.

•   Use a non-existent account and domain name for the customer’s email address, such as random@example.com.

•   Make sure your client is configured to send requests to the test server: https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor. See the documentation for your client for information about how to do this.

•   Unless otherwise specified, use the following test credit card numbers without the spaces, not real credit card numbers:

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.

Going Live

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

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

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

Authorization API Fields

Request Fields

Table 2 lists the fields to use when requesting a credit card authorization.