TrustCommerce Developer's Guide 2.3

March 18, 2003

Table of Contents

I. Introduction

Definitions of credit card processing terms and information about the Vault website are contained in the TrustCommerce User's Guide, and will not be covered here. If you are not familiar with the basics of credit card processing (such as the difference between an auth and capture), then you should probably read the User's Guide first. The User's Guide also describes use of the Vault website's reporting capabilities, which you may find useful to confirm that your test transactions are working as expected.

There are two methods of connecting to the TrustCommerce gateway at the programming level: the TCLink client software, and an HTTPS POST to the Vault server. TCLink is HIGHLY recommend, as it offers support for TrustCommerce's unique features such as automated failover and enhanced security through server certificate verification. It's available for many platforms and languages, and installation is straightforward, so you should try to use it if possible. If you are unable to use TCLink for whatever reason, the HTTPS POST method will still allow you to access most features of the TrustCommerce processing engine, but be aware that it cannot match the speed and especially the reliability of TCLink.

II. Connecting via TCLink

Installation instructions specific to the TCLink version you've downloaded can be found in the readme file contained with the archive. It will also contain a version of the TCTest program specific to the language you're using. It's highly recommended that you look over this example, and even use it as the basis for your own code. In fact, you should look over the code sample first to get a feel for the API, then return to reading this document.

Versions of TCLink for high-level languages (including PHP, Perl, Python, and Java) with built in support for hashes only have one method: Send(). This method accepts a single parameter, a hash of input values, and returns a single parameters, a hash of output values. The only other method avaliable is GetVersion(), which returns the version string for TCLink.

TCLink for other languages (including C/C++, Win32 COM, and CFX) contains four basic methods: Create(), PushParam(), Send(), and GetResponse(). C-style TCLink functions are described in the table below.

These four methods map to the four stages of running a transaction: initialize, push a number of parameters describing the transaction, send the transaction to the TrustCommerce gateway for processing, and finally get details about the transaction results.

The only method which contacts the TC servers is Send(). This function will block for one or two seconds while the transaction is processed. Afterward, you can retrieve response parameters at your leisure; they are stored internally in TCLink.

III. Transaction Types

In terms of parameters passed, preauths and sales are almost identical. They take account data and personal information about the customer, along with a transaction amount. The transaction is authorized and the response values returned. In the case of a sale, the item is also immediately submitted for capture. Preauths are not captured until they are postauthed.

Postauths and credits are also very similar to one another. They indicate a capture or a return of funds for a previous transaction, and no personal data about the customer or their payment method is passed.

There are three other types of transaction. Store and unstore are covered in the Billing ID section of this document. Walletsale is covered under the TCS Wallet section.

IV. Input Parameters

Parameters are carefully checked for format and size before the transaction is sent. If there are any errors in the parameters you've entered, the transaction will be aborted and detailed information about the errors will be returned. These return values are described in more detail in the next section.

The parameters presented in the following tables are used by all transaction types.

The demo parameter is of particular note for testing. Demo transactions allow you to test your processing system without charging real money to a card, and you will not be charged and transaction fees. They are also flagged separately in the Vault database and will not appear in the regular accounting reports.

On card-not-present transactions, the ticket parameter is passed to the acquiring bank in the settlement process as the "purchase identifier." This may aid in reconciling the TrustCommerce transactions with the deposits made into the merchant bank account. If no ticket is passed, then the TrustCommerce transID will be sent to the bank instead.

V. Return Parameters

Transactions also always return a status parameter which describes the success or failure of the transaction. Status can be set to one of the following:

The difference between approved and accepted is subtle, but important. Approved means that the transaction was an authorization of some sort, and has been successfully cleared with the bank. Accepted only means that the transaction was queued into the system without errors, but may be rejected at some later time. An example of the difference is a sale versus a credit. A sale is a realtime authorization, so it returns approved on success. A credit is not realtime; there is no such thing as a "credit authorization." Instead it is queued up for processing by the bank and there is the small but non-zero posibility that it will be rejected at a later time. In practice, however, this rarely happens, so the developer need not worry unduly.

When status is set to decline, the parameter declinetype will contain one of the following:

