On This Page
Using Name-Value Pairs
This section explains how to write Java programs that request
Cybersource
services by using name-value pairs.Requesting Cybersource Services
Cybersource
ServicesTo request
Cybersource
services, write code that can perform these
actions:- Collect information for theCybersourceservices that you will use
- Assemble the order information into requests
- Send the requests to theCybersourceserverTheCybersourceservers 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 ServicesMany
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:
- ACCEPTif the request succeeded.
- REJECTif one or more of the services in the request was declined.
- REVIEW(Advanced package only) if you useDecision Manager, and the order is marked for review. For more information, see Handling Decision Manager Reviews (Cybersource Advanced Services Only).
- ERRORif a system error occurred. For more information, see Handling System Errors.
- 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)
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 theREVIEWresponse like aREJECTresponse. 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 toACCEPTin 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 toACCEPTin your system, request a new authorization for the order. When processing this new authorization, you must disableDecision Manager. Otherwise the order will be marked for review again. For details about the API field that disablesDecision 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 theBusiness 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 isTSYS Acquiring Solutions, you may want to follow this option because this processor can return several system errors that only it can address.
- ContactCybersourceCustomer Support to determine whether the error is caused by aCybersourcesystem issue.
Online Transactions
For online transactions, inform the customer that an error occurred and request that the customer attempts to resubmit the order.