Troubleshooting and FAQs

Learn how to identify, debug, and resolve common issues when integrating the Socure DocV SDKs.

Common issues

Camera feed briefly shows a play/pause icon

Cause On some devices in low-power mode, the browser overlays a transient “play” icon on video elements. This is device/browser behavior and cannot be disabled.

Impact The overlay is temporary and does not affect SDK capture or verification.

What you can do

  • Advise end users that the icon is expected and will disappear momentarily.
  • Suggest disabling low-power mode if the overlay is distracting.

SDK fails to start / “launch failed”

Common causes & fixes

A) Invalid or expired docvTransactionToken

  • Ensure the SDK is initialized with a current, unused token.
  • Regenerate a new token if the previous one has expired, been consumed, or invalidated.

B) Network or firewall restrictions

  • The DocV SDK must reach Socure backend services over HTTPS.
  • Review corporate firewall/proxy rules to allow outbound HTTPS traffic.
  • Temporarily disable ad-blockers/VPN/content filters that might block SDK scripts or domains.

Cannot capture documents or access the camera

Likely causes

  • End user denied camera permission.
  • Browser/device or iframe policies are blocking camera access.

Steps to resolve

  • Ask the user to allow camera access when prompted.
  • If you load the Web SDK inside an iframe, include permissive sandbox flags:
<iframe sandbox="allow-same-origin allow-scripts allow-camera"></iframe>
  • Verify the user is on a supported browser:
    • Chrome
    • Safari
    • Firefox (mobile supported)
👍

Tip:

  • Serve the page over HTTPS so browsers permit camera usage.
  • If using embedded webviews, confirm they support getUserMedia.

Rare crashes or black screen during Capture App

While uncommon, some devices may crash or freeze due to OS/browser version, device capabilities, or low memory (RAM/GPU).

Recommended end-user steps

  • Update the device OS and browser to the latest version.
  • Close unused apps and browser tabs to free memory.
  • Clear cache and reload the Capture App page.
  • Restart the device, then retry the capture flow.

These actions typically resolve device-level issues and allow users to complete verification successfully.



FAQs

Common questions

Does DocV support localization for multiple languages?

Yes. DocV V5 SDKs support per-transaction localization of default UI text (including Terms & Conditions). Set the desired language in your server-side Evaluation request config (see Q7).

Highlights

  • Supports: English, Spanish (multiple variants), French, Simplified/Traditional Chinese, Haitian Creole, Italian, Korean, Polish, Russian, Tagalog, Urdu, Vietnamese, Arabic, Armenian, Bengali, Brazilian Portuguese, Hindi, Japanese, German, and more.
  • Default: If you don’t pass a language, en-us is used.
  • Custom UI text: If you override copy in the Admin Dashboard, provide your own translations for that custom text.

For the full list and locale codes, see your Language Options page.

Does the Android SDK support 16 KB memory page size requirements?

Yes. Support for 16 KB page sizes is included starting with Android SDK v5.1.1. If you’re on an older version, upgrade to ≥ v5.1.1 to maintain compliance with Google’s latest requirements.

Do the SDKs validate images at capture time (retakes)?

Yes. The DocV SDKs guide users and apply immediate quality checks (e.g., framing, glare/blur, document presence) before submitting to backend verification. Users may be prompted to retake images to improve quality and reduce downstream failures/abandonment.

What if users abandon capture and the link expires?
  • You’ll receive a case note webhook (case_notes_added) with Session Expired when the link validity window passes.
  • Expired links are time-bound and single-session. To let the user try again, issue a new document request (typically by creating a new Evaluation so a fresh docvTransactionToken and link are generated).
  • If you must tie attempts back to the same business record, include your own external transaction ID in the id field of the Evaluation.

For progress/event webhooks vs final results, see your Webhooks page (DocV Event Webhooks vs Evaluation Completed).

When are resubmit results triggered, and what should we do?

A resubmit decision is returned when the images don’t meet minimum criteria (e.g., unreadable text, missing side/back, glare/blur).

Recommended handling:

  • Treat resubmit as non-terminal. Prompt the user to recapture by issuing a new document request (fresh link/token).
  • Consider rate-limiting attempts and providing tips (good lighting, remove cases/covers, avoid glare).
How much can we customize the DocV flow and screens?
  • Flows & branding: Use useCaseKey to select a customized Capture App flow you’ve configured in the Dashboard (branding, steps, copy).
  • Skip screens:
    • Document type selection: Skip by passing documentType (e.g., license, passport).
    • Splash/intro: Often configurable in the Dashboard flow.
  • Consent/T&Cs: Must be presented within DocV for compliance. You may show additional disclosures in your own onboarding/handoff page, but the DocV consent screen itself is not removable.
Where do I pass DocV V5 config (language, sendMessage, redirect, documentType, useCaseKey)?

In DocV V5, configuration is server-side only. You pass all options when you create the Evaluation. The SDK launch on the client only needs the docvTransactionToken and SDK key.

Common options (server-side, in your Evaluation request):

  • language — UI locale for the Capture App (default en-us)
  • useCaseKey — choose a specific flow configured in the Dashboard
  • sendMessagetrue to send the capture link via SMS
  • redirect{ method: "POST" | "GET", url: "https://…" } after completion/cancel
  • documentType — restrict to a single type (e.g., license, passport)

Example (JSON)

{
  "id": "your-transaction-id-123",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe",
      "phone_number": "+19999998888",
      "docv": {
        "config": {
          "language": "en-us",
          "useCaseKey": "my_custom_flow",
          "sendMessage": true,
          "redirect": {
            "method": "POST",
            "url": "https://example.com/docv/callback"
          },
          "documentType": "license"
        }
      }
    }
  }
}

What the client gets
Your backend receives an Evaluation response with a DocV link/QR/token at the Document Request step. You then hand that to the client to launch the SDK or hosted capture.