NetNaira website integration guide

CONTENT:
• Introduction
• Requirements
• Details
• Instant Payment Verification
  • The verify_url field
  • Verification Code
  • gt_hash
  • Sample Codes
• Find more help
  

Introduction
The following describes how a merchant integrates the NetNaira payment interface to his website. A merchant is anyone who has a website and an approved NETNAIRA MERCHANT ACCOUNT.

The NetNaira Payment gateway is built to fit into the vast internet business scenerios. It provides a favourable checkout route from a shopping cart as well as satisfying the instant payment for services.

Currently, integration can be made to two forms of NetNaira checkout interfaces, viz:

• The standard checkout
• The professional checkout

Currently, the standard checkout can be used by BOTH merchants and sellers while the professional checkout is open to only merchant account owners.

Requirements
A basic knowledge of HTML is required. Server side scripting knowledge is not necessary but is important if complex procedures are to be achieved.

Also needed is a website that meets the creteria stated in our terms of service and a NetNaira Merchant or Seller account number.

Details
The NetNaira checkout process actually starts with an HTML form submited to our server from the merchants website. The form is written in basic HTML and contains a set of hidden form fields which are parameters specifying the transaction process.

The content of this form depends on the type of account (merchant or seller) or the type of checkout interface (standard or professional) to be used.

Note: Only the STANDARD interface can be used by Seller account owners. A Merchants can use any.

Based on the checkoutinterface to be used, the 'action' parameter of this form is set to
https://www.netnaira.com/pay_pro/checkout.asp (for professional checkout) or
https://www.netnaira.com/pay_standard/checkout.asp (for standard checkout).

Note that this is supposed to be a secure interaction between the merchant's website and our server. Hence, the https must be used. The www. must also be included.

In both cases, the form's submit 'method' should be post.

The forms for both checkout consist of a set of 5 compulsary form fields and 11 optional ones. That is, for a successful payment to occur, 5 fields must be present and specified correctly.

5 FORM FIELDS THAT MUST BE INCLUDED FOR A STANDARD CHECKOUT

1. payee_account : The value of this compulsary field is the merchants NetNaira account number. Payments made will be credited to this account.
2. transaction_id : This field holds the unique alphanumeric id for the transaction in progress. It should not be more than 32 characters long.
3. description: This is a brief description of the transaction.
4. amount : This is the total amount involved in the trasaction.
5. payment_return : This is the URL on the merchants registered website to which the buyer or customer is redirected to when he completes a payment process successfully. It must poin to a file on the website submited by the merchant to us for NetNaira integration.
   

Thus, optimum form required for a successful NetNaira payment via the standard checkout interface will look like this (note that the names of all fields must be specified in lower case):

5 FORM FIELDS THAT MUST BE INCLUDED FOR A PROFESSIONAL CHECKOUT

1. payee_account : The value of this compulsary field is the merchants NetNaira account number. Payments made will be credited to this account.
2. transaction_id : This field holds the unique alphanumeric id for the transaction in progress. It should not be more than 32 characters long.
3. item_X: Where X is an integer (ie 0, 1, 2 ...). This field holds the description of item X.
4. price_X : Where X is an integer that corresponds to item X above. That is, the price of item_1 should be price_1. Price must be numbers only eg. 250.40, 788, 30.
5. payment_return : This is the URL on the merchants registered website to which the buyer or customer is redirected to when he completes a payment process successfully. It must poin to a file on the website submited by the merchant to us for NetNaira integration.
   

Thus, optimum form required for a successful NetNaira payment via the professional checkout interface will look like this (note that the names of all fields must be specified in lower case):

OPTIONAL FORM FIELDS
The following are optional form fields in the merchant entry form to the netnaira payment interface. They are common to both forms of checkout - professional or standard.

