Documentation Powered by ReDoc

EffesEYE Platform API (2020-10)

Download OpenAPI specification:Download

Charles Odili: chaluwa@gmail.com License: MIT Terms of Service

Charles Odili just joined a fintech startup, EffesEYE, and was asked to lead the development of an urgent project on the table, a simple billing application.

In order to have a view on the practicality of this new product, the Board asked that he develop and present an MVP of this product to them at the next Management meeting.

Odili was required to build an MVP on the FSI Sandbox, integrated into the APIs of the available Banks and services of the Sandbox. This application can buy telephone credit, pay electricity bills and Pay TV bills (DSTV, Startimes, etc).

Odili adopted an API-first approach, and this is the documentation convering the API that drives the services and features the EffesEYE billing (MVP) platform provides to customers.

The API is deployed at https://effeseye-api.herokuapp.com, is managed by a secure admin application at https://effeseye-admin.netlify.app, and is available for customers via an installable Progressive Web App at https://effeseye-admin.netlify.app

Authentication

Authorization

The HTTP Authorization header containing a valid access token designated as Bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

airtime

Payment service endpoint

Buy airtime credit, pay for electricity or TV subscription with this endpoint

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

service
required
string [ 2 .. 11 ] characters
Enum: "airtime" "electricity" "tv"

The service you want to pay for

Request Body schema: application/json

HTTP request payload for the payment service

amount
required
integer

The amount to pay for the service

currency
required
string 3 characters
Enum: "NGN" "USD"

The ISO 4217 currency code the amount is expressed in

provider
required
string

The provider whose service is being purchased:

For airtime, this could be Airtel, MTN, Glo, 9Mobile e.t.c.

For PayTV, this could be DSTV, Startimes, GoTV e.t.c

For electricity, this could be EKDC, IKEDC, BEDC, IBEDC e.t.c

sendTo
required
string

The corresponding phone number, meter number, or TV subscription Id to credit this recharge to

accountToDebit
required
string 10 characters

The verified (NUBAN) bank account to debit for this payment

Responses

Request samples

Content type
application/json
Example
airtime-example
airtime-example
electricity-example
tv-example
{
  • "amount": 1000,
  • "currency": "NGN",
  • "provider": "Airtel",
  • "sendTo": "+2348138145472",
  • "accountToDebit": "0037514056"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "paymentId": "string",
  • "status": "PENDING",
  • "details": { }
}

Payment enquiry / status endpoint

Query the status of a payment transaction

Authorizations:
Authorization
path Parameters
paymentId
required
string

The request id of a previous airtime recharge request

version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment status",
  • "paymentId": "45934508043-583",
  • "status": "SUCCEEDED"
}

BVN

The user registration and account creation endpoint

Creates a new user account on the EffesEYE platform

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data needed to create the new account

bvn
required
string 11 characters

The unique Bank Verification Number (BVN) of the new user

pswd
required
string <password> >= 6 characters

The user's password

email
required
string <email> >= 8 characters

The user's email address

Responses

Request samples

Content type
application/json
{
  • "bvn": "12345678901",
  • "pswd": "pa$$word",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Account created",
  • "accountId": "5645f-5dw4358-hgf-34545345345"
}

email

The user registration and account creation endpoint

Creates a new user account on the EffesEYE platform

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data needed to create the new account

bvn
required
string 11 characters

The unique Bank Verification Number (BVN) of the new user

pswd
required
string <password> >= 6 characters

The user's password

email
required
string <email> >= 8 characters

The user's email address

Responses

Request samples

Content type
application/json
{
  • "bvn": "12345678901",
  • "pswd": "pa$$word",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Account created",
  • "accountId": "5645f-5dw4358-hgf-34545345345"
}

PWA client user authentication

The endpoint for authenticating users and granting access into the client application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for user authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "login successful",
  • "authToken": "567459867405764509769457694"
}

Admin user authentication

The endpoint for authenticating administrators and granting access into the admin application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for admin authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "successful login",
  • "authToken": "56745967457640597645967405492-348-239-42"
}

phone number

The user registration and account creation endpoint

Creates a new user account on the EffesEYE platform

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data needed to create the new account

bvn
required
string 11 characters

The unique Bank Verification Number (BVN) of the new user

