Integration

How to set up your app with Okra on the web.

JS library for implementing Okra. The okrajs-npm module can be found here.

All accounts connected to Okra are done via the widget (Okrajs). The API only allows you access to accounts that have been connected.

Installing

Using npm:

$ npm install npm-okrajs

Using yarn:

$ yarn add npm-okrajs

Using CDN:

<script src="https://cdn.okra.ng/v1/bundle.js"></script>

Usage

For JS frameworks import it and use

import Okra from 'npm-okrajs'

For others, just use

Okra.buildWithOptions({
name: 'Peter the Builder',
env: 'production-sandbox',
key: '', //Your key from the Okra dashboard
token: '', //your token from the okra dashboard
onSuccess: function(data){
console.log('options success', data)
},
onClose: function(){
console.log('options close')
}
})
Okra.buildWithShortUrl({
short_url: '', //Your short url from the link builder
})

Okra.buildWithOptions Options

Name

Type

Required

Default Value

Description

key

String

yes

Your public key from your Okra Dashboard.

token

String

yes

Your token from your Okra Dashboard.

env

String

no

production

production(live)/production-sandbox (test)

products

Array

yes

['Auth']

The Okra products you want to use with the widget.

logo

String(URL)

no

Okra's Logo

name

String

no

Your Company's name

Name on the widget

color

HEX

no

#3AB795

Theme on the widget

limit

Number

no

24

Statement length

filter

Object

no

Filter for widget

isCorporate

Boolen

no

false

Corporate or Individual account

connectMessage

String

no

Instruction to connect account

Guarantors

Boolean

no

widget_success

String

no

Widget Success Message

widget_failed

String

no

Widget Failed Message

callback_url

String(Url)

no

redirect_url

String(Url)

no

Specify a URL to your success page. Okra fires the redirect when the process is completed.

currency

String

no

NGN

Wallet to bill

exp

Date

no

Won't expire

Expiry date of widget

options

Object

no

You can pass a object custom values eg id

onSuccess

Function

no

Action to perform after widget is successful

onClose

Function

no

Action to perform if widget is closed

onError

Function

no

Action to perform on widget Error

BeforeClose

Function

no

Action to perform before widget close

limit

Number(3,6,9,12) or date_range (

startDate: '2020-02-10', endDate: '2020-05-10')

no

24

Statement length

countries

Array

yes

['NG']

ISO 3166 code of your country of operation

launchAgain

Boolean

no

true

Whether to show launch Widget button

hideExit

Boolean

no

false

Hide exit button while connecting their account(s)

guarantors.status

Boolean

no

false

Request for guarantors from your client

guarantors.message

String

no

Your Guarantor

Message to display when requesting for client's guarantor

guarantors.number

Number

no

1

number of guarantors to request from client

clientname

String

no

This Client

Your Company Name

Okra.buildWithShortUrl Options

Name

Type

Required

Description

short_url

String

true

Your generated url from link builder.

onSuccess

Function

false

Action to perform after widget is successful

onClose

Function

false

Action to perform if widget is closed

Listen for Callback

This section shows how you can listen for callback whenever a record is created.

You can save your default callback URL in your keys in the dashboard.

In your Node application, create a route called {apiUrl}/callback in your PHP application, you can create a page to listen to callbacks

Scripts for callback, CURL is PHP

JavaScript
PHP
JavaScript
router.post('/callback', (req, res) => {
switch (req.body.method) {
case 'AUTH':
//DO SOMETHING
break;
case 'BALANCE':
//DO SOMETHING
break;
case 'TRANSACTIONS':
//DO SOMETHING
break;
case 'IDENTITY':
//DO SOMETHING
break;
case 'INCOME':
//DO SOMETHING
break;
case 'DIRECT-DEBIT':
//DO SOMETHING
break;
default:
break;
}
})
PHP
$body = @file_get_contents('php://input');
$data = json_decode($body, true);
switch ($data['method']) {
case 'AUTH':
//DO SOMETHING HERE
$fp = file_put_contents('auth.json', print_r($data,true) );
break;
case 'IDENTITY':
//DO SOMETHING HERE
$fp = file_put_contents('identity.json', print_r($data,true) );
break;
case 'BALANCE':
//DO SOMETHING HERE
$fp = file_put_contents('balance.json', print_r($data,true) );
break;
case 'TRANSACTIONS':
//DO SOMETHING HERE
$fp = file_put_contents('transactions.json', print_r($data,true) );
break;
case 'INCOME':
//DO SOMETHING HERE
$fp = file_put_contents('income.json', print_r($data,true) );
break;
case 'DIRECT-DEBIT':
$fp = file_put_contents('direct-debit.json', print_r($data,true) );
break;
default:
break;
}

onSuccess callback

The onSuccess callback should take two arguments, the record_id and a metadata object. The metadata object provides the following information:

Parameter

Description

record_id String

A unique identifier associated with a user's actions and events through the OkraJS flow. Include this identifier when opening a support ticket for faster turnaround.

bank Object

An object with two properties: - name: The full bank name, such as 'Guaranty Trust Bank' - bank_id: The Bank ID

accounts Object

A list of objects with the following properties: -id: the id of the selected account -name: the name of the selected account -mask: the last four digits of the selected account -type: the account type -subtype: the account subtype

Checkout the Account section for more detailed documentation. To collect accounts data, you must enable the Select Account view via the Okra Dashboard.

onSuccess example

okra.create({
...,
onSuccess: function(record_id, metadata) {
},
})
`

// curl // n/a //

onClose callback

The onClose callback is called when a user exits the OkraJS flow. It takes two arguments, a nullable error object and a metadata object.

Parameter

Description

error Object

A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.

metatdeta Object

An object containing information about the last error encountered by the user (if any), bank selected by the user, and the most recent API record ID, and the OkraJS session ID.

onClose example

okra.create({
...,
onClose: function(metadata, error) {
},
})
`

// curl // n/a //

error object schema

{
"display_message": "The credentials were ...",
"error_code": "INVALID_CREDENTIALS",
"error_message": "The credentials were ...",
"error_type": "RECORD_ERROR",
}

onClose metadata schema

{
"record_session_id": String,
"record_id": String,
"bank": {
"name": String,
"bank_id": String
},
"status": String
}

onFailure callback

The onFailure callback is called when an error occurs in the OkraJS flow. It takes two arguments, a nullable error object and a metadata object.

Parameter

Description

error Object

A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.

metatdeta Object

An object containing information about the last error encountered by the user (if any), bank selected by the user, and the most recent API record ID, and the OkraJS session ID.

onFailure example

okra.create({
...,
onFailure: function(error, metadata) {
},
})
`

// curl // n/a //

error object schema

{
"display_message": "The credentials were ...",
"error_code": "INVALID_CREDENTIALS",
"error_message": "The credentials were ...",
"error_type": "RECORD_ERROR",
}

onFailure metadata schema

{
"record_session_id": String,
"record_id": String,
"bank": {
"name": String,
"bank_id": String
},
"status": String
}