FILTER BY TAG

Using Name-Value Pairs

This section explains how to write Java programs that request
Cybersource
services by using name-value pairs.

Requesting
Cybersource
Services

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.
The code in this section’s example is incomplete. For a complete sample program, see the
AuthCaptureSample.java
file in <main directory>
/samples/nvp/src/com/cybersource/sample
directory.
If you make any changes to the
AuthCaptureSample.java
sample, you must rebuild the sample before using it. Use the
compileSample
batch file or shell script provided in the
sample
directory.
If you use Java SDK 1.5 or later, replace
cybsclients14.jar
with
cybsclients15.jar
in the
compileSample
script.

Creating and Sending Requests

To use any
Cybersource
service, you must create and send a request that includes the required information for that service. The example that is developed in the following sections shows basic code for requesting a credit card authorization. In this example, Jane Smith is buying an item for 29.95.

Importing the Client Classes

Add the following import statements:
import java.util.*; 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.

Creating an Empty Request

Create a hashtable that holds the request fields:
HashMap request = new HashMap();

Adding Services to the Request

Indicate the service that you want to use by adding a field to the request, such as a credit card authorization:
request.put( "ccAuthService_run", "true" );
You can request multiple services by adding additional fields to the request. 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
For example, if you fulfill the order 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 you receive includes reply fields only for the authorization:
request.put( "ccAuthService_run", "true" ); request.put( "ccCaptureService_run", "true" );
Example: For Merchants Using
Cybersource
Advanced Services:
Requesting Multiple Services
Many
Cybersource
services include 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 AVS 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, set the
businessRules_ignoreAVSResult
field to true:
request.put( "businessRules_ignoreAVSResult", "true" );
This line tells
Cybersource
to process the capture even if the AVS 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. If you request multiple services that share fields, add the field only once.
request.put( "billTo_firstName", "Jane" ); request.put( "billTo_lastName", "Smith" ); request.put( "card_accountNumber", "4111111111111111" ); request.put( "item_0_unitPrice", "29.95" );
The example above shows only a partial list of the fields you must send. The developer guides for the service you are using contains a complete list of API request and reply fields available for that service.

Sending the Request

Send the request to
Cybersource
, store the reply in a new hashtable, and interpret the exceptions that you might receive:
try {   HashMap reply = Client.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) {   System.out.println( e.getLogString() ); } catch (ClientException e) {   System.out.println( e.getLogString() ); }
In the example above, when an exception occurs, the exception is printed to the console. Your web store should also display to the customer a message 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

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:
  • decision
    : A one-word description of the results of your request. The possible values are as follows:
  • 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 the .

Using the Decision and Reason Code Fields

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( HashMap reply )   throws ClientException {     MessageFormat template = new MessageFormat(     getTemplate( (String) reply.get( "decision" ) ) );     Object[] content = { getContent( reply ) };     /*      * 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   return( "Your order cannot be completed at this time.{0}" +           "\nPlease try again later." ); } private static String getContent( HashMap reply )   throws ClientException {   /*    * 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( (String) reply.get( "reasonCode" ) );   switch (reasonCode) {     // Success     case 100:       return( "\nRequest ID: " + (String) reply.get( "requestID" );     // Missing field or fields     case 101:       return( "\nThe following required field(s) are missing:\n" +               enumerateValues( reply, "missingField" ) );     // Invalid field or fields     case 102:       return( "\nThe following field(s) are invalid:\n" +                enumerateValues( reply, "invalidField" ) );     // 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( Map reply, String fieldName ) {   StringBuffer sb = new StringBuffer();   String key, val = "";   for (int i = 0; ; ++i) {     key = fieldName + "_" + i;     if (!reply.containsKey( key )) {       break;     }     val = (String) reply.get( key );     if (val != null) {       sb.append( val + "\n" );     }   }   return( sb.toString() ); }

Handling
Decision Manager
Reviews (
Cybersource
Advanced Services Only)

  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 .
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 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 system error or a payment processor rejection because of invalid data.

Offline Transactions

We recommend that you resend the request two or three times only, waiting a longer period of time between each attempt. Determine what is most appropriate for your business situation.
Example Handling System Errors for Offline Transactions
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 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

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