Skip to main content
This reference is scoped to the shipped Meld slices: client setup (server-side, no partner endpoints), KYC passthrough (server-side, no partner endpoints), and bank linking. Buy/sell and off-ramp endpoints are not included until those slices ship. For the conceptual model behind these endpoints, see Meld overview, Bank linking, and KYC passthrough.

​
Authentication

All endpoints require the standard Sumvin partner authentication. The user is derived from the auth context — no user_id parameter is accepted. The bank-linking endpoints require the user to have the Meld bank-linking entitlement (a server-side feature gate). Without it, calls return 403 Forbidden with error code GATE-403-001.

​
Provider configuration

GET /v0/accounts/link/config
Returns the provider Sumvin will route the user through and whether the partner needs to collect an institution selection. Responses
​
provider
string
"meld" or "plaid". Determined per user by feature gate.
​
requires_institution_selection
boolean
true for Meld — the partner must list institutions, then pass the selected institution_id on link initiation. false for Plaid.GET /v0/bank-linking/institutions — List institutions.POST /v0/accounts/link — Initiate the link.
​
_links
object
HAL links to self, link, and accounts.
Status codes
CodeMeaning
200 OKConfig returned.
401 UnauthorizedMissing or invalid partner credentials.
403 ForbiddenUser does not pass the resolved provider’s gate.

​
Bank linking

​
List institutions

GET /v0/bank-linking/institutions
Returns the catalog of institutions Meld can connect to, optionally filtered. Query parameters
​
region
string
Filter to institutions present in this country code (e.g. US, GB).
​
products
string[]
Filter to institutions that support all of the named Meld products (e.g. BALANCES, IDENTIFIERS, OWNERS, TRANSACTIONS). Repeatable.
​
search
string
Case-insensitive name substring match.
Response
​
institutions
InstitutionData[]
Institutions matching the filters.
​
total
integer
Number of institutions in the response.
InstitutionData fields:
​
id
string
Meld institution id. Pass as institution_id when initiating the link.POST /v0/accounts/link
​
name
string
Display name.
​
country_codes
string[]
ISO country codes the institution operates in.
​
logo_url
string | null
Logo URL if available.
​
url
string | null
Institution website if available.
​
products
string[]
Meld products the institution supports.
Status codes
CodeMeaning
200 OKInstitutions returned (possibly empty).
401 UnauthorizedMissing or invalid partner credentials.
403 ForbiddenUser does not have the Meld bank-linking entitlement.
POST /v0/accounts/link
Initiates a Meld bank-linking session. Returns 202 Accepted with the widget URL the user opens to complete the connect flow.
This endpoint is shared with Plaid. The shape of link in the response varies by provider (discriminated union). For Plaid, link carries link_token and the response is 200 OK. Sections below describe the Meld variant.
Request body
​
institution_id
string
required
Required when the resolved provider is Meld. Sourced from the institution list.GET /v0/bank-linking/institutions
​
redirect_uri
string
Optional; passed through to the underlying provider where supported.
​
products
string[]
Optional; defaults to ["BALANCES", "IDENTIFIERS", "OWNERS", "TRANSACTIONS"].
​
regions
string[]
Optional; restricts available institutions inside the widget.
Response (Meld variant)
​
link.provider
string
"meld".
​
link.widget_url
string
URL to render the Meld institution-connect widget.
​
link.connect_token
string
Connect token issued by Meld for this session.
​
link.customer_id
string | null
Meld customer id associated with the user.
​
link.institution_id
string | null
Echo of the requested institution id.
​
_links
object
HAL links to self, accounts, and poll (/v0/accounts?status=pending_connection).
Status codes
CodeMeaningError code
202 AcceptedMeld widget URL issued; account creation is asynchronous.—
400 Bad Requestinstitution_id missing for the Meld path.BANK_INSTITUTION_REQUIRED
401 UnauthorizedMissing or invalid partner credentials.—
403 ForbiddenUser does not pass the Meld gate.GATE-403-001
500 Internal Server ErrorSumvin failed to obtain a Meld connect token.BANK_LINK_TOKEN_FAILED

​
Issue a processor token

POST /v0/bank-linking/accounts/{account_id}/processor-token
Mints a processor-specific token for a previously linked account so a downstream payment processor can debit or credit it. Path parameters
​
account_id
string
required
The Meld provider_account_id of the linked account. (This is the Meld-side identifier on the account, not the Sumvin external_id.)
Request body
​
processor
string
required
Name of the downstream processor for which to mint the token. Refer to Meld’s processor compatibility list for valid values.
Response
​
processor_token
string
The processor-issued token.
​
account_id
string
Echo of the account id.
Status codes
CodeMeaningError code
201 CreatedToken issued.—
401 UnauthorizedMissing or invalid partner credentials.—
403 ForbiddenUser does not own the account or does not have the bank-linking entitlement.BANK_ACCOUNT_UNAUTHORIZED, GATE-403-001
404 Not FoundNo Meld-provided account with this id.BANK_ACCOUNT_NOT_FOUND

