Introduction
PHP API
Payment Flow
Generate API Key
Callback Parameters
Currency Settings
Automated
Withdrawals
Dollar Account Chechout
Buttons
Logos
Dollar Checkout
Get eCurrency Rates
Get Base Rate
Get User Status
Get User Balance
Shopping Carts
Checkout Name
Create user
Refund User Fees
Sandbox
Automated BankErrand
Get User Transactions
Set Webhooks
Pay with PIN
Validate transaction

OnlineNaira Developers API

This page is for developers and written in PHP and SQL.
If you would like OnlineNaira to help install this API into your website, please send us an email here.


Payment Parameters

Below is a description for all fields which you can use. For successful payment process you should use the following parameters:
member* OnlineNaira Username - this is one parameter that the user cannot change in OnlineNaira. Once set at signup, it remains the same throughout the life of the account. It is unique and it forms the most important identification for members. This parameter must be set for your integration to work.
action* use "product" if this product is pre-defined
  use "donation" if this is a donation
  use "subscription" if this product is subscription and repeats
  use "payment" if this is a simple payment transaction
product Product Description - This could either be the Product Title in a few words or some unique code or some unique identification for the product.
pid unique transaction identification or some number that uniquely identifies the event - this is optional.
price* price of product (default NGN), please see country field
country NGN, USD, GBP. EUR
Currency of the product (default NGN), If empty currency will be default to NGN
apikey this is currently optional, but some api calls will require your api key. Generate api key here.
quantity use "quantity" to define number of products
period subscription rebilling period in days
country NGN, USD, GBP. EUR
Currency of the product (default NGN), If empty currency will be default to NGN

This is an optional local currency setting. Use ISO. OnlineNaira will assume NGN if left blank - If the currency you need is not lists, please get in touch with us and we would consider adding it.
trial trial period in days, if any
setup use this for setup fee, if applicable
tax tax amount, if applicable
shipping shipping fee, if any
comments This could be extra product description or notes from the buyer.
ucancel This is the url to return the buyer if the payment is unsuccessful.
ureturn this is the url to return the buyer after successful payment
unotify This is the url to your website where some payment script or ipn is handled. OnlineNaira will send you an automated email notification after every successful payment, but if you want to have a deeper integration with OnlineNaira, the unotify must be set to a url that will handle call-back parameters.
Customer Details(Optional) Direct Payment - Without Wallet: To redirect to Card payment page add the following to your form
user_firstname Customer first name
user_lastname Customer last name
user_email Customer email address
user_whatsapp Customer's WhatsApp number - e.g +234 81234 56789
* these parameters are mandatory.

Notes - All payments in OnlineNaira are in Naira (NGN), but you should display your local currency in your shop while setting the country parameter to the 3 digit ISO code (ISO-4217 ) before parsing to OnlineNaira.

This following callback parameters will be sent to your script. After successful payment process OnlineNaira will forward buyer to your site and some parameters also sent back to your script by the POST method: You can get this parameters by the global POST variable, e.g. $_POST[--VARIABLE-NAME--]...


Call-Back Parameters

id This is unique identification for each transaction.
status Returns status of transaction.
  • 0 => Pending
  • 1 => Completed
  • 2 => Cancelled
  • 3 => Refunded
  • 4 => Fraudulent
o_price This is the original price as send to us from the merchant. please see total and charged_amount field below

