Using XML

This section describes how to request CyberSource services using XML.

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

The CyberSource servers do not support persistent HTTP connections.

nProcesses the reply information

The instructions in this section explain how to write the code that requests these services. For a list of API fields to use in your requests, see Related Documents.

Sample Code

We suggest that you examine the name-value pair sample code provided in authCaptureSample.php before implementing your code to process XML requests. The sample will give you a basic understanding of how to request CyberSource services. The sample code file is located in the <installation directory>/samples/nvp directory.

After examining that sample code, read this section to understand how to create code to process XML requests. Note that the code in this section’s example is incomplete. For a complete sample program, see the authSample.php file in the <installation directory>/samples/xml directory.

Creating a Request Document

The client allows you to create an XML request document using any application, then send the request to CyberSource. For example, if you have a customer relationship management (CRM) system that uses XML to communicate with other systems, you can use the CRM system to generate request documents.

The request document must validate against the XML schema for CyberSource transactions. To view the schema, go to
https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor
and look at the XSD file for the version of the Simple Order API you are using.

For transactions in India, go to:

https://ics2ws.in.ic3.com/commerce/1.x/transactionProcessor

Make sure that the elements in your document appear in the correct order. If they do not, your document will not validate, and your request will fail.

The example developed in the following sections shows a basic XML document for requesting CyberSource services. In this example, Jane Smith is buying an item for 29.95.

The XML document in this example is incomplete. For a complete example, see the auth.xml document in the samples/xml directory.

Creating an Empty Request

Add the XML declaration and the document’s root element:

<?xml version="1.0" encoding="utf-8"?>

</requestMessage>

When you construct a request, you must indicate the correct namespace for the elements, and the namespace must use the same API version that you specify in the configuration settings file. For example, if targetAPIVersion=1.18 in the cybs.ini file, the namespace must be urn:schemas-cybersource-com:transaction-data-1.18.

The XML document that you receive in the reply always uses a prefix of c: (for example, xmlns:c="urn:schemas-cybersource-com:transaction-data-1.18"). Make sure you use an XML parser that supports namespaces.

Adding the Merchant ID

You next add the CyberSource merchant ID to the request.

If you specify a merchant ID in the XML document, it overrides the merchant ID you specify in the configuration settings file.

<?xml version="1.0" encoding="utf-8"?>

<merchantID>infodev</merchantID>

</requestMessage>

Adding Services to the Request

You next indicate the service that you want to use by creating an element for that service in the request, then setting the element’s run attribute to true. For example, to request a credit card authorization:

<?xml version="1.0" encoding="utf-8"?>

<merchantID>infodev</merchantID>

</requestMessage>

Requesting a Sale

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

<?xml version="1.0" encoding="utf-8"?>

<merchantID>infodev</merchantID>

</requestMessage>

Adding Service-Specific Fields to the Request

You next add the fields that are used by the services you are requesting. Most fields are child elements of container elements; for example, a <card> element contains the customer’s credit card information.

<?xml version="1.0" encoding="utf-8"?>

<merchantID>infodev</merchantID>

<lastName>Smith</lastName>

</billTo>

</item>

<card>

</card>

</requestMessage>

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

Once you have created an XML document, you use PHP to send the request to CyberSource.

Loading the Configuration Settings

First load the configuration settings from a file:

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

The namespace that you specify in the XML document must use the same API version that you specify in the configuration settings file. For example, if targetAPIVersion=1.18 in the file, the namespace must be urn:schemas-cybersource-com:transaction-data-1.18. The example code below retrieves the API version from the configuration settings file and places it in the XML document.

Reading the XML Document

// Read the XML document.

// See the authSample.php script for

// the implementation of getFileContent().

$inputXML = getFileContent( "MyXMLDocument.xml" );

// Retrieve the target API version from the configuration settings

// and replace the value in the XML document.

$inputXML

= str_replace(

"_APIVERSION_", $config[CYBS_C_TARGET_API_VERSION], $inputXML );

Sending the Request

You next create the request array, add the XML document to the array, and send the request:

$request = array();

$request[CYBS_SK_XML_DOCUMENT] = $inputXML;

// send request

$reply = array();

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

Interpreting the Reply

Handling the Return Status

The $status value is the handle returned by the cybs_run_transaction() method. The $status indicates whether the CyberSource server received the request, the client received the reply, or there were any errors or faults during transmission. See Possible Return Status Values, for descriptions of each status value. For an example in addition to the following one, see the authSample.php file in the client’s <installation directory>/samples/xml directory.

if ($status == CYBS_S_OK)

// Read the value of the "decision" in the oReplyMessage.

// This code assumes you have a method called getField ()

// that retrieves the specified field from the XML document

// in $reply[CYBS_SK_XML_DOCUMENT].

$decision = getField( $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 there

// was an error 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 )

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

{

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 could not 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 could not 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.

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. If your error handler receives a reason code that it does not recognize, it should use the decision to interpret 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 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 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.

The following is an example:

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

// This code assumes you have a method called getField() that retrieves the

// specified field from the XML document in $reply[CYBS_SK_XML_DOCUMENT].

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

function getReplyContent( $reply )

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

{

$reasonCode = $reply['reasonCode']

switch ($reasonCode)

{

// Success

case '100':

return( sprintf(

"Request ID: %s\nAuthorizedAmount:

%s\nAuthorization Code: %s,

getField( $reply, 'requestID' ), getField ($reply,

'ccAuthReply/amount' ),

getField( $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 must 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 Decision Manager Reviews

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.

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 CyberSource Advanced merchants only.

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>

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, we suggest 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 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.