KYC Overview

Every customer must clear identity verification before their wallet can transact.

Choosing a flow

Flow	You submit	Customer submits
KYC WebSDK (the default)	Nothing	Everything
KYC API	Personal data, identity document, questionnaire answers, and any region-specific documents	Email confirmation, liveness selfie, customer agreement
Sumsub shared token	A share token, then questionnaire answers and any region-specific documents	The customer agreement, plus email confirmation or liveness only if the shared session didn’t cover them

Requirements List

Requirement	What satisfies it	How it can be submitted
`personal_data`	Name, date of birth, tax id, country, and residential address.	WebSDK · API · Shared token
`identity_document`	A government-issued photo ID. Any valid one works.	WebSDK · API · Shared token
`proof_of_address`	A utility bill, bank statement, tax bill, employment certificate, property deed, or invoice. Requested only when the identity document carried no address.	WebSDK · API · Shared token
`occupation`	Job title and an occupation category.	WebSDK · API
`email_confirmation`	The customer confirming the email you registered on their organization.	WebSDK · Shared token
`selfie`	A live face capture.	WebSDK · Shared token
`customer_agreement`	The customer accepting Etherfuse’s agreements.	WebSDK

Some countries add specific additional requirements. See Country-specific requirements.

Tracking verification status

The overall status

curl -H "Authorization: <api_key>" \
  https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/kyc

curl -H "Authorization: <api_key>" \
  https://api.etherfuse.com/ramp/customer/<customer_uuid>/kyc

{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "submitted",
  "currentRejectionReason": null,
  "needsWork": false,
  "approvedAt": null
}

Status	Description
`not_started`	No verification started
`in_progress`	Started, but not everything is submitted. Detail in `needsWork` and `userMessage`
`submitted`	Submitted, awaiting review (manual or automated)
`approved`	Cleared; the customer can transact
`denied`	A rejected verdict, or a previously-approved customer whose approval was revoked. Reason in `currentRejectionReason`

The per-requirement breakdown

Add ?requirements=true for a step-by-step account of what the customer still needs. It is opt-in: omit the parameter and the response is unchanged.

curl "https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/kyc?requirements=true" \
  -H "Authorization: <api_key>"

{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "in_progress",
  "requirements": [
    { "type": "personal_data",      "status": "satisfied", "requiresLaunch": false },
    { "type": "identity_document",  "status": "satisfied", "requiresLaunch": false },
    { "type": "occupation",         "status": "pending",   "requiresLaunch": false },
    { "type": "email_confirmation", "status": "pending",   "requiresLaunch": true  },
    { "type": "selfie",             "status": "pending",   "requiresLaunch": true  },
    { "type": "customer_agreement", "status": "pending",   "requiresLaunch": true  }
  ]
}

Each type matches a requirement in the Requirements List or a country-specific one. requiresLaunch: true marks the rows only the WebSDK can satisfy.

requirements is absent until the customer has been routed to their country’s requirements, so it is missing immediately after their personal data is submitted. Read it again a moment later. It also grows: proof_of_address appears only at a later stage, and only when the identity document carried no address.

We reserve the right to add new requirements, and will update these docs when we do. Some countries may also gain requirements of their own.

Requirement statuses

`status`	Meaning	What to do
`satisfied`	Accepted.	Nothing.
`pending`	Nothing has been provided for this yet.	Supply it.
`awaiting_review`	Provided, not yet reviewed.	Wait.
`action_required`	Reviewed and rejected.	Send it again, corrected.

Country-specific requirements

🇲🇽 Mexico

Requirement	What satisfies it	How it can be submitted
`tax_document`	The Constancia de Situación Fiscal, the tax-status document issued by SAT.	WebSDK · API

It must be legible and belong to the customer being verified. Submit it as the tax_document part of POST /ramp/customer/{customer_id}/verification/documents, or let the customer upload it in the widget.

In sandbox, the constancia is the one document that has to look real. Any real constancia with any data in it works. Use this example constancia.

Reference

Show Bank account status

A bank account must be active before you can create orders against it. Check the status in the registration response or via GET /ramp/bank-accounts; a bank_account_updated webhook fires when it changes.

In sandbox, register the bank account with the placeholder RFC XEXX010101000 to mark it active immediately. Any other RFC is treated as a real registration and will not auto-approve.

Show Webhooks

Register a webhook for kyc_updated events to receive status updates. See POST /ramp/webhook for setup and payload details.Approved:

{
  "kyc_updated": {
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "walletPublicKey": "9Qx7r...",
    "status": "approved",
    "approved": true,
    "updateReason": "KYC approved"
  }
}

Denied:

{
  "kyc_updated": {
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "walletPublicKey": "9Qx7r...",
    "status": "denied",
    "approved": false,
    "updateReason": "Identity verification could not be completed."
  }
}

Show Data isolation

Partners can only access KYC data they submitted:

Accessor	Data Visibility
Partner (via API key)	Only data where `source_organization_id` matches their org
Wallet Owner	All data for their wallet
Admin	All data

This prevents partners from accessing PII submitted by other partners or directly by users.

Get Started

Concepts

User Authentication

Integration Guides

KYC

KYB

Blockchains

Resources

Choosing a flow

Requirements List

Tracking verification status

The overall status

The per-requirement breakdown

Requirement statuses

Country-specific requirements

Reference

​Choosing a flow

​Requirements List

​Tracking verification status

​The overall status

​The per-requirement breakdown

​Requirement statuses

​Country-specific requirements

​Reference

Choosing a flow

Requirements List

Tracking verification status

The overall status

The per-requirement breakdown

Requirement statuses

Country-specific requirements

Reference