FYI: This is the requested price & not paid amount.
pid Product id if specified
pname Product Name as received by OnlineNaira from your website
buyerName Full name of the customer
buyer This is the OnlineNaira Username of the customer.
buyeremail customer email address
country Currency of the product
total This is the total amount paid to your OnlineNaira account.
ExchangeRate If product currency not in NGN, the OnlineNaira exchange rate of the product currency
receiver OnlineNaira unique identifier of the merchant
action This is the type of transaction and it can only be either product, donation, subscription or payment.
quantity This is the quantity of product, if applicable.
comments This will provide any comments/notes added by the buyer.
referer system referer URL (https://www.onlinenaira.com)
charged_currency This is OnlineNaira local currency, and it currently in NGN
charged_amount(NGN) This is the actual amount paid by the customer to the Merchant. Please use this value to validated amount in your system
charged_fee The transaction fee
extra_one Extra field will return the value if any is posted to us
extra_two Extra field will return the value if any is posted to us
extra_three Extra field will return the value if any is posted to us
signature A secret hash is used to verify your callback requests. Verify callback requests with the secret hash returned as `signature` from OnlineNaira.
ce_signature This is the concatenate of the following values in the order

email: Merchant email use to register
OnlineNaira: the word "OnlineNaira"
pid unique transaction identification
country: Currency of the product
price: price of product
signature: your onlinenaira signature

Concatenate the above mentioned values, using hash sha256 with ":" as separators

ucancel This is the url to return the buyer if the payment is unsuccessful.
ureturn this is the url to return the buyer after successful payment
unotify This is the url to your website where some payment script or ipn is handled. OnlineNaira will send you an automated email notification after every successful payment, but if you want to have a deeper integration with OnlineNaira, the unotify must be set to a url that will handle call-back parameters.


Generate API Key

Click here to generate API key to use in your installation. Remember you will need to login to create an API key.


Accept Payments

With OnlineNaira API, you will get paid from buyer's account balance, but buyer would be able to fund their account with cash, bank wire or any cards issued in Nigeria. They would also be able to fund their accounts with eCurrencies such as bitcoins, ethereum, Neteller, PerfectMoney, etc

Here's an example of the api implementation if you are looking to receive deposits on your website.

<form method=post action="https://www.onlinenaira.com/process.htm">
<input type=hidden name=member value="ADESIYAN">
<input type=hidden name=action value="payment">
<input type=hidden name=product value="Deposit for Service">
<input type=text name=price value="">
<input type=hidden name=country value="NGN">
<input type=hidden name=ureturn value="http://www.adesiyan.com/web">
<input type=hidden name=unotify value="http://www.adesiyan.com/web">
<input type=hidden name=ucancel value="http://www.adesiyan.com/web">
<input type=hidden name=comments value="Deposit for Service">
<input type=image src="https://www.onlinenaira.com/images/Buy-Now-Button-onlinenaira-50.png">
</form>


Using Other Currencies

If you prefer to collect money with OnlineNaira in other currencies, pls be sure to set the country parameter.

Example - To display the Ghanaian Currency, USD, use the following line
<input type="hidden" name="country" value="USD">

It is better to display $, £ or € on the merchant website and let the OnlineNaira API auto convert the money to NGN. NGN fluctuates, but our API tracks the fluctuation so the correct NGN/$/£/€ conversion is used at all times.


Automated Withdrawals

curl url - https://onlinenaira.com/api/send-money.php

Fields Parameters

*secret_apikey this is different from the apikey, this is a secret key, and should be kept private. Pls login to generate key here - https://onlinenaira.com/members/members-generate-api-key.htm
*sender OnlineNaira username of the sender
*receiver OnlineNaira username of the receiver
*amount amount to send (default in NGN)
currency(optional) NGN by default, but accept USD, EUR, GBP etc
comment(optional) Any additional information for the transaction

The auto withdrawal in our API will enable all your users to do withdrawals by themselves when they want. The withdrawal will initially happen on your platform without calling the OnlineNaira API. When you confirm from your backend, our API would be called (for auto withdrawal, our API is called once) and user is paid. This gives you complete control of the withdrawal process without login into OnlineNaira.


Currency Setting

If you sell in any currency order than the Nigerian Naira (NGN), you should set the country parameter. The OnlineNaira API has built-in features to allow you to sell in any currency, but you will need to set the country parameter to tell OnlineNaira that you are selling in a currency order than the Naira. If you do not set the country parameter, OnlineNaira will treat all your receipts as if you were selling in Naira (NGN). Alternatively, if you sell in dollars ($), please set your action


Dollar Account Checkout

This is the checkout to use if wish to receive money directly into your OnlineNaira Dollar account. Do not use this checkout if you do not have a $account with us. Open a dollar account now. The following line of code is the only thing that needs to change in your API - <form method=post action="https://www.onlinenaira.com/dollar/process.htm">


Buttons

We have provided some buttons below for your use, but you should be able to use just any button that matches the design of your wif you are looking to website.

Logos

We have provided some logos below for your use.


Get eCurrency Rate

We have provided all our eCurrency rates in API so you could automate their use in your applications. The rates are updated every 15mins.

URL - https://onlinenaira.com/api/ecurrency-rate.xml

If you would like to update the rates now, click here.


Checkout Name

To ensure your Company name shows during checkout, pls add your preferred company name to your profile. To add your company name, login and click on SETTINGS, choose PROFILE and change the entry to Company.


Get OnlineNaira Base Rate

This is the rate we will use if you use our pay4me service. The rates are updated every 15mins.

URL - https://onlinenaira.com/api/dollar-naira.xml

If you would like to update the rates now, click here.


Get User Status

This offers you the status of any OnlineNaira user provided you have a username. This can come in handy for a number of reasons including checking if a user exists on the OnlineNaira system and to know if they are UNVERIFIED, VERIFIED or CERTIFIED. See certification information here to see how best to use this API parameter in your applications. For instance, you may want to offer your service or a premium service level to CERTIFIED OnlineNaira members only.

URL - https://onlinenaira.com/api/get-user-status.php?q=username

Example. To check the status of the user ADESIYAN, use https://onlinenaira.com/api/get-user-status.php?q=adesiyan


Get User Transactions

If you have a need to print all transactions with a user, these are the API parameters to use.

URL - https://onlinenaira.com/api/get-user-transactions.php

Make a request Curl/HttpWebRequest with the following fields parameters

FYI: All parameters are mandatory

- apikey(string) e.g "GPFfhAsJL6NfY1on",
- username(string) e.g "test_account",
- date-from(string - yyyy-mm-dd) e.g "2018-01-01",
- date-to(string - yyyy-mm-dd) e.g "2019-01-16",
- trans_id(int) e.g "0000001"


Premium member create OnlineNaira user

Implementing this option will give your customers temporary certification so they could do a first checkout without certification.

URL - https://onlinenaira.com/api/create-member-by-premium.php

Make a request Curl/HttpWebRequest with the following fields parameters

FYI: * mandatory

- apikey(string)* e.g "GPFfhAsJL6NfY1on",
- username(string)* e.g "test_account",
- u_email(string)* e.g "test@gmail.com",
- u_firstname(string)* e.g "John",
- u_lastname(string)* e.g "Smith",
- u_password(string)* e.g "*********",
- u_dob(string)* e.g "yyyy-mm-dd",
- u_address(string)* e.g "78 john smith street",
- u_city(string)* e.g "Lagos",
- u_country(string)* e.g "NG, UK, US",
- u_photoid(string)* e.g "https://www.onlinenaira.com/images/2naira.png",
- u_addressid(string)* e.g "https://www.onlinenaira.com/images/2naira.pdf",


Get User Balance

This parameter tells you the status of any OnlineNaira user provided you have a username. It confirms the user exists and whether they have a balance greater or less than zero.

URL - https://onlinenaira.com/api/get-user-balance.php?q=username

Example. To check the status of the user ADESIYAN, use https://onlinenaira.com/api/get-user-balance.php?q=adesiyan


Refund User Fees

If you would like to refund the fees paid by your customers in the process of making a deposit into their wallets with you, you would need to implement this on your side.

e.g you want to give 0.04% back to your customer who wants to pay $10 - You send $9.96 to OnlineNaira.


Shopping Cart Integrations

 


Sandbox

If you are looking to test the OnlineNaira API, thi si the url to use to see if your api inatalltion is working ok.

POST URL - https://www.onlinenaira.com/process-sandbox.htm

Please remember that to use the Sandbox, every other api paranmeters remain the same except the POST url.



Search Debtor Record

Make a request Curl/HttpWebRequest with the following fields parameters

POST URL - https://onlinenaira.com/api/test-api.php

FYI: All parameters are mandatory
- username(string) e.g "test_account",
- apikey(string) e.g "GPFfhAsJL6NfY1on",
- search(string) e.g "adesiyan",

Webhooks

To received notification on you transaction status change, set Webhooks


Payout to User's Bank

This is the api to use if you'd like to process payouts directly into your clients bank account or mobile money.

- apikey
- sender
- amount
- comment(instruction)
https://onlinenaira.com/api/bank-errand.php

 

 

Payment Flow with Wallet Checkout.


Payment Flow without Wallet.


Pay By PIN Funding

This API is to fund Merchant using OnlineNaira in the background. It offers a third party payment gateway an opportunity to offer their customers Deposits and Withdrawals using OnlineNaira, but without showing up in the customer experience. When the transaction is succssful, your users will receive a Pin to complete their Deposit.
apikey* Merchant OnlineNaira secret key
username* Merchant OnlineNaira username
user_firstname* customer first name
user_lastname* customer last name
user_email* customer email
currency* default is NGN
amount* amount to send

Endpoint - https://onlinenaira.com/api/mid-merchant.php

When the transaction is successful, you get the below values:

  • status - API status success or failed
  • message - message of the status
  • username - OnlineNaira username for the user
  • TransactionID - transaction ID
  • PaymentPIN - Pin to use for payment
  • Balance - Customer Account Balance



Validate transaction

This API is to validate the record/transaction response receives from unotify.
apikey* Merchant OnlineNaira secret key
username* Merchant OnlineNaira username
trans_id* OnlineNaira transaction id (Use the transaction id send in unotify)
Endpoint - https://onlinenaira.com/api/get-transaction-callback.php


Secure SSL Certificate SiteLock