Understanding Customer Identity Verifications (KYC)

Know Your Customer (KYC) is a critical process for businesses to verify the identity of their customers. This helps prevent fraud, comply with regulations, and ensure a secure platform for everyone. Frame Payments provides a streamlined Customer Identity Verification process to help you meet these requirements.

This guide explains the overall KYC flow, what your customer will experience, and how to effectively use Frame Payments tools to manage these verifications. For technical details on API integration, please refer to our Customer Identity Verifications API documentation.

Verification Process Overview

The customer identity verification process with Frame Payments involves several key steps, from initiating the check to handling the outcome:

  1. Initiate Verification via API:

  2. Receive Initial API Response:

    • The API response will include a verification_id (the unique ID for this verification attempt) and, crucially, a verification_url.
    • The initial status will typically be pending.

  3. Share the Secure Verification URL with Your Customer:

    • The verification_url is a unique, secure link that directs your customer to Frame Payments' identity verification flow.
    • This URL is valid for a limited time and can be accessed by your customer on any supported device (desktop or mobile).
    • It is your responsibility to securely deliver this URL to your customer (e.g., via email, in-app message).

  4. Customer Completes the Verification Steps:

    • When the customer opens the verification_url, they will be guided through a series of steps to verify their identity.
    • This typically involves:
      • Providing consent.
      • Capturing images of their government-issued identification document (e.g., passport, driver's license).
      • Taking a selfie for biometric comparison with the document photo.
      • Potentially other checks based on regional requirements or risk assessment.
    • The process is designed to be user-friendly and efficient. The customer can usually close the window once they have submitted all required information.

  5. Monitor Verification Status via Webhooks & API:

    • Webhooks (Recommended): The most reliable way to get real-time updates is by subscribing to webhook events:
      • customer.identity_verification.created: Notifies you when the verification record is first created.
      • customer.identity_verification.updated: Notifies you whenever the verification status changes (e.g., to verified, failed, or other intermediary statuses).
    • API Polling: You can also periodically Retrieve a Customer Identity Verification using its id to check the current status.

  6. Handle the Final Verification Result:

    • Once the verification process is complete on the customer's end and our system has processed it, the status will update.
    • Common final statuses include:
      • verified: The customer's identity has been successfully verified.
      • failed: The customer's identity could not be verified. The webhook payload or API response might contain more details or reason codes if applicable and shareable.
      • incomplete: If the customer abandoned the process or there was an issue before full submission.
    • Your system should be designed to handle these different outcomes appropriately (e.g., grant access for verified status, request more information, or decline service for failed status according to your policies).

The Customer's Experience

When your customer clicks the verification_url you provide, they will be taken to a secure page hosted by Frame Payments. They will be asked to:

  • Consent to the identity verification process.
  • Select their country and document type (e.g., Passport, Driver's License).
  • Upload or capture images of their document:
    • They might be prompted to take a photo of the front and back of their ID.
    • Clear instructions are provided to ensure good image quality.
  • Take a selfie:
    • This is used for liveness detection and to compare against the photo on their ID.
  • Review and confirm the information submitted.

The entire process is designed to be intuitive and typically takes only a few minutes to complete.

Using Webhooks for Real-Time Updates

Webhooks are crucial for an efficient KYC workflow. Instead of repeatedly polling the API, your system can react instantly to status changes.

  • customer.identity_verification.created: Use this event to confirm that the verification process has started for a customer in your system.
  • customer.identity_verification.updated: This is the primary event to monitor. When you receive this event:
    • Check the status field in the data.object (which is the CustomerIdentityVerification object).
    • Update the customer's KYC status in your own database.
    • Trigger any relevant downstream processes in your application (e.g., activating features, sending notifications to your team or the customer).

For detailed information on setting up webhook endpoints, validating signatures, and best practices for handling events, please consult our main Webhooks documentation.

Handling Verification Outcomes

Based on the final status of the CustomerIdentityVerification:

  • verified: You can proceed with onboarding the customer or granting them access to services that require KYC.
  • failed:
    • Review any failure reasons provided (if available).
    • Decide on your policy: you might offer the customer a chance to retry (which may involve creating a new verification attempt), request manual review, or decline service.
    • Communicate clearly with your customer about the outcome and next steps.
  • incomplete: The customer did not complete all required steps. You might consider sending them a reminder with the verification_url (if still valid) or guiding them to restart the process.

It's important to design clear internal procedures and customer communication strategies for each possible outcome.