The logic of the flow in this integration is quite simple -

Step 1: Any Customer/Sub-Reseller of yours needs to pay you money and selects a Payment Gateway to do so.

Step 2: We simply create a collection of messages that you will need to charge this Customer/Sub-Reseller. This set of messages would contain things like Order Information, Amount etc. We then redirect the Customer to YOUR Server with this set of messages.

Step 3: You then charge the Customer/Sub-Reseller using these messages, and your Payment Gateway.

Step 4: You then redirect the Customer BACK to our Server with a status of the transaction as to whether you have successfully charged the Customer/Sub-Reseller.

Step 5: Once this is done we Add these funds to the Customer/Sub-Reseller account, and/or process any associated Orders.

This interaction can be diagrammatically represented as follows -

Let us break down the process you need to carry out in order to complete integrating your Payment Gateway with our system

You will need the following before you begin integrating your Payment Gateway with the System

• Details on the process of integrating with your Payment Gateway

• Server space on your server

• Download the appropriate integration kit from the below list depending on what your Server supports for the integration

  • ASP Integration Kit version 3.0 (last updated on 10th March, 2008)

  • JSP Integration Kit version 3.0 (last updated on 10th March, 2008)

  • PHP Integration Kit version 3.0 (last updated on 10th March, 2008)
     

Next you need to Add your Payment Gateway to our system

You can Add or Modify your current/preferred Payment Gateway within your Reseller account by following the steps given below:

1. Login into your Reseller Control Panel from http://cp.us2.net/reseller

2. Go to  Settings -> Finance and Billing ->  Payment Gateway -> List / Add

3. Click on the Add Payment Gateway button and then on the Add any other Payment Gateway link.

4. Enter the following Details and save your changes by clicking on Submit.

• Gateway Name - This is the heading for your Payment Gateway and it will be displayed to your Customers/Sub-Resellers on the Payment page within a dropdown of options. A typical heading could be VISA/MasterCard/AMEX in order to signify that your Customer/Sub-Reseller can pay using those modes if they select this particular option.
   

• Gateway URL - This is the URL on your server to which we will redirect the Customer/Sub-Reseller. This is explained in detail further ahead. Currently simply fill in some URL. We will change this later to the correct URL.
   

• Payment Gateway Access Level for Customers and Sub-Resellers - Click here to know more about Payment Gateway Transaction types and Access Levels for your Customers and Sub-Resellers >>
   

• Send me a Reminder if a transaction is pending for more than x days - In case you have not yet accepted a payment sent to you via this Payment Gateway, you can get e-mail reminders sent across to you from our system, after every x number of days, until you either Approve or Decline these payments. Click here to know how to Approve / Decline Payment Gateway transactions >>
   

• Display Position - If you plan on adding Multiple Gateways you can select the position in which you wish to display this Gateway on your Payment Page.
   

• Checksum Algorithm - Select MD5 if you have downloaded the latest Integration Kit (version 2 or above) or have followed the upgrade instructions listed in step [i]. Select Addler 32 only if you are still using an older kit and haven't yet upgraded.
   

On your own Server upload the corresponding files from the integration kit you downloaded. We will use the PHP Kit as an example in this document. You will typically have the following files

paymentpage.php - This is the page that we will redirect your Customer/Sub-Reseller to. From this page you need to collect the data we send and use the data to charge your Customer/Sub-Reseller. After you have charged the Customer/Sub-Reseller you will then redirect the Customer/Sub-Reseller to postpayment.php

postpayment.php - This page simply redirects your Customer back to our Server after you have charged him, with appropriate variables required by our Server

functions.php - This is just a functions file used by the other pages for certain calculations

Both the paymentpage.php and the postpayment.php pages contain a variable called KEY. For instance in the above two files you will find a line as follows

$key = "eF9dmG8288OFd9pzzTeHJ3mNvR26xN"; //replace ur 32 bit secure key , Get your secure key from your Reseller Control panel

You need to replace this value in both the files with the KEY we generated for you at the time of adding the Gateway. You can check it from the Settings -> Finance and Billing ->  Payment Gateway -> List / Add section by clicking on the Payment Gateway that you added

