Everything E-Commerce for the small business

SETTING UP AN ECHO FINANCIAL TRANSACTION GATEWAY IN COLDFUSION

Index of Articles CLIENT vs. SERVER in E-COMMERCE STOREFRONTS ARRAYS AS ON-LINE STORE DATABASES TAKING THE MYSTERY OUT OF TAKING CREDIT CARDS TECHNICAL DETAILS OF CREDIT CARD TRANSACTIONS AND THE NETWORK PROCESS SELECTING STOREFRONT SOFTWARE COLDFUSION AND THE ECHO COMMERCE GATEWAY THE NUTS AND BOLTS OF INFORMATION SECURITY SIDEBAR INFO [GATEWAY] The financial gateway is a service provider's software interface that lets internet protocols communicate with financial networks. One job of the application service provider is to interface an on-line Internet storefront with a financial gateway. [CC TRANSACTION] A credit card transaction takes place in a minimum of three steps: authorization, marking, and settlement. Some gateway providers automatically execute some of the steps so that the merchant may not be aware of the process. [AUTHORIZATION] means that the card number and expiration date have been validated, funds in the amount requested are available, and that a hold on the amount has been placed against the card. The hold will remain in effect for anywhere from 10 to 30 days depending on the issuing financial institution. Marking is the step of identifying which authorizations are ready for settlement and placing them in a batch to be settled. Settlement is the process of submitting the batch (This can be a batch of one.) for capture. Capture means that the authorized funds have been transferred from the buyer to the merchant and will arrive in the merchant's account usually within 72 hours. [SETTLING] (capture) a transaction prior to shipment is frowned upon. An application providing credit card processing will ordinarily allow the merchant the option of settling transactions subsequent to order placement. This delays capture for temporarily out of stock items or other impediments to shipment. It also lets the merchant cancel or void a transaction by taking no action, without having to issue a credit. See Code below

