Onboard Customers

Etherfuse supports two approaches for customer onboarding and KYC verification. Both work the same in sandbox as in production.

Approach	Best For	Guide
Hosted UI (Presigned URL)	Fastest integration — Etherfuse handles identity collection, document upload, and agreement signing in one hosted page	Hosted UI Flow
Programmatic	White-label experience — collect data in your own UI, submit via API, full control over the customer journey	Programmatic Flow

Start with the Hosted UI if you want the fastest path to testing. You can migrate to Programmatic later without re-onboarding existing customers.Hybrid is also common — use the programmatic API for identity and documents, then redirect the user to the presigned URL for agreements and compliance verification.

KYC Requirements (Production)In production, the following must be submitted for each customer:

Selfie — A photo of the customer’s face
Government-issued identification — A valid ID document (passport, driver’s license, national ID)
Proof of address — Document showing the customer’s current address (utility bill, bank statement)

If the government-issued ID includes the customer’s address (e.g., a driver’s license), it can satisfy both requirements. After all data is submitted, Etherfuse reviews the information for accuracy before approving the customer.In sandbox, you can complete KYC using fake data — no real personal information is required.

Interactive Tutorial

Use the interactive tutorial below to walk through the full onboarding flow with your sandbox API key.

Reference

Show Checking KYC status

Query the current KYC status at any time (works for both approaches) via GET /ramp/customer//kyc/.

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

Status	Description
`not_started`	No KYC data submitted
`proposed`	Data submitted, awaiting admin review
`approved`	KYC approved
`approved_chain_deploying`	Approved, on-chain marking in progress (Solana only)
`rejected`	KYC rejected (see `currentRejectionReason`)

{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "walletPublicKey": "9Qx7r...",
  "status": "proposed",
  "onChainMarked": false,
  "currentRejectionReason": null,
  "selfies": [...],
  "documents": [...],
  "currentKycInfo": {
    "email": "[email protected]",
    "phoneNumber": "+521234567890",
    "name": { "givenName": "Juan", "familyName": "Garcia" },
    "address": { "street": "Av. Reforma 123", "city": "Mexico City", "region": "CDMX", "postalCode": "06600", "country": "MX" }
  },
  "approvedAt": null
}

Show Handling rejections

If KYC is rejected, the updateReason in the webhook (or currentRejectionReason in the status response) explains why. To resubmit:

Address the rejection reason (e.g., upload a clearer document)
Submit new data via the same endpoints
The new submission creates a fresh review; old rejected data remains for audit purposes

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...",
    "approved": true,
    "updateReason": "KYC approved by admin"
  }
}

Rejected:

{
  "kyc_updated": {
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "walletPublicKey": "9Qx7r...",
    "approved": false,
    "updateReason": "ID document is expired. Please submit a valid government-issued ID."
  }
}

Get Started

Guides

API Reference

Sandbox API Reference

Interactive Tutorial

Reference

Get Started

Guides

API Reference

Sandbox API Reference

​Interactive Tutorial

​Reference

Interactive Tutorial

Reference