Project

General

Profile

Programming Guide » History » Version 16

chin-yeh, 09/22/2011 11:23 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 16 chin-yeh
* *orderNo* - the order number of the submitted transaction
189 10 chin-yeh
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>