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

# 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 the 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]].

# The content of the receipt page is depends on the payment status.

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