Ultimate Guide to Payment

A comprehensive guide on how Okra payment works

Introduction

This guide covers the basics of Okra payments and explains how to integrate them into your product and services.

Okra Payments enables your users with bank accounts to make real-time payments without manually entering their account number and sort code, or leaving your app. For example, your app might allow users to accumulate a credit balance that they can cash out to a bank account, or it might allow users to pay you. You can also provide transfers to a third party, such as in a marketplace application. You can create both one-time payments (also known as Single Immediate Payments) as well as standing orders that make recurring payments on a regular schedule.

There are two ways to integrate with Okra for Payment Initiation: Okra Payment API, which allows customers to own the end-to-end experience, and Okra widget, which allows customers to use existing Okra SDKs or front-end components to get up and running quickly with our payments products.

How does it work?

An okra payment method works in such a way that customer gives authorization to the payment provider to automatically deduct money from their bank account. This payment authorization can be done either manually or electronically. Before the customer’s bank will allow a transaction on an account, the customer must have authorized the merchant to place a debit on their account either immediately or on a later date. There are two levels of carrying out payment on the customer’s account.

  • Direct charge - This is a one-time payment that only allows you to debit the customer once and which means that the customer has to give authorization anytime they want to carry out the payment.
  • Auto debit - This is also known as recurring charges, this type of direct debit gives the merchant permission to place a debit on the customer’s account without requiring the customer to put their pin.

Why Okra Payment?

Okra payment feature enables businesses to charge customers’ accounts without asking for authorization, which is also known as tokenized payment.

Steps on how to integrate Okra Payment

The secret key is your gateway to maximizing Okra suites of API's, the secret key is always needed at the point where you'll need to interface with Okra API.
The secret key should be kept safe and should not go to the public.

Steps on how to integrate Okra Payment

Step 1 - Authentication - To place a debit on your customer’s account, you must first authenticate your customer on the Okra’s widget, this enables the customer to give you consent to carry out actions on their account. You can authenticate your customer either on the widget link or via the API.
For a guide on how to generate a link follow the tutorial on how to authenticate a customer via the widget link, and you can generate this link on the dashboard or via the API.
For a guide on how to generate a link via the dashboard check this guide

To learn how you could generate a payment link via the API, check this short guide.

Integration

https://github.com/okraHQ/okra-js

Step 2 - Choose a payment option (One time, recurring)

When setting up the widget (Okra app link for authentication), you will have to turn on payment in order to be able to debit your customer’s account.

One-time /Recurring payment - This means that you will be able to debit the customer’s account either once or on a recurring basis, and this option should be checked on the widget.

You can initiate a direct debit either via the widget (https://docs.okra.ng/docs/initiate-via-the-widget) or API (https://docs.okra.ng/docs/initiate-via-api). There is also an option for bulk direct debit.

ii. Future payments - Feature allows you to set up recurring or one-time debit for a future date and also set when the debit should stop, you also have the privilege to charge an initial amount and set others on a later date.  (https://docs.okra.ng/docs/recurring-payments).

What details are needed for Okra direct debit?

Account ID of the account to debit - Means the okra identifier for the customer’s account number to be debited. This has been returned after a successful authorization on Okra’s widget.
Account ID of the account to credit (optional) - Account ID means the okra identifier for customer/business account number to be credited. The account ID will be returned after a successful authorization on Okra’s widget. Amount -  Figure to be charged.

What are the features of Okra’s unique feature on direct debit against other financial institutions?

  1. Authorization ID for future charges (recurring or one-time) - Preauthorized/tokenization feature combined.

  2. Garnishment -   This would both check the available balance and if there are funds in the account it would process the transaction for the maximum possible amount minus any minimum you set to leave in the account, which means that you can recover part of the funds instead of getting insufficient funds. This feature is only possible on the account connected to you. Eg. Ifunanya left 10k in her account for loan repayment but due to bank SMS charges every month, the loan repayment technically won’t happen as the bank will return insufficient funds because the available balance has been reduced to 9,950.00, so instead of the loan company getting insufficient funds response, the garnishment feature will enable them to collect 9000 from the customer’s account and set a retry on the balance of 1k on a later date.3. GSI - This feature allows you to garnish any other account the customer has with Okra that is not connected to you directly. Eg. Funmi has taken a loan from Carbon for 20k and had it deposited into her GTB at repayment she has -10k in the account. Funmi has also at some point connected to Umba with her Keystone (5k balance) and Renmoney with her Access (5k balance) ... Here Okra will debit 5k from each of these accounts and additionally if there is 5k in the GTB Okra will first take from there then one of the others. In the first option, it would incur a 176 naira charge (63 2 + 25 2) and the second would incur a 151 naira charge (63 * 2 + 25)

  3. Save on NSF fees - This would help save cost as Okra first runs a check on the customer’s account balance before initiating a charge.

  4. Account Balance status  - Okra free balance check endpoint lets you know when your customer’s account balance has changed so you can place a charge on the account if there is a pending payment yet to be completed by the customer.

Payment Webhooks

To set up and receive webhooks anytime a transaction is performed on your account, check out this short guide for a walkthrough.

Frequently Asked Questions about Okra Direct Debit

  • What happens if there is not enough money in my bank account for direct debit? Okra will return a response of “insufficient balance” and you won’t be charged for it.
  • How will I know if the customer’s balance has changed? Okra has a solution that enables you to check if the balance has been changed or not.
  • What is the list of banks supported for payment on Okra? https://docs.okra.ng/docs/payment-coverage-1
  • What is the meaning of "direct debit reversal"? It means that money is returned back into the customer’s account after it has been debited, this might occur as a  result of timeout from the bank and the payment wasn’t settled to the merchant account or dispute from the customer for an erroneous debit.

Handling Errors

Common bank errors

  1. Account linking ( Authentication)

This means errors that are returned directly from the customer's bank to connect your account to the Okra’s widget (https://docs.okra.ng/docs/bankerrors).

  1. Payment
    This means errors that are returned directly from the customer's bank when a charge is placed to the customer’s account (https://docs.okra.ng/docs/payment-errors).

Payment status

Initialize
This means that the payment has been created and queued for processing. Once the status of the payment change, you will get a callback from Okra and you are advised to call the /verify endpoint to get the final status of the payment. See the doc (https://docs.okra.ng/docs/verify-a-payment)

Canceled

This means that the customer didn’t fulfill the payment, either that it was abandoned or the widget was closed.

Success-pending-validation

This means that the bank processed the payment status but there was no callback from them which might be because of a timeout.

Success

The payment was successfully processed.

Error

This can be an error from the bank or an unknown error.

For a complete list of the payment and bank errors, check here

Conclusion

Contact [email protected] to get access to Okra payment feature and start making payment seamless for your integration.


Did this page help you?