KYC: Feature - SumSub SDK integration

[cmgustavo]

Native identity verification (KYC) using the SumSub React Native MobileSDK (@sumsub/react-native-mobilesdk-module).

The backend exposes two signed /api/v2 RPC methods on the bitpayUser facade (same channel as Device Intelligence's getDeviceAccessToken):

App call (BitPayIdApi.apiCall)	Params	Returns
getKycAccessToken	{levelName?}	SumSub SDK token, or null when the user is not eligible
getKycStatus	{}	KycStatusType object (path, provider, tier, status, activeAttempt, …)

Changes

• Access token via apiCall('getKycAccessToken', {levelName}) — the signed token identifies the user server-side (no userId sent). Backend returns null for users with no shopper product / shopper tier 1 / already holding KYC tier ≥1; the app detects this and does not launch the SDK (no error shown).
• Status sync via apiCall('getKycStatus') + mapBackendKycStatus, mapping the backend status (notStarted, approved, rejected, requiresAction, inProgress, …) to the app's SumSubKycStatus. Unknown in-flight review states fall back to Pending (safe default). Dispatched on app init (fetchInitialUserData), post-pairing (startPairAndLoadUser), and when the KYC screen opens — so the status survives app restarts and reflects reviews completed outside the app (kycStatus is in the persist blacklist).
• Entry points: Home banner (KycBannerGate), Settings → Security (KycVerification), and Profile / VerifyIdentity.
• Redux slice SUMSUB (kycStatus per network); reset on logout.
• Native config: Android SumSub maven repo; iOS Podfile + camera/mic/photo usage strings in Info.plist.

Testing Instructions

Prerequisites

Environment variable — add to your .env (optional; the backend defaults the level if omitted):

SUMSUB_LEVEL_NAME=<level name from SumSub dashboard, e.g. basic-kyc-level>

Start:

yarn install; yarn pod:install; yarn set:dev; yarn start
npx react-native run-android

On testnet, the KYC screen shows a debug banner with the active network, levelName, and raw kycStatus.

---

Test Cases

1. Home Banner Entry Point

• Log in with a TEST account that has a verified email and no KYC completed.
• Verify the identity-verification banner appears on Home (KycBannerGate).
• Tap the banner → navigates to the verification flow.

2. Settings Entry Point

• Settings → Security → verify the KYC option (KycVerification screen) is present and navigates to the flow.

3. Profile Entry Point

• Profile Settings → verify VerifyIdentity is accessible from the BitpayIdGroup navigator.

4. SDK Launch & Permissions (iOS)

• Start the flow → the SumSub SDK opens as a native overlay.
• Verify the Camera / Microphone / Photo Library permission prompts appear.

5. Happy Path

• Complete verification with SumSub sandbox test documents.
• On approval the SDK closes; SUMSUB.kycStatus updates and the Home banner reflects the verified state.

6. Status Sync (backend authoritative)

• Complete or partially complete a flow, then kill and reopen the app.
• On launch, getKycStatus re-fetches the authoritative status → the banner/screen reflect it without reopening the SDK.
• Change the applicant status in the SumSub dashboard (approve/reject) → reopen the KYC screen → status updates.

7. Not-Eligible User (null token)

• Log in as a user who is shopper tier 1 / already KYC-verified.
• Start the flow → the SDK does not launch, no error modal (logged as "KYC not available").

8. Token Refresh

• Simulate token expiration (600s TTL) → the SDK silently re-mints via onTokenExpired; the flow continues.

9. Cancellation / Error

• Cancel the SDK mid-flow → app returns to the previous screen, no crash, store not left in an intermediate state.