Identity Verification

VerifyHuman Identity Verification provides full KYC-level verification by matching a government-issued ID document against a live selfie. It is used for high-value transactions, compliance-sensitive products, and fraud prevention.

Overview

Identity verification is the highest assurance level (L3) in the VerifyHuman system. It requires:

1. A photo of the front of a government-issued ID (driver's license, passport, or ID card).
2. Optionally, a photo of the back of the ID.
3. A live selfie for facial comparison.

The VerifyHuman API compares the selfie against the ID document to confirm the person presenting the ID is the same person making the purchase.

Trigger Methods

Identity verification can be triggered in three ways:

1. Button-Triggered (App Block)

Place the Identity Verification app block anywhere in your theme using the Shopify Theme Editor.

• Renders a styled "Verify My Identity" button on the page.
• Clicking the button opens a multi-step verification modal.
• Best for: Account pages, VIP sections, or any page where you want an explicit verification action.

How it works:

1. The block renders a button with customizable text and color.
2. On click, a modal opens with a 3-step flow: ID Front, ID Back (optional/skippable), and Selfie.
3. Step progress is shown via dot indicators at the top of the modal.
4. After all captures, the widget submits to /api/verify-identity.
5. On success, the onSuccess callback fires and optionally redirects to a configured URL.

2. Checkout Guard (App Embed)

The VerifyHuman - Checkout ID app embed intercepts the checkout process and requires identity verification before a customer can complete their purchase.

• Automatically detects restricted items in the cart using product tags or metafields.
• Blocks the checkout button until verification is complete.
• Hides express checkout buttons (Shop Pay, Apple Pay, Google Pay) until verified.
• Best for: Stores selling regulated products that require identity verification at purchase time.

How it works:

1. On page load, the Liquid template scans cart.items for restricted products.
2. If restricted items are found (or "Require for All Checkouts" is enabled), the widget loads.
3. Checkout buttons are intercepted; clicking them opens the verification modal instead.
4. Express checkout buttons are hidden with CSS to prevent bypass.
5. After successful verification:
   • A signed guest token (UVC) is issued and stored in sessionStorage.
   • The token is written to Shopify cart attributes as vh_idv_token.
   • For logged-in customers, verification is persisted to customer metafields.
   • Express checkout buttons are restored.
   • A green "Identity Verified" badge appears next to the checkout button.
   • The customer is redirected to checkout.

3. Post-Order (Server-Side)

When the identity trigger is set to "After Order" in dashboard settings, verification is requested after the customer has placed their order.

• The app listens for the Shopify orders/create webhook.
• When an order is created that contains restricted products, the app creates a pending verification record and generates a verification token.
• The merchant is responsible for sending the verification link to the customer (for example, via a custom email flow or order note). The app does not send emails automatically.
• Best for: Stores that prefer to verify customers after purchase rather than blocking checkout.

Current limitation: The app creates the pending verification and token, but does not include a built-in email sender. You will need to use a third-party email service or Shopify Flow to deliver the verification link to the customer.

Restricted Product Detection

The checkout guard detects restricted products using two methods:

Product Metafield

Set the metafield verifyhuman.requires_idv to true on any product that requires identity verification.

• Namespace: verifyhuman
• Key: requires_idv
• Type: boolean
• Values accepted: true, "true"

Product Tag

Add the tag vh_requires_idv to any product that requires identity verification.

• Default tag: vh_requires_idv
• Configurable: The tag name can be changed in the Theme Editor settings.
• Matching: Case-insensitive. Also matches any tag that contains vh_requires_idv.

Detection Modes

The server-side detection service supports three modes (configured via detectionMode):

Collection-level metafields (verifyhuman.requires_idv on a collection) are also supported when using both or metafields_only mode.

Customer Verification Persistence

Guest Customers

For visitors who are not logged in:

• A signed guest token (UVC - Universal Verification Credential) is issued after successful verification.
• The token is stored in sessionStorage under the key verifyhuman_identity_verified.
• The token is also written to the Shopify cart attributes as vh_idv_token, which the Shopify checkout validation function can read.
• Token validity: 24 hours.
• Guests are encouraged (via an optional nudge) to create an account to preserve their verification.

Logged-In Customers

For customers with a Shopify account:

• Verification status is persisted to customer metafields via the Shopify Admin API (GraphQL).
• Metafields set:

• Default TTL: 180 days (configurable via identityReuseTtlDays in dashboard settings).
• On subsequent visits, the Liquid template reads these metafields to check if the customer is already verified, skipping the verification flow.

Theme Editor Settings

Identity Verification Block (App Block)

Placed in any theme section via Customize > Add Block > Identity Verification.

Checkout ID Embed (App Embed)

Enabled in Customize > App Embeds > VerifyHuman - Checkout ID. Targets the <head>.

Dashboard Settings

In Advanced Mode, identity verification has its own tab in the dashboard settings:

Verification Levels

Identity verification fits into the VerifyHuman assurance level system:

The level computation service determines the required level based on:

• Shop settings (minimum required level, app mode).
• Cart contents (presence of restricted items).
• Cart total (if an identity cart threshold is configured in Simple Mode).

A higher level always satisfies lower level requirements (L3 satisfies L2 and L1).

UX Flow

Button-Triggered Flow

1. Button click: Customer clicks the "Verify My Identity" button on the page.
2. Step 1 - ID Front: Camera opens in environment-facing mode. Customer photographs the front of their ID. They can retake if needed.
3. Step 2 - ID Back (optional): Customer can capture the back of their ID or skip this step.
4. Step 3 - Selfie: Camera switches to user-facing mode. Customer takes a selfie.
5. Submit: All captures are sent to the API. A loading spinner is shown.
6. Result: Success or failure message is displayed. On success, optional redirect occurs.

Checkout Guard Flow

1. Page load: The widget scans the cart for restricted items.
2. Checkout intercept: If restricted items are found, express checkout buttons are hidden and checkout buttons are intercepted.
3. Modal opens: When the customer clicks checkout, a verification modal appears showing the 3-step process (ID Photo, Selfie, Verified).
4. Start verification: Customer clicks the verification button to begin.
5. ID capture: Camera opens for ID photo capture.
6. Selfie capture: Camera switches to front-facing for selfie.
7. Verification: Images are submitted to /api/verifyhuman/complete-identity-verification.
8. Token issuance: On success, a UVC token is issued, stored in session, and written to cart attributes.
9. Customer persistence: For logged-in customers, metafields are updated.
10. Checkout proceeds: Express checkout buttons are restored, a verified badge appears, and the customer is redirected to checkout after a brief delay.

API Endpoints

POST /api/verify-identity

Basic identity verification endpoint used by the button-triggered widget.

Request body:

{
  "id_front_b64": "<base64 image>",
  "id_back_b64": "<base64 image or null>",
  "selfie_b64": "<base64 image>",
  "customer_id": "optional",
  "order_id": "optional"
}

Response:

{
  "success": true,
  "verified": true,
  "confidence": 0.95,
  "verification_id": "vh_xyz789"
}

POST /api/verifyhuman/complete-identity-verification

Combined endpoint used by the checkout guard widget. Performs verification, issues a token, and optionally persists to customer metafields.

Request body:

{
  "id_front_b64": "<base64 image>",
  "id_back_b64": "<base64 image or null>",
  "selfie_b64": "<base64 image>",
  "customer_id": "optional",
  "cart_token": "optional"
}

Response (success):

{
  "success": true,
  "verified": true,
  "verification_event_id": "vhe_abc123",
  "token": "<signed UVC token>",
  "token_expires_at": "2025-01-16T12:00:00.000Z",
  "customer_persisted": true,
  "message": "Identity verified successfully",
  "uvc": {
    "verification_id": "vhv_def456",
    "assurance_level": 3,
    "age_result": "over_21",
    "verified_at": "2025-01-15T12:00:00.000Z"
  }
}

POST /api/verifyhuman/verify-token

Validates a guest verification token.

Request body:

{
  "token": "<UVC token string>"
}

Response:

{
  "valid": true,
  "remaining_time_ms": 86400000,
  "shop": "my-store.myshopify.com"
}

GET /api/verifyhuman/check-customer-verification/:customerId

Checks if a logged-in customer has valid identity verification in their metafields.

Response:

{
  "verified": true,
  "verified_at": "2025-01-15T12:00:00.000Z",
  "expires_at": "2025-07-14T12:00:00.000Z"
}

Privacy and Data Handling

Identity verification includes built-in privacy disclosures:

• A micro-notice appears at the bottom of the checkout verification modal with a lock icon.
• Text: "Your privacy is protected. We use your image and ID only to complete this verification and do not store personal identity data."
• A "Learn more" link directs to the VerifyHuman privacy policy (or a custom URL).

Data retention:

Testing Identity Verification

1. Tag a test product with vh_requires_idv or set the verifyhuman.requires_idv metafield to true.
2. Enable the Checkout ID embed in the Theme Editor.
3. Add the tagged product to cart and navigate to the cart page.
4. Attempt to check out and confirm the verification modal appears.
5. Complete the verification (camera access required) and confirm:
   • The verified badge appears next to the checkout button.
   • Express checkout buttons are restored.
   • You are redirected to checkout.
6. For button-triggered verification, add the Identity Verification block to a page section and test the click-to-verify flow.
7. Check session persistence by refreshing the page; verification should persist.

For test mode details, see Reviewer Test Mode.