Parallels H-Sphere Documentation Developer Guide


Adding Web Payment Systems

(deprecated since version 2.5)

Related Docs:   Web Payment SDK (HS 2.5+)

Last modified: 28 Dec 2007


WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

To add a web payment system to H-Sphere, you need to:

  1. Create Java servlet
  2. Create .html templates
  3. Create .sbm template
  4. Add new web payment servlet to web.xml
  5. Add new web payment system to merchants.xml


1. Create Java Servlet

Java Servlet is used to redirect users to a web payment system's payment page or receive the parameters from a web payment system and check them before adding payment to users' balance. Use the following example to create a java servlet for your custom web payment system:

package psoft.hsphere.payment;

import psoft.hsphere.Session;
import psoft.hsphere.resource.admin.MerchantManager;
import psoft.util.freemarker.TemplateString;
import psoft.util.freemarker.TemplateMap;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.ServletException;
import java.util.HashMap;
import java.util.StringTokenizer;

import freemarker.template.Template;
import freemarker.template.SimpleHash;

public class ExampleWebPaymentServlet  extends ExternalPayServlet {
    private static final String GATEWAY = "ExampleWebPayment";

    //The below method is called when web payment system or H-Sphere
    //calls this ExampleWebPayment servlet.
    public void service(HttpServletRequest request,
                        HttpServletResponse response)
        throws ServletException, IOException
        //If the servlet is called by H-Sphere
        //(to redirect customers to the payment page on the Web Payment System
        //side), the request value will contain paramter "action"
        String action = request.getParameter("action");
        if ("redirect".equals(action)) {
            //in this case the code redirects users to
            //the web payment system page
            getProcessForm(request, response);
        } else {
            //in this case, the request parameters are checked
            //and if they are correct, the user's balance is debited
            processPayment(request, response);

    protected void getProcessForm(HttpServletRequest request, HttpServletResponse response)
                throws ServletException, IOException
        try {

            //The cp_url, trnas_id, amount and description parameters
            //are received from the request
            String cpUrl = request.getParameter("cp_url");
            if (cpUrl == null ||
                throw new Exception("Empty cp_url parameter");
            String trDesc = request.getParameter("trans_id");
            if ((trDesc == null)
                    || "".equals(trDesc)) {
                throw new Exception("Empty transaction ID");
            String amount = request.getParameter("amount");
            if ((amount == null)
                    || "".equals(amount)) {
                throw new Exception("Empty amount for trans ID:" + trDesc);

            String description = request.getParameter("description");
            //the below instruction extracts the parameters that were set while
            //configuring web payment system (e.g. merchant ID, login etc.)
            HashMap values = MerchantManager.getProcessorSettings(GATEWAY);
            //the below instruction checks if the web payement system is active
            if (!"1".equals(values.get("enabled"))) {
                throw new Exception("ExampleWebPayment is not available");
            //the below set of instructions extracts expample.sbm template
            String template_name = "submit/billing/example.sbm";
            Template template = Session.getTemplate(template_name);

            if (null == template) {
                processEmptyResponse(request, response, "Template " + template_name + " is not exist");
            SimpleHash root = new SimpleHash();
            root.put("trDesc", new TemplateString(trDesc));
            root.put("values", new TemplateMap(values));
            root.put("amount", new TemplateString(amount));
            root.put("servlet_url", new TemplateString(cpUrl + SERVLETPATH
                    + values.get("servlet")));
            root.put("description", new TemplateString(description));
            root.put("invoice", new TemplateString(
                    String.valueOf(Session.getNewIdAsLong()) + "-" + trDesc));
            template.process(root, response.getWriter());
        } catch (Exception e) {
            log.warn("Unable to process transaction", e);
            Ticket.create(e, null);
            processEmptyResponse(request, response, "The payment can't be processed: "+e.getMessage());
        } finally {
            try {
            } catch (Exception ex) {

    protected void processPayment(HttpServletRequest request,
                                  HttpServletResponse response)
        throws ServletException, IOException
        //several specific hsphere variables were included in the
        //request sent earlier by getProcessForm(...) method
        //and example.sbm template (described above)
        //Now these values should be extracted trom the received request.
        //This way the invoice value as well as some other values
        //described below should be initialized.
        //invoice value should have the following format:
        // hsphere_generated_transaction_id-acc-accountID
        // hsphere_generated_transaction_id-sig-signupID
        // hsphere_generated_transaction_id-mail-accountID
        String invoice = request.getParameter("parameter_name_in_the_payment_system_request");
        //the below instruction gets the amount value from the request
        double amount =Double.parseDouble(request.getParameter("parameter_name_in_the_payment_system_request"));
        //here using the request you should check if the payment was sucessful
        //if the payment was successful, run the following set of instructions:
        StringTokenizer tokenizer = new StringTokenizer(invoice, "-");
        String transID = "";
        String accInfo = "";
        short success = 0;
        try {
            try {
                tokenizer = new StringTokenizer(invoice, "-");
                transID = tokenizer.nextToken().trim();
                accInfo = invoice.substring(transID.length()+1);

                //the below instruction adds payment to the user's billing balance
                setPayment(amount, transID, invoice, GATEWAY);
                success = 1;
            } catch (Exception e) {
                log.warn("Unable to add payment to the ", e);
            } finally {
        } catch (Exception e) {
            log.warn("Unable to process transaction", e);
        printResultPage(response, success);

    private void printResultPage(HttpServletResponse response,
                                 int status)
            throws IOException
        PrintWriter out = new PrintWriter(response.getWriter());
        switch (status) {
            case 0 :
                out.println("Unable to process transaction");
            case 1 :
                out.println("Transaction has been completed successfully.");
            default :
                out.println("Unable to process transaction");


When you create the servlet put it into the /home/cpanel/shiva/psoft/hsphere/payment directory.


2. Create .html Templates

You need to create three HTML templates for the payment system settings page following the rules laid out in the Template Customization manual.

1) Create template frame

Template frame includes template controls and defines the "template" value. This is an example of a template frame:

<!-- BEGIN ./admin/merchant/WebPayment.html -->
<assign template="admin/merchant/WebPayment.html">
<include "functions">
<call draw_menu("merchant_view")>
<include "control/admin/merchant/WebPayment.html">
<call bottom()>
<!-- END ./admin/merchant/WebPayment.html -->

When you are through, put the template frame into:

2) Create template controls

A control template collects web payemnt system configuration data, for example:

This is an example of a control template:

<!-- BEGIN ./common/control/admin/merchant/WebPayment.html -->
<assign mm=account.getChild("merchant_manager")>
<call draw_tooltip()>
<table width="70%" border="0" cellspacing="0"
cellpadding="0" align="CENTER" bgcolor="${design.color("border_color")}">
<table width="100%" border="0" cellspacing="1"
cellpadding="3" align="CENTER">
<tr bgcolor="${HEADER_COLOR}">
<td colspan=2><call draw_header(lang.admin.webpayment.header)></td>
<form action="${config.CLIENT_CP_URL}" method="POST"accept-charset="UTF-8">
<input type="hidden" name="template_name"value="submit/admin/merchant/WebPayment.sbm">
<input type="hidden" name="ftemplate" value="${template}">
<input type="hidden" name="stemplate" value="admin/merchant/view.html">
<tr bgcolor="${LIGHT_STRIP}">
<td><call draw_label(lang.admin.webpayment.value_1)></td>
<td><input type="text" name="value_1" value="${settings.WebPayment_VALUE_1}"></td>
<td><call draw_label(lang.admin.webpayment.value_2)></td>
<td><input type="text" name="value_1" value="${settings.WebPayment_VALUE_2}"></td>
<td><call draw_label(lang.admin.webpayment.value_N)></td>
<td><input type="text" name="value_N" value="${settings.WebPayment_VALUE_N}"></td>

<if request.enabled == "1">
<assign venabled="CHECKED"><else><assignvenabled="">
<tr bgcolor="${LIGHT_STRIP}">
<td colspan="2"><input type=checkboxname="enabled" ${venabled}>
<tr bgcolor="${LIGHT_STRIP}">
<td colspan="2" align="center">
<input type="submit">
<!-- END ./common/control/admin/merchant/WebPayment.html -->

3) Create submit template

The submit tempalte posts web payment configuration data into H-Sphere database. This is the example of a submit template:

 <assign admin = account.getChild("admin")>
  <assign mm=account.getChild("merchant_manager")>
  <if request.enabled!="">
  <assign enabled="1">
  <assign enabled="">
  <if admin>
  <assign res=mm.webprocessorparams("WebProcessor", "VALUE_1", request.value_1,
  "VALUE_2", request.value_2,...,"VALUE_N", request.value_n, "enabled",
  <if res.status=="OK">
    <include request.stemplate>
    <assign res=session.addMessage(res.msg)>
    <include request.ftemplate>

When you are through, put the submit template into /shiva-templates/common/submit/admin/merchant/


3. Create .sbm Template

.sbm template redirects customers to the web payment payment page when users decide to pay with your custom web payment system. It should be put to /common/submit/billing.
Follow this example:

<BODY BGCOLOR="${design.color("bgcolor")}">
<assign tmp_action = "">https://webpaymentsystem_purchase_page_url">
<FORM name="login" action="${tmp_action}" method="post" accept-charset="UTF-8">
<input type="hidden" name="value_1" value="${values.VALUE_1}">
<input type="hidden" name="value_2" value="${values.VALUE_2}">
<input type="hidden" name="value_N" value="${values.VALUE_N}">
<input type="hidden" name="desc" value="${description}">
<input type="hidden" name="amount" value="${amount}">

<SCRIPT language="javascript">


4. Add New Web Payment Servlet To web.xml

Add a record about the new servlet to shiva/psoft/hsphere/WEB-INF/web.xml, for example:



Here, initial parameters for the servlet are set in the init-param tags. servlet-mapping specifies the servlet pathname in the URL by which the servlet is called on the Web, e.g., in the example above,


5. Add New Web Payment System To merchants.xml

Add a new record into shiva/psoft/hsphere/merchants.xml within the <processors> tag, for example:

<processor name="WebPayment" description="label.webpayment"
template="admin/merchant/WebPayment.html" servlet="WebPaymentServlet">
        <value name="value_1"/>
        <value name="value_2"/>
        <value name="value_N"/>

Here, value_1-value_N are the fields for values to be stored in the H-Sphere database.

Please note that you don't specify the full servlet name (psoft.hsphere.payments.WebPaymentServlet) in the servlet attribute.

Related Docs:   Web Payment SDK (HS 2.5+)

© Copyright 2017. Parallels Holdings. All rights reserved.