Project

General

Profile

Actions
History

Wiki »

Programming Guide » History » Revision 20

« Previous | Revision 20/21 (diff) | Next »
chin-yeh, 02/21/2012 10:04 AM

Programming Guide

Describes how to integrate the mPay into online mall.

Steps-by-steps: (see also Payment Flow)
  1. First, refer to the Generate Redirect URL section on how to generate the redirect URL
  2. And then, include the method, Capture Payment Status in the return/receipt page to capture & persist the payment status
  3. Finally, query the MPAY_INTERFACE table to get the payment status.
Libraries needed: Demo application:
  • Generate Redirect URL (for hosted payment form)

http://192.168.2.68/ecosway/mpay-sample/payment_form.html

  • Query Payment Status:

http://192.168.2.68/ecosway/mpay-sample/query.html

Source files

Get the source files from SCM.

Files:
  • my.com.eCosway.mpay
    • Commons - list of common constant
    • MpayInterfaceUtils - an utility to perform data persistence related operation
    • MpayPaymentUtils - the mPay APIs
    • MpayProperties - data model of the mPay properties
    • PaymentRequest - data model of the mPay's payment request
    • PaymentResponse - data model of the mPay's payment response
  • resources.properties
    • mpay.properties - the application properties file
  • source file of demo application (JSP):
    • mpay-sample folder

Generate Redirect URL

Generates the URL which will be used to redirect user to the mPay's hosted payment form.

  • Method Signature:
    public static Map<String, String> genRedirectFormData(String orderNo,
            Date txnDate, String amount, String returnUrl, String locale,
            PaymentMethod paymentMethod, CurrencyCode currencyCode)
  • Demo:

Input Parameters

  • orderNo - the unique order number
  • txtDate - the transaction date
  • amount - the transaction amount
  • returnUrl - mPay will redirect the user to this URL after made the payment
  • locale - the display language of the payment form
  • paymentMethod - the payment method, e.g. CUP, Alipay
  • currencyCode - the currency code, e.g. RMB, HKD

Output Parameters

Use the returned key-pair values to construct the HTML form.

Due to the limit of the length of a URL, the recommended HTTP method is POST. This is because extremely long URL will not work in most popular browsers and most importantly the length of the query string is unknown.

Returned key-pair values:
  • form_action - the URL of the hosted payment form. To be placed in the action attribute of the form
  • encmsg - the encrypted message. To be placed in the input element
  • sigmsg - the signed message. To be placed in the input element
  • certserial - the serial number of the certificate. To be placed in the input element

Code Snippets

<body>

<%
    String orderNo = request.getParameter("order_no");
    String txnDate = request.getParameter("txn_date");
    String amount = request.getParameter("amount");
    String returnUrl = request.getParameter("return_url");
    String locale = request.getParameter("locale");
    String paymentMethod = request.getParameter("payment_method");
   String currency = request.getParameter("currency");

    Date transactionDate = new SimpleDateFormat("yyyyMMddHHmmss").parse(txnDate);
    PaymentMethod cardType = PaymentMethod.valueOf(paymentMethod);
        CurrencyCode currencyCode = CurrencyCode.valueOf(currency);

    Map<String, String> formData = MpayPaymentUtils.genRedirectFormData(
            orderNo, 
            transactionDate,
            amount,
            returnUrl,
            locale,
            cardType,
            currencyCode);
%>

<p>
    Redirecting you to the mPay payment form, it may takes up to 1 minute...
</p>

<form name="form1" method="post" action="<%= formData.get("form_action") %>">
    <input type=hidden name=encmsg value="<%=formData.get("encmsg")%>"/>
    <input type=hidden name=sigmsg value="<%=formData.get("sigmsg")%>"/>
    <input type=hidden name=certserial value="<%=formData.get("certserial")%>"/>
</form>

<script language="javascript">

function submitForm(){
    document.form1.submit();
}

window.onload=submitForm ;

</script>

</body>

Capture Payment Status

This method must be invoked in the very beginning of the receipt page.

The main purpose of this method is to parse the payment response (which returned by mPay) and then update the payment status for the corresponding order.

  • Method Signature:
    public static String parsePaymentResponse(Connection connection, HttpServletRequest httpRequest)

Input Parameters

  • connection - an established database connection
  • httpRequest - the HttpServletRequest object. It can be obtained in the JSP or servlet

Output Parameters

The returned value is the order number of the transaction.

Code Snippets

<%
    Connection connection = null;
    String orderNo = "";
    try {
        connection = createDbConnection("java:/DB2DS");
        orderNo = MpayPaymentUtils.parsePaymentResponse(connection, request);
    } catch(Exception ex) {
        throw ex;
    } finally {
        if (connection != null) {
            connection.close();
        }
    }

%>

Query Payment Status

Queries the payment status of the submitted transaction.

  • Method Signature:
    public static PaymentResponse queryPaymentStatus(String orderNo)
  • Demo:

Input Parameters

  • orderNo - the order number of the submitted transaction

Output Parameters

The fields of the returned object, PaymentResponse:
  • merchantId - the merchant ID
  • merchantTId - the merchant terminal ID
  • orderNo - the order number
  • systemDate - the system date of mPay
  • refNo - the transaction ID of mPay
  • amount - the settlement amount
  • currencyCode - the currency of the settlement amount
  • settlementDate - the settlement date
  • responseCode - the response code
  • authCode - the bank authorization code if any
  • transactionStatus - indicate if it's success

Code Snippets

<%
    PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));
%>

Updated by chin-yeh over 12 years ago · 20 revisions