Tink.AccountCheck (Tink v0.1.1)

Copy Markdown View Source

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

Summary

Functions

build_continuous_access_link(map, opts)

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

build_link_url(map, opts)

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

create_authorization(client, params)

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

create_session(client, params)

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

create_user(client, params)

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

delete_user(client, user_id)

Deletes a user and all associated data.

get_account_parties(client, account_id)

Gets parties (account holders) for a specific account.

get_report(client, report_id)

Retrieves an Account Check verification report.

get_report_pdf(client, report_id, opts \\ [])

Retrieves an Account Check verification report as a PDF.

get_user_access_token(client, code)

Exchanges an authorization code for a user access token. Delegates to Tink.Users.get_user_access_token/2.

grant_user_access(client, params)

Grants a user access and generates an authorization code for Tink Link.

list_accounts(client, opts \\ [])

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

list_identities(client)

Lists identities (user information) from connected accounts.

list_reports(client, opts \\ [])

Lists all account verification reports for the authenticated client.

list_transactions(client, opts \\ [])

Lists transactions for the authenticated user. Delegates to Tink.Transactions.list_transactions/2.

Functions

build_continuous_access_link(map, opts)

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

create_authorization(client, params)

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

create_session(client, params)

@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(client, params)

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

delete_user(client, user_id)

@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(client, account_id)

@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(client, report_id)

@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(client, report_id, opts \\ [])

@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(client, code)

Exchanges an authorization code for a user access token. 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 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(client, opts \\ [])

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

list_identities(client)

@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(client, opts \\ [])

@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(client, opts \\ [])

Lists transactions for the authenticated user. Delegates to Tink.Transactions.list_transactions/2.