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.

Prepare your customers for verification

Share the following guidance with your customers before they start the identity verification flow. A smooth verification experience reduces drop-off and support requests.

ℹ️

Customer-facing guidance

Adapt the tips below into your own customer communications — email templates, in-app tooltips, help articles, or onboarding screens — so customers know what to expect before they begin.

What you need

Customers must provide a valid, unexpired government-issued photo ID and complete a live selfie check. The name on the ID must match the customer's legal name on file.

Accepted ID types:

• Driver's license (front and back)
• Passport
• Passport card
• Visa
• Residence card

Government ID photo tips

Poor image quality is the most common reason a verification attempt fails. Advise your customers to follow these steps when photographing their ID:

• Place the ID flat on a dark, non-reflective surface.
• Ensure all four corners of the ID are visible in the frame.
• Avoid glare, shadows, and backlighting — turn off nearby lamps or move away from windows if light reflects off the ID surface.
• Hold the camera steady and wait for auto-focus before capturing.
• If the ID has a back side (for example, a driver's license), capture both sides when prompted.
• Use a mobile phone rather than a desktop or laptop webcam. Mobile cameras produce higher resolution images that are easier to verify.

Selfie check tips

The selfie check confirms that the person completing the verification matches the photo on the government ID. Advise your customers to:

• Face the camera directly with a neutral expression.
• Use even, front-facing lighting. Avoid backlighting from windows or harsh overhead light that casts shadows on the face.
• Remove hats, sunglasses, masks, or anything that obscures the face.
• Use a plain, uncluttered background.
• Hold the device at eye level and keep it steady.

Device and browser requirements

• A device with a working camera is required. A mobile phone is recommended for the best experience.
• Grant camera permissions when the browser or app prompts for access. If the camera prompt does not appear, check the device or browser settings to enable camera access.
• Disable Low Power Mode (iOS) or Battery Saver (Android) before starting. These modes restrict camera functionality and can cause capture failures.
• Ensure the device is sufficiently charged.
• Use a supported, up-to-date browser such as Chrome or Safari.

Session and timing tips

• Complete the verification in a single session when possible. Verification sessions expire after a set period, and an expired session requires a new identity verification.
• If a customer starts on a desktop, the flow can hand off to a mobile device via QR code or a short link. This is useful when the desktop webcam produces low-quality images.
• If a customer navigates away or closes the browser mid-flow, you can resume the session by generating a new session token.

Choose your approach

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

Verify with Persona SDK

Integrate the Persona SDK directly in your application to handle identity verification. 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": null,
  "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"
}

Handle failed verifications

If the identity verification completes with outcome: failed, the failure_codes array and the individual compliance_checks entries indicate what went wrong and whether the customer can retry.

Compliance check outcomes

Each compliance check in the response has its own outcome value:

Retry eligibility by failure code

After the overall verification reaches state: completed with outcome: failed, check the failure_codes array and the customer's state to determine next steps:

Customer stays unverified -- retry allowed:

Create a new identity verification without contacting support. These failures are typically caused by poor image quality or incorrect documents:

• id_check_failure
• id_quality_check_failure
• id_expiration_check_failure
• id_double_side_check_failure
• id_type_allowed_check_failure
• id_country_allowed_check_failure
• phone_number_check_failure
• email_address_check_failure
• document_type_check_failure
• document_quality_check_failure
• document_check_failure
• user_canceled
• decision_timeout

ℹ️

Improve retry success rates

When prompting a customer to retry, surface the relevant tips from the Prepare your customers for verification section. For example, if the failure was id_quality_check_failure, remind the customer to place the ID on a flat surface, ensure all four corners are visible, and avoid glare.

Sent to compliance review -- wait for decision:

These failures are escalated to Cybrid's compliance team. The identity verification enters the reviewing state and the team makes a final determination:

• database_check_failure
• id_barcode_check_failure
• id_number_check_failure
• duplicate_person_check_failure
• country_comparison_check_failure
• name_check_failure
• address_check_failure
• dob_check_failure
• review_required
• pep_check_failure
• media_check_failure
• watchlist_check_failure

Customer is rejected -- contact support:

These failures indicate fraud signals or compliance issues. The customer cannot retry without Cybrid support resetting the customer state to unverified:

• id_mrz_check_failure
• id_presence_check_failure
• id_digital_replica_check_failure
• id_paper_replica_check_failure
• prohibited_person_check_failure
• selfie_failure
• selfie_pose_check_failure
• selfie_quality_check_failure
• compliance_rejection

For the full list of failure codes and their descriptions, see the Identity Verification Overview.

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.

• Create a platform account
• Add Customer External Bank Accounts
• Fund accounts

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