FILTER BY TAG

C/C++ API for the Client

CybsMap Structure

CybsMap is the structure that contains your configuration settings, your request, and the reply. You use the functions described in the next section to manipulate the structure, which includes adding the configuration settings, adding either name-value pairs or an XML document for the request, sending the request, and retrieving the corresponding reply.

Available Functions

The client API includes the functions described in the following sections.

cybs_load_config()

cybs_load_config()
Syntax
CybsMap *cybs_load_config( const char *szFilename )
Description
Creates an empty CybsMap structure and loads the configuration settings into the structure from a file. If you include a configuration property in the file more than once, the behavior is undefined. The
add behavior
setting (see cybs_set_add_behavior()) of the returned map is set to 2 (overwrite). This allows you to use the cybs_add() function (cybs_add()) to immediately override any settings that were read from the configuration file.
You must later free the returned pointer by using cybs_destroy_map() (see cybs_destroy_map(),).
Returns
Returns a pointer to the CybsMap structure containing the configuration settings.
Parameters
szFilename
: Name of the configuration file with the full or relative path.

cybs_create_map()

cybs_create_map()
Syntax
CybsMap *cybs_create_map()
Description
Creates an empty CybsMap structure with the add behavior set to CYBS_NO_CHECK.
You must later free the returned pointer by using cybs_destroy_map() (see cybs_destroy_map()).
Returns
Returns a pointer to the new empty CybsMap structure.
Parameters
None.

cybs_destroy_map()

cybs_destroy_map()
Syntax
void cybs_destroy_map( CybsMap *pMap )
Description
Destroys a CybsMap structure created with either cybs_create_map() or cybs_load_config().
Returns
Returns nothing.
Parameters
pMap
: The CybsMap structure to be destroyed.

cybs_set_add_behavior()

cybs_set_add_behavior()
Syntax
CybsAddBehavior cybs_set_add_behavior(
CybsMap *pRequest, CybsAddBehavior add_behavior )
Description
Sets the type of add behavior that will be used when you add name-value pairs to the specified message structure:
  • 0: When you add a new name-value pair, the client does not check to see if the name-value pair already exists in the structure. If the name already exists, the client still adds the name-value pair to the structure. This is the default value for cybs_create_map().
  • 1: If you try to add a name that already exists in the structure, the client keeps the existing name and value. The client does not allow you to add the same name or change the value of an existing name.
  • 2: If you try to add a name that already exists in the structure, the client overwrites the existing name’s value with the new value. This is the default value for cybs_load_config().
Returns
Returns the previous add behavior setting.
Parameters
pRequest
: The CybsMap structure in which to apply the add behavior setting.
add_behavior
: The add behavior type to assign to the structure.

cybs_add()

cybs_add()
Syntax
int cybs_add( CybsMap *pRequest, const char *szName, const char *szValue )
Description
Adds a name-value pair to the specified message structure.The function will do nothing if
pRequest
,
szName
, or
szValue
is null. With this function you can add name-value pairs for API fields or for configuration settings.
Returns
Returns
0
on success or
-1
on failure.
Parameters
pRequest
: The CybsMap structure to add the name-value pairs to.
szName
: The name to add.
szValue
: The value to add.

cybs_remove()

cybs_remove()
Syntax
void cybs_remove( CybsMap *pRequest, const char *szName )
Description
Uses the specified name to remove the name-value pair from the structure.
Returns
Returns nothing. Simply returns if the name does not exist.
Parameters
pRequest
: The CybsMap structure to be used.
szName
: The name of the value to remove.

cybs_get()

cybs_get()
Syntax
const char *cybs_get( CybsMap *pMap, const char *szName )
Description
Gets the value corresponding to the specified name. Note that this pointer is owned by the client and you should not free it.
Returns
Returns a pointer to the value or null if the name does not exist.
Parameters
pMap
: The CybsMap structure to be used.
szName
: The name to use.

cybs_get_first()

