     ----------------------------------------------------------------------

                      TrustCommerce Developer's Guide 2.3

   http://www.trustcommerce.com
   developer@trustcommerce.com

   March 18, 2003

     ----------------------------------------------------------------------

Table of Contents

   I. Introduction                           
   II. Connecting via TCLink                 
   III. Transaction Types                    
   IV. Input Parameters                      
   V. Return Parameters                      
   VI. Credit Card Preauths and Sales        
   VII. Card Verification Value (CVV)        
   VII. Card-Present Transactions            
   IX. ACH                                   
   X. Postauths, Credits, and Chargebacks    
   XI. TCS Citadel (Billing IDs)             
   XII. Recurring Billing                    
   XIII. TCS Wallet                          
   XIV. Purchase Level II (Commercial Cards) 
   XIV. Order Detail                         
   XVI. Vault Query API                      
   Appendix A - Test Data                    
   Appendix B - Troubleshooting              
   Appendix C - Connecting via HTTPS POST    
   Appendix D - Currency Table               
   Appendix E - Input Field List             

     ----------------------------------------------------------------------

I. Introduction

   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.

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

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

II. Connecting via TCLink

   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.

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

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

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

  TCLink Function Names

   +------------------------------------------------------------------------+
   |    Function Name    |                   Description                    |
   |---------------------+--------------------------------------------------|
   | CreateLink()        | Create a new transaction handle.                 |
   |---------------------+--------------------------------------------------|
   | PushParam()         | Push a parameter into the transaction.           |
   |---------------------+--------------------------------------------------|
   | Send()              | Submit a transaction to the gateway.             |
   |---------------------+--------------------------------------------------|
   | GetResponse()       | Retrieve a response parameter from the           |
   |                     | transaction.                                     |
   |---------------------+--------------------------------------------------|
   | GetEntireResponse() | Get the entire response for the transaction,     |
   |                     | primarily use for debugging or logging.          |
   |---------------------+--------------------------------------------------|
   | Destroy()           | Deallocate any memory associated with the        |
   |                     | transaction handle.                              |
   |---------------------+--------------------------------------------------|
   | GetVersion()        | Get the version string for the TCLink API in     |
   |                     | use.                                             |
   +------------------------------------------------------------------------+

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

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

III. Transaction Types

   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.

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

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

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

IV. Input Parameters

   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.

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

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

  Required Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | amount         | Amount of the transaction, in cents. (example: "500"  |
   |                | is $5.00)                                             |
   |----------------+-------------------------------------------------------|
   | custid         | Your customer ID number assigned to you by            |
   |                | TrustCommerce.                                        |
   |----------------+-------------------------------------------------------|
   | password       | The password for your custid as assigned by           |
   |                | TrustCommerce.                                        |
   |----------------+-------------------------------------------------------|
   |                | The transaction type; can be one of preauth, sale,    |
   | action         | postauth, credit, store, unstore, walletsale, or      |
   |                | chargeback                                            |
   +------------------------------------------------------------------------+

  Optional Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | amount         | Amount of the transaction, in cents. (example: "500"  |
   |                | is $5.00)                                             |
   |----------------+-------------------------------------------------------|
   | demo           | When set to "y", the transaction will be a test       |
   |                | transaction only.                                     |
   |----------------+-------------------------------------------------------|
   |                | Free-form text field intended for storing ticket      |
   | ticket         | number or order number associated with the            |
   |                | transaction, to aid merchants in order tracking and   |
   |                | reporting.                                            |
   |----------------+-------------------------------------------------------|
   |                | Free-form text field intended for recording the       |
   | operator       | operator that entered the transaction, to aid         |
   |                | merchants in order track and reporting.               |
   +------------------------------------------------------------------------+

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

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

