Home > .NET Client > Using the Client

Using the Client

This section explains how to use the .NET Client with ASP.NET and other .NET applications, and how to request CyberSource services.

Using the .NET Client With ASP .NET

When you use the .NET Client with ASP .NET, you can use global.asax or web form pages.

Putting it on global.asax allows you to use the same instance for different pages. Putting it on individual web form pages allows you to have a different configuration for each page.

You can also add more than one instance of ICSClient on one page, and give each instance a different variable name. For example, you can drag two instances of ICSClient into a page and each one uses a different merchant ID.

To use the .NET client with ASP .NET:

Step 1From New Project, use the ASP .NET web application to create a new store.

Step 2From the Component section of the Toolbox, drag the ICSClient component either to global.asax or a web form page.

Step 3Copy CybsSecurity.dll from the CyberSource .NET Client installation directory to the bin directory of your ASP.NET application.

Step 4Set its properties.

See Setting Properties in ICSClient for information on setting properties for ICSClient. See Setting Dynamic Properties for information on setting the properties as dynamic properties.

Step 5Add code to the appropriate pages to send a transaction and handle the replies.

 

The CyberSource services use the SCMP API, which consists of name-value pair API fields. The name-value pair API fields you use for credit card orders are described in the Credit Card Services Using the SCMP API (PDF | HTML).

Setting Properties in ICSClient

Before you send transactions to CyberSource, configure the ICSClient’s properties. You can configure properties either programatically or in the Properties window. To change properties in the Properties windows, choose a property in the left column, then enter a value for the property in the right column. For LogLevel, the property values are provided in a drop-down menu.

The following table lists the configurable properties of ICSClient.

Setting Dynamic Properties

Settings the ICSClient’s properties as dynamic properties allows you to change selected properties of your web store without rebuilding your web application to implement the changes. You only must change their value in your store’s web.config.

To set the ICSClient properties as dynamic properties:

Step 1Right-click the ICSClient instance in the Visual Designer, and click Properties.

The Property Editor appear in the Properties window.

Step 2In the far left column of the Properties window, click Dynamic Properties to expand the available options.

The Dynamic Properties for ICSClient window appears.

Step 3Choose the properties you want to set as dynamic properties.

Step 4Click OK.

 

Using the .NET Client with Other .NET Applications

Other non-ASP .NET applications can be used for CyberSource services such as ics_bill.

To use the .NET client with other .NET applications:

Step 1In the Solution Explorer—My Store, click My Store, and then click Reference.

If the Solution Explorer is not visible, then click Solution Explorer from the View menu.

The Add Reference window appears.

Step 2On the .NET tab, click CyberSource .NET Client.

Step 3Click OK.

Step 4Copy CybsSecurity.dll from the CyberSource .NET Client installation directory to the bin\Debug and bin\Release directories of your project.

Step 5Write code to send transactions and handle the replies.

 

The CyberSource services use the SCMP API, which consists of name-value pair API fields. The name-value pair API fields you use for credit card orders are described in the Credit Card Services Using the SCMP API (PDF | HTML).

Requesting CyberSource Services

To request CyberSource services, you must write your code as follows:

nTo collect the information that is required for the CyberSource services you use. The CyberSource services use the SCMP API, which consists of name-value pair API fields. The name-value pair API fields you use for credit card orders are described in the Credit Card Services Using the SCMP API (PDF | HTML).

nTo assemble the order information into requests, send the requests to the CyberSource server, and process the replies.

Constructing and Sending Requests

To access any CyberSource service, you must create and send a request that holds the required information.

Importing the CyberSource Namespace

Add the following import statement

Creating a Request

Create an instance of ICSrequest:

Adding Services to the Request

Next, add the service that you want to use:

You can request multiple services by using commas to separate the service names. For example, you can request both credit card authorization and capture together (referred to as a “sale”) by using the following code:

Adding Request-Level Fields to a Message

Add fields to the request:

The example above shows only a partial list of the fields required for the request.

Adding Offer-Level Fields to a Message

Add the information about the individual items being purchased. An offer is a single field that contains pairs of field names and values:

Or:

Examining Field Values

You can print the names and associated values of the fields you send to CyberSource:

Sending the Request

You next send the request to CyberSource:

Examining Reply Fields

You can print the names and associated values of all the fields returned from CyberSource:

Handling Exceptions

You should handle the possible exceptions:

Handling Reply Flags and Error Messages

After the CyberSource server processes your request, the server returns a reply consisting of name-value pairs. The fields vary, depending on which services you requested and the results of the request.

To use the reply information, you must integrate it into your system and any other system that uses that data. This includes storing the data and passing it to any other services that need the information.

You must write an error handler to handle the reply flags and error messages that you receive from CyberSource. Do not show the flags or error messages directly to customers. Instead, present an appropriate response that tells customers the result.

The main reply fields to evaluate for the request are as follows:

nics_rcode — a one-digit code indicating the result of the entire request:

l1 indicates the request was successful

l0 indicates the request was declined

l-1 indicates an error occurred

nics_rflag — a one-word description of the result of the entire request:

lSOK indicates the request was successful

lA flag starting with the letter D indicates the request was declined, such as DMISSINGFIELD

lA flag starting with the letter E indicates there was an error, such as ESYSTEM

nics_rmsg — a message that explains the reply flag. Do not show this message to customers or use it to write the error handler.

You also receive similar fields for each service you request, indicating the result of the service. The names of the fields are <service>_rcode, <service>_rflag, and <service>_rmsg. For example, the service for credit card authorization (ics_auth) returns auth_rcode, auth_rflag, and auth_rmsg.

