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

Bank linking is gated by the Meld bank-linking entitlement on the user. Without it, calls return 403 Forbidden with error code GATE-403-001. 
GET /v0/accounts/link/config
Always call this first. The response tells you the link-flow configuration before you initiate. 
{
  "provider": "meld",
  "requires_institution_selection": true,
  "_links": { ... }
}
Meld 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 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.

​
Endpoint surface

AspectEndpoint
Link configurationGET /v0/accounts/link/config — provider=meld, requires_institution_selection=true
Institution discoveryGET /v0/bank-linking/institutions
Initiate linkPOST /v0/accounts/link — returns 202 Accepted with widget_url
Token exchangeImplicit via Meld webhook (BANK_LINKING_ACCOUNTS_UPDATED)
Processor tokenPOST /v0/bank-linking/accounts/{account_id}/processor-token
Account management/v0/accounts/* — list, get, sync, delete
The /v0/bank-linking/* namespace covers Meld-specific operations (institutions, processor tokens). The /v0/accounts/* namespace covers ongoing account management.