TC Developer Guide - Version 2.8

Introduction

Thank you for taking the time to read the TrustCommerce Developer's Guide. As stated above, this document is for people having to integrate their application to TrustCommerce for the purposes of conducting credit card, debit, and ACH transactions. More precisely, this document covers the programming aspects necessary to submit transactions to us and knowledge of programming languages are presumed -- as a matter of fact, most of the examples are provided in the “C” language.

If you are using a shopping cart which has a payment module, such as StoreForge, Mal's e-Commerce, osCommerce, liteCommerce, then you do not need this document. The payment module for those shopping carts contain the necessary instructions for you to process payments. If you are using our TC POS Vault exclusively, then you do not need this document. The TC POS Vault integrates directly to our TCLink product, exposing most (if not all) the functionality you will most likely need.

We provide three methods of performing transaction processing. The first method is through our TCLink client software, available in multiple language bindings. This method offers 2048-bit encryption and sophisticated network failover capabilities. The second method is through an HTTP POST message over SSL (HTTPS). This method offers transaction processing connectivity if the TCLink client software cannot be installed on the machine where the transaction is performed. The third method is a file upload over HTTPS. This method offers batch processing for merchants who collect transactions and perform them in specific periods where the response is not needed immediately. Not all functionality is supported over the batch file upload mechanism -- contact your sales person for more information on specific requirements. This document covers the usage of the TCLink client software and the HTTPS post.

We provide a robust transaction reporting mechanism which you can use to generate your own reports from your own application in addition to our TC POS Vault. Reports are available for the entire transaction life cycle and queries can be restricted to specific criteria of your choosing. This report is generated as the transaction becomes available to us in our internal reporting. Should you find a report insufficient for your needs, feel free to contact us on how to extract the information for your custom report. This document does not cover the usage of the reporting TC POS Vault reporting interface but you can log into the vault and verify that the transactions are reaching us.

Lastly, some transaction types and parameters not listed here are available to merchants who need to process certain type of transactions, such as foreign currency. Contact your solutions consulant for more information on this type of work.

Supported Transaction Types

Supported transaction types are 'preauth', 'postauth', 'sale', 'credit', 'reversal', 'verify', 'chargeback', 'store', and 'unstore',.

A 'preauth' transaction attempts to reduce the 'open to buy' on the credit or debit card and places it on hold for the merchant. The 'open to buy' is the credit limit associated with a credit card or in the case of a debit card, the fund availability within the account.
A 'postauth' transaction indicates that you wish to settle an existing 'preauth'.
A 'sale' transaction is a combination of the two above.
A 'credit' transaction is a transfer of funds from the merchant back to the cardholder.
A 'reversal' transaction attempts to reduce the credit 'hold' on a previously made 'preauth.'
A 'verify' transaction allows you to verify that the credit or debit card is valid and is available on select platforms.
A 'chargeback' transaction allows you to mark a transaction that has been disputed by the cardholder and for which the funds were reversed by the acquiring bank.
A 'store' transaction allows you to store customer billing information as part of our TC Citadel product.
An 'unstore' allows the merchant to deactivate a previously made 'store' transaction.

As more transaction capabilities become available, we may expose them through the use of additional 'action' values and they are discussed more readily in the section that uses them. Field keys are generally identified with double quotations and field values are generally identified with single quotations except in code examples. This section covers what you send to us for transaction processing consideration.

Data Types

For all purposes, data transmitted to us must be in a subset of the ASCII character set with some minor quirks. Some of the quirks include:

Non printable characters should not be submitted.
CR/LF characters should not be submitted. They will most likely result in a data format rejection by the host.
The '|' character should not be submitted. They may be silently removed and/or altered altogether through our system.
Spaces at the beginning of the string are not preserved; spaces in the middle of the string are preserved; spaces at the end of the string are not preserved.
The APIs expect the data to be in string format.

Failure to do so may result in an error at the library or a potential data format rejection by the host.

Mandatory Fields

These fields are required on all transactions:

Field Name	Possible Values
custid	Numeric field provided by us.
password	Alphanumeric field provided by us.
action	preauth, postauth, credit, sale, store, unstore, chargeback, reversal -- see caveat above though

The “custid” is used to identify you in the system. The “password” is used for authentication in our system. The “action” identifies the transaction that you wish to perform, as stated above.

If a transaction passes our internal checks, you will receive a “transid” response for tracking purposes.

Testing Indicator

If your account is in demo mode, you do not need to set this field. If your account is live, you can indicate whether the transaction is live by setting the “demo” field to 'y' if the transaction is a demo transaction and setting the field to 'n' if it is a live transaction. By default, live accounts process live transactions.

The following fragment of code gives an example of the fields up to this point and is generally applicable to all implementations of TCLink through the appropriate method (see Appendix A for a list):

TCLinkHandle handle = TCLinkCreate();

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “sale”);

TCLinkPushParam(handle, “demo”, “y”);

Additional fields are added as needed, some of which are optional, and some of which are required depending on the transaction type.

Preauth or Sale Transactions Required Fields

In order to perform a 'preauth' or 'sale', we require information from the cardholder to process the transaction. This information can be either a “billingid” or cardholder account information. A “billingid” is a previously stored cardholder account information which is obtained through the 'store' transaction.

The minimum cardholder account information is as follows:

Field Name	Possible Values
track1	The track1 data from a card that is swiped with a magnetic stripe reader. Available for merchants who conduct face to face transactions. It is against many card issuer regulations to store or capture this data beyond the time needed to perform the transaction -- do not store this.
track2	The track2 data from a card that is swiped with a magnetic stripe reader. Available for merchants who conduct face to face transactions. It is against many card issuer regulations to store or capture this data beyond the time needed to perform the transaction -- do not store this.
cc	The card number presented by the authorized user.
exp	The expiration date of the card. 'MMYY'
offlineauthcode	If you obtained an authorization through another system, such as a voice authorization, enter the five or six letter/digit approval code here.
amount	The amount of the charge itself, presented without any format characters. For example $1,512.23 is presented to us as '151223'
billingid	A previously stored billing identifier which holds the card information.
media	The type of account information being presented to us. By default, this is set internally by us to 'cc' but if you want to perform ACH transactions, this needs to be set to 'ach'
routing	The routing number present on the checking or saving account. Only valid for sale transactions.
account	The account number associated with the checking or saving account. Only valid for sale transactions.

The following code fragment illustrates the necessary data for performing a card transaction:

	TCLinkPushParam(handle, “cc”, “4111111111111111”);
	TCLinkPushParam(handle, “exp”, “1209”);
	TCLinkPushParam(handle, “amount” “125”);

This performs a 'preauth' or 'sale' for $1.25 against the card number 4111111111111111 with an expiration date of December, 2009. The media field is optional for this type of account information as it is the default in our system. If the transaction occurred offline, set the “offlineauthcode” field as stated above. If the transaction was conducted in a face to face environment, we recommend submitting either 'track1' or 'track2' data or both if available.

The following code fragment illustrates the necessary data for performing a ACH transaction:

	TCLinkPushParam(handle, “media”, “ach”);
	TCLinkPushParam(handle, “routing”, “789456124”);
	TCLinkPushParam(handle, “account”, “55544433221”);
	TCLinkPushParam(handle, “amount” “133”);

