Skip to main content
The Meld client is configured server-side by Sumvin. Partners do not hold Meld credentials, do not call Meld directly, and do not configure widget URLs themselves.

​
Why this exists

Meld credentials carry settlement authority across the platform’s user base. Centralising them in Sumvin keeps the secret blast radius small, lets Sumvin enforce KYC and scope checks before any Meld call is made, and means a partner integration is a single set of Sumvin API calls — not a Meld credential exchange and a Sumvin credential exchange.

​
What Sumvin manages

Sumvin operates a single Meld client per environment, shared across all partner traffic.
ConfigurationOwnerNotes
Meld API keySumvinStored as MELD_API_KEY in Sumvin’s secret manager.
Meld API base URLSumvinMELD_API_URL. Defaults to the Meld sandbox; production environments override.
Meld webhook secretSumvinMELD_WEBHOOK_SECRET. Used to verify the HMAC on inbound Meld webhooks.
SumSub-for-Meld client idSumvinMELD_SUMSUB_CLIENT_ID. Identifies Meld’s SumSub tenant when sharing KYC. See KYC passthrough.
Meld API versionSumvinPinned in the client (Meld-Version header).
Sumvin uses these to construct one MeldClient instance at app startup. All Meld traffic — bank linking, KYC initiation, customer creation, webhook handling — goes through this client.

​
What partners do not configure

  • No Meld API key on the partner side.
  • No widget hostname or version pin on the partner side.
  • No direct Meld endpoint calls. Every Meld interaction is mediated by a Sumvin route.

​
What partners need to know

​
Meld customer is created lazily

A Meld customer record is created the first time a user touches a Meld-backed flow (bank linking today; ramp flows when those slices ship). The Sumvin user’s external_id is sent to Meld as externalId, and the resulting Meld customerId is persisted on the user (meld_customer_id). Subsequent flows reuse the same customer. If the user has completed KYC, name, date of birth, and country code from the SumSub applicant record are included on the customer payload. If the user has not yet completed KYC, only externalId and email are sent.

​
Webhook delivery is configured at the Meld dashboard

Meld posts events to a single Sumvin endpoint: 
POST /v0/webhooks/meld/events
Each request carries an HMAC signature over the timestamp, URL, and body, verified against the configured webhook secret. Sumvin de-duplicates events by eventId for 5 minutes to absorb retries. Partners do not receive Meld webhooks directly. State changes that matter to the partner (account linked, KYC verified) surface on the corresponding partner-visible resource — accounts on the accounts list, KYC status on the user record. Partner-facing webhooks are on the roadmap. GET /v0/accounts/ — List the user’s linked accounts.

​
Sandbox vs production

The base URL distinguishes the two:
  • Sandbox: https://api-sandbox.meld.io (default for dev/local)
  • Production: configured per environment via MELD_API_URL
Partners do not switch environments themselves — the environment is determined by which Sumvin deployment they are calling.

​
Verifying client health

A non-destructive way to confirm the Meld client is wired up in your environment is to list institutions: 
curl -s -H "Authorization: Bearer $SUMVIN_TOKEN" \
  https://api.sumvin.com/v0/bank-linking/institutions | jq .total
A successful integer response means the partner credential, the user’s bank-linking entitlement, and the Meld client are all functioning. A 401 indicates an auth problem on the Sumvin side; a 403 means the user does not have the bank-linking entitlement enabled; a 502 indicates Meld is unavailable.