V. Return Parameters

   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.)

   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:

  Status

   +------------------------------------------------------------------------+
   | Status Value |                       Description                       |
   |--------------+---------------------------------------------------------|
   | approved     | The transaction was successfully authorized.            |
   |--------------+---------------------------------------------------------|
   | accepted     | The transaction has been successfully accepted into the |
   |              | system.                                                 |
   |--------------+---------------------------------------------------------|
   | decline      | The transaction was declined, see declinetype for       |
   |              | further details.                                        |
   |--------------+---------------------------------------------------------|
   | baddata      | Invalid parameters passed, see error for further        |
   |              | details.                                                |
   |--------------+---------------------------------------------------------|
   | error        | System error when processing the transaction, see       |
   |              | errortype for details.                                  |
   +------------------------------------------------------------------------+

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

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

  Decline Type

   +------------------------------------------------------------------------+
   | Declinetype Value |                    Description                     |
   |-------------------+----------------------------------------------------|
   | decline           | This is a "true" decline, it almost always is a    |
   |                   | result of insufficient funds on the card.          |
   |-------------------+----------------------------------------------------|
   | avs               | AVS failed; the address entered does not match the |
   |                   | billing address on file at the bank.               |
   |-------------------+----------------------------------------------------|
   |                   | CVV failed; the number provided is not the correct |
   | cvv               | verification number for the card. (See section X   |
   |                   | for details on CVV.)                               |
   |-------------------+----------------------------------------------------|
   |                   | The card must be authorized manually over the      |
   |                   | phone. You may choose to call the customer service |
   | call              | number listed on the card and ask for an offline   |
   |                   | authcode, which can be passed in the               |
   |                   | offlineauthcode field.                             |
   |-------------------+----------------------------------------------------|
   | carderror         | Card number is invalid, usually the result of a    |
   |                   | typo in the card number.                           |
   |-------------------+----------------------------------------------------|
   | authexpired       | Attempt to postauth an expired (more than 7 days   |
   |                   | old) preauth.                                      |
   |-------------------+----------------------------------------------------|
   | dailylimit        | Daily limit in transaction count or amount as been |
   |                   | reached.                                           |
   |-------------------+----------------------------------------------------|
   | weeklylimit       | Weekly limit in transaction count or amount as     |
   |                   | been reached.                                      |
   |-------------------+----------------------------------------------------|
   | monthlylimit      | Monthly limit in transaction count or amount as    |
   |                   | been reached.                                      |
   +------------------------------------------------------------------------+

   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:

  Bad Data

   +------------------------------------------------------------------------+
   |    Error Value     |                    Description                    |
   |--------------------+---------------------------------------------------|
   | missingfields      | Some parameters required for this transaction     |
   |                    | type were not sent.                               |
   |--------------------+---------------------------------------------------|
   | extrafields        | Parameters not allowed for this transaction type  |
   |                    | were sent.                                        |
   |--------------------+---------------------------------------------------|
   | badformat          | A field was improperly formatted, such as         |
   |                    | non-digit characters in a number field.           |
   |--------------------+---------------------------------------------------|
   | badlength          | A field was longer or shorter than the server     |
   |                    | allows.                                           |
   |--------------------+---------------------------------------------------|
   |                    | 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   |
   | merchantcantaccept | (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.                        |
   |--------------------+---------------------------------------------------|
   | mismatch           | Data in one of the offending fields did not       |
   |                    | cross-check with the other offending field.       |
   +------------------------------------------------------------------------+

   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:

  Error

   +------------------------------------------------------------------------+
   | Errortype Value |                     Description                      |
   |-----------------+------------------------------------------------------|
   | cantconnect     | Couldn't connect to the TrustCommerce gateway. Check |
   |                 | your Internet connection to make sure it is up.      |
   |-----------------+------------------------------------------------------|
   |                 | The TCLink software was unable to resolve DNS        |
   | dnsfailure      | hostnames. Make sure you have name resolving ability |
   |                 | on the machine.                                      |
   |-----------------+------------------------------------------------------|
   | linkfailure     | The connection was established, but was severed      |
   |                 | before the transaction could complete.               |
   |-----------------+------------------------------------------------------|
   |                 | The bank servers are offline and unable to authorize |
   | failtoprocess   | transactions. Try again in a few minutes, or try a   |
   |                 | card from a different issuing bank.                  |
   +------------------------------------------------------------------------+

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

VI. Credit Card Preauths and Sales

   The '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.

   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.

  Required Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | amount         | Amount of the transaction, in cents. (example: "500"  |
   |                | is $5.00)                                             |
   |----------------+-------------------------------------------------------|
   | cc             | Credit card number, digits only (no spaces or dashes) |
   |----------------+-------------------------------------------------------|
   | exp            | Credit card expiration date, in MMYY format           |
   +------------------------------------------------------------------------+

  Optional Parameters

   +------------------------------------------------------------------------+
   | Parameter Name  | Default Value |             Description              |
   |-----------------+---------------+--------------------------------------|
   | media           | cc            | "cc" for credit card or "ach" for    |
   |                 |               | ACH.                                 |
   |-----------------+---------------+--------------------------------------|
   | currency        | usd           | Currency code (see section X for the |
   |                 |               | table of codes)                      |
   |-----------------+---------------+--------------------------------------|
   | avs             | n             | AVS requested, "y" or "n" (see notes |
   |                 |               | below).                              |
   |-----------------+---------------+--------------------------------------|
   | name            |               | Cardholder's name.                   |
   |-----------------+---------------+--------------------------------------|
   | address1        |               | First line of cardholder's street    |
   |                 |               | address.                             |
   |-----------------+---------------+--------------------------------------|
   | address2        |               | Second line of cardholder's street   |
   |                 |               | address.                             |
   |-----------------+---------------+--------------------------------------|
   | city            |               | Cardholder's city.                   |
   |-----------------+---------------+--------------------------------------|
   |                 |               | Two-character code for the           |
   | state           |               | cardholder's state, or the full      |
   |                 |               | region/province for international    |
   |                 |               | addresses.                           |
   |-----------------+---------------+--------------------------------------|
   |                 |               | Cardholder's zipcode, five or nine   |
   | zip             |               | digits with no spaces or dashes, or  |
   |                 |               | the full postal code for             |
   |                 |               | international addresses.             |
   |-----------------+---------------+--------------------------------------|
   | country         |               | Cardholder's country, leave blank    |
   |                 |               | for US.                              |
   |-----------------+---------------+--------------------------------------|
   | phone           |               | Cardholder's phone number.           |
   |-----------------+---------------+--------------------------------------|
   | email           |               | Cardholder's email address.          |
   |-----------------+---------------+--------------------------------------|
   |                 |               | Six-digit numeric code used to       |
   | offlineauthcode |               | "force" the transaction (see notes   |
   |                 |               | below).                              |
   +------------------------------------------------------------------------+

   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.

  AVS Returns Codes

         +------------------------------------------------------------+
         | Code |                     Description                     |
         |------+-----------------------------------------------------|
         |  X   | Exact match, 9 digit zipcode.                       |
         |------+-----------------------------------------------------|
         |  Y   | Exact match, 5 digit zipcode.                       |
         |------+-----------------------------------------------------|
         |  A   | Street address match only.                          |
         |------+-----------------------------------------------------|
         |  W   | 9 digit zipcode match only.                         |
         |------+-----------------------------------------------------|
         |  Z   | 5 digit zipcode match only.                         |
         |------+-----------------------------------------------------|
         |  N   | No match on street address or zipcode.              |
         |------+-----------------------------------------------------|
         |  U   | AVS unavailable on this card.                       |
         |------+-----------------------------------------------------|
         |  G   | Non-US card issuer, AVS unavailable.                |
         |------+-----------------------------------------------------|
         |  R   | Card issuer system currently down, try again later. |
         |------+-----------------------------------------------------|
         |  E   | Error, ineligible - not a mail/phone order.         |
         |------+-----------------------------------------------------|
         |  S   | Service not supported.                              |
         |------+-----------------------------------------------------|
         |  0   | General decline or other error.                     |
         +------------------------------------------------------------+

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

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

  Preauth/Sale Example

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

         result = tclink.send(params)

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

         print 'Here are the full details:'
         print result

VII. Card Verification Value (CVV)

   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.

  CVV Parameters

             +----------------------------------------------------+
             | Parameter Name |            Description            |
             |----------------+-----------------------------------|
             | cvv            | A three or four digit CVV number. |
             +----------------------------------------------------+

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

  CVV Example

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

         result = tclink.send(params)

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

VII. Card-Present Transactions

   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.

  Card-Present Parameters

              +--------------------------------------------------+
              | Parameter Name |           Description           |
              |----------------+---------------------------------|
              | track1         | Up to 79 bytes of Track 1 data. |
              |----------------+---------------------------------|
              | track2         | Up to 40 bytes of Track 2 data. |
              +--------------------------------------------------+

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

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

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

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

  Card Present Example

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

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

         result = tclink.send(params)

IX. ACH

   ACH, 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.

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

  ACH Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | routing        | The routing number of the bank being debited.         |
   |----------------+-------------------------------------------------------|
   | account        | The account number of the person or business being    |
   |                | debited.                                              |
   +------------------------------------------------------------------------+

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

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

  ACH Example

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

         tclink.send(params)

X. Postauths, Credits, and Chargebacks

   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.

  Required Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | transid        | The transaction ID (format: nnn-nnnnnnnnnn) of the    |
   |                | referenced transaction.                               |
   +------------------------------------------------------------------------+

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

  Optional Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | amount         | The amount, in cents, to credit or postauth if it is  |
   |                | not the same as the original amount.                  |
   +------------------------------------------------------------------------+

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

  Credit Example

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

         tclink.send(params)

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

XI. TCS Citadel (Billing IDs)

   The 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.

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

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

  Store Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | verify         | When set to "y", a $1.00 preauth will be run on the   |
   |                | card to ensure that it is valid.                      |
   |----------------+-------------------------------------------------------|
   | billingid      | Pass if you wish to update values of an existing      |
   |                | billing ID.                                           |
   +------------------------------------------------------------------------+

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

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

   The unstore action takes a single parameter:

  Unstore Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | billingid      | The six-character alphanumeric billing ID returned by |
   |                | a previous store transaction.                         |
   +------------------------------------------------------------------------+

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

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

  Billing ID Example

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

         result = tclink.send(params)

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

XII. Recurring Billing

   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.

  Recurring Parameters

   +------------------------------------------------------------------------+
   | Parameter Name | Required? |                Description                |
   |----------------+-----------+-------------------------------------------|
   | cycle          |     X     | Repeat cycle in days, weeks, months, or   |
   |                |           | years.                                    |
   |----------------+-----------+-------------------------------------------|
   | amount         |     X     | Amount to bill in cents.                  |
   |----------------+-----------+-------------------------------------------|
   | start          |           | Date to start, or else offset from        |
   |                |           | current date (defaults to now).           |
   |----------------+-----------+-------------------------------------------|
   | payments       |           | Number of payments to make (defaults to   |
   |                |           | infinite).                                |
   +------------------------------------------------------------------------+

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

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

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

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

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

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

  Recurring Billing Example

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

         mode = chooseSubscriptionMode()

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

         tclink.send(params)

XIII. TCS Wallet

   The 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.

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

  Wallet Parameters

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | wallet         | "y" to enable the wallet.                             |
   |----------------+-------------------------------------------------------|
   | walletsize     | Accumulated amount, in cents, before the wallet is    |
   |                | submitted for capture.                                |
   |----------------+-------------------------------------------------------|
   | walletexposure | Length of time to wait before capturing the wallet.   |
   +------------------------------------------------------------------------+

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

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

  Wallet Example

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

         result = tclink.send(params)

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

XIV. Purchase Level II

   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.

   PL2 has three new parmaeters:

  PL2 Input Parameters

   +------------------------------------------------------------------------+
   |  Parameter Name  |                     Description                     |
   |------------------+-----------------------------------------------------|
   | purchaselevel    | Specify as "2".                                     |
   |------------------+-----------------------------------------------------|
   |                  | The purchasing order number from their Visa         |
   | purchaseordernum | 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.                       |
   |------------------+-----------------------------------------------------|
   |                  | The amount of tax, in cents, charged for the order. |
   | tax              | If the order is tax exempt omit this field or set   |
   |                  | it to 0.                                            |
   +------------------------------------------------------------------------+

   A successful PL2 transaction will return one extra response parameter

  PL2 Output Parameter

   +------------------------------------------------------------------------+
   | Parameter Name |                      Description                      |
   |----------------+-------------------------------------------------------|
   | commercialcard | Set to "S" for if it is a purchasing card, "R" if it  |
   |                | is corporate card, and "B" if it is a business card.  |
   +------------------------------------------------------------------------+

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

  Purchase Level II Example

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

         }

         result = tclink.send(params)

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

