Categorized Transactions Report

Build a report with transactions belonging to requested customer and account and fitting the provided date range. It will show all transactions enriched with category and brand information.

This report can be requested via the Modular Report endpoint. Specific for this report are those options:

ReportOptions

{
    "size" : ?Integer,
    "offset": ?Integer,
    "max_amount": ?Integer,
    "min_amount": ?Integer,
    "insights_transaction_ids": ?Array<String>,
    "category_ids": ?Array<String>,
    "brand_ids": ?Array<String>,
    "order": ?Array<ReportOptionsOrderBy>
}

size Integer, optional

Only return a maximum of size transactions in the report. The default will be unlimited.

offset Integer, optional

Returns the transaction after skipping the first offset number of transactions. Default will be 0, so no transactions will be skipped.

max_amount Integer, optional

Filter the transactions to include only transactions with amount less or equal the max_amount parameter. The amount needs to be provided in the smallest unit of currency. See the amount parameter of the amount object.

min_amount Integer, optional

Filter the transactions to include only transactions with an amount of at least min_amount. The amount needs to be provided in the smallest unit of currency. See the amount parameter of the amount object.

insights_transaction_ids String[], optional

Filter the transactions to include only transactions with the given transaction-ids.

category_ids String[], optional

Filter the transactions to include only transactions matching the categories identified by the category_ids. The id must match a category from the Category List.

brand_ids String[], optional

Filter the transactions to include only transactions matching the brands identified by the brand_ids.

order ReportOptionsOrderBy[], optional

Use this parameter to return the transactions in a specific order.

ReportOptionsOrderBy

{
    "order": ?Enum<'ASC', 'DESC'>,
    "field": Enum<'AMOUNT','DATE','CATEGORY','BRAND'>
}

order Enum, optional

Sets the direction of order: ascending or descending. The default setting is ascending.

field Enum, required

The transactions will be ordered by the field from this enum.

Response Structure of Categorized Transactions Report

The generated report will be part of the modular report response.

{
    "type": "CATEGORIZED_TRANSACTIONSV2",
    "transactions": Array<CategorizedTransaction>
}

type String, always present

The type always contains the value "CATEGORIZED_TRANSACTIONSV2" for this report.

transactions CategorizedTransaction[], always present

List of all transactions for one account with added data about categories and brands.

CategorizedTransaction

{
    "insights_transaction_id": ?String,
    "ob_transaction_id": ?String,
    "value_date": ?Date,
    "booking_date": ?Date,
    "amount": Amount,
    "reference": ?String,
    "bank_references": ? {
        "unstructured": ?String,
        "structured": ?String,
        "end_to_end": ?String
    },
    "state": ?Enum<'PROCESSED', 'PENDING', 'CANCELED', 'FAILED'>,
    "type": Enum<'DEBIT', 'CREDIT'>,
    "method": Enum<'TRANSFER', 'DIRECT_DEBIT', 'INSTANT', 'UNKNOWN'>,
    "bank_transaction_code": ? {
        "code": ?String,
        "sub_code": ?String,
        "description": ?String
    },
    "counter_party": ?{
        "iban": ?String,
        "account_number": ?String,
        "bic": ?String,
        "bank_code": ?String,
        "holder_name": ?String,
        "holder_address": ?{
            "country": ?String
        }
    },
    "categories": Array<CategorizedTransactionCategory>,
    "brand": ?Brand
}

insights_transaction_id String, optional

The Account Insights identifier for the transaction.

ob_transaction_id String, optional

The identifier for the transaction as given by the XS2A API.

value_date Date (String: "YYYY-MM-DD"), optional

The date on which the transaction was valued by the bank (usually in accounting).

booking_date Date (String: "YYYY-MM-DD"), optional

The date on which the transaction was booked.

amount Amount, always present

The unsigned amount of the transaction.

reference String, optional

The reference for the transaction.

bank_references Object, optional

Some banks offer a subset of the transactions reference in different fields. Those fields are given in the BankReference object.

bank_references.unstructured String, optional

The unstructured reference that was really returned from the bank without any modifications.

bank_references.structured String, optional

Part of the reference as delivered by bank.

bank_references.end_to_end String, optional

This value can be used for reconciliation and transaction matching.

state Enum, optional

The state of the transaction.

Possible values are:

  • PROCESSED - The transaction was processed
  • PENDING - The transaction is still pending and not yet processed
  • CANCELED - The transactions was canceled
  • FAILED - The transaction was not processed

type Enum, always present

The type property indicates whether funds were withdrawn (DEBIT) or applied (CREDIT) to the account.

