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:
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.
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.
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.
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.
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.
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.
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. The possible values are as follows:
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 Services Only).
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 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 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.
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. 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 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.