Programming Guide » History » Revision 20
Revision 19 (chin-yeh, 10/31/2011 03:51 PM) → Revision 20/21 (chin-yeh, 11/01/2011 11:47 AM)
{{toc}}
h1. Programming Guide
This guide describes how to make use of the NMI APIs for payment related transaction and it consists of 2 main parts:
* [[programming guide#Step-By-Step|Step-By-Step]] - describes how to integrate the NMI payment gateway
* API Reference - the detailed description of all the APIs mentioned in [[programming guide#Step-By-Step|Step-By-Step]]
The demo application can be found here:
> http://192.168.2.68/ukstore/nmi-sample/orders.jsp
h2. Step-By-Step
Before begin, install the following libraries into your development environment *_(remove the old versions if exists)_*:
* "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
* "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
!ssd.png!
_See also [[Specification#Payment-Flow|Payment Flow]]_
*Steps:*
# To get the *form URL*, pass the required parameters to [[programming guide#Generate-the-form-action-URL|getFormActionUrl]] method.
# Use the *form URL* (in which obtained in the previous step) to construct the payment form with the following <code>input</code> elements:
** billing-cc-number
** billing-cc-exp
** cvv
** billing-first-name
** billing-last-name
** billing-address1
** billing-city
** billing-state
** billing-postal
** billing-country
** billing-phone
** billing-email
*** _Example:_
!payment_form.png!
** *Notes:* the URL of this payment form should be *HTTPS*
** *Notes:* the length of the input fields should be less than *99 characters*
# 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.
# 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.
# 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]]._
# The content of the receipt page is depends on the result of payment.
# done.
h2. Generate the form action URL
Generates the <code>form</code> action URL which is needed in the self-hosted payment form.
_Method Signature:_
<pre>
<code class="JAVA">
public static String getFormActionUrl(String orderId, String orderDescription, BigDecimal orderAmount, String returnUrl)
</code>
</pre>
h3. Input Parameters
* _orderId_ - the unique ID for the order
* _orderDescription_ - a simple description of the order
* _orderAmount_ - the settlement amount of the order in 2 decimal places, e.g. 12.34
* _returnUrl_ - the receipt URL
h3. Output Parameters
Returns a <code>form</code> action URL
h3. Code Snippets
<pre>
<code class="JAVA">
String orderId = request.getParameter("order-id");
String orderDescription = request.getParameter("order-description");
BigDecimal orderAmount = new BigDecimal(request.getParameter("order-amount"));
String returnUrl = request.getParameter("return-url");
String formUrl = PaymentUtils.getFormActionUrl(orderId,
orderDescription,
orderAmount,
returnUrl);
</code>
</pre>
h2. Payment Status Callback
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]].
*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]]).
_Method Signature:_
<pre>
<code class="JAVA">
public static String queryAndPersistPaymentStatus(Connection dbConnection, HttpServletRequest servletRequest)
</code>
</pre>
h3. Input Parameters
* _dbConnection_ - an established database connection
* _servletRequest_ - <code>HttpServletRequest</code> object which will be used to obtain the request parameter, <code>token-id</code>
h3. Output Parameters
the <code>order ID</code> that used in the particular payment transaction
h3. Code Snippets
<pre>
<code class="JAVA">
Connection connection = createDbConnection("java:/DB2DS_USA");
String orderId = "";
try {
orderId = PaymentUtils.queryAndPersistPaymentStatus(connection, request);
} finally {
if (connection != null) {
connection.close();
}
}
</code>
</pre>