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
preselect_banks
attributesThese 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.![]() | 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
charge
attributesThese 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
charge
codeOpen charge
example
"charge": {
"type": "one-time",
"amount": 10000,
"note": "Service payment",
"currency": "NGN",
"account": "{The beneficiary account ID}"
}
cart
attributes
cart
attributesThese 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
cart
codeYou 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.
Updated about 10 hours ago