If at anytime you feel that you may have compromised the security of this Key, you can regenerate a new one from this section by clicking on the Generate Key button. You will then have to replace the New Key in your code.

You will now need to set the Gateway URL which we skipped earlier while adding the Gateway. The Gateway URL is the full http:// URL that will be used to access the paymentpage.php on your server. So a typical Gateway URL would look like "http://www.yourserver.com/paymentpage.php"

Visit the Settings -> Finance and Billing ->  Payment Gateway -> List / Add section and click on the Payment Gateway you added. Click on Modify and enter the Gateway URL as described above. Make sure the URL is entered complete with the "http://" or "https://" all the way up to the name of the page. DO NOT pass any Parameters to the URL

CORRECT GATEWAY URL
http://www.yourserver.com/paymentpage.php

WRONG GATEWAY URLS
www.yourserver.com/paymentpage.php
http://www.yourserver.com/paymentpage.php?someparam=something
 

You are now ready to test your integration and verify that it works. Follow the steps below to Test your Integration

1. Click on Settings -> Finance and Billing ->  Payment Gateway -> List / Add

2. Click on the Payment Gateway you added

3.  Click on Test for Add Funds or Test for Payment, depending upon the type of transaction you wish to test.

This will popup a new window redirect you to the Gateway URL you had specified passing it the following parameters in a POST request

Besides, we also pass the following details which allow you to pre-fill the Customer's / Sub-Reseller's details on the Payment Gateway page -

These variables can directly be accessed in the paymentpage.php. If all goes well, then on clicking the Test PG Integration button you should see the following output on your browser in a separate window

File: paymentpage.php
Checksum Verification ........ Verified
List of Variables Received as follows
paymenttypeid: 202
transid: 1120
userid: 1
usertype: Customer
transactiontype: CustomerAddFund
invoiceids:
debitnoteids:
description:
sellingcurrencyamount: 5
accountingcurrencyamount: 10
redirecturl: http://cp.us2.net/servlet/TestCustomPaymentAuthCompletedServlet
address1 = 213 Main St.
company = My Solutions
address2 = null
zip = 17541
name = Customer Name
city = NYC
telNoCc = 1
country = US
telNo = 45784126
emailAddr = customer@domain.com
address3 = null
state = NY
faxNoCc = null
faxNo = null
checksum: 8cd2a658d2de2c995fc790b66a508ec3

We will stop here right now. If you get the above output in your browser window then you have perfectly followed the steps so far.

If you get any of the following results instead then you can appropriately refer back to see if you have correctly set the following data:

If you do not get this output then you should revert back and check if you have properly inserted your key in the paymentpage.php file, and that the Gateway URL is properly set. Make sure you proceed ahead only after you get the above output for your specific integration kit.

Let us try and understand what we have achieved so far. Basically a set of parameters are passed from our Server to your Server, along with a checksum. If you open your corresponding paymentpage.php page you will see the following code in it

if(verifyChecksum($paymenttypeid, $transid, $userid, $usertype, $transactiontype, $sellingcurrencyamount, $accountingcurrencyamount, $key, $checksum))
{

 // YOUR CODE GOES HERE

}
else
{
    echo "ERROR: Checksum Mismatch";
}

Similar code will exist in the ASP and JSP integration kits. Your goal is to simply put your code inside the braces of the Verify Checksum. Within these braces you will put in code to register these variables in a session, or put them in your local database and then proceed ahead with charging your Customer

The VerifyChecksum function simply validates that the data you have received is valid and is sent by OUR SERVER. If the VerifyChecksum function fails then you MUST NOT proceed with the transaction.
 

You have now successfully achieved the integration steps up to sending the Customer/Sub-Reseller to YOUR Server. You now need to charge this Customer/Sub-Reseller. At this stage you have the list of variables that were passed to you in the paymentpage.php. It is recommended that you either store these variables in some local database of yours or store them in a session, before proceeding ahead, so that you can access these variable values at the time of sending the Customer/Sub-Reseller back after charging him. Storing these is explained in the previous section. After doing so you then must charge this Customer/Sub-Reseller. In doing so the following values are important for you

