Commerce Gate User Guide

Commerce Gate User Guide
Version 1.4.6
January 2008
1
Table of Contents
Introduction ................................................................................................................... ..................
4
The Overall Process ............................................................................................ ...........................
5
Creating a CommerceGate Account .......................................................................... .....................
6
The CommerceGate Website ........................................................................................................ ..
9
My Account ............................................................................................................................. ...
11
Webmaster Data ......................................................................................................... ...........
11
Bank Information ............................................................................................................... .....
12
My Websites ..................................................................................................................... .........
13
My Websites ..................................................................................................... .....................
14
New Website ...................................................................................................................... ....
15
My Offers ........................................................................................................................... ........
18
New Offers .................................................................................................................... .........
20
Currency Support for Offers .......................................................................................... .........
23
Language Support for Offers ....................................................................... ..........................
23
My Packages .................................................................................................................... .........
23
New Package ..................................................................................................................... ....
24
Modifying Offers and Packages ............................................................................................. ....
25
Statistics ....................................................................................................................... .............
25
Transactions ..................................................................................................... .....................
26
Rebills ....................................................................................................................... .............
27
Transaction Reports .............................................................................................................. 28
. Members Management ............................................................................................. .............
29
CommerceGate .......................................................................................................... ...............
30
Documentation Centre .............................................................................................. .............
30
Contact ......................................................................................................... .........................
30
CommerceGate Payment Page ............................................................................... ....................
30
Customer Support and Cancellations ................................................................ ...........................
30
Upsell Transactions ........................................................................................... ...........................
31
Sale Payment Link ........................................................................................ ............................
31
Upsell Payment Link ............................................................................................................ ......
33
Callbacks .............................................................................................................. ........................
34
Overview of Callbacks ................................................................................................... ............
34
Setting Up Your Callback Server ..................................................................................... ..........
35
Callback Message Parameters for String Messages (ID=0) ......................................................
36
Callback Message Parameters for XML Messages (ID=1) .............................................. ..........
37
Valid Callback Message Types ....................................................................... ..........................
38
Callback Server Responses .................................................................................. ....................
39
Testing the Callback Server ............................................................................. .........................
40
Using the Commerce Gate API ............................................................................................. ........
41
2
Cancellation Messages API .................................................................................................... ...
41
Retrieving Transactions Using the API .......................................................................... ............
41
Transaction Message Format ........................................................................................... .........
43
The CC Form ............................................................................................................ ....................
46
Testing Credit Cards ..................................................................................................... ................
46
NATS / MPA3 ............................................................................................................................. ...
47
Integration ........................................................................................................................ .............
48
FAQ .................................................................................................................. ............................
50
Support Information .......................................................................................... ...........................
52
Appendix 1: Callback Information ....................................................................... ..........................
53
Callback Message Formats ......................................................................................... ..............
53
Callback Parameters ................................................................................................ .................
54
Callback Message Types .................................................................................. ........................
54
Callback Server Responses .................................................................................. ....................
55
Currency Parameter Valid Values ....................................................................... ......................
55
Country Information ........................................................................................................ ...........
56
.........
.............................................................................................................................................
62
Server Callback Script ..................................................................................................................
63
Cancel Membership Sample Script .................................................................................... ..........
66
3
Introduction
CommerceGate provides Websites with a billing back­end, allowing your sites to process credit cards and other payment methods without coding the processes to do this yourself, and without requiring you to go through the process of becoming a registered merchant with credit card companies. Essentially, CommerceGate becomes your payment handler, allowing visitors to your site to become members and pay for access to your site through CommerceGate, without the visitor being too aware of the association between your site and CommerceGate.
In order to provide a billing service to your site, when a customer decides to sign up for a membership (you can define what membership means and what it costs), your site transfers to the CommerceGate Website, which then processes the customer’s information, validates their payments, then sends payment confirmation back to your site to let you know the customer has paid (or, in some cases, that payment has been rejected). CommerceGate allows you to set up recurring billing, so that a customer can pay a monthly fee, or any other payment frequency you set, automatically. You can also define payment packages for customers, and payments for packages is handled for you automatically.
The CommerceGate Website is your front­end into the CommerceGate system, and allows you to create offers and packages for customers, as well as associate them with your Websites. You can also use the CommerceGate Website to see how much money you are making!
For CommerceGate to work with your site to process payments, you need to do several things, including setting up the CommerceGate Back Office to contain information about your offers and your Websites. You also have to add the code to your site to call the CommerceGate site and process payment information, as well as handle special codes coming back from CommerceGate to indicate whether a user has paid or not. While this is a technical process, any Web programmer should be able to handle it for you, or, with a bit of patience and guidance from this document, you can do it yourself.
This User’s Guide is divided into a number of sections. To begin, we take an overview of the process you need to follow to set up one of your Websites to handle payments through CommerceGate. Then, you will see the CommerceGate Back Office in detail. Following this, the technical information on adding code to your site to talk to CommerceGate is presented. Finally, a set of summary reference information provides all you (or your Website developers) need to know to finish the integration between your site and CommerceGate.
4
The Overall Process
So you want CommerceGate to handle payments for your Website? Great! While there’s a bit of work you need to do to put this all in place, the process is logical and you can follow the instructions in this guide to complete the steps, one by one.
The overall step process you need to follow is:
1.Create a CommerceGate account
2.Log into your CommerceGate account a.Set up offers
b.Set up packages
c.Give information about your Websites
3.Build the code to link to CommerceGate into your Website
a.Set up callbacks
Each of these steps is covered in more detail in the sections that follow.
To use the CommerceGate services, your Web server needs to communicate with the CommerceGate server, and transfer information back and forth. These data transfers, called “callbacks” are described later. In order to perform callbacks, though, your server needs to meet some minimum requirements. Your Web server needs:
•FTP access enabled
•PHP version 4.2 or higher
•Htaccess functionality
•Support HTTPS (Secure HTTP)
CommerceGate recommends servers running Linux with Apache Web Server software, but Windows will suffice as a server platform if the requirements above are met.
5
Creating a CommerceGate Account
If you want to become a CommerceGate customer, visit the CommerceGate site at
www.CommerceGate.com
and the CommerceGate home page appears:
Click on the “Sign Up Today” button and you will be redirected to a window that asks for your information:
6
Complete all the information requested and click the Submit button. Your information will be sent to a CommerceGate account representative you will review the information and confirm you for a CommerceGate account. You will then receive an email containing your site username (which is also your customer ID) and a temporary password. The email will also contain the link to the CommerceGate Back Office.
It is important to record your customer ID number. This number is used as a base for the login to the CommerceGate system. You should include your customer ID number on all communications with CommerceGate.
At this point, there are several steps you need to complete in order to integrate your Websites with the CommerceGate server. These steps are:
1.Use the CommerceGate Back Office interface to create offers and packages (see “My Offers” and “My Packages” below).
2.While still in the CommerceGate Back Office, set up the links to your site using “My Websites”. Your Website link request will be submitted for approval by CommerceGate.
3.Complete the technical information on the Technical Data page of the Back Office
When you have completed this information, it is reviewed by CommerceGate prior to the link between your Website and CommerceGate being activated. After the information has been reviewed and approved, you can either have CommerceGate support personnel access your server using FTP and install the software components needed to enable the link to CommerceGate, or you can complete the software integration yourself. 7
There are a few more steps required for your Website to properly handle credit cards. These are quickly summarized below, and expanded in detail later in this Guide. Following the installation of CommerceGate code on your server, you need to configure your server to handle callback messages from CommerceGate (see “Callbacks”). This is done through a callback server (see “Setting up Your Callback Server” for more information).
Once these steps are completed, CommerceGate will supply test credit card numbers for you to use to thoroughly test the integration of your server and the CommerceGate server. You should try several transactions to ensure they are processed correctly, and that your server is properly receiving information from the CommerceGate server through your callback server.
Finally, you can make your Website “live” and being processing customer transactions through CommerceGate. 8
The CommerceGate Website
After you have created an account on the CommerceGate Website, you can login in from the main page. Click the login button and you will be greeted by the login window:
The login you should use (and the initial password) will have been emailed to you after your account was created. The first time you log in you using the username and password, you will be asked to change the password:
9
Passwords on the CommerceGate server expire at preset intervals (including the first time you log in). You will be asked to change your password at regular intervals for security reasons. To change your password, enter your username and old password, as well as your new password. You have to re­enter you new password twice to prevent typing errors from preventing your password from being recorded properly. Click the “Accept” button to make the password change effective immediately.
Passwords used on the CommerceGate server must be “strong”, meaning they are hard for a hacker to guess or force using a standard password guessing routine. For this reason, passwords must be a mix of upper and lower characters, must contain at least one digit, and must be between 8 and 20 characters inclusive. If your new password does not meet any of these rules, you will be asked to enter a new password that does meet the requirements. Strong passwords are often difficult to remember, so be sure you record your password somewhere for future use.
When you log in to the CommerceGate server successfully, you’ll see the main screen:
The upper right corner of the window shows your login name as well as a logout button. If you are going to walk away from your PC, you should either lock your session using Windows, or log out of the CommerceGate server for security reasons.
The left side of the window contains a set of links leading to different aspects of the CommerceGate system, divided into four main areas:
10
•My Account: contains basic information about your account and banking information registered with CommerceGate
•Websites Management: allows you to manage the integration of the CommerceGate system with your existing and new Websites
•Statistics: shows information about your transactions and members
•CommerceGate: displays online help as well as contact information
Each of these areas has several links within the area, and is covered in detail later in this User Guide.
My Account
The My Account area of the CommerceGate main window contains information on your CommerceGate account as well as banking information you have registered with CommerceGate. There are two links available under the My Accounts header:
•Webmaster Data: displays general information about you and your account
•Bank Information: displays information about your bank accounts integrated with the CommerceGate system
To access either of these links, click on their name. Each link is covered in more detail below.
Webmaster Data
The Webmaster Data link displays a window that contains general information about your account. The Webmaster Data window looks like this:
11
The information on the Webmaster Data page is divided into three sections:
•Webmaster Data: information about your Webmaster’s account
•Business Data: information about your business
•Technical Data: information about your technical contact
The information on this screen is created by CommerceGate and cannot be directly edited.
Bank Information
The Bank Information link shows information about the bank account tied to your CommerceGate account:
12
You can make changes to your bank information on this screen, and then click “Accept Modifications” to record the changes in your account. Completing this information correctly is important as CommerceGate uses this bank information to send funds to you. Without this information, you will not be paid.
My Websites
The My Websites area on the main CommerceGate window allows you to see and manage the integration of the CommerceGate system with your Web sites.
Note: Once you have configured your Web site information, it will have to be approved by the Commercegate compliance department. After this approval it cannot be changed. This is a legal requirement of the credit card companies. If any subsequent changes are required, you will have to completely recreate the configuration and have it re­approved by the compliance department.
There are seven links in the My Websites area:
•My Websites: shows the Websites currently registered with CommerceGate
•New Website: allows you to add a new Website to your account
•My Packages: shows the packages you have created with CommerceGate
•New Package: allows you to add a new package to your account
•My Offers: shows the offers you currently have active on your account
13
•New Offer: allows you to add a new offer to your account
•Protection Test: lets you run a test on your Websites’ integration
Each of these options is examined in more detail below. My Websites
The My Websites link shows a list of all the Websites you have created in the CommerceGate system. When you click on the My Websites link, you will see a summary of all the Websites:
Each Website is listed with its ID number (for internal reference), the Website name, the URL, the Category, and the date you created the site. The colour of the row indicates the status of the Website. A green colour indicates the Website is accepted by CommerceGate and the URL is active. A yellow colour indicates the Website is still pending approval (usually when you create a Website). A red colour means the Website was denied by CommerceGate, often when there is important information missing.
To see more information about any of the Websites shown, double click on the row of the Website and you will see a summary of the site:
The top pane lists basic information about the site, including:
•the Website name (as created by you)
•the Category (type of Website)
•the public URL (available to anyone)
•Members URL: the URL members are directed to
•Apache Log path: the path to the Apache log file
•Members Path: the absolute or relative path for members on the server •Member Area Test Name and Password: to allow for testing of the server integration
The middle pane of the window shows the packages that are available on that Website. The bottom pane shows information about the Gateway and callback server. The information here is:
14
•Callback URL: the URL for the callback server
•Callback Type: the type of callbacks used
•Username generation: how usernames for the site are generated
•Password generation: how passwords for the site are generated
•Alternative callback URL: a failover URL for the callback server in case the CommerceGate server rejects the transaction for some reason; the user’s browser is sent to this URL if that happens
Each Website can be examined individually by clicking on the site name in the My Websites list.
New Website
The New Website link allows you to add a new Website to your CommerceGate account. Since Websites are tied to Packages, you need to create a Website based on one or more packages. Note that Websites do not show offers, only packages, although a package can have a single offer in it If you click on the New Website link without any offers or packages existing, you will see this warning:
If you are performing an initial setup of your account, you likely will not have any packages created yet. If this is the case, begin by creating one or more offers, then create packages, then you can add a Website to your account.
If you have offers and packages already created for your account, the New Website link allows you to add a new Website to your account quickly. When you click on the New Website link this window appears:
15
There are several components to this window. The top panel asks for the Website information. The fields are:
•Website Name: a description of the Website for your reference
•Website Category: a general category for the Website (Adult or Mainstream)
•Public URL: the URL of the Website
•Member URL: the URL that valid members are sent to
Fill in each of these four fields with their respective information. If you are missing some information (such as Member URL) you can leave it blank and edit the information later.
The Offer Packages Selection panel lets you select the packages that will be associated with this Website. Check all of the packages that will be applied. You can indicate the default package in the last column; this is the package that is used by default in the Website. (Remember that offers are not used on your Website, only packages.)
The Gateway Configuration panel is used for setting access information. Callbacks are created when a visitor to your site buys a package, and are used to send the information to your site. The panel looks like this:
16
The first drop­down list asks whether you are going to install the callback scripts on your Website yourself or whether you want CommerceGate to do this task. The rest of the panel asks for basic information about the callback:
•Callback URL: the URL used to handle the callback
•Callback Type: the type of callback (XML or string). If unsure, you should select XML.
•Username Generation: whether to allow the user to choose a username or to generate one either on your site or at the CommerceGate site
•Password Generation: whether to allow the user to choose their password or create one for them, either on your site or at the CommerceGate site
Callbacks are covered in more detail in the “Callbacks” section of this User Guide. See that section for more information on how to use callbacks.
The final panel in the New Website window is CCForm information:
This panel asks for information about the form design, allowing you to customize the CommerceGate credit card form to match your Website. The fields on this panel are:
•Background Colour: the hexadecimal value of the background colour
•Font Colour: the hexadecimal value of the colour of the font
•Font Size: lets you set the size of the font to use
17
•Upload Logo: allows you to add your Website logo to the credit card page
•No Logo: does not add a logo to the page
When you have completed all this information (or as much as you can at this point) click the “Create Website” button and the new site will be added to My Websites.
My Offers
Offers are the subscription and purchasing options your Website will offer customers as part of a package. A package is made up of one or more offers; packages are the items the customer sees when they are directed to the Website. Since packages are composed of offers, you start by defining offers themselves, then create packages from combinations of the offers.
There are three types of offers. Trial/Membership offers are recurring and have a bill for the customer at intervals you specify, such as monthly or yearly. One Shot offers allow the user to purchase unlimited access to an account (or access controlled by your site software, not CommerceGate). Finally, Upsell offers allow you to add special rights to an offer easily, allowing the customer to sign up for these more easily than creating a new membership. The reason this is a useful feature is that the less a customer has to do to complete a purchase, the higher the chances of them completing the transaction.
The type of offer you choose depends on your needs. For example, if you are creating a technical support forum, you might want to charge the customer for access only once, allowing them unlimited access for a set price. This would be a One Shot offer. Alternatively, you might want to have the customer pay a monthly or quarterly fee, rebilled automatically until the customer cancels their account. A Trial offer allows the customer access for a short period of time (a few days, for example) and then, unless the customer cancels, reverts to a regular membership billing. Finally, Upsell offers allow you to provide additional access or services to the customer for an additional fee over and above the membership fee. You might, for example, charge an extra fee for access to your device driver library, or access to video content/ Each of these offer types is created in the New Offers link, described below, and managed in the My Offers link.
The My Offers link allows you to see all the offers you have created for your account quickly. When you click on My Offers you see this summary window:
18
The top of the window has three tabs for the different types of offers the system allows: Trial/Membership, One Shot, and Upsell. Click on the tab of the offer type you want a summary for, and the screen will change to reflect your choice.
Each tab shows details of all the offers in that category. This includes the name, duration, prices, any translations that may be associated with the offer, the number of packages using that offer (see “My Packages” below), as well as two buttons to allow you to Edit or Remove the offer. To make changes to an offer, click the Edit button. The window will then display the details of the offer and you can make any changes you wish:
After you make any changes required, click the “Accept” button to records those changes.
To remove an offer, click the “Remove” button. You will be asked to confirm the removal of the offer.
Some offers cannot be edited or removed because there are dependencies on those offers (for example, a membership may have Upsell offers associated with it). These dependencies must be resolved first.
19
New Offers
To create a new offer, click the New Offers link. This will display the New Offer first window which asks for the type of offer you are going to create:
As described on the screen, there are three types of offers you can create:
•Trial/Membership: allows a customer access to your site based on a recurring billing model
•One Shot: the customer pays once and is allowed unlimited, no expiry access to the site
•Upsell: allows you to create a basic offer with additional options; users can buy these options at any time in a simpler manner than starting from scratch each time
Click on the button in the area that best describes the type of offer you are going to create.
Trial/Membership Offer
Trial offers allow the customer access to a site for a certain period of time, then they are blocked unless they convert to a membership offer. To create a Trial offer, a Membership offer must exist first (so the trial can revert to membership automatically).
When you select the Trial/Membership type of offer, you are taken to this window:
20
To create the new Trial/Membership offer, fill in the information required on this form:
•Default Name: the name of the offer, used for easy reference •Offer Type: select either Trial or Membership from the drop­down list
•Duration: select the duration of the offer, in months (membership) or days (trial), before the offer or membership expires
•EUR Price: the price of the offer in Euros
•USD Price: the price of the offer in US Dollars
•The price of the offer in any currencies enabled for your account
•Rebills Over: membership offer completed automatically after a Trial expires
When you have finished adding information, click the “Accept” button and the offer is added to your CommerceGate account. One Shot Offer
The One Shot offer is a single price for access, without monthly rebillings. This type of offer allows unlimited access unless blocked by the site administrator or until cancelled by scripts running on your own web server. When you click on the One Short offer option in the New Offer link, this window appears:
21
To create a new One Shot offer, fill in the fields on this form, which are:
•Default Name: the name of the offer, used for easy reference •EUR Price: the price of the offer in Euros
•USD Price: the price of the offer in US Dollars
•The price of the offer in any currencies enabled for your account
•Clone as Upsell: creates an Upsell offer for this offer as well
When you have finished adding information, click the “Accept” button and the offer is added to your CommerceGate account. Upsell Offer
An Upsell offer allows you to sell “add­ons” to a membership account easily. When you click on the Upsell option on the New Offer window, you will see this window:
To create a new Upsell offer, fill in the fields on this form, which are:
22
•Default Name: the name of the offer, used for easy reference •EUR Price: the price of the offer in Euros
•USD Price: the price of the offer in US Dollars
•The price of the offer in any currencies enabled for your account
When you have finished adding information, click the “Accept” button and the offer is added to your CommerceGate account. Currency Support for Offers
By default, CommerceGate Back Office handles two primary currencies: US Dollars and Euros. However, you can customize your offers and packages to support local currencies too. When a customer is redirected to the CommerceGate site, the server attempts to determine where they are connecting from. If the server can determine this, local currency can be offered to the user. If local currency is not offered, or not desired, either US Dollars or Euros are used. All offers and packages have two levels of currency: local and secondary (which is always US Dollars or Euros). Customizing a Website to a local currency allows you to better serve your customers. For example, someone connecting from Sweden could be offered a package in Kroner or in Euros, making the site more targeted and friendly to the customer.
The ability to define the price in multiple currencies is beneficial to your income. The alternative would be to automatically convert the price between currencies. But this way, you might be able to charge a higher price in the other currencies, than a simple automatic conversion would give. For example an offer of $19.95 might convert to 14.56€, but you could probably get away with charging 19.95€ as well..
Language Support for Offers
The offers can have their descriptions defined in other languages as well. The Commerce Gate payment form currently supports 6 languages: English, French, Spanish (Castellano), Dutch, German & Italian. When you define translations for the offer, these will be displayed, when the form is being displayed in that language.
My Packages
Packages are a combination of offers, bundled to make it easier for a customer to choose what they want from your site. A package may be a basic offer with one or more Upsell offers attached to it, or it may be several offers bundled together (for multiple site access, for example). You can also have a package made of only one offer. You can create as many packages as you want, 23
giving your customers a choice in their purchase.
When you click on the My Packages link, all the existing packages are shown in this summary window:
Each package is shown with the package name, the number of Websites that offer that package, the number of offers inside the package, when the offer was created, and two buttons for editing and removing a package.
To make changes to a package, click the Edit button. The window will then display the details of the package and you can make any changes you wish. After you make any changes required, click the “Accept” button to records those changes.
To remove an package, click the “Remove” button. You will be asked to confirm the removal of the package.
Note:If you define a trial offer that rebills to a membership offer, it is not necessary to put both offers in a package. If you place just the trial offer in the package, only the trial will be visible on the payment form. The trial will still rebill to the full membership.
New Package
To add a new package to your CommerceGate account, click the New Package link. Clicking on New Package will display this window:
Enter a descriptive name for this package and click the “Accept” button. This leads to the offer summary window:
24
Click the checkbox in the column to the left of the offers you want this package to contain. When you select an offer, the row will change colour to show it has been selected. If you want to add several offers, check them all. To add an Upsell or One Shot offer, click those tabs and select the offers in the package. Finally, click the “Accept Modifications” button and the new package is created. It will be visible through the My Packages link.
Modifying Offers and Packages
One a package has been linked to one of your Websites, the package contents (the offers and the makeup of the package) cannot be changed. This is to ensure continuity for customers who buy one package, and then the package changes at a later date. It is also a compliance requirement demanded by the credit card companies.
To make a change to a package or an offer already linked to a Website, it is best to create a brand new offer or package to avoid confusion. You could unlink the package, modify the contents, then link it again, but CommerceGate recommends you create a new package instead.
If a package has not been linked to a Website, it can be modified, as can the offers inside the package.
Note: for the above reasons, it is best to get the offers, packages and websites as correct as possible, before submitting them for compliance.
Statistics
The Statistics area of the main CommerceGate window allows you to see summary information about your usage. There are four links in the Statistics area:
•Transactions: a summary of all transactions on your account
•Rebills: a summary of any rebills for memberships
•Transactions Reports: specific reports on transactions
•Member Management: manage the members of your site (if handled by CommerceGate)
Each of these four links is covered in more detail below.
25
Transactions
The Transactions link shows a summary of all transactions that have occurred on your account. The window has several tabs across the top, each of which leads to different information. The first tab is for General Information:
This panel allows you to select the day and time for the start and end of the transaction report, as well as narrow down the report by type of transaction if you wish. You can also use the two checkboxes to indicate whether to include or exclude successful and failed transactions. The other tabs on this panel allow you to create transaction reports by the user’s location, the details of the transaction, the credit card information, or the user information. This allows you to search for very specific information (such as a particular credit card number) or more general reports (such as all users from Belgium). When you have specified any of the information on these panels, click the “Search” button, the transaction report is generated.
The headers of the transaction report look like this:
The icons show the different types of transactions. The columns are labelled and have a “­toggle­“ link next to them to indicate whether to sort by that header or not.
26
Rebills
The Rebills link under the Transaction header lets you see rebilling performed for your sites quickly. When you click on Rebills, this window appears:
You can select the date and time of the starting and ending dates for the report, as well as choose a status, offer, username, or Website. You can specify as much or as little of this information you want, and then click the “Search” button to initiate the search.
The bottom of the panel shows the rebill report, including the Website and user ID that was billed, as well as ongoing status of each rebill attempt (whether it was successful or not).
27
Transaction Reports
Transaction Reports allows you to see a summary of all transactions on your account, including monetary totals. The window looks like this:
28
The top pane of the Transaction Report contains the search information. You can select the date and time of the starting and ending dates for the report, as well as choose a status, offer, username, or Website. You can specify as much or as little of this information you want, and then click the “Search” button to initiate the search.
Below the Search information is the total summary, which shows monetary information associated with your account. Two panels below the summary show successful and failed transactions on your account.
Finally, the last panel shows the ten countries that have the highest uptake of memberships and offers.
Members Management
CommerceGate handles your Website membership lists for you (and handles all membership validation when a member logs onto your site). The Members Management link gives you access to the members database. When you click on the Members Management link, this window appears:
The top part of the window allows you to set parameters for searching the members database. The bottom of the panel shows a summary of all members that match your search criteria.
One feature of Members Management is the ability to create a No Money User (NMU) which is a valid user of your site, but there are no charges incurred. This is useful for people you want to give free accounts to, as well as for testing your Website (see “Callbacks” later in this guide).
29
CommerceGate
The CommerceGate area of the main window allows you to access the online documentation and provides contact information.
Documentation Centre
This link allows you to access the online documentation library supporting CommerceGate. Click on the links to view the documentation. All documents are managed as PDF documents, so you will need a copy of Acrobat Reader to open them (available free of charge from www.acrobat.com).
Contact
The Contact link displays contact information for CommerceGate, including telephone numbers and email addresses (see “Support Information” later in this document).
CommerceGate Payment Page When one of your site visitors decided to purchase an offer from a package, they are taken to your payment page on the CommerceGate server. The payment page is reached from your server by redirecting the user to this URL (but with parameters defined):
https://secure.commercegate.com/payment/ccform.php
This is called the Sale Payment Link.
When they land on this page, the user is presented with a list of the offers in one of the packages that you have set up through the Back Office for the site that is directing them to CommerceGate. After the user has chosen an offer, paid for it by credit card, and finished with the transaction on the CommerceGate server, they are redirected back to your site and a callback message is sent to your server.
To send information about the user to the CommerceGate payment page, you need to send a Sale Payment Link with parameters in a particular format to CommerceGate. This is explained later in this section under the subhead “Sale Payment Link”.
Customer Support and Cancellations
Customers for your Website can change their billing information (such as credit card number) and cancel memberships to your Websites. They do this by being redirected to the following URL (you should put a link to this URL on your site):
30
https://www.cgbilling.com
As an alternative, instead of having the customer visit this URL to cancel their membership, you can have a “cancel membership” link on your site. If you do this, you need a script on your website that sends a message to the CommerceGate server to notify the server of this change. This message to the CommerceGate server is explained in the “API” section below.
Note: It is important to make it as easy as possible for a user to cancel their subscription. This way expensive ‘chargebacks’ or refunds can be avoided.
Upsell Transactions
The use of Upsells allows you to more easily meet customer needs by allowing a faster and more convenient way for them to add to their existing account offers. This is useful when you want to add an “extra” feature to a Website, such as access to a video collection or library, or when you have a renewal­model offer such as a site that uses credits for minutes of access. When an existing customer wants to add access to the video library or buy more credits, they are directed to the CommerceGate server payment page as usual, but only need to enter the last six characters of their credit cards and confirm the purchase, instead of having to go through the entire purchase process again. This fast transaction process is useful because it allows the customer to quickly conduct a purchase; the more a user has to do to buy something, the less likely it is they will complete the transaction (“less clicks means more conversions”).
To direct a user to the “Upsell Payment Form”, put the Upsell Payment Link on your website, with the necessary parameters. Details of the Upsell Payment Link and how to use it are in the “Upsell Payment Link” sub­section, below.
Sale Payment Link
The message your server needs to send to the CommerceGate payment page when a customer is ready to purchase an offer or package will have the following information in it:
31
Parameter
Description
Mandatory
Type
Length
cid
Customer-ID
yes
Number
10
wid
Website-ID
yes
Number
15
username
Preselect a username *
no
Varchar
50
email
Prefilling the payment-page with the
Email-Address of the enduser
no
Varchar
128
password
Preselect a password *
no
Varchar
50
lang
no
Varchar
2
op1
Set a language with lowercase-iso:
Supported languages: es, de, it, en,
us, nl, fr
Optional parameter 1
no
Varchar
255
op2
Optional parameter 2
no
Varchar
255
op3
Optional parameter 3
no
Varchar
255
packid
Package ID; allows a specific
package to be shown to the user
when they reach the
CommerceGate server **
no
Number
10
preoffer
Preselect an offer by offer-id***
no
Number
10
* You must provide the username / password if you have configured your account, in the Commerce Gate Back­Office, so that the username / password is supplied by your server.
** If packid is not specified, the form will display offers from the package that is marked as the ‘default’ package for the website.
*** The offer indicated by the preoffer parameter, is the offer that will be initially selected in the payment form. However, if there are muliple offers in the package, the user can select another offer.
A sample Sale Payment Link from your server to the CommerceGate server looks like this:
https://secure.commercegate.com/payment/ccform.php?cid=1&wid=21&username=client1&email=
[email protected]&packid=222&preoffer=23
For the offer ID and to handle the username and password issues, use the CommerceGate Back Office My Website options (see “My Websites” earlier in this document).
Note that the CommerceGate payment page will accept traffic only from your registered Website (configure your sites in “My Websites”).
32
When a customer purchases an offer or package from the CommerceGate payment page, a SALE callback is sent back to your callback server with the parameters described below in the ‘Callbacks’ section.
Upsell Payment Link
To handle upsells, a special URL is used to redirect your customers to the upsell form:
https://secure.commercegate.com/payment/upsell.php
The browser is then sent to the CommerceGate server with the following parameters:
Parameter Description
Mandatory
cid
Your customer­id
yes
wid
Your website id
yes
username username that was registered with CommerceGate
yes
packid
Package ID; allows a specific package to be shown to the user when they reach the CommerceGate server
no
Note that the CommerceGate payment page will accept traffic only from your registered Website (configure your sites in “My Websites”).
33
Callbacks
Callbacks are information messages sent between two Websites to explain what is going on. For example, when a customer buys one of packages through CommerceGate, the CommerceGate server sends a message (a callback) to your site to tell your site about the purchase. Callback messages are used to describe new purchases as well as to record changes in existing purchases (such as a renewal or rebill). In order for your Websites to handle callbacks, a “callback server” is required, one for each Website you run through CommerceGate. A callback server is not a separate, dedicated machine, but simply a script that runs on your existing server. A callback server has a URL that CommerceGate uses to communicate with it. You have to tell CommerceGate what this callback server URL is (this is done through the New Website link on the main CommerceGate Back Office. A sample script for a callback server has been included in an Appendix to this User Guide. This callback server script will not function if simply copied to your server. Some customization is required. The example script is written in PHP and most Web developers will be able to customize the script easily.
The standard script provides access control through the apache htpasswd module. If you want to add a more sophisticated membership access control system, you will have to provide your own scripts. Commerce Gate can, however, provide you with sample code, for example for use with a MySQL database.
Overview of Callbacks
There are two types of callback messages supported by CommerceGate. The first uses simple strings or lengths of characters which contain information. The second type is based on XML (eXtensible Markup Language). The advantage to XML is it allows for better integration with some server back office functions such as databases, and is a more rigorous and formal method of handling callbacks. String callbacks are easier to create and handle, but not as robust as XML callbacks. The type of callback message is indicated by a number: string callbacks are ID=0, and XML callbacks are ID=1. It is important to tell CommerceGate which type of callback ID you will be using (you do this through the CommerceGate Back Office) or the messages will not make sense to your server.
When a message has to be sent from the CommerceGate server to your server, it is done in a special URL like this:
http://www.domain.com/callback/server.php?messagetype=<ID>&message=<MSG>
The first part of the message is your callback server URL (here 34
www.domain.com/callback/server.php. This callback server runs PHP, a programming language often used for handling callback servers. The second part of the message indicates the message type (so an XML message would be messagetype=1) and the last part is the message itself.
Regardless of whether the callback is sent as a string or XML message, they are both sent using an HTTP GET (not as an HTTP POST). If the message is an XML string, it is automatically encoded by the GET message when sent from the CommerceGate server, and decoded by the callback server PHP script on your machine. (If you write your callback server in a language other than PHP you will have to code the decoder explicitly.)
Setting Up Your Callback Server
There are three steps to setting up your callback server:
•Create a URL for the callback server associated with each site
•Restrict access to the callback server •Configure the callback server to handle communications
•Test the message handling of your callback server.
You can create a callback server URL quite simply by specifying a complete URL which may or may not be based on your Website URL. The second step in creating a callback server is to restrict access to the callback server URL only to the CommerceGate server. You will be provided with the CommerceGate server IP addresses, You must block all IPs except these Commerce Gate IPS, to prevent anyone else accessing the server and creating false payment information. In apache, this is normally done using the .htaccess configuration file. Please ask the commercegate­support for thes IP­Addresses. As mentioned above, a sample PHP­based callback server structure is provided in an Appendix.
Finally, you need to configure the callback server to handle the callbacks from CommerceGate and test it. You can test the callback server using a special test feature built into the CommerceGate Back Office (see “Testing the Callback Server” below).
When a message is sent from the CommerceGate server to your callback server, your callback server replies to the CommerceGate server to indicate whether the message has been received and understood properly (see “Callback Server Responses” below).
Note: It is critical that your server properly respond to a callback message from the CommerceGate server or the transaction is cancelled automatically! If any response other than “success” is received by the CommerceGate server, the transaction is rolled back and cancelled.
35
Callback Message Parameters for String Messages (ID=0)
Each message from the CommerceGate server to your callback server can have parameters in it to pass basic information such as email addresses and user IDs. Each message from the CommerceGate server has the following layout for messages of ID=0 (string callback messages):
<TYPE>#<TRANSACTIONID>#<TRANSACTIONREFERENCEID>#<OFFERNAME>#
<OFFERID>#<AMOUNT>#<CURRENCY>#<USERID>#<USERPW>#<EMAIL>#<IP>#
<COUNTRYISO>#<CARDHOLDER>#<CUSTOMERID>#<WEBSITEID>#
<OP1>#<OP2>#<OP3>#<NMU>#
This message format contains a considerable number of parameters, each parameter separated by a hash mark. The following parameters are included in callback messages. This table includes the data type and the maximum length of the parameter:
Parameter
Type
Description
Length
Type
String
Callback­Type (See Callback­Types)
32
TransactionID
Integer
Unique transaction­id
38
TransactionReferenceID
Integer
Related transaction­id
38
OfferName
String
Name of the offer
80
OfferId
Integer
Unique­Id of the offer
10
Amount
Integer
Amount in cents
20
Currency
String
ISO­Code, see Appendix Currencies
4
UserID
String
Username of the member
40
UserPW
String
Password of the member
40
Email
String
Provided email­address
50
Ip
String
Ip­Address of the enduser
CountryIso
String
ISO­Code of the Country, see Appendix Country­Codes
3
CardHolder
String
Provided Cardholder name
128
CustomerID
Integer
Your customer­id
10
36
WebsiteID
Integer
The website­id the user has registered on
10
Op1
String
Optional­parameter
60
Op2
String
Optional­parameter
60
Op3
String
Optional­parameter
60
NMU
Integer
No­Money­User, can be 0 or 1. Can be 1
used to test the callback server or to create VIP­Users
A message contains all these parameters as shown earlier, but may not have data in all the parameter values. A sample message sent without encoding for clarity is as follows:
SALE#3#1#OFFER1#221#399#EUR#username#aBgR3tg#[email protected]#192.
168.1.1#ES#Max Mustermann#5#6#op1#op2#op3#1#
This would mean that the transaction type is a sale, the transaction ID is 3, the transaction reference ID is 1, the customer chose the offer called “Offer1” with offer ID 221, and so on.
Since this message content will be added to the URL of the callback server for your Website, the actual message from the CommerceGate server would look like this:
http://yourdomain.com/callback/server.php?messagetype=0&
message=SALE%233%231%23OFFER%23221%23399%23EUR%23username%23aB
gR3tg%23email%40email.com%23192.168.1.1%23ES%23Max%20Mustermann%235
%236%23op1%23op2%23op3%231%23
Callback Message Parameters for XML Messages (ID=1)
Message from the CommerceGate server to your callback server using XML can have parameters in them to pass basic information such as email addresses and user IDs. Each message from the CommerceGate server has the following layout for messages of ID=1 (XML callback messages):
<?xml version='1.0' standalone='no'?>
<!DOCTYPE cgCallback SYSTEM 'cgcallback.dtd'>
37
<cgCallback>
<Type>SALE</Type> <TransactionID>3</TransactionID> <TransactionReferenceID>1</TransactionReferenceID> <OfferName>OFFER</OfferName> <OfferId>221</OfferId>
<Amount>399</Amount> <Currency>EUR</Currency> <UserID>username</UserID> <UserPW>aBgR3tg</UserPW> <Email>[email protected]</Email> <Ip>192.168.1.1</Ip> <CountryIso>ES</CountryIso> <CardHolder>Max Mustermann</CardHolder> <CustomerID>5</CustomerID> <WebsiteID>6</WebsiteID> <op1>op1</op1>
<op2>op2</op2> <op3>op3</op3> <NMU>1</NMU>
</cgCallback>
The parameters for XML callback messages are the same as those for string callback messages (see the table in the previous section).
A complete sample XML callback message would look like this:
http://yourdomain.com/callback/server.php?messagetype=1&message=%3C%3 Fxml%20version%3D%271.0%27%20standalone%3D%27no%27%3F%3E%3C%21D OCTYPE%20cgCallback%20SYSTEM%20%27cgcallback.dtd%27%3E%3CcgCallbac k%3E%3CType%3ESALE%3C%2FType%3E%20%3CTransactionID%3E3%3C%2FT ransactionID%3E%0D%0A%20%20%3CTransactionReferenceID%3E1%3C%2FTran sactionReferenceID%3E%3COfferName%3EOFFER%3C%2FOfferName%3E%3COf ferId%3E221%3C%2FOfferId%3E%3CAmount%3E399%3C%2FAmount%3E%3CC urrency%3EEUR%3C%2FCurrency%3E%3CUserID%3Eusername%3C%2FUserID %3E%3CUserPW%3EaBgR3tg%3C%2FUserPW%3E%3CEmail%3Eemail%40email. com%3C%2FEmail%3E%3CIp%3E192.168.1.1%3C%2FIp%3E%3CCountryIso%3EE S%3C%2FCountryIso%3E%3CCardHolder%3EMax%20Mustermann%3C%2FCard Holder%3E%3CCustomerID%3E5%3C%2FCustomerID%3E%3CWebsiteID%3E6% 3C%2FWebsiteID%3E%3Cop1%3Eop1%3C%2Fop1%3E%3Cop2%3Eop2%3C%2Fo p2%3E%3Cop3%3Eop3%3C%2Fop3%3E%3CNMU%3E1%3C%2FNMU%3E%3C%2 FcgCallback%3E
Valid Callback Message Types
The following table shows the callback message types that can be passed from the CommerceGate server to your callback server:
Type
Description
SALE
User signup on the payment page. Grant him access to the members­area.
38
REBILL*
Successful membership renewal
UPSELL*
Sold Package to a registered member
REFUND*
Refund of a transaction, immediately remove user access.
CHARGEBACK*
Customer charged the money back at his bank. Immediately remove user­access. CANCELMEMBERSHIPNOTIFY*
The member requested to cancel his membership and stop rebilling at the end of the payment­period
CANCELMEMBERSHIP*
The requested membership­cancellation was processed. Remove user­access immediately.
Where there is an asterisk, the related transaction ID is specified in the message TransactionReferenceID field.
Callback Server Responses
Whenever a message has been sent from the CommerceGate server to your callback server, you callback server is expected to send back a message to the CommerceGate server to indicate the message was received and understood. This makes sure information is not lost in the process. There are two valid messages your callback server can send to the CommerceGate server:
Type
Success
Error
Simple
SUCCESS
ERROR
Extended
ERROR#<ERRCODE>#<ERRTEXT>
If the CommerceGate server does not receive a SUCCESS message back, then it will send an email to your technical contact (specified in the My Accounts section of the CommerceGate Back Office). The email will contain a copy of the message, allowing for correction and bug fixing, if necessary.
Note: It is critical that your server properly respond to a callback message from the 39
CommerceGate server or the transaction is cancelled automatically! If any response other than “success” is received by the CommerceGate server, the transaction is rolled back and cancelled.
Testing the Callback Server
You can test the functionality of you callback server while you are setting it up, as well as at any time, by logging in to your CommerceGate Back Office. Create some No Money Users (NMUs) inside the Members Management option. Your NMU can then login to your Website and begin a transaction. While no money will be charged, the callback message will be generated from the CommerceGate server and sent to your Callback server, which should show the transaction properly.
40
Using the Commerce Gate API
Note: To use the API functions, you will need an API password. This password is different from your normal back­office login password. You must ask Commerce Gate support to generate and send you the API password for your account.
Cancellation Messages API
If you provide a cancellation ability on your Website (instead of redirecting the user to the CommerceGate server to cancel a membership) you need to have your callback server send a message to the CommerceGate server. To do this, you send a message to this URL:
https://secure.commercegate.com/api/customer/cancel_membership.php
with the following parameters in the message:
Parameter
Description
Mandatory
username
The username to login to the Back office
password
The password to log into the API (not the same as the Back Office yes
password)
website_id
ID of the website the enduser wants to unsubscribe from
yes
website_username
The username (as registered with CG) of the enduser
yes
yes
A sample message from your callback server to the CommerceGate server would be:
https://secure.commercegate.com/api/customer/cancel_membership.php?username=0001&pass
word=xYthDxm3&website_id=1&website_username=user1
Note that the CommerceGate payment page will accept traffic only from your registered Website (configure your sites in “My Websites”).
Note: As the API can only be accessed from your web server and contains the API password, this cannot be a direct link on your website. The call must be made from a script running on your web server. A sample script, to provide a cancel membership link on your website, is given in an Appendix.
Retrieving Transactions Using the API
You can see all the transactions on your account at any time by going to the CommerceGate 41
Back Office and clicking on the Transactions link. You can also retrieve transactions directly from CommerceGate using an API (application programming interface). This is useful if you want to maintain a transaction record on your server or if you want to have a continuous real­time stream of transaction information. Also, there is more detailed information, for each transaction, than is delivered in the callbacks.
To retrieve transactions from the CommerceGate server, use the following URL:
https://secure.commercegate.com/api/customer/get_transactions.php
A login and password is required to access the API server. The login and password for the API server are not the same as your CommerceGate Back Office information. To obtain information from the API, contact CommerceGate and request access.
The following parameters can be sent to the CommerceGate server to narrow the list of the transactions that are to be returned to your callback server:
Parameter
Description
Mandatory
Default
mode
Format of the export: xml,csv
No
xml
username
Customer­ID
yes
password
Password
yes
startdate
DD­MM­YYYY
For example: 13­01­2005
yes
enddate
DD­MM­YYYY
For example: 13­02­2005
yes
website_id
Id of one of your websited
no
offer_id
Id of one of your offers
no
currency
ISO of currency: EUR
No
email
Filter­email­address
no
user_name
Filter user_name
no
get_failed
Get failed transactions:
No
1
get_successful
Get successful transactions:
No
1
op1
Filter Optional parameter 1
No
op2
Filter Optional parameter 2
No
op3
Filter Optional parameter 3
No
header
For csv­format: display header
No
0
42
In order to narrow the results of your transaction query down, you can instruct the CommerceGate server to filter the transactions sent to you. The following filters can be applied to the transactions:
Parameter Adv.Filter­
Example
Description
Param.
email
email_like=1
email=guy@% &email_like=1
Will return every transaction with an email address starting with “guy@”
user_name user_name_like=1 user_name=%dude Will return every transaction with a &user_name_like=1
user_name ending with “dude”
op1 .. op3 op1_like=1
op1=45­453% &op1_like=1 Will return every transaction with optional parameter1 starting with “45­
453”
Transaction Message Format
The following table shows the fields that are included in a transaction record returned from the CommerceGate server to your callback server when queried for a transaction:
Name
Type
Description
Status
String
Successful or failed
Cancelled
Integer
1 = the preauth has been cancelled, default=0
Payed
Integer
1 = the preauth has been payed, default=0
Refunded
Integer
1 = transaction was refunded, default=0
Chargedback
Integer
1 = transaction was chargedback, default=0
Reason
String
Reason for a refund or preauthcancel
Op1
String
Optional parameter 1
Op2
String
Optional parameter 2
Op3
String
Optional parameter 3
Type
Integer
See Appendix: Transaction­Types
Id
Integer
Transaction­ID
Refid
Integer
Related transaction­id
Date
Date
YYYY/MM/DD HH:MI:SS
Timestamp
Integer
Unix­timestamp
Ip
String
IP­Address of the customer
Amount
Integer
Amount in cents
43
Currency
String
See Appendix: Currencies
Website_id
Integer
Id of the website
User.name
String
Username
User.password
String
User/firstname
String
User/lastname
String
User/email
String
User/Address/Street
String
User/Address/Zip
String
User/Address/City
String
User/Address/Country
String
User/Address/State
String
Error/Code
Integer
Error­Number
Error/Text
String
Error­Message
Provided street address
Country­ISO­Code of the Customer
The message from the CommerceGate server will be in one of two formats, depending on whether you use string (ID=0) or XML (ID=1) formats. The format of a string message (ID=0) is:
Status,cancelled,payed,refunded,chargedback,reason,op1,op2,op3,type,id,refid,date,timestamp,i
p,amount,currency,websiteid,username,userpassword,firstname,lastna me,email,street,zip,city,country,state,errcode,errtext
A sample message shows the use of strings for transaction updates:
"successful",0,0,0,0, "","op1","op2","op3",0,111766,,2006/02/17 10:58:57,1143578277,192.168.1.1,399,EUR,1,"user12","b9jTtBie","carl",
"miller","[email protected]","","","","ES ","","",""
A sample XML return of transactions will look like this:
<?xml version='1.0' standalone='yes'?>
<cgTransactionList>
<cgTransactionItem status='successful' cancelled='0' payed='0' refunded='0' chargedback='0' reason='' op1='' op2='' op3='' type='0' id='116' refid='' date='2006/02/17 10:58:57' timestamp='1140170337' ip='192.168.1.1' amount='399' currency='EUR' website_id='1'>
<User name='user12' password='b9jTtBie'>
<firstname>carl</firstname>
<lastname>miller</lastname>
<email>[email protected]</email>
44
</User>
<Error>
<Address>
<Street></Street>
<Zip></Zip>
<City></City>
<Country>ES</Country>
<State></State>
</Address>
<Code></Code>
<Text></Text>
</Error>
</cgTransactionItem>
</cgTransactionList>
45
The CC Form
When a customer is redirected to the CommerceGate server to process a payment, they are directed to a page that looks like this:
The packages that are available to the customer are displayed at the top of the page, with radio buttons that allow the customer to choose the offer they want. Beneath the package information is the billing section. The customer needs to complete this information to allow CommerceGate to process their credit card payment. You can customize the look of the credit card form, adding your site logo or name, using My Websites options.
Testing Credit Cards
To test credit card transactions and callbacks properly, use testing card numbers supplied by CommerceGate. On your test server, follow the links to the payment page (ccform.php). A few general notes about testing credit card processing:
46
•Use a different email address for each test to prevent conflicts
•For the user’s name, use any string (it does not have to be unique)
•For the credit card number, use a different number for each test (using the same number will cause a conflict)
•For the CVV, use any three digits
•For expiration dates, ensure they are later than the current month and year (or the transaction will be rejected prior to processing)
•Complete each test in a different browser session (close the browser and start it again to prevent issues with the browser cache)
If the credit card test is processed successfully, a SUCCESS callback will be generated. You can also see each transaction attempted in the Back Office, under Statistics. This will show you all information about the transaction.
After verifying the test transaction, cancel it in your Back Office to avoid rebills.
Note: Try to avoid making a lot of tests in short succession. If many similar transactions are rreceived from the same IP, the Commerce Gate automatic fraud system or the bank system may become suspicious and block further transactions. If the bank blocks your IP, it can take some time to unblock it. This blocking can occur even with test cards in test mode.
NATS / MPA3
Some information about using NATS and MPA3 can be found here:
NATS: http://knowledgebase.toomuchmedia.com/idx/0/593/article/Commerce_Gate_Setup_Instructions.
html
MPA3: http://support.hostmansion.com/mpa3/help/manual.php?topic=settings/proc­
commercegate; use the username “customer” and the password “welcome12”
NATS and MPA3 are 3rd party affiliation systems. These systems are not in any way affiliated with Commerce Gate, they are completely separate companies. However, both companies provide a way to send billing traffic to one or more payment providers, in a ‘cascade’.
Integrating your website, with MPA3 or NATS, and Commerce Gate is obviously more complicated than simply linking directly from your website to Commerce Gate.
Your payment link will need to link to MPA3 or NATS. The configuration you have made in their 47
system, will then ‘redirect’ it to the Commerce Gate payment form.
Similarly, for callbacks, you cannot simply use the standard Commerce Gate callback scripts. MPA3 and NATS provide their own versions of callback scripts, for Commerce Gate, which allow the payments to be linked back both to your web server and the the MPA3 or NATS system.
Integration
As explained at the start of this document, there are a number of steps that must be followed for your Website to use CommerceGate to process payments. The table below shows a summary of the steps required. For more information on these steps, see the relevant section of this Guide.
Step Step Name
Description
Responsibility
1
Signup
Customer
2
3
Initial Check
Staff assign­
ment
Back Office Access
User completes form at www.commercegate.com or www.paytruth.com
Salesman agrees to authorize the account
Assigned to Salesperson
Sales gives Customer access to Back Office
Salesperson
Customer creates his offers and packages in the Back Office
Customer
Customer completes the technical data page in the Back Office
Website goes into the pending list
Customer
Customer provides Commerce Gate an account to access the member content of their website
Approval of UIRL, content, pricing, Visa and Mas­
terCard rules, etc.
Site removed from pending. Goes to test pro­
cessing account.
Customer provides FTP access to allow Com­
merce Gate toinstall the callback scripts on their server OR the customer installs thecallback scripts themselves
Supply test credit cards to customer
Customer
4
5
6
7
8
9
10
11a
13
Create Web­
sites, Offers and Pack­
ages
Technical Data
Pending Websites
Compliance Access
Compliance
Test Pro­
cessing
FTP Access or Customer
Test credit cards
Salesperson
Salesperson
Automatic
Compliance
Automatic
Customer or In­
tegrator
Integrator
48
14
Testing
Test that integration works fully
15
16
Live Provider
First Live Transaction
First Invoice
Switch client to real processing account
The first real (successful) transaction is made by an end­user
The first invoice is generated 4 weeks after the first live transaction
When the customer has received sufficient sales on the Websites to cross the threshold and 4 weeks have passed, the first invoice to be paid is generated. The customer is paid the following Tuesday.
17
18
First Pay­
ment to Cus­
tomer
Customer / Inte­
grator
Integrator
End­User
Time
Txn Volume
49
FAQ
•Will my CommerceGate password expire?
oYes, all CommerceGate password are valid for a limited time. When your password expires, you will be prompted automatically to change the password when you log in. This will also happen the first time your account is created so you do not continue to use the temporary password created for you. Passwords must be strong, consisting of upper and lower case letters and numbers.
•When I finish my session on the CommerceGate server do I need to log out even if I close my browser?
oYes, you should use the Logout button at the top right of the CommerceGate page. This is because some browsers will retain session information and someone else could start your browser and have access to your account without your knowledge. It is best to get in the habit of always logging out when you finish your CommerceGate session.
•What are callbacks?
oCallbacks are messages sent from one server to another. When a transaction is completed on the CommerceGate server, a message is sent to your Website server with information about the transaction. Other callback messages can be sent, too. •What are the callback message types?
oThere are two types of callback messages: string and XML. String messages are simply long sets of characters with information separated by commas. XML messages have a formal structure. Of the two, XML messages are preferable because they reduce the likelihood of errors.
•What happens if a callback message is not confirmed?
oTransactions will be cancelled if a callback message is not confirmed by your server. Therefore, it is critical that your server properly handle callbacks.
•I see that in Payment Page the purchase is processed correctly, but in my BO I don't see any transaction. Why?
oCheck the parameters that are sent to the payment page, including size of password (which could be too long).
•What happen if my Website is on the test server and a user buys something and makes a transaction?
oThe transaction is processed as usual (as if it was not on the test server), and the payment through credit card is completed but this payment will not appear as a transaction on the customer invoice (no money is given to the webmaster and he will not be paid for this transaction).
•Can a user do a refund?
oNo, the user cannot do refund. A refund can only be done by CommerceGate or the webmaster.
•How can I delete a membership? Can I clear it directly from my database?
50
oYou can delete a membership from the BO, refunding a user’s transaction (click on refund). Once you’ve refunded a user, the membership is deleted. Another way to delete a membership is have the user call our support service or go directly to our support web site (www.cgbilling.com). In all these cases the callback server will receive a callback of type REFUND. When you receive this callback, you can be sure that the user was removed from our system. At this point you can remove the membership from your database.
•When the user tries to open the Credit Card form, an error message saying "not allowed" is displayed, why?
oA new window cannot be opened for the Credit Card form using JavaScript. When the form is open, our system is looking for a referrer but JavaScript doesn't send a referrer. To avoid this problem you should use a normal link or be sure that the referrer is sent properly.
For example:
­­­­
<input name="Button" value="OPEN PAY WINDOW"
onclick="window.open('https://secure.commercegate.com/payment/ccform.php?c
id=12181&wid=5782');"
type="button">
</body
­­­­
Also certain [less popular] web browsers do not send the ‘referer’ information.
•What are the step involved in a purchase from a user’s point of view?
oWhen a user open our payment page, he has to complete the form with his data. Once the process button is pressed, and the system checks that everything is completed properly, the user will receive an e­mail that contains a confirmation link and the username/password for the Website..
51
Support Information When you contact CommerceGate, be sure to include your customers ID number. Without this number, your queries cannot be properly handled, delaying replies.
Customer Support Hours: 24 hours a day, 7 days a week, 365 days a year
Customer Support Phone (Local charges apply):
USA (NY) 212 796 0771
U.K. 02 07 099 5410
France 01 76 60 73 11
Spain 902 010 237
Germ. 0891 214 09 179
Nederl. 02 08 908 062
Italy 069 926 8077
Switz. 02 25 330 195
Luxem. 202 02 458
Belgium 02 74 70 359
Customer Support Fax: +34 93 600 23 08
Customer Support email: client­[email protected]
52
Appendix 1: Callback Information
The section on Callbacks earlier in this User Guide lists the parameters available for messages. These are summarized again here for quick reference, along with some additional expansion on valid fields.
Callback Message Formats
String callbacks (ID = 0):
http://yourdomain.com/callback/server.php?messagetype=0&
message=SALE%233%231%23OFFER%23221%23399%23EUR%23username%23aB
gR3tg%23email%40email.com%23192.168.1.1%23ES%23Max%20Mustermann%235
%236%23op1%23op2%23op3%231%23
XML callbacks (ID=1):
<?xml version='1.0' standalone='no'?>
<!DOCTYPE cgCallback SYSTEM 'cgcallback.dtd'>
<cgCallback>
<Type>SALE</Type> <TransactionID>3</TransactionID> <TransactionReferenceID>1</TransactionReferenceID> <OfferName>OFFER</OfferName> <OfferId>221</OfferId>
<Amount>399</Amount> <Currency>EUR</Currency> <UserID>username</UserID> <UserPW>aBgR3tg</UserPW> <Email>[email protected]</Email> <Ip>192.168.1.1</Ip> <CountryIso>ES</CountryIso> <CardHolder>Max Mustermann</CardHolder> <CustomerID>5</CustomerID> <WebsiteID>6</WebsiteID> <op1>op1</op1>
<op2>op2</op2> <op3>op3</op3> <NMU>1</NMU>
</cgCallback>
53
Callback Parameters
Parameter
Type
Description
Length
Type
String
Callback­Type (See Callback­Types)
32
TransactionID
Integer
Unique transaction­id
38
TransactionReferenceID
Integer
Related transaction­id
38
OfferName
String
Name of the offer
80
OfferId
Integer
Unique­Id of the offer
10
Amount
Integer
Amount in cents
20
Currency
String
ISO­Code, see Appendix Currencies
4
UserID
String
Username of the member
40
UserPW
String
Password of the member
40
Email
String
Provided email­address
50
Ip
String
Ip­Address of the enduser
CountryIso
String
ISO­Code of the Country, see
Appendix Country­Codes
3
CardHolder
String
Provided Cardholder name
128
CustomerID
Integer
Your customer­id
10
WebsiteID
Integer
The website­id the user has
registered on
10
Op1
String
Optional­parameter
60
Op2
String
Optional­parameter
60
Op3
String
Optional­parameter
60
NMU
Integer
No­Money­User, can be 0 or 1,
Can be used to test the callback
server or to create VIP­Users
1
Callback Message Types
54
Type
Description
SALE
User signup on the payment page. Grant him
access to the members­area.
REBILL*
Successful membership renewal
UPSELL*
Sold Package to a registered member
PREAUTH
Preauthorization of a transaction
PREAUTHPAY*
Payment of a preauthorized transaction
PREAUTHCANCEL*
Cancellation of a preauthorized transaction
REFUND*
Refund of a transaction, immediately remove user
access.
CHARGEBACK*
Customer charged the money back at his bank.
Immediately remove user­access.
The member requested to cancel his membership
and stop rebilling at the end of the payment­period
CANCELMEMBERSHIPNOTIFY*
The requested membership­cancellation was
processed. Remove user­access immediately.
CANCELMEMBERSHIP*
Callback Server Responses
Type
Success
Error
Simple
SUCCESS
ERROR
Extended
ERROR#<ERRCODE>#<ERRTEXT>
Currency Parameter Valid Values
Currency
ISO­Code
Euro
EUR
US Dollar
USD
Great Britain Pound
GBP
Japanese Yen
YEN
55
Swedish Krona
SEK
Norwegian Krone
NOK
Danish Krone
DKK
Canadian Dollar
CAD
Country Information
This information is correct at the time of print, but can be updated at any time.
Default Currency Currency Country Name ISO Status Afghanistan AF Not accepted USD USD
Aland Islands AX Not accepted USD USD
Albania AL Not accepted EUR USD
Algeria DZ Not accepted USD USD
American Samoa AS Not accepted USD USD
Andorra AD Accepted EUR USD
Angola AO Not accepted USD USD
Anguilla AI Not accepted USD USD
Antarctica AQ Not accepted USD USD
Antigua And Barbuda AG Not accepted USD USD
Argentina AR Not accepted EUR EUR
Armenia AM Not accepted USD USD
Aruba AW Not accepted USD USD
Australia AU Accepted USD USD
Austria AT Accepted EUR EUR
Azerbaijan AZ Not accepted USD USD
Bahamas BS Accepted USD USD
Bahrain BH Not accepted USD USD
Bangladesh BD Not accepted USD USD
Barbados BB Not accepted USD USD
Belarus BY Accepted EUR USD
Belgium BE Accepted EUR EUR
Belize BZ Accepted USD USD
Benin BJ Not accepted USD USD
Bermuda BM Not accepted USD USD
56
Bhutan BT Not accepted USD USD
Bolivia BO Not accepted USD USD
Bosnia Herzegowina BA Not accepted EUR USD
Botswana BW Not accepted USD USD
Bouvet Island BV Not accepted USD USD
Brazil BR Not accepted USD USD
British Indian Ocean Territory IO Not accepted USD USD
Brunei Darussalam BN Not accepted USD USD
Bulgaria BG Accepted EUR USD
Burkina Faso BF Not accepted USD USD
Burundi BI Not accepted USD USD
Cambodia KH Not accepted USD USD
Cameroon CM Not accepted USD USD
Canada CA Accepted CAD USD
Cape verde CV Not accepted EUR EUR
Cayman Islands KY Accepted USD USD
Central African Rep. CF Not accepted USD USD
Chad TD Not accepted USD USD
Chile CL Not accepted USD USD
China CN Not accepted USD USD
Christmas Island CX Not accepted USD USD
Cocos Islands CC Not accepted USD USD
Colombia CO Not accepted USD USD
Comoros KM Not accepted USD USD
Congo CG Not accepted USD USD
Congo, The Democratic Republic of CD Not accepted USD USD
Cook Island CK Not accepted USD USD
Costa Rica CR Not accepted USD USD
Cote d`Ivoire CI Not accepted USD USD
Croatia HR Accepted EUR USD
Cuba CU Not accepted USD USD
Cyprus CY Accepted USD USD
Czech Republic CZ Accepted EUR USD
Denmark DK Accepted DKK EUR
Djibouti DJ Not accepted USD USD
Dominica DM Not accepted USD USD
Dominican Republic DO Not accepted USD USD
East Timor TL Not accepted USD USD
57
Ecuador EC Not accepted USD USD
Egypt EG Not accepted USD USD
El Salvador SV Not accepted USD USD
Equatorial Guinea GQ Not accepted USD USD
Eritrea ER Not accepted USD USD
Estonia EE Accepted EUR USD
Ethiopia ET Not accepted USD USD
Falkland Islands FK Not accepted USD USD
Faroe Islands FO Accepted EUR USD
Fiji FJ Not accepted USD USD
Finland FI Accepted EUR EUR
France FR Accepted EUR EUR
French Guiana GF Not accepted USD USD
French Polynesia PF Accepted USD USD
French Southern Territories TF Not accepted USD USD
Gabon GA Not accepted USD USD
Gambia GM Not accepted USD USD
Georgia GE Not accepted USD USD
Germany DE Accepted EUR EUR
Ghana GH Not accepted USD USD
Gibraltar GI Accepted USD USD
Greece GR Accepted EUR EUR
Greenland GL Accepted USD USD
Grenada GD Not accepted USD USD
Guadeloupe GP Not accepted USD USD
Guam GU Not accepted USD USD
Guatemala GT Not accepted USD USD
Guernsey GG Not accepted USD USD
Guinea GN Not accepted USD USD
Guinea­bissau GW Not accepted USD USD
Guyana GY Not accepted USD USD
Haiti HT Not accepted USD USD
Heard Island and McDonald Islands HM Not accepted USD USD
Honduras HN Not accepted USD USD
Hong Kong HK Accepted USD USD
Hungary HU Accepted EUR USD
Iceland IS Accepted USD USD
India IN Not accepted USD USD
58
Indonesia ID Not accepted USD USD
Iran, Islamic Republic of IR Not accepted USD USD
Iraq IQ Not accepted USD USD
Ireland IE Accepted EUR EUR
Isle of Man IM Not accepted USD USD
Israel IL Accepted USD USD
Italy IT Accepted EUR EUR
Jamaica JM Not accepted USD USD
Japan JP Accepted JPY USD
Jersey JE Not accepted USD USD
Jordan JO Not accepted USD USD
Kazakhstan KZ Not accepted USD USD
Kenya KE Not accepted USD USD
Kiribati KI Not accepted USD USD
Korea, Democratic People`s Republic of KP Not accepted USD USD
Korea, Republic of KR Not accepted USD USD
Kuwait KW Accepted USD USD
Kyrgyzstan KG Not accepted USD USD
Lao People`s Democratic Republic LA Not accepted USD USD
Latvia LV Not accepted USD USD
Lebanon LB Not accepted USD USD
Lesotho LS Not accepted USD USD
Liberia LR Not accepted USD USD
Libyan Arab Jamahiriya LY Not accepted USD USD
Liechtenstein LI Accepted EUR EUR
Lithuania LT Not accepted USD USD
Luxembourg LU Accepted EUR EUR
Macau MO Not accepted USD USD
Macedonia MK Not accepted USD USD
Madagascar MG Not accepted USD USD
Malawi MW Not accepted USD USD
Malaysia MY Not accepted USD USD
Maldives MV Not accepted USD USD
Mali ML Not accepted USD USD
Malta MT Accepted USD USD
Marshall Islands MH Not accepted USD USD
Martinique MQ Accepted USD USD
Mauritania MR Not accepted USD USD
59
Mauritius MU Not accepted USD USD
Mayotte YT Not accepted USD USD
Mexico MX Not accepted USD USD
Micronesia FM Not accepted USD USD
Moldova MD Not accepted USD USD
Monaco MC Accepted EUR EUR
Mongolia MN Not accepted USD USD
Montenegro ME Not accepted USD USD
Montserrat MS Not accepted USD USD
Morocco MA Not accepted USD USD
Mozambique MZ Not accepted USD USD
Myanmar MM Not accepted USD USD
Namibia NA Not accepted USD USD
Nauru NR Not accepted USD USD
Nepal NP Not accepted USD USD
Netherlands NL Accepted EUR EUR
Netherlands Antilles AN Accepted USD USD
New Caledonia NC Accepted USD USD
New Zealand NZ Accepted USD USD
Nicaragua NI Not accepted USD USD
Niger NE Not accepted USD USD
Nigeria NG Not accepted USD USD
Niue NU Not accepted USD USD
Norfolk Island NF Not accepted USD USD
Northern Mariana Islands MP Not accepted USD USD
Norway NO Accepted NOK EUR
Oman OM Not accepted USD USD
Pakistan PK Not accepted USD USD
Palau PW Not accepted USD USD
Palestinian Territory, occupied PS Not accepted USD USD
Panama PA Not accepted USD USD
Papua New Guinea PG Not accepted USD USD
Paraguay PY Not accepted USD USD
Peru PE Not accepted USD USD
Philippines PH Not accepted USD USD
Pitcairn PN Not accepted USD USD
Poland PL Not accepted USD USD
Portugal PT Accepted EUR
EUR 60
Puerto Rico PR Not accepted USD USD
Qatar QA Not accepted USD USD
Reunion RE Accepted USD USD
Romania RO Not accepted EUR USD
Russian Federation RU Not accepted EUR EUR
Rwanda RW Not accepted USD USD
Saint Kitts And Nevis KN Not accepted USD USD
Saint Lucia LC Not accepted USD USD
Samoa WS Not accepted USD USD
San Marino SM Not accepted EUR USD
Sao Tome And Principe ST Not accepted USD USD
Saudi Arabia SA Not accepted USD USD
Senegal SN Not accepted USD USD
Serbia RS Not accepted USD USD
Seychelles SC Not accepted USD USD
Sierra Leone SL Not accepted USD USD
Singapore SG Accepted USD USD
Slovakia SK Accepted EUR USD
Slovenia SI Accepted EUR USD
Solomon Islands SB Not accepted USD USD
Somalia SO Not accepted USD USD
South Africa ZA Accepted USD USD
South Georgia and the South Sandwich Islands GS Not accepted USD USD
Spain ES Accepted EUR EUR
Sri Lanka LK Not accepted USD USD
St. Helena SH Not accepted USD USD
St. Pierre and Miquelon PM Not accepted USD USD
St. Vincent & The Gren. VC Not accepted USD USD
Sudan SD Not accepted USD USD
Suriname SR Not accepted USD USD
Svalbard & Jan Mayen SJ Not accepted USD USD
Swaziland SZ Not accepted USD USD
Sweden SE Accepted SEK EUR
Switzerland CH Accepted EUR USD
Syrian Arab Republic SY Not accepted USD USD
Taiwan, Province of China TW Not accepted USD USD
Tajikistan TJ Not accepted USD USD
Tanzania TZ Not accepted USD USD
61
Thailand TH Not accepted USD USD
Togo TG Not accepted USD USD
Tokelau TK Not accepted USD USD
Tonga TO Not accepted USD USD
Trinidad And Tobago TT Not accepted USD USD
Tunisia TN Not accepted USD USD
Turkey TR Accepted USD USD
Turkmenistan TM Not accepted USD USD
Turks & Caicos Isl. TC Not accepted USD USD
Tuvalu TV Not accepted USD USD
Uganda UG Not accepted USD USD
Ukraine UA Not accepted EUR USD
United Arab Emirates AE Not accepted USD USD
United Kingdom GB Accepted GBP EUR
United States US Accepted USD USD
United States Minor Outlying Islands UM Not accepted USD USD
Uruguay UY Not accepted USD USD
Uzbekistan UZ Not accepted USD USD
Vanuatu VU Not accepted USD USD
Vatican City State VA Not accepted EUR USD
Venezuela VE Not accepted USD USD
Viet Nam VN Not accepted USD USD
Virgin Islands (uk) VG Not accepted USD USD
Virgin Islands (us) VI Not accepted USD USD
Wallis & Futuna Isl. WF Accepted USD USD
Western Sahara EH Not accepted USD USD
Yemen YE Not accepted USD USD
Zambia ZM Not accepted USD USD
Zimbabwe ZW Not accepted USD USD
62
Server Callback Script The script below is written in PHP and gives the correct structure for a callback server. However, this script does not perform any actual, useful activity and needs customization before it will run properly on your server.
A version of this script – configured to provide membership authentication access, using the Apache .htpasswd file, is available from Commerce Gate on request or can be downloaded from the Back­Office ‘Documentation Centre’.
<?PHP
/*
CommerceGate System use GET Method, it means the callback are send encoded ( urlencoded )
.
If the callback­server file are build with PHP language it will be automatically decoded.
In the case that you are using other lenguage instead of PHP, find the appropriate function to de­
code this url generated
by CG
*/
// This simple example only received the information send by CG system and write it in a log file.
// You should extract the information from this XML and use it in functions
$rcv_callback_msg = $_REQUEST;
$Handle = fopen("rcv_callback_msg.log", 'a'); fwrite($Handle, var_export($rcv_callback_msg,true));
fclose($Handle);
/*
Depending what you set in CommerceGate BO you can receive 2 callback­types, XML (Default) or String
XML ( 'messagetype' => '1' )
String ( 'messagetype' => '0' )
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
Example in XML callback­type:
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
array (
'messagetype' => '1',
'message' => '<?xml version=\'1.0\' standalone=\'no\'?><!DOCTYPE cgCallback SYSTEM
\'cgcallback.dtd\'><cgCallback><TransactionType>SALE</TransactionType><Type>SALE</Type
><TransactionID>2089
093</TransactionID><TransactionReferenceID></TransactionReferenceID><OfferName>test</O
fferName><OfferId>123
63
4</OfferId><Amount>1000</Amount><Currency>EUR</Currency><UserID>C1fDpU8</UserID><
UserPW>ozCLJsR7</
UserPW><Email>[email protected]</Email><Ip>200.10.21.12</Ip><CountryIso>ES</Country­
Iso><CardHolder>test</C
ardHolder><CustomerID>12324</CustomerID><WebsiteID>123</WebsiteID><op1>1234</op1>
<op2></op2><op3></o
p3><NMU></NMU></cgCallback>',)
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
Example in String Callback­type:
­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
array (
'messagetype' => '0',
'message' =>
'SALE#2089008##test#1234#1000#EUR#fXFxqv7#y1qNf7jm#[email protected]#200.10.21.
12#ES#test#1281#521
#134####', )
*/
/**
* @param $username
* @param $password
* @return boolean
*/
function addUser($username,$password){
// your code here
// add your user information here to your authentication­system ( DB­Authentication or simple .htaccess )
// Example to log add users
$Handle = fopen("adduser.log", 'a'); fwrite($Handle, "Add user $username,$password\n\r\n"); fclose($Handle);
}
/**
* @param $username
* @param $password
* @return boolean
*/
function removeUser($username,$password){
// your code here
// remove your user information here from your authentication­system ( DB­Authentication or sim­
ple .htaccess )
// Example to log remove users
$Handle = fopen("removeuser.log", 'a'); fwrite($Handle, "Delete user $username,$password\n\r\n");
64
fclose($Handle);
}
/**
* After your callback­server has processed the callback­message. it should return a message to the commercegategateway
depending of the status
* If All operation done with success, you just print the word "SUCCESS"
* Otherwise if something any step failed, you should print the word "ERROR" or "ERROR#<ER­
RCODE>#<ERRTEXT>".
ERRCODE ­ your code error number give by you and
* ERRTEXT ­ Text given by you related to the code error (ERRCODE)
*/
// This is just an simplified example, that depends also the result from the other function
// In this case we consider that all was processed correctly
$allsuccess = true;
if($allsuccess){
echo "SUCCESS";
}else{
echo "ERROR";
// Example to log the error's
$Handle = fopen("error.log", 'a'); fwrite($Handle, "[".time()."] ERROR generated\n\r\n"); fclose($Handle);
}
?>
65
Cancel Membership Sample Script 66