A status of baddata indicates that no transaction was attempted because one or more parameters was invalid. In this case, the parameter error will indicate the problem, and the offenders parameter will list the offending input fields. The error parameter may be set to one of the following:

A status of error indicates the an error occurred while processing the transaction. These are almost always networking errors; see the Troubleshooting section for more. If the status is error, then the errortype parameter will be set to one of the following:

Other parameters (such as avs or billingid) may be returned by the transaction depending on the action; see sections covering the transaction type you're running for detailed information on the specialized return values.

VI. Credit Card Preauths and Sales

The parameters that can be passed with these action types are described in the following two tables. The first table list required fields that you must pass in order to send the transaction. The second table lists optional fields that you can pass if you wish, but are not required.

A note about AVS: The AVS system is a useful way to help screen for fraud, as it requires that whomever is sending the transaction know the billing address for the card in question. As a merchant, you should know that AVS is not uniformly supported by card issuers; approximately 30% of US-based credit cards will not have AVS capability, and AVS is not available with any non-US cards at all. If avs=y is used, it will attempt to verify the address data with AVS, but if it is unavailable, it will not cause the transaction to fail. Only if AVS is available and the address data does not match will the transaction be declined due to AVS. You may wish to screen AVS results more closely. For this reason, sales and preauths will return the AVS code in a parameter named avs. (This parameter is returned even when avs=n, which is the default.) It returns a single character code, which are enumerated in the table below.

Only the numeric parts of the address (street address and zipcode) are verified. It should also be noted that oftentimes AVS data is incorrect or not entirely up-to-date, dependent upon the card issuing bank. For these reasons, you should treat AVS as a helpful tool which should be used in combination with other methods (dependent upon your business model) for screening transactions. If you trust AVS too blindly, you may risk losing legitimate sales. Some merchants (again, dependent upon business model) choose to turn AVS off altogether. You should analyze your customer base and make the decision that will work best for your business.

A note on offlineauthcode: Some cards returned a declinetype of call. This indicates that the card cannot be automatically authorized, but if you call the card issuers, they may be able to give you a manual authorization, which will consist of a six-digit auth code. You may then push the transaction through by entering that code into the offlineauthcode field. offlineauthcode can only be used with sale transactions. Be warned: offlineauthcode skips the authorization phase altogether, and thus is not guaranteed in the same way as a normal authorization. Be careful with the use of this parameter.

Preauth/Sale Example

	params = {
		'custid':    'mycustid',
		'password':  'mypasswd',
		'action':    'preauth',
		'amount':    '500',
		'cc':        '4111111111111111',
		'exp':       '0404',
		'name':      'Jennifer Smith',
		'address1':  '123 Test St.',
		'city':      'Somewhere',
		'state':     'CA',
		'zip':       '90001',
		'avs':       'y'
	}

	result = tclink.send(params)

	if (result['status'] == 'approved'):
		print  'Transaction was successful'
	elif (result['status'] == 'decline'):
		print 'Transaction declined.  Reason: ', result['declinetype']
	elif (result['status'] == 'baddata'):
		print 'Improperly formatted data.  Offending fields: ', result['offenders']
	else:
		print 'An error occured: ', result['errortype']

	print 'Here are the full details:'
	print result

VII. Card Verification Value (CVV)