The above amounts are the amounts you need to charge your Customer/Sub-Reseller. If your Payment Gateway Currency is the same as any of the above you may freely use one of the above values. If on the other hand the Currency your Gateway uses is different you will need to put in code to convert the amount we send to the amount you wish to charge.

Once you have finished charging your Customer/Sub-Reseller you will need to then send the Customer/Sub-Reseller back to our Server along with the status of the transaction, in order to allow us to Add those Funds to his account and process any associated Orders.

You have now finished the steps required to charge your Customer/Sub-Reseller. You will then send the Customer/Sub-Reseller back to our Server. You will use the redirecturl parameter that was sent to your Gateway URL for this transaction to pass the Customer/Sub-Reseller back to our server.

You will pass the following parameters to the redirecturl in a POST request

The sample code for achieving the above process successfully is shown in the postpayment.php file. You simply need to copy this code in the file in which you do your Payment Processing. This page retrieves the transid and redirecturl from the session and expects a status to be available to it in the session. A simple inspection of the code in postpayment.php will give you an idea of the right way to redirect your Customer/Sub-Reseller to our server.

Explanation of sellingcurrencyamount and accountingcurrencyamount fields
In the above table two important fields are the sellingcurrencyamount and accountingcurrencyamount. These fields MUST be passed, but are used only if the transactiontype is 'CustomerAddFund' or 'ResellerAddFund' (Reference: Payment Gateway Transaction types and Access Levels for your Customers and Sub-Resellers >>). For every transaction performed through the Payment Gateway a Receipt is created in the Customer/Sub-Reseller account.

The amount of the Receipt created incase of transactiontype CustomerAddFund or ResellerAddFund is dependant on this figure. The Receipt amount will be equivalent to the figure you send us for both these values. The reason for allowing you to send us these values is to allow you to deduct any Credit Card Processing charges for Advance Payments made by your Customers/Sub-Resellers in their account.

Lets take an example of a Add Funds transaction performed by your Sub-Reseller

Sub-Reseller A
Your Selling Currency: USD
Your Accounting Currency: INR
Conversion Rate: 50
Amount to add in USD: 100
Amount to add in INR: 5000

When this Sub-Reseller leaves our system and comes to your paymentpage.php, we will send along the two amounts i.e. USD 100, INR 5000, to allow you to charge his card with an equivalent amount. After the transaction is completed, you will send the Sub-Reseller back to our system with a sellingcurrencyamount and accountingcurrencyamount figure. We will then credit THAT amount to his account. You may choose to send the same figures we sent to you, thus crediting the Sub-Reseller with the exact amount that was charged to him/her. Alternatively you may choose to deduct a certain processing amount for Credit Card Transactions and send a reduced amount. Thus you could have the below two scenarios

Scenario 1 - Values sent by your postpayment.php page
sellingcurrencyamount: USD 100
accountingcurrencyamount: INR 5000
In this scenario we sent you USD 100 and INR 5000, and you sent the same figures back. We will therefore credit the Sub-Reseller with the same amount

Scenario 2 - Values sent by your postpayment.php page
sellingcurrencyamount: USD 95
accountingcurrencyamount: INR 4750
In this scenario we sent you USD 100 and INR 5000, and you sent back USD 95 and INR 4750 (deducting 5% processing charges). We will therefore credit the Sub-Reseller with USD 95, INR 4750

Completing the Integration process using the postpayment.php page

We have a special built-in test mechanism for testing the interaction between the postpayment.php on your Server and our Server. The steps below assume you have finished all previous instructions until this step. Follow the steps below to test your integration further

1. Click on Settings -> Finance and Billing ->  Payment Gateway -> List / Add

2. Click on the Payment Gateway you added

3.  Click on Test For Add Fund or Test For Payment

This should result in a page as follows

