Programmatic integration

Use the browser API when verification must start from your own submit button, modal, or multi-step flow. This is required for Invisible mode.

Use an existing component

<humanpass-widget
  id="humanpass"
  data-humanpass-sitekey="hp_site_live_REPLACE_ME"
  data-humanpass-action="checkout"
></humanpass-widget>

<button id="pay">Pay now</button>

const widget = document.querySelector("#humanpass");
const button = document.querySelector("#pay");

button.addEventListener("click", async () => {
  button.disabled = true;

  try {
    const { token } = await widget.solve();
    await submitCheckout({ humanpassToken: token });
  } catch {
    showVerificationError();
    widget.reset();
  } finally {
    button.disabled = false;
  }
});

Create a controller

After loading the widget script, window.HumanPass can create and control a component:

const humanpass = new window.HumanPass({
  sitekey: "hp_site_live_REPLACE_ME",
  action: "checkout",
});

humanpass.addEventListener("progress", (event) => {
  updateProgress(event.detail.progress);
});

const { token } = await humanpass.solve();

Reset after application errors

If your application rejects the request before the response is consumed, reset the widget before another attempt:

humanpass.reset("application-retry");

If your backend has already attempted verification, assume the response may be consumed and always obtain a fresh one.

Avoid duplicate solves

• Disable the initiating button while solve() is pending.
• Do not share one controller between unrelated actions.
• Submit the token immediately after it is produced.
• Handle expire, reset, and error events in your UI.