@transfergratis/react-native-sdk 0.1.25 → 0.1.28

package/src/hooks/useTemplateKYCFlow.tsx

@@ -4,6 +4,8 @@ import { KycEnvironment } from '../types/env.types';
 import kycService, { authentification, truncateFields } from '../modules/api/KYCService';
 import useI18n from './useI18n';
 import { logger } from '../utils/logger';
+import { countryMapping } from '../config/region_mapping';
+import { countryData } from '../config/countriesData';
 
 // Context pour le provider
 interface TemplateKYCFlowContextType {
@@ -17,6 +19,7 @@ interface TemplateKYCFlowContextType {
   getLocalizedText: (text: { en: string; fr: string;[key: string]: string }) => string;
   initializeSession: () => Promise<void>;
   env: KycEnvironment;
+  apiKey?: string;
 }
 
 const TemplateKYCFlowContext = createContext<TemplateKYCFlowContextType | undefined>(undefined);
@@ -32,7 +35,10 @@ interface TemplateKYCFlowProviderProps {
   apiKey?: string;
   env?: KycEnvironment;
   existingSessionId?: string;
-  initialStep?: number;
+  /** Index in template.components where to resume (0-based). Simple to store in template table. */
+  initialComponentIndex?: number;
+  /** Pays / type de document depuis l'URL de reprise — évite de dépendre du backend pour afficher les pays. */
+  initialCountryResume?: { code: string; documentType: string; region?: string };
 }
 
 export const TemplateKYCFlowProvider: React.FC<TemplateKYCFlowProviderProps> = ({
@@ -45,8 +51,10 @@ export const TemplateKYCFlowProvider: React.FC<TemplateKYCFlowProviderProps> = (
   apiKey,
   env = 'PRODUCTION',
   existingSessionId,
+  initialComponentIndex,
+  initialCountryResume,
 }) => {
-  const hookResult = useTemplateKYCFlow(template, onComplete, onError, onCancel, initialLanguage, apiKey, env, existingSessionId);
+  const hookResult = useTemplateKYCFlow(template, onComplete, onError, onCancel, initialLanguage, apiKey, env, existingSessionId, initialComponentIndex, initialCountryResume);
 
   return (
     <TemplateKYCFlowContext.Provider value={hookResult}>
@@ -73,7 +81,8 @@ export const useTemplateKYCFlow = (
   apiKey?: string,
   env: KycEnvironment = 'PRODUCTION',
   existingSessionId?: string,
-  initialStep?: number,
+  initialComponentIndex?: number,
+  initialCountryResume?: { code: string; documentType: string; region?: string },
 ): UseTemplateReturn => {
 
   const { setLocale } = useI18n();
@@ -140,92 +149,90 @@ export const useTemplateKYCFlow = (
   const templateWithReview = useMemo(() => ensureReviewSubmitStep(template), [template, ensureReviewSubmitStep, apiKey]);
   const templateWithReviewAndVerification = useMemo(() => ensureVerificationProgressStep(templateWithReview), [templateWithReview, ensureVerificationProgressStep, apiKey]);
 
-  // État initial du flux
+  // État initial du flux (initialComponentIndex = index dans template.components pour reprendre au bon composant)
   const buildInitialState = (): TemplateState => {
-    // Valider initialStep pour s'assurer qu'il est dans les limites du template
-    let validInitialStep = 0;
+    let resumeAtIndex = 0;
     let completedComponents: number[] = [];
-    
-    logger.log('buildInitialState called', { initialStep, existingSessionId });
-    
-    if (initialStep !== undefined && initialStep >= 0) {
+    let initialComponentData: Record<number, unknown> = {};
+
+    logger.log('buildInitialState called', { initialComponentIndex, existingSessionId, initialCountryResume });
+
+    if (initialComponentIndex !== undefined && initialComponentIndex >= 0) {
       const maxIndex = templateWithReviewAndVerification.components.length - 1;
-      const requestedStep = Math.min(initialStep, maxIndex);
-      const requestedComponent = templateWithReviewAndVerification.components[requestedStep];
-      
-      logger.log('Processing initialStep', {
-        initialStep,
-        requestedStep,
+      const requestedIndex = Math.min(initialComponentIndex, maxIndex);
+      const requestedComponent = templateWithReviewAndVerification.components[requestedIndex];
+
+      logger.log('Processing initialComponentIndex (component in template)', {
+        initialComponentIndex,
+        requestedIndex,
         maxIndex,
         componentType: requestedComponent?.type,
-        componentId: requestedComponent?.id
+        componentId: requestedComponent?.id,
       });
-      
-      // Si on reprend à l'étape id_card, on peut rester à id_card si on a une session existante
-      // car les données de country_selection peuvent être chargées depuis la session
+
+      // Reprendre au composant en cours (id_card, selfie, etc.)
       if (requestedComponent?.type === 'id_card') {
-        // Si on a une session existante, on peut rester à id_card et charger les données
         if (existingSessionId) {
           logger.log('id_card with existing session - staying at id_card');
-          validInitialStep = requestedStep;
-          // Marquer les composants précédents comme complétés
-          if (validInitialStep > 0) {
+          resumeAtIndex = requestedIndex;
+          if (resumeAtIndex > 0) {
             completedComponents = templateWithReviewAndVerification.components
-              .slice(0, validInitialStep)
+              .slice(0, resumeAtIndex)
               .map(component => component.id);
           }
         } else {
-          // Si pas de session, revenir à country_selection pour refaire le choix
           const countrySelectionIndex = templateWithReviewAndVerification.components.findIndex(
             c => c.type === 'country_selection'
           );
-          
           logger.log('id_card without session - going back to country_selection', { countrySelectionIndex });
-          
           if (countrySelectionIndex >= 0) {
-            validInitialStep = countrySelectionIndex;
-            // Marquer les composants avant country_selection comme complétés
+            resumeAtIndex = countrySelectionIndex;
             if (countrySelectionIndex > 0) {
               completedComponents = templateWithReviewAndVerification.components
                 .slice(0, countrySelectionIndex)
                 .map(component => component.id);
             }
           } else {
-            // Si pas de country_selection, commencer au début
-            validInitialStep = 0;
+            resumeAtIndex = 0;
           }
         }
       } else if (requestedComponent?.type === 'review_submit') {
-        // Si on reprend au review_submit, on ne marque pas les composants précédents
-        // pour permettre à l'utilisateur de revenir en arrière et vérifier/modifier les données
-        validInitialStep = requestedStep;
-        // Ne pas marquer les composants précédents comme complétés
+        resumeAtIndex = requestedIndex;
         completedComponents = [];
       } else {
-        // Pour les autres composants (selfie, etc.), commencer directement à l'étape demandée
-        validInitialStep = requestedStep;
-        
-        // Marquer tous les composants précédents comme complétés
-        // Cela permet à l'utilisateur de continuer sans refaire les étapes précédentes
-        if (validInitialStep > 0) {
+        resumeAtIndex = requestedIndex;
+        if (resumeAtIndex > 0) {
           completedComponents = templateWithReviewAndVerification.components
-            .slice(0, validInitialStep)
+            .slice(0, resumeAtIndex)
             .map(component => component.id);
         }
       }
-      
-      logger.log('Final initial state', {
-        validInitialStep,
+
+      logger.log('Final initial state (resume at component index)', {
+        resumeAtIndex,
         completedComponentsCount: completedComponents.length,
-        componentAtStep: templateWithReviewAndVerification.components[validInitialStep]?.type
+        componentAtResume: templateWithReviewAndVerification.components[resumeAtIndex]?.type,
       });
     }
-    
+
+    if (initialCountryResume?.code && initialCountryResume?.documentType) {
+      const countrySel = templateWithReviewAndVerification.components.find(c => c.type === 'country_selection');
+      if (countrySel && countryData[initialCountryResume.code]) {
+        initialComponentData[countrySel.id] = {
+          code: initialCountryResume.code,
+          documentType: initialCountryResume.documentType,
+          region: initialCountryResume.region || 'root',
+          ...countryData[initialCountryResume.code],
+        };
+        logger.log('Prefilled country_selection from URL', { code: initialCountryResume.code, documentType: initialCountryResume.documentType });
+      }
+    }
+
     return {
       template: templateWithReviewAndVerification,
-      currentComponentIndex: validInitialStep,
+      currentComponentIndex: resumeAtIndex,
       completedComponents: completedComponents,
-      componentData: {},
+      componentData: initialComponentData,
       errors: {},
       isProcessing: false,
       currentLanguage: initialLanguage,
@@ -236,6 +243,7 @@ export const useTemplateKYCFlow = (
         isInitialized: false,
         isProcessing: false,
         error: null,
+        sessionDataRestored: !existingSessionId || Boolean(initialCountryResume?.code && initialCountryResume?.documentType),
       },
       verification: {
         status: 'idle',
@@ -265,9 +273,9 @@ export const useTemplateKYCFlow = (
         return;
       }
 
-      // Si initialStep n'est pas défini ou est 0, on ne charge pas (début de session)
-      if (initialStep === undefined || initialStep === 0) {
-        logger.log('initialStep is 0 or undefined, skipping data load');
+      // Si initialComponentIndex n'est pas défini ou est 0, on ne charge pas (début de session)
+      if (initialComponentIndex === undefined || initialComponentIndex === 0) {
+        logger.log('initialComponentIndex is 0 or undefined, skipping data load');
         return;
       }
 
@@ -281,7 +289,7 @@ export const useTemplateKYCFlow = (
       }
 
       try {
-        logger.log('Loading session data for resume:', { sessionId: existingSessionId, step: initialStep });
+        logger.log('Loading session data for resume:', { sessionId: existingSessionId, componentIndex: initialComponentIndex });
         const result = await kycService.getVerificationResult(state.session.session_id);
         const sessionData = result[state.session.session_id]?.data;
 
@@ -291,10 +299,9 @@ export const useTemplateKYCFlow = (
           const data: any = sessionData;
           const restoredComponentData: Record<number, any> = {};
 
-          // Parcourir les composants jusqu'à l'étape initiale (incluse) pour restaurer leurs données
-          // Utiliser initialStep + 1 pour inclure le composant à l'étape initialStep
+          // Parcourir les composants jusqu'au composant de reprise (inclu) pour restaurer leurs données
           templateWithReviewAndVerification.components
-            .slice(0, initialStep + 1)
+            .slice(0, initialComponentIndex + 1)
             .forEach((component) => {
               // Essayer de restaurer les données selon le type de composant
               if (component.type === 'id_card' || component.type === 'file_upload') {
@@ -378,8 +385,27 @@ export const useTemplateKYCFlow = (
                   }
                 }
               } else if (component.type === 'country_selection') {
-                // Les données de sélection de pays peuvent être dans metadata
-                if (data.metadata || data.user_data) {
+                // Reconstruire country_selection au format attendu par IDCardCapture / CountrySelectionTemplate (code, documentType, region, regionMapping)
+                const meta = data.metadata || data.user_data || data;
+                const code = meta.country || meta.country_code || meta.code;
+                const documentType = meta.document_type || meta.documentType;
+                const region = meta.region;
+                if (code && documentType != null) {
+                  const country = countryData[code];
+                  const mapping = countryMapping[code as keyof typeof countryMapping];
+                  if (country) {
+                    restoredComponentData[component.id] = {
+                      code,
+                      ...country,
+                      documentType,
+                      region: region || undefined,
+                      regionMapping: mapping || undefined,
+                    };
+                    logger.log('Restored country_selection for resume', { code, documentType, region });
+                  } else {
+                    restoredComponentData[component.id] = { code, documentType, region: region || undefined, regionMapping: mapping || undefined };
+                  }
+                } else if (data.metadata || data.user_data) {
                   restoredComponentData[component.id] = {
                     ...(data.metadata || {}),
                     ...(data.user_data || {}),
@@ -396,6 +422,30 @@ export const useTemplateKYCFlow = (
               }
             });
 
+          // Fallback: si pas de country_selection restauré mais on a des documents avec templatePath, déduire code/documentType (ex. "templates/national_id_CM_front.jpg")
+          const countrySelectionComponent = templateWithReviewAndVerification.components.find(c => c.type === 'country_selection');
+          if (countrySelectionComponent && !restoredComponentData[countrySelectionComponent.id] && data.documents) {
+            const docs = data.documents as Record<string, { templatePath?: string }>;
+            const firstDoc = Object.values(docs).find(d => d?.templatePath);
+            const path = firstDoc?.templatePath || '';
+            const match = path.match(/([a-z_]+)_([A-Z]{2})(?:_|$)/i) || path.match(/([A-Z]{2})/);
+            const code = match ? (match[2] || match[1]).toUpperCase().slice(0, 2) : null;
+            const docTypeFromPath = path.match(/(national_id|identity_card|passport|passport_card)/i)?.[1]?.toLowerCase().replace('identity_card', 'national_id') || null;
+            if (code && countryData[code]) {
+              const documentType = docTypeFromPath || 'national_id';
+              const mapping = countryMapping[code as keyof typeof countryMapping];
+              const country = countryData[code];
+              restoredComponentData[countrySelectionComponent.id] = {
+                code,
+                ...country,
+                documentType,
+                region: undefined,
+                regionMapping: mapping || undefined,
+              };
+              logger.log('Restored country_selection from document templatePath', { code, documentType, path });
+            }
+          }
+
           // Mettre à jour l'état avec les données restaurées
           if (Object.keys(restoredComponentData).length > 0) {
             logger.log('Session data restored - components:', Object.keys(restoredComponentData));
@@ -406,20 +456,40 @@ export const useTemplateKYCFlow = (
                 ...prev.componentData,
                 ...restoredComponentData,
               },
+              session: { ...prev.session, sessionDataRestored: true },
             }));
             logger.log('Component data updated in state');
           } else {
             logger.log('No component data to restore from session');
+            setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
           }
+        } else {
+          setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
         }
       } catch (error) {
         logger.error('Error loading session data:', truncateFields(error));
-        // Ne pas bloquer le flux si le chargement échoue
+        setState(prev => ({ ...prev, session: { ...prev.session, sessionDataRestored: true } }));
       }
     };
 
     loadSessionData();
-  }, [existingSessionId, initialStep, state.session.isInitialized, state.session.session_id, templateWithReviewAndVerification.components, base64ToDataUri]);
+  }, [existingSessionId, initialComponentIndex, state.session.isInitialized, state.session.session_id, templateWithReviewAndVerification.components, base64ToDataUri]);
+
+  // Si l'index pointe vers Review alors que des étapes ne sont pas complétées, ramener à la première étape incomplète
+  useEffect(() => {
+    const comp = state.template.components[state.currentComponentIndex];
+    if (!comp || comp.type !== 'review_submit') return;
+    const nonReview = state.template.components.filter(
+      c => c.type !== 'review_submit' && c.type !== 'verification_progress'
+    );
+    if (nonReview.every(c => state.completedComponents.includes(c.id))) return;
+    const firstIncomplete = nonReview.find(c => !state.completedComponents.includes(c.id));
+    if (!firstIncomplete) return;
+    const targetIndex = state.template.components.findIndex(c => c.id === firstIncomplete.id);
+    if (targetIndex >= 0 && targetIndex !== state.currentComponentIndex) {
+      setState(prev => ({ ...prev, currentComponentIndex: targetIndex }));
+    }
+  }, [state.currentComponentIndex, state.completedComponents, state.template.components]);
 
   const mapComponentTypeToAction = useCallback((type: TemplateComponent['type']): string | null => {
     switch (type) {
@@ -475,7 +545,7 @@ export const useTemplateKYCFlow = (
     if (!action) {
       return base;
     }
-    // Document upload expects an array of documents with base64 and metadata
+    // Document upload expects documents; include country_selection in metadata so resume can restore it
     if (action === 'document_upload') {
       const documents: Record<string, any> = {};
       if (rawData && typeof rawData === 'object') {
@@ -483,9 +553,18 @@ export const useTemplateKYCFlow = (
           documents[key] = rawData[key];
         });
       }
+      const countryComp = state.template.components.find(c => c.type === 'country_selection');
+      const countryDataForPayload = countryComp ? state.componentData[countryComp.id] : null;
+      const metadata: Record<string, unknown> = {};
+      if (countryDataForPayload?.code) {
+        metadata.country = countryDataForPayload.code;
+        metadata.document_type = countryDataForPayload.documentType;
+        if (countryDataForPayload.region != null) metadata.region = countryDataForPayload.region;
+      }
       return {
         ...base,
         documents,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
       };
     }
 
@@ -520,17 +599,29 @@ export const useTemplateKYCFlow = (
   // console.log('apiKey in useTemplateKYCFlow', apiKey);
 
 
-  // Composant actuel
+  // Composant actuel (peut être redirigé si on pointe vers Review alors que le flux n'est pas terminé)
   const currentComponent = useMemo(() => {
-    return state.template.components[state.currentComponentIndex] || null;
-  }, [state.template.components, state.currentComponentIndex, apiKey]);
-
-  // Progression du flux
+    const comp = state.template.components[state.currentComponentIndex] || null;
+    if (!comp || comp.type !== 'review_submit') return comp;
+    const nonReview = state.template.components.filter(
+      c => c.type !== 'review_submit' && c.type !== 'verification_progress'
+    );
+    const allDone = nonReview.every(c => state.completedComponents.includes(c.id));
+    if (allDone) return comp;
+    const firstIncomplete = nonReview.find(c => !state.completedComponents.includes(c.id));
+    return firstIncomplete || comp;
+  }, [state.template.components, state.currentComponentIndex, state.completedComponents, apiKey]);
+
+  // Progression du flux (basée sur le composant effectivement affiché)
   const progress = useMemo(() => {
+    const idx = currentComponent
+      ? state.template.components.findIndex(c => c.id === currentComponent.id)
+      : state.currentComponentIndex;
+    const i = idx >= 0 ? idx : state.currentComponentIndex;
     return state.template.components.length > 0
-      ? ((state.currentComponentIndex + 1) / state.template.components.length) * 100
+      ? ((i + 1) / state.template.components.length) * 100
       : 0;
-  }, [state.currentComponentIndex, state.template.components.length, apiKey]);
+  }, [currentComponent, state.template.components, state.currentComponentIndex, apiKey]);
 
   // Vérifications de navigation
   const canGoNext = useMemo(() => {
@@ -623,12 +714,21 @@ export const useTemplateKYCFlow = (
       }));
     }
   }, [apiKey]);
-  // Validation d'un composant
-  const validateComponent = useCallback((componentId: number): boolean => {
+
+  // When user switches device: resume with existingSessionId + initialStep — ensure session is initialized so loadSessionData runs
+  useEffect(() => {
+    if (!existingSessionId || state.session.isInitialized) return;
+    if (state.session.session_id !== existingSessionId) return;
+    logger.log('Resuming on new device: initializing session so data can load', { existingSessionId, initialComponentIndex });
+    initializeSession();
+  }, [existingSessionId, state.session.session_id, state.session.isInitialized, initializeSession]);
+
+  // Validation d'un composant (dataOverride permet de valider sans attendre la mise à jour du state)
+  const validateComponent = useCallback((componentId: number, dataOverride?: any): boolean => {
     const component = state.template.components.find(c => c.id === componentId);
     if (!component) return false;
 
-    const componentData = state.componentData[componentId];
+    const componentData = dataOverride !== undefined ? dataOverride : state.componentData[componentId];
 
     switch (component.type) {
       case 'id_card':
@@ -698,8 +798,8 @@ export const useTemplateKYCFlow = (
       }));
     }, [ensureReviewSubmitStep, ensureVerificationProgressStep, apiKey]),
 
-    // Passer au composant suivant
-    nextComponent: useCallback(async () => {
+    // Passer au composant suivant (overrideData = données du step courant si déjà connues, évite un double clic)
+    nextComponent: useCallback(async (overrideData?: any) => {
       if (!canGoNext) return;
 
       const currentComp = state.template.components[state.currentComponentIndex];
@@ -715,8 +815,8 @@ export const useTemplateKYCFlow = (
           isProcessing: true,
         };
       });
-      // Valider le composant actuel
-      if (!validateComponent(currentComp.id)) {
+      // Valider avec override ou state
+      if (!validateComponent(currentComp.id, overrideData)) {
         setState(prev => ({
           ...prev,
           isProcessing: false,
@@ -738,18 +838,16 @@ export const useTemplateKYCFlow = (
           }));
           return;
         }
+
         if (component.type === 'review_submit') {
-          // Move to verification screen and mark verification in progress
           setState(prev => ({
             ...prev,
             currentComponentIndex: prev.currentComponentIndex + 1,
             completedComponents: [...prev.completedComponents, currentComp.id],
+            componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
             isProcessing: false,
             verification: { status: 'in_progress' },
-            errors: {
-              ...prev.errors,
-              [currentComp.id]: ''
-            }
+            errors: { ...prev.errors, [currentComp.id]: '' }
           }));
           return;
         }
@@ -780,18 +878,16 @@ export const useTemplateKYCFlow = (
             ...prev,
             currentComponentIndex: prev.currentComponentIndex + 1,
             completedComponents: [...prev.completedComponents, currentComp.id],
+            componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
             isProcessing: false,
-            errors: {
-              ...prev.errors,
-              [currentComp.id]: ''
-            }
+            errors: { ...prev.errors, [currentComp.id]: '' }
           }));
           return;
         }
 
         const step = serverStep === 0 && action !== 'initialize_session' ? 1 : serverStep;
-        // Build payload data per action
-        const payloadData = buildPayloadForComponent(action, component, state.componentData[currentComp.id], templateId, step);
+        const currentStepData = overrideData !== undefined ? overrideData : state.componentData[currentComp.id];
+        const payloadData = buildPayloadForComponent(action, component, currentStepData, templateId, step);
         console.log('payloadData', action, apiKey);
 
         await kycService.verificationSession({
@@ -804,17 +900,14 @@ export const useTemplateKYCFlow = (
           apiKey: apiKey ?? "-",
         });
         logger.log("currentComp state", truncateFields(state));
-        // Marquer comme complété et passer au suivant
         setState(prev => ({
           ...prev,
           currentComponentIndex: prev.currentComponentIndex + 1,
           completedComponents: [...prev.completedComponents, currentComp.id],
+          componentData: overrideData !== undefined ? { ...prev.componentData, [currentComp.id]: overrideData } : prev.componentData,
           isProcessing: false,
           ...(action === "location_permission" ? { permissionGranted: true } : {}),
-          errors: {
-            ...prev.errors,
-            [currentComp.id]: ''
-          }
+          errors: { ...prev.errors, [currentComp.id]: '' }
         }));
 
       } catch (error) {
@@ -871,8 +964,8 @@ export const useTemplateKYCFlow = (
     }, [apiKey]),
 
     // Valider un composant
-    validateComponent: useCallback((componentId: number) => {
-      return validateComponent(componentId);
+    validateComponent: useCallback((componentId: number, dataOverride?: any) => {
+      return validateComponent(componentId, dataOverride);
     }, [validateComponent, apiKey]),
     // complet verification
     submitVerification: useCallback(async () => {
@@ -953,5 +1046,6 @@ export const useTemplateKYCFlow = (
     getLocalizedText,
     initializeSession,
     env,
-  };
+    apiKey,
+  } as UseTemplateReturn;
 }; 

package/src/i18n/en/index.ts

@@ -71,7 +71,8 @@ export const en = {
       privacyPolicy: 'I agree to the Privacy Policy',
       termsOfService: 'I agree to the Terms of Service',
       marketingConsent: 'I agree to receive marketing communications',
-      readMore: 'Read more'
+      readMore: 'Read more',
+      getStarted: 'Get Started'
     },
 
     // Location Capture
@@ -126,6 +127,7 @@ export const en = {
       success: 'ID captured successfully',
       error: 'Failed to capture ID. Please try again.',
       captureTitle: '%{side} side of your government document',
+      cardNotFullyInFrame: 'The ID is not fully in frame. Position the entire card within the frame.',
       continueOnPhone: 'Continue on Phone',
       continueOnMobile: 'Continue on Mobile',
       scanQrCode: 'Scan this QR code with your phone to continue the verification process.',

package/src/i18n/fr/index.ts

@@ -56,7 +56,8 @@ export const fr = {
       privacyPolicy: 'J\'accepte la Politique de Confidentialité',
       termsOfService: 'J\'accepte les Conditions d\'Utilisation',
       marketingConsent: 'J\'accepte de recevoir des communications marketing',
-      readMore: 'Lire plus'
+      readMore: 'Lire plus',
+      getStarted: 'Commencer'
     },
 
     // Location Capture
@@ -111,6 +112,7 @@ export const fr = {
       success: 'Document d\'identité capturé avec succès',
       error: 'Échec de la capture du document. Veuillez réessayer.',
       captureTitle: '%{side} de votre document d\'identité',
+      cardNotFullyInFrame: 'La carte n\'est pas entièrement visible. Positionnez toute la carte dans le cadre.',
       continueOnPhone: 'Continuer sur mobile',
       continueOnMobile: 'Continuer sur mobile',
       scanQrCode: 'Scannez ce code QR avec votre téléphone pour continuer la vérification.',

package/src/i18n/types.ts

@@ -53,6 +53,8 @@ export interface KYCTranslations {
     processing: string;
     success: string;
     error: string;
+    captureTitle?: string;
+    cardNotFullyInFrame?: string;
   };
   
   selfieCapture: {

package/src/modules/api/CardAuthentification.ts

@@ -1,5 +1,5 @@
 import kycService, { authentification, errorMessage, truncateFields } from "./KYCService";
-import { cropByObb } from "../../utils/cropByObb";
+import { cropByObb, getCardInFrame, getObbConfidence, OBB_CONFIDENCE_THRESHOLD } from "../../utils/cropByObb";
 import { GovernmentDocumentType, IBbox } from "../../types/KYC.types";
 import { KycEnvironment } from "../../types/env.types";
 import { logger } from "../../utils/logger";
@@ -40,7 +40,19 @@ export async function frontVerification(result: { path?: string, regionMapping:
             throw new Error('Aucun visage détecté sur la carte. Veuillez reprendre.');
         }
 
-        // Optional: crop image using card_obb for better MRZ/barcode extraction
+        // If the backend indicates that the card is not fully in frame, stop early
+        const cardInFrame = getCardInFrame((detected as any).card_obb);
+        if (cardInFrame === false) {
+            // Use a stable error code; the UI maps this to a localized i18n message (cardNotFullyInFrame)
+            throw new Error('CARD_NOT_FULLY_IN_FRAME');
+        }
+
+        const obbConfidence = getObbConfidence((detected as any).card_obb);
+        if (obbConfidence !== null && obbConfidence < OBB_CONFIDENCE_THRESHOLD) {
+            throw new Error('Carte non entièrement visible. Positionnez toute la carte dans le cadre.');
+        }
+
+        // Optional: crop image using card_obb for better MRZ/barcode extraction (only when confidence >= threshold)
         let croppedBase64: string | undefined;
         let bbox: IBbox | undefined;
         let mrz: any | undefined;
@@ -124,6 +136,10 @@ export async function backVerification(result: { path?: string, regionMapping: {
                     template_path: result?.templatePath || '',
                     mrz_type: result?.mrzType || ''
                 }, env);
+                const mrzObbConf = getObbConfidence((mrz as any).card_obb);
+                if (mrzObbConf !== null && mrzObbConf < OBB_CONFIDENCE_THRESHOLD) {
+                    throw new Error('Carte non entièrement visible. Positionnez toute la carte dans le cadre.');
+                }
                 let bbox: IBbox | undefined;
                 let croppedBase64: string | undefined;
 
@@ -138,6 +154,10 @@ export async function backVerification(result: { path?: string, regionMapping: {
                 logger.log("MRZ échoué, tentative d'extraction barcode");
                 try {
                     const barcode = await kycService.extractBarcode({ fileUri: result.path!, token: token }, env);
+                    const barcodeObbConf = getObbConfidence((barcode as any).card_obb);
+                    if (barcodeObbConf !== null && barcodeObbConf < OBB_CONFIDENCE_THRESHOLD) {
+                        throw new Error('Carte non entièrement visible. Positionnez toute la carte dans le cadre.');
+                    }
                     return barcode;
                 } catch (barcodeError: any) {
                     throw new Error(`MRZ et barcode ont échoué. MRZ: ${mrzError?.message}, Barcode: ${barcodeError?.message}`);
@@ -164,6 +184,10 @@ export async function backVerification(result: { path?: string, regionMapping: {
                     template_path: result?.templatePath || '',
                     mrz_type: result?.mrzType || ''
                 }, env);
+                const mrzObbConf = getObbConfidence((mrz as any).card_obb);
+                if (mrzObbConf !== null && mrzObbConf < OBB_CONFIDENCE_THRESHOLD) {
+                    throw new Error('Carte non entièrement visible. Positionnez toute la carte dans le cadre.');
+                }
                 let bbox: IBbox | undefined;
                 try {
                     const crop = await cropByObb(result?.path || '', (mrz as any).card_obb);
@@ -179,6 +203,10 @@ export async function backVerification(result: { path?: string, regionMapping: {
             try {
                 logger.log("Tentative d'extraction barcode");
                 const barcode = await kycService.extractBarcode({ fileUri: result.path!, token: token }, env);
+                const barcodeObbConf = getObbConfidence((barcode as any).card_obb);
+                if (barcodeObbConf !== null && barcodeObbConf < OBB_CONFIDENCE_THRESHOLD) {
+                    throw new Error('Carte non entièrement visible. Positionnez toute la carte dans le cadre.');
+                }
                 let bbox: IBbox | undefined;
                 try {
                     const crop = await cropByObb(result?.path || '', (barcode as any).card_obb);