Introduction

A Comprehensive reference for integrating with Okra API endpoints

AN OVERVIEW

Okra offers a range of services that make it possible for you to access the financial accounts of users and make direct debits in minutes. On this page, we'll go over some of the services we offer to give you a quick overview of what is obtainable with Okra.

Get API Access

To gain access to the Okra API, create an account on the Okra developer dashboard. Once you’ve completed the signup process and acknowledged our terms, we’ll provide a live client_token and secret via the Dashboard.

API Headers

The Okra API uses POST and GET requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. All requests must include a Content-Type of application/json and the body must be valid JSON.

Every Okra API request expects a bearer token as the 'Authorization' header. The secret key should be used as the bearer token. You can find your secret key here.

API Host

Base URL

Environment

https://api.okra.ng/sandbox/v2/

production-sandbox

https://api.okra.ng/v2/

production

Authorization

With Okra, you can authorize your API calls by including your secret key in the Authorization header of every request you make.

Secret Keys should be kept confidential and only stored on your own servers. Your account’s secret API key can perform any API request to Okra without restriction.

📘

Authorization Sample

Authorization: Bearer XXXXXXXYYYYYYYZZZZZZZ

🚧

All API requests must be made over HTTPS.

Remember also that API requests made without authorization will fail with the status code 401: Unauthorized

WebHooks

At Okra we use Webhooks to notify data updates in your app, only if you have it configured in an app on your Dashboard.

Overview

What is a Webhook?
At Okra, webhooks are a very important part of our process. We use webhooks to communicate with different services. Primarily we use webhooks to share information about an event that happened on your account with you. These events could range from a successful transaction to a failed transaction or even a direct debit on your account.

Theoretically, a webhook URL is like a transport medium you specified on your server to receive details about an event that occurred on your Okra account. The event details we send to you contain information about that particular event, including the type of event that occurred and the data associated with it.

Setting up Webhooks

How to set up your webhook

Setting up Webhook

Add a webhook URL in the app you're using its public and private keys.

📘

Specify your environment

We have webhook URL and Token for both production and sandbox environments

Example Incoming Webhook

If you're using callbacks with any product, you'll receive a callback when Okra finishes processing the product's data for the Record. Once you receive this callback, you can make an API call to retrieve the product's data.

Below you will see an example of an incoming webhook from Okra's servers. The below example is for AUTH but you will receive webhooks for all products.

Note: Respond with a status code of 200 when you receive the webhook.

📘

Webhook

Note that If your webhook script performs complex logic or makes network calls, it's possible that the script would time out before Okra sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 200 HTTP status code, and then perform the rest of its duties"

Webhook Example Implementation

// Javascript  Implementation

const secret = process.env.OKRA_WEBHOOK_KEY;
function verifyWebhook(req, res, next) {
  
  //isVerified is a function that verifies the token
    if (!isVerified(req.headers['Okra-Auth'])) {
        return res.status(401).json({
            message: "Unauthorized request."
        });
    }
    next();
}
router.post('/create', verifyWebhook, (req, res) => {
    const webhook = req.body;
  switch(webhook.event) {
        case "okra.event":
            // do something with webhook.data.account;
            break;
    }
    return res.sendStatus(200);
});

Webhook Response

If you've set up webhook notifications for your account, we will also send you a response in the format below:

