Using XML

This section explains how to write Java programs that request CyberSource services by using XML.

Requesting CyberSource Services

To request CyberSource services, write code that can perform these actions:

nCollect information for the CyberSource services that you will use

nAssemble the order information into requests

nSend the requests to the CyberSource server

The CyberSource servers do not support persistent HTTP connections.

nProcess the reply information

For the list of API fields that you must add to your requests and will see in the replies, use the guide that describes the service. See Related Documents.

To understand how to request CyberSource services, CyberSource recommends that you examine the name-value pair sample code provided in AuthCaptureSample.java before implementing your code to process XML requests. The sample code file is located in the <main directory>/samples/nvp/src/com/cybersource/sample directory.

The code in this section’s example is incomplete. For a complete sample program, see the AuthSample.java file in the <main directory>/samples/xml/src/com/cybersource/sample directory.

If you make changes to the AuthSample.java sample, you must rebuild the sample before using it by using the compileSample batch file or shell script provided in the xmlsample directory.

If you use Java SDK 1.5 or later, replace cybsclients14.jar with cybsclients15.jar in the compileSample script.

Creating Requests

The client enables you to create an XML request document by using any application and sending the request to CyberSource. For example, if you have a customer relationship management (CRM) application that uses XML to communicate with other applications, you can use your CRM to generate request documents.

You must validate the request document against the XML schema for CyberSource transactions. To view the schema, look at the xsd file for your version of the Simple Order API.

If the elements in your document do not appear in the correct order, your document will not be validated, and your request will fail.

The example that is developed in the following sections shows a basic XML document for requesting a credit card authorization. In this example, Jane Smith is buying an item for 29.95. The XML document in this example is incomplete. For a complete example, see the auth.xml file in the samples/xml directory.

Creating an Empty Request

Start with the XML declaration and the root element:

<?xml version="1.0" encoding="utf-8"?>

</requestMessage>

When you construct a request, indicate the namespace for the elements. The namespace must use the same API version that you specify in the configuration settings.

Example API version: targetAPIVersion=1.18

Namespace: urn:schemas-cybersource-com:transaction-data- 1.18

Adding Services to the Request

Add the services that you want to use by creating an element for that service and setting the element’s run attribute to true. This example shows a credit card authorization:

<?xml version="1.0" encoding="utf-8"?>

</requestMessage>

You can request multiple services by creating additional elements. When you request multiple services in one request, CyberSource processes the services in a specific order. If a service fails, CyberSource does not process the subsequent services in the request. You are charged only for the services that CyberSource performs.

Example For All Merchants:
Requesting Multiple Services in a Request

If you fulfill orders immediately, you can request a credit card authorization and capture together, called a sale. If the authorization service fails, CyberSource does not process the capture service. The reply that you receive contains only authorization reply fields:

<?xml version="1.0" encoding="utf-8"?>

</requestMessage>

Example Only for Merchants Using CyberSource Advanced Services:
Requesting Multiple Services in a Request

Many CyberSource services use fields that tell CyberSource to ignore the result from the first service when deciding whether to run the subsequent services. In the case of the sale, even though the issuing bank gives you an authorization code, CyberSource may decline the authorization based on the address or card verification results. Depending on your business needs, you might choose to capture these declined authorizations. To do so, in your combined authorization and capture request, you must set the businessRules_ignoreAVSResult field to true:

</businessRules>

These lines tell CyberSource to process the capture even if the address verification result causes CyberSource to decline the authorization. In this case, the reply would contain fields for the authorization and the capture.

Adding Service-Specific Fields to the Request

Add the fields that are used by the services you are requesting. Most fields are child elements of container elements. For example, a <card> element contains the customer’s credit card information. This example shows a partial list of possible fields. The developer guides for the service you are using contains a complete list of API request and reply fields for that service.

<?xml version="1.0" encoding="utf-8"?>

<lastName>Smith</lastName>

</billTo>

</item>

<card>

</card>

</requestMessage>

Sending Requests

Once you have created an XML request document, you can use Java to send the request to CyberSource.

Importing the Client Classes

Add the following import statements:

import java.io.*;

import java.util.*;

import javax.xml.parsers.*;

import org.w3c.dom.*;

import org.xml.sax.*;

import com.cybersource.ws.client.*;

Depending on your application, you might need to add more import statements.

Loading the Configuration File

