Skip to main content
Bank linking lets a user connect a bank account to their Sumvin profile through the ramp widget. The link result populates the user’s accounts, makes balance and transaction data available, and supports issuing processor tokens for downstream payment use. It is part of Atomic Money — Sumvin’s payments, ramps, cards, and settlement surface.
Bank linking is in private preview.

​
Why this exists

Sumvin’s account model treats a linked bank account as a first-class resource — it can serve as a fiat settlement destination for off-ramp (off-ramp is in private preview), as a balance source for budgets and insights, and as the funding origin for ACH-style payment flows that consume a processor token. Routing those flows through one ramp that Sumvin operates means the partner integrates against /v0/accounts/* and /v0/bank-linking/* rather than against an external provider directly.

​
Provider routing

The bank-linking entitlement on the user gates the /v0/bank-linking/* endpoints — institution discovery, processor token issuance, and the connection-lifecycle operations. Without it, those calls return 403 Forbidden with error code GATE-403-001. The /v0/accounts/link/config and /v0/accounts/link entry points are not entitlement-gated.
Always call this first. The response tells you the link-flow configuration before you initiate.
The ramp flow requires institution selection — your UI must let the user pick from the institution catalog before initiating the link.

​
End-to-end flow

1

Discover institutions

Fetch the catalog — filter by region, supported products, or name search. The catalog is cached server-side; it is safe to call on every render of your bank-picker UI.GET /v0/bank-linking/institutions
2

Initiate the link

Pass the chosen institution_id. Sumvin returns 202 Accepted with a widget_url and connect_token. Embed the widget URL in your client to surface the hosted institution-connect flow to the user.POST /v0/accounts/link
3

User completes the connect flow

The user authenticates with their bank inside the ramp widget. On success, Sumvin receives a BANK_LINKING_CONNECTION_COMPLETED event on its webhook endpoint. This event is informational — account data lands in the next step.
4

Account data arrives

A BANK_LINKING_ACCOUNTS_UPDATED event arrives with the populated account list. Sumvin upserts each account against the user, mapping the provider’s account types into Sumvin’s account_type taxonomy. The accounts then surface on the list endpoint.GET /v0/accounts/
5

Transactions become available (optional)

For institutions and products that support it, a BANK_LINKING_TRANSACTIONS_AGGREGATED event (and ..._HISTORICAL_... for backfill) arrives. Sumvin triggers a background sync to pull and persist transactions against each account.
6

Issue a processor token (optional)

To use the linked account as a payment source for a downstream processor (for example, an ACH payment partner), pass the processor name. Sumvin mints the token and returns it.POST /v0/bank-linking/accounts/{account_id}/processor-token

​
Polling for completion

Bank linking is asynchronous from the partner’s perspective — the link response is 202, not the final account state. After the user closes the widget, poll the accounts list; new accounts appear once the BANK_LINKING_ACCOUNTS_UPDATED event is delivered. The poll link in the link response points at /v0/accounts?status=pending_connection for that purpose. POST /v0/accounts/link — Initiate the link (returns 202). GET /v0/accounts/ — Poll for completion. Partner-facing webhooks for these events are not yet available; polling is the supported pattern.

​
Connection lifecycle

After the initial link, Sumvin tracks the connection’s status from the BANK_LINKING_CONNECTION_STATUS_CHANGE webhook: If the connection moves to refresh_required, the user needs to re-authenticate. Surface the user-facing prompt off the account’s status field, then call POST /v0/bank-linking/connections/{connection_id}/repair to get a fresh widget_url and connect_token and re-open the connect widget against the existing connection (it returns 201 Created). Alternatively, POST /v0/bank-linking/connections/{connection_id}/refresh triggers a background refresh of the connection and returns 202 Accepted. When the user disconnects the account, Sumvin tears down the connection upstream and soft-deletes the corresponding accounts. DELETE /v0/accounts/{account_id} — Disconnect a linked account.

​
Endpoint surface

The /v0/bank-linking/* namespace covers ramp-specific operations (institutions, processor tokens, and connection lifecycle). The /v0/accounts/* namespace covers ongoing account management.