Overview

Okra’s Spending Patterns uses machine learning to analyze your users’ spending habits. Learn how you can get a clear breakdown of what your users’ spend on, and the frequency of their expenses.

How it works

Spending Patterns is a user-permissioned product. Your users can grant access to their transaction data, which the Okra API then retrieves and sends to the Natural Language Understanding unit. The NLU processes this data to determine your users' spending patterns.

The NLU analyzes and groups transaction data into spending patterns and payment methods.

Spending patterns

Patterns are data points and keywords that show what your user spends on, and the frequency of these expenses. Patterns include:

• Named Entities are keywords and sub-texts that the API identifies in transaction descriptions. These include transaction beneficiary, utility keywords, the reason for transaction, NUBAN, and spending habits.
• Spending keywords are texts that show what your users have spent on. These include gifts, vacations, gym membership, cable tv, and so on.
• Transaction chunks are transactions that are part of a larger transaction chain. The NLU identifies and tracks these transaction chains. These include partial payments and purchases made in several instalments.

The Spending Patterns Engine consumes these data points and keywords to assign each transaction into a spending category.

Payment methods

Payment methods are data points that show the payment channel and the amount of each transaction. This data consists of:

• Payment method keywords that show whether a particular debit transaction was via ATM, web or PoS, mobile or web application, or USSD.
• Transaction amounts that are used to calculate sums, percentages, and amount of times a specific payment method is used.

How to use

Okra recommends that you leverage the Spending Patterns API in this order:

1. Use the process spending patterns operation to analyze the transaction data of a user.

The response of this operation contains processed data split into spending categories and payment methods.

2. Use the get spending patterns operations to retrieve already processed spending pattern data faster.

The get by ID and get by customer operations enable you to fetch data for a single user. You can also utilize the get by record and get by date operations to retrieve data in bulk for multiple users. You can even retrieve spending pattern data for all users in your project in a single request through the get all operation.

Key features of the Spending Patterns API

Evaluating Spending Patterns Models

The Spending Patterns API combines two machine learning models to classify transactions into spending patterns and payment methods groups. The API uses a confidence score to indicate an estimated level of accuracy in classifying transaction data. The confidence score is the number of correctly classified transactions expressed as a percentage.

The NLU uses accuracy, recall, and precision to evaluate the performance of the system by deriving values from a confusion matrix. The NLU uses separate confusion matrices for spending patterns and for payment methods.

• TP: True positive - the number of transactions correctly classified into any of the spending categories
• FN: False Negative - the number of transactions incorrectly classified as not part of any of the spending categories
• FP: False Positive - the number of transactions incorrectly classified into any of the spending categories
• TN: True Negative - the number of transactions correctly classified as not part of any of the spending categories

📘

Spending patterns confidence score = (TP + TN) / (FP + FN + TP + TN) * 100

• TP: True positive - the number of transactions correctly classified as any of the known payment methods
• FN: False Negative - the number of transactions incorrectly classified as different from the known payment methods
• FP: False Positive - the number of transactions incorrectly classified as any of the known payment methods
• TN: True Negative - the number of transactions correctly classified as different from the known payment methods

📘

Payment method confidence score = (TP + TN) / (TP + TN + FP + FN) * 100

Based on the resulting confidence scores, the API calculates an average confidence score to indicate an estimated level of accuracy in classifying transaction data. This average confidence score is the weighted sum of the spending patterns and payment methods confidence score. The weighting indicators alpha and beta represent the number of transactions classified as either a spending pattern or a payment method, expressed as decimal percentages. For example, if 55 out of your user’s 100 transactions are classified as spending patterns, then alpha = 0.55.

📘

Average confidence score = (alpha * Spending patterns confidence) + (beta * Payment method confidence)

Attributes of the spending patterns objects

The Spending Patterns API returns these objects:

Attributes within summary

Attributes within breakdown

Attributes within spending_categories

The Spending Patterns API groups transaction data into spending categories. The spending_categories object returns this data, grouped by spending categories. Each spending category object has these attributes:

Attributes of details

Attributes within payment_methods

The Spending Patterns API determines what payment methods were used in the user’s transaction history. The payment_methods object returns this data, grouped by payment methods. Each payment method object has these attributes:

Attributes of details

Sample objects

Process spending patterns

curl -X POST https://api.okra.ng/v2/spending-patterns/simple
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <AccessToken>'
-d '{
    "customer_id": "614220f94833f507dc0dd9da"
    }'

{
    "data": {
        "spending_pattern": {
            "summary": {
                "cashflow": 50.97,
                "confidence": 99.92,
                "timeline_in_months": 24,
                "total_inflow": 2671075.77,
                "total_outflow": 2671024.8,
                "total_transactions": 728,
                "transactions_recognized": 728
            },
            "breakdown": {
                "payment_methods": [
                    {
                        "details": {
                            "count": 272,
                            "percentage": 50.16,
                            "sum": 1080154.69
                        },
                        "type": "ussd"
                    },
                    {
                        "details": {
                            "count": 340,
                            "percentage": 27.37,
                            "sum": 589554.35
                        },
                        "type": "mobile_web_app"
                    },
                    {
                        "details": {
                            "count": 116,
                            "percentage": 22.47,
                            "sum": 483844
                        },
                        "type": "web_pos"
                    }
                ],
                "spending_categories": [
                    {
                        "details": {
                            "count": 126,
                            "percentage": 60.3,
                            "sum": 1298510.75
                        },
                        "type": "transfers"
                    },
                    {
                        "details": {
                            "count": 464,
                            "percentage": 1.38,
                            "sum": 29880.02
                        },
                        "type": "miscellaneous"
                    },
                    {
                        "details": {
                            "count": 116,
                            "percentage": 25.47,
                            "sum": 548483.27
                        },
                        "type": "food"
                    },
                    {
                        "details": {
                            "count": 22,
                            "percentage": 12.84,
                            "sum": 276600
                        },
                        "type": "savings_investment"
                    }
                ]
            },
            "projects": [
                "1ff62b99aea7a57a5c3baa01"
            ],
            "records": [
                "13d929755427220b4befb1bb"
            ],
            "_id": "13d9297994ecb0cb5b9257b2",
            "customer": "116febac3f956e001e5b4854",
            "env": "production",
            "__v": 0,
            "created_at": "2023-02-07T16:10:00.059Z",
            "last_updated": "2023-02-07T16:10:00.059Z"
        },
        "record": "13d929755427220b4befb1bb",
        "receipt": {
            "status": true,
            "msg": "Receipt has been successfully created",
            "data": {
                "receipt": {
                    "adjustment": {
                        "receipts": []
                    },
                    "charge_breakdown": {
                        "vat": 0
                    },
                    "breakdown": {
                        "discount": 0,
                        "billable_products": []
                    },
                    "billingStatus": true,
                    "adjusted": null,
                    "adjusted_receipt": false,
                    "paid": false,
                    "fixed": false,
                    "adjusted_type": null,
                    "method": "wallet",
                    "charge": 62.25,
                    "wallet_balance": 40073.85,
                    "addons": [],
                    "archived": false,
                    "micro_lending": false,
                    "ussd_pricing": false,
                    "ussd_pricing_discount": 0,
                    "micro_lending_discount": 0,
                    "_id": "13d9297b5427220b4befb1bd",
                    "plan_term": "postpaid",
                    "owner": "5da6358130a943486f33dced",
                    "type": "spending-pattern",
                    "currency": "NGN",
                    "plan": "payg",
                    "plan_type": "1da478aa9ce2295ff32a5131",
                    "record": "13e277d45e94b5001103cc72",
                    "created_at": "2023-02-07T16:10:00.121Z",
                    "last_updated": "2023-02-07T16:10:00.121Z",
                    "__v": 0
                }
            }
        }
    }
}

For more request and response examples, check out the /spending-patterns endpoint in the API reference.