Load the configuration file:

Properties props = Utility.readProperties( args );

The sample reads the configuration settings from the properties file specified in the command line. If you do not specify a file, the sample looks for the file cybs.properties in the current directory.

Sending the Request

Send the request to CyberSource, store the reply in a new Document object, and interpret the exceptions that you might receive:

try {

Document request = readRequest( props, args );

// The sample reads the files specified in the command line, or if no files are

// specified, the sample looks for cybs.properties and auth.xml in the current

// directory.

Document reply = XMLClient.runTransaction( request, props );

// Using the Decision and Reason Code Fields illustrates how you might

// design a ProcessReply() method to handle the reply.

processReply( reply );

}

catch (FaultException e)

{

e.printStackTrace();

System.out.println( e.getLogString() );

}

catch (ClientException e)

{

e.getInnerException().printStackTrace();

System.out.println( e.getLogString() );

}

In the preceding example, when an exception occurs, the exception is printed to the console. Your web store should also display a message to the customer indicating that you were unable to process the order. Using the Decision and Reason Code Fields, shows how to provide feedback to the customer.

Interpreting Replies

The XML document that you receive in the reply always uses a prefix of c:, for example: xmlns:c="urn:schemas-cybersource-com:transaction-data-1.18". Make sure you use an XML parser that supports namespaces.

After your request is processed by the CyberSource server, it sends a reply message that contains information about the services you requested. You receive fields relevant to the services that you requested and to the outcome of each service.

To use the reply information, you must integrate it into your system and any other system that uses that data. For example, you can store the reply information in a database and send it to other back office applications.

You must write an error handler to process the reply information that you receive from CyberSource. Do not show the reply information directly to customers. Instead, present an appropriate response that tells customers the result.

CyberSource may add reply fields and reason codes at any time. If your error handler receives a reason code that it does not recognize, it should use the decision to interpret the reply. Parse the reply data according to the names of the fields instead of their order in the reply.

These are the most important reply fields:

ndecision: A one-word description of the results of your request:

lACCEPT if the request succeeded.

lREJECT if one or more of the services in the request was declined.

lREVIEW (Advanced package only) if you use Decision Manager, and the order is marked for review. For more information, see Handling Decision Manager Reviews (CyberSource Advanced Merchants).

lERROR if a system error occurred. For more information, see Handling System Errors.

nreasonCode: A numeric code that provides more specific information about the results of your request.

You also receive a reason code for each service in your request. You can use these reason codes to determine whether a specific service succeeded or failed. If a service fails, other services in your request may not run. For example, if you request a credit card authorization and capture, and the authorization fails, the capture does not run. The reason codes for each service are described in the Credit Card Services User Guide for CyberSource Essentials merchants or in the service developer guide for CyberSource Advanced merchants.

Using the Decision and Reason Code

This example shows how you can use the decision and the reason code to display an appropriate message to the customer.

The processReply() method described below is not included in the sample code in the client package.

private static boolean processReply( Document reply )