1. payee_name : This is the name a merchant or seller decides to present for a transaction. It can be his business name or website name. This is what the buyer sees during the transaction process.
   
   
2. currency : This is the currency code in which the transaction is meant to take place. Currently on NGN (Nigerian Naira) is supported.
   
   
3. shipping_fee : This holds the total amount charged for shipping the goods. If not specified, shipping is 0.00.
   
   
4. handling_fee : This holds the totoal amount required for handling during delivery and may include cost for packaging etc. 0.00 is used if not specified.
   
   
5. failure_return : This holds the URL on the merchants registered website to which the customer is redirected if the payment process fails for any reason eg. customer cancelation of payment process. The URL is requested for by our server using the POST form method. The status of the transaction is therefore posted to this url.
   
   
6. verify_url : This field deals with the NetNaira INSTANT PAYMENT VERIFICATION (IPV). It holds the url on the merchants website to which a transaction status is immediatly posted during a payment process. For details, see topic INSTANT PAYMENT VERIFICATION below
   
   
7. payment_email : The value of this could be either yes or no . This tells if a mail should be sent to merchant if payment is successfull. If yes is specified a mail will be sent to merchant when ever a successfull payment occurs. If no is specified, no mail will be sent to the merchant when there is a successfull payement. If this parameter is ommited, mails are sent to merchant for every successfull payments.
   
   
8. failure_email : This holds either yes or no. If yes mails are sent to merchant when a payment process fails, and if no, mails are not sent for failed payments.
   
   
9. payment_return_method : This describes the method by which a customer returns to the merchant's website after a successfull payment. It could be either 'get' or 'post'. If not specified, the 'get' method is used.
   
   
10. failure_return_method : This describes how form method by which a customer returns to the merchants website if a payment fails. It could be either 'get' or 'post'. If not specified the 'get' method is used.
    
    
11. extra : This helps a merchant include a custom field (other than the once stated above) that should be returned to his website after a payment process is completed whether successfully or not. The names of the custom field should be specified in the extra hidden field eg. a field holding the username of the user can be etered like this:
    
    
    <input type="hidden" name="extra" value="username" />
    <input type="hidden" name="username" value="the_user_name_of_the_user" />
    
    Our server will therefore check for the availability of a form field called username.
    
    For multiple custom fields, seperate each form field names in the extra hidden field with spaces. eg
    
    <input type="hidden" name="extra" value="firstname lastname">
    <input type="hidden" name="firstname" value="the_first_name_of_the_user">
    <input type="hidden" name="lastname" value="the_last_name_of_the_user">
    

Instant Payment Verification (IPV)

NetNaira instant payment verification is required for real time service delivery. It was design to afford merchants the ability to automate their part of a transaction as soon as payment is made. Requirements for a successfull verification include:

- A url to which transaction status request is sent specified in the verify_url field in the merchant entry form.

- A verification code ( this should be kept confidential). It is used to confirm that the POST request is comming from our server.

- A knowledge of a server side scripting language eg. asp, aspx, php, jsp, perl, python.

After a customer enters his security question and answer during a checkout process, a form with 6 hidden fields is posted from our server to the url specified in the verify_url hidden form field in the merchant's entry form. Certain security checks by the merchant is expected to be done with the data posted to merchants website.

The form posted from our server lookes like this:

<form action = "the verify_url as supplied by merchant in merchant entry form to netnaira" method="post">

<input type = "hidden" name="transaction_id" value = "the transaction_id specified in merchant entry form" >
<input type = "hidden" name="payee_account" value = "the netnaira account no. of the customer" >
<input type = "hidden" name="payer_account" value="the netnaira account of the merchant" >
<input type = "hidden" name="amount" value="total amount involved in the transaction">
<input type = "hidden" name="batch_id" value="the unique id given to every transaction by us">
<input type = "hidden" name="date_time" value="the date and time of the transaction" >
<input type = "hidden" name="gt_hash" value="the md5 encryption value for the transaction">

<!-- custom field(s) specified by the merchant in the entry form (in the extra form field) will also be included -->

</form>

Our server then waits for a success response from the verify_url. If a 'success' response is not received, the payment process fails and the customer's netnaira account is not debited for the transaction. That is to say, the merchants' website is to return 'success' to confirm that it received the transaction notice and the payee's netnaira account can be debited.

gt_hash! What is it?
gt_hash is an encryption based on the popular md5. It is the md5 of the fusion of some of the parameters sent to the merchant's verify url or payment success return url (exactly as sent) including the md5 value of the merchants verification code. A gt_hash code for a transaction can be derived as follows:

Please note that it is the md5 of the merchant's verification code that was used in getting the gt_hash value.

Why you need gt_hash!
Security is utmost in every checkout process. Therefore a merchant's website has to be sure that the form posted to it actually came from netnaira's server. Hence, netnaira passess along with the other parameters, the gt_hash value of the transaction which the merchant also calculates on his website and compares to that which was passed to it by netnaira. If the values are the same, then the transaction can proceed but if not, then it is very likely that the form came from else were (and not our server).
The merchants verification code is thus a confidential entity that should be shared only between netnaira and him.

Verification Code
This is the code entered by the merchant during his or her merchant registration process. It is more or less a secrete code used in validating transactions. The md5 value of the verification code is used in calculating the gt_hash of a transaction (see gt_hash above). The verification code therefore acts as a password to verify that a transaction posted to the merchant actually came from the NetNaira server.

A merchant can change his verification code at any time by logging in to his account and following the following path:
Profile -> Business/Website.

Sample code
Bellow is sample code written in the file pointed to by the verification url supplied by a merchant:

Sample code in ASP: