Overview | Which One to Use? | AgoraCart Gateway Files | Selecting a Gateway to Manage
Installing/Updating a Gateway | Adding to Order Form with x-comments

Overview

In ecommerce there are 5 parts:

1. Customer
2. Shopping Cart (and your web site)
3. Payment Gateway and payment processing network
4. Merchant Account and Payment Processing Network (PPN)
5. Bank Account

For sake of simplicity we'll skip the first two as they are sure to be obvious as to what they are. The payment gateway is called such because it connects or builds a gateway between your shopping cart and payment processing network (PPN). The ID on that processing network is your merchant account (aka merchant account number). The gateway and the PPN talk back and forth until the customers data is processed and a resulting approval or denial of the transaction is reported back. Once done so, the customer returns to the cart and resulting order logs and confirmation emails are sent by AgoraCart. Some gateways will send confirmations emails to the customer and merchant as well (in addition to what the cart does). the final step is a resolution of funds to your company bank account from the merchant bank, but this is done thru that standard banking practices of each country.

NOTE: Processing methods such as ProPay and PayPal work a bit differently. They will usually hold the funds until you request a transfer to your account, whcih adds 3-4 additional business days before you see the funds. Other processing options such as 2checkout hold your funds for 2-4 weeks, with an additional amount held in reserve to cover returns. But true real-time gateways such as Authorize.net, AgoraPay, iTransact, Linkpoint Basic, PsiGate, PlugNPay, eWay, intellipay, PayFlow, etc will resolve in the normal 2-3 business days to your account.

Which Gateway should I use?

This is something you have to determine for yourself. Compatible gateways are listed at: Supported Gateways. Those listed as Pro Members Only require you to buy a Pro Membership to acquire the files you need to use with AgoraCart. These include: Verisign Payflow Link, PayPal (standard), eWay, and others.

For Startups: Those just starting stores and do not want to to get a merchant account, ProPay (use offline gateway for ProPay), PayPal, and 2Checkout.

For Ease of Use: For those wanting ease of use with current versions of AgoraCart, AgoraPay is the best. AgoraPay customers get more support for AgoraCart, a free upgrade if their cart is an older version, and also help with configuration of the managers (normally $125 or more in services). It's also a very solid gateway.

Other AgoraCart Staff Recommended Gateways: iTransact (see AgoraPay), PlugNPay (Canada & USA), PsiGate (Canada and USA), all for differing reasons. Dispite being harder to use and configure, Authorize.net is also recommended due to it's wide spread acceptance. We also had to throw LinkPoint Basic in this list due to their fantastic support to AgoraCart staff.

Gateway Files used in AgoraCart

There is four files for each gateway that AgoraCart supports:

1. The user file. This file is located in the admin_files directory of your store. The naming convention is: gatewayname-user_lib.pl. This file eventually holds the configuration data that you setup in the online gateway manager screen (in your online store manager).

2. The order library. This file is located in the library directory of your store. The naming convention is: gatewayname-order_lib.pl. This file handles many ordering processes including: creating data for order logs, creating data for confirmation emails, compiling variables and information to be sent to the gateway itself, processing the order form, and thank you pages.

3. The manager library. This file is located in the library directory of your store. The naming convention is: gatewayname-mgr_lib.pl. This file allows your online store manager to see and configure your gateway of choice. When you select a gateway fromthe list in the main settings area of your store manager, this is the file that registers the gateway in that drop down list. It also handles writing the configuration data to teh user file listed above when you edit and save data in the gateway manager screen.

4. The order form. This file is located in the html/forms directory of your store (navigate to store, then the html directory, then the forms directory under that). In older verion previous to 4.0K, the order forms are located in a directory under html called: main. The naming convention is: gatewayname-orderform.html. This file is the actual order form. The order form is stripped down HTML as it's included into a dynamically produced page between the secure version of the store's headers and footers. You can edit this form directly and add comments, remove shipping options (if not configurable in the store's online gateway manager screen), add more fields using the x-comments feature of AgoraCart.

Selecting a Gateway in AgoraCart to Edit

This assumes you are logged into the online store manager:

1. To select a gateway that you wish to edit in the gateway manager screen, you need to select the link named: program settings.

2. On the next screen, click on the Main Settings button.

3. On the main settings screen, there is a drop down box listing all the gateways available to you. Select the gateway that you wish to edit, then press the save button at the botton of the page.

4. then at the top of the page are links. Select the edit gateway link. This will take you to the screen to configure and edit your setting for your gateway taht you chose in the main settings screen.

Installing a Gateway into AgoraCart

AgoraCart is modular in many ways. One way is that you can upload the 4 gateway files (listed above) into their respective directory locations and press reload on the main settings screen and instantly see the gateway available to you in the drop down list. So, if you have a gateway you need to install (such as a Pro members only gateway, or an updated version), simply upload the 4 files to their respective locations (make sure .pl files are uploaded in ASCII mode), reload the main settings manager screen in your browser, select it and save. Then go to the gateway manager and set it up according to your needs. Easy as 1, 2, 3 !!!!

Adding Fields to Order Forms using x-comments

Another feature of AgoraCart's modularity is the ability to add fields to the order forms without changing any script code. Using what we call x-comments, you can add these fields and as many as you wish. this is how it is done:

1. open your orderform in an html editor.

2. determine the area where you wish to insert the new form field to collect information.
3. Insert Form Field using the format listed below. make sure to name each xcomment uniquely
4. Save form and upload to the store's html/forms sub directory (old versions are in the html/main sub directory).

Format of X-comments: the format of xcomments within the input tags would be: 1. NAME="Ecom_XCOMMENT_somethinghere"
2. VALUE="$eform_Ecom_XCOMMENT_somethinghere"

So lets say you wanted to collect the Company Name and the Fax number in the order form. This is how the form fields for each one would look:

Company Name:

<INPUT TYPE="text" NAME="Ecom_XCOMMENT_Company_Name"
	VALUE="$eform_Ecom_XCOMMENT_Company_Name" MAXLENGTH="50" Size=40>

Fax Number:

<INPUT TYPE="text" NAME="Ecom_XCOMMENT_fax"
	VALUE="$eform_Ecom_XCOMMENT_fax" MAXLENGTH="13" size=13>

Notice that we added a max length setting. This will limit the amount of characters they can enter, therby protecting you from text bombing. The x-comments for each form field is uniquely names as well. It's best to use something that will describe what you are asking for on the form.

When the form is processed by the order library, all the x-comments are automatically added to the confirmation emails and the order logs. NOTE: make sure not to collect sensitive information using this method, such as a credit card number or password.

If you need form fields required, then you will need to add a standard form field using the standard fields as reference, naming the field name and variable uniquely, then adding the variable name to the required fields array of the order library file (if there is a required array set).