CFX_ecommerce2 Tag Documentation
The CFX_ecommerce2 tag requires six or seven parameters and returns three variables.
Sample CFX_ecommerce2 call:
| <CFX_ECOMMERCE2 | |
| TERMID="#TerminalID#" | |
| TYPE="#TransactionType" | |
| CARD="#CreditCardNumber#" | |
| EXP="#ExpiryDate#" | |
| AMT="#Amount#" | |
| REF=#ReferenceNumber# | |
| RESEND="Y" | |
| USERNAME="username" | |
| PASSWORD="vwspassword"> | |
Input Parameters:
| Variable | Required | Description |
| TERMID | required | Terminal ID supplied by Magma (alphanumeric, case sensitive) |
| TYPE | required | Transaction type ("S" for sale, "V" for void, case sensitive) |
| CARD | required | Credit Card # ( numeric digits only, no spaces ) |
| EXP | required | Expiry Date ( 4 numeric digits only - MMYY ) |
| AMT | required | Amount ( no spaces, no commas, no period ie. $1.00 - should be 100 ) |
| REF | required | Reference number ( a unique number generated by your system; must be at least 7 digits and no more than 60 digits in length ) |
| RESEND | optional | Only include if you are "re-sending" a transaction - see details below |
| USERNAME | required | Your VWS Userid |
| PASSWORD | required | Your VWS Password |
Variables Returned
| VARIABLE | DESCRIPTION |
| CODE | This is a 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. "Decline" conditions will usually have a code in the 1xxx range. All transaction responses contain a CODE field. |
| AUTH | The authorization number. The authorization number returned for a "Sale". If the transaction was a "Void", this variable will be empty. Note that this authorization number is included in the TEXT variable, but is provided in a separate variable for your convenience. |
| TEXT | alphanumeric string (max 30 chars) if CODE="0000" (successful), the string will contain the authorization number and the amount separated by spaces example: (ignore the quotes) "1234 $1.00" if CODE is not equal to "0000" (failed), the string will contain the reason why the transaction failed For example: |
| <CFSET ERROR = 0> | |
| <cfset ReceiptID = UNIQUE NUMBER> | |
| <cfset totalInvoice = #subtotaltax# + #subtotal#> | |
|
<cfset TransAmount = #Replace( #NumberFormat( totalInvoice, "__________.__" )#, ".", "")#> | |
| <cfset ccParsed = #REReplace( #CCNUMBER#, "[ -]", "", "ALL" )#> | |
| <cfset expDateParsed = #Replace( #CCEXP#, "/", "" )#> | |
| <CFX_ECOMMERCE2 | |
| TERMID="#TerminalID#" | |
| TYPE="S" | |
| CARD="#ccParsed#" | |
| EXP="#expDateParsed#" | |
| AMT="#Trim(TransAmount)#" | |
| REF="#ReceiptID#" | |
| USERNAME="#username#" | |
| PASSWORD="#vwspassword#"> | |
| <CFIF #CODE# = "0000"> | |
| <CFOUTPUT> | |
| Your credit card has been successfully processed. | |
| Your authorization number is #AUTH#. | |
| Thank you for your purchase. | |
| </CFOUTPUT> | |
| <CFELSE> | |
| <CFOUTPUT>Error: #TEXT#</CFOUTPUT> | |
| </CFIF> | |
Transaction Security
The CFX_ecommerce2 tag uses the industry-standard SSL encryption protocol for communicating with the processing server located elsewhere on the Internet.
Transaction Timeouts and Advanced Error Handling
The CFX_ecommerce2 tag runs on Magma's hosting server and communicates with another server located elsewhere on the Internet to actually process the credit card. If the tag has any difficulty in connecting with the destination server, it will return an appropriate error message. These connection-oriented error messages are in the 5000 series of error messages .
There is one such error message which you should be aware of. Error message #5008 is "PLEASE RESEND" This particular error message will only ever occur if a connection problem occurs right at the exact moment after the transaction request has been sent from the tag running on Magma's server to the destination server, and the destination server has not yet returned the response. The likelihood of this event occuring is almost negligable, but it could theoretically happen. As such, you should consider adding some code to deal with it.
To handle this situation properly, you should re-send the original request to the tag. You would need to resend the original transaction (all values must be exactly the same) and include the RESEND="Y" variable. The destination server will lookup the original transaction. If the original transaction was processed correctly within the last 24 hours, the result codes from the original transaction will be returned. If the original transaction cannot be found, the "resent" transaction will be processed as a new transaction. You may resubmit the transaction as many times as necessary in order to receive your response.
Here is some sample code which will check for this error condition and try to deal with it.
| <CFX_ECOMMERCE2 | |
| TERMID="#TerminalID#" | |
| TYPE="#TransactionType" | |
| CARD="#CreditCardNumber#" | |
| EXP="#ExpiryDate#" | |
| AMT="#Amount#" | |
| REF="#ReferenceNumber#" | |
| USERNAME="#username#" | |
| PASSWORD="#vwspassword#"> | |
| <cfif #code# EQ "5008"> | |
| <cfset counter = "1"> | |
| <cfloop condition="code GT 1999 and counter LT 10"> | |
| <CFX_ECOMMERCE2 | |
| TERMID="#TerminalID#" | |
| TYPE="#TransactionType" | |
| CARD="#CreditCardNumber#" | |
| EXP="#ExpiryDate#" | |
| AMT="#Amount#" | |
| REF="#ReferenceNumber#" | |
| RESEND="Y" | |
| USERNAME="#username#" | |
| PASSWORD="#vwspassword#"> | |
| <cfset counter = counter + 1> | |
| </cfloop> | |
| <cfif #code# GT "1999"> | |
|
Transaction problem. Please call our technical support department for assistance. Your card may or may not have been processed. | |
| <cfelseif #code# EQ "0000"> | |
| Your credit card has been successfully processed. | |
| <cfelse> | |
| Error: #text# | |
| </cfif> | |
| </cfif> | |
The logic behind the above code is as follows.
- If error code #5008 is returned initially, we're not sure if the transaction completed successfully
- Retry up to ten times (with RESEND="Y" if we keep getting a connection-related error.
- If we end up with an error > 1999, a connection problem has occured. We still don't know if the original transaction completed successfully. Ask the customer to call your support department. It is quite likely that if the original transaction failed part-way through, that some network error has occured which might last for more than a few minutes. It is likely that the subsequent error message will be something like "5004" (Timeout).
- If after doing the "RESEND" we get back an OK ("0000") or a decline related error (1000 series), output the relevant message. These are the "expected" return codes.
