This section explains how to request CyberSource services by using name-value pairs.
Requesting CyberSource Services
To request CyberSource services, write code that:
nCollects information for the CyberSource services that you will use
nAssembles the order information into requests
nSends the requests to the CyberSource server
nProcesses the reply information
|
|
The CyberSource servers do not support persistent HTTP connections. |
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 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\nvp directory. |
Creating a New Visual Studio .NET Project
To get started, create a new project in Visual Studio .NET, and add a reference to the client library, CyberSource.Clients.dll, which is located in the client’s lib directory.
In the code for your application, add the following import statements:
|
using CyberSource.Clients; using System; using System.Collections; using System.Net; using System.Security.Cryptography; using System.ServiceModel; using System.ServiceMode1.Security; |
You next create a hashtable that holds the request fields:
|
Hashtable request = new Hashtable(); |
You next optionally add your CyberSource merchant ID to the request:
|
request.Add( "merchantID", "infodev" ); |
This value overrides any value you set with the merchantID configuration setting (see Table 17 , 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 adding a field to the request. For example, to request a credit card authorization:
|
request.Add( "ccAuthService_run", "true" ); |
You can request multiple services by adding additional fields to the request. For example, if you fulfill the order immediately, you can request a credit card authorization and capture together (also referred to as a “sale”):
|
request.Add( "ccAuthService_run", "true" ); request.Add( "ccCaptureService_run", "true" ); |
Adding Service-Specific Fields to the Request
You next add the fields that are used by the services you are requesting. If you request multiple services and they share common fields, you must add the field once only.
|
request.Add( "billTo_firstName", "Jane" ); request.Add( "billTo_lastName", "Smith" ); request.Add( "card_accountNumber", "4111111111111111" ); request.Add( "item_0_unitPrice", "29.95" ); |
The previous example shows only a partial list of the fields you must send. Refer to Requesting CyberSource Services, for information about the guides that list all of the fields for the services that you are requesting.
You next send the request to CyberSource, store the reply in a new hash table, and catch several exceptions that you might receive:
|
try { Hashtable reply = NVPClient.RunTransaction( request ); SaveOrderState(); // Using the Decision and Reason Code describes the ProcessReply // method. ProcessReply( reply ); } catch (CryptographicException ce) { SaveOrderState(); Console.WriteLine( ce.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 name-value pair 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 name-value pair client shows you how to do this.
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 CyberSource 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:
ndecision: A one-word description of the results of your request. The decision is one of the following:
lACCEPT if the request succeeded
lREJECT if one or more of the services in the request was declined
lREVIEW if you use CyberSource Decision Manager and it flags the order for review. See For CyberSource Advanced Merchants: Handling Decision Manager Reviews, for more information.
lERROR if there was a system error. See Retrying When System Errors Occur, for important information about handling retries in the case of 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.
|
|
CyberSource reserves 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( Hashtable reply ) { string template = GetTemplate( ((string)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( Hashtable 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( (string) 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( Hashtable reply, string fieldName ) { System.Text.StringBuilder sb = new System.Text.StringBuilder(); string val = ""; for (int i = 0; val != null; ++i) { val = (string) reply[fieldName + "_" + i]; if (val != null) { sb.Append( val + "\n" ); } } return( sb.ToString() ); } |
For CyberSource Advanced Merchants: Handling Decision Manager Reviews
The information in this section applies only to CyberSource Advanced merchants.
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.
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:
|
request.put( "businessRules_ignoreAVSResult", "true" ); |
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, CyberSource recommends that you do not design your system to retry sending a transaction many times in the case of a system error.
Instead, CyberSource recommends 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, it is possible that the error is actually being caused by a processor rejection and not a CyberSource system error. In that case, CyberSource suggest that you either:
nSearch for the transaction in the Business 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 they are rejecting the transaction.
nContact CyberSource Customer Support to confirm whether your error is truly caused by a CyberSource system issue.
If TSYS Acquiring Solutions is your processor, you may want to follow the first suggestion as there are several common TSYS Acquiring Solutions processor responses that are returned to you as system errors and that only TSYS Acquiring Solutions can address.
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 following information:
nThe directory that contains your security key
nThe 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.