​
Linked account management

The endpoints below are provider-agnostic — they operate on accounts regardless of whether they were linked via Meld or Plaid. They are listed here for convenience because they are how a partner observes the result of a Meld bank-linking flow.

​
List accounts

GET /v0/accounts?provider=meld
Lists accounts owned by the authenticated user. Query parameters
​
provider
string
Optional. Filter to one provider (meld or plaid).
​
status
string
Optional. Filter by account status (e.g. active, pending_connection, refresh_required, disconnected, error).
​
account_type
string
Optional. Filter by account type (e.g. checking, savings).
Response Returns accounts: AccountData[] and total. See AccountData under Get account.

​
Get account

GET /v0/accounts/{account_id}
Returns a single account. Response fields
​
id
string
Sumvin external_id of the account.
​
provider
string
"meld" or "plaid".
​
account_type
string
Mapped account type (checking, savings, credit_card, loan, investment).
​
status
string
Lifecycle state derived from provider connection state. See the table in Bank linking.
​
institution_name
string
Display name of the institution.
​
institution_logo_url
string | null
Logo URL if available.
​
account_name
string
Display name on the account at the institution.
​
account_mask
string | null
Last few digits if available.
​
balance_current
decimal | null
Current balance, in balance_currency.
​
balance_available
decimal | null
Available balance, in balance_currency.
​
balance_currency
string
ISO currency code (defaults to USD if Meld did not provide one).
​
connection_id
string | null
The Meld connection id (provider_connection_id). Useful for correlating with webhook events.

​
Sync account

POST /v0/accounts/{account_id}/sync
Triggers a background sync of balances and transactions for the account. Returns 202 Accepted immediately with a sync_event_id. Poll the account back for the updated last_synced_at. GET /v0/accounts/{account_id}

​
Disconnect account

DELETE /v0/accounts/{account_id}
Disconnects the account. For Meld accounts, Sumvin calls Meld to delete the underlying connection, then soft-deletes the account record. Returns 204 No Content.

​
Webhooks

Meld posts events to a single Sumvin endpoint. Partners do not subscribe directly — Sumvin consumes these and updates partner-visible resources.

​
Endpoint

POST /v0/webhooks/meld/events
Required headers:
HeaderPurpose
meld-signatureBase64-encoded HMAC-SHA256 of <timestamp>.<url>.<body> keyed by the configured webhook secret.
meld-signature-timestampUnix epoch seconds. Sumvin rejects requests older than 5 minutes.
A missing or invalid signature returns 401 Unauthorized with error code MELD_WEBHOOK_INVALID_SIGNATURE. A successfully verified webhook always returns 200 OK with {"received": true} once the handler has been dispatched, even if the handler itself fails — the event is logged for follow-up rather than retried at the HTTP layer.

​
Events Sumvin handles

Event typeWhat Sumvin does
CUSTOMER_KYC_STATUS_CHANGELogs the change. The Sumvin-side KYC state remains driven by SumSub.
BANK_LINKING_CONNECTION_COMPLETEDInformational. Logged; account creation happens on the next event.
BANK_LINKING_ACCOUNTS_UPDATEDUpserts accounts under the user, mapping Meld account types to Sumvin’s taxonomy.
BANK_LINKING_TRANSACTIONS_AGGREGATEDTriggers a background sync to pull transactions for the affected accounts.
BANK_LINKING_HISTORICAL_TRANSACTIONS_AGGREGATEDSame handler as above; runs on the historical backfill batch.
BANK_LINKING_CONNECTION_STATUS_CHANGEUpdates status and status_reason on every account under the connection.
BANK_LINKING_CONNECTION_DELETEDSoft-deletes every account under the connection.
BANK_LINKING_ACCOUNTS_UPDATINGRecognised but no handler — informational only.
Crypto-transaction event types (TRANSACTION_CRYPTO_*) are recognised by the webhook router; their handlers are part of the buy/sell slice and are not partner-observable today.

​
Error code reference

Errors follow RFC 7807 Problem Details with a Sumvin error_code field.
Error codeWhen it fires
BANK_INSTITUTION_REQUIREDPOST /v0/accounts/link was called against the Meld provider without institution_id.
BANK_LINK_TOKEN_FAILEDSumvin failed to mint a connect token from the underlying provider.
BANK_PROVIDER_ERRORThe underlying provider returned an error during a token exchange or sync.
BANK_ACCOUNT_NOT_FOUNDThe referenced account does not exist for any user.
BANK_ACCOUNT_UNAUTHORIZEDThe referenced account exists but does not belong to the authenticated user.
MELD_WEBHOOK_INVALID_SIGNATUREA Meld webhook was rejected because of a missing or invalid signature, or a stale timestamp.
GATE-403-001The authenticated user does not pass the Meld bank-linking feature gate.