Skip to main content

Troubleshooting

OTP UI Not Showing After Decline​

Checks:

  • suma_security_enable_second_failure_email is enabled
  • Failed payment threshold is reached
  • AJAX nonce is present (suma_security_checkout_otp)
  • checkout-verification.js is enqueued and loaded
  • Verification state endpoint returns requires_verification: true

Device Token Validation Unexpectedly Blocking​

Checks:

  • Hidden field suma_security_device_token exists in checkout form
  • Cookie suma_security_device_token exists and is unexpired
  • Subject hash candidates resolve for current request signals
  • DB row exists in suma_security_device_tokens

Dist JS Missing Error in Development​

If WP debug is enabled and you see missing file errors:

npm install
npm run build

Required files:

  • assets/js/dist/checkout-velocity-fingerprint.js
  • assets/js/dist/checkout-verification.js

Lock Appears Stuck​

Use Tools -> Checkout Fingerprints:

  • inspect lock details (OTP/email/velocity)
  • run Unlock action for affected fingerprint
  • retry checkout with same billing email

High False Positives​

Tune settings incrementally:

  • increase Checkout Attempts Before Block
  • reduce lock duration
  • increase OTP threshold

Then monitor lock table and logger output before further tuning.

Useful Logs​

Review WooCommerce logs for sources:

  • checkout-session-rate-limit
  • checkout-verification

These include event names, lock timing, and shortened hash markers.