Set up Payments

This guide walks you through the process of setting up Okra’s Payments solution. The whole process is only 3 steps:

1. Finish onboarding
2. Build and embed your app
3. Go live!

Onboarding

Complete your onboarding before you start setting up Payments in your application:

1. Sign up to Okra

2. Provide the necessary documentation about your business to fulfill compliance and sign your SLA

3. Top up your wallet

4. Attend your integration kick-off call with the Okra team

Check out the Onboarding guide for more details on each point. Once you complete your onboarding and your company is verified, you can start building!

Set up your Payments app

Most of the action in this step happens in the Okra dashboard. Before you start building, Okra recommends that you get familiar with the dashboard, and play around a bit with the App Builder.

You should also check out the API Keys page in the dashboard to retrieve your credentials. You will need your client token and and public API key when building your app, and you will need the secret API key to interact with the Okra API.

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

Build your app

1. Create a Payments app

   You can create and customize your apps in 2 ways:

   • Use the App Builder to create apps for Instant Payments, and Payment Authorisations.
   • Use the API to build your app programmatically and generate a Payments app link that you can embed or share directly.

   Okra recommends using the App Builder because it requires no coding experience, enables you to preview your app, and you can check any changes you make in real time.

   Make sure that you leverage Okra’s libraries & SDKs in your integration to benefit from features like callbacks, metadata, or bank filtering. Check out the Integration guide for detailed steps.

2. Set up Webhooks

   • Go to the Webhooks page in the dashboard to set up your webhook URLs. The Okra API will send webhook notifications to this URL.
   • Read about how Webhooks work in the Okra API. You can set up different webhook URLs for the apps you create, or even a shared webhook for every app.
   • When you build your app via the API or initialize it through one of Okra’s SDKs, use the callback_url parameter to definie your app-level webhook URL.

3. Set up a redirect URL

   • When you build a web integration, you can use the redirect URL to take users back to your website from the Okra app after they have completed their payments.
   • When you build your app via the API or initialize it through one of Okra’s SDKs, use the redirect_url parameter to definie this redirect URL.

4. Define metadata

   • Metadata is only available when you initialize your app through one of Okra’s SDKs. Metadata is a great way to add an extra layer of data to your app, like custom identifiers, user IDs, payment reference, and so on.
   • Check out the options for metadata in the Okra app reference.

Embed your app

1. Embed your app

   Grab the Payments app that you created and embed it in your application or website.

   • For apps that you created through the App Builder or the API, you can simply embed the short_URL integration snippet in your code.
   • When you initialize your Payments app directly through your application or website, simply embed the buildWithOptions integration snippet. Make sure that you define callbacks!

   Learn more about how to embed your app.

2. Initialize the Okra app & take payment

   Users open the Okra app, select their bank, enter correct bank credentials and authorize a payment with their PIN or OTP.

   This initiates a payment request.

1. Listen for Payments webhooks

   Once a payment is initiated, the Okra API triggers the Payments webhooks that help you stay notified about the status of each payment. Build a logic in your app to handle the various payment statuses.

   Check the status field in the webhook payload:

   • is_success means the payment is successful and you can proceed to verify the payment status in the next step
   • is_failed means the payment failed. Check the payment.error object in the webhook payload for details. You can see an overview of all payment errors in the API reference.
   • is_pending means the payment is still processing. Wait for is_success or is_failed status and proceed accordingly.

2. Verify payment status

   After you receive a payment_success webhook, Okra recommends that you verify the payment's status. This verification can help you handle situations when a technical issue prevents your user from going through with their payment.

   In situations like this, your API might not receive a notification about the payment, and you may be unable to verify the status of the payment on your side. This can result in incorrectly cancelling or refunding a transaction, or even creating duplicate transactions through an unnecessary retry. To avoid these scenarios, verify payments through the Okra API before giving value.

   These are the available statuses:

   Status	Description
   PENDING	The payment is submitted to Okra and is in queue to be processed.
   INITIATED	The payment is initiated.
   ERROR	Occurs when there is a payment error from the bank or insufficient funds from the user's account. More information at error statuses.
   SUCCESS	The payment is successful and responds with any success 2xx status code, 200 or 201.
   SUCCESS_PENDING_VALIDATION	The payment is successful but is pending settlement and validation.
   CANCELLED	The payment is cancelled by the client or the API.
   REVIEW	The payment has been reviewed.
   FAILED	The payment was declined by the bank network or has otherwise expired.

   Check out the API reference about payment verification for more details.

Get familiar with the Payments documentation, the API reference for the Payments endpoints, and understand the different IDs that the Okra API uses.

Test your app

Okra provides a sandbox environment for building and testing your integration. This environment offers realistic data that follows standard use cases. You can test the API, generate test users, go through your Okra app workflow, and even implement webhooks in this environment.

Learn how you can test your app in sandbox.

Go live

After you finish building, embedding, and testing your app, you can start the last step - going live. Here's what you need to do:

• Schedule a go-live integration call with Okra
• Switch API keys from sandbox to production in your app
• Switch callback URL from sandbox to production
• Execute Order form
• Set up a settlement account

Okra recommends that you only launch your product to a subset of your users. This can help you fine-tune the Payments operation before scaling up to a larger user base.

Need help?

• 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 get stuck anywhere in the process.