The CVV value will be checked if anything is passed in this parameter. (If you don't include the parameter, no CVV test will be run.) If the CVV matches, the transaction will run as normal. If it does not, you will receive a status of decline, and a declinetype of cvv.

CVV Example

	params = {
		'custid':    'mycustid',
		'password':  'mypasswd',
		'action':    'sale',
		'amount':    '500',
		'cc':        '4111111111111111',
		'exp':       '0404',
		'cvv':       '123'
	}

	result = tclink.send(params)

	if (result['status'] == 'decline')
		if (result['declinetype'] == 'cvv')
			print 'The CVV number is not valid.'

VII. Card-Present Transactions

You can include all data read from the track, but only data between the start sentinel (a '%' character for track1 and a ';' for track2) and the end sentinel ('?') will be used. Everything outside the start and end sentinels (such as the trailing LRC character) will be discarded.

The cc and exp fields may be passed, but are not required, since they will be extracted from the track data. If you do pass one or both of these fields, however, and it does not match the data extracted from the track data, a status of baddata and an error mismatch will be returned.

If both track1 and track2 data are passed, only the system will choose track1 by default for the authorization, and track2 will be discarded.

Generally AVS and address data are not necessary for swiped transactions, but you may pass them anyway if you choose.

Card Present Example

	params = {
		'custid':    'mycustid',
		'password':  'mypasswd',
		'action':    'sale',
		'amount':    '500'
	}

	params['track1'] = CardReader.readMagStripe()

	result = tclink.send(params)

IX. ACH

ACH sales take the same parameters as credit card sales, with the exception of the "cc" and "exp" fields. Instead, use the following parameters.

AVS is not available for ACH transactions, so the AVS setting is ignored.

There is only one declinetype returned from unsuccessful ACH sales, and that is "decline."

ACH Example

	params = {
		'custid':    'mycustid',
		'password':  'mypass',
		'action':    'sale',
		'media':     'ach',
		'amount':    '1000',
		'routing':   '123456789',
		'account':   '55544433322211'
	}

	tclink.send(params)

X. Postauths, Credits, and Chargebacks

In addition, postauths and credits can take an optional amount parameter.

If no amount is passed, the default will be to take the amount from the original transaction. If, however, you wish to credit or postauthorize less than the original amount, you may pass this parameter.

Credit Example

	params = {
		'custid':    'mycustid',
		'password':  'mypass',
		'action':    'credit',
		'transid':   '001-0000111101'
	}

	tclink.send(params)

	if (result['status'] != 'accepted')
		print 'Credit unsuccesful.'

XI. TCS Citadel (Billing IDs)

The Citadel add two new actions, store and unstore. These allow you to create, update, and deactivate billing IDs. Once stored, the billing ID will be passed in place of the many billing information fields for preauth and sale transactions.

The store transaction looks very similar to a preauth or sale. You may pass credit card information, billing and shipping address, or even ACH information. (Please see sections X and X for a detailed description of these parameters.) It adds one additional parameter:

You can update information on existing billing IDs by passing the billingid field along with the store transaction. If you wish to erase the data contained in a field, pass the exact string "null" (four characters, all lower case) as the parameter value.

The verify parameter is useful for ensuring that the card number is valid if you are not planning to bill the customer right away. It has no effect for ACH billing IDs, because there is no such thing as an ACH preauth. By default, the verification uses AVS; if you don't wish to use AVS, pass an avs of "n". Please note: normally, billing ID storage returns a status of accepted, because the card is unverified. If you use the verify parameter, however, it will return approved upon success.

The unstore action takes a single parameter:

Unstore removes the billing ID from active use, and you won't be able to run further transactions on it. For your convenience, however, it does remain visible in Vault (flagged as an inactive ID), so you can still look up old IDs if needed.

Now, the moment of truth: to run a billing ID transaction, pass the billingid parameter to a preauth or a sale in place of all of the usual billing info fields (name, cc, exp, routing, account, etc). That's all there is to it! You'll find that your sale or preauth transactions are now only a few parameters: custid, password, billingid, and amount.

Billing ID Example

	# First, store a new ID.
	params = {
		'custid':    'mycustid',
		'password':  'mypass',
		'action':    'store',
		'cc':        '4111111111111111',
		'exp':       '0404',
		'name':      'Jennifer Smith'
	}

	result = tclink.send(params)

	if (result['status'] == 'accepted'):
		# It was succesfully stored.  Now try running a transaction on the new ID.
		billingid = result['billingid']
		params2 = {
			'custid':    'mycustid',
			'password':  'mypass',
			'action':    'sale',
			'billingid': billingid,
			'amount':    '995'
		}
		tclink.send(params2);
		# Unstore the ID now that we are done.
		params3 = {
			'custid':    'mycustid',
			'password':  'mypass',
			'action':    'unstore',
			'billingid': billingid
		}
		tclink.send(params3)

XII. Recurring Billing

Cycle is in the format of a number between 1 and 99 followed by a character representing the timeframe: 'd' for days, 'w' for weeks, 'm' for months or 'y' for years. For example, a value of "3d" in this field would cause the charge to recur every three days, whereas a value of "2m" would cause it to recur every two months.

Amount is identical to the amount passed to a sale or a preauth, and indicates the amount of each charge made during the subscription.

Start is an optional field which allows the delay of the cycle's start. By default, the cycle starts the day the billing ID is stored. If it is specified in the format YYYY-MM-DD, it indicates a date when the first payment should be made. (For example, "2005-02-01" would be February 1, 2005.) If it is in the same format as the cycle (a number followed by a character), it indicates an offset from the current date. (For example, "1d" would start the billing tomorrow.)

If there is no start parameter, the first transaction is run immediately (and can cause the store action to return a "decline" or other result you would expect from a sale). Other return parameters associated with auths, such as avs code, will be returned as well.

Payments is also optional; left blank or set to zero it will continue the billing cycle until it is manually interrupted by an unstore, or by updating the billing ID with cycle set to "null". Once the final payment is made, the billing ID will be unstored.

There is only one instance in which the cycle parameter is not required, and that is a one-time future payment. By setting payments to "1" and passing a start date, the payment will be made on that date and then the billing ID unstored. The cycle parameter may be included with a one-time future payment, but it will have no effect.

Recurring Billing Example

	params = {
		'custid':    'mycustid',
		'password':  'mypass',
		'action':    'store',
		'cc':        '4111111111111111',
		'exp':       '0404',
		'name':      'Jennifer Smith',
		'amount':    '1200'
	}

	mode = chooseSubscriptionMode()

	if (mode == 1):
		# Make a payment every day, infinitely (or until someone manually disables it)
		params['cycle'] = '1d';
	elif (mode == 2):
		# Make a payment once a month for one year
		params['cycle'] = '1m';
		params['payments'] = '12';
	elif (mode == 3):
		# Make a payment every six weeks, starting one week from now
		params['cycle'] = '62';
		params['start'] = '1w';
	elif (mode == 4):
		# Make annual payments, and don't start until September 1, 2004
		params['cycle'] = '1y';
		params['start'] = '2004-09-01';
	elif (mode == 5):
		# Make a one time payment in 45 days
		params['start'] = '45d';
		params['payments'] = '1';

	tclink.send(params)

XIII. TCS Wallet

The Wallet is an extension of the billing ID system. It adds three new parameters to the store action, described below.

In order to enable wallets for the billing ID that you are storing, set the "wallet" parameter to "y". The other two parameters are optional, as there are default values attached to your TC account. If you wish to change these values (which are normally $10.00 and 72 hours) please contact TrustCommerce. If you wish to change the values for an individual billing ID without changing your defaults, include these parameters.

Once the billing ID is stored, it is possible to use a new action type on the ID called walletsale. It is identical to a sale in all ways, except that it can only be used on wallet-enabled billing IDs, and it can accept amounts anywhere from $0.01 up to the size of the wallet. Walletsale will usually return "approved", but it may return "decline" if the stored credit card fails to re-authorize when the current wallet is exceeded. Except for these two modifications (the wallet parameters on the store, and changing sales to walletsales), there is no extra development to be done client-side to make wallets work. Captures happen automatically after walletexposure has expired or the walletamount has been used up; reauthorizations also happen automatically.

Wallet Example

	# First, store a new ID with the wallet enabled.
	params = {
		'custid':    'mycustid',
		'password':  'mypass',
		'action':    'store',
		'cc':        '4111111111111111',
		'exp':       '0404',
		'name':      'Jennifer Smith',
		'wallet':    'y'
	}

	result = tclink.send(params)

	if (result['status'] == 'approved'):
		# We have a new wallet at our disposal.  Run a micropayment on it.
		billingid = result['billingid']
		params2 = {
			'custid':    'mycustid',
			'password':  'mypass',
			'action':    'walletsale',
			'billingid': billingid,
			'amount':    '995'
		}
		tclink.send(params)

XIV. Purchase Level II

PL2 has three new parmaeters:

A successful PL2 transaction will return one extra response parameter

If you don't care what kind of card they used (which you probably don't), there is no reason to store or otherwise do anything with the commercialcard return value. TrustCommerce internally handles all the details for you. However, if you want this information for some reason, you can access it from the result parameters.

