|
|
|
|
|
|
This chapter describes how to request ICS services using XML and includes these sections:
Retrying When System Errors Occur
Make sure that you have the guide that explains the API fields (XML elements) 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.
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 write the code that requests these services. You will need another guide, as described in Other Documentation You Need, to get a list of the API fields (XML elements) to use in your requests.
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’s ICS services. The sample code file is located in the <installation directory>/samples/nvp directory.
After examining that sample code, read this chapter to understand how to create code to process XML requests. Note that the code in this chapter’s example is incomplete. For a complete sample program, see the authSample.php file in the <installation directory>/samples/xml directory.
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://ics2ws.ic3.com/commerce/1.x/transactionProcessor
and look at the XSD file for the version of the Simple Order API you are using.
Important 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 following example shows a basic XML document for requesting ICS 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.
Add the XML declaration and the document’s root element:
|
<?xml version="1.0" encoding="utf-8"?> <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18"> </requestMessage> |
When you construct a request, you need to 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.
Note 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.
You next add the CyberSource merchant ID to the request.
Note 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"?> <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18"> <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"?> <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18"> <merchantID>infodev</merchantID> <ccAuthService run="true"/> </requestMessage> |
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"?> <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18"> <merchantID>infodev</merchantID> <ccAuthService run="true"/> <ccCaptureService run="true"/> </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"?> <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.18"> <merchantID>infodev</merchantID> <billTo> <firstName>Jane</firstName> <lastName>Smith</lastName> </billTo> <item id="0"> <unitPrice>29.95</unitPrice> </item> <card> <accountNumber>4111111111111111</accountNumber> |
|
</card> <ccAuthService run="true"/> </requestMessage> |
The example above shows only a partial list of the fields you need to send. Refer to Other Documentation You Need for information about the guide or guides that list all of the fields for the service(s) you are requesting.
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' ); |
Note 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.
|
// 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 ); |
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 ); |
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 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; } } |
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 use 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).
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.
|
// 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 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 ( '' ); } } |
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).
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:
|
<businessRules> <ignoreAVSResult>true</ignoreAVSResult> </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.
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.
|
|
|
|
|
|