XIV. Order Detail

   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.

   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.

  ShipTo Parameters

   +------------------------------------------------------------------------+
   | Parameter Name  |                     Description                      |
   |-----------------+------------------------------------------------------|
   | shiptosame      | y or n (defaults to n). If "y", then no other        |
   |                 | shipto_ parameters should be passed.                 |
   |-----------------+------------------------------------------------------|
   | shipto_name     | Name of the product recipient.                       |
   |-----------------+------------------------------------------------------|
   | shipto_address1 | First line of shipping address.                      |
   |-----------------+------------------------------------------------------|
   | shipto_address2 | Second line (if any) of shipping address.            |
   |-----------------+------------------------------------------------------|
   | shipto_city     | City.                                                |
   |-----------------+------------------------------------------------------|
   | shipto_state    | State.                                               |
   |-----------------+------------------------------------------------------|
   | shipto_zip      | Zipcode, five or nine digits (no spaces or dashes).  |
   |-----------------+------------------------------------------------------|
   | shipto_country  | Country, leave blank for US.                         |
   +------------------------------------------------------------------------+

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

  Order Header Parameters

   +------------------------------------------------------------------------+
   |  Parameter Name  |                     Description                     |
   |------------------+-----------------------------------------------------|
   | shippingcode     | Three character code indicating shipping method to  |
   |                  | use.                                                |
   |------------------+-----------------------------------------------------|
   | shippinghandling | The total cost of shipping and handling, in cents.  |
   |------------------+-----------------------------------------------------|
   | numitems         | Total number of distinct items (product codes) in   |
   |                  | the order.                                          |
   +------------------------------------------------------------------------+

   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.

  Order Detail Parameters

   +------------------------------------------------------------------------+
   |  Parameter Name   |                    Description                     |
   |-------------------+----------------------------------------------------|
   | productcodeX      | The alphanumeric product code defined by the       |
   |                   | fulfillment house.                                 |
   |-------------------+----------------------------------------------------|
   | quantityX         | The number of items of this type to be shipped.    |
   |-------------------+----------------------------------------------------|
   | priceX            | The price of all items of this type not including  |
   |                   | sales tax or shipping, in cents.                   |
   |-------------------+----------------------------------------------------|
   | taxX              | Total tax charged for all items of this product    |
   |                   | code.                                              |
   |-------------------+----------------------------------------------------|
   | shippinghandlingX | Total shipping and handling charged for all items  |
   |                   | of this product code.                              |
   +------------------------------------------------------------------------+

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

  Fulfillment Example

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

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

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

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

         tclink.send(params)

