Shopify - iDenfy Documentation

Overview

The iDenfy Shopify app embeds identity verification directly into your store. Decide when customers verify (4 flows), who is asked (conditional triggers), and what happens after (order holds, auto-refunds, emails) — all from the Shopify Admin.

Install from the App Store

One-click install with automatic permission setup.

Pick a verification flow

Account, cart, checkout, or post-purchase.

Layer conditional triggers

Cart value, region, risk score, products, collections.

Automate order state

Hold, release, and refund orders based on KYC.

How It Works

The Shopify app combines a Shopify Admin app (built on Remix + Polaris), a Theme App Extension (Liquid), and a Checkout/Customer Account UI extension (React). When a verification trigger fires, the storefront fetches a one-time authToken from iDenfy, opens iDenfy’s hosted UI, and writes the result back onto the Shopify customer and order via metafields, tags, and notes.

You don’t need to manage any of the moving parts — the app handles tokens, webhooks, geolocation, holds, and refunds. This section is here so you know what to look for when something doesn’t behave as expected.

Quick Start

Requirements

Active iDenfy production environment (see pricing)
iDenfy API key and secret (Dashboard → Settings → API Keys)
A Shopify store on any plan that supports apps and theme editing

Install the iDenfy app

Install from the Shopify App Store and approve the requested permissions (customers, orders, products, collections, fulfillment).On first install the app pulls your existing collections, products, and customers into its database so they can be used in trigger rules.

Connect your iDenfy account

Open the iDenfy Admin page inside Shopify and connect using one of two methods:

iDenfy login (recommended)
Manual API key

Choose a verification flow

Pick exactly one flow — see Verification Flows below for the trade-offs. Your choice is also written to a shop metafield so theme extensions can read it at runtime.

Configure the iDenfy webhook

On the iDenfy Dashboard → Webhooks, add an ID verification auto finish webhook.

Receiver: https://shopify.idenfy.com/api/sdk/verification/webhook
Signing key: the same API key you connected with above

The Shopify app verifies every incoming webhook signature against this key.

Without the correct signing key, webhooks are rejected and verification results will not appear in your store.

Enable the matching extension in your theme

Open Online Store → Themes → Customize and enable the extension that matches your chosen flow. See Theme & UI Setup.

Verification Flows

You pick one flow per store. Each flow controls where the verify button appears and when the customer is asked.

Flow	Where the button appears	Best for
Account page	Customer account page (Legacy & new)	Pre-qualify customers before they can check out
Before checkout	Cart page or cart drawer	Block checkout until verified
During checkout	The checkout page itself	Verify mid-checkout without leaving Shopify
After checkout	Thank-you & Order-status pages	Let purchase complete, then verify (with hold/refund)

Account page flow

The verification button is shown on the customer account page. The checkout button is hidden site-wide until the customer is verified. If they are already verified, a success badge is shown.

Before checkout flow

The verification button replaces the cart and checkout buttons whenever the cart matches a trigger rule. The check re-runs whenever the cart contents change.

During checkout flow

The verification button appears on the checkout page itself via a Checkout UI extension. Checkout progress is blocked until verification succeeds.

After checkout flow

The order completes normally; the customer is prompted to verify on the Thank-you and Order status pages. Combined with Order State Management, this enables hold-and-refund behavior.

Flow-restricted features. A few features are only available in the After-checkout flow because they need the order or shipping address to exist first:

Risk-factor triggering
Regional minimum age limits
Order State Management (hold + auto-refund)
The “Shipping address” geolocation method

Theme & UI Setup

Once a flow is picked, enable its matching extension in Online Store → Themes → Customize.

App Embed Block (Account + Before checkout)
Checkout / Account UI Extension (During + After checkout)

The Liquid iDenfy ID button app-embed block is injected at the body level.

Block settings:

Setting	Purpose
CTA text	Label on the verify button.
Geolocation permission notice / retry text	Shown when the browser blocks geolocation.
Checkout button selector	CSS selector for the theme’s checkout button, so the app can hide it. Comma-separated for multi-theme support.
Cart alter buttons selector	CSS selector for cart add/remove buttons, so KYC is re-evaluated when the cart changes.
Account (Legacy) button selector	CSS selector used to anchor the verify button on the legacy account page.

Advanced — CSS variable styling

The block exposes CSS variables you can override in your theme stylesheet to match your brand.

:root {
  --idenfy-modal-desktop-width: 60vw;
  --idenfy-modal-desktop-height: 90vh;
  --idenfy-modal-mobile-width: 100vw;
  --idenfy-modal-mobile-height: 90vh;
  --idenfy-modal-backdrop: rgba(0, 0, 0, 0.5);

  --idenfy-btn-min-width: 160px;
  --idenfy-btn-font-size: 16px;
  --idenfy-btn-line-height: 1.5;
  --idenfy-btn-padding: 10px 24px;
  --idenfy-btn-border-radius: 5px;
  --idenfy-btn-bg-color: #28a745;
  --idenfy-btn-text-color: white;
  --idenfy-btn-bg-color-hover: #218838;
  --idenfy-btn-text-color-hover: white;
  --idenfy-error-text-color: #c70a24;

  --idenfy-message-font-size: 14px;
  --idenfy-message-padding: 4px 16px;
  --idenfy-message-margin: 16px 0;
  --idenfy-message-border-radius: 5px;
  --idenfy-message-success-bg-color: #28a745;
  --idenfy-message-info-bg-color: #ffb800;
  --idenfy-message-info-text: black;
  --idenfy-message-success-text: white;
}

