KYC WebSDK

The default flow. You create the customer and launch them; the customer does everything else in the widget at /idv.

The flow

Create the customer's organization

Create a personal organization with POST /ramp/organization. You generate the id. This UUID is the customer’s org id and the customer_id you use everywhere else.

curl -X POST https://api.sand.etherfuse.com/ramp/organization \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<customer_uuid>",
    "displayName": "Ana Ejemplo",
    "accountType": "personal",
    "userInfo": {
      "email": "[email protected]",
      "displayName": "Ana Ejemplo"
    }
  }'

curl -X POST https://api.etherfuse.com/ramp/organization \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<customer_uuid>",
    "displayName": "Ana Ejemplo",
    "accountType": "personal",
    "userInfo": {
      "email": "[email protected]",
      "displayName": "Ana Ejemplo"
    }
  }'

Send userInfo.email. It is the address the customer confirms during verification, and the only place it comes from. A customer with no email on file cannot be verified.

Launch the customer into /idv

An Identity verification launch, using JWT User Authentication.

<form method="POST" action="https://sandbox.etherfuse.com/auth/launch">
  <input type="hidden" name="grant_type" value="urn:ietf:params:oauth:grant-type:jwt-bearer" />
  <input type="hidden" name="assertion" value="<verification_scoped_jwt>" />
  <input type="hidden" name="target" value="/idv" />
</form>

The JWT sub MUST equal the org id from step 1. Any other sub registers a brand-new person instead, and the verification won’t attach to your customer.

Append &lang=es to the target (/idv?lang=es) for Spanish. Pass an optional return_url on the launch to send the customer back to your app when they finish.

The customer completes the steps in the widget

Everything in the Requirements List, plus any country-specific requirement, in one authenticated session. The customer can leave and come back; progress is kept.

Watch for the result

The kyc_updated webhook fires with status: "approved" and the customer’s wallet becomes order-eligible. See Tracking verification status.

Error handling

Failures specific to launching. Verification outcomes (denied, needs-work) are in Tracking verification status; a rejected customer is resubmitted by launching them again.

What you see	Meaning	What to do
The launch never reaches `/idv`	The JWT was rejected: wrong scope, expired, bad signature, or an unrecognized `target`.	See Authentication errors.
The customer lands in `/idv` as a new person	The JWT `sub` wasn’t the org `id`.	Re-mint with `sub` = the org `id`. Don’t reuse the old session.
The liveness scan never starts in an iframe	Camera permission. The bare `allow="camera"` grants only the iframe’s own origin, but the scan runs from a nested frame.	Set `allow="camera ; microphone "` on the iframe. A top-level tab or popup needs nothing extra.

Sandbox

The verification checks don’t run, so any document images and any selfie will pass. The one exception is Mexico’s constancia. See Country-specific requirements and Test environment.

Get Started

Concepts

User Authentication

Integration Guides

KYC

Blockchains

Resources

The flow

Error handling

Sandbox

When to reach for something else

KYC API

Sumsub shared token

​The flow

​Error handling

​Sandbox

​When to reach for something else

KYC API

Sumsub shared token

The flow

Error handling

Sandbox

When to reach for something else