Payment Gateway » NMI - Three Step Redirect

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

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

*Steps:*

# gather the 

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>