XVI. Vault Query API

   The 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.

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

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

  Required Parameters

   +------------------------------------------------------------------------+
   | Parameter Name | Requred? |                Description                 |
   |----------------+----------+--------------------------------------------|
   | custid         |    X     | TrustCommerce customer ID number.          |
   |----------------+----------+--------------------------------------------|
   | password       |    X     | The password for your custID.              |
   |----------------+----------+--------------------------------------------|
   |                |          | Set to "html" for human-readable HTML      |
   | format         |          | output, or "text" (default) for CSV text   |
   |                |          | output.                                    |
   |----------------+----------+--------------------------------------------|
   |                |          | Possible values are: chain, transaction,   |
   |                |          | summary, or billingid, corresponding to    |
   | querytype      |    X     | the equivalent reports on the Vault        |
   |                |          | website. Read the User's Guide for further |
   |                |          | description of each report type.           |
   |----------------+----------+--------------------------------------------|
   | media          |          | Set to "cc" (default) or "ach" for media   |
   |                |          | type.                                      |
   |----------------+----------+--------------------------------------------|
   | begindate      |          | Begin date for query, format: MM-DD-YYYY   |
   |                |          | HH:MM:SS                                   |
   |----------------+----------+--------------------------------------------|
   | enddate        |          | End date for query, format: MM-DD-YYYY     |
   |                |          | HH:MM:SS                                   |
   |----------------+----------+--------------------------------------------|
   | chain          |          | Narrow search to a single chain of         |
   |                |          | transactions.                              |
   |----------------+----------+--------------------------------------------|
   | transid        |          | Narrow search to a single transaction ID.  |
   |----------------+----------+--------------------------------------------|
   | billingid      |          | Narrow search to a single billing ID.      |
   |----------------+----------+--------------------------------------------|
   |                |          | Use 'y' or 'n'. For billing ID search.     |
   | pastdue        |          | Show only recurring billing IDs that have  |
   |                |          | been unable to capture the requested       |
   |                |          | funds.                                     |
   |----------------+----------+--------------------------------------------|
   | action         |          | Narrow search by action (preauth, sale,    |
   |                |          | credit, etc).                              |
   |----------------+----------+--------------------------------------------|
   | status         |          | Narrow search by status (approved,         |
   |                |          | accepted, decline, etc).                   |
   |----------------+----------+--------------------------------------------|
   | name           |          | Narrow search by cardholder name, partial  |
   |                |          | or complete.                               |
   |----------------+----------+--------------------------------------------|
   | cc             |          | Narrow search by credit card number.       |
   |----------------+----------+--------------------------------------------|
   | limit          |          | Do not allow size of result set to exceed  |
   |                |          | this number of records.                    |
   |----------------+----------+--------------------------------------------|
   |                |          | Report result set starting from this       |
   | offset         |          | offset. Use this parameter in conjunction  |
   |                |          | with limit in order to page through a      |
   |                |          | large result set.                          |
   |----------------+----------+--------------------------------------------|
   | showcount      |          | Show the number of records returned on the |
   |                |          | last line of the result set.               |
   +------------------------------------------------------------------------+

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

  Query Example HTML

   TrustCommerce Query Interface  

 TrustCommerce Query Interface 

                   custid 
                    
                   This is your TrustCommerce custid (required) 

                   password 
                    
                   This is your TrustCommerce password (required) 

                   format 
                    text
                                 html
                   Human readable (html) or computer readable (text) results

                   Query type 
                   
                 chain
                 transaction
                 summary
                 billingid
                 
                   Type of query 

                   media 
                    
                   For now this must be cc 

                   begindate MM-DD-YYYY HH:MM:SS 
                    
                   Query begins at this date

                   enddate MM-DD-YYYY HH:MM:SS 
                    
                   Query ends at this date

                   chain 
                    
                   Narrow search to a single chain of transactions 

                   transid 
                    
                   Narrow search to a single transactions 

                   billingid 
                    
                   Narrow search to a single billingid 

                   pastdue 
                   
                 y
                 n
                 
                   Use 'y' or 'n'. For billing ID search.  Show only recurring billing IDs
                      that have been unable to capture the requested funds. 

                   action 
                    
                   Narrow search by action. (example: preauth,postauth) 

                   status 
                    
                   Narrow search by status. (example: approved,accepted) 

                   name 
                    
                   Narrow search by name. 

                   cc 
                    
                   Narrow search by credit card field. 

                   limit 
                    
                   Limit results to this number of fields (not used for summary)

                   offset 
                    
                   Report results at this offset (used with limit to page through results)

                   showcount 
                   
                 yes
                 no
                 
                   Show the number of not-limited rows on the last line of the result

