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> |