tink

README

tink-go

A complete, production-grade Go client for the Tink Open Banking API, built with Domain-Driven Design and zero external dependencies (stdlib only).

---

Design: Domain-Driven Design (DDD)

The SDK is organised into three explicit, dependency-ordered layers:

Layer rules (enforced by import direction):

• domain/ imports nothing from this module.
• infrastructure/ imports only domain/.
• application/ imports domain/ and infrastructure/.
• tink.go imports only application/ and infrastructure/http.

---

Installation

go get github.com/iamkanishka/tink-go

Requires Go 1.25+. No external dependencies — stdlib only.

---

Quick start

import (
    tink    "github.com/iamkanishka/tink-go"
    domauth "github.com/iamkanishka/tink-go/domain/auth"
    domconn "github.com/iamkanishka/tink-go/domain/connectivity"
)

// 1. Create the client (one per application, safe for concurrent use).
client := tink.New(tink.Config{
    ClientID:      os.Getenv("TINK_CLIENT_ID"),
    ClientSecret:  os.Getenv("TINK_CLIENT_SECRET"),
    WebhookSecret: os.Getenv("TINK_WEBHOOK_SECRET"),
    CacheEnabled:  true,
    MaxRetries:    3,
})

// 2. Acquire an app-level token.
token, err := client.Auth.ClientCredentials(ctx, "accounts:read,transactions:read")

// 3. Create an authorization grant for an end user.
grant, err := client.Auth.CreateAuthorizationGrant(ctx, token.AccessToken,
    domauth.CreateAuthorizationGrantParams{
        ExternalUserID: "your-user-id",
        Scope:          "accounts:read,transactions:read",
    })

// 4. Redirect the user to Tink Link.
linkURL := client.Connectivity.BuildTransactionsLink(grant.Code,
    domconn.LinkURLOptions{
        Market:      "GB",
        Locale:      "en_US",
        RedirectURI: "https://yourapp.com/callback",
    })

// 5. After callback, exchange the code for a user token.
userToken, err := client.Auth.ExchangeCode(ctx,
    domauth.AuthorizationCodeParams{Code: callbackCode})

// 6. Fetch all accounts.
accounts, err := client.Accounts.ListAll(ctx, userToken.AccessToken)

// 7. Fetch all transactions with automatic pagination.
txns, err := client.Transactions.ListAll(ctx, userToken.AccessToken,
    domtxn.ListOptions{BookedDateGte: "2026-01-01"})

---

Error handling

Every service method returns error. Use errors.As to inspect the structured type:

import (
    goerrors     "errors"
    domainerrors "github.com/iamkanishka/tink-go/domain/errors"
)

_, err := client.Accounts.ListAll(ctx, token)
var te *domainerrors.TinkError
if goerrors.As(err, &te) {
    fmt.Printf("status=%d type=%s retryable=%v\n",
        te.StatusCode, te.Type, te.Retryable())
    // te.ErrorCode   — application error code (e.g. "TOKEN_INVALID")
    // te.RequestID   — Tink request ID for support escalation
    // te.ErrorDetails — raw parsed JSON error body
}

TinkError.Retryable() returns true for network errors, timeouts, and HTTP 408/429/500/502/503/504. The infrastructure layer retries these automatically (up to Config.MaxRetries attempts with exponential backoff + jitter).

---

Webhook verification

// Register typed handlers.
client.Webhooks.On("credentials.updated", func(e *domwebhook.Event) error {
    log.Printf("credentials updated: %v", e.Data)
    return nil
})
client.Webhooks.On("*", func(e *domwebhook.Event) error {
    // Wildcard — receives every event type.
    return nil
})

// In your HTTP handler:
func handleTinkWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    sig := r.Header.Get("X-Tink-Signature")

    if err := client.Webhooks.Dispatch(body, sig); err != nil {
        http.Error(w, "webhook error", 500)
        return
    }
    w.WriteHeader(204)
}

---

Configuration reference

Field	Type	Default	Description
ClientID	string	—	Tink application client_id (required)
ClientSecret	string	—	Tink application client_secret (required)
WebhookSecret	string	—	HMAC-SHA256 secret for webhook verification
BaseURL	string	https://api.tink.com	Override for testing/staging
Timeout	time.Duration	30s	Per-request HTTP deadline
MaxRetries	int	3	Max retry attempts on transient errors
CacheMaxSize	int	512	In-memory LRU cache capacity
CacheEnabled	bool	false	Enable GET-response caching