Appendix A - Test Data

   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.

   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.

  Test Cards - Approved

   +------------------------------------------------------------------------+
   |Card Type |  Card Number   | Exp |Address |   City    |State| Zip  |CVV |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |Visa      |4111111111111111|04/04|123 Test|Somewhere  |CA   |90001 |123 |
   |          |                |     |St.     |           |     |      |    |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |Mastercard|5411111111111115|04/04|4000    |Anytown    |AZ   |85001 |777 |
   |          |                |     |Main St.|           |     |      |    |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |American  |                |     |12      |           |     |      |    |
   |Express   |341111111111111 |04/04|Colorado|Elsewhere  |IL   |54321 |4000|
   |          |                |     |Blvd.   |           |     |      |    |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |          |                |     |6789    |           |     |      |    |
   |Discover  |6011111111111117|04/04|Green   |Nowhere    |MA   |12345 |-   |
   |          |                |     |Ave.    |           |     |      |    |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |Diner's   |                |     |7390 Del|           |     |      |    |
   |Club      |36484444444446  |04/04|Mar     |Atown      |NY   |01101 |-   |
   |          |                |     |Blvd.   |           |     |      |    |
   |----------+----------------+-----+--------+-----------+-----+------+----|
   |          |                |     |350     |           |     |      |    |
   |JCB       |213122222222221 |04/04|Madison |Springfield|OH   |400000|-   |
   |          |                |     |Ave.    |           |     |      |    |
   +------------------------------------------------------------------------+

   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.

  Test Cards - Declined

                   +----------------------------------------+
                   |   Card Number    |  Exp  | DeclineType |
                   |------------------+-------+-------------|
                   | 4012345678909    | 04/04 | decline     |
                   |------------------+-------+-------------|
                   | 5555444433332226 | 04/04 | call        |
                   |------------------+-------+-------------|
                   | 4444111144441111 | 04/04 | carderror   |
                   +----------------------------------------+

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

