WordPress Hooks

You can use hooks to extend Real ID into your own WordPress code.

Webhooks also available

You can also use webhooks to subscribe to ID verification events as well.

ID verification status changes

You can subscribe in real time when customers submit their ID photos with the id_verification_status_changed hook.

This hook will fire whenever a customer's ID verification status changes.

Order status changes

This hook will also emit on order verification status changes. For example, if an already verified customer places another order, this hook will also fire, since this new order is now considered verified.

id_verification_status_changed

This hook will emit every single time a customer or order's ID verification status changes.

Parameters

This hook passes a single associative array:

• check_id - the unique ID verification token tied to the customer
• new_status - the status being applied to the order. See metadata for a complete list.
• customer_id - the customer's WordPress user ID
• order_id the WooCommerce order ID

Relies on webhooks

Metadata updates rely on your site being reachable by the Real ID service by webhook.

Webhooks are asynchronous checkout or order events, they may not happen at the same time as a new order being placed, etc.

Examples

This simple example will log these changes to your WooCommerce logs so you can see the trail of changes of ID verification status updates:

// Subscribing to the update, and logging the change to the WooCommerce Status Logs
add_action('id_verification_status_changed', function($params) {
  $logger = wc_get_logger();

  $logger->info('ID verification status changed for an order', [
    "source" => "Real ID",
    "new_status" => $params["new_status"],
    "order_id" => $params["order_id"],
    "customer_id" => $params["customer_id"],
    "check_id" => $params["check_id"],
  ]);

}, 10, 1);

You can also use the order_id to retreive the current order details:

// Subscribing to the update, and retrieving the order associated with the ID check:
add_action('id_verification_status_changed', function($params) {
  $order_id = $params["order_id"];

  if(empty($order_id)) {
    // it's possible that only the customer metadata is changing
    return;
  }

  $order = get_wc_order($order_id);

  // check the current fulfillment, payment statuses, etc.
}, 10, 1);

Frequently Asked Questions

Will this hook be called from new orders from already verified customers?

Yes, even though technically it's not an ID verification event by the customer, the order's metadata is updated with the ID check details on a new order by an already verified customer.

This hooks fires multiple times

Yes, it's possible for this hook to fire multiple times for the same event, this is by design to make sure that your metadata is up to date.

Please make sure your extension logic is idempotent and accounts for the possibility of multiple calls for the same event.

How is this hook called?

The Real ID service emits webhooks to your WordPress site when customers progress through ID verification.

This hook is delayed or isn't firing at all in our tests

Make sure your site is publicly accessible to the internet and you haven't recently change your site's home URL.

If you don't see any incoming webhooks from the Real ID service on your WordPress site whatsoever; then that most likely means that your site's URL has changed and it needs to be updated.

Contact our support if you continue to have issues with metadata or hooks not firing properly.

---

Creating ID checks programmatically

You can create ID checks directly from your own PHP code using the real_id_create_check() function. This is useful for:

• Custom trigger logic - Implement complex AND conditions that aren't possible with built-in rules
• Custom thank-you pages - Trigger verification on Elementor or other page builder pages
• Customer registration - Verify identity during account creation (without an order)
• Custom workflows - Integrate ID verification into any part of your site

real_id_create_check($args)

Creates an ID verification check and optionally displays the verification widget.

Parameters

Parameter	Type	Required	Default	Description
order_id	int	No*	null	WooCommerce order ID. If provided, customer data is extracted automatically.
customer_id	int	No	null	WordPress user ID to associate with the check.
email	string	No*	null	Customer email address.
phone	string	No	null	Customer phone number.
first_name	string	No	null	Customer first name.
last_name	string	No	null	Customer last name.
display_widget	bool	No	true	Whether to render the verification widget.
display_mode	string	No	'full'	Widget display mode: 'full' (inline) or 'modal' (overlay popup).
target	string	No	null	CSS selector for custom mount point. If not provided, widget_html includes a mounting div automatically.

Required parameters

Either order_id OR email/phone is required. If you provide order_id, customer contact info is extracted from the order automatically.

Return Value

On success, returns an array:

[
  'success' => true,
  'check_id' => 'abc123...',  // Unique check identifier
  'check' => [...],           // Full check object from API (null if from cache)
  'from_cache' => false,      // Whether check ID was retrieved from session cache
  'widget_html' => '...'      // Complete HTML (div + script) - just return this from your shortcode
]

On error, returns a WP_Error object with one of these codes:

• invalid_order - Order ID provided but order not found
• missing_contact - No email or phone provided
• no_license - Real ID license key not configured
• api_error - API request failed

Examples

Basic shortcode usage (recommended):

