Project

General

Profile

Programming Guide » History » Version 13

chin-yeh, 09/21/2011 03:23 PM

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 11 chin-yeh
*Steps-by-steps:*
8
# 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 4 chin-yeh
*Demo application:*
13
* Generate Redirect URL (for hosted payment form)
14
> http://192.168.2.68/ecosway/mpay-sample/payment_form.html
15 5 chin-yeh
* Query Payment Status:
16 4 chin-yeh
> http://192.168.2.68/ecosway/mpay-sample/query.html
17 3 chin-yeh
18 2 chin-yeh
h2. Source files
19
20
> Get the source files from [[wiki#SCM|SCM]].
21
22
*Files:*
23
* my.com.eCosway.mpay
24
** Commons - list of common constant
25
** MpayInterfaceUtils - an utility to perform data persistence related operation
26
** MpayPaymentUtils - the mPay APIs
27
** MpayProperties - data model of the mPay properties
28
** PaymentRequest - data model of the mPay's payment request
29
** PaymentResponse - data model of the mPay's payment response
30
* resources.properties.mpay
31
** mpay.properties - the application properties file
32 8 chin-yeh
* source file of demo application (JSP):
33
** mpay-sample folder
34 5 chin-yeh
35
h2. Generate Redirect URL
36
37 6 chin-yeh
Generates the URL which will be used to redirect user to the mPay's hosted payment form.
38
39 9 chin-yeh
* *Method Signature:*
40
<pre>
41
<code class="JAVA">
42
public static Map<String, String> genRedirectFormData(String orderNo,
43
			Date txnDate, String amount, String returnUrl, String locale,
44
			PaymentMethod paymentMethod)
45
</code>
46
</pre>
47 10 chin-yeh
* *Demo:*
48
** [[Programming Guide]]
49 6 chin-yeh
50 5 chin-yeh
h3. Input Parameters
51
52 6 chin-yeh
* *orderNo* - the unique order number 
53
* *txtDate* - the transaction date
54
* *amount* - the transaction amount
55
* *returnUrl* - mPay will redirect the user to this URL after made the payment
56
* *locale* - the display language of the payment form
57
* *paymentMethod* - the payment method, e.g. _CUP_, _Alipay_
58
59
h3. Output Parameters
60 1 chin-yeh
61 7 chin-yeh
Use the returned key-pair values to construct the *HTML form*. 
62 1 chin-yeh
63 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.
64 7 chin-yeh
65
*Returned key-pair values:*
66
* *form_action* - the URL of the hosted payment form. To be placed in the *action* attribute of the form
67
* *encmsg* - the encrypted message. To be placed in the input element
68
* *sigmsg* - the signed message. To be placed in the input element
69
* *certserial* - the serial number of the certificate. To be placed in the input element
70
71 5 chin-yeh
h3. Code Snippets
72 1 chin-yeh
73 7 chin-yeh
<pre>
74
<code class="JAVA">
75
<body>
76 1 chin-yeh
77 7 chin-yeh
<%
78
	String orderNo = request.getParameter("order_no");
79
	String txnDate = request.getParameter("txn_date");
80
	String amount = request.getParameter("amount");
81
	String returnUrl = request.getParameter("return_url");
82
	String locale = request.getParameter("locale");
83
	String paymentMethod = request.getParameter("payment_method");
84
	
85
	Date transactionDate = new SimpleDateFormat("yyyyMMddHHmmss").parse(txnDate);
86
	PaymentMethod cardType = PaymentMethod.valueOf(paymentMethod);
87
	
88
	Map<String, String> formData = MpayPaymentUtils.genRedirectFormData(
89
			orderNo, 
90
			transactionDate,
91
			amount,
92
			returnUrl,
93
			locale,
94
			cardType);
95
%>
96
97
<p>
98
	Redirecting you to the mPay payment form, it may takes up to 1 minute...
99 1 chin-yeh
</p>
100 7 chin-yeh
101 9 chin-yeh
<form name="form1" method="post" action="<%= formData.get("form_action") %>">
102 7 chin-yeh
	<input type=hidden name=encmsg value="<%=formData.get("encmsg")%>"/>
103
	<input type=hidden name=sigmsg value="<%=formData.get("sigmsg")%>"/>
104
	<input type=hidden name=certserial value="<%=formData.get("certserial")%>"/>
105
</form>
106
107
<script language="javascript">
108
109
function submitForm(){
110
    document.form1.submit();
111
}
112
113
window.onload=submitForm ;
114
115
</script>
116
117
</body>
118
</code>
119
</pre>
120
121 13 chin-yeh
h2. Capture Payment Status
122
123
*This method must be invoked in the very beginning of the receipt page.*
124
125
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.
126
127
* *Method Signature:*
128
<pre>
129
<code class="JAVA">
130
public static String parsePaymentResponse(Connection connection, HttpServletRequest httpRequest)
131
</code>
132
</pre>
133
134
h3. Input Parameters
135
136
* *connection* - an established database connection
137
* *httpRequest* - the HttpServletRequest object. It can be obtained in the JSP or servlet
138
139
140
h3. Output Parameters
141
142
The returned value is the *order number* of the transaction.
143
144
h3. Code Snippets
145
146
<pre>
147
<code class="JAVA">
148
<%
149
	Connection connection = null;
150
	String orderNo = "";
151
	try {
152
		connection = createDbConnection("java:/DB2DS");
153
		orderNo = MpayPaymentUtils.parsePaymentResponse(connection, request);
154
	} catch(Exception ex) {
155
		throw ex;
156
	} finally {
157
		if (connection != null) {
158
			connection.close();
159
		}
160
	}
161
162
%>
163
</code>
164
</pre>
165
166 7 chin-yeh
167 1 chin-yeh
h2. Query Payment Status
168
169 10 chin-yeh
Queries the payment status of the submitted transaction.
170
171
* *Method Signature:*
172
<pre>
173
<code class="JAVA">
174
public static PaymentResponse queryPaymentStatus(String orderNo)
175
</code>
176
</pre>
177
* *Demo:*
178
** [[Programming Guide]]
179
180 1 chin-yeh
h3. Input Parameters
181
182 10 chin-yeh
orderNo - the order number of the submitted transaction
183
184
185 1 chin-yeh
h3. Output Parameters
186
187 10 chin-yeh
The fields of the returned object, *PaymentResponse*:
188
* *merchantId* - the merchant ID
189
* *merchantTId* - the merchant terminal ID
190
* *orderNo* - the order number
191
* *systemDate* - the system date of mPay
192
* *refNo* - the transaction ID of mPay
193
* *amount* - the settlement amount
194
* *currencyCode* - the currency of the settlement amount
195
* *settlementDate* - the settlement date
196
* *responseCode* - the response code
197
* *authCode* - the bank authorization code if any
198
* *transactionStatus* - indicate if it's success
199
200 7 chin-yeh
h3. Code Snippets
201 1 chin-yeh
202
<pre>
203
<code class="JAVA">
204 10 chin-yeh
<%
205
	PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));
206
%>
207 7 chin-yeh
</code>
208
</pre>