File: paymentpage.php
Checksum Verification ........ Verified
List of Variables Received as follows
paymenttypeid: 202
transid: 1120
userid: 1
usertype: Customer
transactiontype: CustomerAddFund
invoiceids:
debitnoteids:
description:
sellingcurrencyamount: 5
accountingcurrencyamount: 10
redirecturl: http://cp.us2.net/servlet/TestCustomPaymentAuthCompletedServlet
address1 = 213 Main St.
company = My Solutions
address2 = null
zip = 17541
name = Customer Name
city = NYC
telNoCc = 1
country = US
telNo = 45784126
emailAddr = customer@domain.com
address3 = null
state = NY
faxNoCc = null
faxNo = null
checksum: 8cd2a658d2de2c995fc790b66a508ec3

Clicking on any of the above button submits to the same page where the value of status is set in the session and then you are redirected to postpayment.php, and you should see the below display

File: postpayment.php
redirecturl: http://cp.us2.net/servlet/TestCustomPaymentAuthCompletedServlet
List of Variables to send back
transid: 1120
status: Y
rkey: 32423
checksum: 8cd2a658d2de2c995fc790b66a508ec3

Clicking on this button will redirect you to our Server and you should see the following display on our Server

Checksum Verification ........ Verified
List of Variables Received as follows
transid: 1120
status: Y
rkey: 32423
checksum: 8cd2a658d2de2c995fc790b66a508ec3

If you see the above display this means that your integration is complete. You simply now need to modify the files and put in your own code to charge your Customer/Sub-Reseller.

If you get any of the following results instead then you can appropriately refer back to see if you have correctly set the following data:

If you do not get this output then you should revert back and check if you have properly inserted your key in the postpayment.php file. Make sure you proceed ahead only after you get the above output for your specific integration kit.

We have completed the process of Sending a Customer/Sub-Reseller to your Server and then receiving the Customer/Sub-Reseller back. You now need to modify up the files on your server to process the transaction. The process that you will follow is -

1. Modify the paymentpage.php file and insert your code to charge the Customer/Sub-Reseller in the block shown below

if(verifyChecksum($paymenttypeid, $transid, $userid, $usertype, $transactiontype, $sellingcurrencyamount, $accountingcurrencyamount, $key, $checksum))
{

 // YOUR CODE GOES HERE

}

The Code that you insert here may involve any or all of the following steps

• Saving the variables to a local database/session

• Converting the amount to the currency used by your Payment Gateway

• Redirecting the Customer/Sub-Reseller to another page which will obtain input from the Customer (e.g. his Credit Card details) and charge them

2. Once you have made the above changes then after the transaction you need to redirect the Customer back to our server. This task is handled by postpayment.php. Before postpayment.php can redirect the Customer/Sub-Reseller it needs to have transid, redirecturl, and status available in the session. While transid and redirecturl will be available in the session if they have been put in by paymentpage.php, status will have to be separately put into the session. DO NOT PASS a status to the postpayment.php page. This can allow the Customer/Sub-Reseller to modify the status. You must put the status value in session and retrieve the same from the session, or directly copy the code of postpayment.php inside your payment processing page.

3. Clean up the Code in the files. We have put in test related code which you may wish to remove. You can clean up the code at this stage removing all the procedures you do not need.

Attempt a live transaction from one of your Customer/Sub-Reseller accounts to verify everything is working fine. Make sure you try all types of Transactions - Add Funds, Payment of an Invoice, Payment of multiple Invoices/Debit Notes etc.

Every live transaction attempted through your Payment Gateway is recorded by the system. You can list all Transactions and search through them using the List Transactions and Search Transactions buttons in your Payment Gateway toolbar. The following fields are important with respect to each Transaction

There may be occasions when your Customer/Sub-Reseller will be redirected to your Gateway but never comes back to our Server because of loss of connectivity or other issues. In this circumstance our System will not know whether the Transaction was Successful or Failed. You will have to tell that to the System yourselves. This can be easily achieved by Searching Transactions from the Payment Gateway toolbar and clicking on AuthStarted transactions. This will allow you to list all transactions which are yet processing. From here you can state whether they were Successful or Failed. Incase of a successful transaction the System will add those funds to your Customer/Sub-Reseller and process any related Orders. Incase of failed transactions the System will simply mark the transaction as failed. Click here to here to find instructions on how to Search / Approve Decline Payment Gateway Transactions >>