Using XML {#ID-000011f2}
========================

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

Requesting `Cybersource` Services {#ID-000011f4}
================================================

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

* Collect information for the `Cybersource` services that you will use
* Assemble the order information into requests
* Send the requests to the `Cybersource` server The ` Cybersource ` servers do not support persistent HTTP connections.
* Process 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](/docs/cybs/en-us/client-sdk/developer/all/so/client-sdk-so/c_Related_Documents.md "").  
To understand how to request `Cybersource` services, we recommend 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 {#ID-0000121a}
================================

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](https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/ "") 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 {#ID-0000122d}
========================================

Start with the XML declaration and the root element:

```
<?xml version="1.0" encoding="utf-8"?>
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18">
</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`**

```ph codeph
Namespace: urn:schemas-cybersource-com:transaction-data-
1.18
```

Adding Services to the Request {#ID-0000123a}
=============================================

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 xmlns="urn:schemas-cybersource-com:transaction-data-
1.18">
  <ccAuthService run="true"/>
</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 xmlns="urn:schemas-cybersource-com:transaction-data-1.18">
  <ccAuthService run="true"/>
  <ccCaptureService run="true"/>
</requestMessage>
```

**Example 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>
    <ignoreAVSResult>true</ignoreAVSResult>
</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 {#ID-00001258}
============================================================

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"?>
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-
1.18">
  <billTo>
    <firstName>Jane</firstName>
    <lastName>Smith</lastName>
  </billTo>
  <item id="0">
    <unitPrice>29.95</unitPrice>
  </item>
  <card>
    <accountNumber>4111111111111111</accountNumber>
  </card>
  <ccAuthService run="true"/>
</requestMessage>
```

Sending Requests {#ID-00001273}
===============================

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

Importing the Client Classes {#ID-00001275}
===========================================

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 {#ID-0000127e}
=============================================

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 {#ID-00001283}
==================================

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](/docs/cybs/en-us/client-sdk/developer/all/so/client-sdk-so/c_Java_Client/c_Using_Name-Value_Pairs2/c_Interpreting_Replies2/Using_Decision_and_Reason_Code_Fields.md "") shows how to provide feedback to the customer.

Interpreting Replies {#ID-0000129d}
===================================

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.
We 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:

* **decision** : A one-word description of the results of your request:
  * `ACCEPT` if the request succeeded.
  * `REJECT` if one or more of the services in the request was declined.
  * `REVIEW` (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)](/docs/cybs/en-us/client-sdk/developer/all/so/client-sdk-so/c_Java_Client/c_Using_XML2/c_Interpreting_Replies3/Handling_DM_Reviews_cybs_Adv_Merchs.md "").
  * `ERROR` if a system error occurred. For more information, see [Handling System Errors](/docs/cybs/en-us/client-sdk/developer/all/so/client-sdk-so/c_Java_Client/c_Using_XML2/c_Interpreting_Replies3/c_Handling_System_Errors1.md "").
* **reasonCode**: 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 *[Reason Codes for the Simple Order API](https://developer.cybersource.com/docs/cybs/en-us/reason-codes-so/reference/all/so/reason-codes-so/reason-codes-so.md "")*.

Using the Decision and Reason Code {#ID-000012c8}
=================================================

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) {#ID-0000131e}
=====================================================================================

If you use `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, we recommend that you choose one of these options:

* If 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.
* If 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.
* If 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` User Guide](https://ebc2.cybersource.com/content/ebc/docs/cybs/en-us/html/dm-using/user/all/na/index.md "")*.

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 {#ID-0000133d}
=====================================

You must design your transaction management system to correctly handle 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](/docs/cybs/en-us/client-sdk/developer/all/so/client-sdk-so/c_Java_Client/c_Using_XML2/c_Interpreting_Replies3.md ""). The error may indicate a valid system error or a payment processor rejection because of invalid data.

Offline Transactions {#ID-00001341}
===================================

We recommend 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, we recommend one of these options:

* Find 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.
* Contact `Cybersource` Customer Support to determine whether the error is caused by a `Cybersource` system issue.

Online Transactions {#ID-0000134b}
==================================

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