Account Unlock & 3D Verification Helper

Self‑service account recovery, challenge-response verification and 3D Secure escalation. Reduces support tickets, prevents account takeovers and bridges identity verification across payment and access layers.

Core workflows

Self‑service unlock: email verification, SMS OTP, security question recall, biometric consent (face/fingerprint if available).
3D Secure & SCA: initiate 3DS2 challenges for card payments; capture cardholder authentication via issuer app or OTP; store proof of authentication.
Multi‑factor fallback chain: if primary fails (SMS unreachable), step down to email or backup codes; never leave user locked out without escalation path.
Account recovery keys: allow users to pre‑generate one‑time backup codes during onboarding; store encrypted, rate‑limited usage.
Fraud scoring & step‑up: if login or payment risk score is high, trigger additional verification (location check, device fingerprint, CVC re‑entry).
Audit trail & consent: log every unlock attempt and verification method; track GDPR consent and allow user export of verification history.

Quick facts

Methods: Email, SMS OTP, security Q&A, backup codes, biometric

Integrations: 3DS2, payment gateways, SMS/email providers

Docs / Repo:

Architecture & security model

Stateless challenge tokens: generate short‑lived JWT tokens for each verification attempt; include session_id, challenge_type, issued_at, exp (5–10 min).
Rate limiting: per‑email, per‑phone, per‑IP limits on OTP/SMS requests (e.g., max 3 attempts per hour) to prevent brute force and SMS spam.
OTP generation: use TOTP or HOTP (RFC 6238) for time‑based or counter‑based codes; store hash (not plaintext) in transient store (Redis with TTL).
Backup code storage: encrypt with user’s derived key or HSM; store in DB with usage counter (one‑time only).
3DS2 integration: delegate to payment processor API (Stripe 3DS, Adyen, Worldpay); capture challenge response and store proof in audit log.
Device fingerprinting: optional — use browser fingerprint (TLS cert, User‑Agent, canvas fingerprint) to detect anomalous logins and suggest step‑up verification.

API examples

 # Initiate unlock challenge (POST) POST /api/v1/account/unlock/challenge Content-Type: application/json { "email": "user@example.com", "method": "email_otp", "device_fingerprint": "" }

Response:
{
  "challenge_id": "chall_abc123",
  "method": "email_otp",
  "sent_to": "us***@example.com",
  "expires_in_seconds": 600
}
Verify challenge (POST)

POST /api/v1/account/unlock/verify
Content-Type: application/json
{
  "challenge_id": "chall_abc123",
  "code": "123456"
}

Response:
{
  "status": "success",
  "unlock_token": "eyJhbGc...",
  "valid_until": "2026-02-01T13:00:00Z"
}
3DS2 initiation (via payment gateway)

POST /api/v1/payments/3ds-challenge
{
  "payment_id": "pay_xyz789",
  "amount": 10000,
  "currency": "EUR"
}

Response:
{
  "threeds_url": "https://issuer.bank.com/auth?threeds_id=...",
  "threeds_id": "Y410...",
  "method_notif_url": "https://your.app/webhooks/3ds"
}

User experience & fallback

Primary path: email OTP (fast, non‑intrusive). If user requests or risk is high, offer SMS or security questions.
Fallback chain: if email unreachable → try SMS → backup code (if pre‑generated) → contact support with verified payment method or ID scan.
UX consideration: show remaining attempts, countdown timer, and a clear “escalate to support” button with expected response time (e.g., “Support responds within 2 hours”).
Session continuity: after successful verification, issue a session token valid for 24–48 hours (configurable) so user is not re‑challenged on every action.

Operational runbook

 # Check unlock attempt history unlockctl history --email user@example.com --days 7
Manually unlock account (admin override, logged)

unlockctl admin unlock --email user@example.com --reason "support_ticket_12345"
View backup codes for user

unlockctl backup-codes list --email user@example.com
Reset 3DS settings for a payment method

unlockctl payment reset-3ds --payment-id pay_xyz789
Monitor unlock metrics

unlockctl metrics --metric unlock_attempts_per_hour --timerange 24h

Compliance & audit

PSD2 / SCA: comply with Strong Customer Authentication; log all 3DS2 challenges and cardholder authentication proof.
GDPR: provide users with downloadable export of verification attempts and consent records; allow deletion of backup codes.
PCI DSS: never log or store full card data; isolate 3DS logic to PCI-compliant environment or delegate to processor.
Audit log: every unlock, verify, and admin override is immutable; include user ID, method, timestamp, IP, success/fail reason.

Failure modes & mitigations

Email provider down: fall back to SMS or backup code immediately; alert support to check email service status.
SMS unreachable: retry with exponential backoff; offer user to change phone or use backup code instead.
3DS2 timeout: capture the timeout event and allow retry or manual review by support team within SLA (e.g., 1 hour).
Brute force: block IP after N failures; issue CAPTCHA to prevent automation; escalate repeated failures to fraud team.

The FOSS Leader in Industrial Control