Tink.BalanceCheck (Tink v0.1.1)

Copy Markdown View Source

Balance Check API for verifying account balances and affordability.

This module provides access to balance information for affordability checks, subscription verification, and ongoing balance monitoring. It supports two flows:

1. One-time Balance Check

Quick balance verification without permanent user creation:

# Step 1: Get access token
client = Tink.client(scope: "link-session:write")

# Step 2: Build Tink Link URL
tink_link_url = Tink.BalanceCheck.build_link_url(%{
  client_id: "your_client_id",
  market: "GB",
  redirect_uri: "https://yourapp.com/callback"
})

# Step 3: User completes authentication, you receive code

# Step 4: Get account data
{:ok, token} = Tink.Auth.exchange_code(client, code)
user_client = Tink.client(access_token: token["access_token"])
{:ok, accounts} = Tink.BalanceCheck.list_accounts(user_client)

2. Continuous Access Balance Check

Ongoing balance monitoring with persistent user:

# Step 1: Create user
client = Tink.client(scope: "user:create")
{:ok, user} = Tink.Users.create_user(client, %{
  external_user_id: "user_123",
  market: "GB",
  locale: "en_US"
})

# Step 2: Grant access, build Tink Link URL
grant_client = Tink.client(scope: "authorization:grant")
{:ok, grant} = Tink.Users.create_authorization(grant_client, %{
  user_id: user["user_id"],
  scope: "accounts:read,balances:read,transactions:read,provider-consents:read"
})

# Step 3: User connects bank, then exchange code
{:ok, token} = Tink.Users.get_user_access_token(client, auth_code)
user_client = Tink.client(access_token: token["access_token"])

# Step 4: Monitor balances over time
{:ok, accounts} = Tink.BalanceCheck.list_accounts(user_client)
{:ok, balances} = Tink.BalanceCheck.get_account_balance(user_client, account_id)

Required Scopes

  • accounts:read - Read account data
  • balances:read - Read balance information
  • transactions:read - Read transactions (for context)
  • provider-consents:read - Read consent status

Summary

Functions

build_consent_update_link(consent_id, params)

Builds a Tink Link URL for updating a provider consent.

build_continuous_access_link(grant, params)

Builds a Tink Link URL for continuous access balance check.

build_link_url(params)

Builds a Tink Link URL for balance check (one-time access).

create_authorization(client, params)

Creates an authorization grant for a user.

create_user(client, params)

Creates a new Tink user.

get_account_balance(client, account_id)

Gets the current balance for a specific account.

get_provider_consent(client, consent_id)

Gets a specific provider consent.

get_user_access_token(client, code)

Gets a user access token from an authorization code.

grant_user_access(client, params)

Grants user access for Tink Link.

list_accounts(client, opts \\ [])

Lists all accounts for the authenticated user.

list_provider_consents(client)

Lists all provider consents for the user.

list_transactions(client, opts \\ [])

Lists transactions for the authenticated user.

Functions

build_continuous_access_link(grant, params)

@spec build_continuous_access_link(map(), map()) :: String.t()

Builds a Tink Link URL for continuous access balance check.

Parameters

  • grant - Authorization grant map with :code field
  • params - Link parameters:
    • :client_id - Your client ID (required)
    • :redirect_uri - Callback URL (required)
    • :market - Market code (required)
    • :locale - Locale code (optional)

Returns

  • Tink Link URL string

Examples

url = Tink.BalanceCheck.build_continuous_access_link(grant, %{
  client_id: "your_client_id",
  redirect_uri: "https://yourapp.com/callback",
  market: "GB",
  locale: "en_US"
})

create_authorization(client, params)

Creates an authorization grant for a user.

Delegates to Tink.Users.create_authorization/2.

create_user(client, params)

Creates a new Tink user.

Delegates to Tink.Users.create_user/2.

get_account_balance(client, account_id)

@spec get_account_balance(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Gets the current balance for a specific account.

Parameters

  • client - Tink client with user access token and balances:read scope
  • account_id - Account ID

Returns

  • {:ok, balance} - Account balance information
  • {:error, error} - If the request fails

Examples

user_client = Tink.client(access_token: user_access_token)

{:ok, balance} = Tink.BalanceCheck.get_account_balance(user_client, "account_123")
#=> {:ok, %{
#     "booked" => %{
#       "amount" => %{"value" => 5432.10, "currencyCode" => "GBP"},
#       "date" => "2024-01-15"
#     },
#     "available" => %{
#       "amount" => %{"value" => 5432.10, "currencyCode" => "GBP"}
#     }
#   }}

Required Scope

balances:read

get_provider_consent(client, consent_id)

@spec get_provider_consent(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Gets a specific provider consent.

Parameters

  • client - Tink client with user access token
  • consent_id - Provider consent ID

Returns

  • {:ok, consent} - Provider consent details
  • {:error, error} - If the request fails

Required Scope

provider-consents:read

get_user_access_token(client, code)

Gets a user access token from an authorization code.

Delegates to Tink.Users.get_user_access_token/2.

grant_user_access(client, params)

@spec grant_user_access(Tink.Client.t(), map()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Grants user access for Tink Link.

Delegates to Tink.Auth.delegate_authorization/2 for the delegate flow.

Parameters

  • client - Tink client with authorization:grant scope
  • params - Authorization parameters:
    • :user_id - Tink user ID (required)
    • :id_hint - Human-readable user identifier (required)
    • :scope - OAuth scopes (required)
    • :actor_client_id - Actor client ID (optional)

Returns

  • {:ok, grant} - Authorization grant with code
  • {:error, error} - If the request fails

list_accounts(client, opts \\ [])

Lists all accounts for the authenticated user.

Delegates to Tink.Accounts.list_accounts/2.

list_provider_consents(client)

@spec list_provider_consents(Tink.Client.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Lists all provider consents for the user.

Parameters

  • client - Tink client with user access token and provider-consents:read scope

Returns

  • {:ok, consents} - List of provider consents
  • {:error, error} - If the request fails

Required Scope

provider-consents:read

list_transactions(client, opts \\ [])

Lists transactions for the authenticated user.

Delegates to Tink.Transactions.list_transactions/2.