tcdevguide.txt

来自「视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.」· 文本 代码 · 共 1,209 行 · 第 1/5 页

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

                     TrustCommerce Developer's Guide 2.2.3

   http://www.trustcommerce.com
   [e-mail]

   July 9, 2002

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

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. Billing IDs                        
   XII. Recurring Billing                 
   XIII. TCS Wallet                       
   XIV. Automated Fulfillment             
   XV. Vault Query API                    
   Appendix A - Test Data                 
   Appendix B - Troubleshooting           
   Appendix C - Connecting via HTTPS POST 
   Appendix D - Currency Table            

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

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