App properties

Customize the your Okra app and define every aspect that your users see, from the list of available banks to a consistent brand experience.

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

Configuring your Okra app

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

Property	Data type	Description	Example values
`short_url`	`string`	The short link of the app you created. You can retrieve this URL from the Integration tab of your app in the Dashboard.	`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 Okra app. 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 Okra app. Check out Payments and Account data for more details. In the production environment, billing is based on the products that you specify when initializing the Okra app. `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 Okra app initializes, it only shows banks that support every product that you define.	`auth`, `balance`, `identity`, `transactions`, `payments`
`name`	`string`	The name of your product or company that you want your users to see. The Okra app displays this name in the User Agreement document, in app 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 Okra app:

Property	Data type	Description	Accepted values
`countries`	`array of strings`	Defines the country that you want to show banks from in the Okra app.	`NG` Contact sales@okra.ng to access banks from `ZA` (South Africa), and `KY` (Kenya).
`corporate`	`boolean`	`true` sets the Okra app to only display banks that support corporate accounts. `false` sets up the Okra app to only display banks that support personal accounts. When you do not define this option, the app 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 Okra app 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`	Sets the Okra app flow to skip the bank selection screens 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, the Okra app flow skips the bank selection screens.

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`

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"
          },
          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 Okra app. Read more about API key types and authentication in the API reference.

Set up the RUX flows

Use these properties to simplify the user journey in your app for users who already connected their accounts with Okra.

Account data & Payment flows

Property	Data type	Description	Example values
`customer`	`object`	This option enables your app to identify a returning user and simplify the user flow in the Okra app. In the `customer` object you need to specify a key-value pair.

The API accepts these keys: id, bvn, phone, email|{"customer": {"id": "1dcfr...dsf"}}|

Quick Pay

When using Okra's Flutter, iOS, or Android SDKs, or the official React Native package:

Property	Data type	Description	Example values
`reAuthAccountNumber`	`string`	The returning user's account number.	`0123456789`
`reAuthBankSlug`	`string`	The bank's name in slug format.	`guaranty-trust-bank`

When using OkraJS or Okra Node:

Property	Data type	Description	Example values
`reauth_account`	`string`	The returning user's account number.	`0123456789`
`reauth_bank`	`string`	The bank's name in slug format.	`guaranty-trust-bank`

Check out the Returning user experience guide for more details about these flows.

Set up bank account behavior

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

Property	Data type	Description	Example values
`limit`	`int`	This value sets how many months of transaction statements should the API fetch from the bank. The API accepts these values: `3`, `6`, `12`, `24` If you do not set `limit`, the API defaults to 24 months.	`3`
`showBalance`	`boolean`	Display the account balance to your users.	`true` or `false`
`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` or `false`
`multi_account`	`boolean`	Enables users to link another bank account in the same app instance. When `true`, this setting shows the Link another account button on the Success screen.	`true` or `false`

Set up look & feel

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

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 Okra app. This option accepts HEX color codes without the `#` symbol.	`DDFF33`
`logo`	`string`	Adds your logo to the Okra app. 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 Okra app:

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 Okra app 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 Okra app properties.

App properties

Configuring your Okra app

Set up event callbacks and webhooks

Set up banks and institutions

preselect_banks attributes

Example code

Set up the RUX flows

Set up bank account behavior

Set up look & feel

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