# `Tink.BalanceCheck`
[🔗](https://github.com/iamkanishka/tink.ex/blob/v0.1.1/lib/tink/balance_check.ex#L1)

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

## Links

- [Tink Balance Check Documentation](https://docs.tink.com/resources/balance-check)

# `build_consent_update_link`

```elixir
@spec build_consent_update_link(String.t(), map()) :: String.t()
```

Builds a Tink Link URL for updating a provider consent.

## Parameters

  * `consent_id` - Provider consent ID
  * `params` - Link parameters:
    * `:client_id` - Your client ID (required)
    * `:redirect_uri` - Callback URL (required)
    * `:market` - Market code (optional)

## Returns

  * Tink Link URL string

## Examples

    url = Tink.BalanceCheck.build_consent_update_link("consent_123", %{
      client_id: "your_client_id",
      redirect_uri: "https://yourapp.com/callback"
    })
    #=> "https://link.tink.com/1.0/account-check/update-consent?..."

# `build_continuous_access_link`

```elixir
@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"
    })

# `build_link_url`

```elixir
@spec build_link_url(map()) :: String.t()
```

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

## Parameters

  * `params` - Link parameters:
    * `:client_id` - Your client ID (required)
    * `:redirect_uri` - Callback URL (required)
    * `:market` - Market code (required)
    * `:locale` - Locale code (optional)
    * `:test` - Test mode (optional, default: false)

## Returns

  * Tink Link URL string

## Examples

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

# `create_authorization`

Creates an authorization grant for a user.

Delegates to `Tink.Users.create_authorization/2`.

# `create_user`

Creates a new Tink user.

Delegates to `Tink.Users.create_user/2`.

# `get_account_balance`

```elixir
@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`

```elixir
@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`

Gets a user access token from an authorization code.

Delegates to `Tink.Users.get_user_access_token/2`.

# `grant_user_access`

```elixir
@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`

Lists all accounts for the authenticated user.

Delegates to `Tink.Accounts.list_accounts/2`.

# `list_provider_consents`

```elixir
@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`

Lists transactions for the authenticated user.

Delegates to `Tink.Transactions.list_transactions/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*