The ECHO gateway, a robust solution using ColdFusion. Article by Mel Davey INTRODUCTION ImagineNation is an application service provider of back-end utilities in support of the on-line store. Invariably, a financial gateway for taking credit card payment is a part of any utility package. The company has configured many of these gateways. All of them differ in syntax and protocol and each of them has its advantages and disadvantages for the developer and merchant. Typically a merchant already has a merchant account using a particular gateway and wants the developer to create the interface to their storefront. This can be a daunting task for the developer since not all gateways are easily matched to the back-end needs of the merchant. A more manageable approach would be to let the developer select the gateway based on the services required and let the merchant obtain a merchant account that supports that gateway. OVERVIEW The requirements for the gateway interface are generally more stringent for an application service provider (ASP) as compared to a single store user. The ASP should integrate order and payment information such that all transaction results and subsequent processing requirements are available to the merchant from one source, an on-line browser based console. Some conditions the ASP must meet are: 1) Make it easy for the merchant to configure their gateway 2) Interlock payment results with order information 3) Create a virtual terminal using the gateway API so the merchant can execute subsequent processing of credit card transactions as a part of the order transaction from a control console 4) Make the credit card transaction transparent to the customer and free from any generic error pages To these ends, one of the gateways that ImagineNation favors is ECHO. Not only does ECHO offer an excellent value for the merchant, but their COM object and easily implemented ColdFusion interface make the coding job relatively straight forward. Setup of the merchant's gateway is provided through a HTML form page that allows the merchant to plug in their particular gateway parameters and select modes of operation: test vs live, authorize only vs auto settle, etc. This information is stored in a merchant's profile record. When a credit card payment request is made to the application, the merchant's gateway interface is configured on the fly with these parameters. Each order and its financial transaction information is kept in a single record of a database table. The process usually involves entering the initial order information and then updating the record with the customers credit card information. Credit card numbers are encrypted when entered into the record. Following real time processing, the record is again updated with the transaction results. Further updates of the order record are provided in an interlocked manner when the merchant uses the virtual terminal. For instance, an authorized charge to a credit card may not be available for settlement until the merchant enters a shipping date. The ability to settle an authorization will not be available if a settlement has already taken place, either automatically or by a prior action of the merchant. A full or partial return to a card account will not be available until settlement; and, multiple partial returns against the same order are accounted for so that total returned amounts will never exceed the original order settlement amount. Settling a transaction prior to shipment is frowned upon. An application providing credit card processing will ordinarily allow the merchant the option of settling transactions subsequent to order placement. This delays capture for temporarily out of stock items or other impediments to shipment. It also lets the merchant cancel or void a transaction by taking no action, without having to issue a credit. Finally, occasional gateway errors and declined credit cards that a single storefront merchant may be able to overlook, cannot be ignored when creating an application that is serving many storefronts with an assortment of merchant preferences. It must be assumed that at times there will be communication failures between the application server and the gateway server and between the gateway server and the financial network. These errors must be trapped so that the customer is not left hanging, waiting for results or presented with a generic "try latter" page. This would quickly lose a customer. One problem with a communication failure is that the application may not receive back, in real time, information on whether or not the credit card was authorized even though the submit process went OK. It is not good practice to decline the customer based on a lack of return information. To this end ImagineNation in creating an application builds in a tentative approval message to present to the customer and sends a "subject to confirmation", e-mail order confirmation. The order detail page of the merchant's on-line console will reflect this uncertain result in the transaction section and enable the merchant, through the virtual terminal, to retry the transaction using the previously submitted credit card information. The customer does not have to take any further action. Results of the retry are automatically posted to the order record and e-mailed to the customer. In the event of another communication failure, no action is taken and the merchant can try again latter. It must also be assumed that valid customers will at times use a credit card that gets declined for a variety of possible reasons. Provision must be made to keep the order alive while giving the customer a chance to try another card. A technique for doing this is explained with Code Example 2. APPLICATION   Code Example 1 illustrates coding for the financial gateway portion of a back-end application using ColdFusion and the ECHO gateway. ColdFusion makes it relatively easy to code a complex operation and the ECHO gateway provides the robust interface capability. ECHO also provides a custom COM object for use with ColdFusion which greatly simplifies the programmer's job, allowing them to concentrate on higher level operations. Code Example 2 illustrates a method of parsing echotype3 return results. The ECHO COM object is invoked and then configured using cfscript. The "//" is used to comment out certain operations so that the tag as shown is for authorizing a credit card charge. Other operations available using the ECHO gateway with this tag are credit card settlements, returns, voids, and credits, check account authorizations, and automated currency transfers. This particular example is dynamically configured using page and session parameters. Your own application will no doubt use a different configuration technique. SUMMARY When selecting a gateway, cost will always be a factor for the merchant; however, if you're writting the code and need to provide a robust set of back-end capabilities, the flexibility and completeness of the gateway interface and response is tantamount. Considering the cost of development, the merchant's best approach will be to let the developer select the gateway. Different gateways will provide varying degrees of back-end record keeping, but these services often do not provide the specific functions that the developer requires. Additionally, order records and payment transaction records will end up being kept in two separate locations, making it nearly impossible to integrate the two record sets into one easily used control console. The developer of a viable credit card processing solution should look for a gateway with ease of interface, robust responses, and a good API. REFERENCES ECHO Inc ImagineNation Inc

