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.

IMPORTANT

requestKYCVerification and submitKYCData should be used only if there is an unresolved flag with the code KYC_MISSING.

New Two-Step KYC Flow (Recommended)

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.

mutation requestKYCVerification {
  user {
    requestKYCVerification {
      ...KYCVerificationTypeFragment
    }
  }
}

fragment KYCVerificationTypeFragment on KYCVerificationType {
  fields {
    name
    description
    label
    group
    groupPolicy
    fields {
      name
      type
      description
      label
      value
      required
      visible
      max
      min
      maxLength
      minLength
      pattern
      orderNumber
      section
      editable
      values {
        label
        value
      }
      properties {
        key
        type
        value
        description
      }
    }
  }
  status
  title
  subtitle
  description
  errorMessage
  redirectURL
}

Response Properties:

Property	Type	Description
fields	[FieldSetType]	Form fields for KYC data collection. If empty or null, no form needs to be displayed
status	Int	Current status of the KYC verification process
outcome	Int	Outcome of the verification (success, failure, pending)
title	String	Title to display on the KYC screen
subtitle	String	Subtitle with additional context
description	String	Detailed information about the KYC process
errorMessage	String	Error details if verification failed
redirectURL	String	If 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.

mutation submitKYCData($data: VerifyDataInputType!) {
  user {
    submitKYCData(data: $data) {
      ...KYCVerificationTypeFragment
    }
  }
}

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.

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.

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