Purchase Level II Example

	params = {
		'custid':           'mycustid',
		'password':         'mypass',
		'action':           'sale',
		'cc':               '4111111111111111',
		'exp':              '0404',
		'amount':           '1000'
		'name':             'Jennifer Smith',
		'purchaselevel':    '2'
		'purchaseordernum': '12345678901234567'
		'tax':              '83'    # $10.00 x 8.25% sales tax = $0.83

	}

	result = tclink.send(params)

	if (result['status'] == 'approved'):
		print 'Approved'

XV. Order Detail

First, you may wish to specify the shipping address for the customer. If it is the same as the billing address, you need not duplicate it, but rather just send the shiptosame parameter set to y. The table below enumerates the shipping parameters.

Second, some additional data about the order as a whole should be passed in the form of the following parameters.

Finally, a number of parameters which describe the details of each type of item must be passed. In the table below, the 'X' character in the parameter name should be replaced with a digit indicating which item it applies to. For example, if numitems is set to three, then you should pass three product codes, in the form of productcode1, productcode2, and productcode3.

Please note: the shippinghandling field and the shippinghandlingX fields are mutually exclusive. Use one or the other, but not both. If you're not sure which to use, please contact your fulfillment house.

Fulfillment Example

	params = {
		'custid':           'mycustid',
		'password':         'mypass',
		'action':           'preauth',
		'cc':               '4111111111111111',
		'exp':              '0404',
		'amount':           '1979',  # Total of items, tax, and shipping
		'name':             'Jennifer Smith',
		'address1':         '123 Test St.',
		'city':             'Somewhere',
		'state':            'CA',
		'zip':              '90001',
		'shiptosame':       'y',     # Shipping address is same as billing address

		'numitems':         '2',     # Two total product codes will be described
		'shippingcode':     'OVRNGT',
		'shippinghandling': '695',

		'productcode1':     'PCODE1',
		'quantity1':        '3',
		'price1':           '600',   # Item 1 costs $2.00, and there are 3 of them
		'tax1':             '144',   # Tax of 8%

		'productcode2':     'PCODE2',
		'quantity2':        '1',
		'price2':           '500',   # Item 1 costs $5.00, there's only one
		'tax2':             '40'     # Tax of 8%
	}

	tclink.send(params)

