Project

General

Profile

Programming Guide » History » Version 21

Soh Keong, 01/22/2013 03:36 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 13 chin-yeh
* [[programming guide#Step-By-Step|Step-By-Step]] - describes how to integrate the NMI payment gateway
7 2 chin-yeh
* 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 21 Soh Keong
> http://192.168.2.68:8080/TestPage/page/payment/nmi.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 10 chin-yeh
_See also [[Specification#Payment-Flow|Payment Flow]]_
20 3 chin-yeh
21
*Steps:*
22 7 chin-yeh
# To get the *form URL*, pass the required parameters to [[programming guide#Generate-the-form-action-URL|getFormActionUrl]] method.
23
# Use the *form URL* (in which obtained in the previous step) to construct the payment form with the following <code>input</code> elements:
24
** billing-cc-number
25
** billing-cc-exp
26
** cvv
27
** billing-first-name
28 8 chin-yeh
** billing-last-name
29
** billing-address1
30
** billing-city
31
** billing-state
32
** billing-postal
33
** billing-country
34
** billing-phone
35
** billing-email
36 9 chin-yeh
*** _Example:_ 
37
!payment_form.png!
38 11 chin-yeh
** *Notes:* the URL of this payment form should be *HTTPS*
39 20 chin-yeh
** *Notes:* the length of the input fields should be less than *99 characters*
40 19 chin-yeh
# Validate all of the fields in the form using *JavaScript* (do not use server-side validation). Then, the payment form will be submitted directly to the payment gateway and the user will be redirected to the receipt page, which specified in the previous step.
41 16 chin-yeh
# 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, therefore, just pass in the request object to the method.
42 18 chin-yeh
# 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]]. _In certain scenarios, NMI [[FAQ#No-order-ID-returned|will not return the order ID]]._
43 17 chin-yeh
# The content of the receipt page is depends on the result of payment.
44 9 chin-yeh
# done.
45 5 chin-yeh
46
h2. Generate the form action URL
47
48
Generates the <code>form</code> action URL which is needed in the self-hosted payment form.
49
50
_Method Signature:_
51
<pre>
52
<code class="JAVA">
53
public static String getFormActionUrl(String orderId, String orderDescription, BigDecimal orderAmount, String returnUrl)
54
</code>
55
</pre>
56
57
h3. Input Parameters
58
59
* _orderId_ - the unique ID for the order
60
* _orderDescription_ - a simple description of the order
61
* _orderAmount_ - the settlement amount of the order in 2 decimal places, e.g. 12.34
62
* _returnUrl_ - the receipt URL
63
64
h3. Output Parameters
65
66
Returns a <code>form</code> action URL
67
68
h3. Code Snippets
69
70
<pre>
71
<code class="JAVA">
72
	String orderId = request.getParameter("order-id");
73
	String orderDescription = request.getParameter("order-description");
74
	BigDecimal orderAmount = new BigDecimal(request.getParameter("order-amount"));
75
	String returnUrl = request.getParameter("return-url");
76
	
77
	String formUrl = PaymentUtils.getFormActionUrl(orderId, 
78
			orderDescription, 
79
			orderAmount, 
80
			returnUrl);
81
</code>
82
</pre>
83 6 chin-yeh
84
h2. Payment Status Callback
85
86
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]].
87
88
*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]]).
89
90
_Method Signature:_
91
<pre>
92
<code class="JAVA">
93
public static String queryAndPersistPaymentStatus(Connection dbConnection, HttpServletRequest servletRequest)
94
</code>
95
</pre>
96
97
h3. Input Parameters
98
99
* _dbConnection_ - an established database connection
100
* _servletRequest_ - <code>HttpServletRequest</code> object which will be used to obtain the request parameter, <code>token-id</code>
101
102
h3. Output Parameters
103
104
the <code>order ID</code> that used in the particular payment transaction
105
106
107
h3. Code Snippets
108
109
<pre>
110
<code class="JAVA">
111
	Connection connection = createDbConnection("java:/DB2DS_USA");
112
	String orderId = "";
113
	try {
114
		orderId = PaymentUtils.queryAndPersistPaymentStatus(connection, request);
115
	} finally {
116
		if (connection != null) {
117
			connection.close();
118
		}
119
	}
120
</code>
121
</pre>