On This Page
Using SOAP
This section explains how to request
Cybersource
services by using the Simple Object Access Protocol (SOAP).Requesting Cybersource Services
To request Cybersource services, write code that:
- Collects information for the Cybersource services that you will use
- Assembles the order information into requests
- Sends the requests to the Cybersource serverThe Cybersource servers do not support persistent HTTP connections.
- Processes the reply information
The instructions in this section explain how to write C# programs that request CyberSource
services. For a list of API fields to use in your requests, see Related Documents.
Creating and Sending the Request
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
Cybersource
services. In this example, Jane Smith is buying an item for
29.95.The code in this section’s examples is incomplete. For complete sample programs, see the source code in the client’s
samples\src\soap
directory.Creating a New Visual Studio .NET Project
To get started, create a new project in Visual Studio .NET. Then you must add a reference to the client library,
CyberSource.Clients.dll
(located in the client’s lib directory). You must also add references to the .NET Framework libraries System.ServiceModel.dll
and System.Security.dll
.Importing the Client Classes
In the code for your application, add the following import statements:
using System; using System.Net; using System.Security.Cryptography; using System.ServiceModel; using System.ServiceModel.Security; using CyberSource.Clients; using CyberSource.Clients.SoapWebReference;
Creating an Empty Request
You next create a RequestMessage object that holds the request fields:
RequestMessage request = new RequestMessage();
Adding the Merchant ID
You next optionally add your merchant ID to the request:
request.merchantID = "infodev";
This value overrides any value you set with the merchantID configuration setting (see Fields in the Settings File). The merchant ID is case sensitive.
Adding Services to the Request
You next indicate the service that you want to use by creating an object for that service in the request, then setting the object’s
run
property to true
. For example, to request a credit card authorization:request.ccAuthService = new CCAuthService(); request.ccAuthService.run = "true";
Requesting a Sale
You can request multiple services by creating additional objects. For example, if you fulfill the order immediately, you can request a credit card authorization and capture together (referred to as a “sale”):
request.ccAuthService = new CCAuthService(); request.ccAuthService.run = "true"; request.ccCaptureService = new CCCaptureService(); request.ccCaptureService.run = "true";
Adding Service-Specific Fields to the Request
You next add the fields that are used by the services you are requesting. Most fields are properties of additional objects; for example, a
Card
object contains the consumer’s credit card information.BillTo billTo = new BillTo(); billTo.firstName = "Jane"; billTo.lastName = "Smith"; request.billTo = billTo; Card card = new Card(); card.accountNumber = "4111111111111111"; request.card = card; // there is one item in this sample request.item = new Item[1]; Item item = new Item(); item.id = "0"; item.unitPrice = "29.95"; request.item[0] = item;
The example above shows only a partial list of the fields you must send. Refer to Related Documents for information
about the guides that list all of the fields for the services that you are
requesting.
Sending the Request
You next send the request to
Cybersource
, store the reply in a new
ReplyMessage
object, and handle several exceptions that you might
receive.try { ReplyMessage reply =SoapClient.RunTransaction( request ); SaveOrderState(); // Using the Decision and Reason Code describes the ProcessReply // method. ProcessReply( reply ); } catch (CryptographicException ce) { SaveOrderState(); Console.WriteLine( ce.ToString() ); Console.WriteLine( sbe.ToString() ); } catch (WebException we) { SaveOrderState(); /* * Some types of WebException indicate that the transaction may have been * completed by CyberSource. The sample code shows how to identify these exceptions. * If you receive such an exception, and your request included a payment service, * you should use the Cybersource transaction search screens to determine whether * the transaction was processed. */ Console.WriteLine( we.ToString() ); } private static void SaveOrderState() { /* * This is where you store the order state in your system for post-transaction * analysis. Be sure to store the consumer information, the values of the reply * fields, and the details of any exceptions that occurred. */ }
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 consumer indicating that you were unable to process the order. The sample code for the SOAP client shows you how to provide feedback to the consumer.
Also, if the transaction fails, and the request did not include any payment services, you may be able to resend the transaction. The sample code for the SOAP client shows you how to do this.
Interpreting the Reply
After the
Cybersource
server processes your request, it sends a reply
message that contains information about the services you requested. You receive different
fields depending on the services you request and 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 consumers.
Instead, present an appropriate response that tells consumers the result.Because we may add reply fields and reason codes at any time, you
should parse the reply data according to the names of the fields instead of their order in
the reply.
The most important reply fields to evaluate are the following:
- decision: A one-word description of the results of your request. The decision is one of the following:
- ACCEPTif the request succeeded
- REJECTif one or more of the services in the request was declined
- REVIEWif you useDecision Managerand it flags the order for review. See For Cybersource Advanced Merchants: Handling Decision Manager Reviews for more information.
- ERRORif there was a system error. See Retrying When System Errors Occur for important information about handling retries in the case of 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 .
We reserve the right to add new 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.
Using the Decision and Reason Code
The following example shows how you can use the decision and the reason code to
display an appropriate message to the consumer.
private static bool ProcessReply( ReplyMessage reply ) { string template = GetTemplate( reply.decision.ToUpper() ); string content = GetContent( reply ); // This example writes the message to the console. Choose an appropriate display // method for your own application. Console.WriteLine( template, content ); } private static string GetTemplate( string decision ) { // Retrieves the text that corresponds to the decision. if ("ACCEPT".Equals( decision )) { return( "The order succeeded.{0}" ); } if ("REJECT".Equals( decision )) { return( "Your order was not approved.{0}" ); } // ERROR, or an unknown decision return( "Your order could not be completed at this time.{0}" + "\nPlease try again later." ); } private static string GetContent( ReplyMessage reply ) { /* * Uses the reason code to retrieve more details to add to the template. * The messages returned in this example are meant to demonstrate how to retrieve * the reply fields. Your application should display user-friendly messages. */ int reasonCode = int.Parse( reply.reasonCode ); switch (reasonCode) { // Success case 100: return( "\nRequest ID: " + reply.requestID ); // Missing field or fields case 101: return( "\nThe following required fields are missing: " + EnumerateValues( reply.missingField ) ); // Invalid field or fields case 102: return( "\nThe following fields are invalid: " + 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 more specifically. default: // For all other reason codes, such as unrecognized reason codes or codes // that do not require special handling, return an empty string. return( String.Empty ); } } private static string EnumerateValues( string[] array ) { System.Text.StringBuilder sb = new System.Text.StringBuilder(); foreach (string val in array) { sb.Append( val + "\n" ); } return( sb.ToString() ); }
For Cybersource Advanced Merchants: Handling Decision Manager
Reviews
Cybersource
Advanced Merchants: Handling Decision Manager
ReviewsThe information in this section applies only to
Cybersource
Advanced
merchants.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.
Requesting Multiple Services
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.
For example, in the case of a sale (a credit card authorization and a capture requested together), if the authorization service fails, Cybersource will not process the capture service. The reply you receive only includes reply fields for the authorization.
Many Cybersource services include “ignore” 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 might decline the authorization based on the AVS or card verification results. Depending on your business needs, you might choose to capture these types of declined authorizations anyway. You can set the
businessRules_ignoreAVSResult
field to "true"
in your combined authorization and capture request:BusinessRules businessRules = new BusinessRules(); businessRules.ignoreAVSResult = "true"; request.businessRules = businessRules;
This tells Cybersource to continue processing the capture even if the AVS result causes Cybersource to decline the authorization. In this case you would then get reply fields for both the authorization and the capture in your reply.
You are charged only for the services that Cybersource performs.
Retrying When System Errors Occur
You must design your transaction management system to include a way to correctly handle
Cybersource
system errors. Depending on which payment processor is handling the
transaction, the error may indicate a valid Cybersource
system error, or it may indicate a
processor rejection because of some type of invalid data. In either case, we
recommend that you do not design your system to retry sending a transaction many times in
the case of a system error.Instead, we recommend that you retry sending the request only two or three times
with successively longer periods of time between each retry. For example, after the first
system error response, wait 30 seconds and then retry sending the request. If you receive
the same error a second time, wait one minute before you send the request again. Depending
on the situation, you may decide you can retry sending the request after a longer time
period. Determine what is most appropriate for your business situation.
If after several retry attempts you are still receiving a system error, the error may
actually be caused by a processor rejection, not a
Cybersource
system error. In that case,
we suggest one of these actions:- Search for the transaction in theBusiness Center(depending on which one you normally use), look at the description of the error on the Transaction Detail page, and call your processor to determine if and why the transaction was rejected.
- ContactCybersourceCustomer Support to confirm whether your error is truly caused by aCybersourcesystem issue.
If
TSYS Acquiring Solutions
is your processor, you may want to follow the first suggestion
because several common TSYS Acquiring Solutions
processor responses can be returned as
system errors, and only TSYS Acquiring Solutions
can address these errors.Creating an Application Settings File
After you finish writing code for your integration, you must create an application settings file. This file must contain at least the directory that contains your security key and the location of the Cybersource server.
See Table 17, "Fields in the Settings File for a complete list of settings. You
can use the settings files that come with the sample applications as a starting point for
your own settings file. See Configuring the Test Applications for more information.