XVI. Vault Query API

The query API returns data in CSV (comma separated value) format, which is just a flat text file with fields separated by commas, and records separated by newlines. (You can also request the data returned in an HTML table, which is useful for debugging.) The first line of the file contains the name of each field that will be returned in subsequent records.

The parameters that the query interface accepts are described in the table below.

The sample HTML code shown below illustrates the functionality of the query API. It can be pasted into a file and loaded on your web browser in order to try out some queries before you even begin to write your code.

Query Example HTML

<html>
<head> <title> TrustCommerce Query Interface </title> </head>
<body>
<h2> TrustCommerce Query Interface </h2>
<form action=https://vault.trustcommerce.com/query/>
	<table align=center border=1>
	<tr>
		<td> custid </td>
		<td> <input type=text name=custid> </td>
		<td> This is your TrustCommerce custid (required) </td>
	</tr>
	<tr>
		<td> password </td>
		<td> <input type=password name=password> </td>
		<td> This is your TrustCommerce password (required) </td>
	</tr>
	<tr>
		<td> format </td>
		<td> <select name=format> <option value=text>text</option>
				<option value=html>html</option></select></td>
		<td> Human readable (html) or computer readable (text) results</td>
	</tr>
	<tr>
		<td> Query type </td>
		<td> <select name=querytype> 
		<option value=chain>chain</option>
		<option value=transaction>transaction</option>
		<option value=summary>summary</option>
		<option value=billingid>billingid</option>
		</select></td>
		<td> Type of query </td>
	</tr>
	<tr>
		<td> media </td>
		<td> <input type=text name=media value=cc> </td>
		<td> For now this must be cc </td>
	</tr>
	<tr>
		<td> begindate MM-DD-YYYY HH:MM:SS </td>
		<td> <input type=text name=begindate> </td>
		<td> Query begins at this date</td>
	</tr>
	<tr>
		<td> enddate MM-DD-YYYY HH:MM:SS </td>
		<td> <input type=text name=enddate> </td>
		<td> Query ends at this date</td>
	</tr>
	<tr>
		<td> chain </td>
		<td> <input type=text name=chain> </td>
		<td> Narrow search to a single chain of transactions </td>
	</tr>
	<tr>
		<td> transid </td>
		<td> <input type=text name=transid> </td>
		<td> Narrow search to a single transactions </td>
	</tr>
	<tr>
		<td> billingid </td>
		<td> <input type=text name=transid> </td>
		<td> Narrow search to a single billingid </td>
	</tr>
	<tr>
		<td> pastdue </td>
		<td> <select name=pastdue> 
		<option value=y>y</option>
		<option value=n>n</option>
		</select></td>
		<td> Use 'y' or 'n'. For billing ID search.  Show only recurring billing IDs
		     that have been unable to capture the requested funds. </td>
	</tr>
	<tr>
		<td> action </td>
		<td> <input type=text name=action> </td>
		<td> Narrow search by action. (example: preauth,postauth) </td>
	</tr>
	<tr>
		<td> status </td>
		<td> <input type=text name=status> </td>
		<td> Narrow search by status. (example: approved,accepted) </td>
	</tr>
	<tr>
		<td> name </td>
		<td> <input type=text name=name> </td>
		<td> Narrow search by name. </td>
	</tr>
	<tr>
		<td> cc </td>
		<td> <input type=text name=cc> </td>
		<td> Narrow search by credit card field. </td>
	</tr>
	<tr>
		<td> limit </td>
		<td> <input type=text name=limit value=20> </td>
		<td> Limit results to this number of fields (not used for summary)</td>
	</tr>
	<tr>
		<td> offset </td>
		<td> <input type=text name=offset value=0> </td>
		<td> Report results at this offset (used with limit to page through results)</td>
	</tr>
	<tr>
		<td> showcount </td>
		<td> <select name=showcount> 
		<option value=y>yes</option>
		<option value=n>no</option>
		</select></td>
		<td> Show the number of not-limited rows on the last line of the result</td>
	</tr>
	<tr>
		<td colspan=3> <input type=submit> </td>
	</tr>
	</table>
