Onboarding guide

Building the impossible with Okra begins with your onboarding. This guide takes you through the necessary steps to get you started with using Okra’s services.

Sign up

As a first step, you need to register on the Okra Dashboard. The Dashboard is a toolbox that enables you to manage your account, your apps, and your customers. It is where you can find your API keys, and also where you can get insights into all the data that flows between your app, the Okra APIs, your customers, and their banks.

The dashboard requires verification for the email you register - make sure that you confirm your email address.

Complete compliance

After you’ve verified your email address, you can start signing up your business via the Okra Dashboard. This compliance process has 4 steps:

• Company info: provide your company name, its RC number, and select the country of registration. The dashboard verifies your RC number before you can continue.
• Registration documents: upload your company’s CAC certificate, and a proof of your company status on the CAC platform.
• Business profile: select your industry, provide your business’s name, and write a short summary about what your business does. Creating this business profile helps Okra provide more accurate support in case you need help.
• SLA: the last step is to accept Okra’s Service Level Agreement. You can request a copy of this agreement to your email address. Once you agree to the terms, you can launch the dashboard and start building.

📘

If you want to use Okra’s Payments solution, get in touch via [email protected] to request access. It requires some additional verification before you can enable it in your integration.

Using Okra’s paid services

Okra uses wallets to handle payments for the services and products that you use. For example, Okra debits your wallet after your subscription fees, and certain API calls in the production environment.

Things to know about your wallets:

• Okra’s wallets use credits, and the rate of 1 credit is fixed at 1 USD.
• Okra provides separate wallets for each business that you have. This enables you to select different payment plans for each of your businesses in a way that suits your needs.
• The Okra API returns API receipts in the response body for each billed API call. Read more about API receipts here.

Managing your wallet

Use the dashboard to directly manage your wallet. Through the dashboard, you can:

• Check you wallet’s credit balance
• Add funds to your wallet via secure card payments
• Set up automatic top-ups to ensure uninterrupted service for your applications
• Set up notifications to keep you informed about your credit balance

You can also interact with your wallet programmatically. Visit the API reference for more details.

Check out the FAQs to find out more about how billing works, and how you can use your Okra wallet.

Start using the Okra Widget

As soon as your sign-up process is done, you can start creating your Widget experiences.

The Okra Widget is a gateway for your users where they can link their bank accounts to Okra's API in your product, website, or application. This connection enables you to leverage Okra's API and retrieve up-to-date information in real time, and in a secure manner.

Create and customize your Widget

You can create and customize your Widgets in 2 ways:

• via the App Builder
• via the API

Okra recommends using the App Builder because it requires no coding experience, and enables you to preview your Widget, and to check any changes you make in real time. Check out the Widget customization guide for more details about both methods.

👍

The Widgets that you create are hosted by Okra. Each Widget instance comes with an app link, a URL that you can grab from the dashboard. If you do not wish to create a full integration, you can directly send the app links to your customers. Once opened, these app links provide a full user flow where your customers can connect their bank accounts, or even do one-time payments.

Watch a quick summary on how to create a Widget via the App Builder, and see what the user flow in that Widget looks like:

Dive into the App Builder and try creating a similar test app! Or if you prefer a more hands-on approach, visit the integration Quickstart to build a sample Widget for a web integration in just 5 steps.

Integrate your Widget

Okra offers a set of libraries and SDKs that you can use to launch the Okra Widget in your web or mobile applications. Check out the catalog of Libraries and SDKs for the available languanges and platforms.

These libraries and SDKs can launch a Widget instance through two functions:

• buildWithShortUrl provides a quick and simple way to directly integrate a Widget you already created and customized into your app or website.
• buildWithOptions enables you to customize the Widget before initialization. You can programmatically set up the parameters that build the Widget according to your use case or business needs.

Check out the Widget integration guide for more details about each function.

Best practices

This section describes some of the key concepts and best practices that you can adopt for a smooth integration experience.

Understand how authentication works.

Okra’s API uses bearer authentication. There are 3 kinds of keys you must use in your implementation: the client token, the public API key, and the secret API key.

Visit the API overview understand more about your different API keys, and how you can retrieve them from the dashboard.

Understand the different API environments.

Okra’s API operates in two environments: sandbox and production.

• Sandbox is for development purposes and to test Okra’s features without affecting real data. All API calls in the sandbox environment are free.
• Production is used to access real-time data when your product is ready to live.

Make sure that you always match your API keys to the environment you are working in.

Use webhooks.

Webhooks provide real-time notifications when important events take place in your Okra integration. You can subscribe to these notifications by setting up a webhook URL in your Widget. You will receive notifications to your system via simple HTTP requests from Okra, using JSON payloads.

Make sure that you understand these key points about using webhooks:

• How to subscribe to webhooks
• The different webhook notification levels that you can utilize
• How to respond to webhooks
• How to verify that a webhook was sent by Okra

Use callbacks.

Callbacks provide actionable information when specific events take place in your Widget implementation. Improve your application's usability and enhance user experience by building workflows, front-end responses, and automation around the callbacks that Okra offers.

Make sure that you understand the different types of callbacks, and the recommended actions you can take when a callback event occurrs.

Understand the difference between webhooks and callbacks.

Webhook notifications correspond to updates in the Okra products that you enable in your Widget integration. Some examples when Okra sends webhook notifications:

• a user needs reauthentication
• an identity profile is ready
• a user cancels a payment

Use these notifications for tasks that require a response via the API, such as asynchronous requests, retries, or any other operation that needs processing on the backend of your application.

Callback events give you detailed information about what the user does in your Okra integration. For example, you can get callbacks when:

• specific screens load in the Widget
• a user has successfully connected their accounts
• an error occurred during Widget initialization

Use these callbacks to build front-end logic in your app, like displaying success or error messages or advancing your users in the app workflow.

Handle API responses appropriately.

Make sure that your integration handles:

• Paginated responses.
• null values.
• 204 - No content responses. Some API endpoints return this status code, with no content in the body of the response.
• 400, 401, 500, and timeout errors. Okra recommends that you log the request_id of error responses in case you need to reach out to the Support team. This ID can help speed up the troubleshooting process.

Read more about how the handle responses from the Okra API in the API reference.

Be prepared for non-breaking changes.

The Okra team is continuously working to improve the API. This means that changes in the API may happen. Make sure that any potential non-breaking changes in Okra's API will not affect your integration. Some examples:

• New fields or a different field order in the response body
• Change in the number of characters in a string
• Adding new endpoints

Going live

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 best practices 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?

1. If you encounter any errors during your integration journey, check out the Error documentation.
2. If you have any questions about Okra's products or way of working, get in touch with the Support team.
3. If you have technical questions or need help with your code, join Okra's Developer Community on Slack.
4. If you have broader questions, visit the Support Portal for FAQs.