A React extension that targets four storefront surfaces.

Surface	Where it renders
`purchase.checkout.block.render`	Checkout page
`purchase.thank-you.block.render`	Thank-you page
`customer-account.order-status.block.render`	Order status page
`customer-account.profile.block.render`	Customer profile (new accounts)

Setup:

Switch context

In the theme editor, change the dropdown to Checkout and customer accounts.

Add the iDenfy extension

Add it to the Thank you, Profile, and Order status pages.

Position the extension

Click each extension instance to pick exactly where on the page it should appear.

You can also set a “Paragraph above button” message shown directly above the Verify Identity button.

Styling is limited here — Checkout/Account UI extensions render in a sandboxed React environment that does not support arbitrary CSS overrides.

Triggering Rules

In the ID Verification flow card you can layer multiple conditional triggers. The customer is asked to verify only when at least one rule matches.

Rule	Description	Flow restriction
Daily money limit	Customer’s total ordered amount today reaches the limit.	All flows
Monthly money limit	Same, month-to-date.	All flows
Daily order count	Trigger after N orders today.	All flows
Monthly order count	Same, month-to-date.	All flows
By region	Trigger for customers in specific countries or US states. Detected via browser geolocation or shipping address.	Shipping-address detection is after-checkout only
By risk factor	Trigger when the order’s Shopify risk score reaches `low` / `medium` / `high`. Optional “trigger when no risk factor yet” checkbox.	After-checkout only
By product / collection	Narrow all the above triggers to carts containing specific products or collection items.	All flows

How browser geolocation works

The storefront requests the browser’s coordinates via the Geolocation API.
Coordinates are POSTed to /apps/sdk/geolocation and stored as customer metafields (idenfy.geolocation_latitude, idenfy.geolocation_longitude, idenfy.geolocation_date).
Coordinates older than ~5 min on the cart page are refreshed automatically. Coordinates older than 1 hour are flagged in logs but still used.
The server uses PostGIS geometry to check whether the coordinates fall inside any of the configured countries or US states.

Identity Constraints

Separate from triggers, the following identity constraints apply to every verification:

Constraint	Description	Flow restriction
Name must match identity document	iDenfy fails the verification if the Shopify-provided name does not match the document.	All flows
Global minimum age	Minimum age applied to every verification.	All flows
Regional minimum age	Per-country and per-state minimum age. Age is computed from the document’s date of birth.	After-checkout only

Order State Management

Available only in the After-checkout flow. When Automatically manage Shopify’s order state is enabled:

Order placed

If any KYC rule matches the order, the app puts the order’s fulfillment on hold immediately.

Customer prompted

The customer sees the verify button on the Thank-you and Order-status pages. Optionally, an email is sent.

On success — auto-release

If KYC returns APPROVED, the hold is released and the order proceeds to fulfillment automatically.

On timeout — auto-cancel & refund

If verification is not completed within the configured Order refund timeframe (1 hour – 4 weeks), a cron job cancels the order and refunds the customer.

Two optional transactional emails are configurable here:

Ask Complete KYC — sent while the order is on hold.
Order Cancelled — sent when the order is auto-cancelled.

Email Notifications

The app can send up to four transactional emails:

Email	Sent when	Available in
Ask Complete KYC	Order placed and held for verification	After-checkout (Order State Management)
Order Cancelled	Order auto-cancelled after timeframe expires	After-checkout (Order State Management)
Successful KYC verification	Webhook returns `APPROVED`	All flows
Failed KYC verification	Webhook returns `DENIED` / `SUSPECTED` / `EXPIRED`	All flows

Custom Sender Identity

By default, emails are sent from iDenfy’s shared address. You can configure a custom domain via Resend:

Configure identity

Open Configure custom email sender identity. Enter a username (e.g. noreply), domain, and AWS region (us-east-1, eu-west-1, sa-east-1, or ap-northeast-1).

Verify domain

Open Verify custom email sender identity. Add the DNS records shown to your domain registrar. Resend verifies the records on its side.

Edit templates

Once verified, an Edit email template button appears for each email type. You can customize both the text and HTML bodies.

Available template variables

Variable availability depends on the email type:

Variable	Available in
`{firstName}`, `{lastName}`	All emails
`{orderNumber}`	All order-bound emails
`{orderStatusPageUrl}`	Ask Complete KYC
`{timeframe}`	Ask Complete KYC
`{reason}`	Failed KYC
`{manageOrderState}`	Successful KYC (inserted when Order State Management is on)

