Chapter 4

Using Name-Value Pairs

This chapter explains how to use the client to request ICS services by using name-value pairs and includes these sections:

Other Necessary Documentation

Make sure that you have the guide that explains the API fields you need to use in your requests:

For merchants and resellers using the Business Center:

• Business Center Simple Order API User’s Guide: Describes the API for using the CyberSource ICS Credit Card Services and other payment services.

For merchants using the Enterprise Business Center:

• Credit Card Services Implementation Guide: Describes the API for using the CyberSource ICS Credit Card Services. Make sure when you read this guide that you read the Simple Order API chapter and NOT the SCMP API chapter.

• Implementation guides for any other ICS services you are planning to use. These are available in the documentation area of the Support Center.

Requesting ICS Services

To request CyberSource ICS services, write code that:

• Collects information for the ICS services that you will use

• Assembles the order information into requests

• Sends the requests to the CyberSource server

Important The CyberSource servers do not support persistent HTTP connections.

• Processes the reply information

The instructions in this chapter explain how to use PHP to request ICS services. You will need another guide, as described in Other Necessary Documentation, to get a list of the API fields to use in your requests.

Creating and Sending the Request

Note The code in this chapter’s example is incomplete. For a complete sample program, see the authCaptureSample.php file in the <installation directory>/samples/nvp directory, or see the sample PHP pages.

To use any ICS service, you must create and send a request that includes the required information for that service.

The following example shows the basic PHP code for requesting ICS services. In this example, Jane Smith is buying an item for $29.95.

Loading the Configuration Settings

First load the configuration settings from a file:

$config = cybs_load_config( 'cybs.ini' );

You could instead create an array and add each configuration setting separately. You could also use a combination of the two methods: You could read the settings from a file and then add new settings dynamically with the array to override the settings read from the file.

Creating an Empty Request Array

You next create an array to hold the request fields:

$request = array();

Adding the Merchant ID

You next add the CyberSource merchant ID to the request. You can let the CyberSource PHP extension automatically retrieve the merchant ID from the $config array, or you can set it directly in the $request array (see below). The $request array value overrides the $config array value.

$request['merchantID'] = 'infodev';

Adding Services to the Request Array

You next indicate the service you want to use by adding the field to the request. For example, to request a credit card authorization:

$request['ccAuthService_run'] = 'true';

Requesting a Sale

You can request multiple services by adding additional fields to the request. For example, if you fulfill the order immediately, you can request credit card authorization and capture together (referred to as a "sale"):

$request['ccAuthService_run'] = 'true';

$request['ccCaptureService_run'] = 'true';

Adding Service-Specific Fields to the Request Array

You next add the fields that are used by the services that you are requesting. If you request multiple services and they share common fields, you only need to add the field once.

$request['merchantReferenceCode'] = '3009AF229L7W';

$request['billTo_firstName'] = 'Jane';

$request['billTo_lastName'] = 'Smith';

$request['card_accountNumber'] = '4111111111111111';

$request['item_0_unitPrice'] = '29.95';

The example above shows only a partial list of the fields you need to send. Refer to Other Necessary Documentation for information about the guide or guides that list all of the fields for the service(s) you are requesting.

Sending the Request

You next create the array that will hold the reply and send the request:

$reply = array();

$status = cybs_run_transaction( $config, $request, $reply );

Interpreting the Reply

Handling the Return Status

You next handle the $status value returned by the cybs_run_transaction() method. The $status indicates whether the ICS server received the request, if the client received the reply, and if there were any errors or faults during transmission. See Possible Return Status Values for descriptions of each status value. For a different example, see the authCaptureSample.php file in the <installation directory>/samples/nvp directory.

if ($status == 0)

// Read the value of the "decision" in the $reply array.

$decision = $reply['decision'];

// If decision=ACCEPT, indicate to the customer that the request was successful.

// If decision=REJECT, indicate to the customer that the order was not approved.

// If decision=ERROR, indicate to the customer that an error occurred and to try

// again later.

// Now get reason code results:

// $strContent = getReplyContent( $reply);

// See Processing the Reason Codes for how to process the

// reasonCode from the reply.

// Note that getReplyContent() is included in this document to help you

// understand how to process reason codes, but it is not included as part of the

// sample scripts or sample PHP pages.

else

{

handleError( $status, $request, $reply );

}

//---------------------

function handleError( $status, $request, $reply )

//---------------------

// handleError() shows how to handle the different errors that can occur.

