Programming Guide » History » Revision 20
Revision 19 (chin-yeh, 02/21/2012 10:03 AM) → Revision 20/21 (chin-yeh, 02/21/2012 10:04 AM)
{{toc}}
h1. Programming Guide
Describes how to integrate the mPay into online mall.
*Steps-by-steps:* (_see also [[Specification#Suggested-Payment-Flow|Payment Flow]]_)
# First, refer to the [[Programming_Guide#Generate-Redirect-URL|Generate Redirect URL]] section on how to generate the redirect URL
# And then, include the method, [[Programming_Guide#Capture-Payment-Status|Capture Payment Status]] in the return/receipt page to capture & persist the payment status
# Finally, query the [[Specification#Tables-Used|MPAY_INTERFACE]] table to get the payment status.
*Libraries needed:*
* Java cryptography API - http://192.168.2.13:50000/redmine/attachments/download/218/bcprov-jdk14-125.jar
* mPay:
** http://192.168.2.13:50000/redmine/attachments/download/219/MerchantAdmin.jar
** http://192.168.2.13:50000/redmine/attachments/download/220/MerchantClient.jar
*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
h2. Source files
> Get the source files from [[wiki#SCM|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
h2. Generate Redirect URL
Generates the URL which will be used to redirect user to the mPay's hosted payment form.
* *Method Signature:*
<pre>
<code class="JAVA">
public static Map<String, String> genRedirectFormData(String orderNo,
Date txnDate, String amount, String returnUrl, String locale,
PaymentMethod paymentMethod, CurrencyCode currencyCode)
</code>
</pre>
* *Demo:*
** [[Programming Guide]]
h3. 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_
h3. 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
h3. Code Snippets
<pre>
<code class="JAVA">
<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>
</code>
</pre>
h2. 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:*
<pre>
<code class="JAVA">
public static String parsePaymentResponse(Connection connection, HttpServletRequest httpRequest)
</code>
</pre>
h3. Input Parameters
* *connection* - an established database connection
* *httpRequest* - the HttpServletRequest object. It can be obtained in the JSP or servlet
h3. Output Parameters
The returned value is the *order number* of the transaction.
h3. Code Snippets
<pre>
<code class="JAVA">
<%
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();
}
}
%>
</code>
</pre>
h2. Query Payment Status
Queries the payment status of the submitted transaction.
* *Method Signature:*
<pre>
<code class="JAVA">
public static PaymentResponse queryPaymentStatus(String orderNo)
</code>
</pre>
* *Demo:*
** [[Programming Guide]]
h3. Input Parameters
* *orderNo* - the order number of the submitted transaction
h3. 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
h3. Code Snippets
<pre>
<code class="JAVA">
<%
PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));
%>
</code>
</pre>