Custom templates can only be saved while a verified custom identity exists, but they are kept in the database if you later reset the identity — so re-verifying won’t lose your work.

Customer & Order Records

After every verification, the app writes the result onto Shopify.

Customer Record

Field	Type	Meaning
`idenfy.is_verified`	metafield (boolean)	`true` if `APPROVED`. The source of truth across the app.
`idenfy.verification_status`	metafield (text)	`APPROVED` / `DENIED` / `SUSPECTED` / `EXPIRED`
`idenfy.scan_ref`	metafield (text)	iDenfy verification reference
`idenfy.fraud_tags`	metafield (text)	Comma-separated fraud flags from iDenfy
`idenfy.mismatch_tags`	metafield (text)	Comma-separated mismatch flags
`idenfy.geolocation_*`	metafield (number/datetime)	Last submitted geolocation (when geolocation triggering is on)
Tag	string	Exactly one of `idv-approved`, `idv-denied`, `idv-suspected`, `idv-failed`, `idv-expired`, `idv-unverified`

Captured email or phone from the verification is also saved into the customer record when available.

Order Record

When verification is tied to an order (Before checkout with a logged-in customer, During checkout, or After checkout):

Order Notes — the app appends a line summarizing status, scan reference, and any fraud / mismatch tags.
Order Tags — the same idv-<status> tag is added.
Fulfillment hold / release — automatic, under Order State Management.
Order cancellation & refund — automatic, if the order remains unverified past the configured timeframe.

If the customer was not logged in during verification (guest checkout in the Before-checkout flow), only the order is updated. The app has no Shopify customer record to write to.

Additional Settings

Automatically delete customer scan references — when a customer is deleted in Shopify, their iDenfy scan reference is also deleted via the iDenfy API.
Customer scan-ref removal table — a searchable, paginated list of customers with an idenfy.scan_ref metafield. You can manually delete a scan reference; the metafield is then replaced with "Deleted on iDenfy Dashboard" so the action is visible in the customer record.

Reference

Verification Statuses

iDenfy status	Customer/order tag	Meaning
`APPROVED`	`idv-approved`	Verified successfully
`DENIED`	`idv-denied`	Failed verification
`SUSPECTED`	`idv-suspected`	Verified but flagged for manual review
`EXPIRED`	`idv-expired`	Verification session expired without completion
`FAILED`	`idv-failed`	Internal/system failure
(none yet)	`idv-unverified`	Session started, no result yet

A SUSPECTED result returned during checkout triggers a banner asking the customer to retry.

Troubleshooting

Webhook signature errors

The signing key on the iDenfy Dashboard webhook must be identical to the API key the Shopify app is connected with. Mismatch causes every webhook to be rejected and no verifications will appear in the store. Re-paste the key on the iDenfy Dashboard if results stop appearing.

Geolocation permission missing

Verification triggered by By region with browser geolocation requires the customer to grant location permission. The block has configurable “geolocation permission notice” and “retry” copy — make sure those are translated and visible. If the customer denies permission, no coordinates are submitted and the region rule cannot fire.

“Order not ready” / retry

On the Thank-you page the app may briefly show an “order not ready” message while Shopify finishes writing the order. The page polls automatically; no action is required.

SUSPECTED verifications

SUSPECTED means iDenfy verified the identity but flagged the result for human review. By default these customers are not treated as verified — they appear with the idv-suspected tag and Order State Management keeps the order on hold until the status is changed on the iDenfy Dashboard.

Custom themes — buttons not hidden

If your theme uses non-standard CSS classes for the checkout or cart buttons, the default selectors will miss them. Update the Checkout button selector and Cart alter buttons selector in the app-embed block settings (comma-separated CSS selectors are supported).

What’s Next?

iDenfy Dashboard — KYC settings

Tune document types, liveness, languages, and branding for everything triggered from Shopify.

Webhook payload reference

Full payload spec for the verification results the app receives.

Testing & sandbox

Simulate APPROVED / DENIED / SUSPECTED results before going live.

Other plugins

WooCommerce, Adobe Commerce, WordPress, Zapier.

Documentation Index

​Overview

Install from the App Store

Pick a verification flow

Layer conditional triggers

Automate order state

​How It Works

​Quick Start

​Verification Flows

​Theme & UI Setup

​Triggering Rules

​Identity Constraints

​Order State Management

​Email Notifications

​Custom Sender Identity

​Customer & Order Records

​Customer Record

​Order Record

​Additional Settings

​Reference

​Verification Statuses

​Troubleshooting

​What’s Next?

iDenfy Dashboard — KYC settings

Webhook payload reference

Testing & sandbox

Other plugins

Overview

How It Works

Quick Start

Verification Flows

Theme & UI Setup

Triggering Rules

Identity Constraints

Order State Management

Email Notifications

Custom Sender Identity

Customer & Order Records

Customer Record

Order Record

Additional Settings

Reference

Verification Statuses

Troubleshooting

What’s Next?