This section explains how to use the client 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 use C/C++ to request CyberSource services. For a list of API fields to use in your requests, see Related Documents.
The code in this section's example is incomplete. For a complete sample program, see the authCaptureSample.c file in the <installation directory>/samples/nvp directory.
To use any CyberSource service, you must create and send a request that includes the required information for that service.
The example that is developed in the following sections shows basic code for requesting CyberSource services. In this example, Jane Smith is buying an item for 29.95.
First add the include statement for the cybersource.h file:
|
#include "cybersource.h" |
Loading the Configuration Settings
Next use cybs_load_config() to create a new CybsMap structure and load the configuration settings from a file:
|
const char CYBS_CONFIG_INI_FILE[] = "../cybs.ini"; pConfig = cybs_load_config( CYBS_CONFIG_INI_FILE ); |
You could instead create an empty CybsMap structure 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 using the cybs_add() function to override the settings read from the file.
Creating the Empty Request and Reply
Next use cybs_create_map() to create the request and reply:
|
pRequest = cybs_create_map(); pReply = cybs_create_map(); |
You next add the CyberSource merchant ID to the request. You can let the CyberSource C/C++ client automatically retrieve the merchant ID from the pConfig structure, or you can set it directly in the request (see below). The pRequest value overrides the pConfig value.
|
cybs_add( pRequest, "merchantID", "infodev" ); |
Adding Services to the Request Structure
You next indicate the service you want to use by adding the field to the request. For example, to request a credit card authorization:
|
cybs_add( pRequest, "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 credit card authorization and capture together (referred to as a “sale”):
|
cybs_add( pRequest, "ccAuthService_run", "true" ); cybs_add( pRequest, "ccCaptureService_run", "true" ); |
Adding Service-Specific Fields to the Request
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 must add the field once only.
|
cybs_add( pRequest, "merchantReferenceCode", "3009AF229L7W" ); cybs_add( pRequest, "billTo_firstName", "Jane" ); cybs_add( pRequest, "billTo_lastName", "Smith" ); cybs_add( pRequest, "card_accountNumber", "4111111111111111" ); cybs_add( pRequest, "item_0_unitPrice", "29.95" ); |
The example above 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.
|
status = cybs_run_transaction( pConfig, pRequest, pReply ); |
The status value is the handle returned by the cybs_run_transaction() function. 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 a different example, see the authCaptureSample.c file in the <installation directory>/samples/nvp directory:
|
if( status == CYBS_S_OK ) { // Read the value of the "decision" in pReply. decision = cybs_get( pReply, "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: reason = cybs_get( pReply, "reasonCode" ); // See Processing the Reason Codes for how to process the // reasonCode from the reply. } else { handleError( status, pRequest, pReply ); } //--------------------- void handleError( CybsStatus stat, CybsMap* preq, CybsMap* prpl ) //--------------------- { // handleError shows how to handle the different errors that can occur. const char* pstr; pstr = cybs_get( prpl, CYBS_SK_ERROR_INFO ); switch( stat ) {
|
|
// 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 _raw_reply in pReply 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 pReply. // 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 pReply. // 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 pReply. // 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 _raw_reply in pReply for the raw reply. break; default : // Unknown error } } |
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. |
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 are using 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 more information.
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. |
|
// Example of how to handle reason codes // Success if( reason == "100" ) { printf( "Request ID: %s\nAuthorizedAmount: %s\nAuthorization Code: %s\n", cybs_get(pReply, "requestID"), cybs_get(pReply, "ccAuthReply_amount"), cybs_get(pReply, "ccAuthReply_authorizationCode") ); } // Insufficient funds else if (reason == "204") { printf( "Insufficient funds in account. Please use a different card or select another form of payment." ) ; } // add other reason codes here that you must handle specifically else { // For all other reason codes, return NULL, in which case, you should display // a generic message appropriate to the decision value you received. } |
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.
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:
|
cybs_add( pRequest, "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, 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.