add_shortcode('my_verification', function() {
  $result = real_id_create_check(['order_id' => 123]);

  if (is_wp_error($result)) {
    return '';
  }

  // widget_html includes everything needed (mounting div + script)
  return $result['widget_html'];
});

Modal display mode:

add_shortcode('modal_verification', function() {
  $result = real_id_create_check([
    'order_id' => 123,
    'display_mode' => 'modal'  // Shows as popup overlay
  ]);

  if (is_wp_error($result)) {
    return '';
  }

  return $result['widget_html'];
});

Without displaying widget (email/SMS only):

// Just send the verification request via email/SMS
// Don't display anything on the page
real_id_create_check([
  'order_id' => 123,
  'display_widget' => false
]);

With custom target (advanced):

// Use this if you need custom styling or an existing element
add_shortcode('custom_verification', function() {
  $result = real_id_create_check([
    'order_id' => 123,
    'target' => '#my-custom-div',  // Your own element
  ]);

  if (is_wp_error($result)) {
    return '';
  }

  // When using custom target, you provide the element
  return '<div id="my-custom-div" class="my-styles"></div>' . $result['widget_html'];
});

Custom Thank-You Page Example

If you're using Elementor or another page builder with a custom thank-you page, you can create a shortcode that triggers ID verification with custom AND conditions:

// Add this to your theme's functions.php or a custom plugin
add_shortcode('my_id_verification', function() {
  // Payment gateways that require ID verification (add more as needed)
  $required_gateways = [
    'cod',      // Cash on delivery
    'bacs',     // Bank transfer
    // Add more gateway IDs here
  ];

  // Minimum order total to trigger verification
  $minimum_order_total = 200;

  // Get order ID from URL parameters
  $order_id = isset($_GET['order-received']) ? absint($_GET['order-received']) : null;

  if (!$order_id) {
    $order_id = isset($_GET['order_id']) ? absint($_GET['order_id']) : null;
  }

  // Some page builders use ?key=wc_order_xxx format
  if (!$order_id && isset($_GET['key'])) {
    $order_key = sanitize_text_field($_GET['key']);
    $order_id = wc_get_order_id_by_order_key($order_key);
  }

  if (!$order_id) {
    return ''; // No order found
  }

  $order = wc_get_order($order_id);

  if (!$order) {
    return '';
  }

  // Check conditions: order total > minimum AND payment gateway in list
  $order_total = (float) $order->get_total();
  $payment_method = $order->get_payment_method();

  if ($order_total <= $minimum_order_total || !in_array($payment_method, $required_gateways)) {
    return ''; // Conditions not met
  }

  // Conditions met - create ID verification check
  $result = real_id_create_check(['order_id' => $order_id]);

  if (is_wp_error($result)) {
    return '';
  }

  return $result['widget_html'];
});

Then add the shortcode [my_id_verification] to your Elementor thank-you page.

Hook-Based Integration

You can also trigger checks from WooCommerce hooks. Since hooks run in the background (not during page rendering), you must set display_widget to false:

// Trigger verification when order status changes to processing
add_action('woocommerce_order_status_processing', function($order_id) {
  $order = wc_get_order($order_id);

  // Your custom conditions
  $is_high_risk = /* your logic */;
  $is_new_customer = /* your logic */;

  // AND condition: high risk AND new customer
  if ($is_high_risk && $is_new_customer) {
    real_id_create_check([
      'order_id' => $order_id,
      'display_widget' => false  // Required for hooks - sends notification only
    ]);
  }
});

Action Hook Alternative

You can also use the real_id_trigger_check action hook:

// These are equivalent (for notification-only checks):
real_id_create_check(['order_id' => 123, 'display_widget' => false]);

do_action('real_id_trigger_check', ['order_id' => 123, 'display_widget' => false]);

Display Modes

Mode	Description	Use Case
'full'	Widget renders inline where shortcode is placed	Thank-you pages, dedicated verification pages
'modal'	Widget appears as a popup overlay	Less intrusive, doesn't interrupt page layout

Frequently Asked Questions

Will this create duplicate checks?

If a check already exists for the order, the API may return the existing check instead of creating a duplicate. However, it's best practice to check if verification is needed before calling this function.

Can I customize what the widget looks like?

Yes, the widget uses your theme settings configured in the Real ID dashboard, including colors and logo.

Does this work with the built-in automatic rules?

Yes, this function works independently of the built-in rules. You can use both:

• Built-in rules for simple OR conditions (e.g., "order over $100 OR contains alcohol")
• real_id_create_check() for complex AND conditions or custom workflows

Why isn't the widget appearing?

Make sure:

1. The Real ID plugin is activated and up to date
2. You have a valid license key configured
3. The function is called during page rendering (not in an AJAX handler or background process)
4. display_widget is true (the default)
5. Your shortcode returns $result['widget_html']