Transactions

Okra Transactions product gives you access to performant transaction data from various financial institutions across Nigeria, making it possible to analyze the data directly in your app to create better user experiences.
This short guide will show you how to take integrate transactions product on the Okra Dashboard and via the API

The data that traditional banks provide is in most cases raw, unstructured and does not provide a plug-and-play solution that accelerates time-to-market.
Today, businesses sought after a new breed of data connectivity, one that provides data seamlessly with an easy-to-integrate platform. This is where Okra expertise lies.

With the Okra widget, you can pull up to 24 months of historical and transactional statements across all banks in Nigeria, in real-time. You can do this programmatically via our API, or manually, directly through the Okra dashboard without time-consuming OTP activities with your customer, which tend to fail.
Transactions data can be useful for many different applications, including personal finance management, expense reporting, cash flow modeling, risk analysis, and more.

Okra transaction solves 3 main issues;

  1. Businesses need access to financial data: Okra helps companies pull up to 24 months of historical and transactional statements across all banks in Nigeria, in real-time.
  2. Financial data is raw and badly structured: Okra utilizes machine learning algorithms to clean, analyze this raw data, so they can become useful for businesses.
  3. Integrating financial data into your products is usually cumbersome: At Okra our plug-and-play solution via the widget and various developer-friendly SDKs eliminates integration stress and accelerates time-to-market.

How it works

Okra Widget is a front-end SDK that allows integrating with Okra as simple as writing a few lines of code. End-users will be prompted to link their account(s) and login with their bank if Transactions are included in your product flows. If the developer receives permission, he or she will be able to view all of the account's transactions.

Data Availability

  • Account types: Corporate accounts, savings accounts
  • Account information: Account number, identifier, balance, account type
  • Basic information: Amount, date, description
  • User information: Merchant name, Biodata

👍

Refresh Transactions in real-time!

Need your customer's most recent transaction history? Easily Refresh Transactions on any of their accounts connected to you.

We have standardized the data across all financial institutions to allow you to pull one standard format across all banks in Nigeria via internet banking or USSD. We use machine learning technology to take the traditional non-descriptive narrative and break it down into: channel, benefactor, category, date, balance at the time of the transaction, geolocation data, flagging, and more — allowing us to give you the context and content behind transactions.

Read more about Transactions in the Transaction Deck.

Get Context and Content

Transaction data can be useful for many different applications, including personal finance management, expense reporting, cash flow modeling, risk analysis, and more. Okra's Transactions product allows you to access a user's transaction history via the /transactions/get endpoint.

📘

Limited history or Need more context?

For Institutions that provide limited transactions and for non-programmatic needs we provide access to the customer's bank generated account statement, checkout PDF Statements for more info. You can also checkout Enhanced Transactions for a more detailed transaction view.

Transactions data includes the transaction date, amount, and more. Transaction data is lightly cleaned to populate the name field.

Transaction Model

Field Description
id
ObjectID
Unique Auth ID (Unique Okra Identifier)
debit
Number
The amount deducted from an account
credit
Number
The amount credited to an 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 transaction was fetched
last_updated
Date
Last date transaction fetched
trans_date
Date
The date a transaction occurred
cleared_date
Date
The date a transaction was cleared at the bank
unformatted_trans_date
String
The date transaction occurred (from the bank)
unformatted_cleared_date
String
The date transaction cleared (from the bank)
branch
String
The branch transactions occurred
ref
String
The bank reference ID (from the bank)
env
String
Okra API env the transaction was pulled from production or production-sandbox
code
String
Bank Code (from the bank)
benefactor
ObjectID
Customer ID of the sender (within Okra)
location
String
The location or channel the transaction took place
notes
Object
Breakdown of Narrative from bank
bank
ObjectID
Unique Bank ID (Unique Okra Identifier)
balance
Number
Balance after transaction line
mean
Integer
Mean Average Error: Average ‘naira’ the statement is off by

How to add transaction to your app

In this guide, we'll start from scratch and walk through how to use Transactions to perform an initial fetch of a user's transaction history. If you are already familiar with using Okra and are set up to make calls to the Okra API, you can skip to how to check transaction.

Get Okra API Keys

If you don't already have one, you'll need to create an Okra developer account. After creating your account, you can find your API keys under the Settings menu on the Okra developer dashboard.
To better understand how Okra API keys works, check this tutorial

How to check transaction

  1. Make a POST request to https://api.okra.ng/v2/transactions/refresh with the account_id as payload.

For a more detailed breakdown of transactions, including categories and geolocation data, check out our Transactions Add-Ons.

curl -X POST https://api.okra.ng/v2/transactions/refresh
-H 'Content-Type: application/json' 
-H 'Authorisation: Bearer <secretKey>'
-d '{
    "account_id":  OKRA ACCOUNT ID, // Account ID of connected customer
}'
  1. After two minutes, make a GET request to data.callback_url in the response in step 1
