NetNaira is designed to fit perfectly into all or almost all online business scenarios. Online business transactions vary greatly - while some require instant response from the merchant, some others don’t; certain transactions will be best implicitly completed due to constantly changing variables (e.g. products in stock on a really busy website). But no matter the complexity of your business, you (or your developer) have at least 2 integration model options to dig with.

Who should read this:

The concept of the NetNaira checkout integration process is simple (and is likely similar to any other online payment model you might have worked with). While the simplest option requires only a knowledge of basic HTML (HyperText Markup Language), the more complex option will require a profound knowledge of either ASP, PHP, JSP, ASPX or equivalent server side script/CGI language to implement. If you do not know what HTML is, then Google will be very handy.

Integration Requirements:

Ingegration requirements include a NetNaira merchant account (if you do not have any yet, get one now - it might still be free), a well built/running website to which you intend to integrate the NetNaira checkout. Other requirements include a NetNaira personal account for the testing process and your developer having atleast a knowledge of HTML (and/or any other technology mentioned in the previous section).

Understanding the NetNaira checkout process:

Every NetNaira checkout process actually starts with an HTML form submitted to the NetNaira server from the merchants website. We will use the WealthbuilderSpot (www.wealthbuilderspot.com) checkout as an example. When a user wants to activate her (or preferably his) wealthbuilderspot account, all he needs do is click on the ‘Pay Now’ button on the website (Fig 1.1) (as said earlier, this button is actually the submit button of a form). He is then directed to a page on the NetNaira website where the details of his payment is shown to him. To proceed with the payment, he is expected to supply a NetNaira account number and passcode (Fig 1.2). Providing a matching account number and passcode pair takes him to the third step of the payment process (Fig 1.3). Here (step 3) the customer’s security question and answer is demanded. If all goes well again (i.e. matching security question and answer and adequate fund in customers NetNaira account), the value of the payment is instantly transfered from the customers NetNaira account to the merchants NetNaira account. This means that the customer must have prefunded his NetNaira account using any of the available means (as at the time of this writing, available means included an ATM card and NetNaira PINs purchased from sellers). If the payment is successful, a payment successful page is displayed to the customer (Fig. 1.4). Here he can download the invoice for the payment. Clicking on the ‘Continue’ button redirects him back to the merchant website (www.wealthbuilderspot.com in this case) where the status of his payment is shown to him (in our example, he no longer sees the account inactive notice, Fig. 1.5).

Fig 1.1

Fig 1.2

Fig 1.3

Fig 1.4

Fig 1.5

Integration Details:

Your choice of integration method depends on a number of factors including your (or your developer’s) programing skill, your website technology and most importantly the nature of goods or services sold on your website. Simple integrations will suffice in cases such as ‘Donate now’ and wherever records of the user who made the payment is not necessarily stored and mornitored directly by the merchant’s website. On such websites, no CGI/Server side script is necessary and therefore the extent of complexity of such an integration terminates at a basic HTML form posted to a URL on the NetNaira server. The details of how this is done is dicussed below.

The more complex integration will be required for sites that require instant delivery of goods or services paid for. In such scenarios, the website will have to ensure that payment was actually made by a customer before the good or service is delivered. NetNaira offers developers two(2) integration models and your choice of integration does NOT only depend on your programing skill, but even more importantly, the nature of goods and services sold on the website/the mode of delivery. Sites that sell goods that require instant online delivery and products which are capable of going out of stock while the customers checks out (such as an online recharge card store) will benefit more from the first method - the Instant Pre-Payment verification (details below). On the other hand, sites that sell goods or services delivered much later (e.g. an online phone store) or products that never go out of stock (e.g. a webhosting package, software/mp3/video download website) would do best with the second option - the Instant Post-Payment verification.

Please note that whatever your choice of integration - whether simple, complex (Pre-Payment verification, Post-Payment verification or both), all NetNaira checkout processes begin with an HTML form (containing the details of the payment) posted to the NetNaira website.

The Basic HTML form

The basic HTML form consists of a series of hidden form fields posted to a URL on the NetNaira server - https://www.netnaira.com/pay_pro/checkout.asp. This means that the action parameter of the form should be ” https://www.netnaira.com/pay_pro/checkout.asp” (Please take note that the URL begins with https://www as https:// is required to keep the connection secure. Also the submission method should be “post” and NOT “get” i.e. your form should look like this:

If your account is in demo mode mode, please use this

Once again - 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.

The NetNaira checkout form consists of 4 compulsary form fields and 13 optional ones. That is, for a successful payment to occur, 4 fields must be present and specified correctly.

4 FORM FIELDS THAT MUST BE INCLUDED FOR A SUCCESSFUL 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. item_X: Where X is an integer (ie 0, 1, 2 … 24) e.g. item_1. This field holds the name/description of item X. NOTE: X is a number between 0 and 24.
3. price_X : Where X is an integer that corresponds to item X above e.g. price_1 . That is, the price of item_1 should be price_1. Price must be numbers only eg. 250.40, 788, 30.
4. 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 point to a page on the website submitted by the merchant to us during his NetNaira merchant account setup.

Thus, the basic 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.

