Advanced Usage with WordPress Plugin

The ALTCHA WordPress plugin automatically protects your site right after installation, with no extra setup required.

This guide covers advanced topics and custom integrations for developers and power users who want more control.

Disabling ALTCHA for Certain Plugins

By default, ALTCHA protects all non-viewer requests (e.g., POST requests). This may cause issues with some plugins that use Ajax requests on the front end, such as cookie banners, notifications, or certain form plugins.

If you need to disable ALTCHA for a specific plugin, you can exclude the plugin’s Ajax paths or actions under Settings, for example:

• If the plugin uses a REST API endpoint such as /wp-json/some-plugin/submit, add the following to the Paths: !/wp-json/some-plugin/submit — or to exclude all of the plugin’s requests: !/wp-json/some-plugin/*
• If the plugin uses admin-ajax.php, add the Ajax action name to Actions: !action_name

Alternatively, if you only want to protect selected forms and actions on your website, modify the Actions definition by removing the wildcard * (which matches all actions) and listing only the ones you want to protect.

For configuration examples, see Special Plugin Configuration.

Shortcode

In most cases, it’s best to rely on the automatic Request Interceptor, which works without any configuration.

However, if you prefer, you can manually add the ALTCHA widget to your forms using a shortcode:

[altcha]

Shortcode attributes are also supported. See the ALTCHA Widget configuration options:

[altcha floating auto="onload"]

Custom Handlers

With the automatic Request Interceptor, server-side verification is handled seamlessly—no code changes required.

For custom form handlers, you can work directly with the AltchaPlugin class:

$altcha = AltchaPlugin::$instance;
$params = array();
$verified = $altcha->verify($payload, $params);

• $payload: the base64-encoded ALTCHA payload.
• $params: automatically populated with additional parameters from the salt.

When using ALTCHA Sentinel, verification data is available via:

• $params["verification_data"]
• or $altcha->verification_data (parsed into an associative array of key-value pairs).

Hooks

The plugin provides several actions and filters for customization.

Actions

altcha_verify_result

do_action("altcha_verify_result", $verified);

Triggered after ALTCHA verification.

• $verified (boolean): whether the verification succeeded.

Filters

altcha_get_complexity

apply_filters("altcha_get_complexity", $result);

Called in get_complexity(). Allows modification of the challenge’s min/max numbers.

• $result (array): array("max" => 0, "min" => 0)

---

altcha_get_challenge_url

apply_filters("altcha_get_challenge_url", $challenge_url);

Called in get_challenge_url(). Can override the widget’s challenge URL.

• $challenge_url (string)

---

altcha_get_ip_address

apply_filters("altcha_get_ip_address", $ip);

Called in altcha_get_ip_address(). Can override the user’s IP address.

• $ip (string)

---

altcha_get_ip_country

apply_filters("altcha_get_ip_country", null, $ip);

Called in altcha_get_ip_country(). Can override the detected country code.

The get_ip_country function returns null by default, as no IP resolution mechanism is included. You can use the altcha_get_ip_country filter to enable more accurate geolocation based on the user’s IP address instead of their timezone. See Country Detection for more details.

• $result (string|null): 2-letter ISO code
• $ip (string)

---

altcha_get_widget_attrs

apply_filters("altcha_get_widget_attrs", $attrs);

Called in get_widget_attrs(). Can override widget attributes.

• $attrs (array)

---

altcha_get_widget_html

apply_filters("altcha_get_widget_html", $html, $attrs, $wrap);

Called in get_widget_html(). Can modify the widget’s HTML.

• $html (string)
• $attrs (array)
• $wrap (boolean)

---

altcha_intercept

apply_filters("altcha_intercept", $intercept, $payload_data, $params);

Called in the interceptor. Returning false disables interception (verification not required).

• $intercept (boolean): defaults to true
• $payload_data (array): parsed ALTCHA payload
• $params (array): additional parameters from the challenge salt

Plugin Integrations

Thanks to the Request Interceptor, ALTCHA works automatically with most form plugins — no setup required. The widget is displayed as an overlay or invisibly in the background.

The plugin has been tested with several popular plugins, but works many others:

• CoBlocks
• Contact Form 7
• Elementor Pro
• Formidable Forms
• Forminator
• Fluent Forms
• Gravity Forms
• HTML Forms
• MetForm
• Ninja Forms
• WooCommerce
• WP-Members
• wpDiscuz
• WPForms
• WordPress Comments
• WordPress Login, Register, and Password Reset

Some plugins also include additional integrations for direct widget placement:

• Elementor Pro: adds a dedicated widget field.
• Formidable Forms: adds a dedicated widget field.
• Gravity Forms: adds a dedicated widget field and stores submissions flagged as spam (Sentinel only).

Special Configuration

Some plugins require special configuration to ensure they work correctly with ALTCHA. This usually involves disabling specific actions or paths that use Ajax requests.

The following configuration is applied by default if these plugins are detected during ALTCHA activation. To customize it, adjust the Actions and/or Paths under Settings.

• Forminator

  • !forminator_get_nonce: Excludes the action used for fetching a new nonce.

• Elementor Pro

  • !elementor_js_log: Elementor performs Ajax logging; whitelist this action.

• MetForm

  • !/wp-json/metform/v1/forms/views/*: Excludes MetForm’s statistics path.

• Real Cookie Banner

  • !/wp-json/real-cookie-banner/v1/consent: Excludes the main cookie consent Ajax path.
  • !/wp-json/*/consent: Excludes cookie consent Ajax paths (RCB may also use randomly generated paths).

