Tink

The Tink connector links Formance to Tink's European bank-aggregation platform. Once installed, it lets your stack drive the Open Banking PSU flow across Tink's supported markets — create a Payment Service User, forward them to Tink, hand them a Tink Link session, and once they've authenticated their bank, sync the resulting accounts, balances, and transactions back through Connectivity.

The connector first ships in Payments 3.2.0.

Prerequisites#

You need a Tink account and a clientID + clientSecret pair dedicated to Formance. Tink authenticates with an OAuth2 client-credentials grant; the connector exchanges the static client credentials for a short-lived bearer token and refreshes automatically.

The connector covers Tink's standard set of EU markets (AT, BE, DE, DK, EE, ES, FI, FR, GB, IE, IT, LV, LT, NL, NO, PL, PT, SE) — Tink itself enforces the market restriction at the Link session.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/tink \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

endpoint is https://api.tink.com for production. There is no separate sandbox endpoint — Tink uses test users on the same hostname.

Capabilities#

• FETCH_ACCOUNTS — depository accounts attached to each PSU's connections.
• FETCH_BALANCES — available + booked balance per account.
• FETCH_EXTERNAL_ACCOUNTS — counterparty accounts identified by Tink Payments when present.
• FETCH_PAYMENTS — transactions, paginated via Tink's pageToken.
• CREATE_WEBHOOKS + TRANSLATE_WEBHOOKS — at install time the connector creates webhooks per PSU's user so account-data-refreshed and consent-expiry events flow back in real time.

The connector does not initiate transfers or payouts — Tink Payments (the outbound product) is not wired here.

Linking a user#

Tink's authentication ceremony runs through Tink Link. The Connectivity surface is:

1. Create a PSU — v3CreatePaymentServiceUser. Returns a PSU ID.
2. Forward the PSU to Tink — v3ForwardPaymentServiceUserToProvider. The connector creates a Tink user and stores the resulting user_id as PSU metadata.
3. Create a Link session — v3CreateLinkForPaymentServiceUser. Returns a public https://link.tink.com/1.0/transactions/... URL plus an attemptID.
4. Frontend redirects the user to the Link URL. They pick their bank, complete strong customer authentication, and Tink redirects them back to your clientRedirectURL with an authorization code on the query string.
5. Tink posts a refresh-finished webhook. The connector exchanges the code for a refresh_token and binds the connection.

The full step-by-step walkthrough is on the Open Banking Getting Started guide.

Redirect URL requirements#

• Must be HTTPS in production.
• Must be registered under your Tink client's allowed redirect URIs.
• Mobile apps follow Tink's Android and iOS optimisation guides for the in-app browser flow.

Asset model#

Tink is multi-currency. The connector formats balances and payments to UMN with the precision per ISO 4217. Amounts are integer minor units on the wire.

Status mapping#

Tink transactions arrive in three lifecycle states:

When a PENDING transaction matures to BOOKED, Tink replaces the provisional ID with a permanent one. The connector swaps the reference and moves the row to SUCCEEDED.

Metadata keys#

Tink-specific fields land under com.tink.spec/:

• Account: account_id, name, iban, bic, account_number, holder_name, type (CHECKING / SAVINGS / CREDIT_CARD / …), flags.
• External account: counterparty_name, counterparty_account_number, counterparty_iban.
• Payment: transaction_id, provider_transaction_id, merchant_category_code, description, payee_message, payer_message, transaction_code.

PSU-level metadata carries user_id — the Tink user the connector created on the PSU's behalf.

Workflow tree#

FetchAccounts (periodic) — per PSU
  ├── FetchBalances (FromPayload — no extra API call)
  └── FetchPayments (periodic) — per PSU/account, pageToken cursor
FetchExternalAccounts (periodic)
CreateWebhooks — provisioned automatically on link

Pagination and recovery#

Tink's /data/v2/transactions endpoint uses pageToken-based pagination. The connector persists the cursor per PSU/account in the platform-managed State; restarts resume from the last committed cursor.

Known gaps#

• Tink Payments (outbound initiation) is not wired today.
• Identity and Income products aren't surfaced.
• Consent expiry: Tink connections expire after the PSD2 SCA window (usually 90 days). When the connection lapses, Tink emits a consent_expired event the connector translates to a UserConnectionPendingDisconnect → UserConnectionDisconnected pair. Trigger a fresh link via v3UpdateLinkForPaymentServiceUser to renew.