IPQualityScore¶

IPQualityScore (IPQS) provides IP reputation, email validation, and fraud scoring for checkout traffic. On each scored checkout it calls the IPQS Proxy/VPN Detection API and the Email Verification API, takes the higher of the two fraud scores, and returns an allow / review / block decision against configurable thresholds. Use it for pre-payment screening that catches proxies, VPNs, Tor exit nodes, bots, and disposable or abusive email addresses before payment is attempted.

What It Provides¶

• A FraudScoringStrategy implementation registered under the provider name ipqs (per-provider registration). The core fraud engine resolves it with channel-enablement awareness and merges its result with the core rule engine's own factors — see Fraud Scoring Extensions.
• Checkout scoring (score_checkout) — runs in the core pre-payment fraud assessment during checkout. Queries two IPQS REST endpoints:
  • Proxy/VPN Detection (/api/json/ip/...) — returns an IP fraud score plus signals: vpn, tor, proxy, bot_status, is_crawler, recent_abuse, abuse_velocity, and country code.
  • Email Verification (/api/json/email/...) — returns an email fraud score plus signals: valid, disposable, honeypot, spam_trap_score, smtp_score, recent_abuse, leaked, and suspect.
• Login scoring (score_login) — the same combined IP + email check, implemented on the strategy interface.
• Decision mapping — the higher of the IP and email fraud scores (IPQS 0–100 scale) is compared against the thresholds: at or above block_threshold the decision is block, at or above review_threshold it is review, otherwise allow. The score is also normalized to the platform's 0–1 risk scale.

Setup¶

1. Enable IPQualityScore for the channel under Settings > Extensions (extension enablement is per-channel).
2. Provide the API key from your IPQS dashboard. api_key is a secret config field (encrypted at rest and masked in the admin); the strategy factory also falls back to the IPQS_API_KEY environment variable — see the credential-resolution note under Operational Notes.
3. Adjust strictness, review_threshold, and block_threshold to match your risk tolerance.

Configuration Reference¶

Permissions¶

This extension declares no permissions in its manifest.

Operational Notes¶

• Fail-open — with no API key configured the strategy returns allow with score 0. A failed IP or email lookup is logged as a warning and that sub-score is treated as 0; checkout is never aborted by a provider outage. HTTP calls use a 10-second timeout.
• Pre-payment only — IPQS implements checkout and login scoring; the post-payment hook returns the interface default (allow). For post-authorization guarantee decisions, see Signifyd or Riskified.
• Merged scoring — the extension score is combined with the core rule engine (blocklist, velocity, address checks); the merged result records its provider as core+ipqs. A pre-payment block decision aborts checkout with "Order blocked by fraud detection".
• One provider per channel — if more than one fraud extension is enabled on a channel, checkout logs a warning and uses the alphabetically-first provider name.
• IP check parameters — requests send your configured strictness with allow_public_access_points=true and lighter_penalties=false, and include the shopper's user agent when available.