Beanstream Internet Payment Processing Process Transaction API Document Version 1.2.12 Last Updated December 10, 2003 For further information please contact Beanstream customer support at (250) 472-2326 or [email protected]. Beanstream Internet Commerce Process Transaction API Table of Contents 1. DOCUMENT REVISION HISTORY .................................................................................................3 2. OVERVIEW ..........................................................................................................................................4 2.1. ACCESS REQUIREMENTS...................................................................................................................4 2.2. SECURITY .........................................................................................................................................4 3. INTEGRATION PROCEDURE ..........................................................................................................5 3.1. OVERVIEW .......................................................................................................................................5 3.2. SUBMITTING THE TRANSACTION ......................................................................................................5 3.2.1. Duplicate Transaction Checking .............................................................................................5 3.3. ERROR HANDLING............................................................................................................................6 3.3.1. System Generated Errors.........................................................................................................6 3.3.2. User Generated Errors............................................................................................................6 3.4. TRANSACTION COMPLETION ............................................................................................................7 3.4.1. Response Notification URL......................................................................................................7 3.5. THE SERVER-TO-SERVER PROCESSING METHOD..............................................................................8 4. DATA VARIABLES..............................................................................................................................9 4.1. INPUT VARIABLES ............................................................................................................................9 4.1.1. General Information ................................................................................................................9 4.1.2. Credit Information.................................................................................................................11 4.1.3. Billing Information ................................................................................................................11 4.1.4. Shipping Information.............................................................................................................12 4.1.5. Product Information ..............................................................................................................12 4.1.6. Pricing Information ...............................................................................................................12 4.1.7. Custom Information...............................................................................................................13 4.1.8. Transaction Types..................................................................................................................13 4.2. RESPONSE VARIABLES ...................................................................................................................14 4.2.1. Response Parameters.............................................................................................................14 5. VARIABLE CODES ...........................................................................................................................16 5.1. MESSAGEID RESPONSE MESSAGES .................................................................................................16 5.1.1. Processor Legend ..................................................................................................................22 5.2. TRANSACTION TYPES .....................................................................................................................22 5.3. COUNTRY CODES ...........................................................................................................................22 5.4. PROVINCE/STATE CODES ...............................................................................................................24 5.5. AVS RESPONSE CODES ..................................................................................................................25 6. RECURRING TRANSACTIONS......................................................................................................26 6.1. RECURRING DATA VARIABLES.......................................................................................................26 6.1.1. Recurring Billing ...................................................................................................................26 6.1.2. Billing Periods.......................................................................................................................27 6.2. BILLING FREQUENCY .....................................................................................................................27 6.3. BILLING DATES ..............................................................................................................................27 7. TEST CARD NUMBERS ...................................................................................................................29 8. URL ENCODING CHART ................................................................................................................30 9. EXAMPLES.........................................................................................................................................31 Page 2 of 32 Beanstream Internet Commerce Process Transaction API 1. Document Revision History Date Revision Description Author Revision Number March 13, 2002 Added detail on processing adjustment transaction types in Shawn Gerty 1.1 addition to purchase transaction types. Added approvedPage/declinedPage specifications to the list Aston Lau of Input Variables. Oct 22, 2002 Added instructions on CVD Aston Lau 1.2 Oct 23, 2002 Updated instructions on using ref fields Aston Lau 1.2.1 Feb 18, 2003 Added instructions on recurring transactions. Shawn Gerty 1.2.2 Added details on new merchant definable approvedPage and declinedPage URL parameters. Added details on Server to Server Transaction Response Notification. Apr 16, 2003 Added cavEnabled parameter to list of input variables. Aston Lau 1.2.3 Jun 27, 2003 Added AVS response codes to section 4.2.1 Shawn Gerty 1.2.5 Added AVS response code message table to section 5.5 Aug 6, 2003 Updated description of response parameter authCode. Shawn Gerty 1.2.6 Changed trnOrderNumer from numeric only to alphanumeric. Aug 20, 2003 Added new bank and Beanstream response messages. Michael J 1.2.7 Foucher Aug 27, 2003 Added Verified By Visa information. Aston Lau 1.2.8 Sep 15, 2003 Extended length of card owner and address variables. Aston Lau 1.2.9 Fixed formatting of section 5 Oct 27, 2003 Added test credit card numbers PEC 1.2.10 Nov 6, 2003 Added duplicate checking information Aston Lau 1.2.11 Removed reference to Server-to-Server Response Notification URL (Response Notification URL is not a feature of STS) Added information on Server-to-Server Dec 10, 2003 Fixed errorPage variable in example Aston Lau 1.2.12 Page 3 of 32 Beanstream Internet Commerce Process Transaction API 2. Overview The transaction processing API method allows you to link any e-commerce order processing system directly to the Beanstream transaction server. This may be as simple as a one page order form, or as complex as a full shopping cart. Whereas all other processing methods provide you with a web interface that may be built into your site, the transaction processing API method allows you build your own web interface and offers the highest level of flexibility to your order process. With this interface you may process not only purchase transaction types (purchase, pre-auth), but also adjustment transaction types (return, void purchase, void return, pre-auth completion). 2.1. Access Requirements In order to access the Process Transaction API, you must have a merchant account with Beanstream and be able to communicate with our web server via 40-bit or 128-bit SSL. 2.2. Security The Process Transaction API is secured via 128-bit SSL encryption to prevent third parties from seeing the details of your customer’s transaction request during transit to the Beanstream server. Additionally, there are optional security measures that you can enable, including: 9 validating that the referring web site (i.e. the web site that the customer comes from) is yours 9 using PGP signing to verify that the transaction has been authorized by you 9 using PGP encryption to further encrypt the details of the transaction 9 requiring username/password validation 9 validating orders against inventory PGP is a key security feature available for use with Process Transaction. For further information on this and these other security features, please see the “Processing