



                                    Version
                                      2.8

[TrustCommerce]
Product Management Department
                                                                  TrustCommerce
                                                               Developers Guide
Table of Contents
Introduction_1
Supported_Transaction_Types_2
Data_Types_3
Mandatory_Fields_3
Testing_Indicator_4
Preauth_or_Sale_Transactions_Required_Fields_4
Address_Verification_(AVS)_6
Card_Codes_8
Credits_10
Postauths_11
Reversals_12
Voids_13
Specific_Industry_Data_Edits_14
Restaurants_14
E-Commerce_or_Mail_Order_/_Telephone_Order_15
Recurring_/_Installment_Payments_16
Commercial_Card_and_Purchase_Cards_16
Level_III_Transactions_18
TC_Citadel_21
TCS_Wallet_24
Debit_Cards_26
Transaction_Response_Codes_29
Client_Generated_Errors_29
Server_Generated_Non-Fully_Processed_Errors_30
Server_Generated_Error_Conditions_32
Test_Data_(Credit_Cards_/_ACH)_34
Troubleshooting_35
HTTPS_POST_36


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',.
   1. 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.
   2. A 'postauth' transaction indicates that you wish to settle an existing
      'preauth'.
   3. A 'sale' transaction is a combination of the two above.
   4. A 'credit' transaction is a transfer of funds from the merchant back to
      the cardholder.
   5. A 'reversal' transaction attempts to reduce the credit 'hold' on a
      previously made 'preauth.'
   6. A 'verify' transaction allows you to verify that the credit or debit card
      is valid and is available on select platforms.
   7. 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.
   8. A 'store' transaction allows you to store customer billing information as
      part of our TC Citadel product.
   9. 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:
   1. Non printable characters should not be submitted.
   2. CR/LF characters should not be submitted. They will most likely result in
      a data format rejection by the host.
   3. The '|' character should not be submitted. They may be silently removed
      and/or altered altogether through our system.
   4. 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.
   5. 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_______|