curl -X GET https://api.okra.ng/v2/callback?record=60f1ab12dfa83247a9e139e3&method=REFRESH_TRANSACTIONS
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
{
    "status": "success",
    "message": "Callback successfully returned!",
    "data": {
        "transactions": [
            {
                "_id": "60f1991c12e3c4c9a4ddc522",
                "bank": "5d6fe57a4099cc4b210bbeba",
                "cleared_date": "2021-07-06T00:00:00.000Z",
                "credit": null,
                "customer": "5fb1c2767c35c767741805c6",
                "debit": 3.75,
                "notes": {
                    "desc": "card maintenance fee - 709 for 2nd quarter 2021 ac-pl52073",
                    "topics": [],
                    "places": [],
                    "people": [],
                    "actions": [
                        "fee"
                    ],
                    "subjects": [
                        "card maintenance",
                        "quarter",
                        "ac"
                    ],
                    "prepositions": [
                        "for"
                    ]
                },
                "ref": "ft21187101270316",
                "trans_date": "2021-07-06T00:00:00.000Z",
                "account": "5fb1cf6f108b577e6e10795d",
                "balance": 550.17,
                "bank_balance": 550.17,
                "location": "admiralty way",
                "created_at": "2021-07-16T14:35:04.385Z",
                "currency": "NGN",
                "env": "production",
                "last_updated": "2021-07-16T14:43:45.112Z",
                "owner": [
                    "5da6358130a943486f33dced"
                ],
                "record": [
                    "60f19907dfa83247a9e12827",
                    "60f19b0fdfa83247a9e12afa"
                ],
                "unformatted_cleared_date": "06 JUL 2021",
                "unformatted_trans_date": "06 JUL 2021",
                "projects": [
                    "5ff62b99aea7a57a5c3baa01"
                ],
                "fetched": [
                    "5da6358130a943486f33dced"
                ]
            },
            {
                "_id": "60f1991c12e3c4c9a4ddc52c",
                "bank": "5d6fe57a4099cc4b210bbeba",
                "cleared_date": "2021-07-06T00:00:00.000Z",
                "credit": null,
                "customer": "5fb1c2767c35c767741805c6",
                "debit": 50,
                "notes": {
                    "desc": "card maintenance fee - 709 for 2nd quarter 2021",
                    "topics": [],
                    "places": [],
                    "people": [],
                    "actions": [
                        "fee"
                    ],
                    "subjects": [
                        "card maintenance",
                        "quarter"
                    ],
                    "prepositions": [
                        "for"
                    ]
                },
                "ref": "ft21187101270316",
                "trans_date": "2021-07-06T00:00:00.000Z",
                "account": "5fb1cf6f108b577e6e10795d",
                "balance": 500.17,
                "bank_balance": 500.17,
                "created_at": "2021-07-16T14:35:04.385Z",
                "currency": "NGN",
                "env": "production",
                "last_updated": "2021-07-16T14:43:45.112Z",
                "owner": [
                    "5da6358130a943486f33dced"
                ],
                "record": [
                    "60f19907dfa83247a9e12827",
                    "60f19b0fdfa83247a9e12afa"
                ],
                "unformatted_cleared_date": "06 JUL 2021",
                "unformatted_trans_date": "06 JUL 2021",
                "projects": [
                    "5ff62b99aea7a57a5c3baa01"
                ],
                "fetched": [
                    "5da6358130a943486f33dced"
                ]
            }
        ],
        "last_transaction_date": "2021-07-06T00:00:00.000Z",
        "product": "REFRESH_TRANSACTIONS",
        "record": "60f19b0fdfa83247a9e12afa",
        "products": {
            "auth": true,
            "accounts": true,
            "balance": true,
            "periodic-transactions": true
        },
        "status": {
            "process": {
                "running": false,
                "completed": true
            }
        }
    }
}

Transaction Callback

When you refresh the balance, the response is not instantaneous because we must interact with the customer's financial institution. As a result, you will receive a callback_url as in the JSON response example above. You can view an example of how to handle the response and retrieve the balance in real-time.

exports.fetchTransactions = async (req, res, next) => {
    req.setTimeout(0)
    const baseURL = 'https://api.okra.ng/v2'
    const {account_id,record_id,currency,waitTime} = req.body   //waitTime is in minutes
    const token = `Your_JWT_token`
    let config = {
        headers: {
            'Content-Type': 'application/json',
            Authorization: `Bearer ${sekretKey}`
        }
    }
    const getTransactionReq = () => {
        try {
            return axios.post(`${baseURL}/transactions/refresh`, { account_id: account_id, record_id: record_id, currency: currency }, config)
        } catch (error) {
            console.error(error)
        }
    }
    const getCallBackData = (data) => {
        try {
            return axios.get(data, config)
        } catch (error) {
            console.error(error)
        }
    }
    const getCallBackReq = async () => {
        getTransactionReq()
            .then(async response => {
                if (response.data.data) {
                    await waitFor(waitTime * 60000) // convert minutes to millisconds
                    return [response.data.data.callback_url.replace("undefined", "callback")].join('')
                }
            }).then(callBack => {
                getCallBackData(callBack)
                    .then(response => {
                        res.json(response.data)
                    })
                    .catch(error => {
                        console.log(error)
                    })
            })
            .catch(error => {
                console.log(error)
            })
    }
    getCallBackReq()
}

const waitFor = (ms) => new Promise(r => setTimeout(r, ms))

PDF Statements

For Institutions that provide limited transactions and for non-programmatic needs we provide access to the customer's bank-generated account statement for the limit set in within your app integration or link.

Statements can be fetched via the API and also can be viewed and downloaded directly on our dashboard.

Via the Dashboard

To get statements via the dashboard, the following are the steps you must follow,

  • Get logged in, else signup here if you don't have an account already
  • After log in, navigate to products, thereafter click on transaction.

You should see a page like this below if you navigated correctly.

Transaction PageTransaction Page

Transaction Page

  • Next, you can click on any of the transaction you like to get a statement, and then you be taken to a page like this below.
Get StatementGet Statement

Get Statement

  • The last step is to select the Export as button, select pdf, and automatically it will download the statement in PDF format.

:tada: It was quite easy to get a statement from your dashboard wasn't it?

🎉 Now that you understand how the transaction works, check out the API Reference page to test the transaction API in real-time.


Did this page help you?