Project

General

Profile

Programming Guide » History » Version 12

chin-yeh, 09/21/2011 03:13 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
122 1 chin-yeh
h2. Query Payment Status
123
124 10 chin-yeh
Queries the payment status of the submitted transaction.
125
126
* *Method Signature:*
127
<pre>
128
<code class="JAVA">
129
public static PaymentResponse queryPaymentStatus(String orderNo)
130
</code>
131
</pre>
132
* *Demo:*
133
** [[Programming Guide]]
134
135 1 chin-yeh
h3. Input Parameters
136
137 10 chin-yeh
orderNo - the order number of the submitted transaction
138
139
140 1 chin-yeh
h3. Output Parameters
141
142 10 chin-yeh
The fields of the returned object, *PaymentResponse*:
143
* *merchantId* - the merchant ID
144
* *merchantTId* - the merchant terminal ID
145
* *orderNo* - the order number
146
* *systemDate* - the system date of mPay
147
* *refNo* - the transaction ID of mPay
148
* *amount* - the settlement amount
149
* *currencyCode* - the currency of the settlement amount
150
* *settlementDate* - the settlement date
151
* *responseCode* - the response code
152
* *authCode* - the bank authorization code if any
153
* *transactionStatus* - indicate if it's success
154
155 7 chin-yeh
h3. Code Snippets
156 1 chin-yeh
157
<pre>
158
<code class="JAVA">
159 10 chin-yeh
<%
160
	PaymentResponse paymentResponse = MpayPaymentUtils.queryPaymentStatus(request.getParameter("order_no"));
161
%>
162 7 chin-yeh
</code>
163
</pre>