The Transactions Flow

The transactions flow can be used to acquire a list of transactions of a specific account of the consumer. At the end of the flow the XS2A-API returns one array of Transaction objects which can differ depending on the selected bank, as some banks provide more information than others.

In order to request the balance of a specific account, the account identifier or the IBAN can be passed in the payload of the request. If neither the identifier nor the IBAN is set the consumer has to select an account, if more than one account is present.

A transactions flow is only possible for account type DEFAULT.

The timeframe for which the transaction should be obtained can be set by specifying either the from_date and to_date field or the since field.

NOTE: Some banks limit the transactions to specific time frames, e.g. only the last 90 days from today. If the requested time frame is not supported we either adjust it and return the available transactions or return an error.

If neither the from_date and to_date date properties nor the since property are provided, then by default the transactions of the past 30 days are extracted.

The two possible options to specify the timeframe are listed below:

{
    "iban": ?string,
    "account_id": ?string,
    "from_date": ?string,
    "to_date": ?string
}

iban String, optional

The IBAN of the account for which the transactions flow should be executed.

account_id String, optional

The account identifier - as provided in the result of an accounts flow - of the account for which the transactions flow should be executed.

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

The from_date property (in combination with the to_date property) can be used to determine the start date of the transactions search range. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

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

The to_date property (in combination with the from_date property) can be used to determine the end date of the transactions search range. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

{
    "iban": ?string,
    "account_id": ?string,
    "since": ?string
}

since String, optional

The since field can be used to query the last X number of days. Even though the property's value is an integer number it has to be provided as a string.

Response Structure of a successful Transactions Flow

{
    "data": {
        "result": ?{
            "transactions": Array<Transaction>,
            "account": Account,
            "from_date": string,
            "to_date": string,
            "incomplete": boolean,
            "type": string
        },
        "state": enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'ABORTED', 'EXCEPTION', 'FINISHED'>
    }
}

data.result.type String, always present

For successful flows the type property always holds the value transactions.

data.result.transactions Transaction[], always present

An array that contains the extracted transactions.

data.result.account Account, always present

The account for which the transactions were extracted.

data.result.from_date Date (String: "YYYY-MM-DD"), always present

The start date of the timeframe for which the transactions were extracted. It is provided in the YYYY-MM-DD format according to ISO 8601.

data.result.to_date Date (String: "YYYY-MM-DD"), always present

The end date of the timeframe for which the transactions were extracted. It is provided in the YYYY-MM-DD format according to ISO 8601.

data.result.incomplete Boolean, always present

The incomplete boolean indicates whether or not all of the available transactions for the given timeframe could be retrieved. Please see the section "Transactions Flows flagged as incomplete" below for further information on how to handle incomplete transaction results.

Example Response for a successful Transactions Flow

{
    "data": {
        "result": {
            "transactions": [
                {
                    "reference": "Flight 123",
                    "amount": {
                        "amount": 12345,
                        "currency": "EUR"
                    },
                    "counter_party": {
                        "id": "123e4567-e89b-12d3-a456-426655440000",
                        "alias": "Girokonto",
                        "account_number": "123456789",
                        "iban": "DE44500105175407324931",
                        "holder_name": "Max Mustermann",
                        "holder_address": {
                            "street_address": "Konrad-Adenauer-Straße 21",
                            "street_address2": "Backside of the House, Floor 2",
                            "postalcode": "35440",
                            "city": "Linden",
                            "region": "Hesse",
                            "country": "DE"
                        },
                        "bank_code": "51091700",
                        "bic": "VRBUDE51XXX",
                        "bank_name": "VR Bank Untertaunus eG",
                        "bank_address": {
                            "street_address": "Konrad-Adenauer-Straße 21",
                            "street_address2": "Backside of the House, Floor 2",
                            "postalcode": "35440",
                            "city": "Linden",
                            "region": "Hesse",
                            "country": "DE"
                        },
                        "transfer_type": "NONE",
                        "account_type": "DEFAULT"
                    },
                    "date": "2018-10-23",
                    "state": "PROCESSED",
                    "type": "DEBIT",
                    "method": "TRANSFER"
                }
            ],
            "account": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "alias": "Girokonto",
                "account_number": "123456789",
                "iban": "DE44500105175407324931",
                "holder_name": "Max Mustermann",
                "bank_code": "51091700",
                "bic": "VRBUDE51XXX",
                "bank_name": "VR Bank Untertaunus eG",
                "transfer_type": "FULL",
                "account_type": "DEFAULT",
                "balance": {
                    "amount": 12345,
                    "currency": "EUR"
                }
            },
            "from_date": "2018-10-05",
            "to_date": "2018-10-25",
            "incomplete": false,
            "type": "transactions"
        },
        "state": "FINISHED"
    }
}

Transactions Flows flagged as incomplete

If the incomplete property in the response of a transactions flow is true, not all of the transactions that happened within the specified timeframe could be retrieved from the bank. This might happen, because of a timeout of the connection between Open banking. by Klarna and the bank.

It is recommended to start another transactions flow for which the date of the oldest previously received transaction is set as the from_date property.

Example: For a transactions flow with from_date set to 2020-01-08 and to_date set to 2020-02-08 the following data - with "incomplete": true - is returned:

{
    "data": {
        "result": {
            "transactions": [
                {
                    "transaction_id": "r29ndc7gqflfcgdnvpala41njf6c8j7s",
                    "reference": "Kd 1234",
                    "amount": {
                        "amount": 1599,
                        "currency": "EUR"
                    },
                    "counter_party": {
                        "holder_name": "John Doe",
                    },
                    "date": "2020-02-04",
                    "state": "PROCESSED",
                    "type": "DEBIT"
                },
                {
                    "transaction_id": "qdsr1muh80eoe1e2iol4muvk2i185iit",
                    "reference": "Walmart Customer Refund",
                    "amount": {
                        "amount": 19540,
                        "currency": "EUR"
                    },
                    "counter_party": {
                        "iban": "DE44700700700700700700",
                        "bic": "DEUTDEDBMUC"
                    },
                    "date": "2020-01-29",
                    "state": "PROCESSED",
                    "type": "CREDIT"
                }
            ],
            "account": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "alias": "Girokonto",
                "account_number": "123456789",
                "iban": "DE44500105175407324931",
                "holder_name": "Max Mustermann",
                "bank_code": "51091700",
                "bic": "VRBUDE51XXX",
                "bank_name": "VR Bank Untertaunus eG",
                "transfer_type": "FULL",
                "account_type": "DEFAULT",
                "balance": {
                    "amount": 12345,
                    "currency": "EUR"
                }
            },
            "from_date": "2020-01-08",
            "to_date": "2020-02-08",
            "incomplete": true,
            "type": "transactions"
        },
        "state": "FINISHED"
    }
}

Since the oldest transaction has the date 2020-01-29 an additional transactions flow with the from_date left unchanged (2020-01-08) and the to_date set to 2020-01-29 has to be executed in order to retrieve the missing transactions.

results matching ""

    No results matching ""