{

switch ($status)

{

// There was a problem with the parameters passed to cybs_run_transaction()

case CYBS_S_PHP_PARAM_ERROR:

// Non-critical error.

// Tell customer the order could not be completed and to try again later.

// Notify appropriate internal resources of the error.

break;

// An error occurred before the request could be sent.

case CYBS_S_PRE_SEND_ERROR:

// Non-critical error.

// Tell customer the order could not be completed and to try again later.

// Notify appropriate internal resources of the error.

break;

// An error occurred while sending the request.

case CYBS_S_SEND_ERROR:

// Non-critical error.

// Tell customer the order could not be completed and to try again later.

break;

// An error occurred while waiting for or retrieving the reply.

case CYBS_S_RECEIVE_ERROR:

// Critial error.

// Tell customer the order cannot be completed and to try again later.

// Notify appropriate internal resources of the error.

// See the sample code for more information about handling critical errors.

break;

// An error occurred after receiving and during processing of the reply.

case CYBS_S_POST_RECEIVE_ERROR:

// Critical error.

// Tell customer the order could not be completed and to try again later.

// Look at CYBS_SK_RAW_REPLY in $reply for the raw reply.

// Notify appropriate internal resources of the error.

// See the sample code for more information about handling critical errors.

break;

// CriticalServerError fault

case CYBS_S_CRITICAL_SERVER_FAULT:

// Critial error.

// Tell customer the order could not be completed and to try again later.

// Read the various fault details from the $reply.

// Notify appropriate internal resources of the fault.

// See the sample code for more information about reading fault details and

// handling a critical error.

break;

// ServerError fault

case CYBS_S_SERVER_FAULT:

// Non-critical error.

// Tell customer the order could not be completed and to try again later.

// Read the various fault details from the $reply.

// See the sample code for information about reading fault details.

break;

// Other fault

case CYBS_S_OTHER_FAULT:

// Non-critical error.

// Tell customer the order could not be completed and to try again later.

// Read the various fault details from the $reply.

// Notify appropriate internal resources of the fault.

// See the sample code for information about reading fault details.

break;

// HTTP error

Case CYBS_S_HTTP_ERROR:

// Non-critical error.

// Tell customer the order cannot be completed and to try again later.

// Look at CYBS_SK_RAW_REPLY in $reply for the raw reply.

break;

}

Processing the Reason Codes

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 customers. Instead, present an appropriate response that tells customers the result.

Important 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:

• decision: A one-word description of the results of your request. The decision is one of the following:

• ACCEPT if the request succeeded

• REJECT if one or more of the services in the request was declined

• REVIEW if you are an enterprise merchant using CyberSource Decision Manager and it flags the order for review. See Handling Reviews for more information.

• ERROR if there was a system error. See Retrying When System Errors Occur for important information about 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 will not run. The reason codes for each service are described in the Business Center Simple Order API User’s Guide (for Business Center users) or in the service’s implementation guide (for Enterprise Business Center users).

Important 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.

// Note that getReplyContent() is included in this document to help you understand

// how to process reason codes, but it is not included as part of the sample scripts

// or sample PHP pages.

//----------------

function getReplyContent( $reply )

//----------------

{

$reasonCode = $reply['reasonCode']

switch ($reasonCode)

{

// Success

case '100':

return( sprintf(

"Request ID: %s\nAuthorizedAmount: %s\nAuthorization Code: %s,

$reply['requestID'], $reply['ccAuthReply_amount'],

$reply['ccAuthReply_authorizationCode'] ) );

break;

// Insufficient funds

case '204':

return( sprintf(

"Insufficient funds in account. Please use a different card or select another
form of payment." ) );

break;

// Add other reason codes here that you need to handle specifically. For all

// other reason codes, return an empty string, in which case, you should

// display a generic message appropriate to the decision value you received.

default:

return ( '' );

}

Handling Reviews

If you use CyberSource Decision Manager, you may also receive the REVIEW value for the decision field. A REVIEW means that Decision Manager has flagged the order for review based on how you configured the Decision Manager rules.

If you have previously set up your system to use the CyberSource ICS services, and you later decide to use 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 are unable to update your system to handle the REVIEW response, CyberSource recommends that you choose one of the following options:

• Treat the REVIEW response like a REJECT response, and thus reject any orders that are flagged for review. This may be appropriate if the product you sell is a software download or access to a Web site, and you authorize and capture the credit card payment at the same time. You may also want to perform an authorization reversal for the order (if supported by your processor).

• If you approve the order after reviewing it, convert the order status to ACCEPT in your order management system. Here you can simply request credit card capture without requesting a new authorization.

• If 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. You must disable Decision Manager when processing this new authorization or the order will be flagged for review again. See the Decision Manager Developer’s Guide for details about the API field that disables Decision Manager.

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.

You may want to perform an authorization reversal for the original authorization (if supported by your processor).

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.

This following additional example applies to enterprise merchants only.

Many ICS 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['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.

Note 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 (when you successfully receive a reply and the reply’s decision=ERROR; see Processing the Reason Codes for more information about the decision). 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 endlessly retry sending a transaction in the case of a system error.

We recommend that you instead retry sending the request only two or three times, waiting a longer period of time between each successive retry. For example, after the first system error response, wait a short period of time (perhaps 30 seconds) and try sending the request again. If you receive the same error, wait a longer period of time (perhaps 1 minute) and try sending the request again. Depending on the situation, you may decide you can wait and try again after a longer period of time (perhaps 2 minutes). You should 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, we suggest that you either:

• Search for the transaction in the Enterprise Business Center or 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.

• Contact CyberSource Customer Support to confirm whether your error is truly caused by a CyberSource system issue.

If Vital is your processor, you may want to follow the first suggestion as there are several common Vital processor responses that are returned to you as system errors and that only Vital can address.