tclink 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README ADDED
@@ -0,0 +1,69 @@
1
+ Some countries have regulations on the use of cryptographic libraries
2
+ like the ones embedded in TCLink. It may be unlawful to download TCLink
3
+ in these countries.
4
+
5
+
6
+ TCLink v4.2.0
7
+ Ruby Implementation
8
+ copyright (C) TrustCommerce 2010
9
+ http://www.trustcommerce.com
10
+ techsupport@trustcommerce.com
11
+
12
+ June 1, 2016
13
+
14
+ I. DESCRIPTION
15
+
16
+ TCLink is a thin client library to allow your e-commerce servers to
17
+ connect to the TrustCommerce payment gateway easily and consistently.
18
+ The protocol (which is the same across all platforms and languages) is
19
+ well-documented in the Web Developer's Guide, so please consult it for
20
+ any questions you may have about the protocol syntax itself.
21
+
22
+
23
+ II. LICENSE
24
+
25
+ TCLink for Ruby is released under the GNU LGPL. Please read LICENSE
26
+ for details.
27
+
28
+
29
+ III. REQUIREMENTS
30
+
31
+ You need to have the OpenSSL development libraries installed. It
32
+ is recommended that you use the latest version provided by the vendor
33
+ for PCI reasons.
34
+
35
+ Besides the normal Ruby install, you'll need the ruby-devel package,
36
+ which contains files needed for building Ruby extensions.
37
+
38
+ IV. INSTALLATION
39
+
40
+ [sudo] gem install tclink
41
+
42
+ V. TESTING
43
+
44
+ rake test
45
+
46
+ This script will run a test transaction and print the results.
47
+
48
+ VI. USAGE
49
+
50
+ The tctest.rb script shows a simple example of running transactions
51
+ through the TCLink API. For further information, please consult the TC
52
+ Developer's Guide, located in the doc subdirectory.
53
+
54
+ VII. NOTE
55
+
56
+ I forked this from a fork of the original repository whose creator writes:
57
+
58
+ "I packaged this up as a gem for my own uses. I am not affiliated with
59
+ Trust Commerce and have not modified any of the C code.
60
+
61
+ If you have trouble building this, you can download a tarball of the source
62
+ from Trust Commerce's vault.
63
+ "
64
+
65
+ --Keenan Brock
66
+ keenan@thebrocks.net
67
+
68
+ --Phillip Birmingham
69
+ phillip.birmingham@fidelitylife.com
@@ -0,0 +1,21 @@
1
+ require 'bundler/gem_tasks'
2
+
3
+ task :tag, [:repo] do |_, args|
4
+ args.with_defaults repo: `git config --get remote.origin.url`.strip
5
+
6
+ dir_path = Bundler.default_gemfile.dirname
7
+ gemspec_path = Dir["#{dir_path}/*.gemspec"].first
8
+ spec = Bundler.load_gemspec gemspec_path
9
+ version = spec.version
10
+ tag = "v#{version}"
11
+
12
+ command = "git tag -m \"Tagging version #{version}\" #{tag}"
13
+ command << ' && '
14
+ command << "git push #{args.repo} #{tag}"
15
+
16
+ sh command
17
+ end
18
+
19
+ task :test do
20
+ ruby 'test/tclink_test.rb'
21
+ end
@@ -0,0 +1,1923 @@
1
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
+ <html><head>
3
+
4
+
5
+ <meta http-equiv="CONTENT-TYPE" content="text/html; charset=utf-8"><title>TrustCommerce Developer's Guide v2.5</title></head><body dir="ltr" bgcolor="#ffffff" lang="en-US" link="#0000ff" text="#000000" vlink="#00008b">
6
+
7
+ <hr>
8
+
9
+ <h1>TrustCommerce Developer's Guide 2.5 </h1>
10
+
11
+ <p> <a href="http://www.trustcommerce.com/">http://www.trustcommerce.com</a> <br>
12
+ <a href="mailto:developer@trustcommerce.com">developer@trustcommerce.com</a>
13
+
14
+ </p><hr>
15
+
16
+ <h2>Table of Contents </h2>
17
+
18
+ <table>
19
+ <tbody><tr><td><a href="#intro">I. Introduction </a></td></tr>
20
+ <tr><td><a href="#tclink">II. Connecting via TCLink </a></td></tr>
21
+ <tr><td><a href="#transtypes">III. Transaction Types </a></td></tr>
22
+ <tr><td><a href="#inputparam">IV. Input Parameters </a></td></tr>
23
+ <tr><td><a href="#returnparam">V. Return Parameters </a></td></tr>
24
+ <tr><td><a href="#sales">VI. Credit Card Preauths and Sales </a></td></tr>
25
+ <tr><td><a href="#cvv">VII. Card Verification Value (CVV) </a></td></tr>
26
+ <tr><td><a href="#cardpresent">VIII. Card-Present Transactions </a></td></tr>
27
+ <tr><td><a href="#ach">IX. ACH </a></td></tr>
28
+ <tr><td><a href="#credits">X. Postauths, Credits, and Chargebacks </a></td></tr>
29
+ <tr><td><a href="#billingids">XI. Citadel (Billing IDs) </a></td></tr>
30
+ <tr><td><a href="#recurring">XII. Recurring Billing </a></td></tr>
31
+ <tr><td><a href="#wallet">XIII. TC Wallet </a></td></tr>
32
+ <tr><td><a href="#crediguard-neural">XIV. CrediGuard - Neural Network Fraud Scoring</a></td></tr>
33
+ <tr><td><a href="#crediguard-blacklist">XV. CrediGuard - Blacklists</a></td></tr>
34
+ <tr><td><a href="#crediguard-velocity">XVI. CrediGuard - Velocity Control</a></td></tr>
35
+ <tr><td><a href="#pl2">XVII. Purchase Level II (Commercial Cards) </a></td></tr>
36
+ <tr><td><a href="#orderdetail">XVIII. Automated Fulfillment </a></td></tr>
37
+ <tr><td><a href="#batchProcessing">XIX. Batch Processing </a></td></tr>
38
+ <tr><td><a href="#query">XX. Vault Query API </a></td></tr>
39
+ <tr><td><a href="#testdata">Appendix A - Test Data </a></td></tr>
40
+ <tr><td><a href="#troubleshooting">Appendix B - Troubleshooting </a></td></tr>
41
+ <tr><td><a href="#httpspost">Appendix C - Connecting via HTTPS POST </a></td></tr>
42
+ <tr><td><a href="#currency">Appendix D - Currency Table </a></td></tr>
43
+ <tr><td><a href="#inputfields">Appendix E - Input Field List </a></td></tr>
44
+ </tbody></table>
45
+
46
+ <hr>
47
+
48
+ <h2><a name="intro"></a>I. Introduction </h2>
49
+
50
+ <p>
51
+ This guide is for developers. If you are seeking to add payment
52
+ processing functionality to a software package or website using the
53
+ TrustCommerce, platform and language neutral, transaction processing
54
+ API, then this guide is for you. If you are connecting via a
55
+ pre-integrated commerce package, including shopping carts such as
56
+ StoreForge, Mal's e-Commerce, or osCommerce, then you do not need this
57
+ document. </p><p>
58
+ An overview of payment processing and information about the
59
+ TrustCommerce Vault website are presented in the TrustCommerce User's
60
+ Guide and will not be covered here. If you are not familiar with the
61
+ basics of credit card processing (such as the difference between an
62
+ auth and capture), then you should probably read the User's Guide
63
+ first. The User's Guide also describes the Vault's reporting
64
+ capabilities, which you may find useful to confirm that your test
65
+ transactions are working as expected.
66
+ </p><p>There are two methods of connecting to the TrustCommerce
67
+ gateway at the programming level: TCLink client software and HTTPS POST
68
+ to the Vault server. TCLink is HIGHLY recommend, as it offers support
69
+ for TrustCommerce's advanced features such as automated failover,
70
+ 2048-bit encryption and server certificate verification. It's available
71
+ for many platforms and languages, and installation is straightforward.
72
+ If you are unable to use TCLink, the HTTPS POST method will still allow
73
+ you to access most features of the TrustCommerce processing engine, but
74
+ be aware that it cannot match the speed and especially the reliability
75
+ of TCLink. </p><h2><a name="tclink"></a>II. Connecting via TCLink </h2>
76
+
77
+ <p>
78
+ The TCLink API is available for download from the Vault website. Be
79
+ sure to choose the version that matches the platform and language that
80
+ you are using. Win32 developers will typically want the COM object,
81
+ which contains support for a number of different languages on the Win32
82
+ platform, including ASP, Cold Fusion, Perl, PHP, and Python. </p><p>
83
+ Installation instructions specific to the TCLink version you download
84
+ can be found in the readme file contained within the archive. It will
85
+ also contain a version of the TCTest program specific to the language
86
+ you are using. Review this example, and use it as the basis for your
87
+ own code. In fact, we recommend that you look over the code sample now
88
+ to get a feel for the API, and then return to reading this document. </p><p>
89
+ Versions of TCLink for high-level languages (including PHP, Perl,
90
+ Python, and Java) with built in support for hashes only have one
91
+ method: Send(). This method accepts a single parameter, a hash of input
92
+ values, and returns a single parameter, a hash of output values. The
93
+ only other method available is GetVersion(), which returns the version
94
+ string for TCLink. </p><p>
95
+ TCLink for other languages (including C/C++, Win32 COM, and CFX)
96
+ contains four basic methods: Create(), PushParam(), Send(), and
97
+ GetResponse(). These four methods map to the four stages of running a
98
+ transaction: initialize, push a number of parameters describing the
99
+ transaction, send the transaction to the TrustCommerce gateway for
100
+ processing, and finally get details about the transaction results. </p><p>
101
+ The only method which contacts the TC servers is Send(). This function
102
+ will block for one or two seconds while the transaction is processed.
103
+ Afterward, you can retrieve response parameters at your leisure; they
104
+ are stored internally in TCLink. </p><p>
105
+ C-style TCLink functions are described in the table below.
106
+
107
+ </p><p>
108
+ </p><h3 align="center">TCLink Function Names </h3>
109
+
110
+ <center>
111
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
112
+ <tbody><tr><th>Function Name </th><th>Description</th></tr>
113
+ <tr><td>CreateLink()</td><td>Create a new transaction handle.</td></tr>
114
+ <tr><td>PushParam()</td><td>Push a parameter into the transaction.</td></tr>
115
+ <tr><td>Send()</td><td>Submit a transaction to the gateway.</td></tr>
116
+ <tr><td>GetResponse()</td><td>Retrieve a response parameter from the transaction. </td></tr>
117
+ <tr><td>GetEntireResponse()</td><td>Get the entire response for the transaction, primarily use for debugging or logging.</td></tr>
118
+ <tr><td>Destroy()</td><td>Deallocate any memory associated with the transaction handle.</td></tr>
119
+ <tr><td>GetVersion()</td><td>Get the version string for the TCLink API in use.</td></tr>
120
+ </tbody></table>
121
+ </center>
122
+
123
+ <p>
124
+ </p><h2><a name="transtypes"></a>III. Transaction Types </h2>
125
+
126
+ <p>
127
+ You may wish to read the section of the TC User's Guide which describes
128
+ the transaction types and the authorization/capture process, especially
129
+ if you are not already familiar with credit card processing. </p><p>
130
+ In terms of parameters passed, preauths and sales are almost identical.
131
+ They take account data and personal information about the customer,
132
+ along with a transaction amount. The transaction is authorized and the
133
+ response values returned. In the case of a sale, the item is also
134
+ immediately submitted for capture. Preauths are not captured until they
135
+ are postauthed. </p><p>
136
+ Postauths and credits are also very similar to one another. They
137
+ indicate a capture or a return of funds for a previous transaction, and
138
+ no personal data about the customer or their payment method is passed. </p><p>
139
+ There are three other types of transaction. Store and unstore are covered in the <a href="#billingids">Billing ID section </a>of this document. Walletsale is covered under the <a href="#wallet">TC Wallet section </a>.
140
+
141
+ </p><p>
142
+ </p><h2><a name="inputparam"></a>IV. Input Parameters </h2>
143
+
144
+ <p>
145
+ There are a large number of parameters available for describing
146
+ transactions. Not all parameters are accepted for all transaction
147
+ types, and most parameters are optional. Most transactions can be sent
148
+ with only a few parameters. The only parameters always required are
149
+ custid, password, and action. </p><p>
150
+ Parameters are carefully checked for format and size before the
151
+ transaction is sent. If there are any errors in the parameters you've
152
+ entered, the transaction will be aborted and detailed information about
153
+ the errors will be returned. These return values are described in more
154
+ detail in the next section. </p><p>
155
+ All transaction types use the parameters presented in the following tables.
156
+
157
+ </p><p>
158
+ </p><h3 align="center">Required Parameters</h3>
159
+
160
+ <p>
161
+ </p><center>
162
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
163
+ <tbody><tr><th>Parameter Name</th><th>Description</th></tr>
164
+ <tr><td>amount</td><td>Amount of the transaction, in cents. (example: "500" is $5.00) </td></tr>
165
+ <tr><td>custid</td><td>The customer ID number assigned to you by TrustCommerce.</td></tr>
166
+ <tr><td>password</td><td>The password for your custid as assigned by TrustCommerce. </td></tr>
167
+ <tr><td>action</td><td>The transaction type; can be one of preauth, sale, postauth,credit, store, unstore, walletsale, or chargeback </td></tr>
168
+ </tbody></table>
169
+ </center>
170
+
171
+ <p>
172
+ </p><h3 align="center">Optional Parameters </h3>
173
+
174
+ <center>
175
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="3">
176
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
177
+ <tr><td>demo </td><td>When set to "y", the transaction will be a test transaction only.
178
+ <p>This
179
+ parameter is useful for testing. Demo transactions allow you to submit
180
+ transactions from your processing system without charging real money to
181
+ a card and without incurring any transaction fees. Demo transactions
182
+ are also flagged separately in the Vault database and will not appear
183
+ in the regular accounting reports. </p></td></tr>
184
+ <tr><td>ticket</td><td>Free-form
185
+ text field intended for storing ticket number or order number
186
+ associated with the transaction, to aid merchants in order tracking and
187
+ reporting. <p>The ticket parameter is passed to the acquiring bank in the
188
+ settlement process as the "purchase identifier." This may aid in
189
+ reconciling the TrustCommerce transactions with the deposits made into
190
+ the merchant bank account. If no ticket is passed, then the
191
+ TrustCommerce transID will be sent to the bank instead. </p></td></tr>
192
+ <tr><td>operator</td><td>Free-form
193
+ text field intended for recording the operator that entered the
194
+ transaction, to aid merchants in order track and reporting.
195
+ Enterprise-class customers will note that this field corresponds to the
196
+ username assigned to operators in the Vault.</td></tr>
197
+ </tbody></table>
198
+ </center>
199
+ <p>
200
+ </p><h2><a name="returnparam"></a>V. Return Parameters </h2>
201
+
202
+ <p>
203
+ Any transaction sent will return several parameters describing the
204
+ success or failure of the transaction. Properly formatted transactions
205
+ will always return a transaction ID (or "transID".) The transaction ID
206
+ is the unique identifier for this transaction, and can be used to
207
+ retrieve the transaction from the Vault website, or otherwise access
208
+ the transaction in the future. (For example, in order to credit a
209
+ previous transaction, you will need to send the transID of the original
210
+ transaction.) </p><p>
211
+ Transactions always return a status parameter which describes the
212
+ success or failure of the transaction. Status can be set to one of the
213
+ following: </p><h3 align="center"><a name="Status|outline"></a>Status </h3>
214
+ <center>
215
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="3">
216
+ <tbody><tr><th>Status Value </th><th>Description </th></tr>
217
+ <tr><td>approved </td><td>The transaction was successfully authorized. </td></tr>
218
+ <tr><td>accepted </td><td>The transaction has been successfully accepted into the system. </td></tr>
219
+ <tr><td>decline </td><td>The transaction was declined, see declinetype for further details. </td></tr>
220
+ <tr><td>baddata </td><td>Invalid parameters passed, see error for further details. </td></tr>
221
+ <tr><td>error </td><td>System error when processing the transaction, see errortype for details. </td></tr>
222
+ </tbody></table>
223
+ </center>
224
+
225
+ <p>
226
+ The difference between approved and accepted is subtle, but important.
227
+ Approved means that the transaction was an authorization of some sort,
228
+ and has been successfully cleared with the bank. Accepted only means
229
+ that the transaction was queued into the system without errors, but may
230
+ be rejected at some later time. An example of the difference is a sale
231
+ versus a credit. A sale is a real-time authorization, so it returns
232
+ approved on success. A credit is not real-time; there is no such thing
233
+ as a "credit authorization." Instead it is queued up for processing by
234
+ the bank and there is the small but non-zero possibility that it will
235
+ be rejected at a later time. In practice, however, this rarely happens,
236
+ so the developer need not worry unduly. </p><p>
237
+ When status is set to decline, the parameter declinetype will contain one of the following:
238
+
239
+ </p><p>
240
+ </p><h3 align="center"><a name="Decline Type|outline"></a>Decline Type </h3>
241
+ <center>
242
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
243
+ <tbody><tr><th>Declinetype Value </th><th>Description </th></tr>
244
+ <tr><td>decline </td><td>This is a "true" decline, it almost always is a result of insufficient funds on the card.</td></tr>
245
+ <tr><td>avs </td><td>AVS failed; the address entered does not match the billing address on file at the bank. </td></tr>
246
+ <tr><td>cvv </td><td>CVV failed; the number provided is not the correct verification number for the card. (See <a href="#cvv">CVV section </a>for more details.) </td></tr>
247
+ <tr><td>call </td><td>The
248
+ card must be authorized manually over the phone. You may choose to call
249
+ the customer service number listed on the card and ask for an offline
250
+ authcode, which can be passed in the offlineauthcode field. </td></tr>
251
+ <tr><td>expiredcard </td><td>The card has expired. Get updated expiration date from cardholder.</td></tr>
252
+ <tr><td>carderror </td><td>Card number is invalid, which could be a typo, or sometimes a card reported stolen. </td></tr>
253
+ <tr><td>authexpired </td><td>Attempt to postauth an expired (more than 14 days old) preauth. </td></tr>
254
+ <tr><td>fraud </td><td><a href="#crediguard-neural">CrediGuard fraud score</a> was below requested thershold.</td></tr>
255
+ <tr><td>blacklist </td><td><a href="#crediguard-blacklist">CrediGuard blacklist</a> value was triggered.</td></tr>
256
+ <tr><td>velocity </td><td><a href="#crediguard-velocity">CrediGuard velocity control</a> was triggered.</td></tr>
257
+ <tr><td>dailylimit </td><td>Daily limit in transaction count or amount as been reached. </td></tr>
258
+ <tr><td>weeklylimit </td><td>Weekly limit in transaction count or amount as been reached. </td></tr>
259
+ <tr><td>monthlylimit </td><td>Monthly limit in transaction count or amount as been reached. </td></tr>
260
+ </tbody></table>
261
+ </center>
262
+
263
+ <p>
264
+ A status of baddata indicates that no transaction was attempted because
265
+ one or more parameters was invalid. In this case, the parameter error
266
+ will indicate the problem, and the offender's parameter will list the
267
+ offending input fields. The error parameter may be set to one of the
268
+ following: </p><p>
269
+ </p><h3 align="center"><a name="Bad Data|outline"></a>Bad Data </h3>
270
+ <center>
271
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
272
+ <tbody><tr><th>Error Value </th><th>Description </th></tr>
273
+ <tr><td>missingfields </td><td>One or more parameters required for this transaction type were not sent. </td></tr>
274
+ <tr><td>extrafields </td><td>Parameters not allowed for this transaction type were sent. </td></tr>
275
+ <tr><td>badformat </td><td>A field was improperly formatted, such as non-digit characters in a number field. </td></tr>
276
+ <tr><td>badlength </td><td>A field was longer or shorter than the server allows. </td></tr>
277
+ <tr><td>merchantcantaccept </td><td>The
278
+ merchant can't accept data passed in this field. If the offender is
279
+ "cc", for example, it usually means that you tried to run a card type
280
+ (such as American Express or Discover) that is not supported by your
281
+ account. If it was "currency", you tried to run a currency type not
282
+ supported by your account. </td></tr>
283
+ <tr><td>mismatch </td><td>Data in one of the offending fields did not cross-check with the other offending field. </td></tr>
284
+ </tbody></table>
285
+ </center>
286
+
287
+ <p>
288
+ A status of error indicates the an error occurred while processing the
289
+ transaction. These are almost always networking errors; see the <a href="#troubleshooting">Troubleshooting section </a>for more details. If the status is error, then the errortype parameter will be set to one of the following:
290
+
291
+ </p><p>
292
+ </p><h3 align="center"><a name="Errortype|outline"></a><a name="Errortype|outline"></a>Errortype </h3>
293
+
294
+ <center>
295
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
296
+ <tbody><tr><th>Errortype Value </th><th>Description </th></tr>
297
+ <tr><td>cantconnect </td><td>Couldn't connect to the TrustCommerce gateway. Check your Internet connection to make sure it is up. </td></tr>
298
+ <tr><td>dnsfailure </td><td>The TCLink software was unable to resolve DNS hostnames. Make sure you have name resolving ability on the machine. </td></tr>
299
+ <tr><td>linkfailure </td><td>The connection was established, but was severed before the transaction could complete. </td></tr>
300
+ <tr><td>failtoprocess </td><td>The
301
+ bank servers are offline and unable to authorize transactions. Try
302
+ again in a few minutes, or try a card from a different issuing bank. </td></tr>
303
+ </tbody></table>
304
+ </center>
305
+
306
+ <p>
307
+ Other parameters (such as avs or billingid) may be returned by the
308
+ transaction depending on the action; see sections covering the
309
+ transaction type you're running for detailed information on the
310
+ specialized return values. </p><p>
311
+ </p><h2><a name="sales"></a><a name="VI. Credit Card Preauths and Sales|outline"></a> VI. Credit Card Preauths and Sales </h2>
312
+
313
+ <p>
314
+ The 'preauth' and 'sale' actions are identical in terms of parameters
315
+ and function. The only difference is that a sale submits the item for
316
+ capture as well, while preauths run the authorization only and can be
317
+ postauthed at another time. </p><p>
318
+ The parameters that can be passed with these action types are described
319
+ in the following two tables. The first table list required fields that
320
+ you must pass in order to send the transaction. The second table lists
321
+ optional fields that you can pass if you wish, but are not required. </p><p>
322
+ </p><h3 align="center">Required Parameters </h3>
323
+ <center>
324
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="3">
325
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
326
+ <tr><td>amount </td><td>Amount of the transaction, in cents. (example: "500" is $5.00)</td></tr>
327
+ <tr><td>cc </td><td>Credit card number, digits only (no spaces or dashes) </td></tr>
328
+ <tr><td>exp </td><td>Credit card expiration date, in MMYY format. </td></tr>
329
+ </tbody></table>
330
+ </center>
331
+
332
+ <p>
333
+ </p><h3 align="center">Optional Parameters </h3>
334
+ <center>
335
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="3">
336
+ <tbody><tr><th>Parameter Name </th><th>Default Value </th><th>Description </th></tr>
337
+ <tr><td>media </td><td>cc </td><td>"cc" for credit card or "ach" for ACH. </td></tr>
338
+ <tr><td>currency </td><td>usd </td><td>Currency code (see the <a href="#currency">Currency Table </a>for a list of allowed codes.) </td></tr>
339
+ <tr><td>avs </td><td>n </td><td>AVS requested, "y" or "n".
340
+ <p>NOTE:<br>The
341
+ AVS system is a useful way to help screen for fraud. Unfortunately,
342
+ card issuers do not provide uniform support for AVS; approximately 30%
343
+ of US-based credit cards do not have AVS capability, and AVS is not
344
+ available with any non-US cards at all. The ONLY time that a
345
+ transaction will be declined due to AVS is in cases where AVS is
346
+ available and the address data submitted with the transaction does not
347
+ match the data on file at the bank. If AVS is unavailable, it will not
348
+ cause the transaction to fail. For this reason, you may wish to screen
349
+ AVS results closely. </p><p>Only the numeric parts of the address (street address and
350
+ zip code) are verified. It should also be noted that on occasion, AVS
351
+ data is incorrect or not entirely up-to-date. Treat AVS as a helpful
352
+ tool which can be used in combination with other methods (dependent
353
+ upon your business model) for screening transactions. If you trust AVS
354
+ too blindly, you may risk losing legitimate sales. Some merchants
355
+ (again, dependent upon business model) choose to turn AVS off
356
+ altogether. You should analyze your customer base and make the decision
357
+ that will work best for your business. </p></td></tr>
358
+ <tr><td>name </td><td><br></td><td>Cardholder's name. </td></tr>
359
+ <tr><td>address1 </td><td><br></td><td>First line of cardholder's street address. </td></tr>
360
+ <tr><td>address2 </td><td><br></td><td>Second line of cardholder's street address. </td></tr>
361
+ <tr><td>city </td><td><br></td><td>Cardholder's city. </td></tr>
362
+ <tr><td>state </td><td><br></td><td>Two-character code for the cardholder's state, or the full region/province for international addresses. </td></tr>
363
+ <tr><td>zip </td><td><br></td><td>Cardholder's zip code, five or nine digits with no spaces or dashes, or the full postal code for international addresses. </td></tr>
364
+ <tr><td>country </td><td><br></td><td>Cardholder's country, leave blank for US. </td></tr>
365
+ <tr><td>phone </td><td><br></td><td>Cardholder's phone number. </td></tr>
366
+ <tr><td>email </td><td><br></td><td>Cardholder's email address. </td></tr>
367
+ <tr><td>ip </td><td><br></td><td>Customer's
368
+ originating TCP/IP address (e-commerce only). This is not your server's
369
+ IP, but that of the customer's computer, as reported by the web server.
370
+ For example, in PHP the global variable $_SERVER{'REMOTE_ADDR'}
371
+ contains the incoming IP address which should be passed in this field.</td></tr>
372
+ <tr><td>offlineauthcode </td><td><br></td><td>Six-digit numeric code used to "force" the transaction.
373
+ <p>NOTE:
374
+ </p><p>Some
375
+ cards returned a declinetype of call. This indicates that the card
376
+ cannot be automatically authorized. If you call the card issuer, they
377
+ may be able to give you a manual authorization, which will consist of a
378
+ six-digit auth code. You may then push the transaction through by
379
+ entering that code into the offlineauthcode field. Offline
380
+ authorizations via offlineauthcode can only be used with sale
381
+ transactions. Since offlineauthcode skips the authorization phase
382
+ altogether, it is not guaranteed in the same way as a normal
383
+ authorization. Be careful with the use of this parameter. </p></td></tr>
384
+ </tbody></table>
385
+ </center>
386
+
387
+ <p>
388
+ </p><h3 align="center">AVS Returns Codes </h3>
389
+
390
+ <center>
391
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="3">
392
+ <tbody><tr><th>Code </th><th>Description </th></tr>
393
+ <tr><td><p align="center">X </p></td><td>Exact match, 9 digit zip code. </td></tr>
394
+ <tr><td><p align="center">Y</p></td><td>Exact match, 5 digit zip code. </td></tr>
395
+ <tr><td><p align="center">A </p></td><td>Street address match only. </td></tr>
396
+ <tr><td><p align="center">W </p></td><td>9 digit zip code match only. </td></tr>
397
+ <tr><td><p align="center">Z </p></td><td>5 digit zip code match only. </td></tr>
398
+ <tr><td><p align="center">N </p></td><td>No match on street address or zip code. </td></tr>
399
+ <tr><td><p align="center">U </p></td><td>AVS unavailable on this card. </td></tr>
400
+ <tr><td><p align="center">G </p></td><td>Non-US card issuer, AVS unavailable. </td></tr>
401
+ <tr><td><p align="center">R </p></td><td>Card issuer system currently down, try again later. </td></tr>
402
+ <tr><td><p align="center">E </p></td><td>Error, ineligible - not a mail/phone order. </td></tr>
403
+ <tr><td><p align="center">S </p></td><td>Service not supported. </td></tr>
404
+ <tr><td><p align="center">0 </p></td><td>General decline or other error. </td></tr>
405
+ </tbody></table>
406
+ </center>
407
+
408
+ <p>
409
+ </p><h3>Preauth/Sale Example </h3>
410
+
411
+ <pre> params = {
412
+ 'custid': 'mycustid',
413
+ 'password': 'mypasswd',
414
+ 'action': 'preauth',
415
+ 'amount': '500',
416
+ 'cc': '4111111111111111',
417
+ 'exp': '0412',
418
+ 'name': 'Jennifer Smith',
419
+ 'address1': '123 Test St.',
420
+ 'city': 'Somewhere',
421
+ 'state': 'CA',
422
+ 'zip': '90001',
423
+ 'avs': 'y'
424
+ }
425
+
426
+ result = tclink.send(params)
427
+
428
+ if (result['status'] == 'approved'):
429
+ print 'Transaction was successful'
430
+ elif (result['status'] == 'decline'):
431
+ print 'Transaction declined. Reason: ', result['declinetype']
432
+ elif (result['status'] == 'baddata'):
433
+ print 'Improperly formatted data. Offending fields: ', result['offenders']
434
+ else:
435
+ print 'An error occurred: ', result['errortype']
436
+
437
+ print 'Here are the full details:'
438
+ print result
439
+ </pre>
440
+
441
+ <p>
442
+ </p><h2><a name="cvv"></a>VII. Card Verification Value (CVV) </h2>
443
+
444
+ <p>
445
+ Another method for cardholder verification is the CVV system. Visa
446
+ cards use what is called a CVV(II) or CVV2 code; MasterCard calls it
447
+ CVC2, and American Express calls it CID. CVV(II) and CVC2 (Visa/MC) are
448
+ located on the back of the credit card, printed in ink on the signature
449
+ strip. The number is the last three digits on the right hand side of
450
+ the long string of numbers on the strip. In the case of CID (AmEx), the
451
+ number is a four-digit value located on the front of the card, printed
452
+ just above the card number on the left hand side. This value is passed
453
+ to TCLink through the following parameter. </p><p>
454
+ </p><h3 align="center">CVV Parameters </h3>
455
+
456
+ <center>
457
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
458
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
459
+ <tr><td>cvv </td><td>A three or four digit CVV number. </td></tr>
460
+ <tr><td>checkcvv </td><td>Set to "n" to disable CVV check, even if the value is
461
+ passed. Default is "y".</td></tr>
462
+ </tbody></table>
463
+ </center>
464
+
465
+ <p>
466
+ The CVV value will be checked if anything is passed in this parameter.
467
+ (If you don't include the parameter, no CVV test will be run.) If the
468
+ CVV matches, the transaction will run as normal. If it does not, you
469
+ will receive a status of decline, and a declinetype of cvv.
470
+ </p><p>
471
+ In some cases you may wish to pass the CVV code without actually checking to confirm that it
472
+ is correct. In that case set checkcvv=n.
473
+ </p><p>
474
+
475
+ </p><p>
476
+ </p><h3>CVV Example </h3>
477
+
478
+ <pre> params = {
479
+ 'custid': 'mycustid',
480
+ 'password': 'mypasswd',
481
+ 'action': 'sale',
482
+ 'amount': '500',
483
+ 'cc': '4111111111111111',
484
+ 'exp': '0412',
485
+ 'cvv': '123'
486
+ }
487
+
488
+ result = tclink.send(params)
489
+
490
+ if (result['status'] == 'decline'):
491
+ if (result['declinetype'] == 'cvv'):
492
+ print 'The CVV number is not valid.'
493
+ </pre>
494
+
495
+ <p>
496
+ </p><h2><a name="cardpresent"></a>VIII. Card-Present Transactions </h2>
497
+
498
+ <p>In a retail environment with a card swiper, you may wish to pass
499
+ magnetic stripe data along with the other credit card information on a
500
+ preauth or sale. There are two parameters which you can use to send
501
+ this data, named track1 and track2. Each one is for a different type of
502
+ track data, and depends on the type of card reader being used. </p><p>
503
+ </p><h3 align="center">Card-Present Parameters </h3>
504
+
505
+ <center>
506
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
507
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
508
+ <tr><td>track1 </td><td>Up to 79 bytes of Track 1 data. </td></tr>
509
+ <tr><td>track2 </td><td>Up to 40 bytes of Track 2 data. </td></tr>
510
+ </tbody></table>
511
+ </center>
512
+
513
+ <p>
514
+ You can include all data read from the track, but only data between the
515
+ start sentinel (a '%' character for track1 and a ';' for track2) and
516
+ the end sentinel ('?') will be used. Everything outside the start and
517
+ end sentinels (such as the trailing LRC character) will be discarded. </p><p>
518
+ The cc and exp fields may be passed, but are not required, since they
519
+ will be extracted from the track data. If you do pass one or both of
520
+ these fields, however, and it does not match the data extracted from
521
+ the track data, a status of baddata and an error mismatch will be
522
+ returned. </p><p>
523
+ If both track1 and track2 data are passed, the system will choose
524
+ track1 by default for the authorization, and track2 will be discarded. </p><p>
525
+ Generally AVS and address data are not necessary for swiped
526
+ transactions, but you may pass them anyway if you choose. All data
527
+ passed will be saved in the vault and can be downloaded for reports and
528
+ later analysis. </p><p>
529
+ </p><h3>Card Present Example </h3>
530
+
531
+ <pre> params = {
532
+ 'custid': 'mycustid',
533
+ 'password': 'mypasswd',
534
+ 'action': 'sale',
535
+ 'amount': '500'
536
+ }
537
+
538
+ params['track1'] = CardReader.readMagStripe()
539
+
540
+ result = tclink.send(params)
541
+ </pre>
542
+
543
+ <p>
544
+ </p><h2><a name="ach"></a>IX. ACH </h2>
545
+
546
+ <p>
547
+ ACH, also known as electronic checks, is very different from credit
548
+ cards in that it allow a direct debit or credit to a checking account.
549
+ The concept of "authorization" does not exist; it is purely a money
550
+ transfer. For this reason, the only transaction types available for ACH
551
+ are sale and credit. ACH credits are identical to all other types of
552
+ credits in the TrustCommerce system, so please refer to <a href="#credits">postauths, credits and chargebacks </a>for details on issuing credits.
553
+
554
+ </p><p>
555
+ ACH sales take the same parameters as credit card sales, with the
556
+ exception of the "cc" and "exp" fields. Instead, use the following
557
+ parameters. </p><p>
558
+ </p><h3 align="center">ACH Parameters </h3>
559
+
560
+ <center>
561
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
562
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
563
+ <tr><td>routing </td><td>The routing number of the bank being debited. </td></tr>
564
+ <tr><td>account </td><td>The account number of the person or business being debited. </td></tr>
565
+ </tbody></table>
566
+ </center>
567
+
568
+ <p>
569
+ AVS is not available for ACH transactions, so the AVS setting is ignored.
570
+
571
+ </p><p>
572
+ There is only one declinetype returned from unsuccessful ACH sales, and that is "decline."
573
+
574
+ </p><p>
575
+ </p><h3>ACH Example </h3>
576
+
577
+ <pre> params = {
578
+ 'custid': 'mycustid',
579
+ 'password': 'mypass',
580
+ 'action': 'sale',
581
+ 'media': 'ach',
582
+ 'amount': '1000',
583
+ 'routing': '789456124',
584
+ 'account': '55544433221'
585
+ }
586
+
587
+ tclink.send(params)
588
+ </pre>
589
+
590
+ <p>
591
+ </p><h2><a name="credits"></a>X. Postauths, Credits, and Chargebacks </h2>
592
+
593
+ <p>
594
+ These three transaction types are similar in that they reference a
595
+ successful transaction previously executed through the TrustCommerce
596
+ system. These transaction types will not accept credit card information
597
+ or other personal information fields. There is only one required
598
+ parameter. </p><p></p><h3 align="center">Required Parameters </h3>
599
+
600
+ <center>
601
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
602
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
603
+ <tr><td>transid </td><td>The transaction ID (format: nnn-nnnnnnnnnn) of the referenced transaction. </td></tr>
604
+ </tbody></table>
605
+ </center>
606
+
607
+ <p>
608
+ In addition, postauths and credits can take an optional amount parameter.
609
+
610
+ </p><h3 align="center">Optional Parameters </h3>
611
+
612
+ <center>
613
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
614
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
615
+ <tr><td>amount </td><td>The amount, in cents, to credit or postauth if it is not the same as the original amount. </td></tr>
616
+ </tbody></table>
617
+ </center>
618
+
619
+ <p>
620
+ If no amount is passed, the default will be to take the amount from the
621
+ original transaction. If, however, you wish to credit or postauthorize
622
+ less than the original amount, you may pass this parameter. </p><h3>Credit Example </h3>
623
+
624
+ <pre> params = {
625
+ 'custid': 'mycustid',
626
+ 'password': 'mypass',
627
+ 'action': 'credit',
628
+ 'transid': '001-0000111101'
629
+ }
630
+
631
+ tclink.send(params)
632
+
633
+ if (result['status'] != 'accepted'):
634
+ print 'Credit unsuccessful.'
635
+ </pre>
636
+
637
+ <h2><a name="billingids"></a>XI. Citadel (Billing IDs) </h2>
638
+
639
+ <p>
640
+ The Citadel enables you to store customer billing information in an
641
+ encrypted TrustCommerce database. This information can then be recalled
642
+ with a single six-character alphanumeric code known as a billing ID.
643
+ Besides offloading the liability of storing sensitive data such as
644
+ credit card numbers from your business to TrustCommerce, the Citadel
645
+ can also simplify application development on your servers. </p><p>
646
+ The Citadel has two unique actions, store and unstore. These transction
647
+ types allow you to create, update, and deactivate billing IDs. Once
648
+ stored, the billing ID will be passed in place of the many billing
649
+ information fields for preauth and sale transactions. </p><h3 align="center">Store Parameters </h3>
650
+
651
+ <p>The store transaction looks very similar to a preauth or sale. You may pass <a href="#sales">credit card information </a>, billing and shipping address, or even <a href="#ach">ACH </a>information.
652
+
653
+ </p><center>
654
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
655
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
656
+ <tr><td>verify </td><td>When set to "y", a $1.00 preauth will be run on the card to ensure that it is valid. </td></tr>
657
+ <tr><td>billingid </td><td>Pass if you wish to update values of an existing billing ID. </td></tr>
658
+ </tbody></table>
659
+ </center>
660
+
661
+ <p>
662
+ You can update information on existing billing IDs by passing the
663
+ billingid field along with the store transaction. If you wish to erase
664
+ the data contained in a field, pass the exact string "null" (four
665
+ characters, all lower case) as the parameter value. </p><p>
666
+ The verify parameter is useful for ensuring that the card number is
667
+ valid if you are not planning to bill the customer right away. It has
668
+ no effect for ACH billing IDs, because there is no such thing as an ACH
669
+ preauth. It is recommended that you pass avs=y for further verification
670
+ of the cardholder's data. Please note: normally, billing ID storage
671
+ returns a status of accepted, because the card is unverified. If you
672
+ use the verify parameter, however, it will return approved upon
673
+ success. </p><h3 align="center">Unstore Parameters </h3>
674
+
675
+ <p>The unstore action takes a single parameter:
676
+
677
+ </p><center>
678
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
679
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
680
+ <tr><td>billingid </td><td>The six-character alphanumeric billing ID returned by a previous store transaction. </td></tr>
681
+ </tbody></table>
682
+ </center>
683
+
684
+ <p>
685
+ Unstore removes the billing ID from active use, and you won't be able
686
+ to run further transactions on it. For your convenience, however, it
687
+ does remain visible in Vault (flagged as an inactive ID), so you can
688
+ still look up old IDs if needed. </p><h3>Billing ID Example </h3>
689
+
690
+ <p>
691
+ To run a billing ID transaction, pass the billingid parameter to a
692
+ preauth or a sale in place of all of the usual billing info fields
693
+ (name, cc, exp, routing, account, etc). That's all there is to it!
694
+ You'll find that your sale or preauth transactions are now only a few
695
+ parameters: custid, password, billingid, and amount. </p><pre> # First, store a new ID.
696
+ params = {
697
+ 'custid': 'mycustid',
698
+ 'password': 'mypass',
699
+ 'action': 'store',
700
+ 'cc': '4111111111111111',
701
+ 'exp': '0412',
702
+ 'name': 'Jennifer Smith'
703
+ }
704
+
705
+ result = tclink.send(params)
706
+
707
+ if (result['status'] == 'accepted'):
708
+ # It was successfully stored. Now try running a transaction on the new ID.
709
+ billingid = result['billingid']
710
+ params2 = {
711
+ 'custid': 'mycustid',
712
+ 'password': 'mypass',
713
+ 'action': 'sale',
714
+ 'billingid': billingid,
715
+ 'amount': '995'
716
+ }
717
+ tclink.send(params2);
718
+ # Unstore the ID now that we are done.
719
+ params3 = {
720
+ 'custid': 'mycustid',
721
+ 'password': 'mypass',
722
+ 'action': 'unstore',
723
+ 'billingid': billingid
724
+ }
725
+ tclink.send(params3)
726
+ </pre>
727
+
728
+ <h2> <a name="recurring"></a>XII. Recurring Billing </h2>
729
+
730
+ <p>
731
+ Recurring billing (also called "subscription billing") is an extension
732
+ of the billing ID system. There are four parameters that are added to a
733
+ store which turn the billing ID into a recurring billing ID. They are
734
+ described below. </p><h3 align="center">Recurring Parameters </h3>
735
+
736
+ <center>
737
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
738
+ <tbody><tr><th>Parameter Name </th><th>Required? </th><th>Default Value </th><th>Description </th></tr>
739
+ <tr><td>cycle </td><td><p align="center">X </p></td><td>&nbsp;</td><td>Repeat cycle in days, weeks, months, or years. </td></tr>
740
+ <tr><td>amount </td><td><p align="center">X </p></td><td>&nbsp;</td><td>Amount to bill in cents. </td></tr>
741
+ <tr><td>start </td><td><br></td><td>&nbsp;</td><td>Date to start, or else offset from current date (defaults to now). </td></tr>
742
+ <tr><td>payments </td><td><br></td><td>0</td><td>Number of payments to make (defaults to infinite). </td></tr>
743
+ <tr><td>authnow </td><td><br></td><td>n</td><td>If 'y', performs the card authorization immediately. Funds will be captured upon first payment cycle. <i>(requires start date)</i></td></tr>
744
+ <tr><td>lastpaymentunstore </td><td><br></td><td>y</td><td>If 'y', the final payment in the billing cycle will result in the billing ID being unstored. </td></tr>
745
+ </tbody></table>
746
+ </center>
747
+
748
+ <p>
749
+ Cycle is in the format of a number between 1 and 99 followed by a
750
+ character representing the time frame: 'd' for days, 'w' for weeks, 'm'
751
+ for months or 'y' for years. For example, a value of "3d" in this field
752
+ would cause the charge to recur every three days, whereas a value of
753
+ "2m" would cause it to recur every two months. </p><p>
754
+ Amount is identical to the amount passed to a sale or a preauth, and
755
+ indicates the amount of each charge made during the subscription. </p><p>
756
+ Start is an optional field which allows the delay of the cycle's start.
757
+ By default, the cycle starts the day the billing ID is stored. If it is
758
+ specified in the format YYYY-MM-DD, it indicates a date when the first
759
+ payment should be made. (For example, "2005-02-01" would be February 1,
760
+ 2005.) If it is in the same format as the cycle (a number followed by a
761
+ character), it indicates an offset from the current date. (For example,
762
+ "1d" would start the billing tomorrow.) </p><p>
763
+ If there is no start parameter, the first transaction is run
764
+ immediately (and can cause the store action to return a "decline" or
765
+ other result you would expect from a sale). Other return parameters
766
+ associated with auths, such as avs code, will be returned as well. </p><p>
767
+ If you pass authnow=y, an immediate authorization will be performed for
768
+ the payment amount, but the funds will not be captured until the start
769
+ date is reached. This is handy for free trial accounts: because the
770
+ funds are authorized immediately, you are assured the money. If they
771
+ cancel sometime between the time the billing ID is stored and the start
772
+ date of the billing cycle, you can unstore the ID and they will never
773
+ be charged. Their free trial will be the time between the billing ID
774
+ store and the billing cycle start date. Authnow requires that a start
775
+ date be specified.
776
+ </p><p>The payments field is also optional; left blank or set to zero
777
+ it will continue the billing cycle until it is manually interrupted by
778
+ an unstore, or by updating the billing ID with cycle set to "null".
779
+ Once the final payment is made, the billing ID will be unstored, unless
780
+ lastpaymentunstore is set to 'n'. lastpaymentunstore should only be
781
+ used when the number of payments is specified.
782
+ </p><p>There is only one instance in which the cycle parameter is not
783
+ required, and that is a one-time future payment. By setting payments to
784
+ "1" and passing a start date, the payment will be made on that date and
785
+ then the billing ID unstored. The cycle parameter may be included with
786
+ a one-time future payment, but it will have no effect. </p><h3>Recurring Billing Example </h3>
787
+
788
+ <pre> params = {
789
+ 'custid': 'mycustid',
790
+ 'password': 'mypass',
791
+ 'action': 'store',
792
+ 'cc': '4111111111111111',
793
+ 'exp': '0412',
794
+ 'name': 'Jennifer Smith',
795
+ 'amount': '1200'
796
+ }
797
+
798
+ mode = chooseSubscriptionMode()
799
+
800
+ if (mode == 1):
801
+ # Make a payment every day, infinitely (or until someone manually disables it)
802
+ params['cycle'] = '1d';
803
+ elif (mode == 2):
804
+ # Make a payment once a month for one year
805
+ params['cycle'] = '1m';
806
+ params['payments'] = '12';
807
+ elif (mode == 3):
808
+ # Make a payment every six weeks, starting one week from now
809
+ params['cycle'] = '62';
810
+ params['start'] = '1w';
811
+ elif (mode == 4):
812
+ # Make annual payments, and don't start until September 1, 2007
813
+ params['cycle'] = '1y';
814
+ params['start'] = '2007-09-01';
815
+ elif (mode == 5):
816
+ # Make a one time payment in 45 days
817
+ params['start'] = '45d';
818
+ params['payments'] = '1';
819
+
820
+ tclink.send(params)
821
+ </pre>
822
+
823
+ <h2><a name="wallet"></a>XIII. TC Wallet </h2>
824
+
825
+ <p>
826
+ The TC Wallet is an additional service offered by the TrustCommerce
827
+ gateway that allows you to run many small micro payments which are
828
+ later lumped together and submitted as a single, large payment. This
829
+ can offer a substantial savings for the merchant in transaction fees,
830
+ as merchant account providers tend to penalize merchants that run small
831
+ payments. </p><h3 align="center">Wallet Parameters </h3>
832
+
833
+ <p>
834
+ The Wallet is an extension of the billing ID system. It adds three new parameters to the store action, described below.
835
+
836
+ </p><center>
837
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
838
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
839
+ <tr><td>wallet </td><td>"y" to enable the wallet. </td></tr>
840
+ <tr><td>walletsize </td><td><p>Accumulated amount, in cents, before the wallet is submitted for capture. </p></td></tr>
841
+ <tr><td>walletexposure </td><td>Length of time to wait before capturing the wallet. </td></tr>
842
+ </tbody></table>
843
+ </center>
844
+
845
+ <p>
846
+ In order to enable wallets for the billing ID that you are storing, set
847
+ the "wallet" parameter to "y". The other two parameters are optional,
848
+ as there are default values attached to your TC account. If you wish to
849
+ change these default values (which are normally $10.00 and 72 hours)
850
+ please contact TrustCommerce. If you wish to change the values for an
851
+ individual billing ID without changing your defaults, include these
852
+ parameters. </p><p>
853
+ Once the billing ID is stored, it is possible to use a new action type
854
+ on the ID called walletsale. It is identical to a sale in all ways,
855
+ except that it can only be used on wallet-enabled billing IDs, and it
856
+ can accept amounts anywhere from $0.01 up to the size of the wallet.
857
+ Walletsale will usually return "approved", but it may return "decline"
858
+ if the stored credit card fails to re-authorize when the current wallet
859
+ is exceeded. Except for these two modifications (the wallet parameters
860
+ on the store, and changing sales to walletsales), there is no extra
861
+ development to be done client-side to make wallets work. Captures
862
+ happen automatically after walletexposure has expired or the
863
+ walletamount has been used up; reauthorizations also happen
864
+ automatically. </p><h3>Wallet Example </h3>
865
+
866
+ <pre> # First, store a new ID with the wallet enabled.
867
+ params = {
868
+ 'custid': 'mycustid',
869
+ 'password': 'mypass',
870
+ 'action': 'store',
871
+ 'cc': '4111111111111111',
872
+ 'exp': '0412',
873
+ 'name': 'Jennifer Smith',
874
+ 'wallet': 'y'
875
+ }
876
+
877
+ result = tclink.send(params)
878
+
879
+ if (result['status'] == 'approved'):
880
+ # We have a new wallet at our disposal. Run a micropayment on it.
881
+ billingid = result['billingid']
882
+ params2 = {
883
+ 'custid': 'mycustid',
884
+ 'password': 'mypass',
885
+ 'action': 'walletsale',
886
+ 'billingid': billingid,
887
+ 'amount': '995'
888
+ }
889
+ tclink.send(params)
890
+ </pre>
891
+
892
+ <a name="crediguard-neural"></a><h2>XIV. CrediGuard - Neural Network Fraud Scoring</h2>
893
+
894
+ When the CrediGuard Neural Network is enabled, a fraud score is assigned to
895
+ each transaction based on its appearance of fraud or legitimacy. This score is
896
+ determined by running each transaction through an advanced artificial
897
+ intelligence neural network that is trained to recognize fraudulent
898
+ transactions.<p>
899
+
900
+ The fraud score represents an evaluation of how legitimate or fraudulent the
901
+ transaction appears. A fraud score close to 0 means that the transaction is
902
+ likely to be fraudulent, while a fraud score close to 100 means that the
903
+ transaction is likely to be legitimate.</p><p>
904
+
905
+ The CrediGuard Score Threshold is a number from 0 to 100 that controls how
906
+ restrictive the CrediGuard fraud screening system should be. Any transaction
907
+ with a fraud score less than the CrediGuard score threshold will be declined.
908
+ All other transactions will be accepted as per usual. The following chart sums
909
+ up the effects of the possible CrediGuard score threshold ranges:
910
+
911
+ </p><p>
912
+ </p><center>
913
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
914
+ <tbody><tr><th>Score Threshold Range</th>
915
+ <th>Blocking Effect</th></tr>
916
+
917
+ <tr><td align="right">0</td><td>Allow All</td></tr>
918
+ <tr><td align="right">1 - 25</td><td>Allow Most</td></tr>
919
+ <tr><td align="right">26 - 50</td><td>Normal</td></tr>
920
+ <tr><td align="right">51 - 75</td><td>Restrictive</td></tr>
921
+ <tr><td align="right">76 - 100</td><td>Highly Restrictive</td></tr>
922
+ </tbody></table>
923
+ </center>
924
+ <p>
925
+
926
+ The default score threshold can be configured within the Vault web interface.
927
+ To override the default score threshold, you can optionally pass in an extra
928
+ parameter to set a different score threshold for the current transaction only:
929
+
930
+ </p><h3 align="center">CrediGuard Parameters</h3>
931
+
932
+ <p>
933
+ </p><center>
934
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
935
+ <tbody><tr><th>Parameter Name</th><th>Description</th></tr>
936
+ <tr><td>threshold</td><td>The fraud threshold for the current
937
+ transaction. If the transaction receives a Fraud Score below this
938
+ threshold, it will be declined.</td></tr>
939
+ </tbody>
940
+ </table>
941
+ </center>
942
+ <p>
943
+
944
+ With Neural Network scoring enabled, the return parameters for each
945
+ transaction will contain an additional parameter for the calculated fraud
946
+ score:
947
+
948
+ </p><h3 align="center">CrediGuard Return Parameters</h3>
949
+
950
+ <p>
951
+ </p><center>
952
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
953
+ <tbody><tr><th>Parameter Name</th><th>Description</th></tr>
954
+ <tr><td>fraudscore</td><td>The actual numeric score, 0 to 100, that the Crediguard Neural Network gave to the transaction.</td></tr>
955
+ </tbody>
956
+ </table>
957
+ </center>
958
+ <p>
959
+
960
+ </p><h3>CrediGuard Neural Network Example </h3>
961
+
962
+ <pre> params = {
963
+ 'custid': 'mycustid',
964
+ 'password': 'mypasswd',
965
+ 'action': 'sale',
966
+ 'amount': '500',
967
+ 'cc': '4111111111111111',
968
+ 'exp': '0412',
969
+ 'threshold': '45',
970
+ }
971
+
972
+ result = tclink.send(params)
973
+
974
+ if (result['status'] == 'decline'):
975
+ if (result['declinetype'] == 'fraud'):
976
+ print 'Transaction declined based on fraud score.'
977
+ </pre>
978
+
979
+ You may also wish to handle the score result yourself, perhaps with fuzzy logic
980
+ that treats a certain range of low scores as out-and-out declines, a high
981
+ range as approvals, and a middle range as accepting pending further processing.
982
+ The last category of transactions could be set aside in your local database or
983
+ perhaps trigger an email to a customer service rep, who could manually review
984
+ the transaction, and perhaps call the customer for verification.
985
+ <p>
986
+
987
+ </p><h3>CrediGuard Fuzzy Logic Scoring Example </h3>
988
+
989
+ <pre> score_bottom = 30
990
+ score_top = 70
991
+
992
+ params = {
993
+ 'custid': 'mycustid',
994
+ 'password': 'mypasswd',
995
+ 'action': 'sale',
996
+ 'amount': '500',
997
+ 'cc': '4111111111111111',
998
+ 'exp': '0412',
999
+ 'threshold': score_bottom
1000
+ }
1001
+
1002
+ result = tclink.send(params)
1003
+
1004
+ if (result['status'] == 'decline'):
1005
+ if (result['declinetype'] == 'fraud'):
1006
+ print 'Transaction declined, score was too low.'
1007
+
1008
+ if (result['status'] == 'approved'):
1009
+ if (result['fraudscore'] &gt; score_top):
1010
+ print 'Transaction approved'
1011
+ else:
1012
+ print 'Transaction accepted pending review'
1013
+
1014
+
1015
+ </pre>
1016
+
1017
+ <a name="crediguard-blacklist"></a><h2>XV. CrediGuard - Blacklists</h2>
1018
+
1019
+ Blacklists are used to block specific cardholder information that you know to
1020
+ be fraudlent. The most common example would be a customer who keeps using a
1021
+ credit card that caused chargebacks in the past. You can block the customer
1022
+ from running charges on the card by entering their credit card number as a
1023
+ blacklist value.<p>
1024
+
1025
+ Blacklist rules are configured from within the Vault web interface and
1026
+ apply to all transactions, so there are no blacklist input parameters that
1027
+ you need to pass in with TCLink.</p><p>
1028
+
1029
+ If a transaction is declined because it matches a blacklist rule that you
1030
+ have created, the reason for this decline will be returned via the following
1031
+ parameters:
1032
+
1033
+ </p><p>
1034
+ </p><h3 align="center">Blacklist Return Parameters</h3>
1035
+ <center>
1036
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1037
+ <tbody><tr><th>Parameter Name</th><th>Description</th></tr>
1038
+ <tr><td>blacklistfield</td><td>The name of the input field that
1039
+ contained the blacklisted value. This can be one of "name", "cc",
1040
+ "zip", "address1", "state", "country", "email", "phone", or "ip".</td></tr>
1041
+ <tr><td>blacklistvalue</td><td>The input value that triggered the
1042
+ blacklist decline. For instance, if the decline was due to a
1043
+ blacklisted IP address, the offending IP address would be returned here.</td></tr>
1044
+ </tbody>
1045
+ </table>
1046
+ </center>
1047
+ <p>
1048
+
1049
+ </p><h3>Blacklist Example </h3>
1050
+
1051
+ <pre> params = {
1052
+ 'custid': 'mycustid',
1053
+ 'password': 'mypasswd',
1054
+ 'action': 'sale',
1055
+ 'amount': '500',
1056
+ 'cc': '4111111111111111',
1057
+ 'exp': '0412',
1058
+ }
1059
+
1060
+ result = tclink.send(params)
1061
+
1062
+ if (result['status'] == 'decline'):
1063
+ if (result['declinetype'] == 'blacklist'):
1064
+ print 'Transaction declined based on blacklist rule.'
1065
+ print 'The offending field was: ' + result['blacklistfield']
1066
+ print 'And the blacklisted value was: ' + result['blacklistvalue']
1067
+
1068
+ </pre>
1069
+
1070
+ <a name="crediguard-velocity"></a><h2>XVI. CrediGuard - Velocity Control</h2>
1071
+
1072
+ In the world of payment processing, 'velocity' refers to limiting the number
1073
+ or amount of transactions which occur over a set period of time. This allows
1074
+ you, the merchant, to control your risk. The most common use of velocity
1075
+ would be to limit the dollar amount spent per day on a single credit card.
1076
+ But the CrediGuard package supports a wide variety of velocity parameters,
1077
+ allowing you to tailor them to match the usage patterns of your customers and
1078
+ thereby control your risk factor.
1079
+
1080
+ <p>
1081
+ CrediGuard can perform four different types of velocity checks:
1082
+ </p><p>
1083
+ </p><h3 align="center">Velocity Types</h3>
1084
+ <center>
1085
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1086
+ <tbody><tr><th>Velocity Type</th><th>Description</th></tr>
1087
+ <tr><td>Global</td><td>All transactions</td></tr>
1088
+ <tr><td>Zipcode</td><td>Transactions on the same zipcode</td></tr>
1089
+ <tr><td>IP Address</td><td>Transactions sent from the same Internet address</td></tr>
1090
+ <tr><td>Credit Card</td><td>Transactions on the same credit card</td></tr>
1091
+ </tbody>
1092
+ </table>
1093
+ </center>
1094
+ <p>
1095
+
1096
+ Each of the four velocity types offers a <b>count</b> (number of transactions)
1097
+ and a <b>total</b> (dollar amount sum). For each of those two values, there
1098
+ are four time periods, ranging from one day to one month. All of these
1099
+ velocity settings are configured from within the Vault web interface and apply
1100
+ to all transactions, so there are no velocity input parameters that you need
1101
+ to pass in with TCLink.</p><p>
1102
+
1103
+ If a transaction is declined on the basis of exceeding one of these velocity
1104
+ settings, the reason for this decline will be returned via the following
1105
+ parameters:
1106
+
1107
+ </p><p>
1108
+ </p><h3 align="center">Velocity Return Parameters</h3>
1109
+ <center>
1110
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1111
+ <tbody><tr><th>Parameter Name</th><th>Description</th></tr>
1112
+ <tr><td>velocitytype</td><td>A brief string that contains the precise
1113
+ reason for the velocity decline. The first part of this string contains
1114
+ a velocity type, either "global", "zip", "ip", or "cc". The next part
1115
+ of the string contains a time period, either "1day", "3day", "15day",
1116
+ or "30day". The end of the string is "count" if the transaction count
1117
+ for the velocity type and time period was exceeded, or "total" if the
1118
+ dollar amount sum was exceeded. For example, "zip3daycount" would be
1119
+ returned if the velocity transaction count was exceeded for a
1120
+ particular zip code in a three day period.</td></tr>
1121
+ <tr><td>velocityvalue</td><td>The input value that triggered the
1122
+ velocity decline. For instance, if the decline was due to a zip code
1123
+ velocity setting, the offending zip code would be returned here.</td></tr>
1124
+ </tbody>
1125
+ </table>
1126
+ </center>
1127
+ <p>
1128
+
1129
+ </p><h3>Velocity Example </h3>
1130
+
1131
+ <pre> params = {
1132
+ 'custid': 'mycustid',
1133
+ 'password': 'mypasswd',
1134
+ 'action': 'sale',
1135
+ 'amount': '500',
1136
+ 'cc': '4111111111111111',
1137
+ 'exp': '0412',
1138
+ }
1139
+
1140
+ result = tclink.send(params)
1141
+
1142
+ if (result['status'] == 'decline'):
1143
+ if (result['declinetype'] == 'velocity'):
1144
+ print 'Transaction declined based on ' + result['velocitytype'] + ' velocity controls.'
1145
+ </pre>
1146
+
1147
+ <h2><a name="pl2"></a>XVII. Purchase Level II </h2>
1148
+
1149
+ <p>
1150
+ Purchase Level II is required by some merchant banks to achieve a
1151
+ qualified discount rate. It is only used for B2B or B2G transactions.
1152
+ If you are selling products directly to consumers, you do not need to
1153
+ use PL2. Additionally, PL2 can only be used if the cardholder is using
1154
+ one of the three types of commercial cards: a corporate card, a
1155
+ business card, or a purchasing card. </p><h3 align="center">PL2 Input Parameters </h3>
1156
+
1157
+ <p>
1158
+ PL2 has three new parameters:
1159
+
1160
+ </p><center>
1161
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1162
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
1163
+ <tr><td>purchaselevel </td><td>Specify as "2". </td></tr>
1164
+ <tr><td>purchaseordernum </td><td>The
1165
+ purchasing order number from their Visa purchasing card. This is either
1166
+ a 16 or a 17 digit number. If they are not using a Visa purchasing
1167
+ card, do not pass this field. </td></tr>
1168
+ <tr><td>tax </td><td>The amount of tax, in cents, charged for the order. If the order is tax exempt omit this field or set it to 0. </td></tr>
1169
+ </tbody></table>
1170
+ </center>
1171
+
1172
+ <p>
1173
+
1174
+ </p><h3 align="center">PL2 Output Parameter </h3>
1175
+
1176
+ <p>
1177
+ A successful PL2 transaction will return one extra response parameter
1178
+ </p><center>
1179
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1180
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
1181
+ <tr><td>commercialcard </td><td>Set to "S" for if it is a purchasing card, "R" if it is corporate card, and "B" if it is a business card. </td></tr>
1182
+ </tbody></table>
1183
+ </center>
1184
+
1185
+ <p>
1186
+ If you don't care what kind of card they used (which you probably
1187
+ don't), there is no reason to store or otherwise do anything with the
1188
+ commercialcard return value. TrustCommerce internally handles all the
1189
+ details for you. However, if you want this information for some reason,
1190
+ you can access it from the result parameters. </p><h3>Purchase Level II Example </h3>
1191
+
1192
+ <pre> params = {
1193
+ 'custid': 'mycustid',
1194
+ 'password': 'mypass',
1195
+ 'action': 'sale',
1196
+ 'cc': '4111111111111111',
1197
+ 'exp': '0412',
1198
+ 'amount': '1000'
1199
+ 'name': 'Jennifer Smith',
1200
+ 'purchaselevel': '2'
1201
+ 'purchaseordernum': '12345678901234567'
1202
+ 'tax': '83' # $10.00 x 8.25% sales tax = $0.83
1203
+
1204
+ }
1205
+
1206
+ result = tclink.send(params)
1207
+
1208
+ if (result['status'] == 'approved'):
1209
+ print 'Approved'
1210
+ </pre>
1211
+
1212
+ <h2><a name="orderdetail"></a>XVIII. Automated Fulfillment </h2>
1213
+
1214
+ <p>
1215
+ TrustCommerce offers the unique feature of automated fulfillment, by
1216
+ which orders submitted through the TCLink API can contain parameters
1217
+ describing product information. This information is then passed on to
1218
+ your fulfillment house, which ships the products automatically. Even if
1219
+ you aren't using automated fulfillment, you can use the order line item
1220
+ specification parameters to store information in the TrustCommerce
1221
+ transaction database about the type of products ordered. </p><p>
1222
+ First, you may wish to specify the shipping address for the customer.
1223
+ If it is the same as the billing address, you need not duplicate it,
1224
+ but rather just send the shiptosame parameter set to y. The table below
1225
+ lists the shipping parameters. </p><h3 align="center">Ship To Parameters </h3>
1226
+
1227
+ <center>
1228
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1229
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
1230
+ <tr><td>shiptosame </td><td>y or n (defaults to n). If "y", then no other shipto_ parameters should be passed. </td></tr>
1231
+ <tr><td>shipto_name </td><td>Name of the product recipient. </td></tr>
1232
+ <tr><td>shipto_address1 </td><td>First line of shipping address. </td></tr>
1233
+ <tr><td>shipto_address2 </td><td>Second line (if any) of shipping address. </td></tr>
1234
+ <tr><td>shipto_city </td><td>City. </td></tr>
1235
+ <tr><td>shipto_state </td><td>State. </td></tr>
1236
+ <tr><td>shipto_zip </td><td>Zip code, five or nine digits (no spaces or dashes). </td></tr>
1237
+ <tr><td>shipto_country </td><td>Country, leave blank for US. </td></tr>
1238
+ </tbody></table>
1239
+ </center>
1240
+
1241
+ <p>
1242
+
1243
+ </p><h3 align="center">Order Header Parameters </h3>
1244
+
1245
+ <p>
1246
+ Second, some additional data about the order as a whole should be passed in the form of the following parameters.
1247
+
1248
+ </p><center>
1249
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1250
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
1251
+ <tr><td>shippingcode </td><td>Three character code indicating shipping method to use. </td></tr>
1252
+ <tr><td>shippinghandling </td><td>The total cost of shipping and handling, in cents. </td></tr>
1253
+ <tr><td>numitems </td><td>Total number of distinct items (product codes) in the order. </td></tr>
1254
+ </tbody></table>
1255
+ </center>
1256
+
1257
+ <p>
1258
+
1259
+ </p><h3 align="center">Order Detail Parameters </h3>
1260
+
1261
+ <p>
1262
+ Finally, a number of parameters which describe the details of each type
1263
+ of item must be passed. In the table below, the 'X' character in the
1264
+ parameter name should be replaced with a digit indicating which item it
1265
+ applies to. For example, if numitems is set to three, then you should
1266
+ pass three product codes, in the form of productcode1, productcode2,
1267
+ and productcode3. </p><center>
1268
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1269
+ <tbody><tr><th>Parameter Name </th><th>Description </th></tr>
1270
+ <tr><td>productcodeX </td><td>The alphanumeric product code defined by the fulfillment house. </td></tr>
1271
+ <tr><td>quantityX </td><td>The number of items of this type to be shipped. </td></tr>
1272
+ <tr><td>priceX </td><td>The price of all items of this type not including sales tax or shipping, in cents. </td></tr>
1273
+ <tr><td>taxX </td><td>Total tax charged for all items of this product code. </td></tr>
1274
+ <tr><td>shippinghandlingX </td><td>Total shipping and handling charged for all items of this product code. </td></tr>
1275
+ </tbody></table>
1276
+ </center>
1277
+
1278
+ <p>
1279
+ Please note: the shippinghandling field and the shippinghandlingX
1280
+ fields are mutually exclusive. Use one or the other, but not both. If
1281
+ you're not sure which to use, please contact your fulfillment house. </p><h3>Fulfillment Example </h3>
1282
+
1283
+ <pre> params = {
1284
+ 'custid': 'mycustid',
1285
+ 'password': 'mypass',
1286
+ 'action': 'preauth',
1287
+ 'cc': '4111111111111111',
1288
+ 'exp': '0412',
1289
+ 'amount': '1979', # Total of items, tax, and shipping
1290
+ 'name': 'Jennifer Smith',
1291
+ 'address1': '123 Test St.',
1292
+ 'city': 'Somewhere',
1293
+ 'state': 'CA',
1294
+ 'zip': '90001',
1295
+ 'shiptosame': 'y', # Shipping address is same as billing address
1296
+
1297
+ 'numitems': '2', # Two total product codes will be described
1298
+ 'shippingcode': 'OVRNGT',
1299
+ 'shippinghandling': '695',
1300
+
1301
+ 'productcode1': 'PCODE1',
1302
+ 'quantity1': '3',
1303
+ 'price1': '600', # Item 1 costs $2.00, and there are 3 of them
1304
+ 'tax1': '144', # Tax of 8%
1305
+
1306
+ 'productcode2': 'PCODE2',
1307
+ 'quantity2': '1',
1308
+ 'price2': '500', # Item 1 costs $5.00, there's only one
1309
+ 'tax2': '40' # Tax of 8%
1310
+ }
1311
+
1312
+ tclink.send(params)
1313
+ </pre>
1314
+
1315
+ <h2><a name="batchProcessing"></a>XIX. Batch Processing </h2>
1316
+
1317
+ <p>
1318
+ The TrustCommerce Batch Processing service allows programmers to submit
1319
+ an unlimited number of transactions in a single file for offline
1320
+ processing. The file can contain a mixture of transaction types
1321
+ (preauths and postauths, credits, sales, stores and unstores for
1322
+ example) and can use Citadel Billing IDs, ACH Routing codes or credit
1323
+ card information to identify the account to be charged. In fact, any
1324
+ field found in <u>Appendix E �&#8364;&#8220; Input Field List</u> of this guide can be included.
1325
+
1326
+ </p><h3 align="center">Naming Conventions </h3>
1327
+
1328
+ <p>
1329
+ While there is no required naming convention for the transaction file
1330
+ sent to TrustCommerce, we recommend the convention shown in the table
1331
+ below. </p><p>
1332
+ The results file that we return to you will use your file name with the prefix "result-".
1333
+
1334
+ </p><center>
1335
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1336
+ <tbody><tr><th>Recommended File Name</th><th>Description</th></tr>
1337
+ <tr><td>batch-[custid]-[mmddyy][x].txt </td><td>This is the input file containing the list of transactions to be processed.
1338
+ <p><br>This
1339
+ file MUST be in comma separated values (CSV) format and the first row
1340
+ MUST contain the field names for all fields that you choose to include
1341
+ (See <a href="#inputfields"><u>Appendix E </u></a>.) Individual records are not required to contain values for each field.
1342
+ </p><p>[custid] is your numeric TrustCommerce custid. [mmddyy] is a numeric date.
1343
+ </p><p>[x] is an optional alpha identifier to distinguish batches if multiple batches are sent in one day.
1344
+ </p><p>Do not include the "[" or "]"characters in the file name. </p></td></tr>
1345
+ <tr><td>result-[your file name].txt </td><td>This file contains a response record for each transaction record sent in the batch file. </td></tr>
1346
+ </tbody></table>
1347
+ </center>
1348
+ <p>
1349
+ </p><center>
1350
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1351
+ <tbody><tr><td>NOTE:
1352
+ The records in the results file will be sequenced in exactly the same
1353
+ order as the original input file. If you require a more positive
1354
+ identifier for each record (invoice number for example) include the
1355
+ required value in the "ticket" field of your input file. This value
1356
+ will be echoed back to you in the "ticket" field of the results file.
1357
+ See the examples below.</td></tr>
1358
+ </tbody></table>
1359
+ </center>
1360
+
1361
+ <p>
1362
+ <b>Sample Batch Upload File</b>
1363
+
1364
+ </p><p>
1365
+ To invoke the Batch Processing service use your programming language's HTTPS POST function and point it at <a href="https://batch.trustcommerce.com/submit.php"><u>https://batch.trustcommerce.com/submit.php </u></a>.
1366
+
1367
+ </p><p>
1368
+ A sample batch upload file might look like this:
1369
+
1370
+ </p><pre> ticket,action,cc,exp,amount,name,email
1371
+ 01-1224,sale,4111111111111111,0412,999,Test Person,person@example.com
1372
+ 00-1175,preauth,4111111111111111,0412,333,Test Person,person@example.com
1373
+ </pre>
1374
+
1375
+ <p>
1376
+ <b>Sample Batch Response File</b>
1377
+
1378
+ </p><p>The response file will contain one response record for each uploaded transaction record.
1379
+
1380
+ </p><p>
1381
+ The results file can then be downloaded interactively from the Vault or
1382
+ by invoking your language's HTTPS POST function pointed at <a href="https://batch.trustcommerce.com/download.php"><u>https://batch.trustcommerce.com/download.php </u></a>.
1383
+
1384
+ </p><p>
1385
+ A sample response file might look like this:
1386
+
1387
+ </p><pre>ticket,status,transid,billingid,declinetype,errortype,offenders,avs
1388
+ 01-1224,approved,010-0001364786,,,,,N
1389
+ 00-1175,approved,010-0001364785,,,,,N
1390
+ </pre>
1391
+
1392
+ <p>
1393
+ <b>Status Reporting</b>
1394
+
1395
+ </p><p>
1396
+ Email is the primary means used by the Batch Processing service to
1397
+ provide status updates. Status updates will be sent to the same email
1398
+ address used for Daily Reports emails. This email address can be
1399
+ modifed on the "Settings" page of the Vault's web interface.
1400
+ </p><p>After uploading your file, the system will respond immediately
1401
+ with an "Acknowledged" message and then follow by sending an email with
1402
+ a subject similar to the following: </p><p>
1403
+ Subject: Batch File [your file name] Picked Up
1404
+
1405
+ </p><p>
1406
+ The content of the mail will provide processing statistics including the number of records found in the file.
1407
+
1408
+ </p><p>
1409
+ When processing is complete, a second e-mail will be sent. The subject this time will look like:
1410
+
1411
+ </p><p>
1412
+ Subject: Batch File [your file name] Complete
1413
+
1414
+ </p><p>
1415
+ The body of this email will contain relevant information including the number of approvals, declines, accepts and settlements.
1416
+
1417
+ </p><p>
1418
+ <b>Sample Code</b>
1419
+
1420
+ </p><p>
1421
+ The sample HTML code shown below illustrates the functionality of the
1422
+ Batch Processing service invocation of the TCLink API. It can be pasted
1423
+ into a file and loaded on your web browser in order to experiment with
1424
+ batch processing before you even begin to write your code. </p><p>
1425
+ <b>Batch Upload Example</b>
1426
+
1427
+ </p><pre> &lt;html&gt;
1428
+ &lt;head&gt; &lt;title&gt; TrustCommerce Batch Upload Interface &lt;/title&gt; &lt;/head&gt;
1429
+ &lt;body&gt;
1430
+ &lt;h2&gt; TrustCommerce Batch Upload Interface &lt;/h2&gt;
1431
+
1432
+ &lt;form action=https://batch.trustcommerce.com/submit.php method=post
1433
+ enctype=multipart/form-data&gt;
1434
+ &lt;table align=center border=1&gt;
1435
+ &lt;tr&gt;
1436
+ &lt;td&gt; custid &lt;/td&gt;
1437
+ &lt;td&gt; &lt;input type=text name=custid&gt; &lt;/td&gt;
1438
+ &lt;td&gt; This is your TrustCommerce custid (required) &lt;/td&gt;
1439
+ &lt;/tr&gt;
1440
+ &lt;tr&gt;
1441
+ &lt;td&gt; password &lt;/td&gt;
1442
+ &lt;td&gt; &lt;input type=password name=password&gt; &lt;/td&gt;
1443
+ &lt;td&gt; This is your TrustCommerce password (required) &lt;/td&gt;
1444
+ &lt;/tr&gt;
1445
+ &lt;tr&gt;
1446
+ &lt;td&gt; batch file &lt;/td&gt;
1447
+ &lt;td&gt; &lt;input name=file type=file&gt; &lt;/td&gt;
1448
+ &lt;td&gt; This is the batch file to upload (required) &lt;/td&gt;
1449
+ &lt;/tr&gt;
1450
+ &lt;tr&gt;
1451
+ &lt;td colspan=3&gt; &lt;input type=submit&gt; &lt;/td&gt;
1452
+ &lt;/tr&gt;
1453
+ &lt;/table&gt;
1454
+ &lt;/form&gt;
1455
+ &lt;/body&gt;
1456
+ &lt;/html&gt;
1457
+ </pre>
1458
+
1459
+ <p>
1460
+ <b>Batch Results Download Example</b>
1461
+
1462
+ </p><pre> &lt;html&gt;
1463
+ &lt;head&gt; &lt;title&gt; TrustCommerce Batch Results Download Interface &lt;/title&gt; &lt;/head&gt;
1464
+ &lt;body&gt;
1465
+ &lt;h2&gt; TrustCommerce Batch Results Download Interface &lt;/h2&gt;
1466
+
1467
+ &lt;form action=https://batch.trustcommerce.com/download.php method=post&gt;
1468
+ &lt;table align=center border=1&gt;
1469
+ &lt;tr&gt;
1470
+ &lt;td&gt; custid &lt;/td&gt;
1471
+ &lt;td&gt; &lt;input type=text name=custid&gt; &lt;/td&gt;
1472
+ &lt;td&gt; This is your TrustCommerce custid (required) &lt;/td&gt;
1473
+ &lt;/tr&gt;
1474
+ &lt;tr&gt;
1475
+ &lt;td&gt; password &lt;/td&gt;
1476
+ &lt;td&gt; &lt;input type=password name=password&gt; &lt;/td&gt;
1477
+ &lt;td&gt; This is your TrustCommerce password (required) &lt;/td&gt;
1478
+ &lt;/tr&gt;
1479
+ &lt;tr&gt;
1480
+ &lt;td&gt; result file name &lt;/td&gt;
1481
+ &lt;td&gt; &lt;input name=file type=text&gt; &lt;/td&gt;
1482
+ &lt;td&gt; This is the result file name to download (required) &lt;/td&gt;
1483
+ &lt;/tr&gt;
1484
+ &lt;tr&gt;
1485
+ &lt;td colspan=3&gt; &lt;input type=submit&gt; &lt;/td&gt;
1486
+ &lt;/tr&gt;
1487
+ &lt;/table&gt;
1488
+ &lt;/form&gt;
1489
+ &lt;/body&gt;
1490
+ &lt;/html&gt;
1491
+ </pre>
1492
+
1493
+ <h2> <a name="query"></a>XX. Vault Query API </h2>
1494
+
1495
+ <p>
1496
+ The Vault website serves as a web-based interface for merchant
1497
+ reconciliation. On the back end, it is a complex database that tracks
1498
+ all transactional data for your TrustCommerce account. The information
1499
+ contained in the Vault can be accessed at the API level using a
1500
+ standard CGI query over HTTPS. </p><p>
1501
+ The query API returns data in CSV (comma separated value) format, which
1502
+ is just a flat text file with fields separated by commas, and records
1503
+ separated by newlines. (You can also request the data returned in an
1504
+ HTML table, which is useful for debugging.) The first line of the file
1505
+ contains the name of each field that will be returned in subsequent
1506
+ records. </p><p>
1507
+ The parameters that the query interface accepts are described in the table below.
1508
+
1509
+ </p><h3 align="center">Required Parameters </h3>
1510
+
1511
+ <center>
1512
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1513
+ <tbody><tr><th>Parameter Name </th><th>Required? </th><th>Description </th></tr>
1514
+ <tr><td>custid </td><td><p align="center">X </p></td><td>TrustCommerce customer ID number. </td></tr>
1515
+ <tr><td>password </td><td><p align="center">X </p></td><td>The password for your custID. </td></tr>
1516
+ <tr><td>format </td><td><br></td><td>Set to "html" for human-readable HTML output, or "text" (default) for CSV text output. </td></tr>
1517
+ <tr><td>querytype </td><td><p align="center">X </p></td><td>Possible
1518
+ values are: chain, transaction, summary, or billingid, corresponding to
1519
+ the equivalent reports on the Vault website. Read the User's Guide for
1520
+ further description of each report type. </td></tr>
1521
+ <tr><td>media </td><td><br></td><td>Set to "cc" (default) or "ach" for media type. </td></tr>
1522
+ <tr><td>begindate </td><td><br></td><td>Begin date for query, format: MM-DD-YYYY HH:MM:SS </td></tr>
1523
+ <tr><td>enddate </td><td><br></td><td>End date for query, format: MM-DD-YYYY HH:MM:SS </td></tr>
1524
+ <tr><td>chain </td><td><br></td><td>Narrow search to a single chain of transactions. </td></tr>
1525
+ <tr><td>transid </td><td><br></td><td>Narrow search to a single transaction ID. </td></tr>
1526
+ <tr><td>billingid </td><td><br></td><td>Narrow search to a single billing ID. </td></tr>
1527
+ <tr><td>pastdue </td><td><br></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>
1528
+ <tr><td>action </td><td><br></td><td>Narrow search by action (preauth, sale, credit, etc). </td></tr>
1529
+ <tr><td>status </td><td><br></td><td>Narrow search by status (approved, accepted, decline, etc). </td></tr>
1530
+ <tr><td>name </td><td><br></td><td>Narrow search by cardholder name, partial or complete. </td></tr>
1531
+ <tr><td>cc </td><td><br></td><td>Narrow search by credit card number. </td></tr>
1532
+ <tr><td>ticket </td><td><br></td><td>Narrow search by contents of the ticket field. </td></tr>
1533
+ <tr><td>limit </td><td><br></td><td>Do not allow size of result set to exceed this number of records. </td></tr>
1534
+ <tr><td>offset </td><td><br></td><td>Report
1535
+ result set starting from this offset. Use this parameter in conjunction
1536
+ with limit in order to page through a large result set. </td></tr>
1537
+ <tr><td>showcount </td><td><br></td><td>Show the number of records returned on the last line of the result set. </td></tr>
1538
+ </tbody></table>
1539
+ </center>
1540
+
1541
+ <p>
1542
+ The sample HTML code shown below illustrates the functionality of the
1543
+ query API. It can be pasted into a file and loaded on your web browser
1544
+ in order to try out some queries before you even begin to write your
1545
+ code. </p><h3>Query Example HTML </h3>
1546
+
1547
+ <pre>&lt;html&gt;
1548
+ &lt;head&gt; &lt;title&gt; TrustCommerce Query Interface &lt;/title&gt; &lt;/head&gt;
1549
+ &lt;body&gt;
1550
+ &lt;h2&gt; TrustCommerce Query Interface &lt;/h2&gt;
1551
+ &lt;form action=https://vault.trustcommerce.com/query/&gt;
1552
+ &lt;table align=center border=1&gt;
1553
+ &lt;tr&gt;
1554
+ &lt;td&gt; custid &lt;/td&gt;
1555
+ &lt;td&gt; &lt;input type=text name=custid&gt; &lt;/td&gt;
1556
+ &lt;td&gt; This is your TrustCommerce custid (required) &lt;/td&gt;
1557
+ &lt;/tr&gt;
1558
+ &lt;tr&gt;
1559
+ &lt;td&gt; password &lt;/td&gt;
1560
+ &lt;td&gt; &lt;input type=password name=password&gt; &lt;/td&gt;
1561
+ &lt;td&gt; This is your TrustCommerce password (required) &lt;/td&gt;
1562
+ &lt;/tr&gt;
1563
+ &lt;tr&gt;
1564
+ &lt;td&gt; format &lt;/td&gt;
1565
+ &lt;td&gt; &lt;select name=format&gt; &lt;option value=text&gt;text&lt;/option&gt;
1566
+ &lt;option value=html&gt;html&lt;/option&gt;&lt;/select&gt;&lt;/td&gt;
1567
+ &lt;td&gt; Human readable (html) or computer readable (text) results&lt;/td&gt;
1568
+ &lt;/tr&gt;
1569
+ &lt;tr&gt;
1570
+ &lt;td&gt; Query type &lt;/td&gt;
1571
+ &lt;td&gt; &lt;select name=querytype&gt;
1572
+ &lt;option value=chain&gt;chain&lt;/option&gt;
1573
+ &lt;option value=transaction&gt;transaction&lt;/option&gt;
1574
+ &lt;option value=summary&gt;summary&lt;/option&gt;
1575
+ &lt;option value=billingid&gt;billingid&lt;/option&gt;
1576
+ &lt;/select&gt;&lt;/td&gt;
1577
+ &lt;td&gt; Type of query &lt;/td&gt;
1578
+ &lt;/tr&gt;
1579
+ &lt;tr&gt;
1580
+ &lt;td&gt; media &lt;/td&gt;
1581
+ &lt;td&gt; &lt;input type=text name=media value=cc&gt; &lt;/td&gt;
1582
+ &lt;td&gt; For now this must be cc &lt;/td&gt;
1583
+ &lt;/tr&gt;
1584
+ &lt;tr&gt;
1585
+ &lt;td&gt; begindate MM-DD-YYYY HH:MM:SS &lt;/td&gt;
1586
+ &lt;td&gt; &lt;input type=text name=begindate&gt; &lt;/td&gt;
1587
+ &lt;td&gt; Query begins at this date&lt;/td&gt;
1588
+ &lt;/tr&gt;
1589
+ &lt;tr&gt;
1590
+ &lt;td&gt; enddate MM-DD-YYYY HH:MM:SS &lt;/td&gt;
1591
+ &lt;td&gt; &lt;input type=text name=enddate&gt; &lt;/td&gt;
1592
+ &lt;td&gt; Query ends at this date&lt;/td&gt;
1593
+ &lt;/tr&gt;
1594
+ &lt;tr&gt;
1595
+ &lt;td&gt; chain &lt;/td&gt;
1596
+ &lt;td&gt; &lt;input type=text name=chain&gt; &lt;/td&gt;
1597
+ &lt;td&gt; Narrow search to a single chain of transactions &lt;/td&gt;
1598
+ &lt;/tr&gt;
1599
+ &lt;tr&gt;
1600
+ &lt;td&gt; transid &lt;/td&gt;
1601
+ &lt;td&gt; &lt;input type=text name=transid&gt; &lt;/td&gt;
1602
+ &lt;td&gt; Narrow search to a single transactions &lt;/td&gt;
1603
+ &lt;/tr&gt;
1604
+ &lt;tr&gt;
1605
+ &lt;td&gt; billingid &lt;/td&gt;
1606
+ &lt;td&gt; &lt;input type=text name=transid&gt; &lt;/td&gt;
1607
+ &lt;td&gt; Narrow search to a single billingid &lt;/td&gt;
1608
+ &lt;/tr&gt;
1609
+ &lt;tr&gt;
1610
+ &lt;td&gt; pastdue &lt;/td&gt;
1611
+ &lt;td&gt; &lt;select name=pastdue&gt;
1612
+ &lt;option value=y&gt;y&lt;/option&gt;
1613
+ &lt;option value=n&gt;n&lt;/option&gt;
1614
+ &lt;/select&gt;&lt;/td&gt;
1615
+ &lt;td&gt; Use 'y' or 'n'. For billing ID search. Show only recurring billing IDs
1616
+ that have been unable to capture the requested funds. &lt;/td&gt;
1617
+ &lt;/tr&gt;
1618
+ &lt;tr&gt;
1619
+ &lt;td&gt; action &lt;/td&gt;
1620
+ &lt;td&gt; &lt;input type=text name=action&gt; &lt;/td&gt;
1621
+ &lt;td&gt; Narrow search by action. (example: preauth,postauth) &lt;/td&gt;
1622
+ &lt;/tr&gt;
1623
+ &lt;tr&gt;
1624
+ &lt;td&gt; status &lt;/td&gt;
1625
+ &lt;td&gt; &lt;input type=text name=status&gt; &lt;/td&gt;
1626
+ &lt;td&gt; Narrow search by status. (example: approved,accepted) &lt;/td&gt;
1627
+ &lt;/tr&gt;
1628
+ &lt;tr&gt;
1629
+ &lt;td&gt; name &lt;/td&gt;
1630
+ &lt;td&gt; &lt;input type=text name=name&gt; &lt;/td&gt;
1631
+ &lt;td&gt; Narrow search by name. &lt;/td&gt;
1632
+ &lt;/tr&gt;
1633
+ &lt;tr&gt;
1634
+ &lt;td&gt; cc &lt;/td&gt;
1635
+ &lt;td&gt; &lt;input type=text name=cc&gt; &lt;/td&gt;
1636
+ &lt;td&gt; Narrow search by credit card field. &lt;/td&gt;
1637
+ &lt;/tr&gt;
1638
+ &lt;tr&gt;
1639
+ &lt;td&gt; limit &lt;/td&gt;
1640
+ &lt;td&gt; &lt;input type=text name=limit value=20&gt; &lt;/td&gt;
1641
+ &lt;td&gt; Limit results to this number of fields (not used for summary)&lt;/td&gt;
1642
+ &lt;/tr&gt;
1643
+ &lt;tr&gt;
1644
+ &lt;td&gt; offset &lt;/td&gt;
1645
+ &lt;td&gt; &lt;input type=text name=offset value=0&gt; &lt;/td&gt;
1646
+ &lt;td&gt; Report results at this offset (used with limit to page through results)&lt;/td&gt;
1647
+ &lt;/tr&gt;
1648
+ &lt;tr&gt;
1649
+ &lt;td&gt; showcount &lt;/td&gt;
1650
+ &lt;td&gt; &lt;select name=showcount&gt;
1651
+ &lt;option value=y&gt;yes&lt;/option&gt;
1652
+ &lt;option value=n&gt;no&lt;/option&gt;
1653
+ &lt;/select&gt;&lt;/td&gt;
1654
+ &lt;td&gt; Show the number of not-limited rows on the last line of the result&lt;/td&gt;
1655
+ &lt;/tr&gt;
1656
+ &lt;tr&gt;
1657
+ &lt;td colspan=3&gt; &lt;input type=submit&gt; &lt;/td&gt;
1658
+ &lt;/tr&gt;
1659
+ &lt;/table&gt;
1660
+ &lt;/form&gt;
1661
+ &lt;/body&gt;
1662
+ &lt;/html&gt;
1663
+ </pre>
1664
+
1665
+ <h2> <a name="testdata"></a>Appendix A - Test Data </h2>
1666
+
1667
+ <p>
1668
+ While testing, you may wish to experiment with the different responses
1669
+ that the gateway can generate. The following test card numbers will
1670
+ produce an approval, and have address data as listed, for testing AVS.
1671
+ If you wish to test CVV, the code listed int he right-hand column is
1672
+ the correct CVV code, Other valid credit cards will work, but will
1673
+ produce a 'U' AVS code. </p><p>
1674
+ Please note: these cards ONLY work on transactions flagged as demo, or
1675
+ while your account is in "test" mode! For a live transaction, they will
1676
+ all return a decline with a declinetype of carderror. </p><h3 align="center">Test Cards - Approved </h3>
1677
+
1678
+ <center>
1679
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1680
+ <tbody><tr><th>Card Type </th><th>Card Number </th><th>Exp </th><th>Address </th><th>City </th><th>State </th><th>Zip </th><th>CVV </th></tr>
1681
+ <tr><td>Visa </td><td>4111111111111111 </td><td>04/12 </td><td>123 Test St. </td><td>Somewhere </td><td>CA </td><td>90001 </td><td>123 </td></tr>
1682
+ <tr><td>MasterCard </td><td>5411111111111115 </td><td>04/12 </td><td>4000 Main St. </td><td>Anytown </td><td>AZ </td><td>85001 </td><td>777 </td></tr>
1683
+ <tr><td>American Express </td><td>341111111111111 </td><td>04/12 </td><td>12 Colorado Blvd. </td><td>Elsewhere </td><td>IL </td><td>54321 </td><td>4000 </td></tr>
1684
+ <tr><td>Discover </td><td>6011111111111117 </td><td>04/12 </td><td>6789 Green Ave. </td><td>Nowhere </td><td>MA </td><td>12345 </td><td>- </td></tr>
1685
+ <tr><td>Diner's Club </td><td>36484444444446 </td><td>04/12 </td><td>7390 Del Mar Blvd. </td><td>Atown </td><td>NY </td><td>01101 </td><td>- </td></tr>
1686
+ <tr><td>JCB </td><td>213122222222221 </td><td>04/12 </td><td>350 Madison Ave. </td><td>Springfield </td><td>OH </td><td>400000 </td><td>- </td></tr>
1687
+ </tbody></table>
1688
+ </center>
1689
+
1690
+ <p>
1691
+ The following card numbers will generate a decline, with the
1692
+ declinetype listed as follows. You may use this to test code which
1693
+ takes different paths dependent upon the type of decline. </p><h3 align="center">Test Cards - Declined </h3>
1694
+
1695
+ <center>
1696
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1697
+ <tbody><tr><th>Card Number </th><th>Exp </th><th>DeclineType </th></tr>
1698
+ <tr><td>4012345678909 </td><td>04/12 </td><td>decline </td></tr>
1699
+ <tr><td>5555444433332226 </td><td>04/12 </td><td>call </td></tr>
1700
+ <tr><td>4444111144441111 </td><td>04/12 </td><td>carderror </td></tr>
1701
+ </tbody></table>
1702
+ </center>
1703
+
1704
+ <p>
1705
+
1706
+ </p><h3 align="center">ACH Test Numbers </h3>
1707
+
1708
+ <center>
1709
+ <table bgcolor="#e0e0e0" border="1" cellpadding="5" cellspacing="2">
1710
+ <tbody><tr><th>Routing Number </th><th>Account Number </th></tr>
1711
+ <tr><td>789456124 </td><td>55544433221 </td></tr>
1712
+ </tbody></table>
1713
+ </center>
1714
+
1715
+ <p>
1716
+ You should also test your code to make sure it properly handles all <a href="#Bad%20Data%7Coutline">baddata </a>and <a href="#Errortype%7Coutline">error </a>cases. Simply pass bad values in order to generate these situations.
1717
+
1718
+ </p><h2><a name="troubleshooting"></a>Appendix B - Troubleshooting </h2>
1719
+
1720
+ <p>
1721
+ Details about installing and troubleshooting TCLink specific to your
1722
+ development platform can be found in the documentation included with
1723
+ the TCLink archive. </p><p>
1724
+ Once you are able to connect to the TC gateway, you should be able to diagnose parameter-related issues using the <a href="#Status%7Coutline">status</a>, <a href="#Decline%20Type%7Coutline">declinetype </a>, and <a href="#Errortype%7Coutline">errortype </a>parameters returned by the gateway. There is one response which indicates a more generic error, and that's an error of <b>cantconnect</b>. First, check the computer's network connection; can you ping machines on the Internet, by IP or by name?
1725
+
1726
+ </p><p>
1727
+ The most common network connectivity error is that your target computer
1728
+ may be behind a firewall. TCLink uses the HTTPS port (443/tcp) for
1729
+ network communications; you can check whether this port is open from
1730
+ the target machine by typing "telnet vault.trustcommerce.com 443" at a
1731
+ UNIX command prompt, or else by loading a web browser on the target
1732
+ machine and attempting to visit https://vault.trustcommerce.com
1733
+ directly. If you timeout attempting to make the connection, but your
1734
+ Internet connection is working otherwise, then you may be firewalled.
1735
+ Speak to your network administrator about allowing outbound TCP traffic
1736
+ on port 443. </p><p>
1737
+ Another common problem is the lack of domain name (DNS) resolution. In some cases this will result in an errortype <b>dnsfailure</b>.
1738
+ (Not always; the TCLink software will sometimes fall back to hard coded
1739
+ IP addresses for established accounts. But this method is insecure and
1740
+ error-prone, and is used only as a last resort to keep a system with
1741
+ temporary DNS issues up and running during the outage.) The target
1742
+ machine must be able to resolve the trustcommerce.com domain; try
1743
+ typing "host trustcommerce.com" from a UNIX command prompt. If you
1744
+ don't get a response, or get an error, then the machine cannot resolve
1745
+ DNS information and TCLink will not be able to connect to the TC
1746
+ gateway. Speak to your sysadmin about making domain name resolution
1747
+ available to your target host. </p><h2><a name="httpspost"></a>Appendix C - Connecting via HTTPS POST </h2>
1748
+
1749
+ <p>
1750
+ This method should only be used if a TCLink client install is not an
1751
+ option. It does not have the failover capability (and thus the
1752
+ processing uptime is not guaranteed to be 100%), or some of the
1753
+ enhanced security features of TCLink. In addition, transactions may be
1754
+ slightly slower, by an extra half second or so. It does, however
1755
+ support all other features available through TCLink, including all
1756
+ parameters and transaction types. </p><p>
1757
+ This is the URL:
1758
+
1759
+ </p><p>
1760
+ <a href="https://vault.trustcommerce.com/trans/">https://vault.trustcommerce.com/trans/ </a>
1761
+
1762
+ </p><p>
1763
+ The transaction should be sent as a standard POST, with CGI parameters,
1764
+ URL encoded. The parameters are otherwise identical to those used
1765
+ through TCLink. </p><p>
1766
+ Response parameters are returned as name-value pairs separated by newlines.
1767
+
1768
+ </p><h2><a name="currency"></a>Appendix D - Currency Table </h2>
1769
+ <h3 align="center">Currency Codes </h3>
1770
+ <table align="center" bgcolor="#e0e0e0" border="1" cellpadding="5">
1771
+ <tbody><tr><th>Code</th><th>Currency Type</th><th>Code</th><th>Currency Type</th></tr>
1772
+ <tr><td>usd</td><td>US Dollars</td><td>jpy</td><td>Japan Yen</td></tr>
1773
+ <tr><td>eur</td><td>Euro</td><td>jod</td><td>Jordan Dinar</td></tr>
1774
+
1775
+ <tr><td>cad</td><td>Canadian Dollars</td><td>krw</td><td>Korea (South) Won</td></tr>
1776
+ <tr><td>gbp</td><td>UK Pounds</td><td>lbp</td><td>Lebanon Pounds</td></tr>
1777
+ <tr><td>dem</td><td>German Deutschemarks</td><td>luf</td><td>Luxembourg Francs</td></tr>
1778
+
1779
+ <tr><td>frf</td><td>French Francs</td><td>myr</td><td>Malaysia Ringgit</td></tr>
1780
+ <tr><td>jpy</td><td>Japanese Yen</td><td>mxp</td><td>Mexico Pesos</td></tr>
1781
+ <tr><td>nlg</td><td>Dutch Guilders</td><td>nlg</td><td>Netherlands Guilders</td></tr>
1782
+
1783
+ <tr><td>itl</td><td>Italian Lira</td><td>nzd</td><td>New Zealand Dollars</td></tr>
1784
+ <tr><td>chf</td><td>Switzerland Francs</td><td>nok</td><td>Norway Kroner</td></tr>
1785
+ <tr><td>dzd</td><td>Algeria Dinars</td><td>pkr</td><td>Pakistan Rupees</td></tr>
1786
+
1787
+ <tr><td>arp</td><td>Argentina Pesos</td><td>xpd</td><td>Palladium Ounces</td></tr>
1788
+ <tr><td>aud</td><td>Australia Dollars</td><td>php</td><td>Philippines Pesos</td></tr>
1789
+ <tr><td>ats</td><td>Austria Schillings</td><td>xpt</td><td>Platinum Ounces</td></tr>
1790
+
1791
+ <tr><td>bsd</td><td>Bahamas Dollars</td><td>plz</td><td>Poland Zloty</td></tr>
1792
+ <tr><td>bbd</td><td>Barbados Dollars</td><td>pte</td><td>Portugal Escudo</td></tr>
1793
+ <tr><td>bef</td><td>Belgium Francs</td><td>rol</td><td>Romania Leu</td></tr>
1794
+
1795
+ <tr><td>bmd</td><td>Bermuda Dollars</td><td>rur</td><td>Russia Rubles</td></tr>
1796
+ <tr><td>brr</td><td>Brazil Real</td><td>sar</td><td>Saudi Arabia Riyal</td></tr>
1797
+ <tr><td>bgl</td><td>Bulgaria Lev</td><td>xag</td><td>Silver Ounces</td></tr>
1798
+
1799
+ <tr><td>cad</td><td>Canada Dollars</td><td>sgd</td><td>Singapore Dollars</td></tr>
1800
+ <tr><td>clp</td><td>Chile Pesos</td><td>skk</td><td>Slovakia Koruna</td></tr>
1801
+ <tr><td>cny</td><td>China Yuan Renmimbi</td><td>zar</td><td>South Africa Rand</td></tr>
1802
+
1803
+ <tr><td>cyp</td><td>Cyprus Pounds</td><td>krw</td><td>South Korea Won</td></tr>
1804
+ <tr><td>csk</td><td>Czech Republic Koruna</td><td>esp</td><td>Spain Pesetas</td></tr>
1805
+ <tr><td>dkk</td><td>Denmark Kroner</td><td>xdr</td><td>Special Drawing Right (IMF)</td></tr>
1806
+
1807
+ <tr><td>nlg</td><td>Dutch Guilders</td><td>sdd</td><td>Sudan Dinar</td></tr>
1808
+ <tr><td>xcd</td><td>Eastern Caribbean Dollars</td><td>sek</td><td>Sweden Krona</td></tr>
1809
+ <tr><td>egp</td><td>Egypt Pounds</td><td>chf</td><td>Switzerland Francs</td></tr>
1810
+
1811
+ <tr><td>eur</td><td>Euro</td><td>twd</td><td>Taiwan Dollars</td></tr>
1812
+ <tr><td>fjd</td><td>Fiji Dollars</td><td>thb</td><td>Thailand Baht</td></tr>
1813
+ <tr><td>fim</td><td>Finland Markka</td><td>ttd</td><td>Trinidad and Tobago Dollars</td></tr>
1814
+
1815
+ <tr><td>frf</td><td>France Francs</td><td>trl</td><td>Turkey Lira</td></tr>
1816
+ <tr><td>dem</td><td>Germany Deutsche Marks</td><td>gbp</td><td>United Kingdom Pounds</td></tr>
1817
+ <tr><td>xau</td><td>Gold Ounces</td><td>usd</td><td>United States Dollars</td></tr>
1818
+
1819
+ <tr><td>grd</td><td>Greece Drachmas</td><td>veb</td><td>Venezuela Bolivar</td></tr>
1820
+ <tr><td>hkd</td><td>Hong Kong Dollars</td><td>zmk</td><td>Zambia Kwacha</td></tr>
1821
+ <tr><td>huf</td><td>Hungary Forint</td><td>eur</td><td>Euro</td></tr>
1822
+
1823
+ <tr><td>isk</td><td>Iceland Krona</td><td>xcd</td><td>Eastern Caribbean Dollars</td></tr>
1824
+ <tr><td>inr</td><td>India Rupees</td><td>xdr</td><td>Special Drawing Right (IMF)</td></tr>
1825
+ <tr><td>idr</td><td>Indonesia Rupiah</td><td>xag</td><td>Silver Ounces</td></tr>
1826
+
1827
+ <tr><td>iep</td><td>Ireland Punt</td><td>xau</td><td>Gold Ounces</td></tr>
1828
+ <tr><td>ils</td><td>Israel New Shekels</td><td>xpd</td><td>Palladium Ounces</td></tr>
1829
+ <tr><td>itl</td><td>Italy Lira</td><td>xpt</td><td>Platinum Ounces</td></tr>
1830
+
1831
+ <tr><td>jmd</td><td>Jamaica Dollars</td><td>&nbsp;</td><td>&nbsp;</td></tr>
1832
+ </tbody></table>
1833
+ <p>
1834
+
1835
+ <a name="inputfields"></a></p><h2>Appendix E - Input Field List</h2>
1836
+
1837
+ <center><h3>Input Fields</h3></center>
1838
+ <table align="center" bgcolor="#e0e0e0" border="1" cellpadding="5">
1839
+ <tbody><tr><th>Name</th><th>Type</th><th>Minimum Length</th><th>Maximum Length</th><th>Service</th></tr>
1840
+
1841
+ <tr><td>custid</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1842
+ <tr><td>password</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1843
+ <tr><td>action</td><td>string</td><td>1</td><td>10</td><td><br></td></tr>
1844
+
1845
+ <tr><td>media</td><td>string</td><td>1</td><td>10</td><td><br></td></tr>
1846
+ <tr><td>currency</td><td>string</td><td>3</td><td>3</td><td><br></td></tr>
1847
+ <tr><td>amount</td><td>number</td><td>3</td><td>8</td><td><br></td></tr>
1848
+
1849
+ <tr><td>cc</td><td>number</td><td>13</td><td>16</td><td><br></td></tr>
1850
+ <tr><td>exp</td><td>number</td><td>4</td><td>4</td><td><br></td></tr>
1851
+ <tr><td>cvv</td><td>number</td><td>3</td><td>4</td><td><br></td></tr>
1852
+
1853
+ <tr><td>routing</td><td>number</td><td>9</td><td>9</td><td>ACH</td></tr>
1854
+ <tr><td>account</td><td>number</td><td>3</td><td>17</td><td>ACH</td></tr>
1855
+ <tr><td>billingid</td><td>string</td><td>6</td><td>6</td><td>Citadel</td></tr>
1856
+
1857
+ <tr><td>verify</td><td>y/n</td><td>1</td><td>1</td><td>Citadel</td></tr>
1858
+ <tr><td>transid</td><td>string</td><td>14</td><td>14</td><td><br></td></tr>
1859
+ <tr><td>avs</td><td>y/n</td><td>1</td><td>10</td><td><br></td></tr>
1860
+
1861
+ <tr><td>name</td><td>string</td><td>1</td><td>60</td><td><br></td></tr>
1862
+ <tr><td>address1</td><td>string</td><td>1</td><td>80</td><td><br></td></tr>
1863
+ <tr><td>address2</td><td>string</td><td>1</td><td>80</td><td><br></td></tr>
1864
+
1865
+ <tr><td>zip</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1866
+ <tr><td>city</td><td>string</td><td>1</td><td>40</td><td><br></td></tr>
1867
+ <tr><td>state</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1868
+
1869
+ <tr><td>country</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1870
+ <tr><td>phone</td><td>string</td><td>1</td><td>30</td><td><br></td></tr>
1871
+ <tr><td>email</td><td>string</td><td>1</td><td>50</td><td><br></td></tr>
1872
+ <tr><td>ip</td><td>string</td><td>7</td><td>15</td><td><br></td></tr>
1873
+
1874
+ <tr><td>track1</td><td>string</td><td>1</td><td>79</td><td>Card Swipe</td></tr>
1875
+ <tr><td>track2</td><td>string</td><td>1</td><td>40</td><td>Card Swipe</td></tr>
1876
+ <tr><td>ticket</td><td>string</td><td>1</td><td>30</td><td><br></td></tr>
1877
+
1878
+ <tr><td>operator</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1879
+ <tr><td>shiptosame</td><td>y/n</td><td>1</td><td>1</td><td><br></td></tr>
1880
+ <tr><td>shipto_name</td><td>string</td><td>1</td><td>60</td><td><br></td></tr>
1881
+
1882
+ <tr><td>shipto_address1</td><td>string</td><td>1</td><td>40</td><td><br></td></tr>
1883
+ <tr><td>shipto_address2</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1884
+ <tr><td>shipto_city</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1885
+
1886
+ <tr><td>shipto_state</td><td>string</td><td>2</td><td>2</td><td><br></td></tr>
1887
+ <tr><td>shipto_zip</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1888
+ <tr><td>shipto_country</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1889
+
1890
+ <tr><td>numitems</td><td>number</td><td>1</td><td>3</td><td><br></td></tr>
1891
+ <tr><td>price</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1892
+ <tr><td>shippingcode</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1893
+
1894
+ <tr><td>shippinghandling</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1895
+ <tr><td>productcode#</td><td>string</td><td>1</td><td>20</td><td><br></td></tr>
1896
+ <tr><td>quantity#</td><td>number</td><td>1</td><td>3</td><td><br></td></tr>
1897
+
1898
+ <tr><td>price#</td><td>number</td><td>1</td><td>6</td><td><br></td></tr>
1899
+ <tr><td>tax#</td><td>number</td><td>1</td><td>6</td><td><br></td></tr>
1900
+ <tr><td>shippinghandling#</td><td>number</td><td>1</td><td>6</td><td><br></td></tr>
1901
+
1902
+ <tr><td>wallet</td><td>y/n</td><td>1</td><td>1</td><td>TC Wallet</td></tr>
1903
+ <tr><td>walletsize</td><td>string</td><td>3</td><td>8</td><td>TC Wallet</td></tr>
1904
+ <tr><td>walletexposure</td><td>string</td><td>1</td><td>3</td><td>TC Wallet</td></tr>
1905
+
1906
+ <tr><td>start</td><td>string</td><td>2</td><td>10</td><td>Citadel</td></tr>
1907
+ <tr><td>cycle</td><td>string</td><td>2</td><td>4</td><td>Citadel</td></tr>
1908
+ <tr><td>payments</td><td>number</td><td>1</td><td>4</td><td>Citadel</td></tr>
1909
+ <tr><td>authnow</td><td>y/n</td><td>1</td><td>1</td><td>Citadel</td></tr>
1910
+ <tr><td>lastpaymentunstore</td><td>y/n</td><td>1</td><td>1</td><td>Citadel</td></tr>
1911
+
1912
+ <tr><td>fraudthreshold</td><td>number</td><td>1</td><td>2</td><td>CrediGuard (Scoring)</td></tr>
1913
+ <tr><td>ip</td><td>number</td><td>7</td><td>15</td><td>CrediGuard (Blacklist)</td></tr>
1914
+
1915
+ <tr><td>demo</td><td>y/n</td><td>1</td><td>1</td><td><br></td></tr>
1916
+ <tr><td>offlineauthcode</td><td>string</td><td>6</td><td>6</td><td><br></td></tr>
1917
+ </tbody></table><center>
1918
+
1919
+ <p style="margin-left: 1.18in; margin-bottom: 0in;" align="center"><i>Copyright
1920
+ � 2006 TrustCommerce</i>
1921
+
1922
+
1923
+ </p></center></body></html>