Introduction
echo "Welcome to the Eyowo developer API reference!
As you read through this guide,
sample snippets will appear on this panel
to help you get up to speed.
Kindly visit https://developer.eyowo.com to create
a developer account."
const message = `
Welcome to the Eyowo developer API reference!\n
As you read through this guide,\n
sample snippets will appear on this panel\n
to help you get up to speed.\n
Kindly visit https://developer.eyowo.com to create\n
a developer account.`;
console.info(message);
message = "
Welcome to the Eyowo developer API reference!\n
As you read through this guide,\n
sample snippets will appear on this panel\n
to help you get up to speed.\n
Kindly visit https://developer.eyowo.com to create\n
a developer account."
puts message
fun main() {
val message = buildString {
it.append("Welcome to the Eyowo developer API reference!\n")
it.append("As you read through this guide,\n")
it.append("sample snippets will appear on this panel\n")
it.append("to help you get up to speed.\n\n")
it.append("Kindly visit https://developer.eyowo.com to create\n")
it.append("a developer account.")
}
println(message)
}
class Welcome {
public static void main(String[] args) {
StringBuilder builder = new StringBuilder();
builder.append("Welcome to the Eyowo developer API reference!\n")
builder.append("As you read through this guide,\n")
builder.append("sample snippets will appear on this panel\n")
builder.append("to help you get up to speed.\n\n")
builder.append("Kindly visit https://developer.eyowo.com to create\n")
builder.append("a developer account.")
System.out.print(builder.toString());
}
}
The Eyowo Developer API is a RESTful web service that provides developers with a powerful set of resources that can be utilized to build rich applications backed by Eyowo payment services.
The API makes use of standard HTTP request methods and response codes. The Developer API supports both form-encoded and standard JSON requests. All responses rendered by the API are in JSON format.
Feel free to make use of the sandbox to test integrations with the provided endpoints. It is a secure space created specifically for you to familiarize yourself with our services.
We are constantly working on new features to help you build more feature rich applications. As such we constantly update this documentation with new resources. Follow us @eyowo to stay up to date on new API releases.
Getting Started
The first step to integrating your application with the Eyowo API is the creation of a developer account. Navigate to the Eyowo developer website from a browser of your choice to register an account. A valid email address and password is required for registration.
Upon registration you will be redirected to the login page. Go ahead and login with your provided details. On successful login you will be redirected to your developer API dashboard.
Your dashboard provides you with tools that will help you:
- Create and manage multiple Eyowo applications.
- Manage user wallets you have access privileges to.
- View and generate application credentials.
Creating an Application
Having successfully registered and access the dashboard, let's go ahead and create a new application. Click the Create new App button and input a unique name for your application. You can name your app whatever you want but for this guide we will call it eyowo-js-test. Once that's done click submit. You should now see your app on the dashboard.
Application Credentials
There are two crucial credentials for every Eyowo app. They are:
- App Key: This is a security credential for all API requests. It is used to identify your application.
- App Secret: This is your application secret key.
Both your app key and app secret can be accessed via the dashboard by clicking your desired application. Your app secret can be revealed by clicking the Get Secret Key button on your dashboard.
Authentication
To authorize, use this code:
# With shell, you pass the X-App-Key header with each request
curl "api_endpoint_here"
-H "X-App-Key: <APP_KEY>"
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
The Eyowo developer API utilizes your application key to authenticate API requests.
Your app key should be sent via an X-App-Key HTTP request header as shown below:
X-App-Key: <APP_KEY>
In addition to your app secret there is one important headers to note when making direct HTTP calls.
This is the X-App-Wallet-Access-Token header.
- X-App-Wallet-Access-Token: This is a token belonging to an Eyowo user which gives you access to the wallet of a user. It is required for transaction types such as wallet to wallet transfers and wallet to bank transfers.
Validate User
curl --location --request POST "https://api.console.eyowo.com/v1/users/auth/validate" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--data "{
\"mobile\": \"2348000000000\"
}"
require 'net/http'
require 'json'
uri = URI('https://api.console.eyowo.com/v1/users/auth/validate')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-App-Key'] = '842e87acd5ef90caae15fb7bcdf882e9'
req.body = { mobile: '2348000000000' }.to_json
http.request(req)
end
puts res
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.validateUser({ mobile: '2348000000000' });
console.log(response)
})();
Response
{
"success": true,
"data": {
"user": {
"id": "OKHN8E4SS",
"mobile": "2348000000000"
}
},
"message": "Validation successful"
}
This endpoint facilitates the validation of a user via a given mobile number. Requests should be forwarded to the /v1/users/auth/validate URL path.
HTTP Request
POST https://api.console.eyowo.com/v1/users/auth/validate
Request Body.
The request body of the validate user request consists of a single attribute.
| Parameter | Type | Required | Description |
|---|---|---|---|
mobile |
string | true | Any string representation of a valid Nigerian mobile number. |
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting of the details of the validated user.
The user object contains the following attributes:
| Parameter | Type | Description |
|---|---|---|
id |
string | The unique identifier of the Eyowo user. |
mobile |
string | The corresponding phone number of the registered user. |
User Authorization
At times your application may required access to a user's wallet to perform transactions on behalf of a user. A user wallet token is required for this and it can be retrieved upon authorization from a user by login.
User Authorization Initiation Request
curl --location --request POST "https://api.console.eyowo.com/v1/users/auth" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--data "{
\"mobile\": \"2348000000000\",
\"factor\": \"sms\"
}"
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.authenticateUser(
{
mobile: '2348000000000',
factor: 'sms'
});
console.log(response)
})();
require 'net/http'
require 'json'
uri = URI('https://api.console.eyowo.com/v1/users/auth')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-App-Key'] = '842e87acd5ef90caae15fb7bcdf882e9'
req.body = {
mobile: "2348000000000",
factor: "sms"
}.to_json
http.request(req)
end
puts res
Response
{
"success": true,
"message": "Please enter the passcode sent to 2348000000000"
}
To initiate a user login request, call the user login endpoint with the mobile and factor request attributes.
Upon successful login initiation a passcode will be sent to the user's device via SMS. This passcode will be used in the
login validation step.
HTTP Request
POST https://api.console.eyowo.com/v1/users/auth
Request Body.
The request body of the validate user request consists of a single attribute.
| Parameter | Type | Required | Description |
|---|---|---|---|
mobile |
string | true | Any string representation of a valid Nigerian mobile number. |
factor |
string | true | The login verification method to be used. The currently supported value for this attribute issms. |
User Authorization Initiation Response
A successful request receives a response with an HTTP 200 status code. The table below describes the response parameters received from a successful login initiation request.
| Parameter | Type | Description |
|---|---|---|
success |
boolean | The unique identifier of the Eyowo user. |
message |
string | A success message. |
User Authorization Request
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.authenticateUser(
{
mobile: '2348000000000',
factor: 'sms',
passcode: '538245'
});
console.log(response)
})();
curl --location --request POST "https://api.console.eyowo.com/v1/users/auth" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--data "{
\"mobile\": \"2348000000000\",
\"factor\": \"sms\",
\"passcode\": \"538245\"
}"
Response
{
"success": true,
"message": "Wallet added successfully",
"data": {
"refreshToken": "5d07619d019bd118ae99786f3a34840d999b1e84",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkMDc2MTlkMDE5YmQxMThhZTk5Nzg2ZiIsIm1vYmlsZSI6IjIzNDgxODQyMDkxODgiLCJpYXQiOjE1NjA3NjQ4MjksImV4cCI6MTU2MDg1MTIyOX0.g90RxjYHhZJi9XVF1ZMYJQZu_rbUDXtPV77AjuE-HEU",
"expiresIn": 86400
}
}
To authorize a user login request, call the user login endpoint with the mobile, factor, and passcode request
attributes. Upon successful authorization the user will be logged in successfully.
HTTP Request
POST https://api.console.eyowo.com/v1/users/auth
Request Body.
The request body of the validate user request consists of a single attribute.
| Parameter | Type | Required | Description |
|---|---|---|---|
mobile |
string | true | Any string representation of a valid Nigerian mobile number. |
factor |
string | true | The login verification method to be used. The currently supported value for this attribute issms. |
passcode |
string | false | The passcode send to the verification medium of the user. Eyowo passcodes are numeric strings of length 6. |
User Authorization Response
A successful request receives a response with an HTTP 200 status code. The table below describes the response parameters received from a successful login initiation request.
| Parameter | Type | Description |
|---|---|---|
success |
boolean | The unique identifier of the Eyowo user. |
message |
string | A success message. |
data |
object | A JSON object containing an accessToken, refreshToken and expiresIn attribute - which defining the time in seconds to token expiry. |
Wallet Access Token Refresh
curl --location --request POST "https://api.console.eyowo.com/v1/users/accessToken" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--data "{
\"refreshToken\": \"5d1a8b13f9be2b7a62e0d1031dc48a6cbe1ae0ce\"
}"
Response
{
"success": true,
"data": {
"accessToken": "kyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZDI6IjVkMWE4YjEzZjliZTJiNmE2MmUwZDEwMyIsIm1vYmlsZSI6IjIzNDgxODQyMDkxODgiLCJpYXQiOjE1NjI1MzMwNDEsImV4cCI6MTU2MjYxOTQ0MX0.qyZqwrmIIMLloPGbL9q-3O64nQwYNg5DtzDE7B776dQ",
"expiresIn": 86400
}
}
This resource is used to refresh a wallet access token upon expiry.
HTTP Request
POST https://api.console.eyowo.com/v1/users/accessToken
Request Body.
The request body of the validate user request consists of a single attribute.
| Parameter | Type | Required | Description |
|---|---|---|---|
refreshToken |
string | true | Wallet refresh token. |
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting of the following.
| Parameter | Type | Description |
|---|---|---|
accessToken |
string | New wallet access token. |
expiresIn |
string | Token expiry. |
Balance
curl --location --request GET "https://api.console.eyowo.com/v1/users/balance" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--header "X-App-Wallet-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjNGVmZTQ2NWMwOTJmNWE1NGE1ZjVhNSIsIm1vYmlsZSI6IjIzNDkwOTU4MDE3NzIiLCJpYXQiOjE1NDg2ODA3NzQsImV4cCI6MTU0ODc2NzE3NH0.hUjwqiSfk1J6HaMwDkNsKkOJdTaEoT0wO54pFFDCyzA"
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.getBalance(
{
mobile: '2348000000000',
accessToken: '<X-App-Wallet-Access-Token>'
});
console.log(response)
})();
Response
{
"success": true,
"data": {
"user": {
"id": "OKHN8E4SS",
"mobile": "2348000000000",
"balance": 526548935
}
}
}
This resource is used to retrieve the wallet balance of an Eyowo user. Requests should be forwarded to the /v1/users/balance endpoint.
HTTP Request
GET https://api.console.eyowo.com/v1/users/balance
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting user object.
The user object contains the following attributes:
| Parameter | Type | Description |
|---|---|---|
id |
string | The unique identifier of the Eyowo user. |
mobile |
string | The corresponding phone number of the registered user. |
balance |
long | The wallet balance of the user in Kobo. |
Bank
Get Banks
curl --location --request GET "https://api.console.eyowo.com/v1/queries/banks" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9"
Response
{
"success": true,
"data": {
"banks": [
{
"bankCode": "000014",
"bankName": "ACCESS BANK"
},
{
"bankCode": "000010",
"bankName": "ECOBANK"
},
{
"bankCode": "000016",
"bankName": "FIRST BANK OF NIGERIA"
},
{
"bankCode": "000003",
"bankName": "FIRST CITY MONUMENT BANK"
},
{
"bankCode": "000013",
"bankName": "GTBANK PLC"
},
{
"bankCode": "000020",
"bankName": "HERITAGE BANK"
},
{
"bankCode": "000012",
"bankName": "STANBIC IBTC BANK"
},
...
]
}
}
This resource is used to retrieve a list of available banks for bank transfer transactions.
HTTP Request
GET https://api.console.eyowo.com/v1/queries/banks
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting banks object.
The banks object contains an array of available banks. Each array item contains a bank name and bank code.
Transfer
Transfer to Phone
curl --location --request POST "https://api.console.eyowo.com/v1/users/transfers/phone" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--header "X-App-Wallet-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjNGVmZTQ2NWMwOTJmNWE1NGE1ZjVhNSIsIm1vYmlsZSI6IjIzNDkwOTU4MDE3NzIiLCJpYXQiOjE1NDg2ODA3NzQsImV4cCI6MTU0ODc2NzE3NH0.hUjwqiSfk1J6HaMwDkNsKkOJdTaEoT0wO54pFFDCyzA" \
--data "{
\"mobile\": \"2348000000000\",
\"amount\": 100000
}"
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.transferToPhone(
{
amount: 10000,
mobile: '2348000000000',
accessToken: '<X-App-Wallet-Access-Token>'
});
console.log(response)
})();
Response
{
"success": true,
"data": {
"transaction": {
"reference": "5c4f2d205d73fe5abe0a4393",
"amount": 10000
}
},
"message": "Transaction successful"
}
This resource is used to transfer funds from a user wallet to a given phone number.
HTTP Request
POST https://api.console.eyowo.com/v1/users/transfers/phone
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
amount |
long | true | Amount to transfer in Kobo. |
mobile |
string | true | Phone number of user to transfer to. |
Transfer to Bank
curl --location --request POST "https://api.console.eyowo.com/v1/users/transfers/bank" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--header "X-App-Wallet-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjNGVmZTQ2NWMwOTJmNWE1NGE1ZjVhNSIsIm1vYmlsZSI6IjIzNDkwOTU4MDE3NzIiLCJpYXQiOjE1NDg2ODA3NzQsImV4cCI6MTU0ODc2NzE3NH0.hUjwqiSfk1J6HaMwDkNsKkOJdTaEoT0wO54pFFDCyzA" \
--data "{
\"accountName\": \"SEGUN AHMED OKOROMA\",
\"accountNumber\": \"2079151995\",
\"bankCode\": \"000004\",
\"amount\": 100000
}"
const eyowo = require('eyowo-js');
const appKey = process.env.APP_KEY;
const appSecret = process.env.APP_SECRET;
const client = new eyowo.Client({
appKey,
appSecret,
environment: 'production'
});
(async () => {
const response = await client.transferToBank(
{
amount: 10000,
accountName: 'John Doe',
accountNumber: '<ACCOUNT_NUMBER>',
bankCode: '<BANK_CODE>',
accessToken: '<X-App-Wallet-Access-Token>',
});
console.log(response)
})();
Response
{
"success": true,
"data": {
"transaction": {
"reference": "5c4f2d205d73fe5abe0a4393",
"amount": 10000
}
},
"message": "Transaction successful"
}
This resource is used to transfer money from a user wallet to a given bank account.
HTTP Request
POST https://api.console.eyowo.com/v1/users/transfers/bank
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
amount |
long | true | Any string representation of a valid Nigerian mobile number. |
accountName |
string | true | Name of account owner. |
accountNumber |
string | true | Account number to transfer funds to. |
bankCode |
string | true | Unique code of bank. |
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting user object.
The user object contains the following attributes:
| Parameter | Type | Description |
|---|---|---|
id |
string | The unique identifier of the Eyowo user. |
mobile |
string | The corresponding phone number of the registered user. |
balance |
long | The wallet balance of the user in Kobo. |
Virtual Top Up (VTU)
Buy VTU
curl --location --request POST "https://api.console.eyowo.com/v1/users/payments/bills/vtu" \
--header "Content-Type: application/json" \
--header "X-App-Key: 842e87acd5ef90caae15fb7bcdf882e9" \
--header "X-App-Wallet-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVjNGVmZTQ2NWMwOTJmNWE1NGE1ZjVhNSIsIm1vYmlsZSI6IjIzNDkwOTU4MDE3NzIiLCJpYXQiOjE1NDg2ODA3NzQsImV4cCI6MTU0ODc2NzE3NH0.hUjwqiSfk1J6HaMwDkNsKkOJdTaEoT0wO54pFFDCyzA" \
--data "{
\"mobile\": \"2348000000000\",
\"amount\": 10000,
\"provider\": \"etisalat\"
}"
This resource is used to make virtual top ups.
HTTP Request
POST https://api.console.eyowo.com/v1/users/payments/bills/vtu
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
mobile |
string | true | Any string representation of a valid Nigerian mobile number. |
amount |
long | true | Amount in Kobo. |
provider |
string | true | Billing provider to make virtual top up. (etisalat, glo, airtel, mtn) |
Response
A successful request receives a response with an HTTP 200 status code with a response body containing a data object consisting user object.
The user object contains the following attributes:
| Parameter | Type | Description |
|---|---|---|
id |
string | The unique identifier of the Eyowo user. |
mobile |
string | The corresponding phone number of the registered user. |
balance |
long | The wallet balance of the user in Kobo. |
Errors
The Eyowo Developer API utilizes the following HTTP status codes to indicate errors:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The kitten requested is hidden for administrators only. |
| 404 | Not Found -- The specified kitten could not be found. |
| 405 | Method Not Allowed -- You tried to access a kitten with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The kitten requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're requesting too many kittens! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |