Widget callbacks

Handle your Okra Widget data in real-time

Handle callbacks beyond just onSuccess in order to gracefully handle errors and build analytics around your Okra Widget.

Available callbacks

Callback

Description

Example

onSuccess

Called after the successful linking of an account to your Okra Widget

 console.log('handle success', json)
}```

onError

Called after and error occurs while linking an account to your Okra Widget

 console.log('handle error', error)
}```

onClose

Called when the Okra Widget is closed.

 console.log('handle close', json)
}```

onEvent

Called anytime there is a significant event on your widget.

 console.log('Event tracking', event)
}```

onSucces

A function that is called when a user has successfully connected their account to your Okra Widget and created a Record. The function should expect one argument, the metadata JSON object

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onSuccess: (data) => {
        console.log('You have linked an account!', data)
  }
});
{
    "auth": {
        "bank_details": {
            "_id": "5d6fe57a4099cc4b210bbebe",
            "name": "Alat",
            "slug": "alat",
            "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Alat.svg",
            "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/ALAT+by+Wema+Logo+Color.svg",
            "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Alat+by+Wema.png",
            "v2_logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Alat.svg",
            "v2_icon": "https://okra-images.s3.eu-west-3.amazonaws.com/ALAT+by+Wema+Logo+Color.svg"
        },
        "bank_id": "5d6fe57a4099cc4b210bbebe",
        "clientId": "okr-1652195470932-o6jJkRjX3AazT1SX11fUg",
        "customer_id": "61e7dc95d8b92c006348cf0e",
        "status": true,
        "type": "validate",
        "login_type": "bank"
    },
    "income": null,
    "identity": {
        "fullname": "Faith Sunday Smith",
        "firstname": "Faith",
        "lastname": "Smith",
        "middlename": "Sunday",
        "id": "627a80ac4bff31001e9ee9d6",
        "bvn": "50058467026",
        "nin": "5005848975",
        "score": 104,
        "env": "production-sandbox",
        "created_at": "2022-05-10T15:11:40.584Z",
        "last_updated": "2022-05-10T15:11:40.584Z",
        "aliases": [
            "Prosper  Gift Green",
            "Lily Agusto"
        ],
        "customer": "61e7dc95d8b92c006348cf0e",
        "dob": "2021-07-05T10:53:43+00:00",
        "gender": "M",
        "phone": [
            "09303471282",
            "06821834713"
        ],
        "email": [
            "[email protected]",
            "[email protected]"
        ],
        "address": [
            "516 Miss, Rachel Simpson Mission, Oye Delta"
        ],
        "verified": true,
        "status": "true",
        "verification_country": "NG",
        "lga_of_origin": "Ndokwa East",
        "lga_of_residenc": "Lagos Island",
        "marital_status": "Single",
        "nationality": "Nigeria",
        "state_of_origin": "Delta State",
        "state_of_residence": "Lagos State",
        "projects": [
            "62262a18ce77d5001d2b5ef3"
        ]
    },
    "error": null,
    "payment_authorization": null,
    "authorization_id": null,
    "authorizationId": null,
    "done": true,
    "accounts": [
        {
            "manual": false,
            "nuban": "2377140061",
            "id": "61e7dcb74063c16cf13c50c2",
            "connected": false,
            "name": "Prosper Smith",
            "type": "Current"
        },
        {
            "manual": false,
            "nuban": "2377141117",
            "id": "61e7dcb74063c16cf13c50d5",
            "connected": false,
            "name": "Prosper Smith",
            "type": "Domiciliary"
        },
        {
            "manual": false,
            "nuban": "2377146155",
            "id": "61e7dcb74063c16cf13c50e2",
            "connected": true,
            "name": "Prosper Smith",
            "type": "Domiciliary"
        }
    ],
    "record_id": "627a80914bff31001e9ee9d1",
    "record": "627a80914bff31001e9ee9d1",
    "bank_id": "5d6fe57a4099cc4b210bbebe",
    "customer_id": "61e7dc95d8b92c006348cf0e",
    "balance": {
        "formatted": [
            {
                "available_balance": 10089755,
                "ledger_balance": 10089755,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377140061",
                "ref": "current-account",
                "status": "active",
                "type": "Current",
                "account": "61e7dcb74063c16cf13c50c2"
            },
            {
                "available_balance": 10079766,
                "ledger_balance": 10079766,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377141117",
                "ref": "domicialiary-account",
                "status": "active",
                "type": "Domiciliary",
                "account": "61e7dcb74063c16cf13c50d5"
            },
            {
                "available_balance": 10139547,
                "ledger_balance": 10139547,
                "currency": "NGN",
                "name": "Prosper Smith",
                "nuban": "2377146155",
                "ref": "domicialiary-account",
                "status": "active",
                "type": "Domiciliary",
                "account": "61e7dcb74063c16cf13c50e2"
            }
        ],
        "data": {
            "formatted": [
                {
                    "available_balance": 10089755,
                    "ledger_balance": 10089755,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377140061",
                    "ref": "current-account",
                    "status": "active",
                    "type": "Current",
                    "account": "61e7dcb74063c16cf13c50c2"
                },
                {
                    "available_balance": 10079766,
                    "ledger_balance": 10079766,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377141117",
                    "ref": "domicialiary-account",
                    "status": "active",
                    "type": "Domiciliary",
                    "account": "61e7dcb74063c16cf13c50d5"
                },
                {
                    "available_balance": 10139547,
                    "ledger_balance": 10139547,
                    "currency": "NGN",
                    "name": "Prosper Smith",
                    "nuban": "2377146155",
                    "ref": "domicialiary-account",
                    "status": "active",
                    "type": "Domiciliary",
                    "account": "61e7dcb74063c16cf13c50e2"
                }
            ]
        }
    },
    "transactions": {
        "transactions": {
            "callback_url": "https://api.okra.ng/v2/callback?record=627a80914bff31001e9ee9d1&method=TRANSACTIONS"
        }
    },
    "launchAgain": false,
    "hideExit": false,
    "options": {
        "clientDefinedId": "Im testing out",
        "anotherclientDefinedId": "1234567890"
    },
    "meta": {
        "clientDefinedId": "Im testing out",
        "anotherclientDefinedId": "1234567890"
    },
    "success": true
}

onClose

The onClose callback is called when a user exits the Okra Widget flow. It takes two arguments, a nullable error object and a metadata JSON object. The metadata parameter is always present, though some values may be null.

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onClose: (json, error) => {
        console.log('Uh oh, you closed the widget', json)
  }
});

onError

The onExit callback is called when an error occurs during the Okra Widget initialization. It takes two arguments, a nullable error object and a metadata JSON object. The metadata parameter is always present, though some values may be null.

import Okra from 'npm-okrajs';

const OkraHandler = Okra.buildWithOptions({
  ...,
  onError: (json, error) => {
        console.log('You have connected!', json)
  }
});

onEvent

The onEvent callback is called anytime there is a significant event on your widget. It takes one arguments, an event object which is a metadata JSON object. The event parameter is always present, though some values may be null. You can find a list of events below:

🚧

Did you check if there was an error?

Make sure to check the withError parameter. If this is false, then the user did not receive an error. This is especially important with the WIDGET_USER_INTERNET_DISCONNECTED event. If there was no error then the user will be reconnected.

Event sample

{
        event: true
    event_callback_url: webhook.site/10097dhr-ef8c-40d3-86f8-894a010f5706
    event_data: 
        {
        tracking_id: MN09uhhgd
      }
    event_location: "https://app.okra.ng/:ref/bank?bank=rubies-bank"
    event_name: "USER_LOGIN_ATTEMPTED"
    event_time: null
    event_type: "DATA_EVENT"
}

General Events

Event Name

Event Description

user_connecting

The user is attempting to connect to the widget e.g. user has launched our SDK

user_connected

The SDK have been fully loaded and the user can now interact with the Okra widget

user_consent_review

The user clicked on view the Okra terms of service and privacy policy

user_consent_granted

User clicked on Continue to grant data consent on sharing their accounts

user_account_type_selection

The user toggled the Business/Personal button on the widget

user_viewed_banks

The user has landed on the bank selection screen

user_bank_search

User has engaged in search for a bank in the search bar (for at least 5 secs.)

user_bank_search_no_results

User haven't received any results from their search term entered in the search bar.

user_bank_selected

The user clicked on a bank. List view and the front page

user_account_selection

User have landed on the account selection screen on the Okra Widget

user_account_selected

User have selected the account they would like to connect to Okra.

WIDGET_COMPLETE_PROFILING

The user has not completed setting up this internet or mobile banking account and was asked to complete profiling their profile.

user_retry_otp

The user have clicked on the option to get new OTP code.

user_connection_failed

The user has failed to connect their account. In order to get more details on the failure, please review the {property} in the same payload.

user_connection_successful

The user have successfully connected their account to Okra.

user_profile_account_review

User was asked to profile device to bank

user_mfa_question

User has landed on the MFA question screen on the Okra widget.

user_complete_mfa

The user has submitted their MFA answer.

user_login_attempted

The user have entered their credentials and clicked on the login button in order to proceed with the connection.

user_fetch_trans

Okra is pulling the user's transactions.

user_submit_guarantors

The user has submitted guarantors.

user_app_close

The user has close the widget from the success or failure screen.

user_login_selection

The login method that the user selected from the login selection screen. Available options will be returned in the event_data object, under the login_method property (event_data.login_method). Possible options:

Internet banking, Mobile banking, Account number

user_fetch_balance

Okra is pulling the user's balance.

user_retrieved_balance

Okra successfully retrieved the user's balance.

user_balance_sent

A webhooks was triggered for the user's balance.

user_app_redirect

Redirect to page of choice after app close.

Payment Events

Events

Description

user_payment_review

The user is reviewing the payment

user_confirm_payment

The user confirmed the payment.

user_authorize_payment

The user completed the payment authorization

user_payment_acknowledged

The user clicks the Pay Now button

Returning User Events

Events

Description

user_rux_selection

A user viewed a list of their existing banks.

user_rux_bank_selected

The user selects an existing account.

user_rux_not_found

No user accounts were found for provided identification.

Network Events

Events

Description

user_network_disconnected

User lost internet connectivity or experiencing connection issues.

user_network_reconnected

User has reconnected to the Okra widget.

user_timeout

The connection attempt to the user has timed out.

user_bounce

The user has closed the Okra widget without completing the whole flow.


Did this page help you?