Properties

The properties on this page can be used to customize the Widget experience you provide to your users. Use these properties when building with options or when creating a Widget link via the API. Check out the Integration guide for more details.

Configuring the Widget

Use these properties to define the basic configuration for the Widget according to your use case:

Property	Data type	Description	Example values
`short_url`	`string`	The short app link of the Widget you created. You can retrieve this URL from the App Integration tab of your app, in the Dasboard.	`tTthfNrpC`
`token`	`string uuid`	The client token. This is a unique ID that represents you, as a client. Visit the Dashboard to retrieve it. Client tokens can be used in both Sandbox and Production environments.	`5da63...3dced`
`key`	`string uuid`	The public API key. This is used to authenticate your widget implementation. Visit the Dashboard to retrieve it. Make sure that you match the Sandbox or Production API key to the environment that you are working in.	`0191f18f-647e-...-6be4ce8e1da9`
`products`	`array of strings`	This property defines the products that you want to include in your Widget experience. Check out Okra’s products for more details. In the production environment, billing is based on the products that you specify when initializing the Okra Widget. `auth` is a free product that is included by default, as it is required to authenticate users and enable access to other products. When the Widget initializes, it only shows banks that support every product that you define.	`auth`, `balance`, `identity`, `income`, `transactions`, `payments`
`name`	`string`	The name of your product or company that you want your users to see. The Widget displays this name in the User Agreement document, in Widget errors, and when the user has successfully linked their account.	My Company
`env`	`string`	The Okra API environment on which to create user accounts. Visit the API reference for more details about the available environments.	`production` or `production-sandbox`
`source`	`string`	The type of integration that you use.	`android`, `ios`, `rn-ios`, `rn-android` , `ionic`, `wordpress`, `vue`, `flutter`, `integration`, `laravel`, `react`
`redirect_url`	`string`	Specify a URL to redirect your users to the next step in your application's workflow. The redirect is effected when your users click on the Done button at the end of a successful account connection process.	`https://my.website.com/next-steps`

Set up event callbacks and webhooks

Use these properties to set up callback and webhook URLs:

Property	Data type	Description	Example values
`callback_url`	`string`	Specify a URL where Okra can send webhook notifications.	`https://webhooks.site/{id}`
`event_callback_url`	`string`	Specify a URL where Okra can send callback events for logging.

Set up banks and institutions

Use these properties to define the banks and institutions that your users see in the Widget:

Property	Data type	Description	Accepted values
`countries`	`array of strings`	Defines the country that you want to show banks from in the Widget.	`NG` Contact [email protected] to access banks from `ZA` (South Africa), and `KY` (Kenya).
`corporate`	`boolean`	`true` sets up the Widget to only display banks that support corporate accounts. `false` sets up the Widget to only display banks that support personal accounts. When you do not define this option, the Widget displays every bank, regardless of account type.	`true`
`filter`	`object`	Filter for banks that you would like to show to your users on the bank selection screen. If you do not filter for any specific bank, the Widget shows all institutions that support the products you selected in your `billable_products` option. To filter for banks, list bank slugs in an array of strings in your `filter` object. Use the List banks API endpoint to retrieve bank slugs for institutions that Okra supports.	`{"filter":{"banks":["example-bank", "another-example-bank"]}}`
`institutions`	`array of strings`	Defines the banks that you would like to show to your users on the bank selection screen, and sets the remaining banks as searchable. You need to define at least 4 banks.	[ 'first-bank-of-nigeria', 'united-bank-for-africa', 'guaranty-trust-bank', 'access-bank', 'zenith-bank' ]
`preselect_banks`	`object`	Enables you to bypass the bank selection screens in the Widget flow and pre-select a bank for your users.	See the attributes here.

`preselect_banks` attributes

These properties enable you to pre-select a bank for your users. When using this option, you bypass the bank selection screens in your Widget flow.

Property	Data type	Description	Required	Accepted values
`bank`	`string`	The name of bank you want to select in slug format. Use the List banks endpoint to retrieve slugs for each bank that Okra supports.	required	Bank slugs, for example: `guaranty-trust-bank`
`type`	`string`	Sets the account type.	required	`personal`, `business`
`platform`	`string`	Selects the login method: internet banking (`bank`), or mobile banking (`mobile`).	required	`bank`, `mobile`
`login`	`string`	You should use this keyword for banks that have multi-login options. For example, Zenith bank has `pin_and_token` and `password` as login options.	optional	`pin_and_token`, `password`
`app`	`string`	When you pre-select a bank that has multiple mobile banking apps, you can specify a particular app using this attribute. Note that GT Bank is only institution that you can currently use this attribute with.	optional	`gtworld`, `gtbank`

Example code

You can find an example Web initialization with a pre-selected bank here:

