Transactions

Learn how to take control of your transactions on our Okra Dashboard

Overview

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.

👍

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 standardised 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 @ get.okra.ng/transactions-deck.

Get Context and Content

Transaction data can be useful for many different applications, including personal finance management, expense reporting, cash flow modelling, risk analysis, and more. Okra's Transactions product allows you to access a user's transaction history via the /transactions/get endpoint, which can provide transaction history for both depository type accounts such as current and savings accounts.

📘

Limited history or Need more context?

For Institutions that provide limited transactions and for non programmatic needs we provide access tot he 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

FieldDescription
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)
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

Refresh Transaction

/transactions/refresh is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for an item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any transactions-enabled Item. Changes to transactions are discovered after calling /transactions/refresh.

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
}'
{
    "status": "success",
    "message": "Transactions processing...",
    "data": {
        "callback_url": "https://api.okra.ng/v2/callback?record=60f19907dfa83247a9e12827&method=REFRESH_TRANSACTIONS",
        "record": "60f19907dfa83247a9e12827",
        "method": "REFRESH_TRANSACTIONS"
    }
}

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))

How to check the transaction

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

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,
                "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
            }
        }
    }
}

Enhanced Transactions

For a deeper understanding and categorization of your transactions, you can run them through our NER (Named Entity Recognizer). We take each transaction narration, coupled with additional information of the customer's transactions to make the information easy to work with, we put them in these categories: channel, benefactor, category, date, balance at the transaction time, geolocation data, flagging, and much more.

curl -X POST https://api.okra.ng/v2/transactions/process
-H 'Content-Type: application/json' 
-H 'Authorisation: Bearer <secretKey>'
-d '{
    "account":  OKRA ACCOUNT ID, // Account ID of connected customer
}'
{
    "status": "success",
    "message": "Transactions retrieved successfully",
    "data": {
        "pagination": {
            "totalDocs": 236,
            "limit": 5,
            "hasPrevPage": false,
            "hasNextPage": true,
            "page": 1,
            "totalPages": 48,
            "pagingCounter": 1,
            "prevPage": null,
            "nextPage": 2
        },
        "transaction": [
            {
                "_id": "60427241a67cb326c5293b77",
                "bank": {
                    "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Fidelity+Bank+Nigeria+Logo+Color.svg",
                    "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Fidelity+Bank+Nigeria+Logo.svg",
                    "name": "Fidelity Bank",
                    "status": "healthy"
                },
                "cleared_date": "2021-02-27T23:00:00.000Z",
                "credit": null,
                "customer": {
                    "_id": "5e9498cfe5df76cc8b2e64f3",
                    "name": "Lorem ipsum"
                },
                "debit": 128,
                "notes": {
                    "desc": "sms alert charges 18feb 21",
                    "topics": [],
                    "places": [],
                    "people": [],
                    "actions": [],
                    "subjects": [
                        "sms",
                        "18feb"
                    ],
                    "prepositions": []
                },
                "ref": "000000010450 / 000000004710",
                "trans_date": "2021-02-28T23:00:00.000Z",
                "__v": 0,
                "account": {
                    "_id": "5e97790b71fbf1a44eb8a197",
                    "name": "Lorem ipsum",
                    "nuban": "3456789876",
                    "type": "Savings"
                },
                "balance": null,
                "branch": "others",
                "created_at": "2021-03-05T18:02:39.613Z",
                "currency": "NGN",
                "env": "production",
                "last_updated": "2021-03-06T00:01:04.781Z",
                "record": [
                    "6042717362d2a175293aa6ba"
                ],
                "unformatted_cleared_date": null,
                "unformatted_trans_date": null,
                "fetched": [
                    "5d9288ea182d3d000cb7c486"
                ],
                "analyzed": [
                    "2021-03-06T00:01:09.400Z",
                    "2021-03-06T00:01:04.781Z"
                ],
                "ner": {
                    "TRANS_TYPE": "Sms Alert Charges"
                },
                "nerOwner": [
                    null
                ],
                "ner_v": 1.1,
                "id": "60427241a67cb326c5293b77"
            }
           
        ]
    }
}

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 download 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?

To check for transaction endpoints visit the API Reference


Did this page help you?