Getting started

Treat StarkFi KYC as a managed service: we run verification sessions and decisions on Didit, a leading global provider for identity and compliance. You do not need a separate contract, certification path, or second vendor integration for end users who onboard through StarkFi.

The kyc product must be enabled on your deployment. Check GET /config/products with your API key, or contact your account manager.

Two onboarding paths

You can verify identity before opening a Didit session using email or wallet:

Path	Best for	Steps
Email	Web apps with email login	prepare → send OTP → verify OTP → create session
Wallet	Crypto-native apps	wallet challenge → prepare-wallet → create session

Both paths converge at create session and get status.

Email flow

How StarkFi KYC works (Didit)

Identity verification is powered by Didit, with strong coverage for document checks, liveness, screening, and fraud signals. Instead of wiring your product directly to Didit dashboards, API keys, and workflows, StarkFi exposes a single API for starting sessions, tracking progress, and receiving outcomes.

Shared verification across StarkFi

When someone has already completed verification elsewhere on StarkFi, that identity can be recognized across the network. You are not charged again for a full verification cycle for users who are already approved in the ecosystem.

Exact reuse rules and commercial pricing depend on your StarkFi agreement. Contact support@starkfi.io or your account manager for details.

API sequence (email)

POST /kyc/prepare
POST /security/email/send-otp
POST /security/email/verify-otp
POST /kyc/create/verify_public_kyc
GET  /kyc/status?email=

Step	Method and path	Purpose
1	`POST /kyc/prepare`	Register the user’s email for KYC
2a	`POST /security/email/send-otp`	Send the email verification code
2b	`POST /security/email/verify-otp`	Confirm the code
3	`POST /kyc/create/verify_public_kyc`	Create or resume the Didit session
4	`GET /kyc/status?email=`	Read approval state, session URL, and risk signals

Use the same email address in every step. We recommend lowercase addresses.

Wallet flow

API sequence (wallet)

POST /security/wallet/challenge
POST /kyc/prepare-wallet
POST /kyc/create/verify_public_kyc
GET  /kyc/status?wallet=

Step	Method and path	Purpose
1	`POST /security/wallet/challenge`	Get a signable message (expires in 10 min)
2	`POST /kyc/prepare-wallet`	Prove ownership with `message` + `signed_bytes`
3	`POST /kyc/create/verify_public_kyc`	Body: `{ "wallet": "..." }`
4	`GET /kyc/status?wallet=`	Poll until approved or declined

See Wallet challenge and Prepare KYC (wallet) for request bodies and error codes.

Verify quota

KYC session creation consumes your integration’s monthly verify quota. When quota is exceeded, prepare and session endpoints return 429 with status verify_quota_exceeded. Contact StarkFi to increase your limit or wait for the 30-day renewal window.

StarkPay and KYC/KYB

KYC/KYB rules depend on the payment context:

Context	KYC/KYB
Checkout (order)	Not required — payments linked to an order via `order_code` or `executor_id: order_transaction`
Financial transaction (fiat methods)	Required when you send `payer_email` or `payer_wallet`
Financial transaction (`crypto` only)	Not required — 100% on-chain crypto never triggers KYC/KYB

See StarkPay overview for the full checkout vs transaction distinction.

Prerequisites

A valid end-user email or wallet you control for testing.
A way to open HTTPS (browser or in-app web view) when StarkFi returns a hosted Didit URL.
For email flow: outbound email delivery for OTP codes enabled for your environment.

Common issues

What you see	What to check
`403 identity_not_verified`	Complete email OTP or wallet prepare before starting the KYC session.
`403 user_not_prepared`	Call prepare (email or wallet) before create session.
`404 user_not_found` on OTP	Call `POST /kyc/prepare` first for that email.
`404 method_not_found`	Use the path segment `verify_public_kyc` exactly as shown.
`403 product_disabled`	KYC product not enabled — see Products.
`429 verify_quota_exceeded`	Monthly KYC session quota exhausted.

Overview

Guides

Two onboarding paths

Email flow

Wallet flow

Verify quota

StarkPay and KYC/KYB

Prerequisites

Common issues

​Two onboarding paths

​Email flow

​Wallet flow

​Verify quota

​StarkPay and KYC/KYB

​Prerequisites

​Common issues

​Related

Two onboarding paths

Email flow

Wallet flow

Verify quota

StarkPay and KYC/KYB

Prerequisites

Common issues

Related