SurfShopCart Documentation

Setting Up Shop Has Never Been Easier!

User Tools

Site Tools


Setting Up Payment Processing

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:

Find out what data fields your Processor uses

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:

Transaction Result

name of the field which contains the result of the transaction. It is often named “status,” “response,” “Auth,” “APPROVED,” or another name.

Approved Value

value when the transaction is approved. This might be a word or a number. Often it is “Approved,” “Y,” or “1”

Declined Value

value when the transaction is declined. This might be a word or a number. Often it is “Declined,” “N,” or “0”

Declined Message

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”

Authorization Code

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”

Reference No.

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.

Enter the values in your Global Settings Admin

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

AVS: IOC_AVS_result

Authorization Code: [none]

Reference Number: [none]

Enter the payment form into your Check-Out Options Admin

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="">
  <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">

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.

Revise your Check-Out Options

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.

  • Note: if you remove the credit card or check entry form, you must add these fields to your check-out html form by changing them from “hidden” input tags to “text” input tags (see above). You may also need to adjust the HTML to make the form look more attractive in the customer's web browser.

Test your settings

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!

Main Page

setting_up_payment_processing.txt · Last modified: 2018/07/03 04:55 (external edit)