Verifying a Customer

Overview

After you create a customer, the customer state progresses from storing to unverified. The unverified state indicates that you must create an identity verification before the customer can perform account activities like fiat transfers or crypto trading.

The Cybrid Platform verifies customers via government ID and selfie check using the id_and_selfie method. Verification flows may request additional documentation if the system cannot validate portions of the identity.

Choose your approach

Choose one of two approaches to implement KYC/KYB verification:

Approach	Description
Persona SDK Integration	Integrate Persona's SDK directly in your application to drive the verification flow.
Cybrid UI SDKs	Use Cybrid's pre-built UI SDK components as reference implementations.

Verify with Persona SDK

Integrate the Persona SDK directly in your application to provide a seamless identity verification experience. Cybrid creates the Persona inquiry via the identity verification API, and you pass the inquiry ID to the Persona SDK.

Persona offers multiple integration methods including Hosted Flow, Embedded Flow, and Mobile SDKs. See Choosing your integration method to select the approach that best fits your needs. The examples below demonstrate the Persona Embedded Flow integration.

Prerequisites

Before integrating the Persona SDK, ensure you have:

Created a customer via POST /api/customers
Obtained a customer GUID from the customer creation response

Create an identity verification

Create an identity verification by calling POST /api/identity_verifications:

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "kyc",
  "method": "id_and_selfie",
  "customer_guid": "customer_guid",
  "expected_behaviours": ["string"],
  "require_tax_id": true
}

{
  "guid": "identity_verification_guid",
  "customer_guid": "customer_guid",
  "type": "kyc",
  "method": "id_and_selfie",
  "created_at": "2023-03-23T16:01:58.074Z",
  "state": "storing"
}

ℹ️
Sandbox testing options
The expected_behaviours field is available in the sandbox to specify how you want the verification to be returned. This is helpful for testing success/failure scenarios. Remove the expected_behaviours key completely for normal operation, or include passed_immediately or failed_immediately for testing purposes.

ℹ️
Tax ID collection
The require_tax_id flag is optional and, if set, enforces tax ID collection during verification.

Retrieve the Persona Inquiry ID

After creating the identity verification, poll GET /api/identity_verifications/{identity_verification_guid} until the persona_inquiry_id field changes from null to the Inquiry ID.

{
  "guid": "identity_verification_guid",
  "customer_guid": "customer_guid",
  "type": "kyc",
  "method": "id_and_selfie",
  "created_at": "2023-03-23T16:05:40.757Z",
  "state": "waiting",
  "outcome": "passed",
  "persona_inquiry_id": "persona_inquiry_id",
  "persona_state": "waiting"
}

Integrate the Persona SDK

Choose the integration method that works best for your application:

NPM integration

Install the Persona SDK in your application using npm:

npm install [email protected] --save

Import and initialize the Persona client with the inquiry ID from the identity verification:

import Persona from 'persona';

const client = new Persona.Client({
  inquiryId: 'persona_inquiry_id',
  language: 'en',
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    console.log(`Sending finished inquiry ${inquiryId} to backend`);
    // Poll Cybrid API to confirm verification completion
    // Or use Webhooks to be updated on identity_verification.completed
  },
  onCancel: ({ inquiryId, sessionToken }) => {
    console.log('User cancelled verification');
  },
  onError: (error) => {
    console.error('Verification error:', error);
  }
});

CDN integration

Load the Persona SDK via CDN and initialize with your inquiry ID:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Identity Verification</title>
  <script src="https://cdn.withpersona.com/dist/persona-v5.5.0.js"></script>
</head>
<body>
  <script>
    const client = new Persona.Client({
      inquiryId: 'persona_inquiry_id',
      language: 'en',
      onReady: () => client.open(),
      onComplete: ({ inquiryId, status, fields }) => {
        console.log(`Completed: ${inquiryId}`);
        // Poll Cybrid API to confirm verification completion
        // Or use Webhooks to be updated on identity_verification.completed
      },
      onCancel: ({ inquiryId, sessionToken }) => {
        console.log('Cancelled');
      },
      onError: (error) => {
        console.error(error);
      }
    });
  </script>
</body>
</html>

Handle verification events

The Persona SDK provides event callbacks to track the verification flow. For detailed event handling, see Persona's event handling documentation.

Key callbacks:

onReady: Called when the SDK is ready to display
onComplete: Called when the user completes verification flow (the identity verification could still fail)
onCancel: Called when the user cancels the flow
onError: Called when an error occurs

⚠️
Logging for troubleshooting
Implement logging in each callback handler. This helps troubleshoot verification issues and track user progress through the identity verification flow.

Language support:

The language parameter accepts ISO 639-1 language codes. See Persona's supported languages for the full list.

Resume incomplete sessions

Users can resume incomplete verification sessions if they navigate away or close their browser. Generate a new session token using the Cybrid API and pass it to the Persona SDK.

Create a session token for an existing inquiry:

POST /api/persona_sessions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "persona_inquiry_id": "persona_inquiry_id",
  "identity_verification_guid": "identity_verification_guid"
}

{
  "persona_session_token": "persona_session_token",
  "persona_inquiry_id": "persona_inquiry_id",
  "identity_verification_guid": "identity_verification_guid"
}

Use the session token to resume the inquiry:

import Persona from 'persona';

const client = new Persona.Client({
  sessionToken: 'persona_session_token',
  language: 'en',
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    console.log(`Completed: ${inquiryId}`);
  }
});

For more details on session resumption, see Resume Persona Inquiry Session.

Verify completion status

When the user completes the Persona flow, poll the Cybrid API to confirm verification success.

Check identity verification status

Poll GET /api/identity_verifications/{identity_verification_guid} until state: completed and outcome: passed:

{
  "guid": "identity_verification_guid",
  "customer_guid": "customer_guid",
  "type": "kyc",
  "method": "id_and_selfie",
  "created_at": "2026-01-01T16:05:40.757Z",
  "state": "completed",
  "outcome": "passed",
  "persona_inquiry_id": "persona_inquiry_id",
  "persona_state": "completed"
}

The persona_state also shows completed. If the verification fails, check the failure_codes array for specific issues encountered during verification.

Confirm customer verification

After the identity verification completes and passes, confirm the customer entered the verified state. Call GET /api/customers/{customer_guid} and verify state: verified:

{
  "guid": "customer_guid",
  "type": "individual",
  "created_at": "2026-01-01T17:07:08.118Z",
  "state": "verified"
}

Cybrid UI SDKs (Reference Implementation)

Cybrid provides pre-built UI SDK components for Web, iOS, and Android that handle the entire identity verification flow automatically, including Persona integration.

These SDKs are available as reference implementations and provide zero-configuration identity verification—you only need to pass a customer GUID and JWT token. The SDKs automatically create identity verifications, manage Persona inquiry IDs, and handle session resumption.

To test the Web SDK implementation, use the Web Demo App. Create a customer record, authenticate with your customer GUID, and select the identity-verification component to begin the verification process.

⚠️
Reference implementations only
The Cybrid UI SDKs are not actively maintained and are out of date with the current API. Use these SDKs for reference purposes only.

Next steps

Now that the customer is verified, you can proceed with account funding and trading.

Related resources

For detailed reference information about identity verification:

Identity Verification Overview - Verification states, return codes, and concepts
Verify a Business Customer with KYB - Business customer verification
Persona Theming - Customize the Persona verification UI
Resume Persona Inquiry Session - Handle incomplete verification sessions
Persona Inquiry Expiry - Session expiration reference