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:

PropertyData typeDescriptionExample values
short_urlstringThe short link of the app you created. You can retrieve this URL from the Integration tab of your app in the Dashboard.tTthfNrpC
tokenstring uuidThe 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.
keystring uuidThe 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.
productsarray of stringsThis 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.
authbalanceidentitytransactions, payments
namestringThe 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
envstringThe Okra API environment on which to create user accounts.

Visit the API reference for more details about the available environments.
production or production-sandbox
sourcestringThe type of integration that you, ios, rn-ios, rn-android , ionic, wordpress, vue, flutter, integration, laravel, react
redirect_urlstringSpecify 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.

Set up event callbacks and webhooks

Use these properties to set up callback and webhook URLs:

PropertyData typeDescriptionExample values
callback_urlstringSpecify a URL where Okra can send webhook notifications.{id}
event_callback_urlstringSpecify 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:

PropertyData typeDescriptionAccepted values
countriesarray of stringsDefines the country that you want to show banks from in the Okra app.NG

Contact to access banks from ZA (South Africa), and KY (Kenya).
corporatebooleantrue 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.
filterobjectFilter 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"]}}
institutionsarray of stringsDefines 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.
preselect_banksobjectSets 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.

PropertyData typeDescriptionRequiredAccepted values
bankstringThe name of bank you want to select in slug format. Use the List banks endpoint to retrieve slugs for each bank that Okra supports.requiredBank slugs, for example: guaranty-trust-bank
typestringSets the account type.requiredpersonal, business
platformstringSelects the login method: internet banking (bank), or mobile banking (mobile).requiredbank, mobile
loginstringYou should use this keyword for banks that have multi-login options. For example, Zenith bank has pin_and_token and password as login options.optionalpin_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">
    <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>
  <body onload="buildWithOptions()" style="background-color:#fff;height:100vh">
    <script src=""></script>
    <script type="text/javascript">
      function 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 };
          onClose: function () {
            let response = { event: "option close" };
          BeforeClose: function () {
            let response = { event: "option before close" };
          onError: function (data) {
            let response = { event: "option error", data };

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

PropertyData typeDescriptionExample values
customerobjectThis 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:

PropertyData typeDescriptionExample values
reAuthAccountNumberstringThe returning user's account number.0123456789
reAuthBankSlugstringThe bank's name in slug format.guaranty-trust-bank

When using OkraJS or Okra Node:

PropertyData typeDescriptionExample values
reauth_accountstringThe returning user's account number.0123456789
reauth_bankstringThe 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:

PropertyData typeDescriptionExample values
limitintThis 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.
showBalancebooleanDisplay the account balance to your users.true or false
enableAutoConnectbooleanEnables 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_accountbooleanEnables 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:

PropertyData typeDescriptionExample values
continue_ctastringCustomizes the call-to-action button text on the account connection success screen.Continue
connectMessagestringCustomizes the call-to-action text on the account connection screen.Select the account that you want to connect.
colorstringSets the color theme of the Okra app.

This option accepts HEX color codes without the # symbol.
logostringAdds your logo to the Okra app.

This option accepts URLs that point to an image file.

Set up payments

Use these properties to set up a payments flow in your Okra app:

PropertyData typeDescriptionRequiredExample values
paymentbooleanSet to true to initialize the Payments product.required, if you want to use Paymentstrue
chargeobjectSet up specific details about the payment you want to charge.requiredSee example.
cartarray of objectsDefine a list of the items that you collect a payment for, much like a cart in a webshop.optionalSee example.

charge attributes

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

PropertyData typeDescriptionRequiredAccepted values
typestringThe type of payment you want to charge. Currently you can only set up one-time payments. Check out the Payments guide for more details.requiredPossible values: one-time
amountintegerThe amount you want to charge.requiredAn integer, for example: 10000
notestringA note that you want to tie to a specific payment.requiredAny string, for example: Service payment
currencyintegerThe currency that you want to charge in.requiredAccepted value: NGN
accountstringThe 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:

PropertyData typeDescriptionRequiredAccepted values
namestringSet the name of an item that you want to display in the cart.requiredAny string, for example: Full English Breakfast
amountintegerSet the price of an item.requiredAn integer, for example: 20000
currencystringSet the currency of an item.requiredAccepted value: NGN
quantityintegerSet the quantity of an item that is in the cart.requiredAn 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:

PropertyData typeDescriptionExample values
metaany valid JSONSend 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"}}
optionsobjectSend 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.

Was this page helpful?