Skip to main content
Meld bank linking lets a user connect a bank account to their Sumvin profile through the Meld widget. The link result populates the user’s accounts, makes balance and transaction data available, and supports issuing processor tokens for downstream payment use.

​
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 (when that ships), 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 provider that Sumvin operates means the partner integrates against /v0/accounts/* and /v0/bank-linking/* rather than against Meld directly.

​
Provider routing

The bank-linking endpoint family is shared across providers. Sumvin chooses Meld or Plaid for a given user based on a feature gate — if the user has the Meld bank-linking entitlement, all /v0/accounts/link* calls route through Meld; otherwise they route through Plaid. 
GET /v0/accounts/link/config
Always call this first. The response tells you which provider you are about to use and whether you need to collect an institution selection from the user. 
{
  "provider": "meld",
  "requires_institution_selection": true,
  "_links": { ... }
}
The Plaid path does not require institution selection (Plaid Link presents one). The Meld path does — 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 Meld’s 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 Meld widget. On success, Meld posts BANK_LINKING_CONNECTION_COMPLETED to Sumvin’s webhook endpoint. This event is informational — account data lands in the next step.
4

Account data arrives

Meld posts BANK_LINKING_ACCOUNTS_UPDATED with the populated account list. Sumvin upserts each account against the user, mapping Meld’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, Meld posts BANK_LINKING_TRANSACTIONS_AGGREGATED (and ..._HISTORICAL_... for backfill). 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 asks Meld to mint 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 Meld delivers BANK_LINKING_ACCOUNTS_UPDATED. 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 on the roadmap. Until then, polling is the supported pattern.

​
Connection lifecycle

After the initial link, Sumvin tracks the connection’s status from Meld’s BANK_LINKING_CONNECTION_STATUS_CHANGE webhook:
Meld statusSumvin account status
ACTIVEactive
DEGRADEDactive
RECONNECT_REQUIREDrefresh_required
DISCONNECTEDdisconnected
ERRORerror
If the connection moves to refresh_required, the user needs to re-authenticate. Repair flows (re-opening the Meld widget against an existing connection) are operated server-side; surface the user-facing prompt based on the account’s status field. When the user disconnects the account, Sumvin asks Meld to delete the connection and soft-deletes the corresponding accounts. DELETE /v0/accounts/{account_id} — Disconnect a linked account.

​
Scope boundary versus Plaid

Both Meld and Plaid bank linking flow through the same /v0/accounts/* endpoint family. The differences:
AspectMeld pathPlaid path
GET /v0/accounts/link/configprovider=meld, requires_institution_selection=trueprovider=plaid, requires_institution_selection=false
POST /v0/accounts/linkReturns 202 Accepted with widget_urlReturns 200 OK with link_token
Token exchangeImplicit via webhookExplicit via POST /v0/accounts/link/exchange
Institution discoveryGET /v0/bank-linking/institutionsPlaid Link UI handles it
Processor tokenPOST /v0/bank-linking/accounts/{account_id}/processor-tokenPlaid native processor token endpoint
Account inheritanceWebhook-driven (BANK_LINKING_ACCOUNTS_UPDATED)Synchronous from link/exchange response
The /v0/bank-linking/* namespace is currently Meld-specific (institutions, processor tokens). The /v0/accounts/* namespace is provider-agnostic and is where ongoing account management lives.