{
  method: 'IDENTITY',
  callback_type: 'IDENTITY',
  callback_code: 'PRODUCT_IS_READY',
  type: 'CALLBACK',
  code: 'PRODUCT_IS_READY',
  callbackURL: 'https://e2c550b71c3f.ngrok.io/v2/data/login/',
  env: 'production-sandbox',
  status: 'is_success',
  started_at: '2021-04-23T07:39:10.133Z',
  ended_at: '2021-04-23T07:39:35.376Z',
  message: 'Record callback started!',
  options: { },
  bankName: 'Access Bank',
  bankType: 'ind',
  bankId: '5d6fe57a4099cc4b210bbec0',
  bankSlug: 'access-bank',
  record: '6082799e5ad7d31243eb6d43',
  login_type: 'bank',
  customerId: '602d7a668299304ef0df55v2',
  extras: {},
  owner: '5d9288ea182d3d000cb7c481'
}
{
  "method": "AUTH",
  "callback_type": "AUTH",
  "callback_code": "AUTH_SUCCESS",
  "type": "CALLBACK",
  "code": "AUTH_SUCCESS",
  "callbackURL": "",
  "env": "production-sandbox",
  "status": "is_success",
  "started_at": "2021-01-15T13:14:38.359Z",
  "ended_at": "2021-01-15T13:14:38.359Z",
  "message": "Record callback completed!",
  "bankName": "Guaranty Trust Bank",
  "bankType": "ind",
  "bankId": "",
  "bankSlug": "guaranty-trust-bank",
  "record": "",
  "callback_url": "",
  "login_type": "mobile",
  "customerId": ""
}
{
  "method": "IDENTITY",
  "callback_type": "IDENTITY",
  "callback_code": "PRODUCT_IS_READY",
  "type": "CALLBACK",
  "code": "PRODUCT_IS_READY",
  "callbackURL": "https://webhook",
  "env": "production",
  "status": "is_success",
  "started_at": "2021-02-15T06:43:50.554Z",
  "ended_at": "2021-02-15T06:43:50.554Z",
  "message": "Record callback started!",
  "bankName": "Kuda Bank",
  "bankType": "ind",
  "bankId": "5f0cf73e8a8bcc18b8156ad7",
  "bankSlug": "kuda-bank",
  "record": "602a1807b9fdfa599cd3a0b5",
  "login_type": "bank",
  "customerId": "5f636ad0894dbb43795c4e8e",
  "options": {},
  "identity": {
    "id": "5f636ad074b8fde585241eb6",
    "bvn": "22166993390",
    "firstname": "Gaven",
    "middlename": "Big Man"
    "lastname": "Belson",
    "email": [
      "[email protected]"
    ],
    "name": "GAVEN BELSON",
    "fullname": "GAVEN BELSON",
    "dob": "1974-03-01T00:00:00",
    "gender": "male",
    "marital_status": "single",
    "phone": [
      "+19198739291",
      "+18473893931"
    ],
    "address": [
      "9, Huli Blvd."
    ],
    "aliases": [
      "Gav"
    ],
    "details": "https://api.okra.ng/v2/callback?record=602a1807b9fdfa599cd3a0b3&method=IDENTITY",
    "customer": "5f636ad0894dbb43795c4e83",
    "bank": "5f0cf73e8a8bcc18b8156ad7",
    "env": "production"
  }
}
{
  "method": "BALANCE" or "PERIODIC_BALANCE",
  "callback_type": "BALANCE",
  "callback_code": "BALANCE_SUCCESS",
  "type": "CALLBACK",
  "code": "BALANCE_SUCCESS",
  "callbackURL": "",
  "env": "production",
  "status": "is_success",
  "started_at": "2021-02-15T06:43:51.219Z",
  "ended_at": "2021-02-15T06:43:51.219Z",
  "message": "Record callback started!",
  "bankName": "",
  "bankType": "ind",
  "bankId": "",
  "bankSlug": "",
  "record": "",
  "callback_url": "",
  "nuban": "",
  "login_type": "bank",
  "customerId": ""
}
{
  "method": "TRANSACTIONS",
  "callback_type": "TRANSACTIONS",
  "callback_code": "PRODUCT_IS_READY",
  "type": "CALLBACK",
  "code": "PRODUCT_IS_READY",
  "callbackURL": "",
  "env": "production",
  "status": "is_success",
  "started_at": "2021-02-15T06:44:50.472Z",
  "ended_at": "2021-02-15T06:44:50.472Z",
  "message": "Record callback started!",
  "bankName": "",
  "bankType": "ind",
  "bankId": "",
  "bankSlug": "",
  "record": "",
  "callback_url": "",
  "nuban": "",
  "login_type": "bank",
  "customerId": "",
  "options": {}
}
{
  "method": "INCOME",
  "callback_type": "INCOME",
  "callback_code": "INCOME_FAILED",
  "type": "CALLBACK",
  "code": "INCOME_FAILED",
  "callbackURL": "",
  "env": "production",
  "status": "is_failed",
  "started_at": "2021-02-15T06:44:50.770Z",
  "ended_at": "2021-02-15T06:44:50.770Z",
  "message": "Record callback started!",
  "bankName": "",
  "bankType": "ind",
  "bankId": "",
  "bankSlug": "",
  "record": "",
  "callback_url": "",
  "login_type": "bank",
  "customerId": ""
}
{
  "method": "PAYMENT",
  "callback_type": "PAYMENT_RECURRING" or "PAYMENT",
  "schedule": {
    "interval": "monthly",
    "startDate": "2021-02-01",
    "endDate": null,
    "history": [
      ...array of payment ID's...
    ],
    "current_amount": 1000
  },
  "callback_code": "PAYMENT_FAILED",
  "type": "CALLBACK",
  "code": "PAYMENT_FAILED",
  "callbackURL": "",
  "env": "production-sandbox",
  "status": "is_failed",
  "started_at": "2021-02-17T14:18:37.608Z",
  "ended_at": "2021-02-17T14:18:40.083Z",
  "message": "Record callback started!",
  "bankName": "Guaranty Trust Bank",
  "bankType": "ind",
  "bankId": "",
  "bankSlug": "guaranty-trust-bank",
  "record": "",
  "callback_url": ""
}

Checking a Webhook status

curl -X GET https://api.okra.ng/v2/callback?record={RECORD}&method=METHOD
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>

Product Callbacks/Webhooks

Products

Methods

Endpoints

auth

AUTH

GET /v2/callback?record={RECORD ID HERE}&method=AUTH

identity

IDENTITY

GET /v2/callback?record={RECORD ID HERE}&method=IDENTITY

balance

BALANCE
PERIODIC_BALANCE

GET /v2/callback?record={RECORD ID HERE}&method=BALANCE

Income

INCOME

GET /v2/callback?record={RECORD ID HERE}&method=INCOME

Transactions

TRANSACTIONS
PERIODIC_TRANSACTIONS

GET /v2/callback?record={RECORD ID HERE}&method=TRANSACTIONS

Payment

PAYMENT
PAYMENT_RECURRING

GET /v2/callback?record={RECORD ID HERE}&method=PAYMENT

WebHook Trigger

Overview

The webhook trigger can come in very handy if you need to get the webhooks associated with a particular record id(s), in scenarios where the server goes down unexpectedly or you want to send webhooks to a different server.

You can use the webhook trigger to check the status of a webhook by supplying their record id(s) as the payload to the webhook trigger endpoint.

The way these works is by, calling this endpoint https://api.okra.ng/v2/callback/trigger, and passing the record id or an array of record id(s), or maybe a valid URL you'd like to redirect the webhooks to.

payload = {
     records: ["60b7be20ca7ce542d906e029", "60b7bc9aca7ce542d906e026"] //array of recordIds
     url: "https://yourcompany/webhooks/okra"//callback_url (optional), it default to your saved callback_url
}
{
"status": "success",
"messgae": "webhook trigger successfully initiated",
"data": {}
}

:notebook:   Note that the records array accepts a maximum of 100 record ID's