pswd
required
string <password> >= 6 characters

The user's password

email
required
string <email> >= 8 characters

The user's email address

Responses

Request samples

Content type
application/json
{
  • "bvn": "12345678901",
  • "pswd": "pa$$word",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Account created",
  • "accountId": "5645f-5dw4358-hgf-34545345345"
}

registration

The user registration and account creation endpoint

Creates a new user account on the EffesEYE platform

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data needed to create the new account

bvn
required
string 11 characters

The unique Bank Verification Number (BVN) of the new user

pswd
required
string <password> >= 6 characters

The user's password

email
required
string <email> >= 8 characters

The user's email address

Responses

Request samples

Content type
application/json
{
  • "bvn": "12345678901",
  • "pswd": "pa$$word",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Account created",
  • "accountId": "5645f-5dw4358-hgf-34545345345"
}

ping

A meta endpoint for retrieving the server's pulse

Get a pulse of the API service

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "EffesEYE API, Tuesday 4th October 2025"
}

Get the server's pulse

Get a pulse of the server

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

The catch all / fall-back API endpoint

A catch-all / fall-back endpoint for the API

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

A catch all / fall-back endpoint

A catch all / fall-back endpoint

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

auth

PWA client user authentication

The endpoint for authenticating users and granting access into the client application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for user authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "login successful",
  • "authToken": "567459867405764509769457694"
}

Admin user authentication

The endpoint for authenticating administrators and granting access into the admin application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for admin authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "successful login",
  • "authToken": "56745967457640597645967405492-348-239-42"
}

Verify a given authentication token

Checks the validity and expiry of a token, and only returns true for tokens that have a valid cryptographic signature and have not expired

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json
token
required
string

The token to verify

Responses

Request samples

Content type
application/json
{
  • "token": "67760385-30483gdlfkglkdfgtu9564967540764674hgdflhglkfhl2309-5403485"
}

Response samples

Content type
application/json
{
  • "verified": true
}

login

PWA client user authentication

The endpoint for authenticating users and granting access into the client application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for user authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "login successful",
  • "authToken": "567459867405764509769457694"
}

Admin user authentication

The endpoint for authenticating administrators and granting access into the admin application

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

The HTTP request payload of data for admin authentication

pswd
required
string >= 6 characters

The user account password

email
required
string <email>

The user account email

Responses

Request samples

Content type
application/json
{
  • "pswd": "pa55W0rd",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "successful login",
  • "authToken": "56745967457640597645967405492-348-239-42"
}

spec

Get the API specification

Retrieve the EffesEYE platform API specification

path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

admin

Fetch user account data

Fetch a collection of registered users (accounts) on the platform

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data":
    [
    ]
}

Fetch payments collection

Fetch a collection of payments done on the patform

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment successful",
  • "data":
    [
    ]
}

user-data

Fetch user account data

Fetch a collection of registered users (accounts) on the platform

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "success",
  • "data":
    [
    ]
}

payments

Payment service endpoint

Buy airtime credit, pay for electricity or TV subscription with this endpoint

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

service
required
string [ 2 .. 11 ] characters
Enum: "airtime" "electricity" "tv"

The service you want to pay for

Request Body schema: application/json

HTTP request payload for the payment service

amount
required
integer

The amount to pay for the service

currency
required
string 3 characters
Enum: "NGN" "USD"

The ISO 4217 currency code the amount is expressed in

provider
required
string

The provider whose service is being purchased:

For airtime, this could be Airtel, MTN, Glo, 9Mobile e.t.c.

For PayTV, this could be DSTV, Startimes, GoTV e.t.c

For electricity, this could be EKDC, IKEDC, BEDC, IBEDC e.t.c

sendTo
required
string

The corresponding phone number, meter number, or TV subscription Id to credit this recharge to

accountToDebit
required
string 10 characters

The verified (NUBAN) bank account to debit for this payment

Responses

Request samples

Content type
application/json
Example
airtime-example
airtime-example
electricity-example
tv-example
{
  • "amount": 1000,
  • "currency": "NGN",
  • "provider": "Airtel",
  • "sendTo": "+2348138145472",
  • "accountToDebit": "0037514056"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "paymentId": "string",
  • "status": "PENDING",
  • "details": { }
}

