C Functions

The CyberSource C library consists of several functions and one data type that you use to send and receive requests and replies.

ics_destroy() Function

This function clears a used ics_msg.

Table 2ics_destroy() Function
Syntax	void ics_destroy(ics_msg* msg)
Description	Frees resources used by the specified ics_msg that was created by ics_init() or by ics_send(). Destroy used ics_msgs when your program no longer needs them.
Returns	Nothing.

ics_fadd() Function

Adds a field (a name-value pair) to a request.

Table 3ics_fadd() Function
Syntax	int ics_fadd(ics_msg* msg, char* name, char* value)
Description	Adds the field name and its value to the specified request. Adding a field that is already in the request overwrites that field. You can also use ics_fremove() to remove a field before you add it again.
Returns	nThe number of fields in the request after the field is added. n-1: The field cannot be added because the number of added fields exceeds the maximum allowed number.

Example Adding a Field to a Request

qty = ics_fadd(request, "customer_firstname", "John");

ics_fcount() Function

Returns the quantity of fields in an ics_msg.

Table 4ics_fcount() Function
Syntax	int ics_fcount(ics_msg* msg)
Description	Counts the number of fields in the specified request. Then use ics_fget() and ics_fname() to iterate through all the fields in the request.
Returns	The number of fields in the specified request.

ics_fget() Function

Returns the value of the name-value pair at the position in an ics_msg specified by index.

Table 5ics_fget() Function
Syntax	char* ics_fget(ics_msg* msg, int i)
Description	Extracts the field value stored in the request at the position indicated by index. Use this to get all field values in an ics_msg by iterating from 0 to ics_fcount(msg)-1.
Returns	Returns a pointer to the value portion of the name-value pair at the position in the request specified by index.

Example Getting Field Names in a Request

int i, c;

char *name, *value;

c = ics_fcount(msg);

for (i = 0; i < c; i++) {

name = ics_fname(msg, i);

value = ics_fget(msg, i);

printf("%s=%s\n", name, value);

}

ics_fgetbyname() Function

Returns a field from an ics_msg by name.

Table 6ics_fgetbyname() Function
Syntax	char* ics_fgetbyname(ics_msg* msg, char* name)
Description	Extracts the field value from an ics_msg by its field name.
Returns	Pointer to the value portion of the name-value pair of the field with the specified name. Null: no field name exists in the specified request.

Example Accessing a Value in a Request

value = ics_fgetbyname(msg, "ics_rcode")

ics_fname() Function

Returns the name of the name-value pair at the position in an ics_msg specified by index.

Table 7ics_fname() Function
Syntax	char ics_fname(ics_msg msg, int i)
Description	Extracts the field name stored in an ics_msg at the position indicated by index. Use this to get all field names in an ics_msg by iterating from the range of 0 to ics_fcount(msg)-1.
Returns	Pointer to the name portion of the name-value pair at the position in the request specified by index. Null: the index is out of the range.

Example Getting Field Names in a Request

int i, c;

char *name, *value;

c = ics_fcount(msg);

for (i = 0; i < c; i++) {

name = ics_fname(msg, i);

value = ics_fgetbyname(msg, name);

printf("%s=%s\n", name, value);

}

ics_fremove() Function

Removes a field from a request.

Table 8ics_fremove() Function
Syntax	int ics_fremove(ics_msg* msg, char* name)
Description	Removes the field with the specified name from the specified request. Use this call to change the value of a field by removing the field, then adding it using ics_fadd().
Returns	The number of fields in the request after the field is removed. -1: The field is not removed or does not exist in the specified request.

ics_init() Function

Creates and initializes a request.

