Nearlyfree Ng Api Documentation
The Neaarlyfree Ng api is organised around REST, our api has predictable resource-oriented URLS, our api accepts form-encoded bodies and json requests and it returns/ response with JSON-ENCODED reponses, our api uses standard http response code, authentication, authorisation and verbs, which makes our api implementation and integration fun and simple to do.
AUTHENTICATION
Our Api make use of Basic authentication to authorise and validates each transactions. when you make a http request you are required to send an authorisation header that contains the word Basic followed by a space and a base64-encoded string username:apikey
Follow the steps below for the instruction on how to authenticate your requests.
- Login to your wallet (or register an account with us if you are new!)
- Navigate to the Api Section fill in the required forms to be one of our api users.
- After your api application has been Granted, navigate to your Api Dashboard . to copy your apikey.
- Concatenate your Username and Apikey as follows
NearlyFreeNg:APIKEY_TEST_01234567890 - Base64 Encode the concatenated string i.e your username and password
our example above will provide
LKDOSIJFJDIJjfkdjkfjkdoAA== - Add the authorisation header to your request once you have gotten the base64 encoded string. The authorisation header should be sent as follows:
Authorisation: Basic LKDOSIJFJDIJjfkdjkfjkdoAA==
Getting The list Our Available Products / Networks
Use a GET request to get the lists of the category of our various networks
Calling the endpoint, you will receive a json response contaning the products and there properties.
To Specify the category you need you will need to specify the category as part of your request.
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| category optional | Add this parameter if you want to specify the category of the products to be retrieved string data |
Getting The Plans of a Products / Network
Use a GET request to get the lists of the plans of a specific Product
Calling the endpoint, you will receive a json response contaning the products and there properties.
To Specify the network / product you need you will need to specify the network or product as part of your request.
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| network required | Add this parameter if you want to specify the category of the products to be retrieved string data |
Purchasing a Product
Use a POST request to access this endpoint
Calling the endpoint above, you will receive a json response containing the status, TransactionId, price and other relivant informations about your transaction.
Buying Data
Passed The Parameter below as part of your request while Purchasing Data
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| referenceId Required | This is a unique reference Id in which you can use to query a transaction, it also enable us to avoiding duplicate transactions should incase there was a network glitch and your server sent a request more than once, Also it will be sent as part of a webhook notification, Therefore it is neccessary. string mtnsme_01234567890 |
| network required | The networkId of the product you want to purchase string mtn-data |
| plan required | The planId of the product you want to purchase string mtn-sme-m-1gb |
| phoneNumber Required | Phone Number of the recipent of the service string 09067447390 |
| purchase Required | The Product You Want To Buy string data |
Buying Tv Subscriptions
Passed The Parameter below as part of your request when Purchasing Tv Subscriptions
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| referenceId Required | This is a unique reference Id in which you can use to query a transaction, it also enable us to avoiding duplicate transactions should incase there was a network glitch and your server sent the request more than once, Also it will be sent as part of a webhook notification, Therefore it is neccessary. string dstv_01234567890 |
| network required | The networkId of the product you want to purchase string mtn-data |
| plan required | The planId of the product you want to purchase string mtnSme-m-1gb |
| iucNumber Required | This is the Smart card number of service you want to purchase string 01234567890 |
| purchase Required | This is the product you are trying to purchase string data, airtime, tv |
| phoneNumber Required | Phone Number of the recipent of the service string 09067447390 |
| purchase Required | The Product You Want To Buy string tv |
NOTE:: The Endpoint Only Acceptss Json Payload
Buying Airtime
Passed The Parameter below as part of your request when Purchasing Airtime
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| referenceId Required | This is a unique reference Id in which you can use to query a transaction, it also enable us to avoiding duplicate transactions should incase there was a network glitch and your server sent a request more than once, Also it will be sent as part of a webhook notification, Therefore it is neccessary. string mtnsme_01234567890 |
| network required | The networkId of the product you want to purchase string mtn-data |
| plan required | The planId of the Airtime you want to purchase string mtn_topit |
| amount optional |
This is the amount of airtime you wamts to topup Take Note of the minimum and maximum amount of each plan. Also some plan required you to only select from an array of numbers. number 100 |
| phoneNumber Required | Phone Number of the recipent of the service string 09067447390 |
| purchase Required | The Product You Want To Buy string airtime |
NOTE:: The Endpoint Only Acceptss Json Payload
Buying Electricity Units
Passed The Parameter below as part of your request when Purchasing Electricity Units
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| referenceId Required | This is a unique reference Id in which you can use to query a transaction, it also enable us to avoiding duplicate transactions should incase there was a network glitch and your server sent a request more than once, Also it will be sent as part of a webhook notification, Therefore it is neccessary. string mtnsme_01234567890 |
| network required | The networkId of the product you want to purchase string mtn-data |
| plan required | The planId of the Airtime you want to purchase string mtn_topit |
| amount optional |
This is the amount of units you wamts to topup Take Note of the minimum and maximum amount of each plan. number 1000 |
| iucNumber Required | This is the meter number of the service you want to purchase string 0121232324 |
| phoneNumber Required | Phone Number of the recipent of the service string 09067447390 |
| purchase Required | The Product You Want To Buy string electricity |
Buying Examinations Epins
Passed The Parameter below as part of your request when Purchasing Examinations Epins
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| referenceId Required | This is a unique reference Id in which you can use to query a transaction, it also enable us to avoiding duplicate transactions should incase there was a network glitch and your server sent a request more than once, Also it will be sent as part of a webhook notification, Therefore it is neccessary. string mtnsme_01234567890 |
| network required | This Examination type you want to purchase string waec |
| plan required | This is planId of the Examination type string waec_result_checker |
| phoneNumber Required | Phone Number of the recipent of the service string 09067447390 |
| quantity Required |
This is the quantity of the EPins you want to purchase. Take Note of the minimum and maximum quantity of each Examination plan string 10 |
Verify The Smart Card Number/METER NUMBER
Some of our products needs to be verify to be sure you are making purchase to the right number
Use a GET request to get the details of a smart card or meter number, The endpoint and process for each is similar to one another.
Calling the endpoint, you will receive a json response contaning the Smart card or Meter Number of the passed number.
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| network required | This is the product you want to retrieve the information about its Iuc / smartCard Number. string dstv |
| iucNumber required | This field request the smartCard Number or the meter Number you want to retrieve information about. string dstv |
| plan optional |
Some Service requests that you pass the plan of the product you want to purchase. Example is Electircity which can either contains Prepaid or Postpaid string Prepaid |
Query A Transaction
You can query the a specific transaction
Use a GET request to get the details of a particular transaction by either passing your referenceId or The TransactionId will sent back as part of the response.
Calling the endpoint, you will receive a json response containing the details of the particular Transaction you want.
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| transactionId required / ooptional | This is the unique transaction Id will responded back ot your request while purchasing our product string mtncg1gb_01234567890 |
| ref required / optional | This is the unique key you passed with your request while purchasing our product. string 01234567890 |
Resolving / Reporting a Transaction
You can automate the reporting of a transaction by calling our resolve transaction api.
This is useful if your customer/client complains that value where not received for a particular transactions.
You can specify the action you want us to take about the transaction
The action will only be carried out if a transaction actually failed, or value has not been given or it has not be delivered already.
Once a transaction has been refunded it can not be cancelled if value is still need for the transaction the transaction will need to be carried out afresh.
When a transaction is reprocessed you will not be recharged for it. Meaning your balance will remain the same!.
| FieldName Action {Required / Optional} | Description Type Example |
|---|---|
| transactionId required / ooptional | This is the unique transaction Id will responded back ot your request while purchasing our product string mtncg1gb_01234567890 |
| ref required / optional | This is the unique key you passed with your request while purchasing our product. string 01234567890 |
CallBack / Webhooks
Whenever a transaction is performed with us using our api endpoint and the initial status is not yet concluded('i.e' 'PENDING') when a response received.
Also if there is any changes concerning the status of any of your transaction, our server will send/trigger an event in which your application can listen to, in order to perform neccessary actions determined by you, depending on the the notification gotten.
For example if you implement webhooks and you bought an airtime through our api endpoint, if the status of the transaction from the response gotten is pending, once the transaction is successful or its status is determined we will immediately notify your callabck endpoint the transaction status and its neccessary details.
The webhook details contains
Transaction Update Webhook
This is the notification sent when the status if a transaction is altered(PENDING TO FAILED | SUCCESSFUL | REVERSED).
This notification parameters / details is similar to that of the json response gotten when a transaction was initiated the onle difference would be the transaction status and also thee value details sent with it if the transaction is successful. i.e
When you made a purchase whereby a valued pin is to be given (E.g Eledtricity Token, Airtime Epins, Examination Epins, Data Pins And So On). and this was not provided because the status is pending when this pins is available That is the transaction status is now successful the e-pins details would be passed as one of the parameter of the webhook notification
Refunds Update Webhook
This is the notification sent when the status of a transaction is changed to a refund i.e the tranasaction is cancelled and the a refund was sent to your wallet.
This notification update would contains the transaction Id , Reference Id (The Unique id provided by you)., The Reason While the transactions was cancel (WRONG NUMBER | WRONG NETWORK | PRODUCT NOT AVAILABLE | PLAN NOT AVAILABLE | CUSTOMER_REQUESTED | OTHERS)
Ideally a Successful Transaction cannot be refunded which means only defaulted transactions are refunded and if the refunded transaction is still required you can re initiate it a fresh with us.
Resolved Transaction Update Notification
Our api provideds developers the ability to resolve transaction automatedly with our api end.
When a Transaction is Submitted to endpoint with the aim of resolving it our server triggers a notification when the task is completed i.e if your request was reprocessing and the transaction is confirmed to be delivered a notification will be sent to your endpoint informing you of the actions that was taken and the conccluded transaction Status.
Ideally a Successful Transaction cannot be refunded which means only defaulted transactions are refunded and if the refunded transaction is still required you can re initiate it a fresh with us.
/// JSON EXAMPLEIMPORTANT NOTE
There are situations where a transaction can trigger more than one notification, An example is if you reported a transaction with us and the action you specify is refund, if your wish is confired Granted.
This Transaction Would Trigger the following Events- Transaction Update (since the transaction status has been changed to REFUNDED
- Refund Update (since the transaction has been cancelled and a refund has been processed.
- Resolved Transaction Update (since you made a resolve request and ideally we are to let your endpoint know what happens to the reported transaction.