KYC Flow
Who it's for: Mobile and web app developers integrating user onboarding, and any backend service that needs to verify a new user's identity before granting access. Why it matters: The KYC flow handles identity verification, wallet creation, and on-chain credential issuance in one pipeline — so a user goes from sign-up to fully verified in minutes, not days.
core-identity exposes REST endpoints under:
/api/shika-finance/identity/v1/kyc/...
/api/shika-finance/identity/v1/ssi/...KYC
POST /kyc/enhanced — Biometric KYC via SmileID
Request
{
"country": "GH",
"id_type": "PASSPORT",
"id_number": "G12345678",
"first_name": "Kwame",
"last_name": "Mensah",
"dob": "1990-05-15"
}| Field | Notes |
|---|---|
country | ISO 3166-1 alpha-2 |
id_type | PASSPORT, NATIONAL_ID, DRIVERS_LICENSE |
id_number | Document number |
dob | YYYY-MM-DD |
{
"success": true,
"data": {
"smileVerified": true,
"smileResult": { ... }
}
}POST /kyc/enhanced/callback — SmileID Webhook
Receives SmileID job result callbacks. Triggers SSI provisioning on success.
SSI Wallet & Identity
POST /ssi/wallets — Create / Fetch Shika Wallet
Creates a Shika Wallet for the user (idempotent — returns existing wallet if walletIdentifier already registered).
{
"walletIdentifier": "user@example.com",
"useTestKey": false
}{
"success": true,
"message": "Wallet created",
"walletAddress": "0xabc...",
"walletCreated": true
}POST /ssi/initialize — Initialize SSI Contracts
Wire the user's wallet to the protocol's SSI infrastructure (factory, verifier, claim issuer, ENS registrar). Called once per user after wallet creation.
Request{
"walletIdentifier": "user@example.com",
"identityFactory": "0x4C47d600f056eBD01B538a7bB7eF48C0bd885b4a",
"verifier": "0x96a34b41e41df9928e69B51061240f12D19Fdd8e",
"claimIssuer": "0x89FAcE94A8738B50F2DE8B5D2Eb8464e463300e2",
"l2Registrar": "0x10E0EfB9ac9829A83c705067cAc3aED43d5D064d",
"l2Registry": "0xe40d1B1D157c1b97Bcc52A170e659Ed65dFBA43c"
}{
"success": true,
"message": "SSI initialized",
"transaction": { "id": "tx-uuid", "hash": "0x...", "status": "CONFIRMED" },
"addressId": "wallet-address-uuid"
}POST /ssi/create-identity — Deploy On-Chain Identity
Deploys an on-chain identity contract for the user.
Request{
"walletIdentifier": "user@example.com",
"user": "0xabc...",
"salt": "0xsalt..."
}{
"success": true,
"message": "Identity created",
"transaction": { "id": "tx-uuid", "hash": "0x...", "status": "CONFIRMED" },
"addressId": "wallet-address-uuid"
}POST /ssi/register-ens — Register ENS Name
Registers {label}.shikawallet.com for the user's identity.
{
"walletIdentifier": "user@example.com",
"ensLabel": "kwame"
}RPC Methods (worker-two — USSD binding)
When rpc-service-offline calls worker-two over internal service bindings instead of HTTP:
// Full KYC + SSI in one call
const result = await env.IDENTITY_SERVICE.initiateKycSsi({
walletIdentifier, country, id_type, id_number,
first_name, last_name, dob, callback_url?,
})
// Get full profile
const profile = await env.IDENTITY_SERVICE.getUserProfile({ walletIdentifier })
// Check KYC status only
const status = await env.IDENTITY_SERVICE.checkKycStatus({ walletIdentifier })
// PIN management
await env.IDENTITY_SERVICE.setPin({ walletIdentifier, pin })
const { isValid } = await env.IDENTITY_SERVICE.verifyPin({ walletIdentifier, pin })KYC Status Values
| Status | Meaning |
|---|---|
WALLET_CREATED | Shika Wallet created, KYC not started |
KYC_INITIATED | SmileID job submitted |
KYC_VERIFIED | SmileID approved |
SSI_ISSUED | On-chain identity + claim confirmed |
KYC_FAILED | SmileID rejected |