cybs_get_first()
Syntax
void cybs_get_first( CybsMap *pMap, const char **pszName, const char **pszValue )
Description
Returns a pointer to the first name and to its value in the map. Note that the entries in the map are not sorted in any way. If the map contains no entries,
*pszName
and
*pszValue
are null. It is sufficient just to check
*pszName
. Note that the pointers
*pszName
and
*pszValue
are owned by the client; you should not free them.
Use cybs_get_next() to get the subsequent entries (see cybs_get_next()).
Returns
Returns nothing.
Parameters
pMap
: The CybsMap structure to use.
*pszName
: Pointer to the first name in the map.
*pszValue
: Pointer to the value of the first name in the map.

cybs_get_next()

cybs_get_next()
Syntax
void cybs_get_next( CybsMap *pMap, const char **pszName, const char **pszValue )
Description
Returns a pointer to the next name and to its value in the map. Note that the entries in the map are not sorted in any way. You may use this function only after using cybs_get_first() with the same CybsMap structure.
If the map contains no more entries, then
*pszName
and
*pszValue
would be null. It is sufficient just to check
*pszName
.
Note that the pointers
*pszName
and
*pszValue
are owned by the client; you should not free them.
The function’s behavior is undefined if you update the map (for example, if you add a new entry) between calls to cybs_get_first() and cybs_get_next().
Returns
Returns nothing.
Parameters
pMap
: The CybsMap structure to use.
*pszName
: Pointer to the first name in the map.
*pszValue
: Pointer to the value of the first name in the map.

cybs_get_count()

cybs_get_count()
Syntax
int cybs_get_count( CybsMap *pMap )
Description
Returns the number of name-value pairs in the specified message structure.
Returns
Returns the number of name-value pairs.
Parameters
pMap
: The CybsMap structure to use.

cybs_create_map_string()

cybs_create_map_string()
Syntax
char *cybs_create_map_string( CybsMap *pMap )
Description
Creates a string containing all of the name-value pairs in the structure separated by the newline character sequence that is appropriate to the operating system. If the structure is empty, the function returns an empty string. On failure, the function returns null.
You must later free the returned pointer using cybs_destroy_map_string() (see below).
Returns
Returns a pointer to the string containing the name-value pairs.
Parameters
pMap
: The CybsMap structure to use.

cybs_destroy_map_string()

cybs_destroy_map_string()
Syntax
void cybs_destroy_map_string( char *szMapString )
Description
Destroys a string created with cybs_create_map_string().
Returns
Returns nothing.
Parameters
szMapString
: The map string to destroy.

cybs_run_transaction()

cybs_run_transaction()
Syntax
CybsStatus cybs_run_transaction( CybsMap *pConfig, CybsMap *pRequest, CybsMap **ppReply )
Description
Sends the request to the
Cybersource
server and receives the reply.
Returns
A value that indicates the status of the request (see Possible Status Values for a list of values).
Parameters
pconfig
: Pointer to the configuration map structure to use.
pRequest
: Pointer to a map structure containing one of these:
  • The individual name-value pairs in the request (for name-value pair users)
  • A single key called
    _xml_document
    whose value is the XML document representing the request (for XML users)
ppReply
: Pointer to a pointer to a map structure containing one of these:
  • The individual name-value pairs in the reply (for name-value pair users)
  • A single key called
    _xml_document
    whose value is the XML document representing the reply (for XML users)
  • If an error occurs, a combination of these keys and their values:
      _error_info
      _raw_reply
      _fault_document
      _fault_code
      _fault_string
      _fault_request_id
    See below for descriptions of these keys.
    You must later free the
    *ppReply
    pointer with cybs_destroy_map() (see cybs_destroy_map()).

Reply Key Descriptions

  • _error_info
    : Information about the error that occurred
  • _raw_reply
    : The server’s raw reply
  • _fault_document
    : The entire, unparsed fault document
  • _fault_code
    : The fault code, which indicates where the fault originated
  • _fault_string
    : The fault string, which describes the fault.
  • _fault_request_id
    : The request ID for the request.

Possible Return Status Values