---

Running the example

export TINK_CLIENT_ID=your_client_id
export TINK_CLIENT_SECRET=your_client_secret
go run ./examples/quickstart/

---

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package tink is the public entrypoint for the Tink Open Banking SDK for Go.

Domain-Driven Design structure

The SDK is organised into three explicit layers:

• domain/ — Pure value objects and error types. Zero I/O, zero external deps.
• application/ — Use-case services. Each subdirectory is one bounded context.
• infrastructure/ — HTTP transport, LRU cache, retry, rate limiting.

Quick start

client := tink.New(tink.Config{
    ClientID:     os.Getenv("TINK_CLIENT_ID"),
    ClientSecret: os.Getenv("TINK_CLIENT_SECRET"),
})

// 1. Acquire an app-level token.
token, err := client.Auth.ClientCredentials(ctx, "accounts:read,transactions:read")
if err != nil { log.Fatal(err) }

// 2. Create an authorization grant code for an end user.
grant, err := client.Auth.CreateAuthorizationGrant(ctx, token.AccessToken,
    auth.CreateAuthorizationGrantParams{
        ExternalUserID: "user-123",
        Scope:          "accounts:read,transactions:read",
    })

// 3. Build the Tink Link URL and redirect the user.
linkURL := client.Connectivity.BuildTransactionsLink(grant.Code,
    connectivity.LinkURLOptions{
        Market:      "GB",
        Locale:      "en_US",
        RedirectURI: "https://yourapp.com/tink/callback",
    })

// 4. After callback, exchange the code for a user token, then fetch accounts.
userToken, _ := client.Auth.ExchangeCode(ctx, auth.AuthorizationCodeParams{Code: callbackCode})
accounts, _  := client.Accounts.ListAll(ctx, userToken.AccessToken)

Error handling

var te *errors.TinkError
if goerrors.As(err, &te) {
    fmt.Println(te.StatusCode, te.Type, te.Retryable())
}

Index

• type Client
  • func New(cfg Config) *Client
• type Config

Types

type Client

type Client struct {
	// Auth provides OAuth 2.0 token flows and authorization grant operations.
	Auth *appauth.Service
	// Accounts provides bank account, credential, identity, investment, and loan access.
	Accounts *appaccount.Service
	// Transactions provides transaction listing, enrichment, categories, and statistics.
	Transactions *apptxn.Service
	// Providers provides financial institution reference data.
	Providers *appprovider.Service
	// Verification provides account check, balance check, and risk-insights flows.
	Verification *appverif.Service
	// Finance provides budgets, cash flow, and financial calendar management.
	Finance *appfinance.Service
	// Connectivity provides provider health monitoring, Connector ingestion, and Link URL building.
	Connectivity *appconn.Service
	// Webhooks provides HMAC signature verification and event dispatch.
	Webhooks *appwebhook.Service
}

Client is the top-level Tink SDK client. Each field is the application service for its bounded context. Construct via New; the zero value is not usable.

All services share a single underlying HTTP client and are safe for concurrent use by multiple goroutines.

func New

func New(cfg Config) *Client

New creates a fully-wired Tink Client from the given Config.

The returned *Client is safe for concurrent use. Create one instance per application (or one per Tink application credential pair).

type Config

type Config struct {
	// ClientID is your Tink application's client_id (required).
	ClientID string
	// ClientSecret is your Tink application's client_secret (required).
	ClientSecret string
	// WebhookSecret is the HMAC-SHA256 secret for verifying incoming webhook payloads.
	WebhookSecret string
	// BaseURL overrides the Tink API base URL. Defaults to https://api.tink.com.
	BaseURL string
	// Timeout is the per-request HTTP deadline. Defaults to 30s.
	Timeout time.Duration
	// MaxRetries is the maximum number of retry attempts on transient errors. Defaults to 3.
	MaxRetries int
	// CacheMaxSize caps the in-memory response cache. Defaults to 512 entries.
	CacheMaxSize int
	// CacheEnabled enables GET-response caching. Defaults to false.
	CacheEnabled bool
}

Config holds the SDK configuration. ClientID and ClientSecret are required; all other fields have defaults.