Payment enquiry / status endpoint

Query the status of a payment transaction

Authorizations:
Authorization
path Parameters
paymentId
required
string

The request id of a previous airtime recharge request

version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment status",
  • "paymentId": "45934508043-583",
  • "status": "SUCCEEDED"
}

Fetch payments collection

Fetch a collection of payments done on the patform

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment successful",
  • "data":
    [
    ]
}

electricity

Payment service endpoint

Buy airtime credit, pay for electricity or TV subscription with this endpoint

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

service
required
string [ 2 .. 11 ] characters
Enum: "airtime" "electricity" "tv"

The service you want to pay for

Request Body schema: application/json

HTTP request payload for the payment service

amount
required
integer

The amount to pay for the service

currency
required
string 3 characters
Enum: "NGN" "USD"

The ISO 4217 currency code the amount is expressed in

provider
required
string

The provider whose service is being purchased:

For airtime, this could be Airtel, MTN, Glo, 9Mobile e.t.c.

For PayTV, this could be DSTV, Startimes, GoTV e.t.c

For electricity, this could be EKDC, IKEDC, BEDC, IBEDC e.t.c

sendTo
required
string

The corresponding phone number, meter number, or TV subscription Id to credit this recharge to

accountToDebit
required
string 10 characters

The verified (NUBAN) bank account to debit for this payment

Responses

Request samples

Content type
application/json
Example
airtime-example
airtime-example
electricity-example
tv-example
{
  • "amount": 1000,
  • "currency": "NGN",
  • "provider": "Airtel",
  • "sendTo": "+2348138145472",
  • "accountToDebit": "0037514056"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "paymentId": "string",
  • "status": "PENDING",
  • "details": { }
}

Payment enquiry / status endpoint

Query the status of a payment transaction

Authorizations:
Authorization
path Parameters
paymentId
required
string

The request id of a previous airtime recharge request

version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment status",
  • "paymentId": "45934508043-583",
  • "status": "SUCCEEDED"
}

paytv

Payment service endpoint

Buy airtime credit, pay for electricity or TV subscription with this endpoint

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

service
required
string [ 2 .. 11 ] characters
Enum: "airtime" "electricity" "tv"

The service you want to pay for

Request Body schema: application/json

HTTP request payload for the payment service

amount
required
integer

The amount to pay for the service

currency
required
string 3 characters
Enum: "NGN" "USD"

The ISO 4217 currency code the amount is expressed in

provider
required
string

The provider whose service is being purchased:

For airtime, this could be Airtel, MTN, Glo, 9Mobile e.t.c.

For PayTV, this could be DSTV, Startimes, GoTV e.t.c

For electricity, this could be EKDC, IKEDC, BEDC, IBEDC e.t.c

sendTo
required
string

The corresponding phone number, meter number, or TV subscription Id to credit this recharge to

accountToDebit
required
string 10 characters

The verified (NUBAN) bank account to debit for this payment

Responses

Request samples

Content type
application/json
Example
airtime-example
airtime-example
electricity-example
tv-example
{
  • "amount": 1000,
  • "currency": "NGN",
  • "provider": "Airtel",
  • "sendTo": "+2348138145472",
  • "accountToDebit": "0037514056"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "paymentId": "string",
  • "status": "PENDING",
  • "details": { }
}

Payment enquiry / status endpoint

Query the status of a payment transaction

Authorizations:
Authorization
path Parameters
paymentId
required
string

The request id of a previous airtime recharge request

version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Responses

Response samples

Content type
application/json
{
  • "message": "payment status",
  • "paymentId": "45934508043-583",
  • "status": "SUCCEEDED"
}

NUBAN

Verify and add a (NUBAN) bank account

Verify and add a NUBAN (bank account) number to a user's EffesEYE account, allowing them initiate payments from the bank accounts

Authorizations:
Authorization
path Parameters
version
required
string 7 characters ^\d{4}-\d{2}$
Example: 2020-10

The API version

Request Body schema: application/json

HTTP request payload to add a bank account

nuban
required
string 10 characters

The NUBAN account number

bankname
required
string >= 3 characters

The name of the Bank

Responses

Request samples

Content type
application/json
{
  • "nuban": "0037514056",
  • "bankname": "UBA"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "FAILED"
}