The cybs_run_transaction() function returns a status indicating the result of the request. Table 16 describes the possible status values, including whether the error is critical. If an error occurs after the request has been sent to the server, but the client cannot determine whether the transaction was successful, then the error is considered critical. If a critical error happens, the transaction may be complete in the Cybersource system but not complete in your order system. The descriptions below indicate how to handle critical errors.
The sample code (when run from a command prompt) displays a numeric value for the return status, which is listed in the first column.
Possible Status Values
Numeric Value (for Sample Code)
Value
Description
0
CYBS_S_OK
Critical:
No
Result:
The client successfully received a reply.
Keys in **ppReply:
For name-value pair users, **
ppReply
has the reply name-value pairs for the services that you requested.
For XML users, **
ppReply
contains the
_xml_document
key, with the response in XML format.
Manual action to take:
None
1
CYBS_S_PRE_SEND_ERROR
Critical:
No
Result:
An error occurred before the request could be sent. This usually indicates a configuration problem with the client.
Keys in **ppReply:
_error_info
Manual action to take:
Fix the problem described in the error information.
2
CYBS_S_SEND_ERROR
Critical:
No
Result:
An error occurred while sending the request.
Keys in **ppReply:
_error_info
Manual action to take:
None
A typical send error that you might receive when testing occurs if the
ca-bundle.crt
file is not located in the same directory as your security key. See the description of the sslCertFile configuration parameter in Configuration Settings for information about how to fix the problem.
3
CYBS_S_RECEIVE_ERROR
Critical:
Yes
Result:
An error occurred while waiting for or retrieving the reply.
Keys in **ppReply:
_error_info
_raw_reply
Manual action to take:
Check the Transaction Search page in the
Business Center
to verify that the request was processed, and if so, whether it succeeded. Update your transaction database appropriately.
4
CYBS_S_POST_RECEIVE_ERROR
Critical:
Yes
Result:
The client received a reply or a fault, but an error occurred while processing it.
Keys in **ppReply:
_error_info
_raw_reply
Manual action to take:
Examine the value of
_raw_reply
. If you cannot determine the status of the request, then check the Transaction Search pages in the
Business Center
to verify that the request was processed, and if so, whether it succeeded. Update your transaction database appropriately.
5
CYBS_S_CRITICAL_SERVER_FAULT
Critical:
Yes
Result:
The server returned a fault with
_fault_code
set to CriticalServerError.
Keys in **ppReply:
_error_info
_fault_document
_fault_code
_fault_string
_fault_request_id
Manual action to take:
Check the Transaction Search pages in the
Business Center
to verify that the request succeeded. When searching for the request, use the request ID provided by
_fault_request_id
.
6
CYBS_S_SERVER_FAULT
Critical:
No
Result:
The server returned a fault with _fault_code set to ServerError, indicating a problem with the
Cybersource
server.
Keys in **ppReply:
_error_info
_fault_document
_fault_code
_fault_string
Manual action to take:
None
7
CYBS_S_OTHER_FAULT
Critical:
No
Result:
The server returned a fault with _fault_code set to a value other than ServerError or CriticalServerError. Indicates a possible problem with merchant status or the security key. Could also indicate that the message was tampered with after it was signed and before it reached the
Cybersource
server.
Keys in **ppReply:
_error_info
_fault_document
_fault_code
_fault_string
Manual action to take:
Examine the value of the
_fault_string
and fix the problem. You might need to generate a new security key, or you might need to contact Customer Support if there are problems with your merchant status. For more information, see ).
A typical error that you might receive occurs if your merchant ID is configured for “test” mode but you send transactions to the production server. See the description of the sendToProduction configuration parameter in Configuration Settings for information about fixing the problem.
8
CYBS_S_HTTP_ERROR
Critical:
No
Result:
The server returned an HTTP status code other than 200 (OK) or 504 (gateway timeout). Note that if a 504 gateway timeout occurs, then the status=
3
.
Keys in **ppReply:
_error_info
_raw_reply
(contains the HTTP response body, or if none was returned, the literal
"(no response available)")
.
Manual action to take:
None.
The figure below summarizes the reply information you receive for each status value.