Connection Lifecycle
initial_action_required
: User's initial action required.connecting
: Connection process ongoing.updating
: Updating bank data.action_required
: Additional user action required.connected
: Connection successfully established.refresh_delayed
: Temporary issue with bank data update.
Initial Connection
Access authorization to the bank connection will be done through KernelPay's WebView. There are two types of flows for creating the initial connection:
- Bank Selection: The user is presented with a list of banks filtered by region so they can select the bank themselves.
- Direct Bank Page: The user is directly taken to the specific bank's page.
Once the connection is created, its status is initial_action_required
. If it
remains in this state for more than 60 minutes, it will automatically
transition to disabled
.
Authorization Process
After the connection is created, the user must authorize it. Depending on the authentication method, they will either:
- Be presented with a form to enter credentials (for reverse engineering connections).
- Be redirected to an external platform for authorization (for PSD2 connections).
If the form to enter credentials is presented, the user will have input helpers and feedback on errors received during the linking. Additionally, if Strong Customer Authentication (SCA) is required, this information will be required. 1
During connection authorization, its status will temporarily transition to
connecting
.
Completion and Redirection
Once the flow is completed, the user will receive a confirmation message and will be redirected to the URL defined when the connection was created or to the project's default URL.
The connection will transition to updating
once the credentials are valid
and the retrieval of bank products and transactions begins. If the extraction
of bank transactions is successful, the connection will transition to
connected
. Since this moment, the data retrieval of bank products and transactions is available. If the extraction fails, it will transition to refresh_delayed
and will be
retried. 2
Automatic Refreshes
At least once a day, new transactions will be retrieved from all connections in the connected
state. The system prevents duplicates and checks previous transactions to ensure data consistency. The extraction schedule is conditioned by the specifics of each bank and/or bank aggregation integration.
State Transitions During Extraction
- Success: The connection will transition to
updating
and subsequently toconnected
. - Failure: The connection will transition to
refresh_delayed
and will be retried.
Common Causes of Failure
- Temporary errors in retrieving transactions
- Bank server outages
- Expiration of consent in OpenBanking
- Need to complete a new SCA challenge in reverse engineering connections
- User changing their bank credentials
The system has a retry strategy that will transition the connection to updating
and subsequently to connected
if successful. If the retry strategy fails, the connection will transition to action_required
.
From the KernelPay dashboard, a refresh of transactions can be requested on-demand at any time. Note that a manual refresh may result in a failed extraction due to factors such as banks requiring SCA to access transactions at certain times.
Action Required
When the connection is in action_required
state, user participation is most likely required. The KernelPay WebView must be presented to the user again to update credentials, complete an SCA challenge, and/or renew PSD2 consent.
Upon starting the WebView, a transaction retrieval attempt will be made so the user can take the appropriate action. This retry may work, completing the reconnection without specific user action. Otherwise, the necessary action and the error received in the last refresh will be presented.
Basic Definitions
-
Customer: A customer represents a user within the Kernel system. Creating a customer is the first step to interacting with the financial aggregation APIs.
-
Aggregation Institution: A financial institution, that can be connected to and from which data can be aggregated. Agregation Institution must be activated before connections can be established with them. For the same bank, there can be different aggregation providers and can be from diferent Aggregation Integrations. Example:
Caixabank (ES)
-
Aggregation Integration: The external provider that facilitates the aggregation providers. Multiple Agregation Integrations can be grouped under the same institution, representing various external providers to connect to and aggregate data from that institution. Examples:
Tink
orAfterbanks
-
Aggregation Provider: Represents the different aggregation methods offered by the Aggregation Integrations and witch facilitates the connection to a institution. Multiple providers can be grouped under the same institution, representing various ways to connect to and aggregate data from that institution. Examples:
CaixaBank Reverse Engineering
orCaixaBank Open Banking
. -
Aggregation Connection: Represents an established connection between a customer and a financial institution. Used to authenticate and authorize access to a customer's financial data.
-
Aggregation Product: A financial product aggregated from an institution, such as a bank account, credit card, etc. Can be used to check financial details like balances and transactions.
-
Aggregation Task: A specific task within the aggregation system, such as data refresh or identity verification. Manage and execute tasks to keep data updated and accurate.
Events and Webhooks
This documentation describes the various events related to aggregation connections and products. Each event type and its purpose are detailed below.
- Name
aggregation_connection_created
- Description
Triggered when a new aggregation connection is created.
Once the connection is created, its status is
initial_action_required
. If it remains in this state for more than 60 minutes, it will automatically transition todisabled
.
- Name
aggregation_connection_initial_action_required
- Description
Triggered when an aggregation connection requires initial user action.
- Name
aggregation_connection_connecting
- Description
Triggered when an aggregation connection is in the process of connecting.
- Name
aggregation_connection_connected
- Description
Triggered when an aggregation connection is successfully established.
When the connection status is connected, it indicates that retrieval of bank products and transactions is enabled and accessible.
- Name
aggregation_connection_refreshed
- Description
Triggered when an aggregation connection is refreshed.
- Name
aggregation_connection_action_required
- Description
Triggered when an aggregation connection requires additional user action.
- Name
aggregation_connection_refresh_delayed
- Description
Triggered when there is a delay in refreshing an aggregation connection.
- Name
aggregation_connection_disabled
- Description
Triggered when an aggregation connection is disabled.
- Name
aggregation_connection_identity_updated
- Description
Triggered when the identity associated with an aggregation connection is updated.
- Name
aggregation_product_created
- Description
Triggered when a new aggregation product is created.
Entities
Aggregation Institution
This entity represents an aggregation institution, including its status and associated providers.
{
"id": "ai123456",
"code": "INST001",
"default_provider_id": "ap_3zh4zm5u7j1krmmd2jlh",
"region": "US",
"status": {
"connection": {
"success_rate": 98.5,
"total": 1500,
"updated_at": "2024-07-08T12:34:56Z"
},
"refresh": {
"success_rate": 97.0,
"total": 1400,
"updated_at": "2024-07-08T12:34:56Z"
}
},
"meta": {
"_name": "Sample Bank"
},
"updated_at": "2024-07-08T12:34:56Z"
}
Aggregation Provider
This entity represents an aggregation provider, including its connection details and state.
{
"id": "ap_3zh4zm5u7j1krmmd2jlh",
"aggregation_institution_id": "ai_3zh4zm5u7j1krmmd2jlh",
"code": "bank_01",
"integration": "sample_integration",
"region": "US",
"type": "username_password",
"state": "active",
"status": {
"connection": {
"success_rate": 98.5,
"total": 1500,
"updated_at": "2024-07-08T12:34:56Z"
},
"refresh": {
"success_rate": 97.0,
"total": 1400,
"updated_at": "2024-07-08T12:34:56Z"
}
},
"meta": {
"_name": "Sample Bank Provider"
},
"updated_at": "2024-07-08T12:34:56Z"
}
Agregation Provider State
{
"unknown": "The state of the provider is unknown",
"discovered": "The provider has been discovered",
"active": "The provider is active",
"disabled": "The provider is disabled"
}
Aggregation Connection
This entity represents an aggregation connection, including its authentication and task data.
{
"id": "ac_3zh4zm5u7j1krmmd2jlh",
"external_id": "ext123456",
"project_id": "project123",
"customer_id": "cus_3zh4zm5u7j1krmmd2jlh",
"url_secret": "secret123",
"aggregation_institution_id": "ai_3zh4zm5u7j1krmmd2jlh",
"state": "connected",
"fingerprint": "fingerprint123",
"redirect_url": "https://example.com/redirect",
"task_data": {
"last_refresh_id": "at123456",
"last_refresh_at": "2024-07-08T12:34:56Z",
"next_refresh_at": "2024-07-09T12:34:56Z",
"last_transaction_at": "2024-07-07T12:34:56Z"
},
"meta": {
"info": "Sample meta data"
},
"identity": {
"name": "John Doe",
"id_document": "encrypted_data",
"phone_number": "123-456-7890",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1990
},
"address": {
"line_1": "123 Main St",
"line_2": "Apt 4",
"postal_code": "12345",
"city": "Anytown",
"region": "AnyState",
"country": "US"
},
"updated_at": "2024-07-08T12:34:56Z"
},
"updated_at": "2024-07-08T12:34:56Z"
}
Aggregation Product
This entity represents an aggregation product, including its type, balance, and associated task data.
{
"id": "aprod_3zh4zm5u7j1krmmd2jlh",
"external_id": "ext654321",
"project_id": "project123",
"aggregation_connection_id": "ac_3zh4zm5u7j1krmmd2jlh",
"type": "checking",
"balance": {
"amount": 1000.0,
"currency": "USD"
},
"task_data": {
"fetched_at": "2024-07-08T12:34:56Z",
"integration": "IntegrationName",
"integration_product_id": "prod123",
"integration_meta": {
"meta_key": "meta_value"
},
"task_id": "at345678"
},
"meta": {
"info": "Sample meta data"
},
"holders": {
"primary_holder": "John Doe",
"secondary_holder": "Jane Doe"
},
"bank_account_info": {
"iban": "US12345678901234567890"
},
"updated_at": "2024-07-08T12:34:56Z"
}
Agregation Product Type
{
"unknown": "Product type is unknown",
"checking": "Checking account",
"savings": "Savings account",
"credit_card": "Credit card",
"debit_card": "Debit card",
"loan": "Loan",
"investment": "Investment",
"mortgage": "Mortgage",
"insurance": "Insurance",
"pension_plan": "Pension plan",
"line_of_credit": "Line of credit"
}
Aggregation Transaction
This entity represents an aggregation transaction, including its value, balance, and associated product data.
{
"id": "atx_3zh4zm5u7j1krmmd2jlh",
"project_id": "project123",
"aggregation_product_id": "aprod_3zh4zm5u7j1krmmd2jlh",
"provider_external_id": "ext789012",
"value": {
"amount": 100.0,
"currency": "USD"
},
"balance_after": {
"amount": 900.0,
"currency": "USD"
},
"date": "2024-07-08T12:34:56Z",
"book_date": "2024-07-09T12:34:56Z",
"concept": "Payment",
"task_data": {
"fetched_at": "2024-07-08T12:34:56Z",
"integration": "IntegrationName",
"integration_transaction_id": "txn123",
"task_id": "at345678"
},
"meta": {
"info": "Sample meta data"
},
"updated_at": "2024-07-08T12:34:56Z"
}
Footnotes
-
The WebView uses the browser or operating system language to display the translated information. However, input helpers, SCA messages, or errors in credential entry are determined by the bank aggregator and may be displayed in a different language. ↩
-
The age of the transactions obtained may vary between banks and/or bank aggregation integration. ↩