Project

General

Profile

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>