Skip to main content
When a user enters a Meld-backed flow, Sumvin shares their existing SumSub KYC outcome with Meld so Meld can use it instead of re-verifying the user inside the widget.

​
Why this exists

Meld’s hosted flows can run their own KYC against the user. If the user has already completed KYC with Sumvin (via SumSub), running it again is friction without value — the user re-uploads the same documents to satisfy the same provider that already verified them. KYC passthrough hands the existing applicant to Meld via a SumSub share token, so Meld inherits the verified state. For the trust model behind why this is acceptable, see KYC and attestation.

​
How it works

The passthrough is a server-side handshake between Sumvin, SumSub, and Meld. The partner does not need to opt in or carry any extra payload — it is implicit on any Meld-touching flow against a KYC-verified user.
1

User completes KYC with Sumvin

The user verifies through SumSub via the Sumvin onboarding flow. Sumvin persists the SumSub applicantId on the user (sumsub_applicant_id).
2

Sumvin ensures a Meld customer exists

On the user’s first Meld-touching call, Sumvin creates a Meld customer with the user’s external_id, name (from the SumSub applicant), date of birth, and country. The resulting Meld customerId is persisted on the user.
3

Sumvin generates a SumSub share token

When KYC initiation is required, Sumvin asks SumSub to mint a short-lived share token (TTL 600s) scoped to Meld’s SumSub client id (MELD_SUMSUB_CLIENT_ID).
4

Sumvin initiates KYC on the Meld customer

Sumvin calls Meld with serviceProvider: "SUMSUB". Meld pulls the verified applicant from SumSub using the share token, and the Meld customer inherits the verified state.
5

Meld posts a status webhook

Meld emits CUSTOMER_KYC_STATUS_CHANGE once the inherited state is reflected on the customer. Sumvin records the event for observability.

​
What the partner does

Nothing explicit. The passthrough fires whenever Sumvin needs Meld to know the user is KYC-verified. The two preconditions are:
  1. The user has completed Sumvin KYC (the user has a sumsub_applicant_id).
  2. The Meld client has the matching SumSub tenant configured (MELD_SUMSUB_CLIENT_ID).
If the user has not completed KYC, the passthrough is skipped and the Meld customer is created with externalId and email only. Any flow that requires KYC at Meld will surface a Meld-side gating error to the partner.
The reverse direction — Meld telling Sumvin about a KYC change initiated outside Sumvin — is observed via the CUSTOMER_KYC_STATUS_CHANGE webhook but is informational only today. Sumvin treats the SumSub-issued state as the source of truth.

​
What you get on the Meld side

After the passthrough completes, the Meld customer is in a verified state for the SumSub provider. Subsequent Meld widget sessions for the same customer can skip the in-widget KYC step. The user sees the destination flow (account selection, payment confirmation) directly. The Meld customerId and the Sumvin user are linked one-to-one by externalId. There is no concept of multiple Meld customers per Sumvin user — re-entering a Meld flow always reuses the existing customer.

​
Failure modes

SymptomCauseResolution
Meld widget asks for KYC documentsUser has no sumsub_applicant_id on the Sumvin side, or MELD_SUMSUB_CLIENT_ID is not configured.Ensure the user has completed KYC; confirm with Sumvin that the SumSub-for-Meld client id is set.
KYC initiation returns an unexpected payloadMeld returned a response shape Sumvin does not recognise.Surfaces as a 502 on the calling Sumvin route; check trace id.
Share token request failsSumSub rejected the for-client-id or the applicant.Surfaces as a 500 on the calling Sumvin route; check trace id.