SumSub: Enhancement - Prefill KYC applicant with the account email and phone

Author: cmgustavo

declarations.d.ts

@@ -64,13 +64,22 @@ declare module '@sumsub/react-native-mobilesdk-module' {
     onEvent?: (event: SumSubEventPayload) => void;
   }
 
+  interface SumSubDocumentDefinition {
+    idDocType?: string;
+    country?: string;
+  }
+
   interface SumSubSdkBuilder {
     withHandlers(handlers: SumSubHandlers): SumSubSdkBuilder;
     withLocale(locale: string): SumSubSdkBuilder;
     withDebug(debug: boolean): SumSubSdkBuilder;
+    withTheme(theme: object): SumSubSdkBuilder;
     withAutoCloseOnApprove(delayMs: number): SumSubSdkBuilder;
     withAnalyticsEnabled(enabled: boolean): SumSubSdkBuilder;
     withApplicantConf(conf: {email?: string; phone?: string}): SumSubSdkBuilder;
+    withPreferredDocumentDefinitions(
+      definitions: Record<string, SumSubDocumentDefinition>,
+    ): SumSubSdkBuilder;
     build(): {
       launch(): Promise<SumSubSdkResult>;
       dismiss(): void;

src/lib/sumsub.spec.ts

@@ -36,6 +36,44 @@ describe('launchSumSubSdk', () => {
     expect(defaultBuilder.withLocale).toHaveBeenCalledWith('en');
   });
 
+  it('seeds the applicant with the account email and phone', async () => {
+    await launchSumSubSdk(ACCESS_TOKEN, jest.fn(), 'en', {
+      email: 'user@bitpay.com',
+      phone: '+15550001111',
+    });
+
+    const builder = (SNSMobileSDK.init as jest.Mock).mock.results[0].value;
+    expect(builder.withApplicantConf).toHaveBeenCalledWith({
+      email: 'user@bitpay.com',
+      phone: '+15550001111',
+    });
+  });
+
+  it('omits applicant fields the account does not have', async () => {
+    await launchSumSubSdk(ACCESS_TOKEN, jest.fn(), 'en', {
+      email: 'user@bitpay.com',
+    });
+
+    const builder = (SNSMobileSDK.init as jest.Mock).mock.results[0].value;
+    expect(builder.withApplicantConf).toHaveBeenCalledWith({
+      email: 'user@bitpay.com',
+    });
+  });
+
+  it('does not set an applicant conf when no account data is available', async () => {
+    await launchSumSubSdk(ACCESS_TOKEN, jest.fn(), 'en', {});
+
+    const builder = (SNSMobileSDK.init as jest.Mock).mock.results[0].value;
+    expect(builder.withApplicantConf).not.toHaveBeenCalled();
+  });
+
+  it('never sets a document country — the SDK cannot fix it client-side (RN-2904)', async () => {
+    await launchSumSubSdk(ACCESS_TOKEN, jest.fn());
+
+    const builder = (SNSMobileSDK.init as jest.Mock).mock.results[0].value;
+    expect(builder.withPreferredDocumentDefinitions).not.toHaveBeenCalled();
+  });
+
   it('resolves with the result returned by sdk.launch()', async () => {
     const result = await launchSumSubSdk(ACCESS_TOKEN, jest.fn());
 

src/lib/sumsub.ts

@@ -8,12 +8,18 @@ export interface SumSubSdkResult {
   errorMsg?: string;
 }
 
+export interface SumSubApplicantConf {
+  email?: string;
+  phone?: string;
+}
+
 export const launchSumSubSdk = (
   accessToken: string,
   onTokenExpired: () => Promise<string>,
   locale: string = 'en',
+  applicantConf?: SumSubApplicantConf,
 ): Promise<SumSubSdkResult> => {
-  const sdk = SNSMobileSDK.init(accessToken, onTokenExpired)
+  const builder = SNSMobileSDK.init(accessToken, onTokenExpired)
     .withHandlers({
       onStatusChanged: (event: {prevStatus: string; newStatus: string}) => {
         console.log(
@@ -26,8 +32,17 @@ export const launchSumSubSdk = (
     })
     .withLocale(locale)
     .withTheme(sumSubTheme)
-    .withDebug(__DEV__)
-    .build();
+    .withDebug(__DEV__);
+
+  // Seed the applicant from the authenticated BitPay account instead of letting
+  // the flow start from blank, user-typed values.
+  const conf: SumSubApplicantConf = {
+    ...(applicantConf?.email ? {email: applicantConf.email} : {}),
+    ...(applicantConf?.phone ? {phone: applicantConf.phone} : {}),
+  };
+  if (Object.keys(conf).length) {
+    builder.withApplicantConf(conf);
+  }
 
-  return sdk.launch();
+  return builder.build().launch();
 };

src/store/sumsub/sumsub.effects.spec.ts

@@ -42,6 +42,8 @@ const mockLaunchSumSubSdk = launchSumSubSdk as jest.Mock;
 const EID = 'user-eid-123';
 const API_TOKEN = 'api-token-xyz';
 const ACCESS_TOKEN = 'sumsub-access-token';
+const EMAIL = 'user@bitpay.com';
+const PHONE = '+15550001111';
 
 const NOT_STARTED = {
   path: 'sumsub',
@@ -55,7 +57,7 @@ const makeLoggedInStore = () =>
   configureTestStore({
     APP: {network: Network.mainnet},
     BITPAY_ID: {
-      user: {[Network.mainnet]: {eid: EID}},
+      user: {[Network.mainnet]: {eid: EID, email: EMAIL, phone: PHONE}},
       apiToken: {[Network.mainnet]: API_TOKEN},
     },
   });
@@ -111,6 +113,7 @@ describe('startKycVerification — happy path', () => {
       ACCESS_TOKEN,
       expect.any(Function),
       'en',
+      {email: EMAIL, phone: PHONE},
     );
   });
 
@@ -129,6 +132,7 @@ describe('startKycVerification — happy path', () => {
       ACCESS_TOKEN,
       expect.any(Function),
       'es',
+      {email: undefined, phone: undefined},
     );
   });
 

src/store/sumsub/sumsub.effects.ts

@@ -82,7 +82,15 @@ export const startKycVerification =
 
       const locale = (APP.defaultLanguage || 'en').split('-')[0];
 
-      const result = await launchSumSubSdk(accessToken, onTokenExpired, locale);
+      const result = await launchSumSubSdk(
+        accessToken,
+        onTokenExpired,
+        locale,
+        {
+          email: user.email,
+          phone: user.phone,
+        },
+      );
 
       dispatch(
         LogActions.debug(`[SumSub] SDK closed — status: ${result.status}`),

test/mocks/sumsubSdkMock.js

@@ -8,7 +8,8 @@ const builder = {
   withDebug: () => builder,
   withAutoCloseOnApprove: () => builder,
   withAnalyticsEnabled: () => builder,
-  withApplicantConf: () => builder,
+  withApplicantConf: jest.fn(() => builder),
+  withPreferredDocumentDefinitions: jest.fn(() => builder),
   build: () => ({
     launch: jest.fn().mockResolvedValue({
       success: true,