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 the 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 | BALANCEPERIODIC_BALANCE | GET /v2/callback?record={RECORD ID HERE}&method=BALANCE |
| Income | INCOME | GET /v2/callback?record={RECORD ID HERE}&method=INCOME |
| Transactions | TRANSACTIONSPERIODIC_TRANSACTIONS | GET /v2/callback?record={RECORD ID HERE}&method=TRANSACTIONS |
| Payment | PAYMENTPAYMENT_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.
Call the https://api.okra.ng/v2/callback/trigger endpoint and pass either
- a record ID
- an array of record IDs
- or a valid URL you'd like to direct 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": {}
}
Note that the records array accepts a maximum of 100 record ID's