ShipToVerified

விளக்கம்

ShipToVerified connects your WooCommerce store with the ShipToVerified service to automate identity verification and adult signature compliance for regulated product shipments.

The plugin handles the full verification lifecycle:

• Evaluates whether an order requires adult signature or identity verification based on the customer’s shipping destination and cart contents.
• Exposes the store’s WordPress customer roles to the ShipToVerified portal and includes the customer’s roles in the order data, so merchants can scope the ID Verification rules to specific customer roles (with explicit “All” and “Guest” options) under Settings → Platforms → WooCommerce.
• Notifies the ShipToVerified service when a qualifying order is placed.
• Renders a secure identity verification widget on the order confirmation and account pages (and, optionally, the order tracking page) so the customer can complete verification without leaving your store.
• Receives signed webhook events from ShipToVerified when a customer completes verification or when the verified shipping address changes, and updates the WooCommerce order record accordingly.
• Gives store administrators a manual verification option and a verification status panel directly inside the WooCommerce order screen.
• Adds a custom “Awaiting Verification” order status (wc-await-verify) that qualifying orders are placed into until verification completes, so unverified orders are easy to spot and filter in WooCommerce.

Who needs this plugin?

Retailers that ship age-restricted, regulated, or compliance-sensitive products (such as firearms accessories, tobacco, cannabis, or adult goods) to jurisdictions that require adult signature delivery or government-issued identity verification at the point of purchase.

How it works

1. The merchant connects the store to ShipToVerified via an OAuth flow in WooCommerce > ShipToVerified.
2. When a customer reaches the checkout page, the plugin sends the cart’s shipping state, order total, and product details to the ShipToVerified API to determine whether the cart requires an adult signature fee or identity verification notice.
3. When the customer places an order and it moves to processing or completed status, the plugin notifies ShipToVerified with the order ID so that a verification requirement can be assigned.
4. On the order confirmation page (and optionally the account order-detail or order tracking page), the plugin loads an identity verification widget served by ShipToVerified that guides the customer through document capture and liveness checks.
5. Once the customer completes the verification flow, ShipToVerified sends a signed webhook back to the store. The plugin validates the signature, marks the order as verified, and stores the verified name and address in the order meta.

External services