Each CyberSource service has its own list of reply flags and error responses that you must handle. For the credit card services, see the Credit Card Services Using the SCMP API (PDF | HTML) for a list of the fields.

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 does 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 ignore_avs field to "yes" in your combined authorization and capture request:

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.

Setting the Connection Limit

This section explains how to increase the number of simultaneous connections between the client and CyberSource. By default, you can create only two simultaneous connections to an HTTP server. By increasing the number of connections, you can avoid a backlog of requests during times of very high transaction volume. Microsoft recommends for the connection limit a value that is 12 times the number of CPUs. For example, if you have two CPUs, you can set the connection limit to 24. Run performance tests to identify the optimum setting for your application.

Examples

You can increase the number of connections in many ways, for example by using an application- or server-specific configuration file where you can change the setting for a single or for all hosts. The examples below describe briefly some of the methods that you can use to increase connection limits.

cybs.connectionLimit

When set to a value other than -1, the cybs.connectionLimit setting in the client increases the limit for the host where you are sending the request by executing these statements on your behalf:

<connectionManagement>

You can set the connection limit by using .NET's <connectionManagement> tag. In this example, the connection limit for CyberSource's test and production hosts is 12 while the limit for all other hosts is 2:

DefaultConnectionLimit

You can set the connection limit for all hosts to which your application is connected before a connection is made by using the following line in your start-up code:

References

For more information on these and other methods to increase the connection limits, see the Microsoft documentation Managing Connections in the .Net Framework Developer's Guide.

Timeouts and Automatic Retries

If you find that you are not receiving replies to some of your requests, you can troubleshoot the problem by adjusting how your code handles retries and timeouts.

Retries and timeouts control how long the client waits for a reply from the CyberSource server after it sends a request, and whether and when the client automatically resends the request (called a retry).

Three parameters allow you to control how retry requests and timeouts work:

nretry_enabled — indicates whether you want to send a retry request if you do not initially get a reply. Retry request is disabled by default.

nretry_start — controls how long (in seconds) you want to wait for the initial request to be sent and replied to by CyberSource. A retry request is sent if a reply is not received by the time this expires. The default value is 30.

ntimeout — controls the total amount of time (in seconds) you want to wait for a response before a timeout error is returned. The default value is 110.

How a Transaction without Automatic Retry Works

When retry is disabled, the SDK proceeds as follows:

1Encrypts and sends the initial request. The timeout count starts at 0 seconds.

2Receives a response from the CyberSource server in the allotted by the timeout parameter.

If the response does not come back from the CyberSource server in the allotted time, a timeout error is returned.

How a Transaction with Automatic Retry Works

When retry is enabled, the SDK proceeds as follows:

1Encrypts and sends the initial request. The timeout and the retry_start counts start at 0 seconds.

2Waits until retry_start has expired or returns the response if one was received, whichever comes first.

3If retry_start has expired and no response has been received, the client encrypts and sends the request again, using the same request ID as the initial request. The timeout clock continues counting.

The request and the response automatically include an additional field to indicate that this request is a retry.

4The client returns a response if one is received, or waits until the full timeout has expired. The timeout clock started counting at the time that the initial request was sent.

5If no response was received before the timeout expired, a timeout error is returned.

For example, if retry_start is set at 30 seconds, and no response has been received in that 30 seconds, then the client sends a retry request.

The client then waits for the duration of the remaining timeout time (timeout minus retry_start). For example, if timeout is set at 110 seconds, the client then waits for a length of time equal to 110 seconds minus 30 seconds. If no response is received in that 80-second interval, then a timeout error is returned.

Evaluating the Retry Reply Fields

You evaluate the success of the retry request using the ics_retry field. The field returns one of the following values:

n1 — The retry request was successful using the original data; no reprocessing was necessary.

The CyberSource server has a record of the response in its database. CyberSource does not reprocess the request and sends the original response to you.

n0 — The retry request was successful using data from reprocessing the request.

The CyberSource server has no record of the request. CyberSource reprocesses the request and sends you the response.

n-1 — The retry request was unsuccessful due to a processing error.

The CyberSource server has a record of the request, but the response is not in its database. CyberSource does not reprocess the request. Do not resend the request, because you might duplicate the transaction. Use Transaction Search in the Business Center to search for the transaction.

Setting Automatic Retry and Timeout Parameters

Enabling Automatic Retry

The retry_enabled value controls whether the client sends a retry request if no initial response is received. Retry is disabled by default. You enable retry_enabled with the following code:

where “yes” is case-insensitive.

Setting the retry_start Value

The retry_start value controls how long the client waits before sending a retry request. The default value is 30 seconds. The minimum value is 3 seconds, which is acceptable for testing, but not for running live transactions. Start with the default value of 30 seconds and lower the value to 15 seconds if appropriate. You can set the retry_start value with the following code:

Setting the timeout Value

The timeout value controls the maximum time you want to wait to send the request and receive the response. This time begins when the client sends the initial request. The default value is 110 seconds and must not be less than the minimum value of 6 seconds when retry is enabled. You can set the timeout value with the following code:

System Errors and Retries

The client’s automatic retry capability described above in Timeouts and Automatic Retries does not automatically retry in the case of system errors, only timeouts. You must design your transaction management system to include a way to correctly handle CyberSource system errors. System errors occur when you successfully receive a reply and the reply’s ics_rflag=ESYSTEM. For more information about the ics_rflag, see Handling Reply Flags and Error Messages. Depending on which payment processor is handling the transaction, the ESYSTEM error may indicate a valid CyberSource system error or a processor rejection due to invalid data. In either case, CyberSource recommends that you do not design your system to retry sending a transaction many times when an ESYSTEM error occurs.

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 recommends that you either:

nSearch for the transaction in the Business Center, 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 because 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.