Project

General

Profile

Programming Guide » History » Version 9

chin-yeh, 10/18/2011 04:20 PM

1 1 chin-yeh
{{toc}}
2
3
h1. Programming Guide
4 2 chin-yeh
5
This guide describes how to make use of the NMI APIs for payment related transaction and it consists of 2 main parts:
6
* [[programming guide#Step-By-Step|Step-By-Step]] - describes the 
7
* API Reference - the detailed description of all the APIs mentioned in [[programming guide#Step-By-Step|Step-By-Step]]
8
9 3 chin-yeh
The demo application can be found here:
10 5 chin-yeh
> http://192.168.2.68/ukstore/nmi-sample/orders.jsp
11 3 chin-yeh
12 2 chin-yeh
h2. Step-By-Step
13
14
Before begin, install the following libraries into your development environment *_(remove the old versions if exists)_*:
15
* "HttpCore 4.1.2":http://192.168.2.13:8081/nexus/service/local/artifact/maven/redirect?r=central&g=org.apache.httpcomponents&a=httpcore&v=4.1.2&e=jar
16
* "HttpClient 4.1.2":http://192.168.2.13:8081/nexus/service/local/artifact/maven/redirect?r=central&g=org.apache.httpcomponents&a=httpclient&v=4.1.2&e=jar
17 3 chin-yeh
18
!ssd.png!
19
20
*Steps:*
21 7 chin-yeh
# To get the *form URL*, pass the required parameters to [[programming guide#Generate-the-form-action-URL|getFormActionUrl]] method.
22
# Use the *form URL* (in which obtained in the previous step) to construct the payment form with the following <code>input</code> elements:
23
** billing-cc-number
24
** billing-cc-exp
25
** cvv
26
** billing-first-name
27 8 chin-yeh
** billing-last-name
28
** billing-address1
29
** billing-city
30
** billing-state
31
** billing-postal
32
** billing-country
33
** billing-phone
34
** billing-email
35 9 chin-yeh
*** _Example:_ 
36
!payment_form.png!
37
# The payment form will be submitted directly to the payment gateway and the payment gateway will direct the user back to the receipt page, which specified the in the previous step.
38
# The redirect URL will contains the *token-id* query parameter. But the method, [[programming guide#Generate-the-form-action-URL|queryAndPersistPaymentStatus]] will extract the parameter on your behalf.
39
# Use the order ID that returned by the method, [[programming guide#Generate-the-form-action-URL|queryAndPersistPaymentStatus]] to get the payment status in the [[Specification#Interface-Table-Used|Interface table]].
40
# The content of the receipt page is depends on the payment status.
41
# done.
42 5 chin-yeh
43
h2. Generate the form action URL
44
45
Generates the <code>form</code> action URL which is needed in the self-hosted payment form.
46
47
_Method Signature:_
48
<pre>
49
<code class="JAVA">
50
public static String getFormActionUrl(String orderId, String orderDescription, BigDecimal orderAmount, String returnUrl)
51
</code>
52
</pre>
53
54
h3. Input Parameters
55
56
* _orderId_ - the unique ID for the order
57
* _orderDescription_ - a simple description of the order
58
* _orderAmount_ - the settlement amount of the order in 2 decimal places, e.g. 12.34
59
* _returnUrl_ - the receipt URL
60
61
h3. Output Parameters
62
63
Returns a <code>form</code> action URL
64
65
h3. Code Snippets
66
67
<pre>
68
<code class="JAVA">
69
	String orderId = request.getParameter("order-id");
70
	String orderDescription = request.getParameter("order-description");
71
	BigDecimal orderAmount = new BigDecimal(request.getParameter("order-amount"));
72
	String returnUrl = request.getParameter("return-url");
73
	
74
	String formUrl = PaymentUtils.getFormActionUrl(orderId, 
75
			orderDescription, 
76
			orderAmount, 
77
			returnUrl);
78
</code>
79
</pre>
80 6 chin-yeh
81
h2. Payment Status Callback
82
83
Queries the payment status using the <code>token ID</code> that returned by NMI. After obtained the payment status, update the particular record in the [[Specification#Interface-Table-Used|Interface table]].
84
85
*Important:* This method is supposed to be placed and invoked in the very beginning of the receipt page, (a.k.a. the <code>returnUrl</code> that specified in [[programming guide#Generate-the-form-action-URL|Generate form action URL]]).
86
87
_Method Signature:_
88
<pre>
89
<code class="JAVA">
90
public static String queryAndPersistPaymentStatus(Connection dbConnection, HttpServletRequest servletRequest)
91
</code>
92
</pre>
93
94
h3. Input Parameters
95
96
* _dbConnection_ - an established database connection
97
* _servletRequest_ - <code>HttpServletRequest</code> object which will be used to obtain the request parameter, <code>token-id</code>
98
99
h3. Output Parameters
100
101
the <code>order ID</code> that used in the particular payment transaction
102
103
104
h3. Code Snippets
105
106
<pre>
107
<code class="JAVA">
108
	Connection connection = createDbConnection("java:/DB2DS_USA");
109
	String orderId = "";
110
	try {
111
		orderId = PaymentUtils.queryAndPersistPaymentStatus(connection, request);
112
	} finally {
113
		if (connection != null) {
114
			connection.close();
115
		}
116
	}
117
</code>
118
</pre>