Skip to main content

KYC Verification

The KYC (Know Your Customer) verification process can be triggered at any point during user registration or account usage. When a KYC flag is raised, users must complete identity verification before continuing with certain operations.

KYC data will only be accepted if there is an outstanding flag with the code KYC_MISSING.

You can use the userQueries.kycFieldsConfig query to obtain the KYC form definition. On other form definitions, you were using FieldsConfigType, but for the KYC it starts with FieldSetType.

The current KYC implementation uses a two-step process that provides better status tracking and supports both form-based and redirect-based verification methods.

Flow Decision Tree​

Step 1: Request KYC Verification​

Initiate the KYC process using the user.requestKYCVerification mutation.

Response Properties:

PropertyTypeDescription
fields[FieldSetType]Form fields for KYC data collection. If empty or null, no form needs to be displayed
statusIntCurrent status of the KYC verification process
outcomeIntOutcome of the verification (success, failure, pending)
titleStringTitle to display on the KYC screen
subtitleStringSubtitle with additional context
descriptionStringDetailed information about the KYC process
errorMessageStringError details if verification failed
redirectURLStringIf present, redirect user to external KYC provider for verification

Response Handling:

The response from requestKYCVerification determines the next step in the KYC process:

  1. If redirectURL is present: Open the external KYC provider URL in a new tab (not same window). This is required for third-party cookie handling. The user will complete verification on the provider's platform, then you should start polling for status updates.

  2. If fields is present and non-empty: Display the KYC form to the user using the field definitions provided. The form uses FieldSetType structure. Once completed, use submitKYCData to submit the form data.

  3. If both redirectURL and fields are null/empty: Start polling requestKYCVerification to check for status updates. The KYC process is being handled asynchronously.

  4. If errorMessage is present: Display the error message to the user and stop the KYC process.

Step 2: Submit KYC Data (Form-Based Flow Only)​

This step is only used when requestKYCVerification returns fields. If you received a redirectURL, skip this step and use polling instead.

After the user completes the form, submit the collected data using user.submitKYCData.

Important Implementation Notes:

  • Consent Tracking: Before submitting KYC data, you should add consent using user.addConsent mutation with consentType set to the appropriate KYC consent value.

  • Iterative Process: The response may contain additional fields if more information is needed. In this case, display the new fields and repeat Step 2.

  • Data Refetch: After successful KYC submission, refetch the following:

    • User profile data (userQueries.endUser)
    • Onboarding status (userQueries.onboarding)
    • User transactions
    • User tickets
    • Raised flags

Polling for Status Updates​

Polling is required in two scenarios:

  1. After opening redirectURL in a new tab: Poll to detect when the user completes external verification
  2. When both redirectURL and fields are null: Poll to wait for the KYC process to complete

When to Poll:

  • Start polling after opening external provider URL in new tab
  • Start polling when requestKYCVerification returns no fields or redirectURL
  • Poll every 30-60 seconds (recommended: 40 seconds based on implementation)
  • Stop polling when fields are returned (display form) or verification completes

Form Field Structure​

The KYC form uses FieldSetType which differs from other forms that use FieldsConfigType.

Key properties to note:

  • groupPolicy: Defines which elements of FieldSetType are required vs optional
  • group: Groups related fields together
  • orderNumber: Determines field display order
  • section: Organizes fields into logical sections

Legacy Single-Step Flow (Deprecated)​

DEPRECATED

The user.kycVerify mutation and userQueries.kycFieldsConfig query are deprecated and maintained only for backward compatibility. New integrations should use the two-step flow described above.

Legacy kycVerify Mutation​

The older single-step approach uses user.kycVerify.

Limitations:

  • Returns only a boolean success/failure
  • No status tracking or progress information
  • Only accepts data if there's an active raised flag with presentedCode: KYC_MISSING
  • No support for external KYC providers
  • No iterative data collection

Legacy kycFieldsConfig Query​

Previously, form fields were retrieved separately using userQueries.kycFieldsConfig. This is no longer necessary as the new requestKYCVerification mutation returns the fields directly.

Best Practices​

  1. Always refetch data after successful KYC: Update user profile, onboarding status, transactions, tickets, and flags to reflect the new verification status.

  2. Handle all response scenarios: Your implementation should handle forms, redirects, errors, and iterative data collection.

  3. Implement proper error handling: Show user-friendly error messages and provide guidance on next steps.

  4. Add consent tracking: Ensure consent is properly recorded before submitting KYC data (use user.addConsent with consentType: 'KYC').

  5. External providers MUST open in new tab: Always use window.open(url, '_blank') for redirectURL - never use window.location.href. This is critical for third-party cookie handling.

  6. Implement polling wisely:

    • Use reasonable intervals (recommended: 40 seconds)
    • Always clean up intervals on component unmount
    • Poll after opening external provider URL
    • Poll when both fields and redirectURL are null

  7. Clear KYC state: After successful verification, clear any KYC-related UI states and navigation guards.

  8. Handle iterative forms: The submitKYCData response may contain additional fields - be prepared to re-render the form with new fields if needed.

Implementation Checklist​

  • Call requestKYCVerification to initiate KYC
  • Check response for errorMessage, redirectURL, or fields
  • If redirectURL: Open in new tab using window.open(url, '_blank')
  • If redirectURL: Start polling for status updates
  • If fields: Render form using field definitions
  • If fields: Add consent before calling submitKYCData
  • If neither redirectURL nor fields: Start polling
  • Handle submitKYCData response (may have more fields)
  • After success: Refetch user data, transactions, tickets, flags
  • Clean up polling intervals on component unmount
  • Test all three flows: form-based, redirect-based, and async polling