|               |This result code indicates a  |                              |
|               |correct address and an        |                              |
|A______________|incorrect_zip_code.___________|None._________________________|
|               |                              |International card issuers may|
|               |This result code indicates a  |send this code because of the |
|               |correct address but the zip   |different format used in      |
|B______________|code_was_not_verified.________|verifying_zip_codes.__________|
|               |This result code indicates the|                              |
|               |address and zip code were not |Some international issuers may|
|C______________|checked.______________________|not_be_integrated_into_AVS.___|
|               |This result code indicates an |                              |
|               |AVS match for the             |                              |
|D______________|international_card_issuer.____|None._________________________|
|               |                              |The transaction used may not  |
|               |Error encountered or          |be allowed to perform address |
|E______________|transaction_not_allowed.______|verification._________________|
|               |                              |Some international card       |
|               |Address verification not      |issuers may choose not to     |
|G______________|available.____________________|support_AVS.__________________|
|               |                              |Address information not       |
|               |Address verification not      |forwarded because issuer is   |
|I______________|available.____________________|international.________________|
|               |Street Address match for      |                              |
|M______________|international_transaction.____|None._________________________|
|               |Address and zip code do not   |                              |
|N______________|match_what_is_on_file.________|None._________________________|
|               |Zip code match from           |Address information was not   |
|P______________|international_card_issuer.____|verified._____________________|
|R______________|Retry_________________________|Issuer_system_unavailable.____|
|S______________|Service_unavailable.__________|Service_unavailable.__________|
|U______________|Verification_unavailable._____|Address_unavailable.__________|
|               |                              |9 character zip code match    |
|W______________|Zip_Code_match._______________|only._________________________|
|               |                              |Address and 9 character zip   |
|X______________|Exact_match.__________________|code_matches_whats_on_file.___|
|               |                              |Address and 5 character zip   |
|Y______________|Exact_match.__________________|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   |None.                         |
|_______________|Match_______________________|______________________________|
|P              |Not Processed.              |This data was not forwarded to|
|_______________|____________________________|the_issuer.___________________|
|S              |Acknowledgement that CVV2/  |This would happen because the |
|               |CVC2/CID was not sent.      |'cvvstatus' was set to        |
|_______________|____________________________|'notpresent'__________________|
|U              |Issuer doesn't support this |None.                         |
|_______________|field.______________________|______________________________|






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 &amp;&amp; strcmp(status, "approved") == 0) // if it is not
the 'approved' string then it doesn't really matter
	{
		if (cvv != NULL &amp;&amp; *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-day1 (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:
   1. The Reversal feature must be enabled on your TrustCommerce merchant
      account.
   2. 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:
   1. The Void feature must be enabled on your TrustCommerce merchant account.
   2. 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&amp;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 condu|ted
|                  |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 y|ar
|                  |would have a "cycle" of '1y'. We support a number from 1-99 and do not requi|e 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 describ|d
|                  |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 &amp;&amp; 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    |Possible Values                                                                 |
|Name_____|________________________________________________________________________________|
|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" a|d
|         |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|Error |N/A    |cantconnect|
|any_transaction_processing_server._____________|______|_______|___________|
|This occurs when there are issues receiving the|Error |N/A    |linkfailure|
|response data from us. You should check the    |      |       |           |
|transaction independently to determine if the  |      |       |           |
|application was successfully processed to avoid|      |       |           |
|duplication.___________________________________|______|_______|___________|


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 &amp;&amp; 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|baddata|missingfields     |Contains one or   |
|for this transaction to be     |       |                  |more field names. |
|processed. Provide the fields  |       |                  |                  |
|as specified in offenders -    |       |                  |                  |
|- the field names in the       |       |                  |                  |
|offenders value are comma      |       |                  |                  |
|delimited._____________________|_______|__________________|__________________|
|You are providing fields that  |baddata|extrafields       |Contains one or   |
|are not allowed for this       |       |                  |more field names. |
|transaction type. Do not       |       |                  |                  |
|provide the fields as specified|       |                  |                  |
|in_offenders_(see_above).______|_______|__________________|__________________|
|The field length of the field  |baddata|badlength         |The field name    |
|as specified in offenders has  |       |                  |encountering the  |
|minimum and maximum length     |       |                  |problem.          |
|restrictions. In general, you  |       |                  |                  |
|need to provide a corrected    |       |                  |                  |
|version that meets the field   |       |                  |                  |
|length_requirements.___________|_______|__________________|__________________|
|The field type of the field as |baddata|badformat         |The field name    |
|specified in offenders has type|       |                  |encountering the  |
|constraints. For example, the  |       |                  |problem.          |
|field might only allow numbers |       |                  |                  |
|yet you are sending non-digit  |       |                  |                  |
|characters. Consult the field  |       |                  |                  |
|type_and_correct_accordingly.__|_______|__________________|__________________|
|Your custid was not setup to   |baddata|merchantcantaccept|cc - You tried to |
|process the given card type or |       |                  |process a card    |
|currency type. Contact merchant|       |                  |that your account |
|services at TrustCommerce to   |       |                  |is not setup for. |
|determine if you should be     |       |                  |(e.g: American    |
|processing these type of       |       |                  |Express, Discover)|
|transactions. The offenders    |       |                  |currency - You    |
|field indicates the problem    |       |                  |tried to process  |
|field.                         |       |                  |something else    |
|_______________________________|_______|__________________|other_than_USD.___|
|A field provided contains      |baddata|mismatch          |The list of fields|
|conflicting data with another  |       |                  |conflicting with  |
|field provided. For example, if|       |                  |each other.       |
|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.________________________|_______|__________________|__________________|
|TCLink could not perform a DNS |error  |dnsfailure        |N/A               |
|lookup and the account was in  |       |                  |                  |
|demo mode. Your system         |       |                  |                  |
|environment needs to be        |       |                  |                  |
|modified to allow DNS host     |       |                  |                  |
|lookups for                    |       |                  |                  |
|'gateway2048.trustcommerce.com'|_______|__________________|__________________|


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 &amp;&amp; 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 &amp;&amp; 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 |error |linkfailure  |N/A      |
|(from_you_to_us_or_us_to_you).________________|______|_____________|_________|
|This transaction scenario is not supported on |error |unsupported  |action   |
|the_payment_processor.________________________|______|_____________|_________|
|The use of the tip field is not supported on  |error |unsupported  |tip      |
|this_industry_or_platform.____________________|______|_____________|_________|
|The use of the shipdate field is not supported|error |unsupported  |shipdate |
|on_this_industry_or_platform._________________|______|_____________|_________|
|Transmission errors were encountered in our   |error |failtoprocess|N/A      |
|connection_to_the_payment_processor.__________|______|_____________|_________|


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  |4111111111111111|1215|123 Test St. |Somewhere  |CA   |90001|123 |
|Visa_card._|________________|____|_____________|___________|_____|_____|____|
|This is a  |5411111111111115|1215|4000 Main St.|Anytown    |AZ   |85001|777 |
|Mastercard.|________________|____|_____________|___________|_____|_____|____|
|This is a  |341111111111111 |1215|12 Colorado  |Elsewhere  |IL   |54321|4000|
|American   |                |    |Blvd.        |           |     |     |    |
|Express    |                |    |             |           |     |     |    |
|card.______|________________|____|_____________|___________|_____|_____|____|
|This is a  |6011111111111117|1215|6789 Green   |Nowhere    |MA   |12345|N/A |
|Discover   |                |    |Ave          |           |     |     |    |
|card.______|________________|____|_____________|___________|_____|_____|____|
|This is a  |36484444444446  |1215|7390 Del Mar |Atown      |NY   |01101|N/A |
|Diner_card.|________________|____|Blvd_________|___________|_____|_____|____|
|This is a  |213122222222221 |1215|350 Madison  |Springfield|OH   |40000|N/A |
|JCB_card.__|________________|____|Ave__________|___________|_____|_____|____|


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&amp;amount=100&amp;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.
1Non terminal-based platforms generally do not support this type of transaction
conducted with any preauth with track data because the track data cannot be
stored in any way. Contact your solutions consultant for more information.
