Returning user experience

The Returning User Experience (RUX) is a Widget flow that enables you to simplify the user journey in your app for users who already connected their accounts with Okra.

When a user connects their accounts for the first time, the Okra API creates a customer record that can contain important user information like:

customer id
bvn
phone
email

These data points can be used to identify a returning user, and eliminate redundant authentication or bank selection steps in their user flows. This enables you to:

reduce the amount of duplicate account connections
collate data for the same user via different Widget use cases
improve user experience and reduce user friction

Requirements

The RUX flow has 2 requirements:

You can only initialize the RUX Widget flow via the buildWithOptions integration method. Check out the Integration guide for more details.
The API can only identify a returning user when their credentials like customer id or bvn are available through their customer record in your Okra project. This means that the user should already have connected their accounts to Okra, or completed a payment via a Payment link.

Set up RUX

You can set up RUX in both Data and Payment flows by adding the customer property to your Widget initialization code:

"customer":{
		"id": "1ge1e563798ba608e8f59756"
	}

You can change id to bvn, phone, or email.

RUX in the Data flow

In the Data flow, you can use RUX to reconnect a returning user’s account, or connect their account to another app or product in your Okra project.

When the API identifies a returning user, their journey in the Okra Widget is simplifed to only 2 steps; selecting their bank accounts, and providing authentication like their PIN.

Sample RUX integration in the Data flow

Okra.buildWithOptions({
          name: "RUX flow",
          env: "production", // The API environment.
          key: "68c7....c6f9", // Your API key, according to the environment you use.
          token: "5da6....dced", // Your Client token.
          products: ["auth", "identity", "balance", "transactions"], // Okra products that you want to retrieve data from.
          customer: { id: "1ge1e563798ba608e8f59756" }, // The returning user's customer ID.
          multi_account: true, // Enable the "Link new account" button on the Success screen.
          onSuccess: function (data) {
            let response = { event: "option success", data };
            console.log(response);
          },
          onClose: function () {
            let response = { event: "option close" };
            console.log(response);
          },
          BeforeClose: function () {
            let response = { event: "option before close" };
            console.log(response);
          },
          onError: function (data) {
            let response = { event: "option error", data };
            console.log(response);
          },
        });

RUX in the Payments flow

In the Payments flows you can use RUX to connect a returning user’s payment to their existing user profile, and to enable Quick Payments for some banks.

When the API identifies a returning user in the Payments flow, their journey in the Okra Widget is simplifed to only 2 steps; selecting an account, and providing credentials.

Sample RUX integration in the Payments flow

Okra.buildWithOptions({
          name: "RUX flow",
          env: "production", // The API environment.
          key: "68c7....c6f9", // Your API key, according to the environment you use.
          token: "5da6....dced", // Your Client token.
          charge: { // Details about the payment you want to charge.
							"type": "one-time",  
				      "amount": 10000,  
				      "note":  "Service payment",  
				      "currency": "NGN",  
				      "account": "{The beneficiary account ID}"
					},
					customer: { id: "1ge1e563798ba608e8f59756" }, // The returning user's customer ID.
          onSuccess: function (data) {
            let response = { event: "option success", data };
            console.log(response);
          },
          onClose: function () {
            let response = { event: "option close" };
            console.log(response);
          },
          BeforeClose: function () {
            let response = { event: "option before close" };
            console.log(response);
          },
          onError: function (data) {
            let response = { event: "option error", data };
            console.log(response);
          },
        });

RUX in Quick Payments

In the Quick Payments flow a returning user only needs to provide a One Time Password (OTP) or a transaction PIN to initiate a payment, enabling a seamless user flow within your app. You can use this flow for users who are already authenticated through the Okra Widget.

To enable Quick Payments, you need to add these properties to your Widget initialization code:

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

Property	Description
`reAuthAccountNumber`	The returning user's account number.
`reAuthBankSlug`	The bank's name in slug format.

When using OkraJS or Okra Node:

Property	Description
`reauth_account`	The returning user's account number.
`reauth_bank`	The bank's name in slug format.

🚧
Quick Payments is currently only supported by Zenith Bank and Stanbic Bank.

Sample RUX integration in the Quick Payments flow

Okra.buildWithOptions({
          name: "RUX flow",
          env: "production", // The API environment.
          key: "68c7....c6f9", // Your API key, according to the environment you use.
          token: "5da6....dced", // Your Client token.
          products: ["auth", "identity", "balance", "transactions"], // Okra products that you want to retrieve data from.
          charge: { // Details about the payment you want to charge.
							"type": "one-time",  
				      "amount": 10000,  
				      "note":  "Service payment",  
				      "currency": "NGN",  
				      "account": "{The beneficiary account ID}"
					},
          payment: true, // Enables the Payment product.
					reauth_account: "0123456789", // reAuthAccountNumber in Flutter, 
															// React Native, Android & IOS SDKs
					reauth_bank: "access-bank", //reAuthBankSlug in Flutter, React Native, Android & IOS SDKs
          onSuccess: function (data) {
            let response = { event: "option success", data };
            console.log(response);
          },
          onClose: function () {
            let response = { event: "option close" };
            console.log(response);
          },
          BeforeClose: function () {
            let response = { event: "option before close" };
            console.log(response);
          },
          onError: function (data) {
            let response = { event: "option error", data };
            console.log(response);
          },
        });