This creates an ACH entry from a Receiver (e.g: the customer) authorizing an 'Originator' (e.g: the merchant) to issue an ACH debit to an account (e.g: the customer's account) for an amount of $1.33 from the financial institution (e.g: customer's bank) associated with routing number '789456124' and the customer's account number '55544433221.'

Lastly, a previously stored card account or ACH account can be used in the form of a “billingid”. The same restrictions mentioned for ACH or cards still apply. An example of such a transaction is as follows:

	TCLinkPushParam(handle, “billingid”, “Z12345”);
	TCLinkPushParam(handle, “amount”, “145”);

This performs a 'preauth' or 'sale' transaction against the “billingid” Z12345 in the amount of $1.45.

Address Verification (AVS)

This service, which sends the zip code and address to the card issuer, is supported for 'preauth', 'sale', 'store', and 'verify' card transactions. For merchants who encounter card swiper problems (e.g: unable to read the track data) or are processing a mail order, telephone order, and e-commerce transaction, we strongly recommend you submit this data. The following fields are used to perform the transaction:

Field Name	Possible Values
avs	'y' or 'n'. If this field is set to 'y', we will decline the transaction (for you) if the AVS information does not match. By default, this field is set to 'n',
address1	The address of the cardholder which is on file with the issuer.
zip	The zip code of the cardholder which is on file with the issuer. It is also referred to as the postal code.

This is often referred to as the billing address in most shopping carts or billing systems. You should send this data generally without modification. We will send a response back to you in the field 'avs', indicating the response, if available, from the card issuer. The following is a list of AVS responses that may be returned:

AVS Result Code	Meaning	Implementation Comments
A	This result code indicates a correct address and an incorrect zip code.	None.
B	This result code indicates a correct address but the zip code was not verified.	International card issuers may send this code because of the different format used in verifying zip codes.
C	This result code indicates the address and zip code were not checked.	Some international issuers may not be integrated into AVS.
D	This result code indicates an AVS match for the international card issuer.	None.
E	Error encountered or transaction not allowed.	The transaction used may not be allowed to perform address verification.
G	Address verification not available.	Some international card issuers may choose not to support AVS.
I	Address verification not available.	Address information not forwarded because issuer is international.
M	Street Address match for international transaction.	None.
N	Address and zip code do not match what is on file.	None.
P	Zip code match from international card issuer.	Address information was not verified.
R	Retry	Issuer system unavailable.
S	Service unavailable.	Service unavailable.
U	Verification unavailable.	Address unavailable.
W	Zip Code match.	9 character zip code match only.
X	Exact match.	Address and 9 character zip code matches whats on file.
Y	Exact match.	Address and 5 character zip code matches whats on file.
Z	Zip Code match.	5 character zip match only.

The following is an example of what would be necessary to perform the avs check:

	TCLinkPushParam(handle, “avs”, “n”);
	TCLinkPushParam(handle, “zip”, “926148561”);
	TCLinkPushParam(handle, “address1”, “2 Park Plaza”);

This will send the address '2 Park Plaza' and zip code '926148561' to the card issuer for validation. For addresses that have a number as part of the street name, the number form should be sent instead. For example, 'Two Park Plaza' should be sent to us as '2 Park Plaza'.

