Skip to main content

Checkout Security Flow

1) Signal Collection​

On checkout pages, fingerprint script collects and syncs:

  • browser UUID
  • browser fingerprint hash
  • screen resolution
  • timezone

Values are stored in both hidden fields and cookies.

2) Device Token​

During checkout route (template_redirect), plugin issues or refreshes suma_security_device_token with format:

  • token.expires_at.hmac

HMAC is bound to subject hash candidates and verified during checkout submission.

3) Checkout Gate Enforcement​

Plugin enforces gates at multiple hooks:

  • woocommerce_checkout_process
  • cfw_before_process_checkout
  • woocommerce_after_checkout_validation
  • Plus request-level block on init for locked wc-ajax=checkout posts

Gate message priority:

  1. device-token validation failure
  2. OTP verification requirement
  3. velocity lock block

4) Failed Payment Tracking​

Failed hooks call suma_security_process_failed_checkout_for_order():

  • woocommerce_order_status_changed -> failed
  • woocommerce_order_status_failed
  • woocommerce_payment_failed
  • woocommerce_suma_test_gateway_payment_declined

A short debounce transient prevents duplicate processing bursts for the same order event window.

5) OTP Lock Escalation​

When failed count reaches threshold:

  • fingerprint OTP lock transient set
  • email fallback OTP lock transient set
  • session -> fingerprint mapping stored
  • approval transient cleared
  • 6-digit code emailed

6) OTP Verification​

AJAX endpoints:

  • send code
  • verify code
  • get verification state

On successful verification:

  • OTP lock cleared
  • email lock cleared
  • failed counters reset
  • approval state set for 1 day
  • velocity lock transient cleared

7) Admin Intervention​

Tools page allows manual unlock of fingerprint state and associated velocity/OTP transients, including email lock and session-related unlock markers.