SurfShop™ is designed to utilize several common Payment Processors by default. Click the links below for instructions on these “pre-configured” processors.
Even if your processor is not listed, SurfShop was designed to plug right into virtually all payment processor gateways on the market today. Instead of customizing the script for every conceivable combination of processor settings, we have distilled all payment gateways down to their primary components.
Every HTML form-based payment gateway expects to receive a specific data set. We do not try to customize the program to this; instead SurfShop™ lets you insert code that TRANSLATES the values that it uses into the payment gateway's system.
Payment gateways return a field containing the result of the transaction: whether it was declined or approved. The gateway may also return other information, such as an Authorization number, address verification results, and server messages. These can all be set with the autoconfig.cgi installation script and with the “Global Settings” option from your WebStore Manager. SurfShop™ uses special fields to record the results of the transaction and can accomodate just about any processing scheme out there.
You can usually generate your own payment code by following the following steps:
You will get some kind of documentation when you sign up with a payment processor. In this documentation are instructions for linking to the gateway from your website. You need to extract the following information from this document:
What is the URL to initiate the gateway?
It will always be some kind of secure address, usually calling some sort of cgi program.
What variable fields must be passed to the gateway and HOW ARE THEY NAMED?
Examples: Name, credit card number, address, city, state, zip, etc. These will vary depending on the type of transaction, i.e., check authorizations use a different set of fields than credit card authorizations.
What “constants” must be passed to the gateway and HOW ARE THEY NAMED?
Ex: Merchant Number, payment mode, etc.
What values will the processor pass back to SurfShop™?
Specifically you are looking for the following:
name of the field which contains the result of the transaction. It is often named “status,” “response,” “Auth,” “APPROVED,” or another name.
value when the transaction is approved. This might be a word or a number. Often it is “Approved,” “Y,” or “1”
value when the transaction is declined. This might be a word or a number. Often it is “Declined,” “N,” or “0”
name of the field which contains any message as to why a transaction was declined. This is optional and is not present on all processors. Often it contains the phrase, “reject_description” or “response_reason.”
name of the field which contains the AVS (address verification system) result code. This is optional and is not present on all processors. Often it contains the phrase, “avs_code,” “AVS_MSG” or just “AVS”
name of the field which contains a transaction approval code. This is optional and is not present on all processors. Often it contains the phrase, “authcode,” “authno” or “AUTHID”
name of field containing the customer's unique identifier. In some cases, the processor cannot use any of your fields, specifically the “user_uid” field, which identifies the customer to SurfShop™. If this is the case, the program will need to use the processor's field for this purpose. Often it is called “RefNo” or “Reference_Number.” Most of the time it is not necessary.
With this information, you can set up SurfShop™ to call the payment processor's website, request a payement authorization and respond to the customer with the result.
From the WebStore Manager, select “Global Settings.” Enter each of the fields from number 4, above into their respective input boxes and click “Configure Surf Shop.” The program writes the new settings to your SurfShop™ configuration file. A generic ECML type processor might use the following:
Cardservice Domain: [depends on processor]
Transaction Result: IOC_response_code
Approved Value: 0
Declined Value: 2
Declined Message: IOC_reject_description
Authorization Code: [none]
Reference Number: [none]
You can select one of the pre-configured forms on our paymenttypes page, or write your own. In any case, you will need to translate the fields used by SurfShop™ into the respective fields used by your payment processor using hidden HTML input tags.
For example, a generic ECML type processor might use the following form:
<form method="post" action="--ENTER CARDSERVICE URL HERE--" name="process_transaction"> <input type="hidden" name="c" value="receipt.htm"> <input type=hidden name="IOC_merchant_id" value="--ENTER MERCHANT ID HERE--"> <input type=hidden name="IOC_order_total_amount" value="<! USD_chargetotal>"> <input type=hidden name="IOC_merchant_order_id" value="<! orderid>"> <input type=hidden name="Ecom_SchemaVersion" value="http://www.ecml.org/version/1.1"> <input type=hidden name="Ecom_Billto_Postal_Street_Line1" value="<! Ecom_ShipTo_Postal_Street_Line1>"> <input type=hidden name="Ecom_Billto_Postal_Street_Line2" value="<! Ecom_ShipTo_Postal_Street_Line2>" <input type=hidden name="Ecom_BillTo_Postal_StateProv" value="<! Ecom_BillTo_Postal_StateProv>"> <input type=hidden name="Ecom_BillTo_Postal_PostalCode" value="<! Ecom_BillTo_Postal_PostalCode>"> <input type=hidden name="Ecom_Billto_Postal_CountryCode" value="<! Ecom_Billto_Postal_CountryCode>"> <input type=hidden name="Ecom_Billto_Online_Email" value="<! Ecom_Billto_Online_Email>"> <input type=hidden name="Ecom_Payment_Card_Name" value="<! Ecom_Payment_Card_Name>"> <input type=hidden name="Ecom_Payment_Card_Number" value="<! Ecom_Payment_Card_Number>"> <input type=hidden name="Ecom_Payment_Card_Expdate_Month" value="<! Ecom_Payment_Card_Expdate_Month>"> <input type=hidden name="Ecom_Payment_Card_Expdate_Year" value="<! Ecom_Payment_Card_Expdate_Year>"> <input type=hidden name="Ecom_Payment_Card_Verification" value="<! Ecom_Payment_Card_Verification>"> <input type=submit value="Check Out" name="submit"> </form>
Below are the fields used by SurfShop™ for Payment Purposes:
Ecom_BillTo_Online_Email Billing Email address Ecom_BillTo_Postal_City Billing City Ecom_BillTo_Postal_Company Billing company Ecom_BillTo_Postal_CountryCode Billing Country in AA format Ecom_BillTo_Postal_Name_First Billing First Name Ecom_BillTo_Postal_Name_Last Billing Last Name Ecom_BillTo_Postal_PostalCode Billing Zip Code Ecom_BillTo_Postal_StateProv Billing State Ecom_BillTo_Postal_Street_Line1 Billing Street Address Ecom_BillTo_Postal_Street_Line2 Billing Street Address, second line Ecom_BillTo_Telecom_Phone_Number Billing Phone Ecom_Payment_Card_ExpDate_Month credit card expiration month in MM format Ecom_Payment_Card_ExpDate_Year credit card expiration year in YYYY format Ecom_Payment_Card_Name credit card full name on card Ecom_Payment_Card_Number credit card full card number Ecom_Payment_Card_Type credit card type (visa, mast, amer, disc, etc.) Ecom_Payment_Card_Verification credit card CVV code Ecom_Payment_Check_AcctNum Checking Account Number Ecom_Payment_Check_AuthorizedBy Checking Signature Line Ecom_Payment_Check_Bank_City Checking Bank City Ecom_Payment_Check_Bank_Name Checking Bank Name Ecom_Payment_Check_Bank_Phone Checking Bank Phone Ecom_Payment_Check_Bank_State Checking Bank State Ecom_Payment_Check_Name Checking Name on Check Ecom_Payment_Check_Number Checking Check Number Ecom_Payment_Check_RoutingNum Checking Routing Number Ecom_Payment_Check_TransitNum Checking Transit Number
Your processor may require the Expiration date to be formatted a certain way. SurfShop™ automatically generates certain fields just for this purpose:
<! Ecom_Payment_Card_ExpDate_Month> expiration month in MM format <! Ecom_Payment_Card_ExpDate_Year> expiration year in YYYY format <! Ecom_Payment_Card_ExpDate_Yr> expiration year in YY format <! Ecom_Payment_Card_MoYr> expiration date in MMYY format <! cardexp> expiration date in MM/YYYY format
If you do not wish to store sensitive credit card information, you may wish to turn off the credit card form from your input page and capture this information just before initiating the payment processor (see below). If you do this, you must change the card number and expiration date from “hidden” input tags to “text” input tags (example for Authorize.Net):
Card Number: <input type=text name=“x_Card_Num” value=“”>
Exp. Date (MMYY): <input type=text name=“x_Exp_Date” value=“”>
Some processors may require additional fields to be passed as well. Check with your payment processor for specific technical information.
Now that you are using a payment processor to handle the credit card or check data, you may wish to turn off the credit card or check form on your info page. You can do this by selecting “Check-Out” options from your WebStore Manager and unchecking the appropriate boxes.
You should run a few transactions with your gateway in “test mode.” Your payment processor's documentation should have instructions on how to do this. Once you are satisfied that the gateway is working the way it is supposed to and SurfShop is correctly recording the transactions, you can GO LIVE!