Project

General

Profile

Programming Guide » History » Version 19

chin-yeh, 02/21/2012 10:03 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 17 chin-yeh
* resources.properties
37 2 chin-yeh
** 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 18 chin-yeh
			PaymentMethod paymentMethod, CurrencyCode currencyCode)
51 9 chin-yeh
</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 1 chin-yeh
* *paymentMethod* - the payment method, e.g. _CUP_, _Alipay_
64 18 chin-yeh
* *currencyCode* -  the currency code, e.g. _RMB_, _HKD_
65 6 chin-yeh
66
h3. Output Parameters
67 1 chin-yeh
68 7 chin-yeh
Use the returned key-pair values to construct the *HTML form*. 
69 1 chin-yeh
70 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.
71 7 chin-yeh
72
*Returned key-pair values:*
73
* *form_action* - the URL of the hosted payment form. To be placed in the *action* attribute of the form
74
* *encmsg* - the encrypted message. To be placed in the input element
75
* *sigmsg* - the signed message. To be placed in the input element
76
* *certserial* - the serial number of the certificate. To be placed in the input element
77
78 5 chin-yeh
h3. Code Snippets
79 1 chin-yeh
80 7 chin-yeh
<pre>
81
<code class="JAVA">
82
<body>
83 1 chin-yeh
84 7 chin-yeh
<%
85
	String orderNo = request.getParameter("order_no");
86
	String txnDate = request.getParameter("txn_date");
87
	String amount = request.getParameter("amount");
88
	String returnUrl = request.getParameter("return_url");
89
	String locale = request.getParameter("locale");
90 1 chin-yeh
	String paymentMethod = request.getParameter("payment_method");
91 19 chin-yeh
    String currency = request.getParameter("currency");
92 7 chin-yeh
	
93
	Date transactionDate = new SimpleDateFormat("yyyyMMddHHmmss").parse(txnDate);
94 1 chin-yeh
	PaymentMethod cardType = PaymentMethod.valueOf(paymentMethod);
95 18 chin-yeh
        CurrencyCode currencyCode = CurrencyCode.valueOf(currency);
96 7 chin-yeh
	
97
	Map<String, String> formData = MpayPaymentUtils.genRedirectFormData(
98
			orderNo, 
99
			transactionDate,
100
			amount,
101 1 chin-yeh
			returnUrl,
102
			locale,
103 18 chin-yeh
			cardType,
104 19 chin-yeh
            currencyCode);
105 7 chin-yeh
%>
106
107
<p>
108
	Redirecting you to the mPay payment form, it may takes up to 1 minute...
109 1 chin-yeh
</p>
110 7 chin-yeh
111 9 chin-yeh
<form name="form1" method="post" action="<%= formData.get("form_action") %>">
112 7 chin-yeh
	<input type=hidden name=encmsg value="<%=formData.get("encmsg")%>"/>
113
	<input type=hidden name=sigmsg value="<%=formData.get("sigmsg")%>"/>
114
	<input type=hidden name=certserial value="<%=formData.get("certserial")%>"/>
115
</form>
116
117
<script language="javascript">
118
119
function submitForm(){
120
    document.form1.submit();
121
}
122
123
window.onload=submitForm ;
124
125
</script>
126
127
</body>
128
</code>
129
</pre>
130
131 13 chin-yeh
h2. Capture Payment Status
132
133
*This method must be invoked in the very beginning of the receipt page.*
134
135
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.
136
137
* *Method Signature:*
138
<pre>
139
<code class="JAVA">
140
public static String parsePaymentResponse(Connection connection, HttpServletRequest httpRequest)
141
</code>
142
</pre>
143
144
h3. Input Parameters
145
146
* *connection* - an established database connection
147
* *httpRequest* - the HttpServletRequest object. It can be obtained in the JSP or servlet
148
149
150
h3. Output Parameters
151
152
The returned value is the *order number* of the transaction.
153
154
h3. Code Snippets
155
156
<pre>
157
<code class="JAVA">
158
<%
159
	Connection connection = null;
160
	String orderNo = "";
161
	try {
162
		connection = createDbConnection("java:/DB2DS");
163
		orderNo = MpayPaymentUtils.parsePaymentResponse(connection, request);
164
	} catch(Exception ex) {
165
		throw ex;
166
	} finally {
167
		if (connection != null) {
168
			connection.close();
169
		}
170
	}
171
172
%>
173
</code>
174
</pre>
175
176 7 chin-yeh
177 1 chin-yeh
h2. Query Payment Status
178
179 10 chin-yeh
Queries the payment status of the submitted transaction.
180
181
* *Method Signature:*
182
<pre>
183
<code class="JAVA">
184
public static PaymentResponse queryPaymentStatus(String orderNo)
185
</code>
186
</pre>
187
* *Demo:*
188
** [[Programming Guide]]
189
190 1 chin-yeh
h3. Input Parameters
191
192 16 chin-yeh
* *orderNo* - the order number of the submitted transaction
193 10 chin-yeh
194
195 1 chin-yeh
h3. Output Parameters
196
197 10 chin-yeh
The fields of the returned object, *PaymentResponse*:
198
* *merchantId* - the merchant ID
199
* *merchantTId* - the merchant terminal ID
200
* *orderNo* - the order number
201
* *systemDate* - the system date of mPay
202
* *refNo* - the transaction ID of mPay
203
* *amount* - the settlement amount
204
* *currencyCode* - the currency of the settlement amount
205
* *settlementDate* - the settlement date
206
* *responseCode* - the response code
207
* *authCode* - the bank authorization code if any
208
* *transactionStatus* - indicate if it's success
209
210 7 chin-yeh
h3. Code Snippets
211 1 chin-yeh
212
<pre>
213
<code class="JAVA">
214 10 chin-yeh
<%
215
	PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));
216
%>
217 7 chin-yeh
</code>
218
</pre>