Quickstart

This guide takes you through the essential steps of building a sample app with Okra. You can test the sample app you create to check out Okra's features, or you can integrate it into your own application to demo the whole user journey.

1 - Create your Okra Account

Visit the Okra Dashboard and register an account.
Okra requires verification for the email you register - make sure that you confirm your email address.

2 - Get your credentials

Check out the API Keys page in the Dashboard to retrieve your credentials.

The client token is a unique ID that represents you, as a client. You must use it together with your public API key in your widget implementation. Client tokens can be used in both Sandbox and Production environments.
The public API key, along with the client token is used to authenticate your widget implementation.
The secret API key is a JWT bearer token that you must use for authentication on the API level.

Visit the API reference to understand how Authentication works in the Okra API.

Use the sandbox environment

Okra recommends that you use the sandbox environment when building and testing your integration. This environment offers realistic data that follows standard use cases. You can test all API endpoints, use the widget, and even implement webhooks through this environment.

Visit the Sandbox guide to learn more about using this environment, and also to retrieve sandbox test credentials.

3 - Interact with the API

📘
Make sure that you read through the Okra API overview to understand the specifics of interacting with the Okra API, like request and response formats, pagination, and rate limiting.

Okra recommends that you use Postman to test your integration and the data sets that the Okra API offers.

Fork the Okra API Reference collection

To interact with the Okra API via Postman:

Watch Okra's API Reference collection.
Fork the collection into your own private workspace.

Configure Postman

Okra recommends using environment variables to customize the requests that you send. This step is optional, but can help you avoid mixing up environments and credentials. Read more in Postman's Managing environments article.

Details on how to create your environment variables

Add a new environment and call it, for example, Okra Sandbox.
Add these environment variables:

Variable	Description
`api_key`	Your public API key.
`secret`	Your secret API key.
`baseUrl`	`https://api.okra.ng/v2/sandbox`

📘
Make sure that you store your api_key, secret, and baseUrl as initial values and current values.

Try calling the API

Select your Okra Sandbox environment.
In the Okra API Reference collection, select Bank → Get list of banks.
Click Send and check the response.

If you set everything up correctly, this endpoint operation returns a list of banks that Okra supports.

4 - Connect a bank account

Create a test customer

To test how your customer will go through the account connection flow, you need to create a test customer. You can do this in multiple ways:

You can create a customer via the Dashboard. You have the option to manually fill out customer details and define the login credentials, which are needed to go through the account connection flow. You also have the option to autogenerate a customer.
You can also create a customer via the API. You can define customer details manually in your request using the Create customer endpoint operation, and you can leverage the Autogenerate endpoint via the API as well.

📘
When creating customers, the account type you select determines the data set that the API generates. For example, the API only generates BVN and NUBAN values for customers with Personal accounts.

Create a sample Widget integration

Let's see how you can link a bank account using the sandbox environment, and with test credentials:

Grab your API key and client token from the Dashboard
Create an index.html file and open it in your preferred code editor
Paste this snippet into your index.html file, and add your API key and client token:

Web integration sample

<!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>Linking a bank account</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: 'Sandbox Test', // The name of your application or product.
                env: 'production-sandbox', // The API environment.
                key: '...', // Your public API key.
                token: '...', // Your client token.
                products: ['auth', 'identity', 'balance', 'transactions' ], // The products that you want to enable.
                onSuccess: function(data){
                      console.log('data', data)
                  },
                onClose: function(){
                      console.log('close widget')
                  }
              })
          }
      </script>
    </body>
</html>

Open the index.html in your preferred browser.
Use the credentials of the test customer that you created to link a bank account

These are the options that are in the sample integration:

Option	Description
`name`	The company or app name that you want to display on the Widget.
`env`	The API environment. In this case it is set to `production-sandbox`.
`key`	Your public API key.
`token`	Your client token.
`products`	This property defines the products that you want to include in your Widget experience. Check out Okra’s products for more details.
onSuccess and onClose events	These callbacks provide information when specific events take place in your Widget implementation. Check out the Event callbacks guide for more details.

📘
This sample integration uses only the most basic Widget properties. Check out the complete list of Properties for more options.

5 - Check out the data

After you go through the account connection flow, the Okra API immediately starts retrieveing user information. Both in a production environment, and in the Sandbox, this is an async data retrieval process. You can check out the resulting user data in two ways:

Visit the Records page on the Dashboard to find the customer you connected. The dasboard gives you clear indication about which product's data has been synced already, and which product's data retrieval is still in progress.
You can also retireve data directly from the API. Visit the API reference to see the different product endpoints, and the specific methods you can use to retrieve data for the products you enabled.

Switching to production

When you have tested your integration in the Sandbox environment and want to go live with your product, get in touch with the Okra Sales team.

The Sales team makes sure that you finished your onboarding and that your business needs are satisfied. The team then connects you with Okra engineer who verifies that your integration is running optimally. Okra recommends that you take a look at the Integration checklist before you switch to production.

Once your integration is verified, you need to:

Update the sandbox credentials in your code to production credentials.
Set the base URL of your application's requests to the production environment.
Make sure that you define a production URL for your webhooks. Visit the Webhooks guide for more details.

Need help?

Check out the Widget Errors and the API Errors guide to understand the different error scenarios.
Join Okra's Developer Community on Slack if you have technical questions or need help with your code.
Get in touch with the Support team if you have any questions about Okra's products.