Programming Guide » History » Version 18
chin-yeh, 02/21/2012 10:02 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 | 18 | 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 | 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> |