Project

General

Profile

Specification » History » Version 18

Chooi-Mey, 05/02/2012 02:24 PM

1 2 chin-yeh
{{toc}}
2
3 1 chin-yeh
h1. Specification
4 2 chin-yeh
5 5 chin-yeh
The chosen integration method is *Customer Link*. The consumer enters payment information on GlobalCollect's hosted payment pages and GlobalCollect will forward the payment result to the merchant through *Payment Status Communicator* (PSC).
6
7 15 chin-yeh
Demo Application:
8
* Without Address:
9
> http://192.168.2.68/ukstore/sample/payment_form.jsp
10
* With Address:
11
> http://192.168.2.68/ukstore/sample/payment_form_with_address.jsp
12
13 6 chin-yeh
h2. Introduction
14 1 chin-yeh
15 6 chin-yeh
*Payment Flow*:
16 1 chin-yeh
!flow_diagram.jpg!
17 6 chin-yeh
18
19
h3. Java Package Name
20
21
Package name:
22
<pre>
23
my.com.eCosway.globalcollect
24
</pre>
25
26
h3. Table(s) used
27
28
<pre>
29
GLOBALCOLLECT_INTERFACE
30
</pre>
31
32
h2. Configuration
33
34
The GlobalCollect's *Customer Link* requires the merchant to provide the following URL:
35
* *Return URL* - A link to be displayed on GlobalCollect's payment pages. 
36
* *PSC URL* - GlobalCollect sends the payment information to this URL after the consumer has completed a payment attempt successfully.
37
38
h3. globalcollect.properties
39
40
This properties file is located at:
41
<pre>
42
resources/properties/uk/globalcollect.properties
43
</pre>
44 11 chin-yeh
> The properties file for development environment:
45
> <pre>resources/properties/uk/globalcollect-dev.properties</pre>
46 14 chin-yeh
> *important note:* rename to <code>globalcollect.properties</code>
47 6 chin-yeh
48
*Properties Description*:
49
|_.Property Name|_.Description|
50
|cl.url|The API URL for Customer Link|
51
|merchant.id|The merchant ID (provided by GlobalCollect)|
52
|merchant.ip|The merchant's public IP address|
53
|order.api.version|The API version of INSERT_ORDER|
54
|order.status.api.version|The API version of GET_ORDERSTATUS|
55
|currency.code|3 letter currency code (ISO-4217)|
56
|country.code|2 letter country code|
57
|language.code|2 letter language code (ISO-639)|
58
59
h2. Programming
60
61
This section contains 3 parts:
62
* Generate redirect URL - describes how to generate the redirect URL
63
* Back URL - describes how to handle the returned consumer
64
* PSC URL - describes how to capture the payment information
65
66 9 chin-yeh
h3. Required libraries
67
68
Apache HttpClient:
69
* httpclient-4.0.3.jar 
70
* httpcore-4.0.1.jar
71
* httpmime-4.0.3.jar
72
73
Download link:  http://hc.apache.org/downloads.cgi
74
75 6 chin-yeh
h3. Generate redirect URL
76
77 12 chin-yeh
The generated URL will be used to redirect the consumer to GlobalCollect's payment pages. 
78 6 chin-yeh
79
*Step-by-Step:*
80
# Prepare  the following parameters:
81
** *connection* - an established database connection
82
** *orderId* - the unique order ID, 20 alphanumeric characters
83
** *amount* - the order amount in cents, and integer values only
84
# Pass the above parameters to the following interface:
85
<pre>
86
String redirectUrl = PaymentUtils.genRedirectPaymentUrl(connection, orderId, amount);
87
</pre>
88
# Insert the order ID information into session.
89 1 chin-yeh
# Redirect the consumer to the generated URL using *JavaScript* or *HttpServletResponse.sendRedirect*. 
90 12 chin-yeh
91
h3. Generate redirect URL with address info and email
92
93
The generated URL URL will be used to redirect the consumer to GlobalCollect's payment pages. 
94
95
*Step-by-Step:*
96
# Prepare  the following parameters:
97 13 chin-yeh
** *transactionType* - the transaction type, e.g. PURCHASE, REGISTRATION
98 12 chin-yeh
** *connection* - an established database connection
99
** *orderId* - the unique order ID, 20 alphanumeric characters
100
** *amount* - the order amount in cents, and integer values only
101
** *email* - the email of the customer
102
** *profileAddress* - the address of the customer
103
** *shippingAddress* - the shipping address of the customer
104
# Pass the above parameters to the following interface:
105 1 chin-yeh
<pre>
106 13 chin-yeh
String redirectUrl = PaymentUtils.genRedirectPaymentUrl(transactionType, connection, orderId, amount, email, profileAddress, shippingAddress);
107 12 chin-yeh
</pre>
108
# Insert the order ID information into session.
109
# Redirect the consumer to the generated URL using *JavaScript* or *HttpServletResponse.sendRedirect*. 
110
111
112 6 chin-yeh
113
h3. Back URL
114
115
The back URL acts as receipt URL also. This is where the consumer will be redirected to after completed the payment.
116
117 8 chin-yeh
As GlobalCollect will not forward payment information to the URL, one has to obtain the order details via the active session. The following guide assumes the order ID is stored in the session.
118 6 chin-yeh
119
*Step-by-Step:*
120
# Prepare the following parameters:
121
** *connection* - an established database connection
122
** *orderId* - the unique order ID, 20 alphanumeric characters
123
# Pass the above parameters to the following interface:
124
<pre>
125
String orderId = (String) session.getAttribute("test_ord_id");
126
PaymentUtils.persistPaymentStatusForReceipt(connection, orderId);
127 1 chin-yeh
</pre>
128 8 chin-yeh
# And then, one can obtain the payment status in the interface table (see [[Specification#Table-used|Table Name]]);
129 6 chin-yeh
130
h3. PSC URL
131
132
For every payment transaction with the status 500 and above, GlobalCollect will post the payment information to the PSC URL.
133
134
*Step-by-Step*:
135
# Prepare the following parameters:
136
** *connection* - an established database connection
137
** *request* - the HttpServletRequest object
138
# Pass the above parameters to:
139
<pre>
140
PaymentUtils.persistPaymentStatusForPsc(dataBean.getConnection(), request);
141
</pre>
142
# *[Important]* The PSC must not contains any HTML element except a *'OK'* string e.g., 
143
<pre>
144
out.print("OK");
145 1 chin-yeh
</pre>
146 6 chin-yeh
 
