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:

1. Bank Selection: The user is presented with a list of banks filtered by region so they can select the bank themselves.
2. Direct Bank Page: The user is directly taken to the specific bank's page.

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. ¹

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.

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 to connected.
• Failure: The connection will transition to refresh_delayed and will be retried.

Common Causes of Failure

1. Temporary errors in retrieving transactions
2. Bank server outages
3. Expiration of consent in OpenBanking
4. Need to complete a new SCA challenge in reverse engineering connections
5. 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.

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 or Afterbanks

• 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 or CaixaBank 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.

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"
}