Project

General

Profile

Edit History

Wiki ยป

Programming Guide » History » Version 15

chin-yeh, 09/22/2011 11:18 AM

1 2 chin-yeh 
{{toc}}
2 





    3
    1
    chin-yeh
    
h1. Programming Guide





    4
    2
    chin-yeh
    





    5
    
    
    
Describes how to integrate the mPay into online mall.





    6
    
    
    





    7
    15
    chin-yeh
    
*Steps-by-steps:* (_see also [[Specification#Suggested-Payment-Flow|Payment Flow]]_)





    8
    11
    chin-yeh
    
# First, refer to the [[Programming_Guide#Generate-Redirect-URL|Generate Redirect URL]] section on how to generate the redirect URL





    9
    
    
    
# And then, include the method, [[Programming_Guide#Capture-Payment-Status|Capture Payment Status]] in the return/receipt page to capture & persist the payment status





    10
    12
    chin-yeh
    
# Finally, query the [[Specification#Tables-Used|MPAY_INTERFACE]] table to get the payment status.





    11
    11
    chin-yeh
    





    12
    14
    chin-yeh
    
*Libraries needed:*





    13
    
    
    
* Java cryptography API - http://192.168.2.13:50000/redmine/attachments/download/218/bcprov-jdk14-125.jar





    14
    
    
    
* mPay:





    15
    
    
    
** http://192.168.2.13:50000/redmine/attachments/download/219/MerchantAdmin.jar





    16
    
    
    
** http://192.168.2.13:50000/redmine/attachments/download/220/MerchantClient.jar





    17
    
    
    





    18
    4
    chin-yeh
    
*Demo application:*





    19
    
    
    
* Generate Redirect URL (for hosted payment form)





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





    21
    5
    chin-yeh
    
* Query Payment Status:





    22
    4
    chin-yeh
    
> http://192.168.2.68/ecosway/mpay-sample/query.html





    23
    3
    chin-yeh
    





    24
    2
    chin-yeh
    
h2. Source files





    25
    
    
    





    26
    
    
    
> Get the source files from [[wiki#SCM|SCM]].





    27
    
    
    





    28
    
    
    
*Files:*





    29
    
    
    
* my.com.eCosway.mpay





    30
    
    
    
** Commons - list of common constant





    31
    
    
    
** MpayInterfaceUtils - an utility to perform data persistence related operation





    32
    
    
    
** MpayPaymentUtils - the mPay APIs





    33
    
    
    
** MpayProperties - data model of the mPay properties





    34
    
    
    
** PaymentRequest - data model of the mPay's payment request





    35
    
    
    
** PaymentResponse - data model of the mPay's payment response





    36
    
    
    
* resources.properties.mpay





    37
    
    
    
** mpay.properties - the application properties file





    38
    8
    chin-yeh
    
* source file of demo application (JSP):





    39
    
    
    
** mpay-sample folder





    40
    5
    chin-yeh
    





    41
    
    
    
h2. Generate Redirect URL





    42
    
    
    





    43
    6
    chin-yeh
    
Generates the URL which will be used to redirect user to the mPay's hosted payment form.





    44
    
    
    





    45
    9
    chin-yeh
    
* *Method Signature:*





    46
    
    
    
<pre>





    47
    
    
    
<code class="JAVA">





    48
    
    
    
public static Map<String, String> genRedirectFormData(String orderNo,





    49
    
    
    
			Date txnDate, String amount, String returnUrl, String locale,





    50
    
    
    
			PaymentMethod paymentMethod)





    51
    
    
    
</code>





    52
    
    
    
</pre>





    53
    10
    chin-yeh
    
* *Demo:*





    54
    
    
    
** [[Programming Guide]]





    55
    6
    chin-yeh
    





    56
    5
    chin-yeh
    
h3. Input Parameters





    57
    
    
    





    58
    6
    chin-yeh
    
* *orderNo* - the unique order number 





    59
    
    
    
* *txtDate* - the transaction date





    60
    
    
    
* *amount* - the transaction amount





    61
    
    
    
* *returnUrl* - mPay will redirect the user to this URL after made the payment





    62
    
    
    
* *locale* - the display language of the payment form





    63
    
    
    
* *paymentMethod* - the payment method, e.g. _CUP_, _Alipay_





    64
    
    
    





    65
    
    
    
h3. Output Parameters





    66
    1
    chin-yeh
    





    67
    7
    chin-yeh
    
Use the returned key-pair values to construct the *HTML form*. 





    68
    1
    chin-yeh
    





    69
    8
    chin-yeh
    
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.





    70
    7
    chin-yeh
    





    71
    
    
    
*Returned key-pair values:*





    72
    
    
    
* *form_action* - the URL of the hosted payment form. To be placed in the *action* attribute of the form





    73
    
    
    
* *encmsg* - the encrypted message. To be placed in the input element





    74
    
    
    
* *sigmsg* - the signed message. To be placed in the input element





    75
    
    
    
* *certserial* - the serial number of the certificate. To be placed in the input element





    76
    
    
    





    77
    5
    chin-yeh
    
h3. Code Snippets





    78
    1
    chin-yeh
    





    79
    7
    chin-yeh
    
<pre>





    80
    
    
    
<code class="JAVA">





    81
    
    
    
<body>





    82
    1
    chin-yeh
    





    83
    7
    chin-yeh
    
<%





    84
    
    
    
	String orderNo = request.getParameter("order_no");





    85
    
    
    
	String txnDate = request.getParameter("txn_date");





    86
    
    
    
	String amount = request.getParameter("amount");





    87
    
    
    
	String returnUrl = request.getParameter("return_url");





    88
    
    
    
	String locale = request.getParameter("locale");





    89
    
    
    
	String paymentMethod = request.getParameter("payment_method");





    90
    
    
    
	





    91
    
    
    
	Date transactionDate = new SimpleDateFormat("yyyyMMddHHmmss").parse(txnDate);





    92
    
    
    
	PaymentMethod cardType = PaymentMethod.valueOf(paymentMethod);





    93
    
    
    
	





    94
    
    
    
	Map<String, String> formData = MpayPaymentUtils.genRedirectFormData(





    95
    
    
    
			orderNo, 





    96
    
    
    
			transactionDate,





    97
    
    
    
			amount,





    98
    
    
    
			returnUrl,





    99
    
    
    
			locale,





    100
    
    
    
			cardType);





    101
    
    
    
%>





    102
    
    
    





    103
    
    
    
<p>





    104
    
    
    
	Redirecting you to the mPay payment form, it may takes up to 1 minute...





    105
    1
    chin-yeh
    
</p>





    106
    7
    chin-yeh
    





    107
    9
    chin-yeh
    
<form name="form1" method="post" action="<%= formData.get("form_action") %>">





    108
    7
    chin-yeh
    
	<input type=hidden name=encmsg value="<%=formData.get("encmsg")%>"/>





    109
    
    
    
	<input type=hidden name=sigmsg value="<%=formData.get("sigmsg")%>"/>





    110
    
    
    
	<input type=hidden name=certserial value="<%=formData.get("certserial")%>"/>





    111
    
    
    
</form>





    112
    
    
    





    113
    
    
    
<script language="javascript">





    114
    
    
    





    115
    
    
    
function submitForm(){





    116
    
    
    
    document.form1.submit();





    117
    
    
    
}





    118
    
    
    





    119
    
    
    
window.onload=submitForm ;





    120
    
    
    





    121
    
    
    
</script>





    122
    
    
    





    123
    
    
    
</body>





    124
    
    
    
</code>





    125
    
    
    
</pre>





    126
    
    
    





    127
    13
    chin-yeh
    
h2. Capture Payment Status





    128
    
    
    





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





    130
    
    
    





    131
    
    
    
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.





    132
    
    
    





    133
    
    
    
* *Method Signature:*





    134
    
    
    
<pre>





    135
    
    
    
<code class="JAVA">





    136
    
    
    
public static String parsePaymentResponse(Connection connection, HttpServletRequest httpRequest)





    137
    
    
    
</code>





    138
    
    
    
</pre>





    139
    
    
    





    140
    
    
    
h3. Input Parameters





    141
    
    
    





    142
    
    
    
* *connection* - an established database connection





    143
    
    
    
* *httpRequest* - the HttpServletRequest object. It can be obtained in the JSP or servlet





    144
    
    
    





    145
    
    
    





    146
    
    
    
h3. Output Parameters





    147
    
    
    





    148
    
    
    
The returned value is the *order number* of the transaction.





    149
    
    
    





    150
    
    
    
h3. Code Snippets





    151
    
    
    





    152
    
    
    
<pre>





    153
    
    
    
<code class="JAVA">





    154
    
    
    
<%





    155
    
    
    
	Connection connection = null;





    156
    
    
    
	String orderNo = "";





    157
    
    
    
	try {





    158
    
    
    
		connection = createDbConnection("java:/DB2DS");





    159
    
    
    
		orderNo = MpayPaymentUtils.parsePaymentResponse(connection, request);





    160
    
    
    
	} catch(Exception ex) {





    161
    
    
    
		throw ex;





    162
    
    
    
	} finally {





    163
    
    
    
		if (connection != null) {





    164
    
    
    
			connection.close();





    165
    
    
    
		}





    166
    
    
    
	}





    167
    
    
    





    168
    
    
    
%>





    169
    
    
    
</code>





    170
    
    
    
</pre>





    171
    
    
    





    172
    7
    chin-yeh
    





    173
    1
    chin-yeh
    
h2. Query Payment Status





    174
    
    
    





    175
    10
    chin-yeh
    
Queries the payment status of the submitted transaction.





    176
    
    
    





    177
    
    
    
* *Method Signature:*





    178
    
    
    
<pre>





    179
    
    
    
<code class="JAVA">





    180
    
    
    
public static PaymentResponse queryPaymentStatus(String orderNo)





    181
    
    
    
</code>





    182
    
    
    
</pre>





    183
    
    
    
* *Demo:*





    184
    
    
    
** [[Programming Guide]]





    185
    
    
    





    186
    1
    chin-yeh
    
h3. Input Parameters





    187
    
    
    





    188
    10
    chin-yeh
    
orderNo - the order number of the submitted transaction





    189
    
    
    





    190
    
    
    





    191
    1
    chin-yeh
    
h3. Output Parameters





    192
    
    
    





    193
    10
    chin-yeh
    
The fields of the returned object, *PaymentResponse*:





    194
    
    
    
* *merchantId* - the merchant ID





    195
    
    
    
* *merchantTId* - the merchant terminal ID





    196
    
    
    
* *orderNo* - the order number





    197
    
    
    
* *systemDate* - the system date of mPay





    198
    
    
    
* *refNo* - the transaction ID of mPay





    199
    
    
    
* *amount* - the settlement amount





    200
    
    
    
* *currencyCode* - the currency of the settlement amount





    201
    
    
    
* *settlementDate* - the settlement date





    202
    
    
    
* *responseCode* - the response code





    203
    
    
    
* *authCode* - the bank authorization code if any





    204
    
    
    
* *transactionStatus* - indicate if it's success





    205
    
    
    





    206
    7
    chin-yeh
    
h3. Code Snippets





    207
    1
    chin-yeh
    





    208
    
    
    
<pre>





    209
    
    
    
<code class="JAVA">





    210
    10
    chin-yeh
    
<%





    211
    
    
    
	PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));





    212
    
    
    
%>





    213
    7
    chin-yeh
    
</code>





    214
    
    
    
</pre>