Appendix B - Troubleshooting

   Details about installing and troubleshooting TCLink specific to your
   development platform can be found in the documentation included with the
   TCLink archive.

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

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

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

Appendix C - Connecting via HTTPS POST

   This 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.

   This is the URL:

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

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

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

Appendix D - Currency Table

  Currency Codes

   +-----------------------------------------------------------------------+
   | Code |       Currency Type       | Code |        Currency Type        |
   |------+---------------------------+------+-----------------------------|
   | usd  | US Dollars                | jpy  | Japan Yen                   |
   |------+---------------------------+------+-----------------------------|
   | eur  | Euro                      | jod  | Jordan Dinar                |
   |------+---------------------------+------+-----------------------------|
   | cad  | Canadian Dollars          | krw  | Korea (South) Won           |
   |------+---------------------------+------+-----------------------------|
   | gbp  | UK Pounds                 | lbp  | Lebanon Pounds              |
   |------+---------------------------+------+-----------------------------|
   | dem  | German Deutschemarks      | luf  | Luxembourg Francs           |
   |------+---------------------------+------+-----------------------------|
   | frf  | French Francs             | myr  | Malaysia Ringgit            |
   |------+---------------------------+------+-----------------------------|
   | jpy  | Japanese Yen              | mxp  | Mexico Pesos                |
   |------+---------------------------+------+-----------------------------|
   | nlg  | Dutch Guilders            | nlg  | Netherlands Guilders        |
   |------+---------------------------+------+-----------------------------|
   | itl  | Italian Lira              | nzd  | New Zealand Dollars         |
   |------+---------------------------+------+-----------------------------|
   | chf  | Switzerland Francs        | nok  | Norway Kroner               |
   |------+---------------------------+------+-----------------------------|
   | dzd  | Algeria Dinars            | pkr  | Pakistan Rupees             |
   |------+---------------------------+------+-----------------------------|
   | arp  | Argentina Pesos           | xpd  | Palladium Ounces            |
   |------+---------------------------+------+-----------------------------|
   | aud  | Australia Dollars         | php  | Philippines Pesos           |
   |------+---------------------------+------+-----------------------------|
   | ats  | Austria Schillings        | xpt  | Platinum Ounces             |
   |------+---------------------------+------+-----------------------------|
   | bsd  | Bahamas Dollars           | plz  | Poland Zloty                |
   |------+---------------------------+------+-----------------------------|
   | bbd  | Barbados Dollars          | pte  | Portugal Escudo             |
   |------+---------------------------+------+-----------------------------|
   | bef  | Belgium Francs            | rol  | Romania Leu                 |
   |------+---------------------------+------+-----------------------------|
   | bmd  | Bermuda Dollars           | rur  | Russia Rubles               |
   |------+---------------------------+------+-----------------------------|
   | brr  | Brazil Real               | sar  | Saudi Arabia Riyal          |
   |------+---------------------------+------+-----------------------------|
   | bgl  | Bulgaria Lev              | xag  | Silver Ounces               |
   |------+---------------------------+------+-----------------------------|
   | cad  | Canada Dollars            | sgd  | Singapore Dollars           |
   |------+---------------------------+------+-----------------------------|
   | clp  | Chile Pesos               | skk  | Slovakia Koruna             |
   |------+---------------------------+------+-----------------------------|
   | cny  | China Yuan Renmimbi       | zar  | South Africa Rand           |
   |------+---------------------------+------+-----------------------------|
   | cyp  | Cyprus Pounds             | krw  | South Korea Won             |
   |------+---------------------------+------+-----------------------------|
   | csk  | Czech Republic Koruna     | esp  | Spain Pesetas               |
   |------+---------------------------+------+-----------------------------|
   | dkk  | Denmark Kroner            | xdr  | Special Drawing Right (IMF) |
   |------+---------------------------+------+-----------------------------|
   | nlg  | Dutch Guilders            | sdd  | Sudan Dinar                 |
   |------+---------------------------+------+-----------------------------|
   | xcd  | Eastern Caribbean Dollars | sek  | Sweden Krona                |
   |------+---------------------------+------+-----------------------------|
   | egp  | Egypt Pounds              | chf  | Switzerland Francs          |
   |------+---------------------------+------+-----------------------------|
   | eur  | Euro                      | twd  | Taiwan Dollars              |
   |------+---------------------------+------+-----------------------------|
   | fjd  | Fiji Dollars              | thb  | Thailand Baht               |
   |------+---------------------------+------+-----------------------------|
   | fim  | Finland Markka            | ttd  | Trinidad and Tobago Dollars |
   |------+---------------------------+------+-----------------------------|
   | frf  | France Francs             | trl  | Turkey Lira                 |
   |------+---------------------------+------+-----------------------------|
   | dem  | Germany Deutsche Marks    | gbp  | United Kingdom Pounds       |
   |------+---------------------------+------+-----------------------------|
   | xau  | Gold Ounces               | usd  | United States Dollars       |
   |------+---------------------------+------+-----------------------------|
   | grd  | Greece Drachmas           | veb  | Venezuela Bolivar           |
   |------+---------------------------+------+-----------------------------|
   | hkd  | Hong Kong Dollars         | zmk  | Zambia Kwacha               |
   |------+---------------------------+------+-----------------------------|
   | huf  | Hungary Forint            | eur  | Euro                        |
   |------+---------------------------+------+-----------------------------|
   | isk  | Iceland Krona             | xcd  | Eastern Caribbean Dollars   |
   |------+---------------------------+------+-----------------------------|
   | inr  | India Rupees              | xdr  | Special Drawing Right (IMF) |
   |------+---------------------------+------+-----------------------------|
   | idr  | Indonesia Rupiah          | xag  | Silver Ounces               |
   |------+---------------------------+------+-----------------------------|
   | iep  | Ireland Punt              | xau  | Gold Ounces                 |
   |------+---------------------------+------+-----------------------------|
   | ils  | Israel New Shekels        | xpd  | Palladium Ounces            |
   |------+---------------------------+------+-----------------------------|
   | itl  | Italy Lira                | xpt  | Platinum Ounces             |
   |------+---------------------------+------+-----------------------------|
   | jmd  | Jamaica Dollars           |      |                             |
   +-----------------------------------------------------------------------+

