Programming Guide » History » Revision 19
Revision 18 (chin-yeh, 02/21/2012 10:02 AM) → Revision 19/21 (chin-yeh, 02/21/2012 10:03 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>