• WooCommerce

  • !wc-ajax=*: Excludes all WooCommerce Ajax actions.
  • !*_wc_privacy_cleanup: Excludes internal “cleanup” actions.
  • /wp-json/wc/store/v1/checkout: Protects the checkout path.
  • !/wp-json/wc/store/v1/*: Excludes all other WooCommerce Ajax paths.

• Wordfence

  • !wordfence_ls_authenticate: Excludes 2FA verification Ajax action.

• wpDiscuz

  • !wpdCheckNotificationType: Excludes the wpDiscuz notification action triggered after submitting a comment.

Country Detection

The plugin determines the user’s country based on their timezone, as reported during the verification process. This method provides reliable, privacy-friendly geolocation without relying on any IP address resolution service.

Geolocation data is used for event logging and firewall request blocking.

For more precise geolocation, you can use the altcha_get_ip_country filter to implement your own IP resolution logic or integrate with another plugin’s API.

Cookies and GDPR

The ALTCHA for WordPress plugin utilizes only strictly necessary, first-party cookies that are essential for the proper operation of the website and its security mechanisms. These cookies are used solely for technical and security-related purposes and do not involve user profiling, behavioral tracking, or cross-site data sharing. No personally identifiable information (PII) is stored or processed through these cookies.

In accordance with Article 6(1)(f) of the General Data Protection Regulation (GDPR), the use of such cookies is based on the legitimate interest of the website operator to ensure the security, integrity, and reliable operation of online forms and web access.

Essential Security Cookie:

• altcha: A single-use, functional cookie required for validating legitimate form submissions and preventing spam or automated abuse. This cookie is transient and does not contain any personal data.

Temporary Protection Cookies (used only when “Under Attack Mode” is enabled):

• altcha_under_attack: A session-based cookie used to temporarily manage access during periods of increased malicious activity or automated attacks.
• altcha_under_attack_expires: A session cookie that records the expiration timestamp of the altcha_under_attack cookie.
• altcha_under_attack_ttl: A session cookie that records the lifespan (time-to-live) of the altcha_under_attack cookie.
• altcha_under_attack_tz: A session cookie that stores the user’s timezone, used exclusively for low-precision country detection.

All cookies set by ALTCHA:

• Are first-party and stored exclusively on the user’s device by the website domain;
• Are strictly necessary for the operation and security of the website;
• Are temporary and automatically expire after their intended security purpose is fulfilled;
• Do not collect, transmit, or process personal or behavioral data;
• Are therefore exempt from the consent requirement under Article 5(3) of the ePrivacy Directive (Directive 2002/58/EC, as amended).

For full transparency, it is recommended to disclose the above information in your website’s Privacy Policy under the section describing the use of cookies and security measures. Since these cookies are strictly necessary for the website’s security and functionality, they are exempt from the consent requirement under the ePrivacy Directive and GDPR. Therefore, a cookie banner or consent notice is not required, provided that no other non-essential cookies (such as analytics or marketing cookies) are used on the website.