Appendix E - Input Field List

  Input Fields

        +--------------------------------------------------------------+
        |       Name        |  Type  | Minimum Length | Maximum Length |
        |-------------------+--------+----------------+----------------|
        | custid            | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | password          | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | action            | string | 1              | 10             |
        |-------------------+--------+----------------+----------------|
        | media             | string | 1              | 10             |
        |-------------------+--------+----------------+----------------|
        | currency          | string | 3              | 3              |
        |-------------------+--------+----------------+----------------|
        | amount            | number | 3              | 8              |
        |-------------------+--------+----------------+----------------|
        | cc                | number | 13             | 16             |
        |-------------------+--------+----------------+----------------|
        | exp               | number | 4              | 4              |
        |-------------------+--------+----------------+----------------|
        | cvv               | number | 3              | 4              |
        |-------------------+--------+----------------+----------------|
        | routing           | number | 9              | 9              |
        |-------------------+--------+----------------+----------------|
        | account           | number | 3              | 17             |
        |-------------------+--------+----------------+----------------|
        | billingid         | string | 6              | 6              |
        |-------------------+--------+----------------+----------------|
        | verify            | string | 1              | 1              |
        |-------------------+--------+----------------+----------------|
        | transid           | string | 14             | 14             |
        |-------------------+--------+----------------+----------------|
        | avs               | string | 1              | 10             |
        |-------------------+--------+----------------+----------------|
        | name              | string | 1              | 60             |
        |-------------------+--------+----------------+----------------|
        | address1          | string | 1              | 80             |
        |-------------------+--------+----------------+----------------|
        | address2          | string | 1              | 80             |
        |-------------------+--------+----------------+----------------|
        | zip               | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | city              | string | 1              | 40             |
        |-------------------+--------+----------------+----------------|
        | state             | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | country           | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | phone             | string | 1              | 30             |
        |-------------------+--------+----------------+----------------|
        | email             | string | 1              | 50             |
        |-------------------+--------+----------------+----------------|
        | track1            | string | 1              | 79             |
        |-------------------+--------+----------------+----------------|
        | track2            | string | 1              | 40             |
        |-------------------+--------+----------------+----------------|
        | ticket            | string | 1              | 30             |
        |-------------------+--------+----------------+----------------|
        | operator          | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shiptosame        | string | 1              | 1              |
        |-------------------+--------+----------------+----------------|
        | shipto_name       | string | 1              | 60             |
        |-------------------+--------+----------------+----------------|
        | shipto_address1   | string | 1              | 40             |
        |-------------------+--------+----------------+----------------|
        | shipto_address2   | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shipto_city       | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shipto_state      | string | 2              | 2              |
        |-------------------+--------+----------------+----------------|
        | shipto_zip        | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shipto_country    | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | numitems          | number | 1              | 3              |
        |-------------------+--------+----------------+----------------|
        | price             | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shippingcode      | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | shippinghandling  | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | productcode#      | string | 1              | 20             |
        |-------------------+--------+----------------+----------------|
        | quantity#         | number | 1              | 3              |
        |-------------------+--------+----------------+----------------|
        | price#            | number | 1              | 6              |
        |-------------------+--------+----------------+----------------|
        | tax#              | number | 1              | 6              |
        |-------------------+--------+----------------+----------------|
        | shippinghandling# | number | 1              | 6              |
        |-------------------+--------+----------------+----------------|
        | wallet            | string | 1              | 1              |
        |-------------------+--------+----------------+----------------|
        | walletsize        | string | 3              | 8              |
        |-------------------+--------+----------------+----------------|
        | walletexposure    | string | 1              | 3              |
        |-------------------+--------+----------------+----------------|
        | start             | string | 2              | 10             |
        |-------------------+--------+----------------+----------------|
        | cycle             | string | 2              | 4              |
        |-------------------+--------+----------------+----------------|
        | payments          | number | 1              | 4              |
        |-------------------+--------+----------------+----------------|
        | demo              | string | 1              | 1              |
        |-------------------+--------+----------------+----------------|
        | offlineauthcode   | string | 6              | 6              |
        +--------------------------------------------------------------+

     ----------------------------------------------------------------------

                        Copyright (c) 2003 TrustCommerce