CODE EXAMPLE 1 The ECHO Object This particular example is dynamically configured for a credit card charge authorization using page and session parameters. Your own application will no doubt use a different configuration technique. The "result = Echo.Submit;" line is what initiates the transaction with theECHO gateway. <CFOBJECT ACTION=Create TYPE=COM CLASS=EchoObj.Echo NAME=Echo> <cfscript> //********** ECHO VALUES ************* Echo.EchoServer = session.TRNSURL; //"https://wwws.echo-inc.com/scripts/INR200.EXE"; Echo.counter = count; //RandRange(1, 10000); Echo.order_type = 'S'; //F Echo.debug = 'F'; //T or C for certify Echo.transaction_type = trns; //merchant preference, AV=auth only, EV=auth and settle //********** MERCHANT VALUES FROM MERCHANT PROFILE********* Echo.merchant_echo_id = session.TRNSID; Echo.merchant_pin = session.TRNSKEY; Echo.merchant_email = session.auth.email; Echo.merchant_trace_nbr = oid; //an order id that is reflected back for application tracking //********** ISP VALUES FOR TYPE F "order_type" ********** Echo.isp_echo_id = ''; Echo.isp_pin = ''; //********** CUSTOMER VALUES ********* Echo.grand_total = session.ustotal; Echo.billing_name = session.customer; Echo.billing_address1 = ""; Echo.billing_address2 = session.ccaddress; Echo.billing_zip = session.cczip; Echo.billing_email = session.ccemail; Echo.billing_phone = session.cctelephone; Echo.cc_number = session.ccnumber; Echo.ccexp_year = ccyear; Echo.ccexp_month = ccmonth; Echo.billing_ip_address = cgi.REMOTE_ADDR; //********** CREDIT RETURNS **************** //Echo.original_amount = ''; //amount settled (ES,EV,DS) against original order //Echo.grand_total = ''; //amount for this transaction //Echo.order_number = ''; //the original echo "order_number" from either ES, EV or DS transaction // the below fields are optional if "order_number" is supplied //Echo.original_reference = ''; //the echo "auth_code" //Echo.original_trandate_mm = ''; //Echo.original_trandate_dd = ''; //Echo.original_trandate_yyyy = ''; //********** SETTLEMENT (capture) ********** //Echo.authorization = ''; //the echo "auth_code" returned from original authorization //Echo.grand_total = ''; amount authorized on original order //Echo.order_number = ''; //the original echo order number from the authorization //********** COMMERCIAL TRANSACTIONS ******* //Echo.product_description = session.ORDERLIST; //Echo.purchase_order_number = session.ponumber; //Echo.sales_tax = session.ustax; //********** SUBMIT TO PROCESS ******************** result = Echo.Submit; </cfscript>

CODE EXAMPLE 2 Parsing the echotype3 return Transaction results are returned to the parameter "echo" in three different formats. The "echotype3" format is an ordered list of XML like tags that provides the best overall return information for the purpose of transposing into human readable form and customer friendly responses. It is used exclusively with ImagineNation applications of the ECHO gateway. The ECHO type3 response is parsed and, for ease of access, converted to a query structure called "crdck". In ImagineNation applications, so that syntax down-stream remains the same for different gateways, an added step is taken to replace the ECHO names with the application generic names, "islandnames". The cfbreak call is simply a precaution to prevent an endless loop. <CFIF IsDefined('result')> <!--- create array of names and then loop to populate a query structure called "crdck". Map Echo names to Island names for standardization. ---> <CFSET echostring = echo.echotype3> <CFSET echonames = "status,avs_result,auth_code,tran_amount,decline_code,tran_date,order_number, echo_reference,merchant_name,merchant_trace_nbr,version,term_code"> <CFSET echonamearray = ListToArray(echonames)> <CFSET islandnames = "Status,AVSCode,AuthNumber,TrnsAmt,ActionCode,TrnsDate,MerchantTransaction, ReferenceCode,MerchName,OrderID,SWVersion,ErrorMessage"> <CFSET islandnamearray = ListToArray(islandnames)> <CFSET crdck = QueryNew(islandnames)> <CFSET temp = QueryAddRow(crdck)> <CFLOOP INDEX="k" FROM="1" TO="#ArrayLen(echonamearray)#"> <CFSET sz = Len(echonamearray[k])> <CFSET m = FindNoCase(echonamearray[k], echostring, 1)> <CFIF m is 0> <CFSET temp = QuerySetCell(crdck, islandnamearray[k], "x")> <CFELSE> <CFSET n = Find('</', echostring, m+sz)> <CFSET avalue = Mid(echostring, m+sz+1, n-m-sz-1)> <CFSET temp = QuerySetCell(crdck, islandnamearray[k], avalue)> </CFIF> <CFIF k gt 20><CFBREAK></CFIF> </CFLOOP> </CFIF> To get the value of a return parameter, scope it to the query "crdck". For instance, for address verification, access to the value is crdck.AVScode. Each of the return values is entered into the order logs as part of the record for the particular order and some of the values are used to determine subsequent actions. For instance, ECHO provides an extensive set of return action codes, which when combined with the status code make it easy to advise the customer and the merchant about the transaction. A status "D" for declined (crdck.status) combined with an action code (crdck.ActionCode) value of 51 indicates that a card was declined for lack of adequate credit. These robust returns allow the application to provide friendly responses to the customer. For instance, if a code 51 is received, the application presents the customer with a "this card was declined for a credit problem, would you like to try another card?" page which has a back button that will return the customer to the credit card form while preserving the order session information. To prevent misuse the back button is made available for just two retrys.