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
}

Overview

Next - Okra JS

Other Integrations

Last updated 2 months ago

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

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

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.