Possible values are:

  • DEBIT - Funds were withdrawn from the account
  • CREDIT - Funds were applied to the account

method Enum, always present

The type property indicates which transaction method was used.

Possible values are:

  • TRANSFER - A DEBIT transaction that was initiated by the consumer
  • DIRECT_DEBIT - A DEBIT transaction
  • INSTANT - An INSTANT transaction
  • UNKNOWN - A transaction that could not be classified

bank_transaction_code Object, optional

The Bank Transaction Code as provided by the bank. This information allows the customer to correctly report a transaction, which will help to - for example - perform reconciliation operations.

The values of this object are not normalized and the meaning and format could differ per PSD2-framework or even per bank. For more information, visit the related PSD2-API documentation of the specific banks. Some banks (e.g. Berlin-Group PSD2) follow the ISO-20022 Standard.

bank_transaction_code.code String, optional

Specifies the business area of the underlying transaction. There is no guarantee that the code-field follows the ISO-20022 Standard.

bank_transaction_code.sub_code String, optional

Specifies the sub-product family within a specific family. There is no guarantee that the sub_code-field follows the ISO-20022 Standard.

bank_transaction_code.description String, optional

A textual description of the bank_transaction_code.

counter_party Object, optional

The other party involved in the transaction. Can be empty for some transactions.

counter_party.iban String, optional

The bic of the counter party account.

counter_party.account_number String, optional

The account number of the counter party account.

counter_party.bic String, optional

The bic of the counter party account.

counter_party.bank_code String, optional

The bank code of the counter party account.

counter_party.holder_name String, optional

The name of the counter party account holder.

counter_party.holder_address.country String, optional

The country code in the ISO 3166-1 alpha-2 format, e.g. DE, GB, SE.

categories Category[], always present

Any transaction could match a number of categories. All those matched categories will be reported as a list here.

brand Brand, optional

If the transaction was sent to or received from a known brand, this will be shown in the brand property.

Example request

{
    "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
    "insights_account_ids": 
        [
            "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
        ],
    "report_days": 60,
    "reports": [
        {
            "type": "CATEGORIZED_TRANSACTIONSV2",
            "options": {
                "max_amount": 1000,
                "min_amount": -1000,
                "limit": 3
            }
        },
    ]
}

Example response

{
    "data": {
        "accounts": [
            {
                "insights_account_id": "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1",
                "reports": [
                    {
                        "type": "CATEGORIZED_TRANSACTIONSV2",
                        "transactions": [
                            {
                                "ob_transaction_id": "31234-12314234",
                                "booking_date": "2020-01-01",
                                "amount": {
                                        "amount": 1599,
                                        "currency": "EUR"
                                },
                                "reference": "transfer to esprit online shop",
                                "bank_references": {
                                    "unstructured": "esprit online  shop"
                                },
                                "type": "DEBIT",
                                "method": "UNKNOWN",
                                "bank_transaction_code": {
                                    "code": "CCRD",
                                    "sub_code": "CreditCardPayment",
                                    "description": "Transaction is related to a payment of credit card."
                                },
                                "counter_party": {
                                    "holder_name": "esprit germany",
                                    "holder_address": {
                                        "country": "DE"
                                    }
                                },
                                "categories": [
                                    {
                                        "id": "a9184d59-25be-5f03-aebb-f639a5ed9a8a",
                                        "name": "Clothes"
                                    }
                                ],
                                "brand": {
                                    "id": "664bb3a2-62c9-52b7-9ccd-81cfe904258c",
                                    "name": "Esprit"
                                },
                                "insights_transaction_id": "ae66102e-f4ff-5e02-8f95-ad0bbd225e19"
                            },
                            {
                                "value_date": "2020-01-01",
                                "amount": {
                                        "amount": 679,
                                        "currency": "EUR"
                                },
                                "reference": "rewe sagt danke",
                                "type": "DEBIT",
                                "method": "TRANSFER",
                                "state": "PROCESSED",
                                "counter_party": {
                                    "holder_name": "rewe gmbh"
                                },
                                "categories": [
                                    {
                                        "id": "edde5df6-fbf4-5e79-afb1-97de52d93aca",
                                        "name": "Groceries"
                                    }
                                ],
                                "brand": {
                                    "id": "71569e21-bfe3-5871-9a5a-f791cca811c0",
                                    "name": "Rewe",
                                    "icon_url": "https://x.klarnacdn.net/openbanking-de/icons/110ed771-7f71-43fc-9bcb-b8921e2881fe.png"
                                },
                                "insights_transaction_id": "3a1cf972-a9bb-5fc7-b36d-12ad707f29aa"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

results matching ""

    No results matching ""