1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
|
<html>
<head>
<title> TrustCommerce Developer's Guide 2.3 </title>
</head>
<body bgcolor=white text=black link=blue vlink=darkblue>
<hr>
<h1>TrustCommerce Developer's Guide 2.3</h1>
<a href=http://www.trustcommerce.com>http://www.trustcommerce.com</a><br>
<a href=mailto:developer@trustcommerce.com>developer@trustcommerce.com</a><p>
March 18, 2003<br>
<hr><p>
<h2>Table of Contents</h2>
<table>
<tr><td> <a href=#intro>I. Introduction</a> </td></tr>
<tr><td> <a href=#tclink>II. Connecting via TCLink</a> </td></tr>
<tr><td> <a href=#transtypes>III. Transaction Types</a> </td></tr>
<tr><td> <a href=#inputparam>IV. Input Parameters</a> </td></tr>
<tr><td> <a href=#returnparam>V. Return Parameters</a> </td></tr>
<tr><td> <a href=#sales>VI. Credit Card Preauths and Sales</a> </td></tr>
<tr><td> <a href=#cvv>VII. Card Verification Value (CVV)</a> </td></tr>
<tr><td> <a href=#cardpresent>VII. Card-Present Transactions</a> </td></tr>
<tr><td> <a href=#ach>IX. ACH</a> </td></tr>
<tr><td> <a href=#credits>X. Postauths, Credits, and Chargebacks</a> </td></tr>
<tr><td> <a href=#billingids>XI. TCS Citadel (Billing IDs)</a> </td></tr>
<tr><td> <a href=#recurring>XII. Recurring Billing</a> </td></tr>
<tr><td> <a href=#wallet>XIII. TCS Wallet</a> </td></tr>
<tr><td> <a href=#pl2>XIV. Purchase Level II (Commercial Cards)</a> </td></tr>
<tr><td> <a href=#orderdetail>XV. Order Detail</a> </td></tr>
<tr><td> <a href=#query>XVI. Vault Query API</a> </td></tr>
<tr><td> <a href=#testdata>Appendix A - Test Data</a> </td></tr>
<tr><td> <a href=#troubleshooting>Appendix B - Troubleshooting</a> </td></tr>
<tr><td> <a href=#httpspost>Appendix C - Connecting via HTTPS POST</a> </td></tr>
<tr><td> <a href=#currency>Appendix D - Currency Table</a> </td></tr>
<tr><td> <a href=#inputfields>Appendix E - Input Field List</a> </td></tr>
</table>
<hr><p>
<a name=intro></a><h2>I. Introduction</h2>
This guide covers the TrustCommerce transactional processing API. It is platform- and language-neutral. If you are a developer programming processing functionality to a software package or website, then this guide is for you. If you are connecting via a pre-integrated commerce package, including shopping carts such as StoreForge, Mal's e-Commerce, PDG Cart, or AllCommerce, then you do not need this document.
<p>
Definitions of credit card processing terms and information about the Vault website are contained in the TrustCommerce User's Guide, and will not be covered here. If you are not familiar with the basics of credit card processing (such as the difference between an auth and capture), then you should probably read the User's Guide first. The User's Guide also describes use of the Vault website's reporting capabilities, which you may find useful to confirm that your test transactions are working as expected.
<p>
There are two methods of connecting to the TrustCommerce gateway at the programming level: the TCLink client software, and an HTTPS POST to the Vault server. TCLink is HIGHLY recommend, as it offers support for TrustCommerce's unique features such as automated failover and enhanced security through server certificate verification. It's available for many platforms and languages, and installation is straightforward, so you should try to use it if possible. If you are unable to use TCLink for whatever reason, the HTTPS POST method will still allow you to access most features of the TrustCommerce processing engine, but be aware that it cannot match the speed and especially the reliability of TCLink.
<p>
<a name=tclink></a><h2>II. Connecting via TCLink</h2>
The TCLink API is available for download from the Vault website, in the "Downloads" section. Be sure to chose the version that matches the platform and language that you are using. In particular, Win32 developers will probably always want the COM object, which contains support for a number of different languages on the Win32 platform, including ASP, ColdFusion, Perl, PHP, and Python.
<p>
Installation instructions specific to the TCLink version you've downloaded can be found in the readme file contained with the archive. It will also contain a version of the TCTest program specific to the language you're using. It's highly recommended that you look over this example, and even use it as the basis for your own code. In fact, you should look over the code sample first to get a feel for the API, then return to reading this document.
<p>
Versions of TCLink for high-level languages (including PHP, Perl, Python, and Java) with built in support for hashes only have one method: Send(). This method accepts a single parameter, a hash of input values, and returns a single parameters, a hash of output values. The only other method avaliable is GetVersion(), which returns the version string for TCLink.
<p>
TCLink for other languages (including C/C++, Win32 COM, and CFX) contains four basic methods: Create(), PushParam(), Send(), and GetResponse(). C-style TCLink functions are described in the table below.
<p>
<center><h3>TCLink Function Names</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th> Function Name </th><th> Description </th></tr>
<tr><td> CreateLink() </td><td> Create a new transaction handle. </td></tr>
<tr><td> PushParam() </td><td> Push a parameter into the transaction. </td></tr>
<tr><td> Send() </td><td> Submit a transaction to the gateway. </td></tr>
<tr><td> GetResponse() </td><td> Retrieve a response parameter from the transaction. </td></tr>
<tr><td> GetEntireResponse() </td><td> Get the entire response for the transaction, primarily use for debugging or logging. </td></tr>
<tr><td> Destroy() </td><td> Deallocate any memory associated with the transaction handle. </td></tr>
<tr><td> GetVersion() </td><td> Get the version string for the TCLink API in use. </td></tr>
</table>
<p>
These four methods map to the four stages of running a transaction: initialize, push a number of parameters describing the transaction, send the transaction to the TrustCommerce gateway for processing, and finally get details about the transaction results.
<p>
The only method which contacts the TC servers is Send(). This function will block for one or two seconds while the transaction is processed. Afterward, you can retrieve response parameters at your leisure; they are stored internally in TCLink.
<p>
<a name=transtypes></a><h2>III. Transaction Types</h2>
You may wish to read the section of the TCS User's Guide which describes the transaction types and the authorization/capture process, especially if you are not already familiar with credit card processing.
<p>
In terms of parameters passed, preauths and sales are almost identical. They take account data and personal information about the customer, along with a transaction amount. The transaction is authorized and the response values returned. In the case of a sale, the item is also immediately submitted for capture. Preauths are not captured until they are postauthed.
<p>
Postauths and credits are also very similar to one another. They indicate a capture or a return of funds for a previous transaction, and no personal data about the customer or their payment method is passed.
<p>
There are three other types of transaction. Store and unstore are covered in the Billing ID section of this document. Walletsale is covered under the TCS Wallet section.
<p>
<a name=inputparam></a><h2>IV. Input Parameters</h2>
There are a large number of parameters available for describing transactions. Not all parameters are accepted for all transaction types, and most parameters are optional. Most transactions can be sent with only a few parameters. The only parameters always required are custid, password, and action.
<p>
Parameters are carefully checked for format and size before the transaction is sent. If there are any errors in the parameters you've entered, the transaction will be aborted and detailed information about the errors will be returned. These return values are described in more detail in the next section.
<p>
The parameters presented in the following tables are used by all transaction types.
<center><h3>Required Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>amount</td><td>Amount of the transaction, in cents. (example: "500" is $5.00)</td></tr>
<tr><td>custid</td><td>Your customer ID number assigned to you by TrustCommerce.</td></tr>
<tr><td>password</td><td>The password for your custid as assigned by TrustCommerce.</td></tr>
<tr><td>action</td><td>The transaction type; can be one of preauth, sale, postauth, credit, store, unstore, walletsale, or chargeback</td></tr>
</table>
<p>
<center><h3>Optional Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>amount</td><td>Amount of the transaction, in cents. (example: "500" is $5.00)</td></tr>
<tr><td>demo</td><td>When set to "y", the transaction will be a test transaction only.</td></tr>
<tr><td>ticket</td><td>Free-form text field intended for storing ticket number or order number associated with the transaction, to aid merchants in order tracking and reporting.</td></tr>
<tr><td>operator</td><td>Free-form text field intended for recording the operator that entered the transaction, to aid merchants in order track and reporting.</td></tr>
</table>
<p>
The demo parameter is of particular note for testing. Demo transactions allow you to test your processing system without charging real money to a card, and you will not be charged and transaction fees. They are also flagged separately in the Vault database and will not appear in the regular accounting reports.
<p>
On card-not-present transactions, the ticket parameter is passed to the acquiring bank in the settlement process as the "purchase identifier." This may aid in reconciling the TrustCommerce transactions with the deposits made into the merchant bank account. If no ticket is passed, then the TrustCommerce transID will be sent to the bank instead.
<p>
<a name=returnparam></a><h2>V. Return Parameters</h2>
Any transaction sent will return several parameters describing the success or failure of the transaction. Properly formatted transactions will always return a transaction ID (or "transID') this is the unique identifier for this transaction, and can be used to retrieve the transaction from the Vault website, or otherwise access the transaction in the future. (For example, in order to credit a previous transaction, you will need to send the transID of said transaction.)
<p>
Transactions also always return a status parameter which describes the success or failure of the transaction. Status can be set to one of the following:
<center><h3>Status</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Status Value</th><th>Description</th></tr>
<tr><td>approved</td><td>The transaction was successfully authorized.</td></tr>
<tr><td>accepted</td><td>The transaction has been successfully accepted into the system.</td></tr>
<tr><td>decline</td><td>The transaction was declined, see declinetype for further details.</td></tr>
<tr><td>baddata</td><td>Invalid parameters passed, see error for further details.</td></tr>
<tr><td>error</td><td>System error when processing the transaction, see errortype for details.</td></tr>
</table>
<p>
The difference between approved and accepted is subtle, but important. Approved means that the transaction was an authorization of some sort, and has been successfully cleared with the bank. Accepted only means that the transaction was queued into the system without errors, but may be rejected at some later time. An example of the difference is a sale versus a credit. A sale is a realtime authorization, so it returns approved on success. A credit is not realtime; there is no such thing as a "credit authorization." Instead it is queued up for processing by the bank and there is the small but non-zero posibility that it will be rejected at a later time. In practice, however, this rarely happens, so the developer need not worry unduly.
<p>
When status is set to decline, the parameter declinetype will contain one of the following:
<center><h3>Decline Type</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Declinetype Value</th><th>Description</th></tr>
<tr><td>decline</td><td>This is a "true" decline, it almost always is a result of insufficient funds on the card.</td></tr>
<tr><td>avs</td><td>AVS failed; the address entered does not match the billing address on file at the bank.</td></tr>
<tr><td>cvv</td><td>CVV failed; the number provided is not the correct verification number for the card. (See section X for details on CVV.)</td></tr>
<tr><td>call</td><td>The card must be authorized manually over the phone. You may choose to call the customer service number listed on the card and ask for an offline authcode, which can be passed in the offlineauthcode field.</td></tr>
<tr><td>carderror</td><td>Card number is invalid, usually the result of a typo in the card number.</td></tr>
<tr><td>authexpired</td><td>Attempt to postauth an expired (more than 7 days old) preauth.</td></tr>
<tr><td>dailylimit</td><td>Daily limit in transaction count or amount as been reached.</td></tr>
<tr><td>weeklylimit</td><td>Weekly limit in transaction count or amount as been reached.</td></tr>
<tr><td>monthlylimit</td><td>Monthly limit in transaction count or amount as been reached.</td></tr>
</table>
<p>
A status of baddata indicates that no transaction was attempted because one or more parameters was invalid. In this case, the parameter error will indicate the problem, and the offenders parameter will list the offending input fields. The error parameter may be set to one of the following:
<center><h3>Bad Data</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Error Value</th><th>Description</th></tr>
<tr><td>missingfields</td><td>Some parameters required for this transaction type were not sent.</td></tr>
<tr><td>extrafields</td><td>Parameters not allowed for this transaction type were sent.</td></tr>
<tr><td>badformat</td><td>A field was improperly formatted, such as non-digit characters in a number field.</td></tr>
<tr><td>badlength</td><td>A field was longer or shorter than the server allows.</td></tr>
<tr><td>merchantcantaccept</td><td>The merchant can't accept data passed in this field. If the offender is "cc", for example, it usually means that you tried to run a card type (such as American Express or Discover) that is not supported by your account. If it was "currency", you tried to run a currency type not supported by your account.</td></tr>
<tr><td>mismatch</td><td>Data in one of the offending fields did not cross-check with the other offending field.</td></tr>
</table>
<p>
A status of error indicates the an error occurred while processing the transaction. These are almost always networking errors; see the Troubleshooting section for more. If the status is error, then the errortype parameter will be set to one of the following:
<center><h3>Error</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Errortype Value</th><th>Description</th></tr>
<tr><td>cantconnect</td><td>Couldn't connect to the TrustCommerce gateway. Check your Internet connection to make sure it is up.</td></tr>
<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>
<tr><td>linkfailure</td><td>The connection was established, but was severed before the transaction could complete.</td></tr>
<tr><td>failtoprocess</td><td>The bank servers are offline and unable to authorize transactions. Try again in a few minutes, or try a card from a different issuing bank.</td></tr>
</table>
<p>
Other parameters (such as avs or billingid) may be returned by the transaction depending on the action; see sections covering the transaction type you're running for detailed information on the specialized return values.
<p>
<a name=sales></a><h2>VI. Credit Card Preauths and Sales</h2>
The 'preauth' and 'sale' actions are identical in terms of parameters and function. The only difference is that a sale submits the item for capture as well, while preauths run the authorization only and can be postauthed at another time.
<p>
The parameters that can be passed with these action types are described in the following two tables. The first table list required fields that you must pass in order to send the transaction. The second table lists optional fields that you can pass if you wish, but are not required.
<p>
<center><h3>Required Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>amount</td><td>Amount of the transaction, in cents. (example: "500" is $5.00)</td></tr>
<tr><td>cc</td><td>Credit card number, digits only (no spaces or dashes)</td></tr>
<tr><td>exp</td><td>Credit card expiration date, in MMYY format</td></tr>
</table>
<p>
<center><h3>Optional Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Default Value</th><th>Description</th></tr>
<tr><td>media</td><td>cc</td><td>"cc" for credit card or "ach" for ACH.
<tr><td>currency</td><td>usd</td><td>Currency code (see section X for the table of codes)
<tr><td>avs</td><td>n</td><td>AVS requested, "y" or "n" (see notes below).
<tr><td>name</td><td> </td><td>Cardholder's name.
<tr><td>address1</td><td> </td><td>First line of cardholder's street address.
<tr><td>address2</td><td> </td><td>Second line of cardholder's street address.
<tr><td>city</td><td> </td><td>Cardholder's city.
<tr><td>state</td><td> </td><td>Two-character code for the cardholder's state, or the full region/province for international addresses.
<tr><td>zip</td><td> </td><td>Cardholder's zipcode, five or nine digits with no spaces or dashes, or the full postal code for international addresses.
<tr><td>country</td><td> </td><td>Cardholder's country, leave blank for US.
<tr><td>phone</td><td> </td><td>Cardholder's phone number.
<tr><td>email</td><td> </td><td>Cardholder's email address.
<tr><td>offlineauthcode</td><td> </td><td>Six-digit numeric code used to "force" the transaction (see notes below).
</table>
<p>
A note about AVS: The AVS system is a useful way to help screen for fraud, as it requires that whomever is sending the transaction know the billing address for the card in question. As a merchant, you should know that AVS is not uniformly supported by card issuers; approximately 30% of US-based credit cards will not have AVS capability, and AVS is not available with any non-US cards at all. If avs=y is used, it will attempt to verify the address data with AVS, but if it is unavailable, it will not cause the transaction to fail. Only if AVS is available and the address data does not match will the transaction be declined due to AVS. You may wish to screen AVS results more closely. For this reason, sales and preauths will return the AVS code in a parameter named avs. (This parameter is returned even when avs=n, which is the default.) It returns a single character code, which are enumerated in the table below.
<center><h3>AVS Returns Codes</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Code</th><th>Description</th></tr>
<tr><td align=center>X</td><td>Exact match, 9 digit zipcode.</td></tr>
<tr><td align=center>Y</td><td>Exact match, 5 digit zipcode.</td></tr>
<tr><td align=center>A</td><td>Street address match only.</td></tr>
<tr><td align=center>W</td><td>9 digit zipcode match only.</td></tr>
<tr><td align=center>Z</td><td>5 digit zipcode match only.</td></tr>
<tr><td align=center>N</td><td>No match on street address or zipcode.</td></tr>
<tr><td align=center>U</td><td>AVS unavailable on this card.</td></tr>
<tr><td align=center>G</td><td>Non-US card issuer, AVS unavailable.</td></tr>
<tr><td align=center>R</td><td>Card issuer system currently down, try again later.</td></tr>
<tr><td align=center>E</td><td>Error, ineligible - not a mail/phone order.</td></tr>
<tr><td align=center>S</td><td>Service not supported.</td></tr>
<tr><td align=center>0</td><td>General decline or other error.</td></tr>
</table>
<p>
Only the numeric parts of the address (street address and zipcode) are verified. It should also be noted that oftentimes AVS data is incorrect or not entirely up-to-date, dependent upon the card issuing bank. For these reasons, you should treat AVS as a helpful tool which should be used in combination with other methods (dependent upon your business model) for screening transactions. If you trust AVS too blindly, you may risk losing legitimate sales. Some merchants (again, dependent upon business model) choose to turn AVS off altogether. You should analyze your customer base and make the decision that will work best for your business.
<p>
A note on offlineauthcode: Some cards returned a declinetype of call. This indicates that the card cannot be automatically authorized, but if you call the card issuers, they may be able to give you a manual authorization, which will consist of a six-digit auth code. You may then push the transaction through by entering that code into the offlineauthcode field. offlineauthcode can only be used with sale transactions. Be warned: offlineauthcode skips the authorization phase altogether, and thus is not guaranteed in the same way as a normal authorization. Be careful with the use of this parameter.
<p>
<h3>Preauth/Sale Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypasswd',
'action': 'preauth',
'amount': '500',
'cc': '4111111111111111',
'exp': '0404',
'name': 'Jennifer Smith',
'address1': '123 Test St.',
'city': 'Somewhere',
'state': 'CA',
'zip': '90001',
'avs': 'y'
}
result = tclink.send(params)
if (result['status'] == 'approved'):
print 'Transaction was successful'
elif (result['status'] == 'decline'):
print 'Transaction declined. Reason: ', result['declinetype']
elif (result['status'] == 'baddata'):
print 'Improperly formatted data. Offending fields: ', result['offenders']
else:
print 'An error occured: ', result['errortype']
print 'Here are the full details:'
print result
</pre>
<p>
<a name=cvv></a><h2>VII. Card Verification Value (CVV)</h2>
Another method for cardholder verification is the CVV system. Visa cards use what is called a CVV2 code; Mastercards call it CVC2, and American Express calls it CID. CVV2 and CVC2 (Visa/MC) are located on the back of the credit card, printed in ink on the signature strip. The number is the last three digits on the righthand side of the long string of numbers on the strip. In the case of CID (AmEx), the number is a four-digit value located on the front of the card, printed just above the card number on the lefthand side. This value is passed to TCLink through the following parameter.
<center><h3>CVV Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>cvv</td><td>A three or four digit CVV number.</td></tr>
</table>
<p>
The CVV value will be checked if anything is passed in this parameter. (If you don't include the parameter, no CVV test will be run.) If the CVV matches, the transaction will run as normal. If it does not, you will receive a status of decline, and a declinetype of cvv.
<p>
<h3>CVV Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypasswd',
'action': 'sale',
'amount': '500',
'cc': '4111111111111111',
'exp': '0404',
'cvv': '123'
}
result = tclink.send(params)
if (result['status'] == 'decline')
if (result['declinetype'] == 'cvv')
print 'The CVV number is not valid.'
</pre>
<p>
<a name=cardpresent></a><h2>VII. Card-Present Transactions</h2>
In a retail environment with a card swiper, you may wish to pass magnetic stripe data along with the other credit card information on a preauth or sale. There are two parameters which you can use to send this data, named track1 and track2. Each one is for a different type of track data, and depends on the type of card reader being used.
<center><h3>Card-Present Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>track1</td><td>Up to 79 bytes of Track 1 data.</td></tr>
<tr><td>track2</td><td>Up to 40 bytes of Track 2 data.</td></tr>
</table>
<p>
You can include all data read from the track, but only data between the start sentinel (a '%' character for track1 and a ';' for track2) and the end sentinel ('?') will be used. Everything outside the start and end sentinels (such as the trailing LRC character) will be discarded.
<p>
The cc and exp fields may be passed, but are not required, since they will be extracted from the track data. If you do pass one or both of these fields, however, and it does not match the data extracted from the track data, a status of baddata and an error mismatch will be returned.
<p>
If both track1 and track2 data are passed, only the system will choose track1 by default for the authorization, and track2 will be discarded.
<p>
Generally AVS and address data are not necessary for swiped transactions, but you may pass them anyway if you choose.
<p>
<h3>Card Present Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypasswd',
'action': 'sale',
'amount': '500'
}
params['track1'] = CardReader.readMagStripe()
result = tclink.send(params)
</pre>
<p>
<a name=ach></a><h2>IX. ACH</h2>
ACH, also known as electronic checks, are very different from credit cards in that they allow a direct debit or credit to a checking account. The concept of "authorization" does not exist; it is purely a money transfer. For this reason, the only transaction types available for ACH are sale and credit. ACH credits are identical to all other types of credits in the TrustCommerce system, so please refer to section X for details on issuing credits.
<p>
ACH sales take the same parameters as credit card sales, with the exception of the "cc" and "exp" fields. Instead, use the following parameters.
<center><h3>ACH Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>routing</td><td>The routing number of the bank being debited.</td></tr>
<tr><td>account</td><td>The account number of the person or business being debited.</td></tr>
</table>
<p>
AVS is not available for ACH transactions, so the AVS setting is ignored.
<p>
There is only one declinetype returned from unsuccessful ACH sales, and that is "decline."
<p>
<h3>ACH Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'sale',
'media': 'ach',
'amount': '1000',
'routing': '123456789',
'account': '55544433322211'
}
tclink.send(params)
</pre>
<p>
<a name=credits></a><h2>X. Postauths, Credits, and Chargebacks</h2>
These three transaction types are similar in that they reference a successful transaction previously executed through the TrustCommerce system. No credit card information or other personal information fields will be accepted by this transaction types; there is only one required parameter.
<p>
<center><h3>Required Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>transid</td><td>The transaction ID (format: nnn-nnnnnnnnnn) of the referenced transaction.</td></tr>
</table>
<p>
In addition, postauths and credits can take an optional amount parameter.
<center><h3>Optional Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<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>
</table>
<p>
If no amount is passed, the default will be to take the amount from the original transaction. If, however, you wish to credit or postauthorize less than the original amount, you may pass this parameter.
<p>
<h3>Credit Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'credit',
'transid': '001-0000111101'
}
tclink.send(params)
if (result['status'] != 'accepted')
print 'Credit unsuccesful.'
</pre>
<p>
<a name=billingids></a><h2>XI. TCS Citadel (Billing IDs)</h2>
The TCS Citadel enables you to store the billing information for your customers in the encrypted TrustCommerce database, and recall it with a single six-character alphanumeric code known as a billing ID. Besides offloading the liability of storing sensitive data such as credit card numbers from your business to TrustCommerce, it also can simplify database access on your servers.
<p>
The Citadel add two new actions, store and unstore. These allow you to create, update, and deactivate billing IDs. Once stored, the billing ID will be passed in place of the many billing information fields for preauth and sale transactions.
<p>
The store transaction looks very similar to a preauth or sale. You may pass credit card information, billing and shipping address, or even ACH information. (Please see sections X and X for a detailed description of these parameters.) It adds one additional parameter:
<center><h3>Store Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<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>
<tr><td>billingid</td><td>Pass if you wish to update values of an existing billing ID.</td></tr>
</table>
<p>
You can update information on existing billing IDs by passing the billingid field along with the store transaction. If you wish to erase the data contained in a field, pass the exact string "null" (four characters, all lower case) as the parameter value.
<p>
The verify parameter is useful for ensuring that the card number is valid if you are not planning to bill the customer right away. It has no effect for ACH billing IDs, because there is no such thing as an ACH preauth. By default, the verification uses AVS; if you don't wish to use AVS, pass an avs of "n". Please note: normally, billing ID storage returns a status of accepted, because the card is unverified. If you use the verify parameter, however, it will return approved upon success.
<p>
The unstore action takes a single parameter:
<center><h3>Unstore Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>billingid</td><td>The six-character alphanumeric billing ID returned by a previous store transaction.</td></tr>
</table>
<p>
Unstore removes the billing ID from active use, and you won't be able to run further transactions on it. For your convenience, however, it does remain visible in Vault (flagged as an inactive ID), so you can still look up old IDs if needed.
<p>
Now, the moment of truth: to run a billing ID transaction, pass the billingid parameter to a preauth or a sale in place of all of the usual billing info fields (name, cc, exp, routing, account, etc). That's all there is to it! You'll find that your sale or preauth transactions are now only a few parameters: custid, password, billingid, and amount.
<h3>Billing ID Example</h3>
<pre>
# First, store a new ID.
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'store',
'cc': '4111111111111111',
'exp': '0404',
'name': 'Jennifer Smith'
}
result = tclink.send(params)
if (result['status'] == 'accepted'):
# It was succesfully stored. Now try running a transaction on the new ID.
billingid = result['billingid']
params2 = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'sale',
'billingid': billingid,
'amount': '995'
}
tclink.send(params2);
# Unstore the ID now that we are done.
params3 = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'unstore',
'billingid': billingid
}
tclink.send(params3)
</pre>
<p>
<a name=recurring></a><h2>XII. Recurring Billing</h2>
Recurring billing (sometimes also called "subscription billing") is an extension of the billing ID system. There are four parameters that are added to a store which turn the billing ID into a recurring billing ID. They are described below.
<center><h3>Recurring Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Required?</th><th>Description</th></tr>
<tr><td>cycle</td><td align=center>X</td><td>Repeat cycle in days, weeks, months, or years.</td></tr>
<tr><td>amount</td><td align=center>X</td><td>Amount to bill in cents.</td></tr>
<tr><td>start</td><td> </td><td>Date to start, or else offset from current date (defaults to now).</td></tr>
<tr><td>payments</td><td> </td><td>Number of payments to make (defaults to infinite).</td></tr>
</table>
<p>
Cycle is in the format of a number between 1 and 99 followed by a character representing the timeframe: 'd' for days, 'w' for weeks, 'm' for months or 'y' for years. For example, a value of "3d" in this field would cause the charge to recur every three days, whereas a value of "2m" would cause it to recur every two months.
<p>
Amount is identical to the amount passed to a sale or a preauth, and indicates the amount of each charge made during the subscription.
<p>
Start is an optional field which allows the delay of the cycle's start. By default, the cycle starts the day the billing ID is stored. If it is specified in the format YYYY-MM-DD, it indicates a date when the first payment should be made. (For example, "2005-02-01" would be February 1, 2005.) If it is in the same format as the cycle (a number followed by a character), it indicates an offset from the current date. (For example, "1d" would start the billing tomorrow.)
<p>
If there is no start parameter, the first transaction is run immediately (and can cause the store action to return a "decline" or other result you would expect from a sale). Other return parameters associated with auths, such as avs code, will be returned as well.
<p>
Payments is also optional; left blank or set to zero it will continue the billing cycle until it is manually interrupted by an unstore, or by updating the billing ID with cycle set to "null". Once the final payment is made, the billing ID will be unstored.
<p>
There is only one instance in which the cycle parameter is not required, and
that is a one-time future payment. By setting payments to "1" and passing a
start date, the payment will be made on that date and then the billing ID
unstored. The cycle parameter may be included with a one-time future
payment, but it will have no effect.
<p>
<h3>Recurring Billing Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'store',
'cc': '4111111111111111',
'exp': '0404',
'name': 'Jennifer Smith',
'amount': '1200'
}
mode = chooseSubscriptionMode()
if (mode == 1):
# Make a payment every day, infinitely (or until someone manually disables it)
params['cycle'] = '1d';
elif (mode == 2):
# Make a payment once a month for one year
params['cycle'] = '1m';
params['payments'] = '12';
elif (mode == 3):
# Make a payment every six weeks, starting one week from now
params['cycle'] = '62';
params['start'] = '1w';
elif (mode == 4):
# Make annual payments, and don't start until September 1, 2004
params['cycle'] = '1y';
params['start'] = '2004-09-01';
elif (mode == 5):
# Make a one time payment in 45 days
params['start'] = '45d';
params['payments'] = '1';
tclink.send(params)
</pre>
<p>
<a name=wallet></a><h2>XIII. TCS Wallet</h2>
The TCS Wallet is an additional service offered by the TrustCommerce gateway that allows you to run many small micropayments which are later lumped together and submitted as a single, large payment. This can offer a substantial savings for the merchant in transaction fees, as merchant account providers tend to penalize merchants that run small payments.
<p>
The Wallet is an extension of the billing ID system. It adds three new parameters to the store action, described below.
<center><h3>Wallet Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>wallet</td><td>"y" to enable the wallet.</td></tr>
<tr><td>walletsize</td><td>Accumulated amount, in cents, before the wallet is submitted for capture.</td></tr>
<tr><td>walletexposure</td><td>Length of time to wait before capturing the wallet.</td></tr>
</table>
<p>
In order to enable wallets for the billing ID that you are storing, set the "wallet" parameter to "y". The other two parameters are optional, as there are default values attached to your TC account. If you wish to change these values (which are normally $10.00 and 72 hours) please contact TrustCommerce. If you wish to change the values for an individual billing ID without changing your defaults, include these parameters.
<p>
Once the billing ID is stored, it is possible to use a new action type on the ID called walletsale. It is identical to a sale in all ways, except that it can only be used on wallet-enabled billing IDs, and it can accept amounts anywhere from $0.01 up to the size of the wallet. Walletsale will usually return "approved", but it may return "decline" if the stored credit card fails to re-authorize when the current wallet is exceeded.
Except for these two modifications (the wallet parameters on the store, and changing sales to walletsales), there is no extra development to be done client-side to make wallets work. Captures happen automatically after walletexposure has expired or the walletamount has been used up; reauthorizations also happen automatically.
<p>
<h3>Wallet Example</h3>
<pre>
# First, store a new ID with the wallet enabled.
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'store',
'cc': '4111111111111111',
'exp': '0404',
'name': 'Jennifer Smith',
'wallet': 'y'
}
result = tclink.send(params)
if (result['status'] == 'approved'):
# We have a new wallet at our disposal. Run a micropayment on it.
billingid = result['billingid']
params2 = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'walletsale',
'billingid': billingid,
'amount': '995'
}
tclink.send(params)
</pre>
<p>
<a name=pl2></a><h2>XIV. Purchase Level II</h2>
Purchase Level II is required by some merchant banks to achieve a qualifed discount rate. It is only used for B2B or B2G transactions. If you are selling products directly to consumers, you do not need to use PL2. Additionally, PL2 can only be used if the cardholder is using one of the three types of commercial cards: a corporate card, a business card, or a purchasing card.
<p>
PL2 has three new parmaeters:
<center><h3>PL2 Input Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>purchaselevel</td><td>Specify as "2".</td></tr>
<tr><td>purchaseordernum</td><td>The purchasing order number from their Visa purchasing card. This is either a 16 or a 17 digit number. If they are not using a Visa purchasing card, do not pass this field.</td></tr>
<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>
</table>
<p>
A successful PL2 transaction will return one extra response parameter
<p>
<center><h3>PL2 Output Parameter</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<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>
</table>
<p>
If you don't care what kind of card they used (which you probably don't), there is no reason to store or otherwise do anything with the commercialcard return value. TrustCommerce internally handles all the details for you. However, if you want this information for some reason, you can access it from the result parameters.
<p>
<h3>Purchase Level II Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'sale',
'cc': '4111111111111111',
'exp': '0404',
'amount': '1000'
'name': 'Jennifer Smith',
'purchaselevel': '2'
'purchaseordernum': '12345678901234567'
'tax': '83' # $10.00 x 8.25% sales tax = $0.83
}
result = tclink.send(params)
if (result['status'] == 'approved'):
print 'Approved'
</pre>
<p>
<a name=orderdetail></a><h2>XV. Order Detail</h2>
TrustCommerce offers the unique feature of automated fulfillment, by which orders submitted through the TCLink API can contain parameters describing product information. This information is then passed on to your fulfillment house, which ships the products automatically. Even if you aren't using automated fulfillment, you can use the order line item specification parameters to store information in the TrustCommerce transaction database about the type of products ordered.
<p>
First, you may wish to specify the shipping address for the customer. If it is the same as the billing address, you need not duplicate it, but rather just send the shiptosame parameter set to y. The table below enumerates the shipping parameters.
<center><h3>ShipTo Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>shiptosame</td><td>y or n (defaults to n). If "y", then no other shipto_ parameters should be passed.</td></tr>
<tr><td>shipto_name</td><td>Name of the product recipient.</td></tr>
<tr><td>shipto_address1</td><td>First line of shipping address.</td></tr>
<tr><td>shipto_address2</td><td>Second line (if any) of shipping address.</td></tr>
<tr><td>shipto_city</td><td>City.</td></tr>
<tr><td>shipto_state</td><td>State.</td></tr>
<tr><td>shipto_zip</td><td>Zipcode, five or nine digits (no spaces or dashes).</td></tr>
<tr><td>shipto_country</td><td>Country, leave blank for US.</td></tr>
</table>
<p>
Second, some additional data about the order as a whole should be passed in the form of the following parameters.
<center><h3>Order Header Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>shippingcode</td><td>Three character code indicating shipping method to use.</td></tr>
<tr><td>shippinghandling</td><td>The total cost of shipping and handling, in cents.</td></tr>
<tr><td>numitems</td><td>Total number of distinct items (product codes) in the order.</td></tr>
</table>
<p>
Finally, a number of parameters which describe the details of each type of item must be passed. In the table below, the 'X' character in the parameter name should be replaced with a digit indicating which item it applies to. For example, if numitems is set to three, then you should pass three product codes, in the form of productcode1, productcode2, and productcode3.
<center><h3>Order Detail Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Description</th></tr>
<tr><td>productcodeX</td><td>The alphanumeric product code defined by the fulfillment house.</td></tr>
<tr><td>quantityX</td><td>The number of items of this type to be shipped.</td></tr>
<tr><td>priceX</td><td>The price of all items of this type not including sales tax or shipping, in cents.</td></tr>
<tr><td>taxX</td><td>Total tax charged for all items of this product code.</td></tr>
<tr><td>shippinghandlingX</td><td>Total shipping and handling charged for all items of this product code.</td></tr>
</table>
<p>
Please note: the shippinghandling field and the shippinghandlingX fields are mutually exclusive. Use one or the other, but not both. If you're not sure which to use, please contact your fulfillment house.
<p>
<h3>Fulfillment Example</h3>
<pre>
params = {
'custid': 'mycustid',
'password': 'mypass',
'action': 'preauth',
'cc': '4111111111111111',
'exp': '0404',
'amount': '1979', # Total of items, tax, and shipping
'name': 'Jennifer Smith',
'address1': '123 Test St.',
'city': 'Somewhere',
'state': 'CA',
'zip': '90001',
'shiptosame': 'y', # Shipping address is same as billing address
'numitems': '2', # Two total product codes will be described
'shippingcode': 'OVRNGT',
'shippinghandling': '695',
'productcode1': 'PCODE1',
'quantity1': '3',
'price1': '600', # Item 1 costs $2.00, and there are 3 of them
'tax1': '144', # Tax of 8%
'productcode2': 'PCODE2',
'quantity2': '1',
'price2': '500', # Item 1 costs $5.00, there's only one
'tax2': '40' # Tax of 8%
}
tclink.send(params)
</pre>
<p>
<a name=query></a><h2>XVI. Vault Query API</h2>
The Vault website serves as a web-based interface for merchant reconciliation. On the backend, it is a complex database that tracks all transactional data for your TrustCommerce account. The information contained in the Vault can be accessed at the API level using a standard CGI query over HTTPS.
<p>
The query API returns data in CSV (comma separated value) format, which is just a flat text file with fields separated by commas, and records separated by newlines. (You can also request the data returned in an HTML table, which is useful for debugging.) The first line of the file contains the name of each field that will be returned in subsequent records.
<p>
The parameters that the query interface accepts are described in the table below.
<center><h3>Required Parameters</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Parameter Name</th><th>Requred?</th><th>Description</th></tr>
<tr><td>custid</td><td align=center>X</td><td>TrustCommerce customer ID number.</td></tr>
<tr><td>password</td><td align=center>X</td><td>The password for your custID.</td></tr>
<tr><td>format</td><td> </td><td>Set to "html" for human-readable HTML output, or "text" (default) for CSV text output.</td></tr>
<tr><td>querytype</td><td align=center>X</td><td>Possible values are: chain, transaction, summary, or billingid, corresponding to the equivalent reports on the Vault website. Read the User's Guide for further description of each report type.</td></tr>
<tr><td>media</td><td> </td><td>Set to "cc" (default) or "ach" for media type.</td></tr>
<tr><td>begindate</td><td> </td><td>Begin date for query, format: MM-DD-YYYY HH:MM:SS</td></tr>
<tr><td>enddate</td><td> </td><td>End date for query, format: MM-DD-YYYY HH:MM:SS</td></tr>
<tr><td>chain</td><td> </td><td>Narrow search to a single chain of transactions.</td></tr>
<tr><td>transid</td><td> </td><td>Narrow search to a single transaction ID.</td></tr>
<tr><td>billingid</td><td> </td><td>Narrow search to a single billing ID.</td></tr>
<tr><td>pastdue</td><td> </td><td>Use 'y' or 'n'. For billing ID search. Show only recurring billing IDs that have been unable to capture the requested funds.</td></tr>
<tr><td>action</td><td> </td><td>Narrow search by action (preauth, sale, credit, etc).</td></tr>
<tr><td>status</td><td> </td><td>Narrow search by status (approved, accepted, decline, etc).</td></tr>
<tr><td>name</td><td> </td><td>Narrow search by cardholder name, partial or complete.</td></tr>
<tr><td>cc</td><td> </td><td>Narrow search by credit card number.</td></tr>
<tr><td>limit</td><td> </td><td>Do not allow size of result set to exceed this number of records.</td></tr>
<tr><td>offset</td><td> </td><td>Report result set starting from this offset. Use this parameter in conjunction with limit in order to page through a large result set.</td></tr>
<tr><td>showcount</td><td> </td><td>Show the number of records returned on the last line of the result set.</td></tr>
</table>
<p>
The sample HTML code shown below illustrates the functionality of the query API. It can be pasted into a file and loaded on your web browser in order to try out some queries before you even begin to write your code.
<p>
<h3>Query Example HTML</h3>
<pre>
<html>
<head> <title> TrustCommerce Query Interface </title> </head>
<body>
<h2> TrustCommerce Query Interface </h2>
<form action=https://vault.trustcommerce.com/query/>
<table align=center border=1>
<tr>
<td> custid </td>
<td> <input type=text name=custid> </td>
<td> This is your TrustCommerce custid (required) </td>
</tr>
<tr>
<td> password </td>
<td> <input type=password name=password> </td>
<td> This is your TrustCommerce password (required) </td>
</tr>
<tr>
<td> format </td>
<td> <select name=format> <option value=text>text</option>
<option value=html>html</option></select></td>
<td> Human readable (html) or computer readable (text) results</td>
</tr>
<tr>
<td> Query type </td>
<td> <select name=querytype>
<option value=chain>chain</option>
<option value=transaction>transaction</option>
<option value=summary>summary</option>
<option value=billingid>billingid</option>
</select></td>
<td> Type of query </td>
</tr>
<tr>
<td> media </td>
<td> <input type=text name=media value=cc> </td>
<td> For now this must be cc </td>
</tr>
<tr>
<td> begindate MM-DD-YYYY HH:MM:SS </td>
<td> <input type=text name=begindate> </td>
<td> Query begins at this date</td>
</tr>
<tr>
<td> enddate MM-DD-YYYY HH:MM:SS </td>
<td> <input type=text name=enddate> </td>
<td> Query ends at this date</td>
</tr>
<tr>
<td> chain </td>
<td> <input type=text name=chain> </td>
<td> Narrow search to a single chain of transactions </td>
</tr>
<tr>
<td> transid </td>
<td> <input type=text name=transid> </td>
<td> Narrow search to a single transactions </td>
</tr>
<tr>
<td> billingid </td>
<td> <input type=text name=transid> </td>
<td> Narrow search to a single billingid </td>
</tr>
<tr>
<td> pastdue </td>
<td> <select name=pastdue>
<option value=y>y</option>
<option value=n>n</option>
</select></td>
<td> Use 'y' or 'n'. For billing ID search. Show only recurring billing IDs
that have been unable to capture the requested funds. </td>
</tr>
<tr>
<td> action </td>
<td> <input type=text name=action> </td>
<td> Narrow search by action. (example: preauth,postauth) </td>
</tr>
<tr>
<td> status </td>
<td> <input type=text name=status> </td>
<td> Narrow search by status. (example: approved,accepted) </td>
</tr>
<tr>
<td> name </td>
<td> <input type=text name=name> </td>
<td> Narrow search by name. </td>
</tr>
<tr>
<td> cc </td>
<td> <input type=text name=cc> </td>
<td> Narrow search by credit card field. </td>
</tr>
<tr>
<td> limit </td>
<td> <input type=text name=limit value=20> </td>
<td> Limit results to this number of fields (not used for summary)</td>
</tr>
<tr>
<td> offset </td>
<td> <input type=text name=offset value=0> </td>
<td> Report results at this offset (used with limit to page through results)</td>
</tr>
<tr>
<td> showcount </td>
<td> <select name=showcount>
<option value=y>yes</option>
<option value=n>no</option>
</select></td>
<td> Show the number of not-limited rows on the last line of the result</td>
</tr>
<tr>
<td colspan=3> <input type=submit> </td>
</tr>
</table>
</form>
</body>
</html>
</pre>
<p>
<a name=testdata></a><h2>Appendix A - Test Data</h2>
While testing, you may wish to experiment with the different responses that the gateway can generate. The following test card numbers will produce an approval, and have address data as listed, for testing AVS. If you wish to test CVV, the code listed int he right-hand column is the correct CVV code, Other valid credit cards will work, but will produce a 'U' AVS code.<p>
Please note: these cards ONLY work on transactions flagged as demo, or while your account is in "test" mode! For a live transaction, they will all return a decline with a declinetype of carderror.
<center><h3>Test Cards - Approved</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<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>
<tr><td>Visa</td><td>4111111111111111</td><td>04/04</td><td>123 Test St.</td><td>Somewhere</td><td>CA</td><td>90001</td><td>123</td></tr>
<tr><td>Mastercard</td><td>5411111111111115</td><td>04/04</td><td>4000 Main St.</td><td>Anytown</td><td>AZ</td><td>85001</td><td>777</td></tr>
<tr><td>American Express</td><td>341111111111111</td><td>04/04</td><td>12 Colorado Blvd.</td><td>Elsewhere</td><td>IL</td><td>54321</td><td>4000</td></tr>
<tr><td>Discover</td><td>6011111111111117</td><td>04/04</td><td>6789 Green Ave.</td><td>Nowhere</td><td>MA</td><td>12345</td><td> - </td></tr>
<tr><td>Diner's Club</td><td>36484444444446</td><td>04/04</td><td>7390 Del Mar Blvd.</td><td>Atown</td><td>NY</td><td>01101</td><td> - </td></tr>
<tr><td>JCB</td><td>213122222222221</td><td>04/04</td><td>350 Madison Ave.</td><td>Springfield</td><td>OH</td><td>400000</td><td> - </td></tr>
</table>
<p>
The following card numbers will generate a decline, with the declinetype listed as follows. You may use this to test code which takes different paths dependant upon the type of decline.
<center><h3>Test Cards - Declined</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Card Number</th><th>Exp</th><th>DeclineType</th></tr>
<tr><td>4012345678909</td><td>04/04</td><td>decline</td>
<tr><td>5555444433332226</td><td>04/04</td><td>call</td>
<tr><td>4444111144441111</td><td>04/04</td><td>carderror</td>
</table>
<p>
You should also test your code to make sure it properly handles all baddata and error cases as listed in section X. Simply pass bad values in order to generate these situations.
<p>
<a name=troubleshooting></a><h2>Appendix B - Troubleshooting</h2>
Details about installing and troubleshooting TCLink specific to your development platform can be found in the documentation included with the TCLink archive.
<p>
Once you are able to connect to the TC gateway, you should be able to diagnose parameter-related issues using the status, error, declinetype, and errortype parameters returned by the gateway. There is one response which indicates a more generic error, and that's an error of <b>cantconnect</b>. First, check the computer's network connection; can you ping machines on the Internet, by IP or by name?
<p>
The most common network connectivity error is that your target computer may be behind a firewall. TCLink uses the HTTPS port (443/tcp) for network communications; you can check whether this port is open from the target machine by typing "telnet vault.trustcommerce.com 443" at a UNIX command prompt, or else by loading a web browser on the target machine and attempting to visit https://vault.trustcommerce.com directly. If you timeout attempting to make the connection, but your Internet connection is working otherwise, then you may be firewalled. Speak to your network administrator about allowing outbound TCP traffic on port 443.
<p>
Another common problem is the lack of domain name (DNS) resolution. In some cases this will result in an errortype <b>dnsfailure</b>. (Not always; the TCLink software will sometimes fall back to hardcoded IP addresses for established accounts. But this method is insecure and error-prone, and is used only as a last resort to keep a system with temporary DNS issues up and running during the outage.) The target machine must be able to resolve the trustcommerce.com domain; try typing "host trustcommerce.com" from a UNIX command prompt. If you don't get a response, or get an error, then the machine cannot resolve DNS information and TCLink will not be able to connect to the TC gateway. Speak to your sysadmin about making domain name resolution available to your target host.
<p>
<a name=httpspost></a><h2>Appendix C - Connecting via HTTPS POST</h2>
This method should only be used if a TCLink client install is not an option. It does not have the failover capability (and thus the processing uptime is not guaranteed to be 100%), or some of the enhanced security features of TCLink. In addition, transactions may be slightly slower, by an extra half second or so. It does, however support all other features available through TCLink, including all parameters and transaction types.
<p>
This is the URL:
<p>
<a href=https://vault.trustcommerce.com/trans/>https://vault.trustcommerce.com/trans/</a>
<p>
The transaction should be sent as a standard POST, with CGI parameters, URL encoded. The parameters are otherwise identical to those used through TCLink.
<p>
Response parameters are returned as name-value pairs separated by newlines.
<p>
<a name=currency></a><h2>Appendix D - Currency Table</h2>
<center><h3>Currency Codes</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Code</th><th>Currency Type</th><th>Code</th><th>Currency Type</th></tr>
<tr><td>usd</td><td>US Dollars</td><td>jpy</td><td>Japan Yen</td></tr>
<tr><td>eur</td><td>Euro</td><td>jod</td><td>Jordan Dinar</td></tr>
<tr><td>cad</td><td>Canadian Dollars</td><td>krw</td><td>Korea (South) Won</td></tr>
<tr><td>gbp</td><td>UK Pounds</td><td>lbp</td><td>Lebanon Pounds</td></tr>
<tr><td>dem</td><td>German Deutschemarks</td><td>luf</td><td>Luxembourg Francs</td></tr>
<tr><td>frf</td><td>French Francs</td><td>myr</td><td>Malaysia Ringgit</td></tr>
<tr><td>jpy</td><td>Japanese Yen</td><td>mxp</td><td>Mexico Pesos</td></tr>
<tr><td>nlg</td><td>Dutch Guilders</td><td>nlg</td><td>Netherlands Guilders</td></tr>
<tr><td>itl</td><td>Italian Lira</td><td>nzd</td><td>New Zealand Dollars</td></tr>
<tr><td>chf</td><td>Switzerland Francs</td><td>nok</td><td>Norway Kroner</td></tr>
<tr><td>dzd</td><td>Algeria Dinars</td><td>pkr</td><td>Pakistan Rupees</td></tr>
<tr><td>arp</td><td>Argentina Pesos</td><td>xpd</td><td>Palladium Ounces</td></tr>
<tr><td>aud</td><td>Australia Dollars</td><td>php</td><td>Philippines Pesos</td></tr>
<tr><td>ats</td><td>Austria Schillings</td><td>xpt</td><td>Platinum Ounces</td></tr>
<tr><td>bsd</td><td>Bahamas Dollars</td><td>plz</td><td>Poland Zloty</td></tr>
<tr><td>bbd</td><td>Barbados Dollars</td><td>pte</td><td>Portugal Escudo</td></tr>
<tr><td>bef</td><td>Belgium Francs</td><td>rol</td><td>Romania Leu</td></tr>
<tr><td>bmd</td><td>Bermuda Dollars</td><td>rur</td><td>Russia Rubles</td></tr>
<tr><td>brr</td><td>Brazil Real</td><td>sar</td><td>Saudi Arabia Riyal</td></tr>
<tr><td>bgl</td><td>Bulgaria Lev</td><td>xag</td><td>Silver Ounces</td></tr>
<tr><td>cad</td><td>Canada Dollars</td><td>sgd</td><td>Singapore Dollars</td></tr>
<tr><td>clp</td><td>Chile Pesos</td><td>skk</td><td>Slovakia Koruna</td></tr>
<tr><td>cny</td><td>China Yuan Renmimbi</td><td>zar</td><td>South Africa Rand</td></tr>
<tr><td>cyp</td><td>Cyprus Pounds</td><td>krw</td><td>South Korea Won</td></tr>
<tr><td>csk</td><td>Czech Republic Koruna</td><td>esp</td><td>Spain Pesetas</td></tr>
<tr><td>dkk</td><td>Denmark Kroner</td><td>xdr</td><td>Special Drawing Right (IMF)</td></tr>
<tr><td>nlg</td><td>Dutch Guilders</td><td>sdd</td><td>Sudan Dinar</td></tr>
<tr><td>xcd</td><td>Eastern Caribbean Dollars</td><td>sek</td><td>Sweden Krona</td></tr>
<tr><td>egp</td><td>Egypt Pounds</td><td>chf</td><td>Switzerland Francs</td></tr>
<tr><td>eur</td><td>Euro</td><td>twd</td><td>Taiwan Dollars</td></tr>
<tr><td>fjd</td><td>Fiji Dollars</td><td>thb</td><td>Thailand Baht</td></tr>
<tr><td>fim</td><td>Finland Markka</td><td>ttd</td><td>Trinidad and Tobago Dollars</td></tr>
<tr><td>frf</td><td>France Francs</td><td>trl</td><td>Turkey Lira</td></tr>
<tr><td>dem</td><td>Germany Deutsche Marks</td><td>gbp</td><td>United Kingdom Pounds</td></tr>
<tr><td>xau</td><td>Gold Ounces</td><td>usd</td><td>United States Dollars</td></tr>
<tr><td>grd</td><td>Greece Drachmas</td><td>veb</td><td>Venezuela Bolivar</td></tr>
<tr><td>hkd</td><td>Hong Kong Dollars</td><td>zmk</td><td>Zambia Kwacha</td></tr>
<tr><td>huf</td><td>Hungary Forint</td><td>eur</td><td>Euro</td></tr>
<tr><td>isk</td><td>Iceland Krona</td><td>xcd</td><td>Eastern Caribbean Dollars</td></tr>
<tr><td>inr</td><td>India Rupees</td><td>xdr</td><td>Special Drawing Right (IMF)</td></tr>
<tr><td>idr</td><td>Indonesia Rupiah</td><td>xag</td><td>Silver Ounces</td></tr>
<tr><td>iep</td><td>Ireland Punt</td><td>xau</td><td>Gold Ounces</td></tr>
<tr><td>ils</td><td>Israel New Shekels</td><td>xpd</td><td>Palladium Ounces</td></tr>
<tr><td>itl</td><td>Italy Lira</td><td>xpt</td><td>Platinum Ounces</td></tr>
<tr><td>jmd</td><td>Jamaica Dollars</td><td> </td><td> </td></tr>
</table>
<p>
<a name=inputfields></a><h2>Appendix E - Input Field List</h2>
<center><h3>Input Fields</h3></center>
<table align=center border=1 cellpadding=5 bgcolor=#e0e0e0>
<tr><th>Name</th><th>Type</th><th>Minimum Length</th><th>Maximum Length</th></tr>
<tr><td>custid</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>password</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>action</td><td>string</td><td>1</td><td>10</td></tr>
<tr><td>media</td><td>string</td><td>1</td><td>10</td></tr>
<tr><td>currency</td><td>string</td><td>3</td><td>3</td></tr>
<tr><td>amount</td><td>number</td><td>3</td><td>8</td></tr>
<tr><td>cc</td><td>number</td><td>13</td><td>16</td></tr>
<tr><td>exp</td><td>number</td><td>4</td><td>4</td></tr>
<tr><td>cvv</td><td>number</td><td>3</td><td>4</td></tr>
<tr><td>routing</td><td>number</td><td>9</td><td>9</td></tr>
<tr><td>account</td><td>number</td><td>3</td><td>17</td></tr>
<tr><td>billingid</td><td>string</td><td>6</td><td>6</td></tr>
<tr><td>verify</td><td>string</td><td>1</td><td>1</td></tr>
<tr><td>transid</td><td>string</td><td>14</td><td>14</td></tr>
<tr><td>avs</td><td>string</td><td>1</td><td>10</td></tr>
<tr><td>name</td><td>string</td><td>1</td><td>60</td></tr>
<tr><td>address1</td><td>string</td><td>1</td><td>80</td></tr>
<tr><td>address2</td><td>string</td><td>1</td><td>80</td></tr>
<tr><td>zip</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>city</td><td>string</td><td>1</td><td>40</td></tr>
<tr><td>state</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>country</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>phone</td><td>string</td><td>1</td><td>30</td></tr>
<tr><td>email</td><td>string</td><td>1</td><td>50</td></tr>
<tr><td>track1</td><td>string</td><td>1</td><td>79</td></tr>
<tr><td>track2</td><td>string</td><td>1</td><td>40</td></tr>
<tr><td>ticket</td><td>string</td><td>1</td><td>30</td></tr>
<tr><td>operator</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shiptosame</td><td>string</td><td>1</td><td>1</td></tr>
<tr><td>shipto_name</td><td>string</td><td>1</td><td>60</td></tr>
<tr><td>shipto_address1</td><td>string</td><td>1</td><td>40</td></tr>
<tr><td>shipto_address2</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shipto_city</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shipto_state</td><td>string</td><td>2</td><td>2</td></tr>
<tr><td>shipto_zip</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shipto_country</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>numitems</td><td>number</td><td>1</td><td>3</td></tr>
<tr><td>price</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shippingcode</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>shippinghandling</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>productcode#</td><td>string</td><td>1</td><td>20</td></tr>
<tr><td>quantity#</td><td>number</td><td>1</td><td>3</td></tr>
<tr><td>price#</td><td>number</td><td>1</td><td>6</td></tr>
<tr><td>tax#</td><td>number</td><td>1</td><td>6</td></tr>
<tr><td>shippinghandling#</td><td>number</td><td>1</td><td>6</td></tr>
<tr><td>wallet</td><td>string</td><td>1</td><td>1</td></tr>
<tr><td>walletsize</td><td>string</td><td>3</td><td>8</td></tr>
<tr><td>walletexposure</td><td>string</td><td>1</td><td>3</td></tr>
<tr><td>start</td><td>string</td><td>2</td><td>10</td></tr>
<tr><td>cycle</td><td>string</td><td>2</td><td>4</td></tr>
<tr><td>payments</td><td>number</td><td>1</td><td>4</td></tr>
<tr><td>demo</td><td>string</td><td>1</td><td>1</td></tr>
<tr><td>offlineauthcode</td><td>string</td><td>6</td><td>6</td></tr>
</table>
<p>
<hr>
<center><font size=-1><i>Copyright © 2003 TrustCommerce</i></font></center>
</body>
</html>
|
