API Overview

Here, you’ll find detailed information about our APIs – what they’re for, how to use them and when to use them.

In order to start using Epay’s APIs to receive and/or disburse payments, you would need to have an Epay Account and also create an Integration. Head over to our Signup page to create a new Epay account.

Kindly note that your email and telephone will be verified.


Introduction

The Epay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.

Once registered, log into your account and head over to your settings sections on your dashboard to generate a Merchant Key. This Key should be kept confidential, as it would grant you access to all protected API Resources as well as direct incoming funds to your Epay Wallet.

To help you get oriented with Epay’s API and what it can help you do, let’s start by defining some basics:

  • The endpoints listed are to be applied to the base Url https://epaygh.com/api
  • All payments received are instantly deposited into your Epay wallet
  • All API endpoints except Authorization requires authentication
  • An Integration must be created on your Epay account to start using the API
  • All API requests must be made over HTTPS.
  • All Bulk fetches via a “list” endpoint are Paginated
  • All API endpoints are versioned
  • All Charge API allow payments from only our payment methods


API Resources / Endpoints

Resource Name Endpoint Url Description Last Updated
Authentication /v1/token This endpoint allows to retrieve a token
which will be used to authenticate or
gets you access to all protected API
Resources or endpoints.

All tokens expire after 1 hour 		25th Jan. 2019
Charges /v1/charge This single endpoint allows you to
charge both mobile money accounts
and Credit Cards into your Epay wallet.

All tokens expire after 1 hour 		25th Jan. 2019
Customers /v1/customers This endpoint allows you to create a
customer, retrieve customer details
and all transactions by a specific customer,

All tokens expire after 1 hour 		25th Jan. 2019
Transactions /v1/transactions This endpoint returns a list of all
transactions under your account and
also allows you to retrieve information
for a specific transaction or check the
status of a transaction

All tokens expire after 1 hour 		25th Jan. 2019


HTTP Status Code Summary

Status Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable,
often due to missing a
required parameter.
401 - Unauthorized No valid Access token,
merchant_key, app_id
or app_secret provided.
402 - Request Failed The parameters were valid
but the request failed.
404 - Not Found The requested resource
doesn't exist.
402 - Request Failed The parameters were
valid but the request failed.
409 - Conflict The request conflicts
with another request
429 - Too Many Requests Too many requests hit the
API too quickly. We
recommend an exponential
backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong
on our end. (These are rare.)


Handling Errors

Error Type Description
authentication_error Failure to properly
authenticate yourself
in the request.
invalid_request_error Invalid request errors
arise when your request
has invalid parameters.
momo_error Mobile Money wallet errors
are the most common type of
error you should expect to
handle. They result when the
user enters a mobile money
wallet that can't be charged
for some reason.
api_error API errors cover any other
type of problem (e.g., a
temporary problem with our
servers), and are extremely uncommon.


Example API Error Responses

The API by default returns almost the same content structure when a call fails. Please take note of the structure below since this will no longer be mentioned in the documentation of the various individual calls.

{
    "success": false,
    "error_type": "authentication_error",
    "message": "We couldn't verify your identity!"
}
{
    "success": false,
    "error_type": "invalid_request_error",
    "message": "Not a valid API request with missing parameters"
}
{
    "success": false,
    "error_type": "authentication_error",
    "message": "Your identity couldn't be validated!"
}

{
    "success": false,
    "error_type": "momo_error",
    "message": "Ooops! We encountered an issue trying to charge 
    the mobile wallet"
}

Next, learn more about our API Authentication.