Overview

In this section, you'll learn the basics steps you can follow to integrate Okra Direct Debits via the Widget or the API using the sandbox environment.

Getting started

The getting started steps include;
:white-check-mark: Signup
:white-check-mark: Login to your dashboard
:white-check-mark: Request payment access via [email protected]
:white-check-mark: Check out the sandbox credentials you require to get started.


Payment features

At Okra, we offer a variety of payment features that makes dealing with payments integration seamless in your projects.
The following are the payment features available at Okra;

  • Payment Links - Create a payment link from your dash with no-code and send it to any of your merchants to send payments with ease.
  • One-time payments - This allows you to simply receive a one-time payment from your customers.
  • Recurring payments - Collect recurring and subscription-based payments from your customers.
  • Future payments - Get customer authorization so you can collect future payments on their account.
  • Bulk payments - This allows you to initiate multiple debit payments to a bulk list of customers.
  • Refunds - Make refunds to your customers with ease.
  • Garnishments - This helps vendors legally collect money from accounts to repay outstanding debt.
  • Payouts - Receive funds seamlessly into your account connected to Okra.

Payment objects

Field Description
id
ObjectID
Unique Auth ID (Unique Okra Identifier)
available_balance
Number
Amount of available funds in the account
ledger_balance
Number
The closing balance of the account
account
ObjectID
Unique account ID (Unique Okra Identifier)
connected
Boolean
Customer connection status (Did they choose to connect this account to you?)
customer
ObjectID
Unique customer ID (Unique Okra Identifier)

See Manage Customers ]
record
ObjectID
Unique record ID (Unique Okra Identifier)

See Records
owner
ObjectID
Unique company ID (Unique Okra Identifier) ( Your Client Token)
env
String
Okra API Env the Auth was pulled from production or production-sandbox
created_at
Date
Date of Authentication
last_updated
Object
Last date of Authentication

Payment status

While making a payment, technical issues can prevent your customer from paying and your API from receiving a response. Without this response, you may be unable to verify whether the payment has been processed or it's either canceled or completed.

This may cause you to attempt to cancel or refund the transaction, or risk a duplicate transaction.

Instead, your integration should request the payment status to verify whether the transaction is success, pending, initiated, cancelled, completed, error, review, success_pending_validation, failed.

Status messages

Status

Description

PENDING

The payment is submitted to Okra and is in the queue to be processed.

INITIATED

The payment is initiated.

COMPLETED

The payment was completed whether or not it was successful or it failed.

ERROR

It occurs when there is a payment error from the bank or insufficient funds from the customer account.
More information at error statuses.

SUCCESS

The payment is successful and responds with ANY success status code 2XX, like 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 otherwise expired.


Check a payment status

Verify payments

This endpoint allows you to verify the status of a payment initiated

curl -X POST https://api.okra.ng/v2/pay/verify
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "payment_id":"PAYMENT ID"
}'
{
    "status": "success",
    "message": "Payment Status suceccefully retrieved!",
    "data": {
        "payment_status": {
            "_id": "5f88ebf63103d912f1d4baca",
            "amount": 10000, //kobo
            "currency": "NGN",
            "customer": "5f5b67748df30163f294f432",
            "link": {
                "_id": "5f824ed45f283033c424f530",
                "url": "https://dev-pay.okra.ng/wyred",
                "short_url": "wyred",
                "surl": "https://dev.okr.to/wyred"
            },
            "status": "completed",
            "response_status": "success"
        }
    }
}

Cancel payments

You can cancel a payment if you no longer intend to use it to collect payment from the customer. Canceling a payment is optional, and it’s okay to keep the payment in an incomplete status. Incomplete payments are useful in understanding your conversion rates.

Payment can only be canceled when it has one of the following statuses: initialized or
pending

curl -X POST https://api.okra.ng/v2/pay/cancel
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{ 
        payment_id: "xxxxxxxxxxxxxxxx"
    }'

A Payment can’t be canceled while it is actively processing or once it has succeeded.

When a Payment is canceled, you can no longer use it to perform additional charges. Any operations that your application attempts to perform on a canceled Payment will fail with API Errors.

Check the reference to test in real-time.


Did this page help you?