Table 9ics_init() Function
Syntax	ics_msg* ics_init(int debug_flag)
Description	Creates and initializes a new instance of a CyberSource request. The debug_flag parameter is required (example: int debug_flag = 0). This parameter can contain one of the following values: n0: Debugging information not displayed (default). n1: (ICS_DEBUG) Requests that debugging information be sent to stdout whenever ics_send is called with this request. You can use 1 or ICS_DEBUG. n2: (ICS_TRACE) Writes debugging information to a log file. New logging information is appended to the existing log file, but does not overwrite it. You can use 2 or ICS_TRACE. For Linux and Solaris, the trace log file is $ICSPATH/tmp/icsapilog.txt. For Windows, the trace log file is \icsapilog.txt on the current drive from which the program is run. Debugging information includes: nVariable values nFields of the request being sent nEncrypted data being sent nData about where the request was sent nEncrypted data received as a result nFields of the decrypted result PCI Important CyberSource recommends that you use logging only when troubleshooting problems. To comply with all Payment Card Industry (PCI) and Payment Application Data Security Standards (PADSS) regarding the storage of credit card and card verification number data, the logs that are generated contain only masked credit card and card verification number data (CVV, CVC2, CVV2, CID, CVN). Follow these guidelines: nUse debugging temporarily for diagnostic purposes only. nIf possible, use debugging only with test credit card numbers. nNever store clear text card verification numbers. nDelete the log files as soon as you no longer need them. nNever send email to CyberSource containing personal and account information, such as customers' names, addresses, credit card or checking account numbers, and card verification numbers. For more information about PCI and PABP (Payment Application Best Practices) requirements, see the Visa Cardholder Information Security Program.
Returns	Returns a pointer to ics_msg, or NULL if the function cannot allocate memory for ics_msg.

Example Creating a Request

request = ics_init(0);

ics_send() Function

Sends an encrypted request to the CyberSource server.

Table 10ics_send() Function
Syntax	ics_msg* ics_send(ics_msg* msg)
Description	Sends an encrypted request to the CyberSource server. Each request consists of one field specifying the services to be performed, and several data fields required by the requested services. The returned message includes status fields and calculated data fields.
Returns	Pointer to a message which contains data about the successful or failed request. Null: Memory for the reply message cannot be allocated.

Example Sending a Request

result = ics_send(msg);

ics_set_config_file() Function

Sets a configuration file for a request.

Table 11ics_set_config_file() Function
Syntax	void ics_set_config_file(ics_msg* request, char* filename)
Description	Sets a configuration file for a request. If the function fails to read the configuration file, then the request does not use a configuration file.
Returns	Nothing.

The following table lists parameters that you can use to specify fields you use for all requests in the configuration file. For more information about the configuration file, see Creating the Configuration File.

Table 12Configuration File Parameters
Parameter	Description and Example
debug	Enables debug output. Overrides the ics_init() parameter. You can use the following values: n0: Debugging information not displayed (default). n1: (ICS_DEBUG) Requests that debugging information be sent to stdout whenever ics_send is called with this request. You can use 1 or ICS_DEBUG. n2: (ICS_TRACE) Writes debugging information to a log file. New logging information is appended to the existing log file, but does not overwrite it. You can use 2 or ICS_TRACE. Example: debug=0
ics.host_id	Local IP address to use for generating a request ID. This value must not be 127.0.0.1. Corresponds to the host_id request field. Example: ics.host_id=67.187.183.26
ics.http_proxy	HTTP proxy URL for the CyberSource server. Example: ics.http_proxy=http://my.proxy.host:3128/
ics.http_proxy_ password	HTTP proxy password for the CyberSource server. Example: ics.http_proxy_password=myPassword
ics.http_proxy_ username	HTTP proxy user name for the CyberSource server. Example: ics.http_proxy_username=myUserName
ics.merchant_id	Default CyberSource merchant identifier. Corresponds to the merchant_id request field. Example: ics.merchant_id=myMerchantID
ics.server_host	Default CyberSource server name. Corresponds to the server_host request field. Example: ics.server_host=ics2test.ic3.com
ics.server_port	Default CyberSource server port. Corresponds to the server_port request field. Example: ics.server_port=80

ics_msg Data Type

A request or reply.