To check the response, the following logic would probably be implemented (or some variation on it):

	TCLinkSend(handle); // the data must be sent to us before you get a response
	char buf[1024]; // allocate a temporary buffer to hold the result
	char * ptr = TCLinkGetResponse(handle, “avs”, buf);
	if (ptr != NULL)
	{
		switch (*ptr)
		{
			case 'Y': // exact match
			.
			.
			.
			default: // some code not in list above
	`	}
	}

You would use the response code to determine the appropriate business logic for your particular business. For example, if you are shipping out product and the AVS response code is a 'N', then you might choose not to ship the product until you contact the customer by phone for further investigation.

Card Codes

Visa, Mastercard, Discover, and American Express implement an additional security feature known as the “Card Verification Value”, “Card Validation Code”, “Card Identification Data”, “Card Identification Digits” respectively (CVV2, CVC2, CID, CID). For transactions that are non-swiped, you should send this data and the appropriate indicator, if unavailable. It is generally best practice to send this data to us and in some cases, may result in non-compliance fees being assessed if no information is submitted. Lastly, we will attempt to send a response, if available, and in some cases, this response may be a space, which doesn't indicate anything at all, in the 'cvv' field.

The following is a list of fields associated with Card Codes:

Field Name	Possible Values
cvv	The three or four character field located in the front or back of the card. For Visa, Mastercard, and Discover, this is a three character field located on the back of the card to the far right. For American Express, it is a four character field located on the front of the card above the primary account number.
cvvstatus	This field should be assigned if the 'cvv' field is not submitted. Possible values include 'present', 'notpresent', 'illegible'. By default, it will be treated as 'notpresent' although some processors may treat it otherwise if this field is not submitted by the merchant. The 'present' value states that the merchant did not provide the card code stated above even though it was present. The 'notpresent' value states that the merchant did not see a card code. The 'illegible' value states that the merchant could not read the card code. In all cases, this field is used when the cvv is not submitted -- by submitting a cvv, the merchant is stating that the cvv is present and the value is the 'cvv' indicated above.
cvvcheck	'y' or 'n'. By default, this is set to 'y'. This determines whether we should decline the transaction on behalf of the merchant if the CVV does not match.

Possible response codes are:

CVV Result Code	Meaning	Implementation Comments
M	CVV2/CVC2/Discover CID Match	None.
N	CVV2/CVC2/Discover CID No Match	None.
P	Not Processed.	This data was not forwarded to the issuer.
S	Acknowledgement that CVV2/CVC2/CID was not sent.	This would happen because the 'cvvstatus' was set to 'notpresent'
U	Issuer doesn't support this field.	None.

The following code illustrates sending CVV to us:

	TCLinkPushParam(handle, “cvv”, “1234”);

The following code illustrates sending a CVV indicator to us:

	TCLinkPushParam(handle, “cvvstatus”, “notpresent”);

The following code illustrates an appropriate logic for handling the CVV response:

	TCLinkSend(handle); // the data must be sent to us before you get a response
	char buf[1024], buf2[1024]; // allocate a temporary buffer to hold the result
	char * status = TCLinkGetResponse(handle, “status”, buf);
	char * cvv = TCLinkGetResponse(handle, “cvv”, buf2);
	if (status != NULL && strcmp(status, “approved”) == 0) // if it is not the 'approved' string then it doesn't really matter
	{
		if (cvv != NULL && *cvv != ' ') // see if we have a cvv response to look at and ignore cvv spaces
		{
			// check cvv response
			switch (*cvv)
			{
				case 'M': // cvv match
				.
				.
				default: // some other response...
				
			}
		}
	}

Credits

In the TrustCommerce Payment Gateway system, credits are generally performed against a specific transaction identifier. This allows for reconciliation on a higher level where the disposition of the transaction is in question, such as in the case of chargebacks. If you need to perform credits on a transaction conducted outside of the system, contact us for more information.

The fields required for this transaction are:

Field Name	Possible Values
transid	The transaction identifier returned from a 'postauth' or 'sale' transaction.
amount	The amount that you wish to credit back. By default, the amount credited is the amount used on the 'postauth' or 'sale' transid referenced by the transid field, For example, if the sale is for $5.00, and a credit is performed against the sale, the amount credited is $5.00 unless specified otherwise.

A transid is required for a credit transaction. If the amount is supplied, the amount must be some value greater than or equal to $0.01 and less than or equal to the amount specified in the transid. Otherwise, the transaction will not be credited. If the amount is less than $1.00, then the amount must be prepended with zeros until the field length is three or more digits.

An example of the fields used in a credit transaction:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “credit”);
	TCLinkPushParam(handle, “transid”, “011-1234567890”);
	TCLinkPushParam(handle, “amount”, “013”);

This attempts to credit the cardholder associated with transaction identifier 011-1234567890 in the amount of $0.13. All credit transactions currently return a status of 'accepted' indicating that we have received the transaction.

Postauths

Postauths are used in an environment where the merchant wants to capture funds at a later date or perform additional data submissions. An example of such a scenario is when an order is placed online and the product is shipped 1-7 business days later. The merchant in this scenario would 'preauth' the card at the time the order was placed and if approved, 'postauth' the order when the product is shipped. Another example is merchandise purchased at a store and the merchant may want to delay capture until end-of-day^¹ (to allow for any returns). The 'postauth' works in the same way as the credit but with the action replaced with 'postauth.' For transactions initiated outside the system, use the 'sale' transaction with the 'offlineauthcode' previously mentioned.

Field Name	Possible Values
transid	The transaction identifier returned from an approved 'preauth' transaction.
amount	The amount that you wish to collect. By default, the amount credited is the amount used on the approved 'preauth' transid referenced by the transid field, For example, if the preauth is for $5.00, and the postauth is performed against the preauth, the amount captured is $5.00 unless specified otherwise.

We allow for a postauth to be applied to a 'preauth' or a 'sale' transaction which was declined by our internal AVS or CVV checking -- this is strongly discouraged because of the risk involved and in some cases, the decline may be for another reason altogether. Contact your solutions consultant for more information if this is a scenario that you envision using.

An example of the fields used in a postauth transaction:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “postauth”);
	TCLinkPushParam(handle, “transid”, “011-1234567890”);
	TCLinkPushParam(handle, “amount”, “100”);

This attempts to capture the funds held from the 'preauth' associated with 'transid' '011-1234567890' in the amount of $1.00.

Reversals

A 'reversal' is a transaction that allows the merchant to manipulate the credit 'hold' on a previously made authorization. The typical usage of this transaction is when the cardholder modifies or cancels his or her order, resulting in a charge to be captured which is less than what is previously authorized. This transaction can only be applied against a 'preauth' transaction and only if no 'postauth' has been applied to the 'preauth.' In addition, not all card issuers support this transaction type and not all processors support this functionality. We support partial and full reversals for Visa branded cards and full reversals for Mastercard branded cards. Once a reversal is processed, it cannot be undone. Lastly, this functionality is only available for merchants in a card not present environment.

Field Name	Possible Values
transid	The transaction identifier returned from an approved 'preauth' transaction.
amount	The amount that you wish to reverse. By default, the amount credited is the amount used on the approved 'preauth' transid referenced by the transid field, for example, if the preauth is for $5.00, and the reversal is performed against the preauth, the amount reversed is $5.00 unless specified otherwise.

An example of the fields used in a reversal transaction:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “reversal”);
	TCLinkPushParam(handle, “transid”, “011-1234567890”);
	TCLinkPushParam(handle, “amount”, “100”);

This attempts to reverse the preauth associated with transid '011-1234567890' in the amount of $1.00.

NOTE:

The Reversal feature must be enabled on your TrustCommerce merchant account.
Reversals are currently only supported for Visa and MasterCard Only.

Voids

Occasionally, merchants make mistakes and require a way to ‘undo’ a transaction. This errant transaction could be a preauth, a postauth, a sale or a credit. To resolve these situations, TrustCommerce provides Voids. A Void removes a Sale, Postauth, or Credit transaction from its settlement batch. In order for a Void to be successful, it must be submitted before the batch settles. For all practical purposes, this means Voids must be submitted before 8pm Pacific time on the day that the transaction was submitted.

Field Name	Possible Values
transid	The transaction identifier returned from an approved ‘sale’ transaction.

An example of the fields used in a void transaction:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “void”);
	TCLinkPushParam(handle, “transid”, “011-1234554321”);

This attempts to void the sale associated with transid '011-1234554321' in the amount of $1.00.

NOTE:

The Void feature must be enabled on your TrustCommerce merchant account.
When enabled same-day Credits are not available.

Specific Industry Data Edits

For merchants who process credit card or debit card transactions, certain data element edits may need to be made in order to comply with the various association or issuer requirements. This section covers these requirements and they may or may not apply depending on the type of transactions that you perform. These features may or may not be supported on the platform where your transaction is routed to.

Restaurants

Transactions processed in a restaurant environment or fast food environment may want to support the use of the 'tip' (gratuity) field. The 'tip' field allows the merchant to earmark how much of the transaction went towards gratuity and allows for certain over the authorization amounts to be captured on an existing transaction.

For environments with no tipping requirements, e.g: quick serve restaurants; no changes are needed.

For environments in a tipping environment, you would specify the bill amount as part of the preauth transaction and when you perform the postauth, specify the 'tip' amount to be captured.

An example of a transaction with tip follow up:

	TCLinkHandle handle = TCLinkCreate();
	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “preauth”);
	TCLinkPushParam(handle, “track2”, “;4111111111111111=07120000000000000000?”);
	TCLinkPushParam(handle, “amount”, “1500”);
	TCLinkSend(handle); // the data must be sent to us first before you get a response
	// this logic assumes a 'status' of 'approved'...
	// customer writes in tip at this point and gives you the bill back
	char buf2[1024];
	TCLinkHandle handle2 = TCLinkCreate();
	TCLinkPushParam(handle2, “custid”, “123456”);
	TCLinkPushParam(handle2, “password”, “abc123”);
	TCLinkPushParam(handle2, “action”, “postauth”);
	TCLinkPushParam(handle2, “transid”, TCLinkGetResponse(handle, “transid”, buf2));
	TCLinkPushParam(handle2, “tip”, “200”);
	TCLinkSend(handle2); // the data must be sent to us first before you get a response
	// this logic assumes a 'status' of 'accepted'

This will do an authorization for $15.00 and the tip from the customer is in the amount of $2.00, for a total dollar amount of $17.00

E-Commerce or Mail Order / Telephone Order

You can specify your own purchase identifier (order number) by putting data into the 'ticket' field. To use this, put the same value in this field for all your preauth, postauth, and sale transactions. By default, the order identifier is the 'transid' of the transaction if it is not supplied.

An example of setting this is:

	TCLinkPushParam(handle, “ticket”, “011112222”);

If you ship products out to customers and you use the postauth transaction, you can specify the ship date. By default, we presume that the ship date is the day you initiated the postauth as this is consistent with the clearing requirements of the industry itself. The ship date is in the form “MM-DD-YYYY” where MM represents the two digit month, DD represents the two digit day, YYYY represents the four digit year.

An example of setting this is:

	TCLinkPushParam(handle, “shipdate”, “12-01-2006”);

By default, merchants setup as direct marketing, which encompasses mail order, telephone order, and e-commerce, are processed as if the transactions are e-commerce within the application. If a merchant wishes to process the transactions as if it occurred via telephone or mail order, they would submit the following code for a “preauth”, “postauth”, “sale” transaction:

	TCLinkPushParam(handle, “type”, “moto”);

Recurring / Installment Payments

Merchants who initiate recurring or installment payments outside of our Citadel system need to send us the fields below if they want the transaction to be marked as recurring or installment. Transactions with only the paymentnumber field are marked as recurring. Transactions with both fields are marked as installment. Only 'sale' transactions support this indicator.

Field Name	Possible Values
paymentnumber	This field is the payment number associated with the transaction. It is required for both recurring and installment payment transactions.
totalpayments	This field indicates the number of installments. It is required for installment payment transactions.

In addition to the requirements above, you should submit AVS data as well on the first transaction and whenever the cardholder has changed his or her address in your records.

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “sale”);
	TCLinkPushParam(handle, “cc”, “4111111111111111”);
	TCLinkPushParam(handle, “exp”, “1207”);
	TCLinkPushParam(handle, “amount”, “1500”);
	TCLinkPushParam(handle, “address1”, “123 Anywhere St”);
	TCLinkPushParam(handle, “zip”, “90210”);
	TCLinkPushParam(handle, “paymentnumber”, “1”);
	TCLinkPushParam(handle, “totalpayments”, “3”);

This transaction is an installment payment for $15.00 and is the first of three payments.

Commercial Card and Purchase Cards

We support the data edits for Level II and Level III (II + Line Item Data) transactions. For Level II, we support the use of the 'preauth', 'postauth', and 'sale' transaction sets. For Level III, we support the use of only the 'sale' transaction sets. We support the American Express Corporate/Purchase Card but none of the optional charge descriptors. Failure to submit the appropriate data will generally cause the transaction to be cleared (settled) but you may experience non-compliance fees or the transaction may be qualified for a non-discount rate.

The fields used in a level II transaction are:

Field Name	Possible Values
purchaselevel	'2' or '3'. Used to determine whether we should attempt to qualify the transaction as a Level II transaction or Level III transaction at all, respectively.
taxidentifier	This indicates the type of tax being submitted. If the tax is a city or county tax, then you should submit 'localsales' for this field. If this transaction is exempt from tax, submit 'taxexempt' This is required for all Visa/Mastercard (Commercial and Purchase), and American Express Level II transactions.
tax	The amount of the tax, if applicable, in cents. This is required for all Visa/Mastercard (Commercial and Purchase), and American Express Level II transactions.
shipto_zip	This is the postal code of where the goods were sent. If the product associated with this transaction is not shipped, then you should provide your own zip code for this field. This is required for all American Express Purchase Corporate transactions.
purchaseordernum	This is a customer assigned order number for tracking the purchases being sent. If the customer does not assign a value and the card type is American Express, put your merchant invoice number here. If the customer does not assign a value and the card type is Visa/Mastercard, contact your merchant bank on an appropriate value to put here. This is required for Visa/Mastercard non-purchase, commercial or corporate cards and American Express Corporate Card Level II transactions.

In a preauth/postauth scenario, you would submit the Level II data at the time of the postauth and indicate that you want to try and qualify it for level II on the preauth. In a sale only scenario, you would submit the Level II data at the time of the sale. The following fields are used in a card present swiped, sale transaction with Level II data:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “sale”);
	TCLinkPushParam(handle, “track2”, “;4111111111111111=07120000000000000000?”);
	TCLinkPushParam(handle, “amount”, “1500”);
	TCLinkPushParam(handle, “purchaselevel”, “2”);
	TCLinkPushParam(handle, “taxidentifier”, “localsales”);
	TCLinkPushParam(handle, “tax”, “100”);
	TCLinkPushParam(handle, “purchaseordernum”, “ABC123”);
	TCLinkPushParam(handle, “shipto_zip”, “92606”);

In a 'preauth' scenario, you would submit a preauth similar to the following:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “preauth”);
	TCLinkPushParam(handle, “track2”, “;4111111111111111=07120000000000000000?”);
	TCLinkPushParam(handle, “amount”, “1500”);
	TCLinkPushParam(handle, “purchaselevel”, “2”);

Depending on the support of the backend process, you will receive an indicator specifying whether the card is a commercial card or purchase card. The indicator will tell you whether you should submit the additional data and your application should prompt accordingly. If the processor does not support the identifier return and we do not return an identifier, then you will have to submit the data on every transaction to avoid non-compliance fees and potential discount rate downgrades. In addition to this requirement, you should also ensure that the transaction qualifies for the appropriate interchange program or it may also be downgraded. Once you've determined whether to send this information (or send it everytime), send us the tax, purchaselevel, taxidentifier, purchaseordernum, and shipto_zip if applicable, on the postauth transaction.

An example of this is:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “postauth”);
	TCLinkPushParam(handle, “transid”, “011-1234567890”);
	TCLinkPushParam(handle, “purchaselevel”, “2”);
	TCLinkPushParam(handle, “taxidentifier”, “localsales”);
	TCLinkPushParam(handle, “tax”, “100”);
	TCLinkPushParam(handle, “purchaseordernum”, “ABC123”);
	TCLinkPushParam(handle, “shipto_zip”, “92606”);

Level III Transactions

Level III transactions are essentially Level II transactions with additional data elements. These data elements are used to help the cardholder's business identify items that were purchased and information about the order as a whole. The TrustCommerce Payment Gateway supports non-T&E, non Fleet Level III transactions on specific providers. We support this type of transaction currently for 'sale' transactions only and do not currently support the 'preauth' / 'postauth' configuration. Contact your solutions consultant before implementing this section of the specification as it requires additional information about your business. In addition, additional fields may be defined as needed for the merchant to process orders outside of the U.S. Contact your merchant bank as to what they want to see for Level III transactions.

Visa Level III transactions may have the following information about the order as whole:

Field Name	Possible Values
vatnum	The VAT Registration number associated with the customer. If this field is not provided, we will send blank spaces.
commoditycode	The commodity code assigned by the acquiring bank. If this field is not provided, we will send “7472”
discount	The total discount amount of the order in cents. If this field is not provided, we will send zeros.
shippinghandling	The total freight (including handling) amount of the order in cents. If this field is not provided, we will send zeros.
duty	The duty charged if the goods were imported in cents. If this field is not provided, we will send zeros.
shipto_zip	The zip code of the destination where the goods are being shipped to. If this field is not provided, we will send blanks.
numitems	This field is used to indicate the number of line item details associated with the order. This is mandatory if line item data is submitted as it will be used to determine how many are available. Up to 99 line items are supported.

Line item data may be submitted for Visa Level III transactions as follows:

Field Name	Possible Values
productcode#	The product code or SKU of the item in question.
price#	The unit price of the SKU or item in question.
discount#	The discount amount in cents. This discount is applicable to that single SKU or product code, regardless of the number of items.
quantity#	The number of units ordered.
productdescription#	A description of the product in question.
unitofmeasure#	The type of measurement used with respect to the product code. For example, some products might be sold in cases of 6, or individually. Hence, the merchant might define this as 'CASE' or 'EACH' respectively as the unit of measure. This field should be capitalized.

The # is replaced with the list item number. For example, if you are referring to the second item, then you would replace '#' with '2' and provide that data accordingly.

An example of the data submitted for a Visa Level III transaction is as-follows (the amounts need to be fixed):

	TCLinkPushParam(handle, "custid", "18");
	TCLinkPushParam(handle, "password", "123456");
	TCLinkPushParam(handle, "action", "sale");
	TCLinkPushParam(handle, "cc", "4012881888818888");
	TCLinkPushParam(handle, "exp", "1205");
	TCLinkPushParam(handle, "amount", "2000");
	TCLinkPushParam(handle, "purchaselevel", "3");
	TCLinkPushParam(handle, "tax", "120");
	TCLinkPushParam(handle, "discount", "200");
	TCLinkPushParam(handle, "country", "840");
	TCLinkPushParam(handle, "zip", "90000");
	TCLinkPushParam(handle, "vatnum", "123");
	TCLinkPushParam(handle, "cvv", "999");
	TCLinkPushParam(handle, "shippinghandling", "300");
	TCLinkPushParam(handle, "numitems", "3");
	TCLinkPushParam(handle, "productcode1", "P003");
	TCLinkPushParam(handle, "price1", "300");
	TCLinkPushParam(handle, "discount1", "50");
	TCLinkPushParam(handle, "quantity1", "2");
	TCLinkPushParam(handle, "productdescription1", "PINPAD");
	TCLinkPushParam(handle, "unitofmeasure1", "each");
	TCLinkPushParam(handle, "productcode2", "T300010");
	TCLinkPushParam(handle, "price2", "455");
	TCLinkPushParam(handle, "discount2", "45");
	TCLinkPushParam(handle, "quantity2", "1");
	TCLinkPushParam(handle, "productdescription2", "terminal");
	TCLinkPushParam(handle, "unitofmeasure2", "each");
	TCLinkPushParam(handle, "productcode3", "ML50010");
	TCLinkPushParam(handle, "price3", "325");
	TCLinkPushParam(handle, "discount3", "105");
	TCLinkPushParam(handle, "quantity3", "1");
	TCLinkPushParam(handle, "productdescription3", "accessory");
	TCLinkPushParam(handle, "unitofmeasure3", "each");
	TCLinkPushParam(handle, "purchaseordernum", "1234567");

In this example, the transaction amount is $20.00, containing three line items. The shipping and handling costs were $2.00 altogether. The total discounts applied

The TrustCommerce Payment Gateway supports 99 distinct line items, differentiated by the line item number scheme above.

TC Citadel

The TC Citadel product is a recurring/installment payment solution designed for merchants who wish to have their billing performed on a regular basis, a secure method of storing sensitive data, and a micropayment aggregation system. Using the 'store' transaction, a merchant would store financial data as well as personally identifiable information. There are two scenarios in which a merchant might use the system:

Merchant stores sensitive data with us and we initiate transactions on behalf of the merchant. The merchant is responsible for providing an amount, a time interval, and a start date for which payments are to start.

Merchant stores sensitive data with us and initiates transactions in conjunction with stored data. In the case of micro transactions, we offer micro payment aggregation where small payments are tallied up until a suitable threshold is reached to reduce the number of authorizations. See our TCS Wallet system for more details.

In both cases, the merchant is restricted from viewing the sensitive card or check information, such as credit card numbers or account numbers. This is accomplished through the use of a unique identifier assigned by TrustCommerce and sent back as a result of the 'store' transaction, called the 'billingid'. In addition to this, we store various customer specific information in fields such as the name, address, etc and allow for custom fields specific to your application to be associated on a billing id basis. Contact us for more information on what kind of information you plan to store to determine if this additional functionality is needed.

The following fields are applicable to store transactions:

Field Name	Possible Values
verify	Applicable to non ACH transactions. When this field is set to 'y', a card verification transaction is attempted to determine if the card is valid. If the card verification transaction is not supported or returns an unspecified, a $1.00 preauth will be run on the card to determine card validity.
billingid	If this field is passed, the store will update the data on file with TrustCommerce.
cycle	The time interval in which transactions should be processed. We support the use of days, weeks, months, and years as the time length. For example, a transaction conducted every single day would have a “cycle” of '1d'. A transaction conducted every two weeks would have a “cycle” of '2w'. A transaction conducted every quarter would have a “cycle” of '3m'. A transaction conducted every single year would have a “cycle” of '1y'. We support a number from 1-99 and do not require a leading zero. This is required in scenario #1 as described above.
amount	This is the amount charged each time the recurring or installment payment is processed. This is required in scenario #1 as described above.
start	This is the date or offset from the current date in which transactions should start occuring. A valid date is of the form 'YYYY-MM-DD' where YYYY is the four digit year, MM is the two digit month, DD is the two digit day. For example, Februrary 1, 2007 would be written as '2007-02-01'. A valid offset has the same constraints as the “cycle” field. This is required in scenario #1 as described above. If no start date is provided, then the start date is presumed to be the day on which this billingid store occurred.
payments	This is the total number of payments that the merchants want to make against this cardholder. This is used only in an installment scenario and only valid for scenario #1 as described above. By default, this field is set to '0' to indicate that the billing id requested is either recurring or a store only.
authnow	This field determines whether we should an attempt an authorization immediately for the “amount” specified. We will perform an authorization for the amount specified above and attempt to capture it on the day specified by start. For example, if start is defined as '3d', we will perform a 'preauth' on the day the store occurs and a 'postauth' 3 days later. The start field determines when the postauth will occur. If the start field is not defined, then the 'postauth' is performed at or around the next 02:00 cycle. This is valid only for scenario #1 as described above. Set this to 'y' if you wish to attempt an authorization immediately. By default, this is set to 'n'.
lastpaymentunstore	This field determines whether we should perform an unstore for an installment citadel store once all payments have been made. This is valid for scenario #1 as described above. By default, this field is set to 'y', which tells us to perform the 'unstore'.

Recurring or installment payments are initiated by us at around 02:00 Pacific Standard Time. An example of a recurring payment to be initiated by us is as follows:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “store”);
	TCLinkPushParam(handle, “address1”, “123 Anywhere St”);
	TCLinkPushParam(handle, “zip”, “92606”);
	TCLinkPushParam(handle, “cc”, “4111111111111111”);
	TCLinkPushParam(handle, “exp”, “1209”);
	TCLinkPushParam(handle, “amount”, “1000”);
	TCLinkPushParam(handle, “verify”, “y”);
	TCLinkPushParam(handle, “cycle”, “1m”);
	TCLinkPushParam(handle, “start”, “3d”);
	TCLinkPushParam(handle, “authnow”, “y”);

This transaction will store the credit card number with us, perform a card verification, do an authorization for $10.00 immediately, and perform a sale every month every month, subject to the rules as stated in the above table.

An example of an installment payment to be initiated by us is as follows:

	TCLinkPushParam(handle, “custid”, “123456”);
	TCLinkPushParam(handle, “password”, “abc123”);
	TCLinkPushParam(handle, “action”, “store”);
	TCLinkPushParam(handle, “address1”, “123 Anywhere St”);
	TCLinkPushParam(handle, “zip”, “92606”);
	TCLinkPushParam(handle, “cc”, “4111111111111111”);
	TCLinkPushParam(handle, “exp”, “1209”);
	TCLinkPushParam(handle, “amount”, “500”);
	TCLinkPushParam(handle, “verify”, “y”);
	TCLinkPushParam(handle, “cycle”, “1m”);
	TCLinkPushParam(handle, “payments”, “3”);

This transaction will store the credit card number with us, perform a card verification, and effective at the next run (as determined by our time slot stated above), we will perform a sale for $5.00 three times, once each month and after the last payment, the billingid is unstored.

An example of a store only transaction would be as follows:

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “store”);

TCLinkPushParam(handle, “address1”, “123 Anywhere St”);

TCLinkPushParam(handle, “zip”, “92606”);

TCLinkPushParam(handle, “cc”, “4111111111111111”);

TCLinkPushParam(handle, “exp”, “1209”);

This will store the address, zip, card number, and expiration date into our system.

An example of an update transaction would be as follows:

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “store”);

TCLinkPushParam(handle, “address1”, “123 Anywhere St”);

TCLinkPushParam(handle, “zip”, “92606”);

TCLinkPushParam(handle, “cc”, “4111111111111111”);

TCLinkPushParam(handle, “exp”, “1209”);

TCLinkPushParam(handle, “billingid”, “B01234”);

This will update the account on record associated with billingid 'B01234'.

Transactions are initiated via either a 'preauth' or a 'sale' as described in the Supported Transactions and by passing the “billingid” which the merchants obtains from the results of the transaction.

A merchant can stop further transactions as well as removing it from our processing network by doing an 'unstore' transaction.

An example of an 'unstore' transaction:

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “unstore”);

TCLinkPushParam(handle, “billingid”, “B01234”);

TCS Wallet

The TCS Wallet system is a micropayment aggregation system built atop our TCS Citadel product offering. A merchant can use the TCS Wallet system to treat an authorization as a store credit line for their product offering and process transactions against it. Charges are settled either when the store credit runs out or by the time interval specified. Once this occurs, a new authorization is performed and the billingid wallet is ready for use again. By default, these are set to $10.00 and 72 hours respectively and can be changed accordingly. Contact TrustCommerce before implementing this on your system.

The following additional fields are used in conjunction with the store:

Field Name	Possible Values
wallet	In order to use the TCS Wallet system, this field must be submitted with the value 'y' when doing the initial billingid setup. By default, we do not treat the billingid generated as wallet oriented unless this field is submitted as stated.
walletsize	Overrides the default dollar amount specified above. This field value must be cents and is numeric. (no non-numeric symbols, e.g: $ , .)
walletexposure	Overrides the default time exposure above, in hours. This field value must be numeric and no fractional portion is allowed. (no non-numeric symbols, e.g: $ , .)

Once the billingid is created, you would initiated “walletsale” transactions as opposed to “sale” to further differentiate them in our system. An example of this series is provided below:

// First, store a new ID with the wallet enabled.

TCLinkHandle handle = TCLinkCreate();

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “store”);

TCLinkPushParam(handle, “cc”, “4111111111111111”);

TCLinkPushParam(handle, “exp”, “0909”);

TCLinkPushParam(handle, “address1”, “123 Anywhere St”);

TCLinkPushParam(handle, “zip”, “90210”);

TCLinkPushParam(handle, “name”, “Jennifer Smith”);

TCLinkPushParam(handle, “wallet”, “y”);

TCLinkSend(handle);

char * ptr, buf[256];

// Second, check the response, verify that it got approved, and that you

// have a billingid.

ptr = TCLinkGetResponse(handle, “status”, buf);

if (ptr != NULL && strcmp(ptr, “approved”) == 0)

{

ptr = TCLinkGetResponse(handle, “billingid”, buf);

if (ptr != NULL)

{

// Third, perform the wallet sale. This can be done anytime.

TCLinkHandle handle2 = TCLinkCreate();

TCLinkPushParam(handle2, “custid”, “123456”);

TCLinkPushParam(handle2, “password”, “abc123”);

TCLinkPushParam(handle2, “action”, “walletsale”);

TCLinkPushParam(handle2, “amount”, “995”);

TClinkPushParam(handle2, “billingid”, ptr);

TCLinkSend(handle2);

}

“Walletsale” transactions have the same response codes as “sale” transactions. The only difference is that an authorization is performed on an as-needed basis and captures occur only when the the time interval as specified by 'walletexposure' expires or the wallet 'amount' has been used up.

Debit Cards

Debit cards are private label cards in which the cardholder's money is used to provide for the “open to buy” and for which the transactions are generally settled immediately upon receipt of the appropriate transaction. These transactions generally provide for a purchase transaction and a refund transaction and their meanings are conceptually the same in which a person pays for goods or services in cash and for which a person returns goods or services for cash. In our system, we have mapped the purchase transaction to the “sale” transaction and have mapped the refund transaction to a new transaction type called “credit2”. Our support for debit is limited to transactions in which a personal identification number (aka pin) is required.

Since debit cards represent actual money being transferred, a failure to process, a failure to communicate, and simple unavailability may produce results that are not desired (e.g: duplicate charges/refunds). To prevent this, consider any response but an approval or decline to be something that requires follow up with TrustCommerce / your merchant bank. Furthermore, any debit which is not confirmed also requires follow up with the same entities. This specific condition can be determined if the field 'debitack' in the response is set to 'n'.

In order to process a debit “sale” transaction, the additional fields below are generally required:

Field Name	Possible Values
pin	The pin field is a specifically formatted field containing the DUK/PT encrypted, hex encoded, personal identification number followed by the key set identifier (used to determine which key is being used for encryption) followed by the transaction sequence counter (acts as a salt to protect against weak personal identification numbers). The encrypted DUK/PT encrypt hex encoded, personal identification number is 16 characters in length. The key set identifier is 6 characters in length and is generally hex encoded. The transaction sequence sequence counter is generally 10-20 characters in length. The transaction will not process without this field and must be submitted all the time.
surcharge	The surcharge field is the amount in cents of the surcharge assessed on the transaction. This is commonly seen as part of the little sticker on a POS device where the merchant wants to charge some arbitrary amount of money for using their device. It is the portion of the 'amount' field indicating the surcharge. Merchants who wish to charge a surcharge must provide this information as required by the acquiring bank. This amount may be “0” and if this field is omitted altogether, the surcharge amount is considered to be “0”.
cashback	The cashback field is the amount in cents of the cash that the merchant intends to return to the user. This is the amount of money that the merchant will return to the cardholder. It is the portion of the 'amount' field indicating the cash back. Merchants who wish to provide cash back to the cardholder must provide this information as required by the acquiring bank. This amount may be “0” and if this field is omitted altogether, the cashback amount is considered to be “0”.

The “amount” is generally the cost of the goods or services plus the merchant's surcharge plus the cash back amount requested by the cardholder.

The debit “sale” has additional constraints on the fields that may be submitted for processing with respect to the section on “Preauth or Sale Required Fields”. Specifically, 'track2' and 'amount' must be submitted or the transaction will not process. It is recommended that the implementor not populate the additional fields in that section as our system may reject the transaction because of other validation criteria (e.g: lack of availability, unsuitability, etc.)

An example of a debit sale is provided as follows:

TCLinkHandle handle = TCLinkCreate();

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “sale”);

TCLinkPushParam(handle, “track2”, “;4111111111111111=1212?”);

TCLinkPushParam(handle, “pin”, “BECD3379A717D40E4B00010000200000001A”);

// $25.00 = $4.00 + $1.00 + $20.00

// The cost of the goods and services is $4.00

TCLinkPushParam(handle, “amount”, “2500”);

// The surcharge is $1.00

TCLinkPushParam(handle, “surcharge”, “100”);

// The amount of cash requested by the cardholder is $20.00

TCLinkPushParam(handle, “cashback”, “2000”);

TCLinkSend(handle);

In order to process a debit “refund” transaction, the additional fields below are generally required:

Field Name	Possible Values
pin	See 'pin' for debit transaction “sale” for specifics. The merchant will need to prompt for the user's pin on the refund so that a new 'pin' block is generated.
debitdata	This field corresponds to the return field value from the debit sale transaction 'debitdata'. We require this field currently in order to match the original transaction.
originalsaledate	This field corresponds to the return field value from the debit sale transaction 'originalsaledate'. We require this field currently in order to meet the requirements of certain debit networks. The format for this is “YYYYMMDDHHMISS” where YYYY is the 4 digit year, MM is the two digit month, DD is the two digit day, HH is the two digit hour (0-23), MI is the two digit minute (0-60), SS is the two digit seconds (0-60)

The restrictions which apply to “Preauth or Sale Transactions” as discussed in the Debit Sale section also applies to the Debit Refund.

The debitdata field is used to store debit network specific information so that it can be processed at a latter point. As a result, debit refunds for cards processed outside the TrustCommerce Payment Gateway software is not available -- if that level of integration is needed, contact your account representative for more information.

An example of a debit refund is provided as follows:

TCLinkHandle handle = TCLinkCreate();

TCLinkPushParam(handle, “custid”, “123456”);

TCLinkPushParam(handle, “password”, “abc123”);

TCLinkPushParam(handle, “action”, “credit2”);

TCLinkPushParam(handle, “track2”, “;4111111111111111=1212?”);

TCLinkPushParam(handle, “pin”, “AAAA3379A717D40E4B00010000200000001A”);

TCLinkPushParam(handle, “debitdata”, “0012345678901234567890123456789”);

// January 1st, 2007 at 7:00PM

TCLinkPushParam(handle, “originalsaledate”, “20070101190000”);

// Since the cost of the goods and services is only really $4.00, you can

// refund $4.00. There are no surcharges or cash back amounts that can be

// applied here.

TCLinkPushParam(handle, “amount”, “400”);

TCLinkSend(handle);

Transaction Response Codes

Once a suitable transaction set has been identified for processing, you will need to process the response in order to determine the appropriate business logic. This response is codified into the 'status' field. For example, transactions that are “approved” would indicate that the 'open to buy' charge is acceptable to the card issuer and transactions that are in the “decline” state are not acceptable for a wide number of reasons. Transactions that we received successfully may also be “accepted” for later processing. Transactions containing malformed data that does not pass our validation returns the “baddata” response. Lastly, transactions may encounter routing or network issues (either from you to TrustCommerce or TrustCommerce to Acquirer Processing Entities) and these are generally identified as “error” transactions. If the transaction succesfully passes basic data validation, the response will contain an additional field called 'transid'. This field is a unique identifier in the TrustCommerce Payment Gateway software and can be used to track the transaction through the entire lifecycle. As a general disclaimer, we may add additional “approval”, “decline”, “accepted”, and “error” sub-types to identify specific causes for applications requiring a greater degree of control in how transactions are processed. This section covers the type of responses that you can receive from the TrustCommerce Payment Gateway.

Client Generated Errors

Errors may occur that the TCLink client generates and indicate network connectivity issues -- they are independent of the transaction type submitted to us. Fields that are not present are indicated as N/A and will return the appropriate nothing type as determined by the TCLink implementation.

The following table indicates the two errors that you could potentially see if there was trouble connecting to or receiving data from the TrustCommerce Payment Gateway:

Error Description	Status	transid	errortype
This occurs when a connection cannot be made to any transaction processing server.	Error	N/A	cantconnect
This occurs when there are issues receiving the response data from us. You should check the transaction independently to determine if the application was successfully processed to avoid duplication.	Error	N/A	linkfailure

An example of a code to check this, assuming that handle represents the TCLink object can be seen below:

char *ptr, buf[256];

ptr = TCLinkGetResponse(handle, “status”, buf);

if (ptr != NULL && strcmp(ptr, “error”) == 0)

{

ptr = TCLinkGetResponse(handle, “transid”, buf);

if (ptr == NULL)

{

ptr = TCLinkGetResponse(handle, “errortype”, buf);

if (ptr != NULL)

{

if (strcmp(ptr, “cantconnect”) == 0)

{

// Add your own logic since you couldn't connect.
}

else if (strcmp(ptr, “linkfailure”) == 0)

{

// Add your own code to check this order as it may

// have gone through.

}

We recommend that you also check the 'transid' field as it will allow you to differentiate between various “errortype” successfully.

Server Generated Non-Fully Processed Errors

Errors may occur when the transaction fails to meet our internal checks for validity. This is generally the result of sending malformed data to us or you are missing a required functionality needed for processing the network failover component correctly. Before you go into production, you should fix all the errors of this type as it can be generally corrected by either modifying the environment or your application to send the correct data.

Error Description	status	error	offenders
You are missing fields required for this transaction to be processed. Provide the fields as specified in offenders -- the field names in the offenders value are comma delimited.	baddata	missingfields	Contains one or more field names.
You are providing fields that are not allowed for this transaction type. Do not provide the fields as specified in offenders (see above).	baddata	extrafields	Contains one or more field names.
The field length of the field as specified in offenders has minimum and maximum length restrictions. In general, you need to provide a corrected version that meets the field length requirements.	baddata	badlength	The field name encountering the problem.
The field type of the field as specified in offenders has type constraints. For example, the field might only allow numbers yet you are sending non-digit characters. Consult the field type and correct accordingly.	baddata	badformat	The field name encountering the problem.
Your custid was not setup to process the given card type or currency type. Contact merchant services at TrustCommerce to determine if you should be processing these type of transactions. The offenders field indicates the problem field.	baddata	merchantcantaccept	cc - You tried to process a card that your account is not setup for. (e.g: American Express, Discover) currency - You tried to process something else other than USD.
A field provided contains conflicting data with another field provided. For example, if the 'cc' field does not match the data provided in the 'track1', you would encounter such a problem here. Correct this issue by either rejecting the transaction outright or providing only one of the fields.	baddata	mismatch	The list of fields conflicting with each other.
TCLink could not perform a DNS lookup and the account was in demo mode. Your system environment needs to be modified to allow DNS host lookups for 'gateway2048.trustcommerce.com'	error	dnsfailure	N/A

An example of a code fragment checking this error range is as-follows:

	char *ptr, buf[256], *ptr2, buf2[256];
	ptr = TCLinkGetResponse(handle,  “status”, buf);
	ptr2 = TCLinkGetResponse(handle, “error”, buf2);
	if (ptr != NULL && strcmp(ptr, “error”) == 0)
	{
		if (ptr2 != NULL)
		{
			if (strcmp(ptr2, “missingfields”) == 0)
			{
				// you are missing one or more fields in what you sent
			}
			/* add additional cases above that you wish to handle 
			 * for each additional error status
			 */
		}	
	}
	else if (ptr2 != NULL && strcmp(ptr2, “dnsfailure”) == 0)
	{
		// you should not get this and you should fix your environment
	}

Server Generated Error Conditions

These error conditions are the result of the unavailability, lack of reliability in communicating to and from the actual card processing networks, or an unrecognized response code from the actual card processing networks. In this scenario, transactions may have actually processed all the way to the card issuer. For preauth transactions, you should simply let the authorization expire or attempt to run another authorization. If you are routed over a host-based platform and they do not have duplicate checking enabled, you should contact TrustCommerce customer service to have them void out the transaction if the transaction is a credit, postauth, or sale. If you are routed over a terminal-based platform, you should review your transactions via the TrustCommerce Vault and if needed, contact TrustCommerce customer service if a transaction needs to be removed from the nightly batch.

Error Description	status	errortype	offenders
Malformed data was received over the SSL link (from you to us or us to you).	error	linkfailure	N/A
This transaction scenario is not supported on the payment processor.	error	unsupported	action
The use of the tip field is not supported on this industry or platform.	error	unsupported	tip
The use of the shipdate field is not supported on this industry or platform.	error	unsupported	shipdate
Transmission errors were encountered in our connection to the payment processor.	error	failtoprocess	N/A

Test Data (Credit Cards / ACH)

The information in this section contains test cards as well as routing and account numbers for one to use in testing your implementation to our processing gateway software. In order for this to work, your account must be setup in test mode or the transaction itself must be flagged as a demo transaction. The former is something that we generally start all merchants off until they are ready for production. The latter is something that you can set by sending us the field 'demo' and setting its value to “y”. The following table contains sample data you can use to represent a cardholder for the purposes of running approved, address match, and if applicable CVV/CVC2/CID2 matching demo transactions:

Notes	cc	exp	address1	city	state	zip	cvv
This is a Visa card.	4111111111111111	1215	123 Test St.	Somewhere	CA	90001	123
This is a Mastercard.	5411111111111115	1215	4000 Main St.	Anytown	AZ	85001	777
This is a American Express card.	341111111111111	1215	12 Colorado Blvd.	Elsewhere	IL	54321	4000
This is a Discover card.	6011111111111117	1215	6789 Green Ave	Nowhere	MA	12345	N/A
This is a Diner card.	36484444444446	1215	7390 Del Mar Blvd	Atown	NY	01101	N/A
This is a JCB card.	213122222222221	1215	350 Madison Ave	Springfield	OH	40000	N/A

The following table contains card numbers that will fail in our system as well if the account is in test mode or explicitly set to be in demo mode by the merchant with a 'status' of “decline” and a generated 'declinetype' value as listed below:

cc	exp	declinetype
4012345678909	1215	decline
5555444433332226	1215	call
4444111144441111	1215	carderror

The following table contains an ACH routing number and an ACH account number that will be accepted in our system if the account is in test mode or explicitly set to be in demo mode:

routing	account
789456124	55544433221

If you are interested in our software providing more simulated error cases, let us know and we will accommodate accordingly.

Troubleshooting

Depending on which TCLink you use, there are specific instructions regarding the language and environment for which it runs on. This should be consulted before any documentation here as it describes the environment that you can reasonably expect the software to run in.

Our software requires that you have a functioning DNS as well as allow outbound traffic to port 443. Specifically, our software needs to be able to lookup 'gateway2048.trustcommerce.com' and be able to connect to port 443 on those machines. If you do not have a functioning DNS system, please contact your system administrator. The determining factor for this is if you are able to do something like the following on your Windows or Unix machine and get a similar result back:

[x@skuld ~]$ ping gateway2048.trustcommerce.com
PING gateway2048.trustcommerce.com (207.38.18.54) 56(84) bytes of data.
64 bytes from pn24.sna.trustcommerce.com (207.38.18.54): icmp_seq=1 ttl=42 time=37.3 ms
64 bytes from pn24.sna.trustcommerce.com (207.38.18.54): icmp_seq=2 ttl=42 time=38.6 ms
64 bytes from pn24.sna.trustcommerce.com (207.38.18.54): icmp_seq=3 ttl=42 time=37.3 ms

--- gateway2048.trustcommerce.com ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2000ms
rtt min/avg/max/mdev = 37.365/37.805/38.674/0.653 ms

If you are not seeing the “ttl” as specified above, then you may be encountering some sort of network connectivity issues. Please contact your system administrator and/or internet service provider and provide them with the information above as well as what we require. We will assist as needed with our internet service provider.

If you are unable to resolve the issue through the documentation and resolution steps above, feel free to contact techsupport@trustcommerce.com. Please provide information about the software you are using (e.g: TCLink Version, Host Operating System), the field names and values you are sending -- do not send us the field values for 'track1', 'track2', 'cvv', 'cc', 'exp', 'routing', 'account', 'password' -- and any values you are receiving from us (e.g: 'transid', 'status', 'error', 'declinetype', 'errortype' )

HTTPS POST

For merchants who are unable to install the TCLink software, you can still process through us using the HTTPS POST. The HTTPS POST is a Hypertext Transfer Protocol POST request over Secure Socket Layer (now referred to as Transport Layer Security - TLS) and the underlying context is described here at http://www.ietf.org/rfc/rfc2818.txt The main disadvantage of using this method is the lack of failover because of DNS issues and single processing point.

The URL that you will need to POST to is:

https://vault.trustcommerce.com/trans/

The form data you will post to us is URL encoded (http://www.faqs.org/rfcs/rfc2396.html):

action=sale&amount=100&cc=4111111111111111

The field names and field values are the same as described in this document.

Most people use some sort of software or library to perform the actual transaction, e.g: (curl, .NET WebRequest) You will have to integrate your application to the library or be able to call the software externally in order to use this. Some of our TCLink examples include non TCLink examples that may be of use to you. An example of how this might work in curl is as-follows:

[x@skuld seamonkey]$ curl -d "custid=X" -d "action=sale" https://vault.trustcommerce.com/trans/

offenders=password,amount,cc,exp

error=missingfields

status=baddata

The text before the equal sign is the name of the field. The text after the equal sign is the value of the field. Each pair of field name and field value is separated by a Unix newline.

Data Types

Mandatory Fields

Testing Indicator

Preauth or Sale Transactions Required Fields

Address Verification (AVS)

Card Codes

Credits

Postauths

Reversals

Voids

Restaurants

E-Commerce or Mail Order / Telephone Order

Recurring / Installment Payments

Commercial Card and Purchase Cards

Level III Transactions

TCS Wallet

Client Generated Errors

Server Generated Non-Fully Processed Errors

Server Generated Error Conditions