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

Account Check API for verifying bank account ownership and details.

This module provides comprehensive account verification capabilities through
two main workflows:

## 1. Account Check with User Match (One-time Verification)

Verify account ownership by matching user information (name) against bank records.
Perfect for KYC, onboarding, and one-time verification needs.

### Flow

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

    # Step 2: Create session with user information
    {:ok, session} = Tink.AccountCheck.create_session(client, %{
      user: %{
        first_name: "John",
        last_name: "Doe"
      },
      market: "GB"
    })

    # Step 3: Generate Tink Link URL
    tink_link_url = Tink.AccountCheck.build_link_url(session,
      client_id: "your_client_id",
      market: "GB",
      redirect_uri: "https://yourapp.com/callback"
    )

    # Step 4: User completes authentication in browser
    # After success, you receive account_verification_report_id via redirect

    # Step 5: Get access token with account-verification-reports:read scope
    report_client = Tink.client(scope: "account-verification-reports:read")

    # Step 6: Retrieve verification report
    {:ok, report} = Tink.AccountCheck.get_report(report_client, report_id)

    # Step 7: Get report as PDF (optional)
    {:ok, pdf_binary} = Tink.AccountCheck.get_report_pdf(
      report_client,
      report_id,
      template: "standard-1.0"
    )

## 2. Account Check with Continuous Access (Ongoing Access)

Verify accounts with ongoing access for repeated checks and transaction monitoring.
Perfect for subscription services, affordability checks, and recurring payments.

### Flow

    # Step 1: Get access token with user:create scope
    client = Tink.client(scope: "user:create")

    # Step 2: Create permanent user
    {:ok, user} = Tink.AccountCheck.create_user(client, %{
      external_user_id: "user_123",
      market: "GB",
      locale: "en_US"
    })

    # Step 3: Get access token with authorization:grant scope
    grant_client = Tink.client(scope: "authorization:grant")

    # Step 4: Grant user access for Tink Link
    {:ok, grant} = Tink.AccountCheck.grant_user_access(grant_client, %{
      user_id: user["user_id"],
      id_hint: "john.doe@example.com",
      scope: "authorization:read,authorization:grant,credentials:refresh,credentials:read,credentials:write,providers:read,user:read"
    })

    # Step 5: Build Tink Link URL
    tink_link_url = Tink.AccountCheck.build_continuous_access_link(grant, %{
      client_id: "your_client_id",
      products: "ACCOUNT_CHECK,TRANSACTIONS",
      redirect_uri: "https://yourapp.com/callback",
      market: "GB",
      locale: "en_US"
    })

    # Step 6: User connects bank in browser

    # Step 7: Create authorization for data access
    {:ok, auth} = Tink.AccountCheck.create_authorization(grant_client, %{
      user_id: user["user_id"],
      scope: "accounts:read,balances:read,accounts.parties:readonly,identities:readonly,transactions:read,provider-consents:read"
    })

    # Step 8: Exchange code for user access token
    {:ok, token_response} = Tink.AccountCheck.get_user_access_token(
      client,
      auth["code"]
    )

    # Step 9: Fetch user data
    user_client = Tink.client(access_token: token_response["access_token"])

    {:ok, accounts} = Tink.AccountCheck.list_accounts(user_client)
    {:ok, parties} = Tink.AccountCheck.get_account_parties(user_client, account_id)
    {:ok, identities} = Tink.AccountCheck.list_identities(user_client)
    {:ok, transactions} = Tink.AccountCheck.list_transactions(user_client,
      booked_date_gte: "2024-01-01",
      booked_date_lte: "2024-12-31"
    )

## Report Structure

Account verification reports contain:

- **Verification Status**: MATCH, NO_MATCH, or INDETERMINATE
- **Account Details**: IBAN, account number, sort code
- **Account Holder**: Name from bank records
- **Match Confidence**: HIGH, MEDIUM, LOW
- **Timestamp**: When verification was performed

## Required Scopes

Different operations require different OAuth scopes:

- Session creation: `link-session:write`
- User creation: `user:create`
- Authorization grant: `authorization:grant`
- Report retrieval: `account-verification-reports:read`
- Account data: `accounts:read`, `balances:read`
- Transactions: `transactions:read`
- Identities: `identities:readonly`, `accounts.parties:readonly`

## Links

- [Tink Account Check Documentation](https://docs.tink.com/resources/account-check/)
- [Continuous Access Guide](https://docs.tink.com/resources/transactions/continuous-connect-to-a-bank-account)

# `build_continuous_access_link`

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

Builds a Tink Link URL for continuous access flow with authorization code.

## Parameters

  * `grant` - Grant response containing authorization `code`
  * `opts` - Options (all required unless noted):
    * `:client_id` - Your Tink client ID
    * `:market` - Market code (e.g., "GB")
    * `:locale` - Locale code (e.g., "en_US")
    * `:redirect_uri` - Redirect URI after completion
    * `:products` - Products to enable (default: "ACCOUNT_CHECK,TRANSACTIONS")

## Returns

  String URL to redirect user to for bank authentication

## Examples

    grant = %{"code" => "auth_code_xyz"}

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

# `build_link_url`

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

Builds a Tink Link URL for Account Check with the given session.

## Parameters

  * `session` - Session map containing `sessionId` from `create_session/2`
  * `opts` - Options:
    * `:client_id` - Your Tink client ID (required)
    * `:market` - Market code (default: "GB")
    * `:redirect_uri` - Redirect URI (default: "https://console.tink.com/callback")

## Returns

  String URL to redirect the user to for authentication

## Examples

    session = %{"sessionId" => "abc123..."}

    url = Tink.AccountCheck.build_link_url(session,
      client_id: "your_client_id",
      market: "GB",
      redirect_uri: "https://yourapp.com/callback"
    )

# `create_authorization`

Creates an authorization grant for a user.
Delegates to `Tink.Users.create_authorization/2`.

# `create_session`

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

Creates a new Tink Link session with user information for account verification.

This session is used to initiate the Account Check flow where the user's
name is matched against bank account holder information.

## Parameters

  * `client` - The Tink client with `link-session:write` scope
  * `params` - Session parameters:
    * `:user` - User information (required):
      * `:first_name` - User's first name (required)
      * `:last_name` - User's last name (required)
    * `:market` - Market code (e.g., "GB", "SE", "US") - optional
    * `:locale` - Locale code (e.g., "en_US", "sv_SE") - optional
    * `:redirect_uri` - Redirect URI after completion - optional

## Returns

  * `{:ok, session}` - Session created with `sessionId`
  * `{:error, error}` - If the request fails

## Examples

    # Minimal session
    {:ok, session} = Tink.AccountCheck.create_session(client, %{
      user: %{
        first_name: "John",
        last_name: "Doe"
      }
    })
    #=> {:ok, %{"sessionId" => "abc123...", "user" => %{...}}}

    # With market and locale
    {:ok, session} = Tink.AccountCheck.create_session(client, %{
      user: %{
        first_name: "Anna",
        last_name: "Svensson"
      },
      market: "SE",
      locale: "sv_SE"
    })

## Required Scope

`link-session:write`

# `create_user`

Creates a permanent Tink user.
Delegates to `Tink.Users.create_user/2`.

# `delete_user`

```elixir
@spec delete_user(Tink.Client.t(), String.t()) :: :ok | {:error, Tink.Error.t()}
```

Deletes a user and all associated data.

## Parameters

  * `client` - Tink client with `user:delete` scope
  * `user_id` - Tink user ID to delete

## Returns

  * `:ok` - User deleted successfully
  * `{:error, error}` - If the request fails

## Warning

This action is **irreversible**. All user data will be permanently deleted.

## Required Scope

`user:delete`

# `get_account_parties`

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

Gets parties (account holders) for a specific account.

## Parameters

  * `client` - Tink client with user access token
  * `account_id` - Account ID

## Returns

  * `{:ok, parties}` - Account holder information
  * `{:error, error}` - If the request fails

## Examples

    {:ok, parties} = Tink.AccountCheck.get_account_parties(
      user_client,
      "account_123"
    )
    #=> {:ok, %{
    #     "parties" => [
    #       %{"name" => "John Doe", "type" => "OWNER"}
    #     ]
    #   }}

## Required Scope

`accounts.parties:readonly`

# `get_report`

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

Retrieves an Account Check verification report.

## Parameters

  * `client` - Tink client with `account-verification-reports:read` scope
  * `report_id` - Account verification report ID from redirect

## Returns

  * `{:ok, report}` - Complete verification report
  * `{:error, error}` - If the request fails

## Examples

    client = Tink.client(scope: "account-verification-reports:read")

    {:ok, report} = Tink.AccountCheck.get_report(client, "report_abc123")
    #=> {:ok, %{
    #     "id" => "report_abc123",
    #     "verification" => %{
    #       "status" => "MATCH",
    #       "nameMatched" => true,
    #       "matchConfidence" => "HIGH"
    #     },
    #     "accountDetails" => %{
    #       "iban" => "GB29NWBK60161331926819",
    #       "accountHolderName" => "John Doe"
    #     },
    #     "timestamp" => "2024-01-15T10:30:00Z"
    #   }}

## Required Scope

`account-verification-reports:read`

# `get_report_pdf`

```elixir
@spec get_report_pdf(Tink.Client.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, Tink.Error.t()}
```

Retrieves an Account Check verification report as a PDF.

## Parameters

  * `client` - Tink client with `account-verification-reports:read` scope
  * `report_id` - Account verification report ID
  * `opts` - Options:
    * `:template` - PDF template (default: "standard-1.0")

## Returns

  * `{:ok, pdf_binary}` - PDF file as binary data
  * `{:error, error}` - If the request fails

## Examples

    {:ok, pdf_binary} = Tink.AccountCheck.get_report_pdf(
      client,
      "report_abc123",
      template: "standard-1.0"
    )

    File.write!("verification_report.pdf", pdf_binary)

## Required Scope

`account-verification-reports:read`

# `get_user_access_token`

Exchanges an authorization code for a user access token.
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 a user access and generates an authorization code for Tink Link.

Delegates authorization to Tink Link, allowing the user to connect their
bank account through the Tink Link interface.

## Parameters

  * `client` - Tink client with `authorization:grant` scope
  * `params` - Grant parameters:
    * `:user_id` - Tink user ID (required)
    * `:id_hint` - Human-readable user identifier shown in Tink Link (required)
    * `:scope` - OAuth scopes (required)
    * `:actor_client_id` - Actor client ID (optional)

## Returns

  * `{:ok, grant}` - Grant with authorization `code`
  * `{:error, error}` - If the request fails

## Required Scope

`authorization:grant`

# `list_accounts`

Lists accounts for the authenticated user.
Delegates to `Tink.Accounts.list_accounts/2`.

# `list_identities`

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

Lists identities (user information) from connected accounts.

## Parameters

  * `client` - Tink client with user access token

## Returns

  * `{:ok, identities}` - User identity information
  * `{:error, error}` - If the request fails

## Examples

    {:ok, identities} = Tink.AccountCheck.list_identities(user_client)
    #=> {:ok, %{
    #     "identities" => [
    #       %{
    #         "firstName" => "John",
    #         "lastName" => "Doe",
    #         "addresses" => [
    #           %{"street" => "123 Main St", "city" => "London", "postalCode" => "SW1A 1AA"}
    #         ]
    #       }
    #     ]
    #   }}

## Required Scope

`identities:readonly`

# `list_reports`

```elixir
@spec list_reports(
  Tink.Client.t(),
  keyword()
) :: {:ok, map()} | {:error, Tink.Error.t()}
```

Lists all account verification reports for the authenticated client.

## Parameters

  * `client` - Tink client with `account-verification-reports:read` scope
  * `opts` - Query options:
    * `:page_size` - Number of reports per page (max 100)
    * `:page_token` - Token for pagination

## Returns

  * `{:ok, response}` - List of reports with pagination info
  * `{:error, error}` - If the request fails

## Required Scope

`account-verification-reports: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*