Project

General

Profile

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>