147 8 chin-yeh
h2. FAQ
148 7 chin-yeh
149
*PSC:*
150
* GlobalCollect post the payment result within 2 minutes after completed payment
151
* The PSC URL must be a HTTPS URL
152
* Only those payment result with status 500 or above will be posted to PSC URL.
153 10 chin-yeh
* The number of retry attempt is 10. If reached the maximum retry attempt, the PSC posting will be disabled.
154
* The retry interval is 2-minutes for the first attempt and 1-minute for the subsequence attempts. 
155 16 Chooi-Mey
156
157 17 Chooi-Mey
*SSL Certification:*
158
* Global Collect has install a new SSL Cert installation which signed by Secure Trust on 11th April 2012:*
159 18 Chooi-Mey
 
160 1 chin-yeh
* Q1: How to check whether the cert is trusted by the system? 
161 18 Chooi-Mey
* A1: By requesting the below URL from the system that is connecting to Global Collect production platform the merchant can check that the root certificate of Secure_trust is be trusted by the system.
162
<pre>
163
Staging env: https://ps.gcsip.nl/wdl/version.txt 
164
Prod env: https://ps.gcsip.com/wdl/version.txt
165
</pre>
166 17 Chooi-Mey
This should give a response like: 7.1.20110709.2
167 18 Chooi-Mey
168 17 Chooi-Mey
* Q2: What is the action need to be taken by merchant?
169
* A2: Action to be performed by Merchant, is to add/import the provided new SSL Cert keystore into production server by using the Java command as below: 
170 18 Chooi-Mey
<pre>
171 16 Chooi-Mey
* ./keytool -import -trustcacerts -alias globalcollectSecureTrust -file Secure_trust.cer -keystore /usr/java/jdk1.5.0_15/jre/lib/security/cacerts
172
* ./keytool -import -trustcacerts -alias globalcollectWildcardGcsipCom -file wildcard.gcsip.com.cer -keystore /usr/java/jdk1.5.0_15/jre/lib/security/cacerts
173
* ./keytool -import -trustcacerts -alias globalcollectWildcardGcsipNl -file wildcard.gcsip.nl.cer -keystore /usr/java/jdk1.5.0_15/jre/lib/security/cacerts
174 18 Chooi-Mey
</pre>
175 16 Chooi-Mey