throws ClientException {

// The following code allows you to use XPath with the CyberSource schema, which

// uses a non-empty default namespace.

XPathAPI xp = new XPathAPI();

Element nsNode = reply.createElement( "nsNode" );

// The version number (1.20) at the end of the namespaceURI below is an example.

// Change it to the version of the API that you are using.

nsNode.setAttribute("xmlns:cybs", "urn:schemas-cybersource-com:transaction-data
-1.20" );

Node replyMessage =

getNode( xp, reply, "cybs:replyMessage", nsNode );

String decision =

getText( xp, replyMessage, "cybs:decision", nsNode );

MessageFormat template =

new MessageFormat( getTemplate( decision ) );

Object[] content = { getContent( xp, replyMessage, nsNode ) };

* This example writes the message to the console. Choose an appropriate display

* method for your own application.

System.out.println( template.format( content ) );

}

private static String getTemplate( String decision ){

// Retrieves the text that corresponds to the decision.

if ("ACCEPT".equalsIgnoreCase( decision )) {

return( "Your order was approved.{0}" );

}

if ("REJECT".equalsIgnoreCase( decision )) {

return( "Your order was not approved.{0}" );

}

// ERROR, or unknown decision

return( "Your order cannot be completed at this time.{0}" +

"\nPlease try again later." );

}

private static String getContent(

XPathAPI xp, Node ctxNode, Node nsNode )

throws XMLClientException {

* Uses the reason code to retrieve more details to add to the template.

* The strings returned in this sample are meant to demonstrate how to retrieve

* the reply fields. Your application should display user-friendly messages.

int reasonCode = Integer.parseInt(

getText( xp, ctxNode, "cybs:reasonCode", nsNode ) );

switch (reasonCode) {

// Success

case 100:

return ( "\nRequest ID: " +

getText( xp, ctxNode, "cybs:requestID", nsNode ) );

// Missing field or fields

case 101:

return( "\nThe following required field(s) are missing:\n" +

enumerateValues( xp, ctxNode, "cybs:missingField", nsNode ) );

// Invalid field or fields

case 102:

return( "\nThe following field(s) are invalid:\n" +

enumerateValues( xp, ctxNode, "cybs:invalidField", nsNode ) );

// Insufficient funds

case 204:

return( "\nInsufficient funds in the account. Please use a " +

"different card or select another form of payment." );

// Add additional reason codes here that you must handle specifically.

default:

// For all other reason codes (for example, unrecognized reason codes, or

// codes that do not require special handling), return an empty string.

return( "" );

}

private static String enumerateValues(

XPathAPI xp, Node ctxNode, String xpath, Node nsNode )

throws TransformerException {

try {

StringBuffer sb = new StringBuffer();

NodeList list =

xp.selectNodeList( ctxNode, xpath + "/text()", nsNode );

if (list != null) {

for (int i = 0, len = list.getLength(); i < len; ++i) {

sb.append( list.item( i ).getNodeValue() + "\n" );

}

return( sb.toString() );

}

Handling Decision Manager Reviews (CyberSource Advanced Merchants)

If you use CyberSource Decision Manager, you may also receive the REVIEW value in the decision field. REVIEW means that Decision Manager has marked the order for review based on how you configured the Decision Manager rules.

If you will be using Decision Manager, you have to determine how to handle the new REVIEW value. Ideally, you will update your order management system to recognize the REVIEW response and handle it according to your business rules. If you cannot update your system to handle the REVIEW response, CyberSource recommends that you choose one of these options:

nIf you authorize and capture the credit card payment at the same time, treat the REVIEW response like a REJECT response. Rejecting any orders that are marked for review may be appropriate if your product is a software download or access to a Web site. If supported by your processor, you may also want to reverse the authorization.

nIf you approve the order after reviewing it, convert the order status to ACCEPT in your order management system. You can request the credit card capture without requesting a new authorization.

nIf you approve the order after reviewing it but cannot convert the order status to ACCEPT in your system, request a new authorization for the order. When processing this new authorization, you must disable Decision Manager. Otherwise the order will be marked for review again. For details about the API field that disables Decision Manager, see the Decision Manager Developer Guide Using the Simple Order API (PDF | HTML) or the Decision Manager Developer Guide Using the SCMP Order API (PDF | HTML).

Alternately, you can specify a custom business rule in Decision Manager so that authorizations originating from a particular internal IP address at your company are automatically accepted.

If supported by your processor, you may want to reverse the original authorization.

Handling System Errors

You must design your transaction management system to correctly handle CyberSource system errors, which occur when you successfully receive a reply, but the decision field is ERROR. For more information about the decision, see Interpreting Replies. The error may indicate a valid CyberSource system error or a payment processor rejection because of invalid data.

Offline Transactions

CyberSource recommends that you resend the request two or three times only, waiting a longer period of time between each attempt. You should determine what is most appropriate for your business situation.

Example After the first system error response, wait a short period of time, perhaps 30 seconds, before resending the request. If you receive the same error a second time, wait a longer period of time, perhaps 1 minute, before resending the request. If you receive the same error a third time, you may decide to try again after a longer period of time, perhaps 2 minutes.

If you are still receiving a system error after several attempts, the error may be caused by a processor rejection instead of a CyberSource system error. In this case, CyberSource recommends one of these options:

nFind the transaction in the Business Center. After looking at the description of the error on the transaction details page, call your processor to determine if and why the transaction was rejected. If your processor is TSYS Acquiring Solutions, you may want to follow this option because this processor can return several system errors that only it can address.

nContact CyberSource Customer Support to determine whether the error is caused by a CyberSource system issue.

Online Transactions

For online transactions, inform the customer that an error occurred and request that the customer attempts to resubmit the order.