preselect_bank example code

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Okra Direct Bank Flow</title>
  </head>
    <body onload="buildWithOptions()" style="background-color:#fff;height:100vh">
      <script src="https://cdn.okra.ng/v2/bundle.js"></script>
      <script type="text/javascript">
          function buildWithOptions(){
              Okra.buildWithOptions({
                name: 'Kent Woods Inc',
                env: 'production-sandbox',
                key: '<Sandbox API Key>', 
                token: '<Client Token>',
                products: ['auth', 'identity', 'balance', 'transactions' ],
                showBalance: true,
                preselect_bank: {
                    bank: 'guaranty-trust-bank',
                    type: 'personal',
                    platform:'mobile', 
                    app: 'gtbank', 
                },
              onEvent: (event) => {
                      console.log('Event Payload', event)
                  },
                onSuccess: function(data){
                      let response = {event:'option success', data}
                      console.log(data)
                  },
                onClose: function(){
                      let response = {event:'option close'}
                  },
                  BeforeClose: function(){
                    let response = {event:'option before close'}
                },
                onError: function(data){
                  let response = {event:'option error', data}
              }
              })
          }
      </script>
    </body>
</html>

You can test this initialization example by running it as an HTML file. Replace the values of api_key and client_token with your own API key and client token to run the Widget. Read more about API key types and authentication in the API reference.

Set up bank account behavior

Use these properties to define the account connection behavior for your users:

Property	Data type	Description	Accepted values
`limit`	`int`	This value sets how many months of transaction statements should the API fetch from the bank. If you do not set `limit`, the API defaults to 24 months.	`3`, `6`, `12`, `24`
`showBalance`	`boolean`	Display the account balance to your users.	`true`
`enableAutoConnect`	`boolean`	Enables users to automatically connect their accounts. This automatically connects all accounts your customer has at the bank they are connecting with. When your customer has only one account at the bank they are connecting with, this property defaults to `true`.	`true`

Set up Widget branding

Use these properties to customize texts and the branding of your Widget:

Property	Data type	Description	Example values
`continue_cta`	`string`	Customizes the call-to-action button text on the account connection success screen.	Continue
`connectMessage`	`string`	Customizes the call-to-action text on the account connection screen.	Select the account that you want to connect.
`color`	`string`	Sets the color theme of the Widget. This option accepts HEX color codes without the `#` symbol.	`DDFF33`
`logo`	`string`	Adds your logo to the Widget. This option accepts URLs that point to an image file.	`https://my.website.com/assets/logo.png`

Set up payments

Use these properties to set up a payments flow in your Widget implementation:

Property	Data type	Description	Required	Example values
`payment`	`boolean`	Set to `true` to initialize the Payments product.	required, if you want to use Payments	`true`
`charge`	`object`	Set up specific details about the payment you want to charge.	required	See example.
`cart`	`array of objects`	Define a list of the items that you collect a payment for, much like a cart in a webshop.	optional	See example.

`charge` attributes

These properties enable you to set up specific details about the payment you want to charge:

Property	Data type	Description	Required	Accepted values
`type`	`string`	The type of payment you want to charge. Currently you can only set up one-time payments. Check out the Payments guide for more details.	required	Possible values: `one-time`
`amount`	`integer`	The amount you want to charge.	required	An integer, for example: `10000`
`note`	`string`	A note that you want to tie to a specific payment.	required	Any string, for example: `Service payment`
`currency`	`integer`	The currency that you want to charge in.	required	Accepted value: `NGN`
`account`	`string`	The ID of the beneficiary account, where you want the payment to be sent.	required

Example `charge` code

Open charge example

"charge": {  
      "type": "one-time",  
      "amount": 10000,  
      "note":  "Service payment",  
      "currency": "NGN",  
      "account": "{The beneficiary account ID}"  
    }

`cart` attributes

These properties enable you to show a detailed list of the items that you collect a payment for, much like a cart in a webshop:

Property	Data type	Description	Required	Accepted values
`name`	`string`	Set the name of an item that you want to display in the cart.	required	Any string, for example: `Full English Breakfast`
`amount`	`integer`	Set the price of an item.	required	An integer, for example: `20000`
`currency`	`string`	Set the currency of an item.	required	Accepted value: `NGN`
`quantity`	`integer`	Set the quantity of an item that is in the cart.	required	An integer, for example: `2`

Example `cart` code

You can specify multiple items as an array of objects:

Open cart example

"cart": [
  {
    name: "Full English Breakfast",
    amount: 20000,
    currency: "NGN",
    quantity: 2
  },
  {
    name: "Coffee",
    amount: 2500,
    currency: "NGN",
    quantity: 2
  }
]

Set up metadata and tracking

Use these properties to set up unique IDs, fingerprints, or any other tracking information for a specific Widget implementation:

Property	Data type	Description	Example values
`meta`	any valid `JSON`	Send metadata in any valid `JSON` format. The API returns the metadata you define in this field in webhook responses. Check out the Webhooks guide for more details.	`{"meta": {"tracking_ID": "ID_xxxx"}}`
`options`	`object`	Send metadata in key-value pairs. The API returns the data you define in this field in webhook responses. Check out the Webhooks guide for more details.	`{"options" {"key_1": "value", "key_2": "another_value"}}`

📘
To use metadata effectively, make sure you set up Webhooks on an app-level when you define your Widget properties.

Configuring the Widget

Set up event callbacks and webhooks

Set up banks and institutions

preselect_banks attributes

Example code

Set up bank account behavior

Set up Widget branding

Set up payments

charge attributes

Example charge code

cart attributes

Example cart code

Set up metadata and tracking

`preselect_banks` attributes

`charge` attributes

Example `charge` code

`cart` attributes

Example `cart` code