1. transaction_id : If this is specified, it must be a unique number for every new transaction submitted.
2. 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.
3. quantity_X : This is the quantity of item_X. If not specified, 1 is used.
4. currency : This is the currency code in which the transaction is meant to take place. Currently only NGN (Nigerian Naira) is supported. Defaults is NGN
5. shipping_fee : This holds the total amount charged for shipping the goods. If not specified, shipping is 0.00.
6. handling_fee : This holds the total amount required for handling during delivery and may include cost for packaging etc. 0.00 is used if not specified.
7. 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 cancellation of payment process. The URL is requested for by our server using either the GET or POST form method. The status of the transaction is therefore sent to this url.
8. verify_url : (For complex integrations only) This field is related to the NetNaira INSTANT PAYMENT VERIFICATION (IPV). It holds the url on the merchants website to which a transaction status is immediately posted during a payment process. For details, see topic INSTANT PAYMENT VERIFICATION below
9. 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 successful. If yes is specified a mail will be sent to merchant when ever a successful payment occurs. If no is specified, no mail will be sent to the merchant when there is a successful payment. If this parameter is ommited, mails are sent to merchant for every successful payments.
10. 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.
11. payment_return_method : This describes the method by which a customer returns to the merchant’s website after a successful payment. It could be either ‘get‘ or ‘post‘. If not specified, the ‘get‘ method is used.
    
12. 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.
13. extra : This helps a merchant include one or more custom fields (other than those 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 entered 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 offers merchants the opportunity of automatically verifying if a payment occured successfully or not. The NetNaira IPV defines this concept. Instant payment verification can be done in any of two ways (or a combination of both ways) depend on goods/services delivered on the merchant’s website viz:

Instant Pre-Payment Verification
Instant Post-Payment Verification

Instant Pre-Payment Verification (IPrePV)

As the name implies, IPrePV refers to verifying a transaction before payment occurs. The merchant is an important determinant of the success of the transaction. He tells the NetNaira server whether to debit the customers NetNaira account or not for a specified transaction. In a classical IPrePV scenario, of great importance is the “verify_url” form field in the merchant checkout form. The field specifies a url on the merchant website to which the details of a transaction that is about to occur is posted. When a customer supplies his security question and answer correctly during the checkout process (Fig 1.3 above), a form is instantly posted to the merchants verify_url. This form contains the details of the transaction (including amount, transaction number, payer account number, payee account number, date and time of transaction e.t.c). Whether the transaction continues or not depends on the response gotten from the merchants verify_url. Response expected for a transaction to fail is “failed“. If the verify_url supplied returns any thing other than “failed” or is not found on the merchant’s website, then the transaction succeeds. Below is a diagrammatic representation of the IPrePV transaction pathway.

Fig 2.1

Your security guaranteed:|
It is important to note that it is possible for anyone to make a false form post to your verify_url for a transaction he only initiated on your website without proceeding to the payment page on the NetNaira website. The merchant then delivers a product that has not been paid for. This could have been a security flaw but it has all been worked out. Along with the transaction details posted to the merchants verify_url, is a hash code (the GT HASH). This code is unique for every transaction and is computed from what is expected to be a secret between the merchant and NetNaira, his verification code. A verification code is supplied by a merchant during his sign up process. He can modify this anytime in the Business/Website section of his account Settings page in his NetNaira account control panel. The merchant is also capable of calculating the GT HASH of a transaction since he knows his verification code. He then compares his calculated GT HASH with that sent from the NetNaira server, if identical, then it is a valid transaction else it is invalid and should not be processed. This means that the key to his safety is his verification code being kept confidential at all times.

Computing the GT HASH
The gt_hash for a transaction is computed using one of the most common encryption technology, MD5. It is available in almost all programming and scripting platforms (if it not available on yours, search the internet, you will, almost definately, find an implementation). The following is required in calculating the gt_hash code of a transaction:

- Transaction id
- Merchant’s (Payee’s) NetNaira Account Number
- Amount
- Customer’s (Payer’s) NetNaira account number

- The batch id of the transaction as supplied by us (NetNaira)
- The MD5 value of the merchants verification code

In ASP, calculating the gt_hash will look like this:
md5(Lcase(Transaction id:Merchant’s NetNaira Account Number:Amount:Customer’s NetNaira account number:batch id:md5(verification code)))

Note that each parameter is seperated from the other by a full colon :

e.g.

In PHP,

Please always compair the amount with that in your database in every transaction to ensure that your customer did not alter the amount paid during the checkout process.

Instant Post-Payment Verification (IPostPV)

IPostPV refers to confirming the status of a transaction at any time (but more often after payment is expected to have occured). Unlike IPrePV, the merchant is reponsible for sending a form post to the NetNaira server and reading the response from the server. To implement this, he will need to enable automation on his account in the Automation section of the Settings page in his NetNaira account control panel. Once a checkout process is completed (whether successfully or not), the customer is redirected to a return page supplied by the merchant in his checkout form. It is on this page he is likely to run a post payment verification of that transaction. If status returns completed and amount paid is valid, he delivers (or start processing) the product.

We have written out an automation API for merchants to make things easier, and so you might not need to understand the minutiae of the form post process. Get the Automation API and sample codes from the downloads page

Enabling Automation on your account for IPostPV (Learn more about automating your NetNaira account here)
Enabling automation on your account allows access to your NetNaira account remotely. This means you can actually check your balance, do transfers, query transaction status and search transaction history from your website or a desktop application without browsing the NetNaira website physically i.e. via a webservice. To enable automation, log into your NetNaira account, go to the Settings page and click on the Automation tab. Click on the check box labeled “Check to enable”. Fill the form displayed. Note that to use the IPostPV, you must select the Transaction Request checkbox in the “Allowed Actions” section. Save your changes. An automation secret key will be sent instantly to your phone. This key will grant anyone who has it access to your account, so again, you must keep it confidential. You can always reset your secret key. To maximise security on your account, consider inserting your servers IP address in the IP field. Learn more here…

The details on how to verify the status of a transaction has been posted here >>

You can get our APIs and sample codes on the download page.

For more information on integrating your website to NetNaira, browse through other posts on NetNaira.

Do not hesitate posting questions and comments at the bottom of this page. You can also contact us directly through our help desk (help.netnaira.com). We are always willing to put you through the process.

Join the forum discussion on this post - (1) Posts