The Transactions Flow
The transactions flow can be used to acquire a list of transactions of a specific account of the consumer.
The flow is not available for all accounts. Please check the capabitilies of the account to see if it's available.
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.
The timeframe for which the transaction should be obtained can be set by specifying either the from_date and to_date field or the last_days field. If a timeframe is defined in the consent_scope.transactions then the transactions flow can only fetch transactions from dates within the defined frame.
NOTE: There is a new functionality added to this flow. When adding a preferred_pagination_size to your request you can now activate pagination for your transactions when it is available. For more information regarding this see Paginate Transactions.
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 last_days 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,
"account_number": ?String,
"allowed_accounts": ?AllowedAccounts,
"from_date": ?Date,
"to_date": ?Date,
"preferred_pagination_size": ?Integer
}
The account identifier - as provided in the result of an accounts flow - of the account for which the transactions flow should be executed.
The account number - as provided in the result of an accounts flow - of the account for which the transactions flow should be executed.
A configuration for filtering the options at the account selection for the consumer.
This can't be used in combination with the iban and account_id fields.
The from_date property (in combination with the to_date property) can be used to determine the inclusive start date of the transactions search range.
The to_date property (in combination with the from_date property) can be used to determine the inclusive end date of the transactions search range.
The preferred_pagination_size property, when defined, enables pagination of transactions. The specified value for the preferred_pagination_size is used as a basis for determining the page size. However, it is not guaranteed that the returned page size will exactly match the requested value.
In cases where the bank is incompatible with the provided value, the system will attempt to find the closest possible alternative for page size.
In the event of an incomplete retrieval, for example, because the processing time is exceeded, the already processed transactions will still be returned. This can cause the page size to be smaller than requested for individual requests.
In both scenarios, the response will include a pagination object with an adjusted offset, allowing to continue pagination normally.
{
"iban": ?String,
"account_id": ?String,
"account_number": ?String,
"allowed_accounts": ?AllowedAccounts,
"last_days": ?Integer,
"preferred_pagination_size": ?Integer
}
Response Structure of a successful Transactions Flow
{
"data": {
"result": ?{
"transactions": Array<Transaction>,
"account": Account,
"from_date": String,
"to_date": String,
"incomplete": Boolean,
"type": String,
"pagination": ?Pagination
},
"state": Enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'ABORTED', 'EXCEPTION', 'FINISHED'>
}
}
For successful flows the type property always holds the value transactions.
An array that contains the extracted transactions.
The start date of the timeframe for which the transactions were extracted (inclusive).
The end date of the timeframe for which the transactions were extracted (inclusive).
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.
The pagination object indicates whether or not a pagination is available. This object will not be present if there are no available pages. See Transactions Next for more information on this use case.
Example Response for a successful Transactions Flow
{
"data": {
"result": {
"transactions": [
{
"reference": "Flight 123",
"amount": {
"amount": 1200,
"currency": "EUR"
},
"original_amount": {
"amount": 12345,
"currency": "SEK"
},
"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,
"pagination": {
"count": 4000,
"url": "https://api.openbanking.playground.klarna.com/xs2a/v1/sessions/t2nt3piqith2hretkh6hhcuchuir510b/flows/5p80e29nr1gbe75rglt8ifl61lq9cuu0/list",
"next": {
"offset": "EYNYcTCDOqx4+8RhyMHjPKnW87ifsANLiUANDD4zDt5oO3I3y4y5Rpt0J7Cxn2RpcljIjVKm7jrGUSIVJZpkhvD7boUxUww0CTeryoLYp5fGJBWM4M+/kION/bVOCRtOSc2qT6rKcj4I5n4I2H7z+9qCWoJ5lxnRebmTxXu7y2f2+/QjrJd2K8TZak+c11rScvdMkU0ak1Fp3dxUdbRqPfO5BvBPv1rpk3a9Sb4DRlyF7Laq1WVzmK/DG0vE1zvAYk2MO5z3b0vFxnn+8LoAWD4ePDWdXtd0pFk+J7BigFv8VDC5K+8uTyG4IU8LO/0Wn2nM7j1ch1l4dsQeqze0tkEIo/PhwOrMqMlEpSQeFycLcWjzmy/ZWFIjOj8orLXJxn3/u8hD2uGD/ZkVHXOALPSOKfo20WvQMRW+pW1cZiJVDNHloGeVXa1lt4BzZH0ws2vqwEokp+xb+wejDJGWzM8sL+5ECrtavK4P1EpUQybZoauJXRbrUfMo8VxejyF1q+ugch38LQWL0zfalQegWd76nAyZ1dp2lXSqIbayUW+KBlBFCK+2DQvWB8cJgrXo+qnJKYaSdLhpCGprrjusfIaGnBul1HSWcMqRo6HSuM0KR7pic5TpukoJl4gF9BBs2QmW1p93CVWOyD45em0QtRa7W+d7Rl5ThP3xto7fw+mkgCjp69R1eOh4YBLBpBH4TIeybv2pKcKKPBMi7tPbjvZsB6VWkYG9AEqEeNtJ4KGmC7yO2ITnSjBP5JOKxMgTlA44GZwFuaZ5wo15Y6DeyL6Huik3o21x+TtfSzjl/WqIUc5aDMLphavo8ccTcQa8eOjEpM+gy5uJTB3tiC/zWV8Dyg4IIB2tsNgq3xIL2nNufaYlGKXl/tr0VDiWOLA8x5V2QroLXWBDUpSm4+gsuhLB+yNgG/V88T8A9YY=.DPEvt4m0TPRiaOuA"
}
},
"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",
"merchant_category_code": "5967"
},
{
"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.