This plugin connects to the ShipToVerified API (https://api.shiptoverified.com). A ShipToVerified merchant account is required. Connection is established by the store administrator during initial setup via OAuth.

Checkout eligibility check
Triggered automatically on the checkout page for every customer session (including guests) while the plugin is active and connected. This call determines whether the current cart requires an adult signature fee or identity verification notice.

• When it runs: the first time a customer reaches checkout, and again whenever the relevant cart details change (shipping state, cart total, or cart contents). Results are cached for the duration of the customer’s session — keyed on a hash of the cart, shipping state, and total — so a repeat checkout page load with an unchanged cart does not trigger another API call.
• Data sent: customer’s shipping state (two-letter US state code), cart grand total, and line items (product ID, product name, quantity, and product category names).
• Why it is sent: ShipToVerified maintains up-to-date jurisdiction rules for regulated products. Sending the cart snapshot allows the service to evaluate applicable state laws without storing a static ruleset inside the plugin.
• Data received: a boolean indicating whether an adult signature fee and/or a verification notice should be displayed.

Order created notification
Triggered once per order, when the order status first moves to processing or completed.

• Data sent: WooCommerce order ID and store URL.
• Why it is sent: this tells ShipToVerified to create a verification record linked to the order so it can manage the customer-facing verification flow and track completion.
• Data received: a flag indicating whether the order requires identity verification.

Widget initialization
Triggered on the order confirmation page (and optionally the account order-detail or order tracking page) when an order requires identity verification.

• Data sent: WooCommerce order ID and store URL.
• Why it is sent: ShipToVerified generates a short-lived, single-use widget token scoped to that order so that the verification session cannot be replayed or hijacked.
• Data received: a widget token and a flag confirming verification is required.
• A JavaScript file (/widget.js) is then loaded directly from https://api.shiptoverified.com to render the verification interface. This file is served by the ShipToVerified service and is part of the core service functionality (similar to how payment processors serve their checkout scripts).

Webhook (inbound)
ShipToVerified sends a signed POST request to /wp-json/shiptoverified/v1/webhook when a verification event occurs (e.g., the customer completes verification, the verified shipping address changes, the address cannot be validated, or address validation is awaiting customer input).

• Supported events: verification.completed, address.updated, address.unverified, address.review_required.
• Data received: event type, event ID, order ID, verification ID, verified customer name, and verified shipping address. For the address events the payload instead carries a human-readable reason and/or a suggested address — address.updated sends the corrected address, address.unverified sends a reason, and address.review_required sends a reason plus an optional suggested_address.
• For address.review_required, the plugin adds a private order note recording the pending state and any suggested address, and takes no other action (the order stays awaiting the customer’s response).
• All webhook payloads are validated with an HMAC-SHA256 signature before processing.
• Each event is idempotent: duplicate event IDs are ignored.

Order data endpoint (inbound)
ShipToVerified may request full order details via GET /wp-json/shiptoverified/v1/order/{id} to display order context inside the ShipToVerified merchant dashboard.

• Data returned: order ID, order status, order total and currency, the customer’s billing email address (personally identifiable information), the customer’s name, account ID, and WordPress roles, the full shipping address (name, street, city, state, postcode, country), and line items (product ID, name, quantity, and product category names).
• Authentication: requires the store’s API key in the X-API-Key header.

Store roles endpoint (inbound)
ShipToVerified may request the store’s configured WordPress roles via GET /wp-json/shiptoverified/v1/roles so a merchant can scope ID Verification rules to specific customer roles in the ShipToVerified dashboard.

• Data returned: the slug and display name of each WordPress role defined in the store. No customer-specific data is sent.
• Authentication: requires the store’s API key in the X-API-Key header.

Connection management (OAuth)
Used once during initial setup and optionally to test or re-establish the connection.

• Data sent: store URL, OAuth authorization code or callback parameters.
• Data received: API key, webhook secret.

By installing, activating, and connecting this plugin, the store administrator consents to the transmission of the above data to ShipToVerified on behalf of the store and its customers, in accordance with the service terms.

• Terms of Service: https://shiptoverified.com/terms
• Privacy Policy: https://shiptoverified.com/privacy

Merchants are responsible for disclosing the use of this service to their customers in their store’s privacy policy.

Order Meta Keys

The plugin stores all verification data in WooCommerce order meta. Keys are defined as constants in src/App/Domains/Orders/Order.php (and the reminder-timestamp keys in src/Units/Admin/Actions/ManualVerifyOrderAction.php).

Meta keys use more than one prefix for historical reasons. _stv_* is the canonical ShipToVerified namespace used for newer keys. Keys without that prefix (_is_ffl, _requires_id_verification, _order_id_*, _id_verification_*_reminder_sent_at) predate the namespace standardization and are retained as-is so existing orders keep their verification history; they are not renamed because doing so would orphan compliance data on already-processed orders. Plugin options use a single stv_ prefix (see Uninstall Cleanup).

Verification state

• _requires_id_verification — Set to 'yes' when the STV backend determines the order requires identity verification.
• _order_id_verified — Set to 'yes' when the customer successfully completes the verification flow (via widget or manual override).
• _is_ffl — Set to 'yes' when the order is flagged as an FFL (Federal Firearms License) order. FFL orders are excluded from identity verification and adult signature workflows.

Verified identity data (written via webhook)

• _order_id_verified_name — Full name as verified by STV (string).
• _order_id_verified_address — Verified shipping address (serialized array).
• _order_id_verification_timestamp — MySQL datetime string recording when verification completed.
• _stv_verification_id — The STV-side verification UUID. Use this to look up the verification record in the ShipToVerified dashboard.

Widget and notification state

• _stv_widget_token — Short-lived, single-use token used to initialise the frontend verification widget. Generated by STV and stored temporarily; do not rely on its value after the order is verified.
• _stv_order_created_notified — Set to 'yes' after the plugin has successfully notified the STV backend of a new order. Prevents duplicate notifications on status re-changes.
• _stv_webhook_processed_{event_id} — Idempotency guard. Written once per processed webhook event to prevent duplicate processing if STV delivers the same event more than once. {event_id} is the event UUID from the STV webhook payload.

Reminder email timestamps (set by ShipToVerified)

• _id_verification_first_reminder_sent_at — Timestamp recorded when ShipToVerified sent the customer the first verification reminder. The plugin does not send email itself; it stores these timestamps and clears them when an order is manually verified.
• _id_verification_second_reminder_sent_at — Timestamp recorded when ShipToVerified sent the customer the second verification reminder.

Hooks Reference

= Filters the plugin listens to =

• woocommerce_order_actions (priority 10, 2 args) — Adds the Mark ID Verified entry to the order action dropdown in the admin order screen (ManualVerifyOrderFilter::addManualVerificationOrderAction).

Custom actions the plugin fires

Third-party code can hook into these to react to verification events.

do_action( 'shiptoverified_order_id_verification_complete', int $order_id )

Fired when an order is marked as successfully verified — either by the STV webhook completing the customer flow, or by the admin using the manual verify order action.
* $order_id (int) — The WooCommerce order ID that was just verified.

do_action( 'shiptoverified_add_ca_signature_fee', bool $requires )

Fired during checkout eligibility evaluation after the cart rules are checked against the STV backend.
* $requires (bool) — true if the current cart requires an adult signature fee; false otherwise. Hook into this to add or remove a fee line item on the cart.

REST API Endpoints

Four endpoints are registered under the namespace shiptoverified/v1.

GET /wp-json/shiptoverified/v1/order/{id}

Returns order details to the ShipToVerified merchant dashboard.

• Authentication: X-API-Key request header must match the stv_api_key WordPress option.
• Response: order_id, status, total, currency, billing_email, customer (id, email, first_name, last_name, name, roles), shipping_address (first_name, last_name, address_1, address_2, city, state, postcode, country), and items (product_id, name, quantity, categories).
• Use: called by the STV backend when a merchant views an order inside the ShipToVerified dashboard.

GET /wp-json/shiptoverified/v1/order-statuses

Returns the list of available WooCommerce order statuses (id + label) to the ShipToVerified dashboard.

• Authentication: X-API-Key request header must match the stv_api_key WordPress option.
• Response: array of { "id", "name" } objects derived from wc_get_order_statuses().

GET /wp-json/shiptoverified/v1/roles

Returns the store’s WordPress user roles so a merchant can choose which roles ID Verification applies to.

• Authentication: X-API-Key request header must match the stv_api_key WordPress option.
• Response: array of { "id", "name" } objects derived from wp_roles()->get_names().

POST /wp-json/shiptoverified/v1/webhook

Receives verification event callbacks from ShipToVerified.

• Authentication: open endpoint, but every request is validated against an HMAC-SHA256 signature in the X-Stv-Signature header using the stv_webhook_secret option. Requests with an invalid signature or a timestamp outside the 5-minute window are rejected with 401.
• Payload fields: event_type, event_id, order_id, verification_id, verified_name, verified_address.
• On success: validates and idempotently processes the event, then returns 200. For verification.completed it marks the order ID-verified, applies the verified shipping address, and fires shiptoverified_order_id_verification_complete. The address.* events update the shipping address (address.updated), flag the order for manual review (address.unverified), or add a pending-customer note (address.review_required); these do not fire shiptoverified_order_id_verification_complete.

Testing & Review Guide

This section is intended for WordPress.org and WooCommerce plugin reviewers. It explains how to test each feature end-to-end.

A sandbox/test account can be requested from the ShipToVerified team at support@shiptoverified.com. Please mention that you are reviewing the plugin for WordPress.org.

Setup

1. Install and activate WooCommerce. Create at least one simple product.
2. Install and activate ShipToVerified.
3. Go to WooCommerce > ShipToVerified and click “Connect with ShipToVerified”.
4. Complete the OAuth flow. On success, the settings page shows a green “Connected” badge, the API key (read-only), and widget placement checkboxes.

Things to verify:

• The “Connect” button generates a nonce-protected URL (action stv_oauth_start).
• After authorization, stv_api_key and stv_webhook_secret are stored in wp_options.
• The “Test Connection” button calls the STV API and reports success or failure.
• Widget placement checkboxes (Thank You page, View Order, Order Tracking) save correctly.

Order Verification Flow

When an order moves to processing or completed, the plugin notifies ShipToVerified.

1. Place a test order and complete payment so the order reaches processing.
2. Open the order in WooCommerce > Orders.

Things to verify:

• The order has meta _stv_order_created_notified = yes (notification was sent).
• If the STV account is configured for verification, the order may be moved to “Awaiting Verification” status (wc-await-verify).
• The admin order detail panel shows a “California ID Verification” section with either a green “Verified” badge or a yellow “Pending” badge.
• FFL orders (meta _is_ffl = yes) are skipped entirely.
• The notification is sent only once per order (idempotency via _stv_order_created_notified).

Verification Widget

The plugin injects a JavaScript widget on customer-facing order pages so the customer can complete identity verification.

1. Place an order that requires verification.
2. On the Thank You page, the widget should render with a verification prompt.
3. Alternatively, go to My Account > Orders > View Order for the same order.

The widget appears on these pages (controlled by settings checkboxes):

• Thank You page (woocommerce_thankyou) — enabled by default.
• My Account > View Order (woocommerce_view_order) — enabled by default.
• Order Tracking (woocommerce_order_tracking) — disabled by default.

Things to verify:

• The widget only renders for orders with _requires_id_verification = yes.
• The widget does not render for already-verified orders (_order_id_verified = yes).
• The widget does not render for FFL orders or FFL customers.
• The widget does not render for admin users viewing the page.
• The script is enqueued via wp_register_script / wp_enqueue_script (not echoed directly).

CA Adult Signature Notice

For orders shipping to California, the plugin can display a notice at checkout.

1. Add products to the cart and go to checkout.
2. Enter a California shipping address.
3. If the STV account has adult signature rules configured, a notice appears above the payment section.
4. Change the shipping state to a non-CA state — the notice should disappear.

Things to verify:

• The notice renders inside #ca-adult-signature-notice.
• The notice updates when the checkout form is refreshed (AJAX fragments).
• FFL customers are excluded.
• Results are cached per session to avoid redundant API calls (cache key: cart hash + state + total).

= …