</form>
</body>
</html>

Appendix A - Test Data

Please note: these cards ONLY work on transactions flagged as demo, or while your account is in "test" mode! For a live transaction, they will all return a decline with a declinetype of carderror.

The following card numbers will generate a decline, with the declinetype listed as follows. You may use this to test code which takes different paths dependant upon the type of decline.

You should also test your code to make sure it properly handles all baddata and error cases as listed in section X. Simply pass bad values in order to generate these situations.

Appendix B - Troubleshooting

Once you are able to connect to the TC gateway, you should be able to diagnose parameter-related issues using the status, error, declinetype, and errortype parameters returned by the gateway. There is one response which indicates a more generic error, and that's an error of cantconnect. First, check the computer's network connection; can you ping machines on the Internet, by IP or by name?

The most common network connectivity error is that your target computer may be behind a firewall. TCLink uses the HTTPS port (443/tcp) for network communications; you can check whether this port is open from the target machine by typing "telnet vault.trustcommerce.com 443" at a UNIX command prompt, or else by loading a web browser on the target machine and attempting to visit https://vault.trustcommerce.com directly. If you timeout attempting to make the connection, but your Internet connection is working otherwise, then you may be firewalled. Speak to your network administrator about allowing outbound TCP traffic on port 443.

Another common problem is the lack of domain name (DNS) resolution. In some cases this will result in an errortype dnsfailure. (Not always; the TCLink software will sometimes fall back to hardcoded IP addresses for established accounts. But this method is insecure and error-prone, and is used only as a last resort to keep a system with temporary DNS issues up and running during the outage.) The target machine must be able to resolve the trustcommerce.com domain; try typing "host trustcommerce.com" from a UNIX command prompt. If you don't get a response, or get an error, then the machine cannot resolve DNS information and TCLink will not be able to connect to the TC gateway. Speak to your sysadmin about making domain name resolution available to your target host.

Appendix C - Connecting via HTTPS POST

This is the URL:

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

The transaction should be sent as a standard POST, with CGI parameters, URL encoded. The parameters are otherwise identical to those used through TCLink.

Response parameters are returned as name-value pairs separated by newlines.

Appendix D - Currency Table

Appendix E - Input Field List