SnapAgree

Live Draft Composer

Auto-transcribes your call and turns commitments into clean clauses—scope, deliverables, timelines, and pricing—using intent detection. Pre-fills client details from the calendar invite, highlights missing pieces, and assembles a plain-language draft as you speak, so you stay present while the contract writes itself.

Requirements

Real-time Transcription & Speaker Diarization

"As a service provider, I want my calls transcribed in real time with who-said-what labeling so that I can capture commitments accurately without taking notes and missing details."

Description

Continuously capture and transcribe meeting audio with sub‑second latency, accurate punctuation, timestamps, and speaker attribution, optimized for accented English and variable network conditions. Support input from system microphone and connectors for Zoom, Google Meet, and Teams. Provide confidence scores, automatic filler-word removal, smart punctuation, and optional on-device noise suppression. Maintain rolling buffers for resilience, auto-reconnect on drops, and encrypt audio/transcript in transit and at rest. Expose a streaming API to downstream NLP, persist transcript segments with offsets, and enable configurable PII redaction and retention windows.

Acceptance Criteria

Sub-Second Real-Time Transcription Latency

Given a live meeting audio stream from any supported source When audio is continuously received Then partial transcript updates are emitted with end-to-end latency <= 800 ms at P95 And final transcript for each utterance is emitted within 2.5 s after voice activity end at P95 And each token/word carries a timestamp with absolute error <= 100 ms at P95 versus ground-truth alignment And punctuation appears no later than the final emission for the utterance

Accurate Speaker Diarization and Timestamps

Given a conversation with 2–5 participants including overlapping speech under 10% When diarization runs in real time Then diarization error rate (DER) <= 12% at P95 on an accented-English evaluation set And speaker turns are labeled consistently as Speaker 1..N within the session (no relabeling drift > 1% of segments) And each emitted segment includes speaker_id, start_ms, end_ms, and is_final And sentence-level punctuation is present in final segments with correct capitalization

Network Resilience with Rolling Buffers and Auto-Reconnect

Given simulated network impairment of 10% packet loss, 200 ms jitter, and up to 5 s connection drops When the upstream connection drops and recovers Then the client auto-reconnects within 3 s of connectivity restoration at P95 And no more than 1 duplicate final segment is re-emitted per segment_id after reconnection And rolling buffers ensure no gaps > 2 s in the final transcript; missing audio during drops is backfilled upon reconnection if the source supports it And latency P95 under impairment remains <= 1500 ms for partials and <= 4 s for finals

Multi-Source Audio Input: Mic, Zoom, Meet, Teams

Given a user selects a source: System Microphone, Zoom, Google Meet, or Microsoft Teams When a session starts Then audio is ingested at 16 kHz mono (or resampled with <= 0.5% drift) with supported codecs (PCM16/Opus) And meeting metadata (meeting_id, participant_ids) is captured for connector sources And transcription begins within 2 s of session start at P95 And switching between sources during a session occurs without process restart and with no data loss > 2 s

Confidence Scores, Filler Removal, and Smart Punctuation

Given real-time transcription with post-processing enabled When filler-word removal is ON with default list ["um", "uh", "like" (discourse use), "you know", "I mean"] Then the cleaned transcript excludes those fillers while the raw transcript retains them; both variants are available in stream and persistence And word-level confidence scores in [0,1] are included; utterance-level confidence equals the geometric mean of word confidences And on an accented-English benchmark, word error rate (WER) <= 12% at P50 and <= 18% at P90 for the cleaned transcript And smart punctuation inserts sentence-final punctuation (.?!), commas, and capitalization with F1 >= 0.90 vs. reference on the benchmark

Security, Encryption, PII Redaction, and Retention

Given audio and transcript data flow through the system When data transits networks or is persisted Then transport uses TLS 1.2+ and data at rest is encrypted with AES-256; keys are managed via KMS with 90-day rotation And configurable PII redaction rules (email, phone, SSN, credit card, address) applied server-side redact in-stream and at-rest fields when enabled; redacted tokens are replaced with entity type tags (e.g., [EMAIL]) And retention windows are configurable per workspace (1–365 days; default 30); expired items are hard-deleted within 24 h and deletions are logged with audit entries (who, when, what) immutable for 1 year And all connectors use OAuth 2.0 with least-privilege scopes; tokens are stored encrypted and rotated per provider guidelines

Streaming API and Persistent Segments with Offsets

Given a downstream NLP service subscribes to the streaming API When a transcription session is active Then a WebSocket and gRPC stream are available that emit messages with schema {segment_id, offset_ms, speaker_id, text_raw, text_clean, confidence, is_partial, is_final, redaction_applied, created_at} And messages are delivered in order by offset_ms with no overlapping ranges; back-pressure is supported via flow control or ACK And final segments are delivered to subscribers within 500 ms of finalization at P95 And persisted segments can be replayed by time range or offset range within the retention window; replays are idempotent via segment_id

Intent Detection & Clause Mapping

"As a freelancer, I want the system to recognize and structure commitments as we speak so that the right contract fields are populated without manual data entry."

Description

Analyze live transcript tokens to detect commitments and intents—scope, deliverables, milestones, timelines, pricing, change orders, payment terms, IP ownership, warranties, termination, and confidentiality—extracting entities (quantities, dates, amounts, parties) and mapping them to a structured contract schema. Maintain provenance links from each extracted field to transcript spans, apply confidence thresholds and conflict resolution rules, and surface ambiguities for review. Support incremental updates as speech arrives, multilingual date/number normalization, and domain-tunable models per service type. Provide audit logs of model decisions and a review queue for low-confidence items.

Acceptance Criteria

Real-Time Incremental Intent Mapping

Given a live English sales call containing commitments for scope, deliverables, milestones, timelines, pricing, change orders, payment terms, IP ownership, warranties, termination, and confidentiality When partial transcript tokens stream in at normal speech rates Then mapped schema fields update within 500 ms p95 from token receipt And macro F1 ≥ 0.85 across the listed intent types on a held-out annotated evaluation set And once a field’s confidence exceeds 0.85, its value changes at most once unless a new contradictory mention arrives with confidence ≥ prior + 0.05 And partial-field values are marked as provisional until confidence ≥ 0.8

Entity Extraction and Multilingual Normalization

Given transcripts containing dates, amounts (with or without currency symbols), quantities, and party names in English and Spanish When entities are extracted Then dates are normalized to ISO-8601 with timezone inference rules applied where stated, with ≥ 98% normalization accuracy on the evaluation set And amounts are normalized to decimal with detected currency (ISO 4217) with ≥ 98% normalization accuracy and ≥ 95% currency detection accuracy And numbers expressed in words are converted to numerals correctly ≥ 98% of the time And party names are consistently canonicalized (exact string match to contact or invitee) ≥ 97% of the time

Provenance Links to Transcript Spans

Given any extracted or mapped contract field value When the user inspects the field Then a provenance link shows the exact transcript span(s) and timestamps that support the value And 100% of mapped fields retain start/end character indices and word-level timecodes And clicking a link highlights the correct text and seeks playback to within ±250 ms of the supporting audio And composite values maintain multiple span links with correct ordering

Confidence Thresholding and Conflict Resolution

Given multiple mentions that produce conflicting values for the same field When confidence scores are computed Then the system auto-commits the value with confidence ≥ 0.8 and highest score And if the top two values are within 0.05 confidence, prefer the latest mention by timestamp And if no value ≥ 0.8, do not auto-commit; create a review item with all candidates and rationales And every resolution decision is recorded with the rule applied in the audit log

Low-Confidence Review Queue and Ambiguity Surfacing

Given any field candidate with confidence < 0.8 or an unresolved conflict When the pipeline produces the candidate Then an item appears in the reviewer queue within 1 s with highlighted spans, top-3 alternatives, and reasons And the contract draft shows an “Ambiguity” badge for affected sections until resolution And reviewer accept/override applies to the schema within 500 ms and clears the badge And 100% of low-confidence items are represented in the review queue (no drops)

Domain-Tunable Models by Service Type

Given the user selects a service type profile (e.g., Web Design, Coaching, Marketing) When a call is processed Then the corresponding domain model/config is applied and recorded (model_id, version) in session metadata And on the domain evaluation set, F1 for scope/deliverables improves by ≥ 0.05 absolute over the generic baseline And switching service type mid-call applies the new domain config within 2 s without clearing previously mapped fields And the selected domain persists to the assembled contract metadata

Model Decision Audit Logging and Export

Given any prediction, update, threshold decision, conflict resolution, or reviewer action When the event occurs Then an immutable audit record is written containing timestamp, session_id, actor/model_id+version, input span ids, field path, prior value, new value, confidence, and rule applied And 100% of mapping actions have corresponding audit records And audit logs are queryable within 2 s and exportable as JSONL for the session And logs are retained for ≥ 90 days with access controlled by role

Live Draft Assembly Engine

"As a small-business owner, I want the contract to assemble itself during the call so that I can stay present in the conversation and finish with a ready-to-review draft."

Description

Assemble a plain‑language contract draft in real time from a modular template library using structured data from intent detection and calendar autofill. Continuously update clause blocks (scope, deliverables, timeline, pricing, payment terms) as new information is confirmed, while inserting placeholders for unknowns. Enforce brand voice and reading-level constraints, include dynamic risk flags per clause, and generate a change log of how the draft evolved during the call. Support service-type templates, locale-aware formatting, and idempotent regeneration on transcript edits. Output to the inline editor with versioning and export to PDF/Docx when finalized.

Acceptance Criteria

Real-Time Assembly from Intents & Calendar Autofill

Given a scheduled call with a calendar invite containing client name, company, email, timezone, and service type When the call starts and intent detection emits structured data for scope, deliverables, timeline, pricing, and payment terms Then the engine selects the correct service-type template and assembles an initial draft within 2 seconds populated with available client details and clause blocks And then locale-aware formatting (dates, currency, numbers) matches the invite's locale/timezone (e.g., en-US MM/DD/YYYY, $1,234.56; en-GB DD/MM/YYYY, £1,234.56) And then all populated fields reflect the latest structured values with no conflicting duplicates

Continuous Clause Updates with Confirmation State & Missing Pieces Highlighting

Given a clause block exists in the draft When new or updated structured data for that clause is confirmed by the user or high-confidence intent (>0.90) Then the clause updates in place within 1 second, preserving stable clause IDs and change history And when required fields are unknown Then placeholders with clear labels (e.g., [Start Date], [Milestone 2 Deliverable]) are inserted and visually highlighted in the editor And then a Missing Pieces panel lists unresolved placeholders with counts and deep links to each clause

Brand Voice and Reading-Level Enforcement

Given the brand voice guide and a target reading level of Grade 8 ±1 are configured When the draft is assembled or updated Then the text passes automated checks: Flesch-Kincaid grade ≤ 9 and no forbidden terms from the style guide And then passive voice ratio ≤ 15% and sentences > 30 words constitute ≤ 10% of sentences And when violations occur Then the engine auto-rewrites to comply while preserving legal intent, and flags any unfixable items for manual review

Per-Clause Dynamic Risk Flags

Given risk rules are configured When a clause contains terms matching a risk rule Then a risk flag appears inline with severity (Low/Medium/High), rationale, and suggested safer alternative And then risk flags are filterable by severity and exportable as a summary And when a flagged term is removed or mitigated Then the risk flag resolves automatically

Change Log of Draft Evolution

Given the call is in progress When any clause content changes Then an entry is appended to the change log with timestamp (UTC), source (Intent Detection, Calendar Autofill, User Edit), clause ID, before/after diff, and actor And then the change log can be filtered by clause and exported as JSON and CSV And when the session ends Then the final change log is immutable and versioned with the draft

Idempotent Regeneration on Transcript Edits

Given a transcript edit is applied that does not change the structured data When the draft is regenerated Then the clause texts remain byte-identical and clause IDs are unchanged And given identical structured inputs and template version When regeneration occurs multiple times Then the output is deterministic with no duplicate clauses or order changes And when structured data changes Then only affected clauses update; unaffected clauses remain unchanged

Inline Editor Output, Versioning, and Final Export

Given the draft is assembled When opened in the inline editor Then clauses are editable with tracked changes and version numbers (v1, v2, ...), and each save creates a new version snapshot And when the draft is marked Final Then a locked version is created and can be exported to PDF and DOCX within 5 seconds with preserved formatting, headers, and risk flag annotations (optional include/exclude) And then the exported files pass a checksum and include document metadata (title, client, date, version, locale)

Calendar & CRM Autofill

"As a consultant, I want client details auto-filled from my calendar invite so that I don’t waste time typing names and emails into the contract."

Description

Ingest attendee and meeting metadata from Google and Outlook calendars to pre‑fill party names, emails, company, meeting title, and time zone into the contract draft. Match or create contacts in the internal CRM, deduplicate based on email and domain, and map fields to contract parties. Handle missing or ambiguous invite data with guided prompts. Provide OAuth-based authentication, granular permission scopes, and user-controlled linking/unlinking per meeting. Respect privacy settings and do not write back to calendar without explicit consent.

Acceptance Criteria

OAuth Connection with Granular Read-Only Scopes (Google & Outlook)

Given a user initiates a Google or Outlook calendar connection When the OAuth consent screen is displayed Then only read-only calendar scopes are requested and no write scopes are requested Given OAuth completes successfully When credentials are stored Then access and refresh tokens are encrypted at rest and tied to the user account Given a calendar is connected When the user opens Connected Apps Then the provider and the exact granted scopes are displayed Given the user revokes access at the provider or in SnapAgree When SnapAgree next requests calendar data Then a re-authentication prompt is shown and no calendar data is ingested until reconnected

Autofill Party & Event Fields from Calendar Invite (Single External Attendee)

Given a calendar event where the SnapAgree user is the organizer and exactly one external attendee exists When Live Draft Composer starts for that event Then the draft pre-fills Client party name, email, company (from CRM match or attendee domain), engagement title (from event title), and event time zone into contract metadata within 3 seconds Given fields are autofilled from the calendar When the draft is displayed Then those fields are visually indicated as Autofilled and are editable by the user

CRM Match/Create and Deduplication

Given the CRM contains a contact whose primary email equals the attendee email (case-insensitive) When autofill runs Then that contact is matched and linked to the draft without creating a new contact Given no exact email match exists but exactly one contact shares the attendee email domain and the same display name When autofill runs Then that contact is linked; otherwise a new contact is created with the attendee’s name, email, and inferred company Given a new contact is created When the CRM is queried by email Then only one contact record exists for that email Given duplicate contacts already exist When autofill runs Then the attendee is linked to the oldest active contact and no additional duplicates are created

Guided Prompts for Missing or Ambiguous Invite Data

Given multiple external attendees or missing company information is detected When autofill runs Then the user is prompted to select the Client party and to confirm or enter the company before draft creation proceeds Given the user completes the prompt When the draft is generated Then the selected values populate the draft and update/create the CRM contact accordingly Given the user dismisses or skips the prompt without completing required selections When draft creation is attempted Then the draft is not created and a clear actionable message explains what is needed

Per-Meeting Linking and Unlinking Controls

Given an event is linked to a draft When the user toggles Link this event for autofill off Then no further calendar data is pulled for that draft and the event–draft link is removed without deleting any CRM contact Given the link toggle is off When the user toggles it on Then the event re-links and autofill is available again Given a draft with a linked CRM contact When the user selects Unlink contact Then the draft retains current field values while removing the CRM association

Privacy Respect and No Write-Back Without Explicit Consent

Given a calendar event is marked Private or has limited visibility When autofill runs Then only provider-permitted metadata (e.g., start/end time, title, attendee emails) is ingested and event body/attachments are not stored Given the user has not explicitly enabled Write back to calendar When using Live Draft Composer Then SnapAgree does not create, update, or delete any calendar events Given the user enables Write back to calendar and provides explicit consent When a calendar write occurs Then an audit log records the action, affected event ID, user, and timestamp

Time Zone Detection and Contract Mapping

Given an event with a specific IANA time zone When the draft is generated Then all contract date/time fields use that time zone and the IANA identifier is stored in draft metadata Given the user’s account has a different default time zone than the event When viewing the draft Then times display in the event’s time zone with a tooltip showing the user’s local time conversion Given the event lacks an explicit time zone When the draft is generated Then the user’s account time zone is used and the user is prompted to confirm the client’s time zone before sending

Missing Info Detector & Live Prompter

"As a project lead, I want the system to tell me what’s missing and suggest what to ask so that important terms don’t get overlooked during the call."

Description

Continuously evaluate the draft for completeness against business rules (e.g., payment schedule, acceptance criteria, revision limits, change request process, late fees) and highlight gaps. Surface discreet live prompts with suggested questions to ask next, plus quick‑fill chips to confirm defaults. Support a private ‘whisper’ mode that shows prompts only to the user, and a form fallback to manually enter values. Track resolution state for each missing item, prevent finalization while critical gaps remain, and record rationales for accepted defaults.

Acceptance Criteria

Auto-Detection of Critical Missing Terms

Given a live draft is created or updated When any of the following required terms are missing or incomplete: payment schedule, acceptance criteria, revision limits, change request process, late fees, client legal entity Then the system flags each gap within 2 seconds of the change, assigns severity (Critical/Non-critical) per rules, highlights the gap inline, and updates a gap counter And each gap is created as a unique, addressable item with type, severity, and detected evidence And on the standard test corpus, gap detection achieves precision >= 95% and recall >= 90% for Critical terms

Contextual Live Prompts and Suggested Questions

Given a gap is detected during an active call in Live Draft Composer When a prompt is generated Then a discreet prompt appears within 1 second containing: one recommended question (<= 140 chars), up to 3 quick-fill chips including a default, and a 'Form' option And no more than one prompt is visible at a time; additional prompts are queued and accessible via a prompt tray And prompts auto-dismiss immediately when the underlying gap is resolved

Quick-Fill Defaults with Rationale Capture

Given quick-fill chips are shown for a gap When the user selects a default for a Critical gap Then the system requires a rationale (min 10 characters), records user ID and timestamp, and marks the gap 'Resolved by Default' And for Non-critical gaps, rationale is optional; if provided, it is stored And all rationales are persisted with the draft and exportable via audit log

Whisper Mode Privacy

Given Whisper Mode is ON When prompts are generated Then prompts are visible only to the authenticated user, are excluded from shared screens/guest views/recordings, and play no sounds And a 'Whisper' indicator is shown only to the user And toggling Whisper OFF resumes standard prompt visibility without exposing prior private prompts to others

Manual Form Fallback

Given a gap exists When the user chooses 'Form' from a prompt or gap list Then a structured form opens with fields scoped to the gap type, client-side validation, and inline help And saving valid input resolves the gap as 'Resolved by Value' and suppresses related prompts And canceling or invalid input leaves the gap unresolved and displays validation errors (including screen-reader announcements)

Resolution Tracking and Finalization Gate

Given any gaps exist When the user attempts to finalize the contract Then finalization is blocked while any Critical gaps are not resolved (by Value or by Default), and a banner lists blockers with deep links And Non-critical gaps permit finalization after an explicit confirmation, with each unresolved Non-critical gap logged And the gap list supports filtering by state and severity and displays resolution timestamps

Calendar Pre-fill and Gap Sync

Given a draft is started from a connected calendar invite When client details (name, organization, email) are present in the invite Then the system pre-fills matching contract fields with a confidence score and marks them 'Proposed' until confirmed And confirming a pre-fill clears related gaps; rejecting it leaves/creates gaps And if invite data changes before finalization, the user is prompted to review the deltas; conflicts do not overwrite confirmed values without consent

Inline Clause Editor with Risk Flags

"As a business owner, I want to review and tweak suggested clauses with clear risk guidance so that I can finalize a fair, plain-language contract confidently."

Description

Provide an inline, block-based editor that displays AI-suggested clauses with plain‑language risk flags and rationales. Allow users to accept, edit, or replace clauses, with track changes, version history, and one-click revert to template defaults. Show provenance links to the transcript for each clause and recalculate risk as text changes. Enforce style and readability constraints, support snippet reuse across contracts, and maintain an audit trail of edits with user attribution.

Acceptance Criteria

Accept AI-Suggested Clause with Risk Flags

Given an AI-suggested clause is rendered as an inline block in the editor Then the block displays clause text, a risk level badge (Low/Medium/High), and a plain-language rationale accessible on hover or click And Accept, Edit, and Replace actions are visible and enabled When the user clicks Accept Then the clause state changes to Accepted and is persisted to storage And the user ID and UTC timestamp are recorded in the audit trail entry for acceptance And the block stops receiving auto-overwrites from new AI suggestions And the risk badge and rationale remain visible in read mode And the accepted state persists after save and reload And initial render of the clause block completes within 500 ms at P95 on desktop

Edit Clause with Real-Time Risk Recalculation

Given a clause block is in Edit mode When the user stops typing for 500 ms or blurs the field Then the risk score is recalculated and the badge and rationale update within 800 ms at P95 And the prior risk level is indicated as a delta until dismissed When the recalculated risk level is High Then an inline warning banner is displayed with a link to mitigation suggestions When the risk service is unreachable Then a "Risk pending" state is shown within 100 ms, retries occur with exponential backoff up to 3 attempts within 10 s, and no stale risk is displayed as current

Replace Clause and One-Click Revert to Template Default

Given a clause block is selected When the user clicks Replace and chooses a template clause from the library Then the existing text is replaced, and track changes records the substitution with before/after text And the source is set to Template with template name and version And risk is recalculated and displayed within 800 ms at P95 And a Revert to Template Default control becomes available When the user clicks Revert to Template Default Then the block text exactly matches the current default template for the contract type and locale (byte-for-byte) And track changes records the revert action with user ID and timestamp And risk recalculation occurs and updates the badge and rationale

Track Changes, Version History, and Restore

Given track changes is enabled When any insertion, deletion, or replacement is made to a clause Then the change is visually marked inline with per-user color, user ID, and UTC timestamp And the change is recorded in the audit trail with a unique change ID When the user opens Version History for the clause Then a list of versions with timestamps, editor, and summary diff is shown When the user selects a prior version and clicks Restore Then the clause content reverts to that version within 500 ms at P95 And a new version is created capturing the restore action with attribution And risk is recalculated and displayed within 800 ms at P95

Transcript Provenance Links per Clause

Given a clause block has mapped transcript segments Then a provenance icon shows the count of linked segments When the user clicks the provenance icon Then a side panel opens listing each link with speaker, timestamp, and a 1–2 sentence excerpt When the user clicks a link Then the transcript view jumps to the timestamp (±2 s) and highlights the segment within 300 ms at P95 When a clause has no mapped segments Then the provenance icon indicates "No transcript" and an Add Link action is available When clause text changes by more than 20% Levenshtein distance Then the user is prompted to confirm, update, or remove existing provenance links

Enforce Style and Readability Constraints

Given organization style rules and readability targets are configured When a clause is edited Then inline validations highlight violations (e.g., undefined terms, sentence length > 30 words, passive voice) within 300 ms at P95 And a readability score is shown and must be Grade 9 or lower to mark the clause as Ready When the user attempts to finalize a contract with Critical violations Then finalization is blocked until violations are fixed or an override reason (minimum 10 characters) is entered And any override is recorded in the audit trail with user ID, timestamp, and rule IDs When the user clicks Apply Suggestions Then auto-fixes are applied to non-critical style issues and recorded in track changes

Reusable Snippets with Audit Trail and Attribution

Given the user selects a clause block When the user clicks Save as Snippet and provides a title and tags Then the snippet is created with a unique ID and appears in library search within 200 ms at P95 When the user inserts the snippet into another contract Then a clause block is created with the snippet content, risk is recalculated within 800 ms at P95, and the audit trail records snippet ID, source contract ID, user ID, and timestamp When the inserted snippet is edited locally Then the block becomes decoupled from the source snippet (no auto-sync), while retaining reference metadata in the audit trail And all edits include user attribution in track changes

Consent & Privacy Compliance

"As a responsible operator, I want clear consent and privacy controls so that I can record and draft contracts without violating trust or regulations."

Description

Obtain and record participant consent for transcription with an on-screen banner and optional audio notice, storing time-stamped consent artifacts. Provide configurable data retention, export, and deletion controls; encryption at rest and in transit; role-based access; and automatic redaction of sensitive identifiers when enabled. Offer regional data residency options and admin policies to restrict recording or external sharing. Display clear indicators when recording is active and halt processing if consent is withdrawn.

Acceptance Criteria

Pre-Call Consent Banner and Audio Notice

Given a meeting starts, When participants join, Then an on-screen consent banner is displayed to every participant before any transcription begins. Given the consent banner is displayed, When a participant clicks “Agree,” Then their consent is recorded with meeting ID, participant ID, timestamp (UTC), and notice version hash. Given admin has enabled audio notice, When the host initiates recording, Then a standardized audio notice plays within 5 seconds to all connected participants. Given audio notice is enabled, When a participant verbally states consent (e.g., “I agree to recording”) with STT confidence ≥ 0.90 within 30 seconds, Then their consent is recorded and linked to the audio snippet timestamp. Given any participant has not consented, When the host attempts to start transcription, Then transcription is blocked and the UI lists non-consenting participants. Given a participant joins late, When they enter the call, Then the consent banner is shown and their audio is excluded from transcription until consent is given.

Recording Active Indicators

Given transcription is active, When any participant views the call UI, Then a persistent visual indicator (red dot and “Transcribing”) is visible to all participants. Given transcription is paused or stopped, When the call UI is displayed, Then the indicator reflects “Paused” or is removed within 2 seconds. Given accessibility requirements, When the indicator renders, Then it meets WCAG 2.1 AA contrast and exposes aria-label “Transcribing” and a live region update. Given clients on web, desktop, and mobile, When transcription is active, Then the indicator is shown consistently across platforms with the same status text.

Consent Withdrawal Mid-Call

Given a participant has previously consented, When they click “Withdraw consent” or issue the voice command “Stop recording my audio” and confirm in the UI, Then transcription and processing stop for the entire call within 5 seconds. Given processing is halted due to withdrawal, When the host attempts to resume, Then the system requires re-consent from all participants before transcription can restart. Given consent was withdrawn, When new audio is received, Then it is neither stored nor processed until consent is re-established. Given withdrawal occurred, When the meeting ends, Then a withdrawal event with timestamp, actor, and meeting ID is present in the audit log.

Consent Artifact Storage and Audit Log

Given a consent action occurs (agree, decline, withdraw), When the event is persisted, Then an immutable artifact is stored with meeting ID, participant ID, status, UTC timestamp, source (banner/audio), notice text hash, and IP/user-agent when available. Given a Compliance Manager views a meeting, When they open the Compliance Console, Then they see a read-only consent timeline and can download signed JSON/PDF artifacts. Given consent artifacts have their own retention rule, When other meeting data expires, Then consent artifacts remain for the configured compliance period and are exportable. Given an export request for consent artifacts, When processed, Then the export completes within 10 seconds for meetings under 4 hours and includes an integrity checksum.

Data Retention, Export, and Deletion Controls

Given workspace retention is set to N days, When a transcript/audio reaches end-of-life, Then the system purges it within 24 hours and logs a deletion event. Given an admin requests an export for a meeting, When the export is generated, Then JSON and PDF files include transcript, consent artifacts, and redaction metadata, delivered via a link that expires in 24 hours. Given an admin performs a hard delete, When confirmed, Then primary storage is purged within 24 hours and backups within 30 days, and an audit log entry is created. Given a data subject access request, When an export is requested, Then all personal data fields tied to the subject identifier are included in the export.

Security and Admin Policy Enforcement

Given data in transit, When clients connect, Then TLS 1.2+ with HSTS and modern cipher suites is enforced for all endpoints. Given data at rest, When stored in databases or object storage, Then AES-256 encryption is applied with KMS-managed keys rotated at least every 90 days. Given role-based access control, When a user without the necessary role tries to view a transcript or consent artifacts, Then the request is denied with HTTP 403 and an audit event is recorded. Given admin policy “Disallow Recording” is enabled, When users attempt to initiate recording/transcription, Then the UI control is disabled and API attempts return HTTP 403. Given admin policy “Restrict External Sharing” is enabled, When users attempt to create external share links or exports, Then the action is blocked or requires admin override with justification captured in the audit log.

PII Redaction and Regional Data Residency

Given redaction is enabled, When transcripts are generated, Then sensitive identifiers (e.g., SSN, passport, credit card, bank account, DOB, email, phone) are masked in UI and exports using standardized tokens (e.g., “[REDACTED]”). Given redaction is enabled, When a user downloads an export, Then masked content cannot be reversed and original values are not present in the exported files. Given data residency is set to a specific region, When storing and processing meeting artifacts, Then all at-rest and in-region processing stays within the chosen region and approved sub-processors. Given the residency setting is changed, When applied, Then new data is stored in the new region and existing data remains in the original region until migrated via an admin tool with a full audit trail. Given a cross-region write is attempted, When detected, Then the request is blocked and an alert is sent to workspace admins within 5 minutes.

Co-Edit Studio

Share a secure link mid-call so both parties edit the same draft in real time. Inline suggestions, smart placeholders, and locked guardrails keep approved language intact while letting clients tweak only what matters. See changes live, accept with one click, and skip the email ping-pong.

Requirements

Secure Mid-Call Share Link

"As a small-business owner on a sales call, I want to share a secure edit link my client can open instantly so that we can co-edit the contract without account setup or email back-and-forth."

Description

Generate a time-limited, single-use collaboration link that can be shared during a live call, enabling guests to join the contract draft without creating an account. Enforce role-based access (Owner, Editor, Commenter, Viewer), optional OTP verification, domain allowlisting, and link expiration/revocation to prevent unauthorized access. All sessions use TLS in transit and encrypted storage at rest, with session-level audit events (join, leave, IP/device metadata). The link deep-loads the specific draft, applies the correct permissions, and falls back gracefully on mobile. Integrates with existing SnapAgree auth, orgs, and document permissions while minimizing join friction for clients.

Acceptance Criteria

Owner Generates Time-Limited Single-Use Link to Draft

Given an Owner is viewing Draft ID D and sets expiration to 15 minutes and single-use to true When they generate a share link Then a unique tokenized HTTPS link is created bound to Draft D and Role R. Given the link is opened the first time within 15 minutes When the Guest loads it Then Draft D deep-loads directly and displays the join screen in <= 2 steps. Given the link has already been used successfully once When any user attempts to use it again Then access is blocked with HTTP 410 and message "Link already used" and an audit event is recorded. Given current time > expiration When any user opens the link Then access is blocked with HTTP 410 and message "Link expired" and an audit event is recorded. Given link generation occurs under nominal load When the Owner clicks Generate Then 95th percentile link creation latency is <= 600 ms.

Guest Joins Mid-Call Without Account (Optional OTP)

Given OTP is disabled for the link When a Guest opens the link Then no account creation is required and the Guest can join the session within 2 clicks. Given OTP via email is enabled When a Guest provides an email Then a 6-digit OTP is issued and is valid for 2 minutes and a maximum of 5 attempts. Given the Guest enters a valid OTP within 2 minutes When they submit it Then the session starts and the Guest display name is captured and shown to the Owner. Given the Guest enters invalid OTP 5 times When they attempt again Then access is temporarily blocked for 15 minutes and an audit event is recorded. Given the Guest opens the link on a typical 4G connection When they join Then 50th percentile time-to-draft-load is <= 5 seconds and 95th percentile <= 10 seconds.

Role-Based Permissions and Guardrails Enforcement

Given the link role is Editor When the Guest tries to edit locked clauses Then edits are prevented, an inline notice explains "locked by owner", and a suggestion mode is offered. Given the link role is Editor When the Guest edits unlocked fields or smart placeholders Then changes are permitted and tracked as suggestions with attribution. Given the link role is Commenter When the Guest attempts to edit body content Then edit controls are disabled and API requests are rejected with HTTP 403. Given the link role is Viewer When the Guest attempts to comment or edit Then those controls are hidden and any direct API calls are rejected with HTTP 403. Given the Owner reviews incoming suggestions live When they click Accept Then the change is applied in one action and the audit log records the accept event and actor.

Domain Allowlisting Gating Access

Given domain allowlisting is enabled with [client.com, partner.co] When a Guest provides an email for access Then only emails matching the allowed domains are accepted; others are rejected with "Email domain not allowed". Given domain allowlisting is enabled and OTP is disabled When a Guest opens the link Then the Guest is prompted for email solely for domain validation before joining. Given domain allowlisting is disabled When a Guest opens the link Then no domain restriction is enforced. Given a Guest is rejected due to domain mismatch When they retry with an allowed domain Then access proceeds per the link’s OTP setting and an audit event records the outcome.

Link Revocation, Regeneration, and Invalidation

Given a link is active When the Owner clicks Revoke Link Then new access attempts are blocked within 5 seconds with message "Link revoked" and HTTP 401/410 and an audit event is recorded. Given a Guest is currently connected via the link When the Owner revokes the link Then the Guest session is terminated within 5 seconds with an in-app notice. Given the Owner regenerates a new link for Draft D When regeneration completes Then any previously issued links for Draft D are invalidated and cannot be used. Given Draft D is archived or the Owner loses permission to share it When a previously issued link is used Then access is denied with HTTP 403 and an audit event is recorded.

Session Security and Audit Logging

Given any access attempt (success or failure) occurs via the link When the event happens Then an immutable audit record is stored with timestamp, link ID, actor identifier (email or guest label), role, IP, user agent, and outcome. Given a session starts or ends When join/leave occurs Then corresponding audit events are captured within 2 seconds of occurrence. Given any request to the share endpoints When it is made Then TLS 1.2+ HTTPS is required; HTTP requests are redirected to HTTPS and non-TLS API calls are rejected. Given data for the draft is stored at rest When it is persisted Then it is encrypted at rest and no secret tokens or PII appear in URLs. Given the Owner opens the Audit panel for Draft D When they view Link Activity Then events for joins, leaves, OTP failures, domain rejections, revocations, expirations, and permission denials are visible and filterable by time and outcome.

Mobile Access and Graceful Fallback

Given a Guest opens the link on a supported mobile browser (iOS Safari 16+, Android Chrome 110+) When they join Then real-time co-editing loads with the correct role and latency targets are met. Given a Guest opens the link on an unsupported or degraded mobile environment When they join Then a simplified experience loads (view/comment per role), a banner explains limited functionality, and no app crash occurs. Given the device is mobile and screen width < 480px When the editor UI loads Then critical actions (Accept, Comment, View History) are accessible within 2 taps and text remains readable (WCAG 2.1 AA contrast). Given the Guest loses connectivity on mobile for < 30 seconds When connectivity resumes Then the session auto-reconnects and resynchronizes changes without data loss.

Real-Time Presence & Conflict-Free Editing

"As a user, I want to see my client’s cursor and edits in real time so that we can make changes together without overwriting each other."

Description

Provide multi-user live editing with presence indicators, live cursors, selection highlights, and sub-100ms keystroke propagation using OT/CRDT to prevent conflicts. Support 2–10 concurrent participants, resilient reconnects, offline buffering, and eventual consistency without data loss. Persist draft state with snapshotting and incremental ops for reliability and rollback. Ensure performance on average broadband and modern mobile browsers. Integrates with SnapAgree’s document model, templates, and version history.

Acceptance Criteria

Sub-100ms Keystroke Propagation

Given 2–10 participants are connected to the same draft over average broadband (≥25 Mbps down/3 Mbps up, ≤80 ms RTT) When any participant inserts or deletes a single character Then all other participants render the change within ≤100 ms at the 95th percentile and ≤150 ms at the 99th percentile over a sample of ≥500 keystrokes, with zero dropped or duplicated characters and per-author ordering preserved

Presence Indicators, Live Cursors, and Selections

Given a participant joins a draft with 1–9 others When the join is acknowledged by the server Then their presence indicator (name/avatar/color) appears for all participants within ≤500 ms, a live cursor is visible at their caret position, and selection highlights update within ≤100 ms p95 during selection changes And when a participant disconnects or becomes idle, presence and live cursor disappear or show idle within ≤2 s of detection

Conflict-Free Merging with OT/CRDT and Eventual Consistency

Given multiple participants type concurrently in overlapping and non-overlapping ranges and operations are delivered out of order or duplicated When all operations are processed by clients and server Then all replicas converge to an identical document state within ≤2 s after network stabilization, with no data loss, no manual merge prompts, and deterministic ordering of concurrent inserts based on defined tie-break rules And operation application is idempotent; applying the same operation twice yields no additional change

Resilient Reconnects and Offline Buffering

Given a participant goes offline for up to 10 minutes while editing When connectivity is restored Then locally buffered operations are uploaded and applied in original author order within ≤3 s, with zero loss or duplication, and the participant’s view matches the server’s state within ≤1 s thereafter And while offline, the UI indicates unsynced changes and, upon completion, updates to a synced state indicator within ≤1 s

Snapshotting, Recovery, and Rollback

Given snapshotting is enabled for the draft When a process crash or restart occurs Then the latest document state is recoverable from the most recent snapshot plus incremental operations with no acknowledged edits lost and with recovery time ≤2 s for a 50-page (~30k characters) document And snapshots are produced at least every 60 seconds or every 1000 operations (whichever comes first), and replaying operations from the last snapshot reconstructs an identical state byte-for-byte And when a user requests rollback via version history to any prior version, the system restores that exact content within ≤2 s and records the rollback as a new version

Performance on Average Broadband and Modern Mobile Browsers

Given 10 concurrent participants actively editing (≈3 keystrokes/sec/user) on Chrome 120+ (Windows/macOS) and Safari iOS 16+/Chrome Android 12+ over average broadband When observed over a continuous 15-minute co-editing session Then p95 keystroke propagation meets the latency criteria, client CPU ≤30% p95 on desktop and ≤50% p95 on mobile for the active tab, memory ≤250 MB on desktop and ≤300 MB on mobile, and zero disconnects due to client load occur

Integration with SnapAgree Document Model, Templates, and Version History

Given a draft instantiated from a SnapAgree template with smart placeholders, clause IDs, risk flags, and locked sections When participants co-edit permitted sections and accept changes Then locked sections remain immutable for unauthorized users, smart placeholders retain type constraints and render correctly, clause IDs and risk flags persist across edits and merges, and every accepted change is recorded in version history with author, timestamp, and diff And rolling back to any prior version restores the exact content and metadata (placeholders, clause IDs, risk flags) for that version within ≤2 s

Clause Guardrails & Locked Sections

"As a business owner, I want key clauses locked with clear editable areas so that clients can tweak details without compromising approved legal language."

Description

Allow template owners to lock approved clauses and restrict edits to predefined fields or sections while visibly marking editable regions. Enforce rule-based constraints (e.g., minimum notice periods, liability caps) with inline validation and explainers when a proposed change violates policy. Provide an override workflow requiring owner approval and an audit record for any exception. Prevent deletion or modification of locked text while permitting client input where safe. Integrates with template library, risk flags, and policy management to maintain compliance during co-editing.

Acceptance Criteria

Locked Clauses Are Immutable to Collaborators

Given a draft contains one or more clauses marked as Locked by the template owner And a collaborator with edit permissions opens the draft via a secure co-edit link When the collaborator attempts to edit, delete, move, or reformat text inside any locked clause (including via typing, paste, drag-select, cut, bulk actions, or API) Then the action is blocked within 100 ms And no content within the locked clause changes And an inline tooltip displays “Locked by owner” with a padlock icon And the attempt is logged with timestamp, user ID, action type, and clause ID

Editable Regions Are Clearly Marked and Accessible

Given the draft is loaded in Co-Edit Studio When the editor renders content Then all editable regions are visually highlighted and locked regions display a padlock icon And indicators meet WCAG 2.1 AA contrast ratios And screen readers announce “Editable region” or “Locked region” with descriptive aria-labels And keyboard navigation (Tab/Arrow) skips locked regions and focuses the next editable region And these indicators persist during live co-editing with no more than 200 ms delay after changes

Edits Restricted to Predefined Fields and Sections

Given the template defines editable sections and Smart Placeholders with type and format constraints When a collaborator edits within an allowed placeholder or editable section Then input is validated client-side and server-side for type (e.g., date, currency), format, and min/max length And edits outside predefined editable regions are prevented And Save/Accept Change is enabled only when all modified fields pass validation And the diff view highlights only changes within editable regions and excludes locked text

Inline Validation Enforces Policy Constraints with Explainability

Given a policy set defines rule-based constraints (e.g., NoticePeriod >= 14 days; LiabilityCap <= ContractValue) When a proposed change violates a constraint Then inline validation appears adjacent to the field within 150 ms stating the policy name/ID and human-readable explainer And a suggested compliant value is shown when determinable (e.g., “Set to 14 days”) And Save/Accept Change is disabled for that field while violation persists And a “Request Override” control is available to the collaborator

Owner Approval Override Workflow

Given a collaborator requests an override for a violating change When the template owner is notified (in-app and email) and opens the request Then the owner can Approve or Deny and must provide a rationale (min 10 characters) And on Approval, the change is applied, marked with an “Override” badge, and visible to all participants within 5 seconds And on Denial, the change is reverted and a comment is posted to the thread And the system records the decision, rationale, and approver identity

Audit Trail for Exceptions and Violations

Given any blocked edit attempt or approved/denied override occurs When the event is recorded Then the audit log entry includes: event type, user ID and role, clause/field ID, previous value, proposed value, policy rule ID, decision (if override), rationale (if provided), draft ID, session ID, timestamp (UTC ISO 8601), and IP hash And audit entries are immutable, queryable via UI within 60 seconds, and exportable to CSV and JSON And deleting or editing audit entries is not permitted by any role

Risk Flags and Policy Sync During Live Co-Editing

Given the draft is linked to a template and active policy set When policy rules change during a live co-edit session Then the session receives updates within 10 seconds and displays a banner “Policy updated” And clauses or fields affected are risk-flagged inline with severity (Low/Medium/High) and a brief explainer And accepting a High severity change requires owner acknowledgement or an approved override And the risk summary panel reflects flags in real time and links to policy details

Inline Suggestions & Change Tracking

"As a collaborator, I want to propose edits as suggestions and accept them with one click so that we can converge on terms quickly."

Description

Enable Suggest mode where edits create inline suggestions with contextual diffs, per-change accept/reject controls, and keyboard shortcuts. Support batch accept/reject, threaded comments on suggestions, and at-mention notifications within the session. Present a side panel of pending changes with filters by author, section, or risk level, plus exportable redlines. Changes integrate with version history and audit logs for traceability. Maintain responsiveness with pagination or virtualization on large documents.

Acceptance Criteria

Toggle Suggest Mode and Create Inline Suggestion with Diffs

Given a shared draft is open in Co-Edit Studio and the user has edit access When the user toggles Suggest Mode on via toolbar or shortcut (Ctrl/Cmd+Shift+S) Then subsequent insertions, deletions, and replacements create inline suggestions instead of direct edits And insertions display as green underline, deletions as red strikethrough, and replacements show contextual diff on hover or side-by-side tooltip And each suggestion shows per-change controls (Accept, Reject, Comment, More) and attributes author, timestamp, and avatar And the suggestion appears in the Pending Changes panel immediately with correct metadata

Per-Change Accept/Reject and Undo

Given at least one suggestion is present in the document When the user accepts a suggestion via inline control, sidebar item, or shortcut (Ctrl/Cmd+.) Then the suggestion text merges into the document, visual markup is removed, and the Pending Changes count decrements accordingly And an Undo toast appears for 10 seconds; activating Undo reverses the accept in one step When the user rejects a suggestion via inline control, sidebar item, or shortcut (Ctrl/Cmd+/) Then the original text is preserved/restored, markup is removed, and counts update And Accept/Reject actions are disabled with tooltip explanation for suggestions that are stale, conflicted, or locked And each action is written to version history and audit logs with suggestion ID, user, timestamp, and action

Batch Accept/Reject with Filters

Given the Pending Changes panel is open When the user applies filters by author, section, and risk level and chooses Select All Then only the filtered suggestions are selected and a summary shows total selected, sections affected, and risk distribution When the user clicks Accept All or Reject All Then the batch operation applies atomically; on any failure no partial changes persist and a retry option is presented And up to 500 suggestions complete in under 2 seconds on a standard laptop (Chrome latest); UI remains responsive during processing And version history records a single batch entry referencing all suggestion IDs; audit logs include per-item entries

Threaded Comments and @Mentions on Suggestions

Given a suggestion exists When a user opens its comment thread and posts a comment Then the comment appears immediately, is timestamped, and supports edit/delete by author within 5 minutes When the comment contains an @mention of a participant in the current session Then the mentioned user receives an in-session notification within 1 second with a jump link to the suggestion And resolving a thread marks it as resolved, hides it by default, and allows reopening with history preserved And comments inherit the suggestion’s visibility and are included/excluded in exports based on the user’s export option

Pending Changes Side Panel with Filters, Navigation, and Exportable Redlines

Given a document contains pending suggestions across multiple authors, sections, and risk levels When the user opens the Pending Changes panel Then the panel lists suggestions with author, section, risk badge, timestamp, and a concise diff preview And filters by author, section, and risk level can be combined; clearing filters resets the full list And clicking an item scrolls and focuses the corresponding suggestion in the editor within 300 ms And the panel updates in real time within 300 ms of new suggestions, accepts/rejects, or comments When the user selects Export Redlines and chooses format (PDF or DOCX) and filter scope (author, section, risk) and whether to include comments Then the exported file renders redline markup consistent with in-app visuals, includes metadata (doc ID, version, export timestamp), and downloads successfully And exports complete within 5 seconds for documents up to 100 pages or 2,000 suggestions with progress feedback

Version History and Audit Log Traceability

Given suggestions are created and actions are taken on them When the user opens Version History Then each accept, reject, and batch action appears as a version entry with author, timestamp, and diff summary And selecting a version highlights the relevant changes in the editor and allows restore When restoring a prior version Then a new version is created without deleting history; suggestions superseded by the restore are labeled as superseded And the audit log captures create, comment, accept, reject, resolve, restore events with user, timestamp, session ID, and IP address

Performance and Responsiveness on Large Documents

Given a large document (≥ 300 pages or ≥ 10,000 suggestions) with two or more active collaborators When users scroll, filter, or perform batch operations Then the editor employs virtualization/pagination such that input latency stays under 100 ms at the 95th percentile and scrolling remains ≥ 60 FPS on a standard laptop (Chrome latest) And memory usage stays under 600 MB and CPU under 80% average during batch accept/reject of 1,000 suggestions And real-time updates for new suggestions render to all participants within 300 ms end-to-end And when limits are exceeded, the UI provides back-pressure and clear messaging without freezing

Smart Placeholders & Auto-Fill

"As a freelancer, I want smart placeholders that auto-fill and stay consistent so that I don’t have to update the same info in multiple places."

Description

Insert structured placeholders for parties, dates, scope, fees, and SLAs that auto-fill from intake answers or connected sources (e.g., CRM) and propagate consistently across the document. Validate types, formats, and ranges (currency, dates, percentages) with real-time error states and required-field gating before finalization. Provide quick-edit chips and a summary form to update all placeholders in one view. Support localization for dates/currency and default fallbacks. Integrates with SnapAgree data panels, templates, and risk flags to reduce manual edits and errors.

Acceptance Criteria

Auto-fill Placeholders From Intake And CRM With Global Propagation

- Given a template with placeholders mapped to intake and CRM fields, when a draft is created and the user connects a CRM record, then mapped placeholders auto-fill with the latest data and display a filled state. - Given multiple instances of the same placeholder key across the document, when one instance is updated (via chip or summary form), then all instances update within 1 second (95th percentile). - Given a conflict between intake and CRM values, when auto-fill runs, then the CRM value wins by default and the change is logged with source=CRM. - Given a CRM API timeout or error, when auto-fill runs, then existing values are preserved, a non-blocking error banner is shown with retry, and unmapped placeholders remain unfilled with a clear state. - Given a user manually overrides an auto-filled value, when a new auto-fill sync occurs, then the overridden value is preserved unless the user explicitly opts to reapply source values.

Real-Time Type, Format, And Range Validation With Inline Error States

- Given a currency placeholder, when the user enters a value, then it must be a valid currency amount for the locale (symbol/code, thousand separators, 2 decimal places by default), otherwise an inline error appears and the field is marked invalid. - Given a date range (start_date, end_date), when values are entered, then both must be valid dates and end_date must be after start_date; otherwise inline errors appear on offending fields. - Given a percentage placeholder, when a value is entered, then it must be between 0 and 100 inclusive and allow up to 2 decimal places; otherwise an inline error appears. - Given an invalid placeholder value, when the user attempts to save or navigate, then the invalid field remains focused/highlighted and an accessible error message is announced. - Given a valid value entered after an error, when the user blurs the field, then the error state clears within 100 ms.

Finalization Gated On Required Placeholders Completion

- Given at least one required placeholder is empty or invalid, when the user attempts to finalize, send for e-sign, or export, then the action is blocked, the finalize button is disabled, and a checklist of missing/invalid fields is shown with deep links. - Given all required placeholders are valid, when the user attempts to finalize, then the action proceeds without placeholder-related blocking. - Given a co-edit session, when the guest fixes a required placeholder, then the host’s gating checklist updates in real time within 2 seconds.

Quick-Edit Chips And Summary Form Bi-Directional Sync

- Given placeholders in the document, when the user hovers or focuses a placeholder, then a quick-edit chip appears with the field name and current value. - Given the summary form is opened, when the user edits any placeholder value, then all instances in the document reflect the change within 1 second (95th percentile). - Given a placeholder is edited inline via a chip, when the summary form is open, then the corresponding entry updates immediately to match. - Given 20+ placeholders exist, when the user searches in the summary form, then results filter in under 200 ms and can be sorted by status (filled/required/invalid). - Given a bulk update is saved in the summary form, when the user clicks undo, then the last change set is reverted across all affected instances.

Localization Of Dates And Currency With Fallback Defaults

- Given the workspace locale is set (e.g., en-US, en-GB), when date and currency placeholders render, then they display in the locale format while values are stored in canonical ISO currency code and ISO-8601 date formats. - Given the user switches locale, when the document is reopened or refreshed, then all date and currency displays re-render to the new locale without altering stored canonical values. - Given a placeholder lacks a source value and a default fallback is configured, when auto-fill runs, then the fallback is inserted and marked with a fallback badge until the user confirms or edits it. - Given a multi-currency template, when a currency placeholder is filled, then the correct symbol, decimal, and thousand separators render for the chosen currency (e.g., USD $1,234.56; EUR €1.234,56).

Co-Edit Live Placeholder Sync With Guardrails And Permissions

- Given a co-edit session with a guest editor, when the guest tries to edit a locked placeholder, then the field is read-only with a tooltip explaining the guardrail. - Given an editable placeholder, when either participant changes its value, then the other participant sees the update within 2 seconds (95th percentile), with a transient “updated by [name]” indicator. - Given both participants edit the same placeholder concurrently, when the host accepts a suggestion or the last change is submitted, then the system applies last-accepted wins and shows a conflict banner with a revision diff and undo. - Given suggestion mode is enabled for guests, when the guest proposes a change to a placeholder, then the host can accept or reject with one click; on accept, the value propagates everywhere.

Integration With Templates, Data Panels, And Risk Flags

- Given a SnapAgree template with placeholder bindings, when a document is generated, then placeholders map to template variables and appear in the data panel with their current values and statuses. - Given a placeholder value triggers a defined risk condition (e.g., upfront fee > 50%, SLA uptime < 99.5%), when the value is saved, then a risk flag is added inline and in the risk panel with severity and rule detail. - Given a risk flag exists due to a placeholder value, when the value is brought back within safe thresholds, then the risk flag clears automatically. - Given the data panel is used to edit a placeholder, when the change is saved, then the document and summary form reflect the update and the change is logged to the audit trail.

One-Click Accept & Merge to Final

"As a business owner, I want to finalize the draft with one click and move straight to e-sign so that we close the deal while momentum is high."

Description

Offer a single action that applies all accepted suggestions, resolves placeholders, and produces a clean read-only version ready for e-sign. Create a timestamped snapshot, update version history, and lock the draft while preserving the ability to rollback. Trigger the standard SnapAgree e-sign flow with participants pre-filled and send completion notifications. Generate an audit trail summarizing accepted changes and participants. Ensure idempotency and guard against finalizing with unresolved validation errors.

Acceptance Criteria

One-Click Applies Accepted Suggestions and Resolves Placeholders

Given a draft contains one or more suggestions marked Accepted and all required placeholders have values And there are no unresolved blocking validations When the user clicks Finalize (One-Click Accept & Merge to Final) Then the system applies all Accepted suggestions and removes all suggestion markers And replaces all placeholder tokens with their resolved values And generates a clean final document with zero placeholder tokens, comments, or suggestion markup And returns the final document ID and snapshot ID

Idempotent Finalization on Retry

Given a draft is eligible for finalization And the finalize action is invoked multiple times due to retry or duplicate submission of the same operation When the first invocation completes successfully Then subsequent invocations return 200 OK with the same final document ID and snapshot ID And do not create additional version history entries, e-sign packets, or notifications And the event is logged as an idempotent duplicate without side effects

Validation Guard Blocks Finalization on Errors

Given a draft has any unresolved required placeholders, invalid participant data, or suggestions not marked Accepted where acceptance is required When the user clicks Finalize Then the system blocks finalization and returns a validation error summary listing each failing field and its location And no snapshot is created, no version history is updated, the draft is not locked, and no e-sign flow or notifications are triggered And the finalize action becomes available after all errors are corrected and re-validation passes

Snapshot, Version History Update, and Rollback Availability

Given a draft finalizes successfully When finalization completes Then a timestamped immutable snapshot with checksum is created and linked in version history as the latest entry And the version history entry records actor, UTC timestamp, final document ID, snapshot ID, and a concise change summary And a rollback control is available to authorized users for this version When an authorized user performs rollback Then the pre-final editable draft state is restored exactly (content, suggestions, placeholders), the draft is unlocked, and a rollback entry is added to version history

Read-Only Final and Draft Lock with Role-Based Controls

Given a document has been finalized When any user attempts to edit the final document or the originating draft Then editing controls are disabled and a lock banner shows who finalized and when And concurrent co-edit sessions receive a real-time lock notification within 5 seconds And only users with Owner or Admin role can access the rollback control; all others have view-only access

E-Sign Flow Triggered with Prefilled Participants and Notifications

Given participants are defined on the draft And the document finalizes successfully When finalization completes Then the standard SnapAgree e-sign flow is initiated with participants pre-filled in the configured signing order And signer invitations are sent to all participants with delivery status logged And the document owner and watchers receive a “Finalized and Sent for Signature” notification And the e-sign packet link is attached to the final document record

Audit Trail Generated for Finalization Event

Given a document finalizes successfully When finalization completes Then an audit trail entry is created capturing actor ID, UTC timestamp, final document ID, snapshot ID, count of Accepted suggestions applied, sections modified, count of placeholders resolved, and participant names/emails included in the e-sign packet And the audit trail entry is immutable, exportable (PDF/JSON), and visible to authorized users from the final document

Voice-to-Clause

Speak natural commands like “add a 30-day termination for convenience” or “split payments 50/50” to insert or update clauses instantly. Cuts typing and screen-switching, speeds negotiation, and keeps momentum—especially when you’re mobile.

Requirements

Real-time Voice Intent Parsing

"As a freelancer on a client call, I want SnapAgree to understand my spoken contract changes instantly so that I can modify terms without breaking the flow of the conversation."

Description

Provide low-latency speech-to-text and domain-tuned natural language understanding that converts spoken commands into structured actions (add, update, replace, remove) with extracted entities like durations, percentages, currency amounts, dates, and parties. Handle accents and common negotiation phrases (e.g., “net-15”, “terminate for convenience”, “split payments 50/50”), apply confidence scoring, and gracefully recover from ambient noise, partial phrases, or corrections. Deliver end-of-utterance detection and target under one second from speech end to parsed intent to keep negotiations fluid, and expose standardized intent payloads to the clause engine.

Acceptance Criteria

Parse Core Voice Commands with Entities

Given a curated domain test set of 200 spoken commands covering add, update, replace, and remove actions with durations, percentages, currency amounts, dates, and parties When the audio is processed end-to-end Then intent classification F1 ≥ 0.95 and action mapping accuracy ≥ 0.98 And entity extraction micro-F1 ≥ 0.95 across duration, percentage, currency_amount, date, and party And domain phrase normalization is correct (e.g., "net-15" => duration=15 days; "split payments 50/50" => percentage=0.5; "terminate for convenience" => clause_type=termination_for_convenience)

Sub-Second Intent Latency

Given the device is online via Wi‑Fi ≥ 10 Mbps or LTE with RSRP ≥ −110 dBm When the user stops speaking and end-of-utterance is detected Then time from speech end to emitted final intent payload is p95 ≤ 1000 ms and p99 ≤ 1500 ms over ≥ 1000 samples And telemetry records per-utterance timestamps for speech_end and payload_emitted

Confidence Scoring and Safe Fallbacks

Given each parsed intent includes a confidence score ∈ [0.0, 1.0] When confidence ≥ 0.85 Then the system flags the intent as executable without confirmation When 0.60 ≤ confidence < 0.85 Then the system requests confirmation and applies only upon explicit confirm When confidence < 0.60 Then the system reprompts to repeat or reformulate and applies no changes And the decision path is included in the payload as decision.mode ∈ {auto, confirm, reject}

Accent and Phrase Robustness

Given a balanced test set of ≥ 50 speakers across ≥ 8 English accents (US, UK, AUS, NZ, IN, PH, ZA, IE) When they speak domain commands including "net-15", "terminate for convenience", and "split payments 50/50" Then intent accuracy ≥ 0.93 and entity extraction micro-F1 ≥ 0.92 across accents And coverage accuracy for the listed domain phrases ≥ 0.98 overall

Noise, Interruptions, and Corrections

Given ambient noise conditions with SNR in [5 dB, 20 dB] including café and street noise When a command is spoken amid noise or with a truncated start Then either a correct intent is produced or a reprompt ("please repeat") is issued within 800 ms; no changes are applied at confidence < 0.60 When the user issues a correction (e.g., "scratch that", "undo last", "actually make it 45 days") within 10 seconds Then the system recognizes and applies the correction with intent accuracy ≥ 0.95 and completes updates/reversal within 1000 ms

End-of-Utterance Detection Reliability

Given a normal conversational speaking rate When the user finishes a command and pauses Then end-of-utterance triggers after 300–700 ms of silence by default And early cutoff rate (intent emitted before command completion) ≤ 2% over ≥ 500 utterances And late cutoff rate (silence > 1.5 s before processing starts) ≤ 3%

Standardized Intent Payload Contract

Given an intent is parsed Then the emitted payload conforms to JSON schema v1 with fields: id, version, action ∈ {add, update, replace, remove}, clause_type, entities (duration, percentage, currency_amount, date, party), transcript, confidence, locale, timestamps {speech_start_ms, speech_end_ms, emitted_ms}, decision {mode}, source {voice} And required fields are present and normalized (percentage ∈ [0,1]; currency_amount {value:number, currency:ISO-4217}; date ISO-8601; duration {value:int, unit ∈ {days, months}}) And schema validation pass rate is 100% over ≥ 1000 payloads And contract tests verify backward/forward compatibility across versions

Clause Template Mapping & Parameters

"As a small-business owner, I want my voice command to fill the right clause template with the correct numbers and dates so that the contract reflects exactly what I said without manual edits."

Description

Map parsed intents to SnapAgree’s clause library, selecting the appropriate plain-language template and populating variable fields from extracted parameters with unit normalization (calendar vs. business days, fixed fee vs. percentage, one-time vs. milestone payments). Validate required parameters, apply safe defaults where permissible, and surface ambiguities for confirmation. Support common domains (payments, termination, IP ownership, confidentiality, warranties, governing law) and maintain backward compatibility with existing template IDs and versioning.

Acceptance Criteria

Template Selection by Intent and Domain

Given a parsed intent {domain: termination, action: add, subtype: convenience, parameters: {period: 30, unit: days}} When clause mapping runs Then the system selects the clause template whose domain = termination and key = termination_convenience And returns templateId and templateVersion And templateVersion = latestCompatibleVersion for templateId And mappingOutcome = mapped

Time Unit Normalization and Defaults

Given a period value with no unit When mapping runs Then unit is set to calendar_days per template configuration And a normalization flag defaulted_unit is recorded Given a period expressed in business day synonyms (business day/business days) When mapping runs Then parameters.unit = business_days Given input 30 days with no qualifier When mapping runs Then normalizedPeriod.value = 30 And normalizedPeriod.unit = calendar_days

Payment Split Mapping (Percentage vs Fixed Fee)

Given the utterance split payments 50/50 When mapping runs Then templateId = payment_split And amountType = percentage And installments = [50,50] And sum(installments) = 100 Given the utterance fixed fee $1,200 one-time When mapping runs Then templateId = payment_fixed And amountType = fixed And schedule = one_time And amount.value = 1200 And amount.currency is normalized Given the utterance milestone payments 40/60 When mapping runs Then templateId = payment_milestone_split And schedule = milestone And percentages = [40,60] And sum(percentages) = 100

Required Parameter Validation and Safe Defaults

Given a required parameter is missing and no safe default is configured When mapping runs Then mappingOutcome = needs_confirmation And missingParameters contains the absent field names Given a required parameter is missing and a safe default is configured in the template When mapping runs Then the default value is applied And defaultsApplied contains the parameter name And mappingOutcome = mapped_with_defaults Given a provided parameter violates constraints (e.g., percentage > 100 or negative period) When mapping runs Then mappingOutcome = invalid_parameters And parameterErrors includes the field and reason

Ambiguity Detection and Confirmation Prompt

Given an ambiguous phrase terminate in 30 days with no unit or effective reference date When mapping runs Then mappingOutcome = needs_confirmation And ambiguities includes time_unit and effective_date And a human-readable confirmationPrompt with explicit options is returned When the user selects an option to resolve ambiguities Then mapping completes And selected values are applied to parameters And mappingOutcome = mapped

Domain Coverage for Core Clauses

Given representative parsed intents for payments, termination, IP ownership, confidentiality, warranties, and governing law When mapping runs Then each intent returns mappingOutcome = mapped And each has a valid templateId and templateVersion And parameters populated according to the template schema

Backward Compatibility with Template IDs and Versioning

Given an existing clause reference {templateId: T, templateVersion: V} When resolving for edit Then the system loads exactly version V And preserves parameter schema compatibility Given a new mapping request without an explicit version When mapping runs Then templateVersion = latestCompatibleVersion for templateId Given template T is deprecated When mapping runs Then the system maps to successor template T' And records a deprecationNotice And preserves semantic equivalence Given an external integration sends a previously valid templateId When mapping runs Then the reference resolves without error

Smart Clause Placement & Formatting

"As a consultant editing a contract on the go, I want voice-applied clauses to appear in the right place with proper numbering and style so that I don’t have to reformat or reorganize the document later."

Description

Insert or update clauses in the correct section based on document structure, creating sections if missing, and preserving numbering, headings, cross-references, and house style. Detect and merge near-duplicate clauses, maintain plain-language tone, and ensure changes are compatible with the current document mode (draft, redline, final). Update the table of contents and references automatically so that voice-driven edits produce a polished, legally coherent document without manual cleanup.

Acceptance Criteria

Insert Termination Clause into Existing Agreement

Given a contract with an existing "Termination" section and a recognized command "add a 30-day termination for convenience" When the system processes the command Then the new clause is inserted as the next correctly numbered subsection under "Termination" without disrupting existing numbering And heading, indentation, and numbering style match the house style guide And the clause text is in plain language (Flesch-Kincaid Grade Level ≤ 8.5) And in Draft mode, the insertion appears as clean text with no tracked changes or comments And in Redline mode, the insertion appears as a tracked change attributed to "SnapAgree" per house redline style And in Final mode, the insertion appears as clean text with no tracked changes or comments

Update Payment Split via Voice

Given a contract with a "Payment Terms" section specifying milestone payments and a recognized command "split payments 50/50" When the system processes the command Then the relevant clauses in "Payment Terms" are updated to reflect a 50/50 split with percentages totaling 100% And currency and percentage formatting follow house style (e.g., 50%, $1,000.00) And numbering and any internal references within "Payment Terms" remain correct And in Draft mode, updates appear as clean text with no tracked changes And in Redline mode, updates appear as tracked modifications attributed to "SnapAgree" And in Final mode, updates appear as clean text with no tracked changes or comments

Create Missing Confidentiality Section with Correct Numbering

Given a contract that does not contain a "Confidentiality" section and a recognized command "add confidentiality clause: mutual NDA for 2 years" When the system processes the command Then a new top-level section titled "Confidentiality" is created at the correct outline level and position with the next correct section number And the clause is inserted inside the new section using the house heading style and numbering scheme And the section title appears in the table of contents with the correct number And the clause text is plain language (Flesch-Kincaid Grade Level ≤ 8.5) And behavior conforms to the active document mode (Draft/Redline/Final as defined)

Detect and Merge Near-Duplicate Clauses

Given the document contains two clauses in the same section that are ≥85% similar by semantic comparison after a voice-driven insertion When the system evaluates for duplicates Then the user is prompted with a merge suggestion showing differences side-by-side And upon user confirmation, a single merged clause replaces the duplicates using the user-selected wording and house style And all internal cross-references point to the merged clause with zero broken references And section and clause numbering are renumbered sequentially without gaps

Auto-Update Cross-References After Renumbering

Given the document contains internal cross-references to sections or clauses affected by a voice-driven insertion, update, or merge When numbering changes occur Then 100% of internal cross-references are updated to the new numbers/text within 2 seconds of the change And there are 0 broken or unresolved cross-references reported by the validator

Auto-Update Table of Contents After Edits

Given the document has a table of contents When headings are added, removed, or renumbered due to a voice-driven edit Then the table of contents regenerates automatically without user action And all affected entries display correct titles, levels, and numbering And the update completes within 2 seconds for documents up to 100 pages

Respect Document Mode: Draft, Redline, Final

Given the document is in Draft mode When a clause is inserted or updated via voice Then the change appears as clean text with no tracked changes or comments, and unresolved placeholders (e.g., [Party Name]) are allowed Given the document is in Redline mode When a clause is inserted or updated via voice Then the change is tracked as an insertion/modification attributed to "SnapAgree", with deletions struck-through and insertions underlined per house redline style Given the document is in Final mode When a clause is inserted or updated via voice Then the change appears as clean text with no tracked changes, comments, or unresolved placeholders

Command Confirmation & Quick Edit

"As a freelancer, I want a quick confirmation of what SnapAgree heard and easy ways to tweak it so that I can fix small mistakes without slowing down."

Description

Display an inline confirmation card with the interpreted command, a human-readable summary, and a diff preview before applying changes. Offer single-tap or voice options to confirm, edit parameters (e.g., change 30 to 45 days), undo, or cancel. Provide a clear listening indicator, push-to-talk control, and immediate feedback for misheard terms. Minimize clicks while preventing unintended edits to balance speed with accuracy during live negotiations.

Acceptance Criteria

Inline Confirmation Card Appears Post-Command

- Given the user issues a valid voice command and speech recognition returns a transcript, when interpretation completes, then an inline confirmation card appears within 1200 ms containing: the interpreted command text, a one-sentence human-readable summary, and a diff preview showing insertions and deletions with +/- indicators and highlighting. - And the card is anchored adjacent to the affected clause/section within the document viewport. - And the diff preview is scoped to only impacted clauses (≤ 5 lines of surrounding context per change). - And no document changes are applied until the user explicitly confirms.

One-Tap Confirm, Cancel, and Undo

- Given the confirmation card is visible, when the user taps Confirm or says "Apply", then the proposed changes are applied within 800 ms and the card transitions to a success state. - And an Undo action is presented for at least 10 seconds; tapping Undo or saying "Undo" reverts the changes entirely with no data loss. - When the user taps Cancel or says "Cancel", then no changes are applied and the card is dismissed. - All actions are single-tap and keyboard accessible (Enter to confirm, Esc to cancel).

Quick Parameter Edit In-Card

- Given the confirmation card contains parameterized values (e.g., numbers, dates, percentages, party names), when the user taps an inline chip or field, then the parameter becomes editable. - When the user edits the parameter (via keypad, date picker, or voice), then the summary and diff preview update in under 500 ms to reflect the new value. - Validation enforces schema (e.g., days must be integer 1–365; percentages 1–100; currency formatted to locale). - Errors are explained inline and block confirmation until resolved.

Push-to-Talk and Listening Indicator

- Given the mic control is visible, when the user presses/holds the push-to-talk or toggles it on, then a persistent listening indicator (animated icon + "Listening…") and an audible cue are presented immediately. - When listening ends (release, timeout, or confirm), then the indicator turns off within 200 ms and a stop cue plays. - If speech is detected but overall interpretation confidence < 0.80, then the indicator shows an "Unsure" state and the confirmation card displays the top 3 interpretations with confidence scores; no changes are applied until one is selected. - Users can start/stop listening without leaving the editor; no more than one tap/click is required to initiate capture.

Misheard Terms Feedback and Correction

- Given the transcription includes entities with low confidence (e.g., number, duration, currency), when the confirmation card appears, then uncertain terms are underlined and tooltipped with the heard value and confidence. - When the user says "change X to Y" or edits a highlighted term, then the card re-renders with the corrected value and updated diff within 500 ms. - If no correction is made and confidence remains < 0.80 for any critical entity, then Confirm is disabled and a prompt suggests corrections or alternatives.

Accessibility and Mobile Usability

- All confirmation card controls meet WCAG 2.2 AA: color contrast ≥ 4.5:1; hit-area ≥ 44x44 px; logical focus order; visible focus states; accessible names/roles/states. - On mobile (viewport ≤ 414 px), the card renders as a bottom sheet occupying ≤ 60% height; primary actions remain visible without scrolling; the diff preview collapses with an "Expand" control. - Voice actions have text equivalents; all primary actions operable with one hand; haptic feedback provided on Confirm and Undo. - Performance on mid-tier mobile devices: time from command end to card render ≤ 1500 ms; main-thread long tasks (>50 ms) during interaction < 5%.

Conflict Detection & Risk Flags

"As a solo founder, I want SnapAgree to warn me if my spoken change creates conflicts or added risk so that I don’t accidentally weaken my position."

Description

Before applying a voice change, scan the document for conflicting or duplicative terms (e.g., multiple termination clauses with different notice periods, inconsistent payment schedules) and surface risk flags consistent with SnapAgree’s risk engine. Provide contextual guidance and safer alternatives when a command increases risk beyond user-defined thresholds, and allow users to override with explicit confirmation. Update the document’s risk summary in real time after any applied change.

Acceptance Criteria

Pre-Apply Conflict Scan for Voice Commands

Given a user issues a valid voice command to add or modify a clause When the system parses the intent and target clause category Then it scans the entire document for conflicts and duplicates before any text change is applied And returns the scan results within 2 seconds for documents up to 20,000 words And the document remains unchanged until the user selects apply, modify, or cancel

Conflict Detection for Termination and Payment Clauses

Given a document with two termination clauses using different notice periods and an existing Net 30 payment term And the user says either “add a 30-day termination for convenience” or “split payments 50/50” When the pre-apply scan runs Then it identifies all conflicting or duplicative clauses related to the command And lists each with clause title, section/location, conflict type (duplicate/inconsistent), and differing parameters And highlights affected text ranges in the editor And provides one-click options to replace, merge, or cancel per conflict

Risk Flags Consistency and Threshold Gate

Given a user-defined risk threshold is set (e.g., Medium) And a proposed change has a computed risk delta from SnapAgree’s risk engine When the scan completes Then the risk flags displayed (IDs, severity, descriptions) match the engine output for the same inputs And if projected risk exceeds the threshold, the system blocks auto-apply and shows a blocking banner with top-severity flags And if projected risk is at or below threshold, the system allows apply without a blocking banner

Contextual Guidance and Safer Alternatives

Given the proposed change exceeds the user’s risk threshold When guidance is displayed Then at least two safer alternatives are presented with plain-language rationales and estimated risk deltas And selecting an alternative updates the inline preview and recalculates flags within 2 seconds And the user can insert an alternative with a single action without re-speaking the command

Explicit Override Confirmation

Given the proposed change exceeds threshold and/or conflicts remain When the user opts to proceed anyway Then the system requires explicit confirmation via clicking “Confirm override” or saying “Confirm override” And records the override with timestamp, user ID, command transcript, current risk flags, and optional reason And applies the change only after successful confirmation And if confirmation is not received within 15 seconds, the operation times out with no change

Real-time Risk Summary Update

Given a change is applied by accept, alternative selection, or override When the document updates Then the risk summary panel recalculates and shows the updated overall risk score, count of flags by severity, and new/cleared flags within 2 seconds And resolved conflicts are removed from the summary And if the user cancels or times out, the summary remains unchanged

Mobile Mic Controls & Accessibility

"As a service provider often working from my phone, I want simple, reliable mic controls and readable captions so that I can make contract changes while mobile."

Description

Offer prominent, reliable microphone controls across mobile and desktop with push-to-talk and hands-free modes, permission handling, noise suppression, and automatic timeout. Provide captions of recognized speech, large-tap targets, and screen-reader accessible controls. Optimize for variable network conditions with graceful degradation and optional on-device preprocessing to keep the feature usable when traveling or multitasking.

Acceptance Criteria

Mobile Push-to-Talk Button Visibility & Size

Given the Voice-to-Clause editor is open on mobile or desktop When the UI loads Then a push-to-talk mic button is visible without scrolling within 1 second, has a minimum touch target of 48x48 dp (Android), 44x44 pt (iOS), or 40x40 px (desktop), displays a mic icon and "Hold to Speak" label, and meets WCAG 2.1 AA contrast (>= 4.5:1). Given the on-screen keyboard is open on mobile When the editor toolbar is shown Then the mic button remains accessible above the keyboard and does not overlap essential controls. Given the mic button receives focus When navigating via keyboard or switch access Then focus order is logical and a visible focus indicator with >= 3:1 contrast is shown. Given the user presses and holds the mic button When recording starts Then the button switches to a "Listening…" state within 150 ms and on release recording stops within 150 ms.

Hands-Free Mode Toggle & State Persistence

Given the mic menu is open When the user toggles Hands-Free mode on Then the app starts listening using VAD without requiring hold, shows a persistent recording indicator, and exposes a Stop button with a minimum touch target of 48x48 dp. Given Hands-Free mode is on When the app is backgrounded for up to 2 minutes Then recording auto-stops immediately and shows a notification "Recording stopped (backgrounded)". Given Hands-Free mode was last used When the app relaunches on the same device Then the Hands-Free toggle state persists for 30 days and does not auto-start listening without an explicit user action. Given the user toggles Hands-Free off When they return to Push-to-Talk Then no background recording continues and the UI reflects the change immediately.

Microphone Permission Handling & Re-prompt

Given microphone permission is not granted When the user first taps the mic Then the OS permission prompt appears within 300 ms. Given the user denies permission When they return to the app Then an inline banner explains why mic access is needed with "Retry" and "Open Settings" actions; the mic button is disabled with aria-disabled=true and tooltip. Given permission is granted in system settings while the app is open When the user returns to the app Then the app detects the change within 2 seconds and enables the mic without requiring app restart. Given permission is permanently denied (Don't ask again) When the user taps Retry Then the app opens the system settings page via deep link.

Noise Suppression & Speech Robustness

Given noise suppression is enabled (default) When ambient noise is 60–70 dBA and the user issues a 5–10 second contract command at ~0.5 m from the device Then transcription achieves word error rate <= 15% and the intent is correctly parsed in >= 95% of test utterances; the UI shows a "Noise suppression on" indicator and a toggle. Given noise suppression is toggled off When the user records Then the state persists for the session and can be toggled back on; a one-time per session warning "Higher background noise" is shown. Given a headset microphone is connected When recording starts Then the app prioritizes the headset input and reflects the input source in the UI.

Automatic Timeout & Partial Transcript Preservation

Given the user is recording (push-to-talk or hands-free) When continuous silence is detected for 3 seconds (±0.5 s) Then recording auto-stops, provides a 100 ms haptic/audio cue, and finalizes the transcript. Given partial captions are visible during recording When timeout occurs or the user manually stops Then no recognized text is lost; the last partials are committed within 500 ms and displayed in the caption area. Given no speech is detected within 10 seconds of starting When timeout triggers Then show a tip "Try speaking closer to the mic" and do not create an empty clause command.

Live Captions & Screen Reader Accessibility

Given recording is active When the user speaks Then live captions update at least every 300 ms, use a font size >= 16 sp on mobile (>= 14 px desktop), and maintain contrast ratio >= 4.5:1. Given a screen reader is enabled (TalkBack/VoiceOver) When the user navigates to mic controls Then controls expose accessible names, roles, and states (e.g., aria-pressed for Hands-Free), and announce "Recording started" and "Recording stopped" via a polite live region; focus does not jump unexpectedly. Given a user uses hardware keyboard or switch control When tabbing through controls Then mic, Hands-Free toggle, and Stop are reachable and operable; all actions are achievable without touch.

Graceful Degradation on Poor/Offline Network & On-Device Preprocessing

Given network latency > 800 ms, bandwidth < 200 kbps, or offline When the user records a command Then the app performs on-device preprocessing (VAD/noise suppression), buffers audio locally with encryption at rest, displays "Transcribing locally—will sync" status, and queues the command for server processing. Given connectivity is restored When queued items exist Then the app uploads and processes within 5 seconds per item and applies resulting clause updates automatically with a toast "Applied: <summary>". Given the queue reaches 20 unprocessed items or 50 MB of audio When additional recordings occur Then the app blocks new recordings with an explanation and offers "Manage queue" to free space. Given the user disables on-device preprocessing in Settings When poor network is detected Then the app falls back to local buffering only (no on-device transcription) and clearly indicates decreased performance.

Voice Action Audit Logging

"As a business owner, I want an audit history of voice-applied changes so that I can verify what was said and applied if questions arise later."

Description

Record a secure audit trail of voice-driven actions including transcript, derived intent, parameters, user, timestamp, document version, and before/after diffs. Store confidence scores and decision outcomes (applied, edited, canceled) for troubleshooting and compliance. Respect privacy by redacting sensitive content where possible and limiting retention per workspace policy, while enabling export for dispute resolution and internal QA.

Acceptance Criteria

Core Voice Action Audit Entry Creation

Given a signed-in user issues a supported voice command that leads to a contract change When the system processes the command Then exactly one audit record is persisted containing: transcript, derived_intent, parameters, user_id, timestamp (UTC ISO 8601), document_id, document_version, before_diff, after_diff, confidence_score (0.0–1.0), decision_outcome (applied|edited|canceled) And the audit record’s values correspond exactly to the executed change And the record is retrievable by document_id and timestamp via the audit API

Redaction of Sensitive Content in Audit Records

Given a transcript, parameters, or diffs contain sensitive data (email, phone number, payment card number, government ID, street address) When the audit record is stored Then those values are replaced with redaction tokens [EMAIL], [PHONE], [CARD], [GOV_ID], [ADDRESS] in transcript, parameters, and diffs And non-sensitive content remains unchanged And redaction occurs deterministically before persistence and before any export or query returns the data

Retention Policy Enforcement for Voice Audit Logs

Given a workspace retention policy of N days is configured When an audit record’s age exceeds N days Then the record is permanently deleted from primary storage and scheduled backups And queries and exports no longer return the deleted record And a change to the retention policy takes effect for new and existing records within 24 hours

Export of Voice Audit Logs for Dispute Resolution

Given a workspace admin requests an export for a date range with optional filters (user_id, document_id, derived_intent, decision_outcome) When the export completes Then the export contains only the workspace’s audit records matching the filters with redactions applied And the export is delivered in JSONL and CSV formats And the export includes a SHA-256 checksum file for payload integrity verification

Access Control to Voice Audit Trail

Given any user attempts to view or export audit logs When the system evaluates the user’s role and workspace membership Then Owners and Admins can view/export all workspace audit records And Members can view their own audit records for documents they can access And users without permission or from other workspaces receive HTTP 403 and no data is leaked

Tamper-Evidence and Immutability of Audit Records

Given an audit record is persisted When any attempt is made to modify or delete it before retention expiry Then the system prevents modification (append-only) and only allows deletion via retention policy And each record stores a content_hash and prev_hash forming a verifiable chain And verification of the chain over a 24-hour window of records yields zero mismatches

Diff and Outcome Semantics for Voice Actions

Given a voice action is processed with an outcome of applied, edited, or canceled When the audit record is created Then for applied: before_diff and after_diff accurately reflect the clause-level change and document_version increments by 1 And for edited: decision_outcome is edited, diffs reflect the final user-edited text that was applied, and document_version increments by 1 And for canceled: decision_outcome is canceled, no document change occurs, diffs are empty or null, and document_version does not change

On-Call Risk Coach

As terms change, live risk flags explain why something’s risky and offer safer, jurisdiction-aware alternatives you can apply instantly. Prevents gotchas under pressure and gives you confidence to accept or counter without pausing the conversation.

Requirements

Real-time Risk Detection Engine

"As a small-business owner negotiating live, I want risk flags to update instantly as I edit clauses so that I can assess and respond without breaking the flow of the conversation."

Description

Provide continuous clause-level monitoring of the contract editor to detect risky terms as the user types or pastes content. Evaluate change diffs and map text to risk patterns (e.g., indemnity scope, limitation of liability caps, auto-renewal, governing law, payment terms, IP assignment), assigning severity levels and rationale codes. Trigger updates within 300 ms for single-clause edits and under 800 ms for multi-clause paste operations for documents up to 50 pages. Support English initially with locale variants (US, UK, CA, AU). Integrate with the SnapAgree editor event bus and produce structured risk annotations with character offsets, rationale codes, and suggested remedy templates. Handle nested clauses, tables, and numbered lists, failing safely by marking unknown structures as "needs review."

Acceptance Criteria

Single-Clause Edit Risk Detection and Latency

Given an English document up to 50 pages is open in the SnapAgree editor and a clause is focused When the user types, deletes, or edits text that changes risk-relevant language within that single clause Then the engine evaluates only the edited clause and publishes updated risk annotations to the editor event bus within 300 ms of the edit event And each annotation includes: category (indemnity_scope | liability_cap | auto_renewal | governing_law | payment_terms | ip_assignment), severity (Low | Medium | High | Critical), rationale_code, start_offset, end_offset, clause_id, and remedy_template_id And detection for the edited clause achieves at least 95% recall and 90% precision against the regression corpus for the supported categories

Multi-Clause Paste Risk Detection and Latency

Given an English document up to 50 pages is open in the SnapAgree editor When the user pastes content that modifies two or more clauses Then the engine computes a diff, re-evaluates only impacted clauses, and publishes consolidated risk annotations for all impacted clauses within 800 ms of the paste completion event And no annotations are emitted for clauses not impacted by the paste And detection for impacted clauses meets at least 95% recall and 90% precision against the regression corpus for the supported categories

Diff-Based Evaluation and Minimal Recompute

Given any edit event (type, delete, paste) occurs in the editor When the engine processes the change Then only changed clauses are re-evaluated and annotated; risk annotations for unchanged clauses retain their annotation_ids and are not re-published And the published payload includes the set of changed_clause_ids and the full set of annotations for those clauses only

Locale-Aware Rules and Remedies (EN: US, UK, CA, AU)

Given the document locale is set to US, UK, CA, or AU English When the text contains locale-sensitive terms (e.g., governing law venues, tax terms, spelling variants) relevant to risk categories Then the engine applies locale-specific risk rules and emits rationale_code and remedy_template_id that match the selected locale And governing law detection correctly identifies jurisdiction granularity appropriate to the locale (e.g., US state, CA province, UK constituent country, AU state/territory) And all unit tests in the locale suite pass for each supported locale

Complex Structures Handling and Safe Failure

Given a document contains nested clauses, tables, and numbered lists When the engine analyzes these structures Then it emits correct risk annotations with accurate character offsets for supported structures And for unknown or ambiguous structures it emits a needs_review flag for the affected clause(s) without throwing errors or timeouts, and no severity is assigned until review And the engine remains responsive, with no single operation exceeding the specified latency thresholds

Structured Risk Annotation Schema Compliance

Given the engine publishes risk annotations When a consumer validates the payload Then each annotation includes: annotation_id (UUID), clause_id, category, severity, rationale_code, start_offset, end_offset, locale, and remedy_template_id And start_offset and end_offset map to the exact risky substring in the current editor snapshot (substring(start_offset,end_offset) equals the flagged text) for 100% of annotations in test cases And all fields conform to the documented types and allowed values, with schema validation passing for 100% of messages

Editor Event Bus Integration and Throughput

Given the engine is subscribed to the SnapAgree editor change events and publishes to the risk annotations topic When the editor emits a sustained rate of 200 edits per minute including typing, paste, and undo/redo Then the engine processes and publishes corresponding risk.annotations.updated events with no dropped events and within the specified 300 ms/800 ms latency thresholds And each outbound event includes document_id, locale, changed_clause_ids, and annotations[] And consumers can idempotently apply events using a monotonically increasing sequence number per document

Jurisdiction-Aware Rule Service

"As a freelancer working with clients in different regions, I want safer alternatives that match the governing law so that I don’t accidentally accept terms that are unenforceable or risky where I operate."

Description

Centralize a versioned knowledge base of jurisdiction-specific risk rules and safer clause patterns, backed by citations and applicability scopes (jurisdiction, sector, contract type, party role). Resolve governing law and venue from the document or user selection and apply correct variants. Allow hot-swapping of rule sets without redeploying the editor via remote configuration. Include conflict resolution when multiple jurisdictions are detected, with a fallback hierarchy. Track rule provenance and effective dates. Provide an API endpoint to fetch rules and return tailored alternatives. Log rule hits for analytics. Initial coverage includes US state-level (CA, NY, TX, DE), federal US, UK, Ontario, and Australia; with an extensible schema for expansion.

Acceptance Criteria

Resolve Governing Law and Venue from Document or User Selection

Given a contract contains an explicit governing law clause naming a jurisdiction and no user override When the service parses the document Then governing_law is returned as the normalized jurisdiction code for that clause and venue is returned if explicitly named Given a user has selected a governing law override When the service processes the same document Then governing_law equals the user-selected jurisdiction and source_of_truth='user' is included Given neither explicit clause nor user selection are present but party addresses or template/account defaults exist When the service attempts to resolve jurisdiction Then governing_law is set using the configured fallback hierarchy and a confidence value between 0 and 1 is returned

Apply Jurisdiction-Scoped Risk Rules and Safer Alternatives

Given governing_law='US-CA', sector='marketing', contract_type='services', party_role='supplier' When rules are requested Then only rules whose applicability includes US-CA and that match the provided scope values or wildcard are returned Given multiple clause variants exist for a rule at different specificity levels When results are returned Then the most specific matching variant is marked primary and others are listed as secondary Given no state-specific variant exists for a rule When results are returned Then the service falls back to federal or generic according to order state > federal > generic Given initial coverage jurisdictions {US-CA, US-NY, US-TX, US-DE, US-Federal, GB, CA-ON, AU} When queries are made with each as governing_law Then the endpoint returns a 200 response and any configured applicable rules without schema or scope errors

Versioned Rule Provenance and Effective Dating

Given rules have fields id, version, effective_start, effective_end (nullable), supersedes, citations When a client queries with as_of_date Then only rule versions where effective_start <= as_of_date < effective_end (or end is null) are returned Given a newer version of a rule is published When querying without a specific version Then the latest effective version is returned and previous versions remain retrievable by version Given a rule includes citations When returned in the API Then each citation includes at least source, citation_text, and url

Conflict Resolution with Fallback Hierarchy for Multiple Jurisdictions

Given the document references multiple jurisdictions When resolving governing_law Then the priority order is applied: user_selection > governing_law_clause > venue_clause > template_default > account_default > majority_document_mentions > none Given two candidates at the same priority level are present When selecting one Then the tie-breakers are applied in order: prefer more specific over broader, prefer higher mention frequency, otherwise choose by ascending jurisdiction code for determinism Given a conflict was resolved When the API responds Then a conflict_resolution object lists considered candidates, their ranks, and the selected jurisdiction

Hot-Swap Rule Sets via Remote Configuration Without Redeploy

Given an administrator updates the remote configuration to activate ruleset 'v2025.09.14' When the change is committed Then subsequent API calls begin using the new ruleset within 60 seconds and responses include ruleset_version='v2025.09.14' Given active sessions initiated before the switch When they continue to request evaluations Then they consistently receive their original ruleset for up to 15 minutes or until session end, whichever comes first Given a rollback is requested to the previous ruleset When the remote configuration is updated Then traffic reverts within 60 seconds without service redeploy or downtime

API Returns Tailored Alternatives with Citations and Extensible Schema

Given a request payload includes contract_text or clause_ids, governing_law, venue, sector, contract_type, party_role, and as_of_date When POST /rules/resolve is called Then the response is 200 and conforms to schema with fields rules[], each containing rule_id, version, jurisdiction, applicability, risk_severity, citations[], and alternatives[] Given an applicable rule is returned When inspecting alternatives Then at least one safer_clause.text and rationale are provided and are tagged with the same jurisdiction as the rule Given a new jurisdiction code 'NZ' is added via configuration When queries specify governing_law='NZ' Then the endpoint accepts the code and returns configured rules without code changes Given an unsupported jurisdiction code is provided When the active ruleset does not include it Then the endpoint returns 200 with rules=[] and a warning indicating unsupported jurisdiction

Log Rule Hits and Alternatives for Analytics

Given rules are evaluated for a request When the API responds Then an analytics event is emitted per rule with fields tenant_id, document_id_hash, rule_id, version, jurisdiction, severity, action (flagged|alternative_suggested|applied), timestamp, and source_of_jurisdiction Given analytics events are produced When inspected within the analytics store Then events appear within 120 seconds of the API response and contain no raw contract text or PII beyond hashed identifiers Given a failure to deliver analytics occurs When the event stream is unavailable Then events are queued and retried with exponential backoff for at least 24 hours

Inline Risk Coach Panel

"As a service-based founder under time pressure, I want clear, in-context explanations and fixes so that I can confidently accept or counter terms without leaving the editor."

Description

Add an inline, non-blocking UI panel that anchors to the selected clause and displays a plain-language explanation of the risk, severity, and business impact, with links to underlying rationale. Provide ranked safer alternatives with one-click apply actions. Show compatibility badges for jurisdiction and contract type. Include quick filters (e.g., minimize liability, maintain IP, accelerate payment). Support keyboard shortcuts, screen readers (WCAG 2.2 AA), and localization. Ensure the panel never obscures critical text; auto-reposition and collapse on scroll. Persist the user’s last choice of view density. Telemetry should capture impressions, selections, and dismiss reasons.

Acceptance Criteria

Panel Anchors Without Obscuring Selected Clause

Given a user selects any clause in the editor When the risk panel opens Then the panel anchors adjacent to the selected clause and does not overlap the clause’s bounding rectangle Given the initial anchor position would overlap the selected clause or its immediate preceding/following lines When the panel renders Then it auto-repositions to the nearest edge that avoids covering critical text Given the user scrolls such that the selected clause is no longer fully visible in the viewport When the scroll state changes Then the panel collapses to a compact header that does not cover editor text and remains associated with the clause Given the selected clause returns to full visibility When scrolling stops Then the panel expands back to full size without obscuring the clause Given the panel is open When the user types or edits elsewhere in the editor Then editor interactions remain uninterrupted and the panel does not block caret movement, selections, or clicks

Plain-Language Risk Explanation with Severity and Impact

Given a clause has one or more risk flags When the panel opens Then it displays a risk title, a severity level (Low, Medium, or High), and a business impact summary for the selected clause Given the explanation is displayed Then the body text reads at or below a 9th-grade level as measured by Flesch-Kincaid (or equivalent) Given rationale sources exist When the panel renders Then at least one link to underlying rationale or policy is present and opens without losing editor state Given multiple risks apply to the clause When the panel renders Then risks are listed in descending severity and the top item is focused

Ranked Safer Alternatives with One-Click Apply and Compatibility Badges

Given alternatives are available for the selected clause When the panel renders Then it shows a ranked list by risk reduction score, and each item displays a short rationale Given the user clicks Apply on an alternative When the action completes Then the clause text updates in the editor, an inline diff is shown, and focus returns to the updated clause Given an alternative has been applied When the user performs Undo or Redo (via shortcut or panel control) Then the clause text reverts or reapplies accordingly and the risk panel updates to reflect the current state Given document metadata includes jurisdiction and contract type When alternatives are listed Then each alternative displays badges indicating compatibility with the current jurisdiction and contract type Given the clause text has changed via an applied alternative When risk analysis re-runs Then the panel updates severity and compatibility badges to reflect the new text

Quick Filters Adjust Alternatives List

Given the panel is open When the user toggles any quick filter (Minimize Liability, Maintain IP, Accelerate Payment) Then the alternatives list updates to include only items matching all selected filters Given multiple filters are selected When the user clears filters Then all filters reset and the full alternatives list is restored Given filters are changed When the panel re-renders Then the current filter state is visibly indicated and persists while the panel remains open

Keyboard Shortcuts and WCAG 2.2 AA Compliance

Given the editor has focus When the user presses the defined shortcut to open or close the risk panel Then the panel opens or closes and focus moves predictably to the panel header or back to the editor Given the panel is open When the user navigates with the keyboard Then all interactive controls are reachable in logical tab order with visible focus indicators and no keyboard traps Given the panel content updates dynamically (e.g., alternatives re-ranked, status changes) When the update occurs Then a screen reader announces the change via ARIA live regions without interrupting typing Given UI elements in the panel Then they meet WCAG 2.2 AA for color and non-text contrast, keyboard accessibility, focus order and visibility, and name/role/value semantics Given keyboard usage When the user invokes shortcuts for Next Risk, Previous Risk, Apply Selected Alternative, and Toggle Filters Then the associated actions execute successfully

Localization and View Density Preference Persistence

Given the application language is set to a supported locale When the panel renders Then all visible strings (severity labels, filter names, badges, actions) are localized Given a right-to-left locale is active When the panel renders Then layout mirrors appropriately and text flows RTL without clipping or overlap Given longer translations When the panel renders Then the layout accommodates up to 30% text expansion without truncation or overlap Given the user selects a view density (Comfortable or Compact) When the panel is reopened in a new session Then the last chosen density is restored Given the view density is changed When the panel re-renders Then content reflows without obscuring editor text or causing unexpected scrolling

Telemetry Captures Impressions, Selections, and Dismiss Reasons

Given the panel becomes visible for a clause When it first renders Then an impression event is logged with timestamp and anonymized document and clause identifiers, jurisdiction, and contract type Given the user applies an alternative When the action completes Then a selection event is logged including alternative ID, risk reduction score, compatibility status, and input method (mouse or keyboard) Given the panel is closed or collapsed by the user When the action occurs Then a dismiss event is logged with a standardized dismiss reason (Resolved, Not Relevant, Already Compliant, Postpone, Other) and capture method (click, keyboard, scroll) Given telemetry events are logged Then no contract body text or personally identifiable information is stored in the payloads

One-Click Safe Apply with Diff Preview

"As a negotiator on a live call, I want to apply safer wording with a single click and preview the exact changes so that I avoid mistakes and keep negotiations moving."

Description

Implement atomic replacement of risky clauses with selected safer alternatives, including a side-by-side or inline diff preview showing changes before commit. Preserve numbering, references, and formatting. Validate cross-references and defined terms; prompt to update definitions if required. Provide undo/redo and a change note entry for audit. If the counterparty is present in a shared session, show a “proposed change” mode instead of immediate apply, integrating with SnapAgree’s suggestion/track-changes system.

Acceptance Criteria

Atomic Safe Apply Preserves Structure

Given a document with a flagged risky clause and a selected safer alternative When the user clicks Apply Safely Then only the targeted clause is replaced atomically with the selected alternative And numbering, section hierarchy, list styles, and surrounding formatting are preserved And internal anchors/IDs are retained so existing cross-references continue to resolve And the operation completes within 1.0 second on a 15-page contract

Diff Preview Accuracy and Toggle

Given a risky clause and a selected safer alternative When the user opens Diff Preview Then a side-by-side view and an inline view are available and selectable And insertions/deletions are highlighted to reflect exactly the textual delta and nothing else And switching between views preserves scroll position and current selection And the preview renders within 1.5 seconds for a 20-page document

Cross-Reference and Definitions Validation

Given the replacement introduces/removes defined terms or affects cross-references When the user attempts to apply the change Then the system validates all cross-references and defined terms And blocks commit if any broken references or undefined terms exist And displays a list of issues with suggested fixes or definition updates And enables Apply only after re-validation passes with zero blocking issues

Required Change Note and Audit Log

Given an Apply or Proposed Change action is initiated When the user confirms the action Then a non-empty change note of at least 3 characters is required And an audit entry is recorded with timestamp, user ID, session ID, clause identifier, before/after text hashes, selected alternative ID, jurisdiction value, and diff summary And the audit entry appears in the change history UI and API within 2 seconds

Undo/Redo Restores All State

Given one or more changes have been applied or accepted When the user triggers Undo Then the document content, numbering, cross-references, definitions, and formatting revert to the exact prior state And the audit trail records the reversal and links it to the original change And when the user triggers Redo the change reapplies identically And the undo/redo stack persists across autosave and session reconnects

Shared Session Proposed Change Mode

Given the counterparty is present in an active shared session When the user clicks Apply Safely Then the system creates a Proposed Change instead of committing immediately And the change appears as a tracked suggestion attributed to the proposer And the counterparty receives a real-time notification and can Accept or Reject And on Accept the change commits with an audit entry noting counterparty acceptance; on Reject no document content is altered

Jurisdiction-Aware Alternative Application

Given the workspace or document jurisdiction is set or detected When the user selects a safer alternative Then suggested alternatives are filtered/prioritized for the active jurisdiction with visible compliance flags And the applied text uses the selected jurisdiction variant And if jurisdiction is unknown the user is prompted to choose before apply And the Diff Preview indicates the jurisdiction basis of the alternative And the audit entry records the jurisdiction used

Risk Tolerance Profiles

"As a small-business owner with varying deal sizes, I want to set my risk tolerance so that recommendations match my appetite and context."

Description

Allow users to configure risk tolerance profiles (Conservative, Balanced, Aggressive, or custom) that weight severity thresholds and preferred remedies (e.g., cap multiples, indemnity carve-outs, payment terms). Profiles influence which flags are shown, their order, and which alternative is defaulted. Support workspace-level defaults and per-document overrides. Provide starter templates for common service businesses and a wizard to calibrate based on deal size and buyer type. Persist securely and sync across devices.

Acceptance Criteria

Create and Manage Risk Tolerance Profiles

Given I am a workspace admin and provide a unique profile name within the workspace When I create a custom risk tolerance profile Then the profile is saved and appears in the profile selector for that workspace Given I enter a duplicate or blank profile name When I attempt to save Then I see a validation error and the profile is not created Given I configure severity thresholds and weights within allowed ranges (e.g., 0–100) and preferred remedies (e.g., liability cap multiple 0.5–5.0x, indemnity carve-outs toggles, payment terms NET 0–90) When I save the profile Then the values persist exactly as set Given system profiles (Conservative, Balanced, Aggressive) exist When I view them Then I can see settings and clone but cannot edit or delete the originals Given I have a custom profile When I rename, clone, archive, or unarchive it Then the action succeeds and the change is reflected immediately in the selector and API responses Given a custom profile is set as workspace default or assigned to any active document When I attempt to delete it Then deletion is blocked with a clear message and I am offered to archive instead

Profile Influences Risk Flags and Defaults

Given an open document with recognized clauses and a selected profile When I switch the profile from Balanced to Conservative Then the risk flags list reorders and/or increases based on the profile’s severity thresholds within 1 second of selection Given a selected profile with a minimum severity threshold When flags are recalculated Then flags below the threshold are hidden unless I toggle “Show all” Given a suggestion card offers multiple safer alternatives for a flagged clause When a profile is selected Then the alternative whose attributes best match the profile’s preferred remedies is preselected by default Given I toggle between profiles A and B When I return to profile A Then the ordering and defaulted alternatives revert to profile A’s logic consistently Given profile-driven defaults are applied When I click “Apply” on the suggestion Then the chosen alternative matches the profile’s preselected choice unless I manually change it

Workspace Default and Per-Document Override

Given a workspace default profile is set to Balanced When a new document is created in that workspace Then the document’s profile is Balanced by default Given a document with the workspace default profile When a user with edit permission overrides the profile to Conservative for that document Then only that document’s profile changes and the workspace default remains unchanged Given a document with an overridden profile When the workspace default later changes to Aggressive Then the overridden document retains its override and other non-overridden documents adopt Aggressive on next open or analysis Given a document with an overridden profile When I select “Reset to workspace default” Then the document reverts to the current workspace default and the override indicator is cleared Given documents display profile info When I open the document header Then I see the current profile name and an explicit “Overridden” badge if applicable

Starter Templates for Common Service Businesses

Given I open the profile templates gallery When I browse categories (e.g., Design, Marketing, Software Development, Consulting) Then I see at least one starter template per category with descriptions Given I select a template (e.g., Freelance Designer) When I click “Use template” Then a new unsaved custom profile is created pre-populated with the template’s thresholds and preferred remedies Given templates are read-only When I attempt to edit template fields directly Then the UI prevents edits and prompts me to clone/use template instead Given I created a custom profile from a template When I save it with a unique name Then it is available in the workspace and can be set as default or applied per document Given I apply a template-derived profile to a document When I run risk analysis Then the resulting flag order and default remedies reflect the template’s settings

Calibration Wizard by Deal Size and Buyer Type

Given I launch the calibration wizard When I input required fields (deal size range, buyer type, jurisdiction) Then the “Continue”/“Finish” button becomes enabled and validation errors clear Given I complete the wizard with valid inputs When recommendations are generated Then I see a recommended profile (system or custom-derived) with a preview of key setting deltas before applying Given I accept the recommendation When I choose “Apply to current document” Then the document’s profile updates immediately and flags/defaults recompute within 2 seconds Given I accept the recommendation When I choose “Save as custom profile” and provide a unique name Then the profile is saved to the workspace and appears in selectors Given the wizard is jurisdiction-aware When I change jurisdiction input Then the recommended remedies adjust (e.g., liability cap multiple suggestions) and the preview reflects the change before I apply

Secure Persistence and Cross-Device Sync

Given I save a profile or change defaults When the request completes Then data is stored encrypted at rest and transmitted over TLS 1.2+ (or higher) Given I update a profile on Device A When I open the profiles list on Device B (same user/workspace) Then the change appears within 10 seconds without requiring an app restart Given conflicting edits occur to the same profile from two clients within 30 seconds When both saves succeed Then last-writer-wins is applied and an audit entry records both versions with timestamps and editors Given I edit profiles while offline When connectivity is restored Then queued changes sync automatically, conflicts are resolved per policy, and I am notified of outcomes Given a profile is archived When a document referencing it is opened Then the document remains usable and shows the archived profile with an option to switch to an active profile

Role-Based Access and Auditability

Given workspace roles are enforced When a non-admin user attempts to create, edit, delete, or set a workspace default profile Then the action is blocked with a clear permission error Given a document owner/editor When they open a document Then they can override the profile for that document regardless of admin status, without altering the workspace default Given any profile change occurs (create, edit, archive, default change, document override, applied alternative) When I view the audit log Then I see who, what changed (before/after), where (workspace/document), and when (timestamp) with export to CSV available Given audit retention is configured for at least 90 days When I query the audit log for a past change within that window Then the entry is retrievable and complete Given admin views profiles When they filter the audit log by profile name or document ID Then only relevant entries are shown

Decision Audit Log

"As a founder who may need to justify decisions later, I want a clear record of what risks were flagged and what I chose so that I can defend my negotiation choices if challenged."

Description

Capture an immutable log of risk flags shown, alternatives offered, user selections or dismissals, timestamps, rule versions, and diffs applied. Allow export as a PDF or JSON report attached to the contract record. Surface a timeline within the document history for later review or legal escalation. Redact sensitive personal data per privacy settings. Ensure logs are tamper-evident and retained per workspace policy with configurable retention periods.

Acceptance Criteria

Immutable Event Capture for Risk Decisions

Given a user edits contract terms and a risk flag is triggered When the user views the flag and chooses either "Apply safer alternative" or "Dismiss" Then the system appends an event with fields {event_type, contract_id, workspace_id, user_id, timestamp_utc (ISO 8601), rule_engine_version, rule_id, suggested_clause_id, diff_patch} And the event includes previous_event_hash and current_event_hash computed with SHA-256 over a canonical JSON of the event body And the append completes within 300 ms at p95 And update/delete operations on prior events are rejected with 409 and are themselves logged as integrity_violation events

Tamper-Evidence Verification

Given an audit log exists for a contract When integrity verification is requested via UI "Verify" or API POST /audit/verify Then the system validates the full hash chain and returns status "verified" with last_event_hash and event_count if all links are valid And if a mismatch is found, returns status "corrupted" with first_bad_event_index and blocks export with error code AUDIT_INTEGRITY_FAILED And a verification record is appended with verifier_id, timestamp_utc, and result

Export Report Attachment to Contract Record

Given a contract has audit events and the requester has Exporter role When the user exports as PDF or JSON Then the system generates the report within 10 seconds at p95 including header {contract_id, contract_version, created_by, created_at_utc, rule_engine_version}, chronological event list, summaries, and a report_hash And the export is attached to the contract record as an immutable attachment with metadata {attachment_id, format, size_bytes, hash, version} And the attachment is downloadable via UI and GET /contracts/{id}/attachments/{attachment_id} And regenerating creates a new version; prior versions remain accessible and unchanged

Timeline in Document History

Given a document with audit events When the user opens Document History > Decision Timeline Then the first page (50 events) renders within 2 seconds at p95, ordered by sequence_number And filters {event_type, user_id, date_range, rule_version} are available and filtered results load within 1.5 seconds at p95 And selecting an event opens a panel showing human-readable diff highlighting (additions/deletions) and the triggering rule label and explanation

Privacy Redaction per Workspace Settings

Given workspace privacy settings define PII patterns and redaction_mode=mask When events are displayed in UI or exported Then PII fields are masked per policy while the stored canonical event used for hashing remains unredacted And roles {Owner, Compliance} can reveal PII via explicit action; each reveal is logged with who/when/why And exports include redaction_applied=true and redaction_policy_version

Retention and Legal Hold Compliance

Given workspace retention_days=N and no legal hold on the contract When an event age exceeds N days Then the event is logically purged within 24 hours and a purge_tombstone event is appended recording range and reason And backups and search indexes remove purged content within 72 hours And if a legal hold exists, no purge occurs until the hold is released; hold create/update/delete actions are logged

Access Control and Multi-Tenant Isolation

Given a signed-in user requests to view timeline or export When the user lacks a required role in the workspace Then the request is denied with 403 and an access_denied audit event is appended And all queries are constrained by workspace_id; cross-tenant access attempts are blocked and a security_alert event is emitted And API rate limit of 60 exports/hour/workspace is enforced with 429 and retry_after on exceedance

Recap Readback

Auto-generates a clear summary of key terms—what’s included, dates, price, payment schedule, IP/usage—and presents it on-screen or reads it aloud for final confirmation. Captures the “yes” moment and reduces post-call misunderstandings.

Requirements

Key Term Extraction & Normalization

"As a small-business owner, I want the system to automatically extract the key terms from my contract and discussion so that the recap reflects exactly what we agreed without me manually hunting for details."

Description

Implement an NLP-driven extraction service that pulls core deal terms (scope/inclusions, deliverables, dates/milestones, total price, payment schedule, IP/usage rights, change orders/out-of-scope, termination, and warranty/limitations) from the active SnapAgree contract draft and any linked negotiation artifacts (structured deal inputs, proposal data, chat/notes, call transcript). Normalize results into a canonical schema with field-level confidence scores, source citations (section/line/timecode), and validation rules. Expose the data via an internal API consumed by the recap generator and risk flagger, supporting custom fields and regional formatting for currency and dates.

Acceptance Criteria

Multi-source core term extraction

Given an active SnapAgree contract draft and linked artifacts (structured deal inputs, proposal, chat/notes, call transcript) When the extraction service runs Then it extracts the following fields: scope/inclusions, deliverables, dates/milestones, total price, payment schedule, IP/usage rights, change orders/out-of-scope, termination, warranty/limitations And it merges duplicate mentions across sources into a single canonical value per field where possible And on the project's gold test set it achieves macro-average F1 >= 0.87 across all fields, with total price and dates/milestones F1 >= 0.95

Normalization to canonical schema with regional formatting

Given locale and currency settings are provided (e.g., en-US with USD, en-GB with GBP) When normalization occurs Then dates are output as ISO 8601 strings plus a locale_formatted string following the requested locale And currency values include amount (decimal), currency (ISO 4217), and locale_formatted respecting regional separators and symbol placement And payment schedules are normalized to an array of entries {amount, currency, due_date, trigger, period} And numeric amounts are rounded to the currency's minor units And all fields validate against the canonical JSON schema without errors

Field-level confidence scoring

Given any extracted field When the service returns results Then each field includes a confidence score between 0.0 and 1.0 with at most three decimal places And on the gold test set, probability calibration yields Brier score <= 0.12 And fields with confidence < 0.70 are flagged as low_confidence=true

Source citations for traceability

Given extracted values originate from multiple sources When the service returns results Then each field value includes at least one citation with source_type and pointer: document -> {section, line_range}, transcript -> {timecode_start, timecode_end}, structured -> {json_pointer} And each citation pointer resolves to the original content without error And values synthesized from multiple sources include >= 2 distinct citations

Validation rules and conflict detection

Given extracted total price and payment schedule When validation runs Then sum(payment_schedule.amounts) equals total price within currency minor units or a validation_error with code "PAYMENT_SUM_MISMATCH" is emitted And if conflicting values for the same field exist across sources, a "FIELD_CONFLICT" error is emitted including all competing values and their citations And milestone and due dates are chronological and not in the past relative to contract_effective_date or errors "DATE_ORDER_INVALID" / "DATE_IN_PAST" are emitted

Internal API for recap and risk services

Given a request to POST /v1/extractions with document_id and optional context (locale, custom_fields, request_id) When the request is valid Then the API responds 202 with a job_id; a subsequent GET /v1/extractions/{job_id} returns 200 with status=completed and a payload conforming to the published OpenAPI schema And requests with the same request_id are idempotent And P95 end-to-end latency for documents <= 30 pages and transcripts <= 60 minutes is <= 2.5 seconds after job start And error cases return typed errors with codes and actionable messages (4XX for client, 5XX for server)

Custom fields extraction and extensibility

Given custom field definitions are provided via schema extension (name, type, patterns, examples) When extraction runs Then custom fields are attempted and returned under custom_fields with normalized values appropriate to type And missing custom fields are returned with status="not_found" and no value And adding new custom fields does not break existing consumers; unknown fields are ignored by older clients while still present in the payload And clients can request a subset via include_fields and the API returns only requested fields

Plain-Language Recap Generator

"As a freelancer, I want a clear, plain-language summary of the deal so that my client and I can quickly confirm we’re aligned without parsing legal text."

Description

Create a template-driven natural-language generation layer that converts normalized terms into a concise, non-legalese summary. Provide configurable tone (friendly/professional), length (brief/detailed), and formatting (headings/bullets). Localize currency, dates, and numbering per locale. Include inline uncertainty indicators when confidence is low and gracefully omit fields not present. Allow brand-specific phrasing via tenant-level templates. Output both structured JSON and human-readable text for display and speech synthesis.

Acceptance Criteria

Generate friendly, brief, bullet summary from normalized terms

Given normalized contract terms including scope, dates, price, payment schedule, and IP/usage And configuration tone=friendly, length=brief, formatting=bullets When the recap generator runs Then the output text uses bullet formatting only And the output contains only fields present in the input And the output is concise with total word count between 60 and 120 words And no sentence exceeds 25 words And the text achieves Flesch Reading Ease >= 60 and Flesch-Kincaid Grade <= 8 And the text does not contain blocked legalese terms: herein, aforementioned, indemnify, witnesseth

Localize currency, dates, and numbering for en-GB tenant

Given normalized terms include a price of 1234.56 USD and dates such as 2025-09-14 And tenant locale=en-GB And length setting is brief When the recap generator runs Then currency appears as £1,234.56 (symbol before amount, comma thousands, dot decimals) And dates appear as 14/09/2025 for brief summaries And switching length to detailed produces dates as 14 September 2025 And numbers >= 1,000 use comma separators and decimals use a dot And no US-style formats appear (no $ symbol, no MM/DD/YYYY)

Insert inline uncertainty indicators below confidence threshold

Given some extracted fields have confidence scores below the default threshold of 0.70 When the recap generator runs Then an inline indicator is appended next to each low-confidence value in text in the form of "(to be confirmed)" or "(low confidence)" And fields at or above the threshold have no uncertainty indicator And the JSON output includes an uncertainties array listing fieldName, value, and confidence for each low-confidence field And when no fields are below the threshold, no uncertainty text appears anywhere in the summary

Omit absent fields and maintain grammatical flow

Given normalized terms are missing IP/usage and payment schedule And formatting is set to headings or bullets When the recap generator runs Then the summary does not include empty headings, placeholders (N/A, -, none), or dangling punctuation/colons And phrasing adjusts grammatically (e.g., "Start date" instead of "Start/End dates" when only one date exists) And there are no extra blank lines, stray commas, or double spaces And bullet numbering or symbols remain continuous without gaps

Apply tenant-specific brand phrasing with fallback to default

Given a tenant has an active template with id "acme-v2" and defined brand phrases and placeholders When the recap generator runs for that tenant Then the generated text uses the tenant’s brand-specific phrasing where defined And all template placeholders are fully resolved to values or default fallbacks; no "{{...}}" tokens remain And any segment not defined by the tenant template falls back to the SnapAgree default template And the JSON output includes template metadata: tenantId, templateId, and templateVersion

Produce synchronized structured JSON and human-readable text

Given normalized terms and configuration length=detailed, formatting=headings, tone=professional When the recap generator runs Then the response includes both summaryText (human-readable) and summary (structured JSON) in one payload And every value rendered in summaryText has a corresponding canonical field in summary JSON with the same value after localization And summaryText length is between 120 and 400 words for detailed mode And summaryText contains only plain text and newlines (no HTML markup) And if includeSsml=true is provided, an ssml field is returned that is valid SSML and semantically mirrors summaryText

Handle invalid inputs and meet response time SLA

Given a valid request with up to 40 normalized fields When the recap generator runs under normal load Then p95 end-to-end generation time is <= 1.5 seconds and p99 <= 2.5 seconds server-side And for an invalid locale code, the system falls back to en-US without failing and records a recoverable warning in logs And for malformed input, the API returns HTTP 400 with machine-readable error codes and no partial summaryText is returned And if a tenant template cannot be found, the default template is used and summary.template.fallback=true is set in JSON

On-screen & Voice Readback Delivery

"As a service business owner, I want the recap shown and read aloud during the call so that my client can hear and see exactly what they’re agreeing to."

Description

Build a responsive UI component that presents the recap as a modal or full-screen panel with prominent key fields and optional drill-down to sources. Integrate a text-to-speech engine with selectable voice, speed, and language to read the recap aloud. Provide playback controls (play/pause/restart) and captions, and meet WCAG 2.1 AA accessibility standards. Support web and mobile form factors, with graceful degradation to on-screen only when audio permissions are denied.

Acceptance Criteria

Modal/Full-Screen Recap Presentation

- Given a recap is generated, When the user selects "Review Recap", Then the component opens as a modal on desktop and as a full-screen panel on mobile and renders within 500 ms. - Given the component is open, When the viewport is resized across the 640 px breakpoint, Then the layout adapts between modal and full-screen without content loss, clipping, or overlap. - Given the component is open, When the user activates the Close control or presses Escape, Then the component closes and programmatic focus returns to the triggering control.

Prominent Key Fields with Drill-Down Sources

- Given a recap exists, Then the following key fields are displayed above the fold with clear labels: Included Items/Scope, Dates/Timeline, Price, Payment Schedule, IP/Usage. - Given a key field has a source clause, When the user chooses "View Source", Then a drill-down view shows the exact source text with the matched phrase highlighted and a link back to the original section. - Given a key field has no source available, Then the "View Source" control is not shown for that field. - Given the recap content updates, Then all displayed key fields refresh to reflect changes within 300 ms.

Text-to-Speech with Selectable Voice, Speed, and Language

- Given recap text is available, When the user presses Play, Then TTS speaks the recap using the selected voice, speed, and language. - Given the voice selector, Then at least two distinct voices are available for the current language; selecting a voice updates the next playback (or immediately if playing). - Given the speed control, Then the user can set speed from 0.75x to 1.5x in 0.05 increments and playback reflects the selection within 150 ms. - Given the language selector, When a supported language is chosen, Then TTS and captions switch to that language; if unsupported, Then the system falls back to en-US and displays a non-blocking notice.

Playback Controls and Captions

- Given the component is open, Then Play, Pause, and Restart controls are visible and operable via mouse, touch, and keyboard (Tab/Enter/Space). - Given audio is playing, When the user presses Pause, Then playback pauses within 150 ms and the control state updates to Resume. - Given audio is paused or finished, When the user presses Restart, Then playback restarts from the beginning within 300 ms. - Given captions are enabled, Then captions mirror the spoken text and are time-synchronized within ±250 ms; users can toggle captions on/off. - Given TTS fails or is slow, Then captions still render from the prepared text and a non-blocking error banner appears without blocking on-screen recap use.

WCAG 2.1 AA Accessibility Compliance

- Given the recap opens, Then focus moves to the panel heading, focus is trapped within the panel, and Escape/Close returns focus to the trigger. - All interactive controls meet minimum 44x44 px target size and 4.5:1 contrast; text meets AA contrast. - All controls expose correct roles, names, and states via ARIA; the component is fully operable by keyboard without timing-dependent gestures. - No audio plays without explicit user action; a visible transcript/captions option is provided. - Automated audit (axe/Pa11y) reports 0 critical/serious violations; manual NVDA and VoiceOver checks confirm correct announcements for key controls.

Graceful Degradation When Audio Permissions Are Denied

- Given the browser blocks audio playback or TTS APIs are unavailable/denied, Then voice options and play controls are disabled with an explanatory tooltip, and the on-screen recap remains fully functional. - Given the user enables audio permissions, When the user clicks Retry or reopens the component, Then TTS initializes and controls become enabled without a page reload. - Given TTS initialization or playback fails, Then the system logs the error, shows a non-blocking alert, and the UI does not freeze or crash.

Responsive Web and Mobile Support

- Given a viewport ≥ 640 px, Then the recap opens as a centered modal (max width 800 px); for < 640 px, it opens full-screen. - The layout supports portrait and landscape without horizontal scrolling; all controls remain visible and usable down to 320 px width. - On touch devices, tap targets are ≥ 44x44 px and scroll areas do not obstruct access to controls. - Under 3G Fast conditions, the component’s UI loads under 150 KB gzipped and becomes interactive within 2 seconds.

Confirmation Capture & Binding

"As a contract sender, I want to capture a definitive “yes” tied to the exact recap and contract version so that I have a clear audit trail and fewer post-call disputes."

Description

Implement multi-modal confirmation capture: a one-click "Yes, that’s correct" action and a verbal "yes" capture with short audio snippet. Record timestamp, user/client identity, device/IP, recap text hash, normalized term payload, and linked contract version. Store an immutable audit record and attach a confirmation certificate and recap as an appendix to the contract. Provide a shareable confirmation record and expose events/webhooks for downstream systems. Include safeguards to block confirmation if mandatory fields are missing.

Acceptance Criteria

One-Click Confirmation Capture

Given the recap readback is displayed and all mandatory fields are complete And the client is identified (session or invite link) and the contract version is locked When the client clicks "Yes, that’s correct" Then a confirmation event is created within 2 seconds with status "captured" And the event is linked to the current contractVersionId And the UI displays a success state with a confirmationId And the operation is idempotent: repeated clicks within 60 seconds return the same confirmationId

Voice "Yes" Capture with Audio Snippet

Given the readback prompt requests a verbal confirmation and microphone permission is granted When the client says an affirmative (e.g., "yes") within 10 seconds of the prompt Then the system stores an audio snippet 2–10 seconds long capturing the affirmation And a transcript is saved with confidence ≥ 0.90 indicating an affirmative And the audio and transcript are attached to the confirmation event And if permission is denied or no affirmative is detected, no confirmation is recorded and the user is prompted to retry or use one-click

Evidence Metadata Completeness and Hash Integrity

Given a confirmation (click or voice) is captured Then the persisted record includes non-null fields: timestamp (UTC ISO 8601), client identity (name/email or clientId), user/accountId, device info (userAgent and deviceFingerprint), IP address, contractVersionId, recapTextHash, normalizedTermPayload And recapTextHash equals the SHA-256 of the normalized recap text used in the readback And normalizedTermPayload includes: parties, inclusions, dates, totalPrice, currency, paymentSchedule, ipUsage, and matches the linked contract version And any attempt to save a record missing required fields is rejected with validation errors and no record is created

Immutable Audit Record and Certificate Attachment

Given a confirmation record exists Then it is stored in an append-only audit log with a unique confirmationId And attempts to modify or delete the record via application APIs are blocked; only a new superseding record with parentId can be created And a confirmation certificate (PDF) is generated within 5 seconds and appended as an appendix to the contract document And the certificate includes: confirmationId, timestamp, parties, client/user identities, device/IP, recapTextHash, normalizedTermPayload summary, and audio reference/checksum when applicable And downloading or sharing the contract shows the appended certificate and recap

Shareable Confirmation Record and Access Controls

Given a confirmation record exists When a share link is generated Then the link is a signed, time-bound URL with a configurable expiry (default 30 days) that renders the recap and certificate And authenticated users with appropriate permissions can access without the share link And unauthorized requests receive 403/404 with no data leakage And the share view displays confirmationId and essentials while omitting sensitive internal IDs And revoking the link prevents access within 1 minute

Webhook Event Emission and Delivery Guarantees

Given a confirmation is captured Then a confirmation.captured webhook is sent within 5 seconds to all active endpoints And the payload contains: confirmationId, contractVersionId, timestamp, client/user identities, device/IP, recapTextHash, normalizedTermPayload, and deliveryAttemptId And each request is signed using a shared secret and includes signature and timestamp headers And delivery retries use exponential backoff for up to 24 hours or until a 2xx response And retries are idempotent via an idempotency key; duplicate deliveries are safely ignored by consumers And admins can manually replay events for a given confirmationId

Mandatory Fields Safeguard Blocks Confirmation

Given any mandatory field is missing or invalid (e.g., parties, inclusions, dates, totalPrice, currency, paymentSchedule, ipUsage) Then the "Yes, that’s correct" button is disabled and the voice flow does not prompt for verbal confirmation And inline validation specifies which fields require completion And direct API attempts to force confirmation are rejected with HTTP 422 and an audit entry is recorded And once all mandatory fields are valid, confirmation controls enable within 1 second

Consent, Compliance & Privacy Controls

"As an owner concerned about liability, I want built-in consent prompts and secure handling of recordings so that confirmations are legally compliant and private."

Description

Add jurisdiction-aware consent prompts for audio capture (one-party vs. two-party consent), with dynamic messaging and logging of explicit consent decisions. Encrypt audio, transcripts, and recap records at rest and in transit; enforce role-based access and retention policies with configurable deletion windows. Map confirmation flow to e-sign compliance requirements and document accessibility (captions/ARIA). Provide GDPR/CCPA controls (export/delete) and comprehensive audit logs to support SOC 2 evidence collection.

Acceptance Criteria

Jurisdiction‑Aware Consent Prompting and Logging

Given a session with detected jurisdictions for all participants When Recap Readback requests audio capture Then consent messaging matches one‑party or two‑party requirements for those jurisdictions Given two‑party consent is required When not all required parties provide explicit consent (click or verbal “yes”) Then recording does not start and no audio is stored Given consent is granted by all required parties When recording begins Then a consent record is created with session ID, party identifiers, jurisdiction basis, consent method (click/voice), locale, timestamp, and message version Given any party withdraws consent When withdrawal is recorded Then recording stops immediately and a withdrawal event is logged; subsequent audio is not stored

Recap Confirmation “Yes” Capture and Evidence Package

Given the recap of key terms is presented on‑screen or read aloud When the customer affirms “Yes, I agree” via click or voice Then the affirmation is captured with timestamp, user identity, method, and bound to the exact recap version and contract/envelope ID Given an affirmation is captured When the evidence package is generated Then it includes the audio snippet (±10 seconds), aligned transcript segment, cryptographic hash of the recap content, and a link to the e‑sign envelope Given the customer says “No” or does not respond within 30 seconds When the flow times out Then a non‑consent outcome is recorded and e‑sign progression is blocked

Encryption In Transit and At Rest for Audio, Transcripts, and Recaps

Given data classes audio, transcript, recap, and consent logs When stored at rest Then they are encrypted with AES‑256 or stronger and keys are managed in a KMS with rotation at least annually Given any client or service connects to send or retrieve these data When transport is established Then TLS 1.2+ with modern ciphers is enforced and plaintext connections are rejected Given an operator without key access attempts to read storage directly When data are inspected Then only ciphertext is observable and access is denied and logged

Role‑Based Access Control and Access Logging

Given roles Owner, Admin, Legal, Sales, and Viewer When accessing audio, transcripts, or recaps Then Owner/Admin/Legal have full access, Sales has access only to records they own, Viewer has read‑only to recaps without audio, and all unauthorized requests receive 403 Given any access to protected resources When a request is authorized or denied Then an audit event logs actor, role, resource ID, action, decision, and timestamp Given a user’s role changes When the change is saved Then new permissions take effect within 5 minutes and are reflected in subsequent access decisions

Configurable Retention and Deletion Windows

Given workspace‑level retention settings per data class (audio, transcript, recap) with defaults When a record exceeds its configured retention window Then it is irreversibly deleted and no longer retrievable via UI or API Given an admin updates retention settings When the change is saved Then future deletions follow the new windows and existing records’ deletion dates are recalculated accordingly Given a legal hold is placed on a record When retention processing runs Then the held record is excluded from deletion until the hold is lifted and the exception is logged

GDPR/CCPA Export and Delete Controls

Given a verified data subject export request When processed in‑app Then a machine‑readable export is available within 5 minutes containing audio, transcripts, recaps, consent records, and related metadata for that subject Given a verified data subject deletion request When processed Then personal data are deleted or anonymized within the configured retention SLA and a confirmation receipt with scope and timestamp is provided Given any DSR action (export or delete) When completed Then an immutable audit entry records requester, verifier, scope, processor, timestamp, and outcome

Accessible Confirmation Flow (WCAG/ARIA) and Captions

Given the recap is displayed on‑screen When evaluated with screen readers and keyboard navigation Then all interactive elements have accurate ARIA labels, focus order is logical, and color contrast meets WCAG 2.1 AA Given audio readback is used When captions are enabled Then synchronized captions are displayed and a full transcript is available for download Given automated accessibility tests (axe or Lighthouse) run on the confirmation view When executed Then there are zero critical violations and no more than two minor issues Given a user navigates with keyboard only When progressing through the confirmation flow Then the flow is fully operable without a mouse, including activating consent controls

Edit-and-Regenerate Loop

"As a user, I want to tweak the recap terms and regenerate the summary so that I can correct errors or clarify language before asking for confirmation."

Description

Allow users to adjust extracted fields or wording before confirmation through inline editing of scope, dates, price, payment schedule, and IP terms. Validate entries (currency/date formats, arithmetic checks) and update the normalized data. Regenerate the recap on demand, preserving prior versions with diffs and editor identity. Provide guardrails to flag divergences from the underlying contract and offer quick actions to push approved edits back into the contract draft.

Acceptance Criteria

Inline Edit of Price with Currency and Arithmetic Validation

Given a recap with extracted Price and Payment Schedule When the user edits the Price inline (currency and amount) and clicks Save Then the currency must be a valid ISO 4217 code or locale symbol and the amount a positive number with max 2 decimals And the sum of Payment Schedule amounts must equal the Price for fixed-price projects, otherwise an inline error is shown on offending fields And the Regenerate Recap action remains disabled until all price-related errors are resolved And the normalized data store is updated with currency, amount (in minor units), and recalculated totals on successful save And a success toast appears within 1 second of save

Edit Dates with Format and Temporal Validation

Given Start Date, End Date, Milestones, and Payment Due Dates are present in the recap When the user edits any date field and clicks Save Then input accepts locale date formats but stores values in ISO 8601 with timezone And End Date must be on or after Start Date; milestones and due dates must fall within the project date range And invalid entries display inline error text and aria-describedBy associations for accessibility And the Confirm Recap action is disabled while any date errors exist And normalized data is updated on successful validation and the UI reflects the new dates

IP Terms Edit with Divergence Guardrail and Push-back

Given the recap shows IP ownership and license terms derived from the contract draft When the user edits IP terms to change ownership, license scope, sublicensing, duration, or territory Then the system compares against the underlying contract clause and displays a divergence warning banner listing changed dimensions And quick actions are available: View Source Clause, Apply Change to Draft, and Revert Edit And selecting Apply Change to Draft shows a redline diff and, on confirm, updates the contract draft with tracked changes and returns a success confirmation And an audit record captures editor ID, timestamp, changed fields, and divergence status

Regenerate Recap with Versioning and Diff

Given the user has saved one or more edits When the user clicks Regenerate Recap Then a new recap is generated from normalized data within 3 seconds at the 95th percentile And the prior recap version is preserved with incremented version number, editor identity, timestamp, and a change summary And Version History allows selecting any two versions to view a text diff highlighting added, removed, and modified phrases And the current recap displays its version label (e.g., vN) matching the latest entry in Version History

Version History Access Control and Audit Logging

Given multiple collaborators with roles (Owner, Editor, Viewer) When a user opens Version History Then Owners and Editors can view editor identities, diffs, and perform Apply Change to Draft; Viewers can only read versions and diffs without editing controls And unauthorized actions (e.g., Viewer attempting Apply Change) are blocked with a 403-style UI message and no data change And all version views and apply actions are logged with user ID, timestamp, version IDs, and outcome

Readback Sync After Regeneration

Given the recap has been regenerated after edits When the user views the on-screen summary and triggers audio readback Then both outputs reflect the latest normalized data for scope, dates, price, payment schedule, and IP terms with no stale values And the audio readback is generated within 2 seconds of request and includes each changed field in plain language And a matching version label or checksum is displayed alongside the screen recap and recorded in the audio transcript metadata

Validation Error Handling and Regenerate Control

Given one or more fields fail validation (currency, date, arithmetic) When the user attempts to click Regenerate Recap Then the action is blocked and focus moves to the first invalid field with a visible error message And an ARIA live region announces the error state for assistive technologies And once all errors are corrected, the Regenerate Recap action becomes enabled and proceeds successfully

Post-Confirmation Automation & Sync

"As a business owner, I want the system to move the deal forward automatically after the yes so that I can close faster without manual follow-up steps."

Description

After a successful confirmation, automatically update the contract status (e.g., Recap Confirmed), embed the recap and confirmation certificate into the contract, and trigger downstream actions: email recap to both parties, notify in-app, and initiate the e-sign request in SnapAgree. Sync events to connected tools (CRM, invoicing) via native integrations or webhooks, and expose retry/error handling for failed deliveries.

Acceptance Criteria

Contract status updates to 'Recap Confirmed' after successful confirmation

Given a contract is in status "Recap Pending" and a successful confirmation event with a unique confirmation ID is received When the system processes the event Then the contract status is updated to "Recap Confirmed" within 5 seconds And the status change is recorded in the audit log with timestamp (UTC), actor, and correlation ID And the operation is idempotent so repeated identical events do not create duplicate status transitions

Recap and confirmation certificate embedded into the contract record

Given a recap has been confirmed When the contract record is updated Then the recap summary and a confirmation certificate PDF are embedded as immutable attachments And the certificate includes contract ID, counterparties, confirmation timestamp (UTC), confirmation channel (on-screen/voice), and SHA-256 checksum And the contract PDF displays a recap section on the first page with a "Confirmed" badge and certificate reference And a new contract version is created without altering prior versions

Downstream notifications and e-sign are triggered

Given a contract transitions to "Recap Confirmed" When downstream actions are executed Then an email containing the recap is sent to both parties with a verified sender and a subject that includes the contract ID And in-app notifications are delivered to both parties within 10 seconds of confirmation And an e-sign request is created in SnapAgree with correct signers, signing order (if configured), and the confirmed contract version And no duplicate emails or e-sign requests are generated for the same confirmation ID

Integrations and webhooks deliver confirmed events to external tools

Given CRM and invoicing integrations are enabled and a webhook endpoint is registered When a contract is confirmed Then a "recap.confirmed" event payload is delivered to each target with HMAC signature, retry-count, and schema version And the CRM is updated to stage "Contract Confirmed" with the confirmation date as close date And an initial invoice draft is created with price and payment schedule from the recap And webhook deliveries use at-least-once semantics with exponential backoff starting at 30 seconds up to 24 hours And 2xx responses mark delivery success; 4xx responses are marked failed after max retries; 5xx responses are retried until max retries

Retry and error handling surfaced to users

Given any downstream delivery fails When the system retries Then retries follow exponential backoff with jitter for up to 10 attempts or 24 hours, whichever comes first And failures appear in the contract activity timeline with target, error code/message, attempt count, and last-attempt timestamp And users with appropriate permissions can manually trigger a retry from the UI And permanently failed deliveries are moved to a dead-letter queue and a warning banner is shown on the contract

Auditability and traceability of post-confirmation automation

Given a confirmation event is processed When automation steps execute Then every step (status update, embed, emails, notifications, e-sign, integrations, webhooks) is logged under a single correlation ID And logs capture start and end timestamps, outcome (success/failure), and latency per step And audit entries are retained for 24 months and are exportable as CSV And PII in logs is minimized and masked according to data protection policy

Sign-Now OTP

Trigger one-tap e-sign during the call with identity verification via SMS/email one-time code. Routes multiple signers sequentially if needed, timestamps the event, and locks the final PDF in your audit trail before you hang up.

Requirements

One-Tap In-Call Signature Trigger

"As a sales-focused small-business owner, I want to trigger a one-tap e-sign while on a call so that I can close the deal before the prospect hangs up."

Description

Provides a single-click "Sign Now" control within SnapAgree to initiate the e-sign flow during a live call. Preloads the selected contract and recipient list, opens a lightweight signing modal for the recipient, and streams real-time status (OTP sent, verified, signed) to the sender. Supports desktop and mobile, deep links for recipients, and keeps the sender in context so the call is uninterrupted. Ensures minimal steps from trigger to signature completion and presents immediate success/failure feedback before the call ends.

Acceptance Criteria

In-Call One-Tap Trigger (Desktop/Web)

Given the sender is in an active SnapAgree call with a contract selected and a recipient list configured When the sender clicks "Sign Now" Then the system preloads the selected contract and recipient list And a lightweight signing modal is opened for the recipient via deep link And the sender remains on the call view with audio/video uninterrupted And the sender sees an "OTP sent" status event in the call sidebar And the recipient completes the flow in no more than two screens (OTP entry and signature)

OTP Delivery and Verification Gate

Given a recipient has valid SMS and/or email on file When "Sign Now" is triggered and an OTP delivery channel is chosen per recipient preference Then a one-time OTP is generated for this session and delivered to the chosen channel And the recipient signing modal displays an OTP input and masks the destination contact When the recipient enters a correct OTP within its validity window Then the sender UI updates the status to "OTP verified" without manual refresh And the signature step becomes available to the recipient When the recipient exhausts the allowed number of incorrect OTP attempts Then the sender UI updates the status to "OTP failed" and the recipient is blocked from signing

Real-Time Status Streaming to Sender

Given the sender is viewing the call sidebar during the signing session When the system emits events (OTP sent, OTP verified, Signed, Failed) Then the sender sees live status updates in sequence without reloading the page And each event includes a to-the-second timestamp And the latest event is visible before the call ends

Sequential Multi-Signer Routing

Given the contract requires multiple signers with a defined signing order When the first signer completes OTP verification and signs Then the next signer automatically receives their deep link and OTP And the sender UI displays the current signer and pending next signer(s) And the document remains in-progress until the final signer completes When the final signer signs Then the system marks the signing as complete for all parties

Finalization, Timestamping, and Audit Trail Lock

Given all required signatures are complete Then the system generates a final, locked PDF with an immutable hash And appends audit trail entries for each event (OTP sent, OTP verified, Signed/Failed) with UTC timestamps, signer identity, delivery channel (masked), and IP/device metadata And the audit trail and final PDF are linked and cannot be modified And the sender can download or share the locked PDF and audit trail immediately

Mobile Sender Flow Preserves Call Context

Given the sender is on a mobile device in an active SnapAgree call When the sender taps "Sign Now" Then the call audio remains active and uninterrupted And the sender stays within the call screen using an in-context sheet/modal (no full-screen navigation) And live status updates appear in the call UI as the recipient completes OTP and signing

Recipient Deep Link Opens Lightweight Signing Modal

Given the recipient receives a deep link via SMS or email When the recipient opens the link on desktop or mobile Then a lightweight signing modal opens in the browser without requiring app installation And the modal is pre-populated with the correct contract and signer role And the link expires after successful signing or session timeout

OTP Delivery & Verification Engine

"As a signer, I want to verify my identity with a one-time code via SMS or email so that I can securely sign without creating an account."

Description

Generates cryptographically secure, per-transaction one-time codes and delivers them via SMS and email with configurable expiry and attempt limits. Stores only hashed OTPs, enforces rate limiting, supports locale-aware message templates, and offers magic-link auto-fill to reduce friction. Implements resend throttling, anti-brute-force protections, and detailed verification logs, ensuring compliant, reliable identity checks without requiring an account.

Acceptance Criteria

Per-Transaction OTP Generation and Storage Security

Given a guest user initiates identity verification for a transaction When an OTP is generated Then the OTP is produced using a cryptographically secure random source with at least 10^6 possible values, is unique to that transaction and recipient, and is bound to transaction_id and recipient And only a salted, peppered hash of the OTP plus metadata (transaction_id, recipient, channel, created_at, expires_at, attempt_count) is persisted; plaintext OTP is never stored in the database, logs, caches, or analytics And attempts to retrieve plaintext OTP from any storage or log return no instances And the API returns only an opaque reference (no OTP value) to the caller

Configurable Expiry and Attempt Limits Enforcement

Given configured expiry_minutes = E and max_attempts = M for the transaction When the recipient attempts verification after E minutes from OTP creation Then the response is "expired" and the OTP is invalidated When the recipient submits incorrect OTPs M times within the validity window Then the response is "attempts_exceeded" and further attempts are blocked until a new OTP is issued When per-transaction overrides for E or M are provided within allowed bounds Then those overrides take effect and are reflected in messages and verification behavior

SMS and Email Delivery with Locale-Aware Templates

Given a recipient locale L and channel (SMS or Email) When an OTP message is sent Then the locale-specific template for L is used; if unavailable, en-US is used as a fallback, with placeholders (code, expiry, product name, transaction label) correctly populated And the SMS content includes OTP and expiry, remains within the configured segment limit, and includes the SnapAgree brand And the email subject does not include the OTP; the email body includes OTP and expiry and uses the SnapAgree brand When the primary provider fails or times out Then a fallback provider is attempted once and both provider message IDs are logged And upon successful provider handoff the API responds with status "accepted" and a provider message ID within 5 seconds at the 95th percentile

Magic-Link Auto-Fill and One-Tap Verification

Given magic-link auto-fill is enabled for the transaction When the recipient taps the magic link on a supported device/email client Then the verification page opens over TLS with the code pre-filled and auto-submitted, and verification succeeds if within validity window And the magic-link token is single-use, bound to the same transaction and recipient, and expires at the same time as the OTP And the URL contains no plaintext OTP digits; only a signed, non-guessable token is present; replay attempts return "used_or_invalid"

Resend Throttling and OTP Invalidation

Given configured resend_throttle_seconds = W and max_resends = R When a resend is requested within W seconds of the last send Then the API returns "throttled" with a Retry-After header equal to remaining seconds and no new message is sent When the number of resends requested exceeds R Then the API returns "resend_limit_reached" and no new message is sent When a resend is issued after the throttle window and under the resend limit Then a new OTP is generated and all prior OTPs for the transaction are invalidated; attempts with an older OTP return "superseded"

Anti-Brute-Force and Rate Limiting Controls

Given verification attempt limits per transaction (M), per identifier (V per minute), and per IP (I per minute) When any of these limits are exceeded on send or verify endpoints Then the API responds with HTTP 429, includes a Retry-After header, and logs the event with reason "rate_limited" When repeated failed verifications from the same IP or identifier reach a risk threshold T Then exponential backoff or a temporary block of B minutes is enforced and further requests return "temporarily_blocked" Given normal usage (<= 2 sends and <= 5 verify attempts within 10 minutes) When the user proceeds Then no rate limiting is applied

Verification Logging and Auditability

Given any send, resend, verify attempt (success/failure), expiry, or rate-limit event When the event occurs Then a log entry is recorded with: timestamp (UTC), transaction_id, event_type, channel, masked recipient, result/reason code, provider message_id (if any), requester IP (truncated), user-agent hash, and latency (ms) And no log, database, or analytics payload contains plaintext OTP or magic-link token; codes are masked or hashed And logs are append-only and queryable by transaction_id with 95th percentile lookup latency < 1 second, and retention is enforced per policy with automatic purging after expiry And an audit export endpoint returns an ordered event trail for a transaction with sequence numbers and without sensitive fields

Sequential Multi-Signer Routing

"As a contract owner, I want signers routed in a set order so that the right people sign at the right time without confusion."

Description

Enables defining and enforcing a signer order so each recipient receives the signing request only after the previous signer verifies via OTP and completes their signature. Includes progress tracking, deadlines, per-signer reminders, and delegation handling. Automatically advances to the next signer on completion, pauses the flow on failure or expiry, and surfaces status to the sender in real time.

Acceptance Criteria

Sequential Signer Order Enforcement

Given a sender defines signer order [Signer A, Signer B, Signer C] When Signer B accesses the signing link before Signer A completes OTP and signs Then Signer B is blocked from signing and shown status "Waiting on Signer A" and the sender dashboard reflects "Waiting on prior signer" for Signer B. Given Signer A completes OTP and signs When the system advances the flow Then the invite for Signer B is dispatched within 60 seconds via configured channels and an audit event "Advanced to next signer" is recorded with UTC timestamp and transport details. Rule: Only one signer can be in Active state at a time; later signers remain Queued until the prior signer status = Signed.

OTP Verification Gate Before Signing

Given a signer opens their signing session When they have not verified identity Then a one-time code (6 digits) must be entered from SMS or email before any fields become editable. Rule: OTP expiry window = 10 minutes; max 5 failed attempts per session; after max failures the session locks for 15 minutes and the flow is paused for that signer. Rule: Up to 3 OTP resends are allowed per 15-minute window; each resend and delivery outcome is captured in the audit trail. Then upon successful OTP verification, the signer status updates to "OTP Verified" within 5 seconds and is visible to the sender in real time.

Auto-Advance to Next Signer on Completion

Given a signer has verified via OTP and completed all required signature fields When they click Finish Then their status changes to Signed and a UTC timestamp is recorded in the audit trail. Then the next signer in sequence is notified within 60 seconds using configured delivery method(s), and the flow state for that signer becomes Invited. Rule: Advancement is automatic unless the flow is paused due to failure or expiry. Rule: After the final signer completes, the final PDF is rendered, cryptographically locked, and an immutable audit trail entry "Agreement completed" is recorded with document hash and completion timestamp.

Per-Signer Deadlines and Reminder Cadence

Given the sender configures a per-signer deadline and reminder cadence When a signer becomes Active Then the deadline countdown starts from activation and reminders are sent on the configured schedule until the signer is Signed or Expired. Rule: If the deadline elapses without signature, the signer status becomes Expired, the flow pauses, and the sender is alerted within 60 seconds. Rule: The sender can extend the deadline or adjust reminder cadence for the current signer; updates apply immediately and are logged in the audit trail. Rule: Reminders include current status, remaining time, and a secure link; each reminder delivery outcome is recorded.

Signer Delegation with Audit Preservation

Given delegation is enabled for the agreement When the Active signer delegates by submitting delegate name, contact (email/phone), and reason Then the delegate must pass OTP verification, the sequence position is reassigned to the delegate, and a delegation event is recorded with both identities and UTC timestamps. Rule: The sender is notified in real time and can approve or revoke before the delegate signs; if revoked, the flow returns to the original signer. Rule: Completed signatures of prior signers remain valid; no previously completed signatures are invalidated by delegation. Rule: Only one delegation per position is allowed unless explicitly overridden by the sender; further attempts are blocked with an explanatory message.

Pause and Recovery on OTP Failure or Delivery Issues

Given OTP delivery fails (hard bounce, carrier error) or the signer exceeds maximum verification attempts When the failure occurs Then the signer's state becomes Paused with a visible reason, the flow does not advance, and the sender is notified. Rule: The sender can update the signer's contact details and resend; upon resend the state becomes Invited and a new OTP is issued; all actions are timestamped in the audit trail. Rule: If a signer's invitation expires, the flow remains paused until the sender extends the deadline or re-invites; resumption continues from the same sequence position.

Real-Time Progress and Status Visibility to Sender

Given the agreement is in progress When any routing event occurs (Invited, OTP Sent, OTP Verified, Signed, Delegated, Paused, Expired, Advanced) Then the sender dashboard updates within 5 seconds to show per-signer status badges, the current Active signer, and overall progress (e.g., 2/4 signed). Rule: A chronological activity log is available with UTC timestamps, actor, event type, delivery outcomes, and signer IP/country where available. Rule: The sender can download the audit trail at any time; after completion, the final audit trail reflects the full sequence and the document hash.

Audit Trail & Event Timestamping

"As a business owner, I want a detailed, timestamped audit trail so that I can prove who signed, when, and from where in case of disputes."

Description

Captures a comprehensive, append-only record of all key events, including OTP sent/verified, document viewed, signature applied, and completion, with NTP-synchronized UTC timestamps, IP address, and device/user-agent metadata. Generates a certificate of completion and links it to the finalized document. Supports secure export, search, and retention policies suitable for legal evidence.

Acceptance Criteria

Record Key Events with Metadata for OTP and Signing

Given a document is in a Sign-Now OTP flow When OTP is sent (via SMS or Email), OTP is verified, the document is viewed, a signature is applied, and the document is marked complete Then an audit event is created within 1 second for each action containing: event_id, event_type, document_id, signer_identifier (email and/or phone), signer_sequence_index (for multi-signer flows), channel (for OTP), outcome (success/failure), error_code (if failure), timestamp_utc (ISO 8601, millisecond precision), ip_address (IPv4/IPv6), and user_agent

UTC Timestamps with NTP Synchronization Evidence

Given any audit event is recorded When the system stamps the event Then the timestamp_utc is generated from an NTP-synchronized clock with measured_drift_ms ≤ 500, and the event stores ntp_server and measured_drift_ms; timestamps are in UTC ISO 8601 with millisecond precision And if synchronization is unavailable, the event records time_sync_status = "unsynchronized" with reason, and an operational alert is raised within 60 seconds

Immutable, Tamper-Evident Audit Log

Given the audit trail contains events for a document When verifying integrity Then each event contains prev_event_hash and event_hash = SHA-256(prev_event_hash + event_payload), and the chain validates end-to-end for that document And any attempt to modify or delete an existing audit event via UI, API, or direct storage is denied (HTTP 403 or equivalent), leaves the original event unchanged, and creates a security_event audit entry

Certificate of Completion Linked to Finalized Document

Given all required signatures are applied and OTP verifications are successful When the document is finalized Then the system generates a certificate of completion containing: document_id, finalized_pdf_sha256, completion_timestamp_utc, signer list with order and verification method, chronological key events with timestamps, ip_address, and user_agent, and the audit chain root hash And the certificate is linked to the finalized document, embedded as a PDF attachment, and both the certificate and final PDF are locked (read-only) and digitally signed by SnapAgree

Secure, Authorized Export of Audit Trail

Given an authorized user with audit.export permission requests an export for a document When the export is generated Then the system provides machine-readable JSON and human-readable PDF including all audit events and the certificate; the export is delivered over TLS 1.2+ and includes a cryptographic signature to verify origin and integrity And all export attempts (success and failure) are logged with user_id, timestamp_utc, and ip_address; unauthorized requests return HTTP 403 and are logged

Searchable Audit Events with Performance Targets

Given ≥ 10,000 audit events exist in the workspace When a user with appropriate permission searches by any combination of document_id, signer_identifier (email/phone), event_type, ip_address, and UTC date range Then the system returns accurate, paginated results sorted by timestamp_utc (asc/desc) with p95 first-page response time ≤ 2 seconds and total count accuracy = 100% And partial matches are supported for signer_identifier (contains match), and all search queries and access are audit-logged

Retention Policies and Legal Hold Enforcement

Given a workspace retention policy in days is configured When audit events exceed the retention period Then the system permanently deletes those events and writes a destruction log entry with event_id, policy_id, and destruction_timestamp_utc; backups honor the same retention And when a legal hold is placed on a document or signer, affected events are exempt from deletion until the hold is lifted; policy changes are logged and apply prospectively unless an admin explicitly confirms a retroactive purge

Final PDF Locking & Certification

"As a contract owner, I want the final PDF to be locked and certified after signing so that it cannot be altered and is legally defensible."

Description

On final signer completion, flattens fields, applies a tamper-evident digital signature, computes and stores a document hash, and marks the PDF as read-only. Associates the sealed file with the audit trail entry and exposes a "Locked" state in the UI and via API. Any subsequent edits require a new version and a fresh signing sequence, preserving legal integrity.

Acceptance Criteria

Auto-Lock on Final Signer Completion

- Upon last required signer completion, system flattens all PDF form fields. - System applies a tamper-evident digital signature verifiable in Adobe Acrobat as valid. - System computes a SHA-256 hash of the sealed PDF and persists it with the document record and audit trail. - Resulting PDF is read-only; form fields cannot be edited in standard PDF viewers. - Lock-and-certify completes within 5 seconds at the 95th percentile from final signing event.

Audit Trail Association and Timestamping

- Sealed PDF is attached to the audit trail entry for the final signing event. - Audit trail stores: final signer ID, UTC ISO 8601 timestamp (ms precision), IP address, user agent, SHA-256 hash, and signature certificate fingerprint. - UI audit trail displays a "Locked" event with link to the sealed PDF and hash value. - Audit trail export/API includes the same fields with identical values.

UI Locked State and Controls

- Document detail view displays a prominent "Locked" badge within 1 second of lock event. - All edit controls are disabled; a "Create New Version" CTA is available. - Any attempt to edit shows warning: "This document is locked. Create a new version to make changes." - Built-in signature verification action reports the digital signature as valid.

API Locked State Exposure

- GET /documents/{id} returns status=Locked with lockedAt (UTC ISO 8601), sha256Hash, and signatureInfo. - GET /documents/{id}/versions marks current version readOnly=true and locked=true. - POST/PATCH calls that would alter the locked PDF return 409 Conflict with error code DOC_LOCKED. - GET /documents/{id}/file returns bytes whose SHA-256 matches stored sha256Hash.

Prevent Post-Lock Edits via New Version Workflow

- Initiating any edit on a locked document creates a new version (versionNumber+1) with a new signingSequenceId and no signatures. - Original version remains immutable and accessible; sending for signature is blocked on the locked version. - New version metadata references previousVersionId and previousSha256Hash. - Audit trail for the original version remains unchanged; new version begins a separate trail linked via cross-reference IDs.

Multi-Signer Sequential Routing and Lock Timing

- For sequential signers, lock occurs only after the final signer completes; intermediate completions do not lock. - Partial completions update audit trail with signer order and status=In Progress; no final hash/signature applied. - If final signer declines or times out, document remains unlocked and no sealed PDF is produced. - On final completion, lock event records signer order, completion timestamp, and triggers sealing within performance SLA.

Deliverability & Fallback Handling

"As a sender, I want OTP delivery to automatically fallback and support resends so that signers can receive codes even if SMS fails."

Description

Validates phone numbers and emails pre-send, monitors delivery via provider webhooks, and automatically falls back from SMS to email (or vice versa) when delivery fails. Provides branded, localized messages, short-link support, and clear in-product controls to resend or switch channels, with safeguards on frequency. Logs delivery outcomes for diagnostics and compliance.

Acceptance Criteria

Pre-Send Contact Validation

- Given a signer phone and email are entered, When the user initiates OTP send, Then the phone is validated against E.164 and rejected if non-conforming with an error code and message. - Given a phone number is a landline or VOIP per carrier lookup, When validation runs, Then SMS OTP is blocked with guidance to switch to email. - Given an email address is entered, When validation runs, Then it is checked against RFC 5322 syntax and MX records; invalid emails are rejected with an error code and message. - Given an email or phone is on an internal bounce/opt-out list, When a send is initiated, Then the channel is blocked with reason displayed and a one-click option to switch channels. - Given multiple signers exist, When validation runs, Then results are shown per-signer and sending is allowed only for signers passing validation.

SMS Delivery Monitoring & Fallback to Email

- Given an SMS OTP is sent, When the SMS provider webhook returns failed or undelivered, Then the system automatically sends the OTP via email to the same signer within 60 seconds and records the fallback event. - Given an SMS OTP is sent, When no delivery or final status is received within 120 seconds, Then the system marks the SMS as timed_out and triggers email fallback. - Given a fallback to email occurs, When the email is sent, Then the OTP token/link remains the same and is single-use across channels. - Given a fallback occurs, When viewing the UI, Then it displays the channel switch, timestamps, and provider message IDs, and provides a manual resend control. - Given a fallback has been triggered, When late SMS delivery notifications arrive, Then no additional messages are sent and the audit reflects the first successful channel.

Email Delivery Monitoring & Fallback to SMS

- Given an email OTP is sent, When the email provider webhook returns hard_bounce, soft_bounce, blocked, or complaint, Then the system automatically sends the OTP via SMS within 60 seconds if a valid mobile number exists. - Given an email OTP is sent, When no delivered/accepted event is received within 5 minutes and no bounce occurred, Then the system triggers SMS fallback and labels the email attempt as timed_out. - Given a fallback to SMS occurs, When the SMS is sent, Then the OTP token/link remains the same and is single-use across channels. - Given no valid mobile number exists, When email delivery fails, Then the system surfaces a blocking error with guidance to correct the phone or retry email without entering a fallback loop. - Given multiple signers, When one signer’s email fails, Then only that signer’s channel falls back; others proceed unaffected.

Branded Localized Message Content

- Given organization branding is configured, When generating OTP messages, Then SMS uses the verified sender ID (where supported) and email uses the branded From, subject, and logo per settings. - Given a signer locale is determined from contract settings or browser, When composing messages, Then content is localized to that locale and falls back to English if unavailable. - Given SMS length constraints, When composing the SMS with a short link, Then the message fits within ≤2 segments (≤306 GSM-7 chars or equivalent UCS-2) and shows segment count; if exceeded, non-essential text is truncated while preserving legal copy and link. - Given right-to-left languages are used, When rendering SMS/email, Then directionality is correct and placeholders render in the proper order. - Given template tokens are present, When sending, Then all tokens resolve; otherwise the send is blocked with a clear template resolution error.

Resend & Channel Switch Controls with Rate Limits

- Given the agent clicks Resend OTP, When the last send was <60 seconds ago, Then the resend is blocked with a throttle message; otherwise the resend proceeds. - Given per-signer rate limits, When resending, Then the system enforces a maximum of 3 sends per 15 minutes per channel and displays remaining attempts. - Given repeated failures, When the agent clicks Switch Channel, Then a single OTP is queued via the alternate channel and any in-flight unsent retries are canceled. - Given the rate limit window is exhausted, When additional resends are attempted, Then the UI control is disabled until the window resets and a tooltip explains the cooldown time. - Given an OTP has been verified, When a resend is attempted, Then the action is blocked with a message that verification is complete. - Given sequential signing, When resending for signer N, Then no OTP is sent to signer N+1 until N verifies or is manually skipped by the agent with an audit entry.

Audit Logging of Delivery Outcomes & Timestamps

- Given any OTP send attempt, When delivery webhooks are received, Then the system logs event type, channel, timestamps (UTC and org-local), provider message IDs, status codes, and reason texts. - Given a fallback occurs, When logging, Then the audit trail shows original attempt, fallback trigger, subsequent attempt, and final success/failure in chronological order. - Given the contract is fully signed, When the PDF is locked, Then a delivery summary is attached to the audit trail and is immutable and exportable (JSON/CSV) with a checksum. - Given compliance requirements, When exporting logs, Then phone numbers and emails are masked per policy (e.g., last 2 digits/characters visible) while preserving diagnostics. - Given a 24-month retention policy is configured, When the window expires, Then delivery logs are purged and the audit trail records a purge event with timestamp.

Branded Short-Link Support & Fallback

- Given a verified custom short domain exists, When generating OTP URLs, Then per-signer, single-use, HTTPS short links are created using that domain. - Given shortener failure or DNS misconfiguration, When attempting to shorten, Then the system falls back to the full-length secure URL, records the failure, and continues sending. - Given link tracking is enabled, When a signer clicks a link, Then a click event with timestamp, channel, and device metadata is recorded without storing PII and appears in the audit trail. - Given OTP security, When a short link is generated, Then it expires after the configured TTL (default 30 minutes) and invalidates any prior unredeemed links for that signer. - Given multiple deliveries of the same OTP exist, When any one link is redeemed, Then remaining links immediately expire and subsequent clicks show an expired-page with a one-click request-new-OTP option.

Admin & Compliance Controls

"As an admin, I want to configure OTP policies and legal consent so that our signatures remain compliant and match our brand."

Description

Offers workspace-level settings for OTP expiry, max attempts, preferred channels, and message templates/branding. Presents ESIGN/eIDAS-compliant disclosures and explicit consent capture before signing. Provides role-based permissions for triggering Sign-Now, retention policies for audit artifacts, export capabilities, and encryption of sensitive data at rest and in transit.

Acceptance Criteria

Workspace OTP Expiry Configuration

Given I am a workspace admin, when I set OTP expiry to a value between 1 and 30 minutes and publish, then newly issued OTPs in this workspace expire after the configured duration (±5 seconds), late verifications return "OTP_EXPIRED", and an audit event with policy version is recorded. Given OTPs were issued before an expiry change, when a signer verifies, then the previous expiry applies (non-retroactive) and the audit event references the prior policy version. Given I enter an invalid expiry (0, >30, non-integer), when I save, then the UI blocks the change, inline validation explains the allowed range, and the API returns HTTP 400 with code "INVALID_OTP_EXPIRY". Given I lack admin permissions, when I view settings, then expiry controls are hidden; when I call the API to update, then I receive HTTP 403 and an "UNAUTHORIZED" audit event is logged.

Max OTP Attempts Enforcement

Given I am a workspace admin, when I set max OTP verification attempts between 1 and 10 and publish, then the new limit applies to OTPs issued afterward and is recorded with a policy version. Given a signer enters an incorrect OTP and reaches the max attempts, when they try again, then verification is blocked until a new OTP is issued, the session shows "MAX_ATTEMPTS_REACHED", and the audit trail captures each attempt with timestamps. Given I set an invalid max attempts value (0, >10, non-integer), when I save, then validation prevents it and the API returns HTTP 400 "INVALID_MAX_ATTEMPTS". Given a new OTP is issued after lock, when the signer verifies correctly within attempts and before expiry, then verification succeeds and the audit trail shows attempts count reset.

OTP Delivery Channels and Fallback

Given I am a workspace admin, when I enable one or more channels (SMS, Email) and set a priority order, then subsequent OTP sends use the primary channel and record channel used and message ID. Given delivery on the primary channel fails (provider failure, bounce, or undeliverable), when a fallback channel is configured and the recipient has required contact info, then the system retries via the next channel within 15 seconds and logs both attempts with statuses. Given only one channel is enabled or the recipient lacks data for fallback, when delivery fails, then the system surfaces "DELIVERY_FAILED" with a retry option and the audit event includes a failure reason code. Given a workspace disables a channel, when Sign-Now is triggered, then the disabled channel is not used and any attempts to send via it return HTTP 409 "CHANNEL_DISABLED".

OTP Templates and Branding Customization

Given I am a workspace admin, when I edit the SMS/email OTP templates using allowed placeholders {{otp}}, {{workspace_name}}, {{signer_name}}, {{document_title}}, {{expiry_minutes}}, then preview renders with sample data and save succeeds. Given a template includes an unknown placeholder or exceeds max length (SMS > 160 chars for the first segment), when I attempt to save, then validation highlights the issue and blocks save. Given branding settings (logo, brand color, sender name) are configured, when an OTP is sent, then the email uses the branded header and sender name and the consent screen displays the logo and color; the audit event records the template version and branding version used. Given a new template version is published, when OTPs are sent afterward, then they reference the new version in the audit trail; previously sent messages retain the prior version.

ESIGN/eIDAS Disclosure and Explicit Consent

Given a signer starts Sign-Now, when disclosures are presented, then the signer must explicitly consent by checking a consent checkbox and selecting "Agree and Continue" before any OTP is issued. Given the signer declines or closes the disclosure, when the flow ends, then no OTP is sent, the transaction is marked "CONSENT_DECLINED", and an audit record captures disclosure version, timestamp (UTC), IP, and user agent. Given the signer consents, when the OTP is issued, then the consent record includes disclosure content hash, version, timestamp (UTC), IP address, user agent, locale, and signer identifier and is linked to the final signed PDF/audit trail. Given multiple signers are routed sequentially, when each signer reaches disclosures, then consent is required and recorded per signer; the flow does not advance to OTP for a signer without their consent.

Role-Based Permission to Trigger Sign-Now

Given workspace roles and permissions are configured, when a user without "Trigger Sign-Now" permission opens a deal, then the Sign-Now action is hidden/disabled in UI and API calls to initiate return HTTP 403 with code "INSUFFICIENT_PERMISSIONS". Given an admin grants "Trigger Sign-Now" to a role, when a user with that role refreshes within 60 seconds, then the action is enabled and the permission change is logged with actor, time, and scope. Given a user has permission in Workspace A but not Workspace B, when they attempt to trigger from Workspace B, then it is blocked and an "UNAUTHORIZED_WORKSPACE" audit event is created. Given "Trigger Sign-Now" permission is removed, when the user attempts to reuse an open session, then the action is blocked and the audit trail records the permission check and denial.

Audit Artifact Retention, Export, and Data Encryption

Given I am a workspace admin, when I set retention durations for signed PDFs, consent records, OTP logs, and delivery events within the allowed range (30–2555 days) and publish, then items older than the configured duration are purged by the retention job within 24 hours and a "PURGED" audit event is recorded per item type. Given retention is updated, when new items are created, then they inherit the new policy; existing items follow the previous policy until purged and audit events reference the applicable policy version. Given I have "Export Audit" permission, when I export artifacts for a date range and signer filter, then a ZIP is generated containing the final PDFs and a JSONL of audit events with a SHA-256 checksum file; exports up to 10,000 records complete within 5 minutes. Given an unauthorized user attempts export, when the request is made, then it is denied with HTTP 403 and audited. Given the system stores sensitive data, when data at rest is inspected, then OTP secrets and PII fields are encrypted (AES-256 or equivalent) and logs mask PII (phone masked except last 2 digits, email local-part partially redacted); when in transit, TLS 1.2+ is enforced and HSTS is present; HTTP requests are redirected to HTTPS.

PaySign Merge

Combine e‑signature and secure checkout in a single, seamless step. The contract autofills the deposit or first invoice amount and processes payment the moment the client signs, eliminating post‑call drop‑off and letting you lock revenue while momentum is high.

Requirements

Unified Sign-and-Pay Experience

"As a client signer, I want to review, sign, and pay in one step so that I can finish the agreement quickly without being redirected or repeating information."

Description

Deliver a single, responsive flow that combines contract review, e‑signature, and secure payment collection without redirects. The signer reviews terms, signs, and immediately completes payment in the same step, with clear progress indicators, mobile optimization, accessibility support, and trust signals. The flow minimizes context switching, reduces drop‑off, and embeds seamlessly into SnapAgree’s signing pages and shared links, preserving brand styling and template-specific requirements.

Acceptance Criteria

One-Step Mobile Sign-and-Pay Completion

Given a signer opens a SnapAgree signing link on a mobile device (viewport width 320–414 px, 4G network) When the signer reviews the contract, applies an e‑signature, and submits payment Then the entire flow occurs within a single page without full‑page redirects or domain changes And the layout adapts responsively with tap targets ≥ 44 px and body text ≥ 16 px And Largest Contentful Paint ≤ 2.5 s and First Input Delay ≤ 100 ms for each step transition And the signer reaches a single confirmation screen indicating both "Signed" and "Payment Successful"

Auto-Filled Amount with Template Controls and Immediate Charge on Signature

Given the contract template defines a deposit/first‑invoice amount, currency, and editability rules When the signer reaches the payment step after signing Then the amount is pre‑populated from the contract and is non‑editable unless the template permits edits within a defined min/max range And the transaction currency matches the contract currency And upon final submission, payment authorization and capture execute immediately And if SCA/3DS is required, the challenge occurs inline without leaving the flow and success results in capture And both parties receive a confirmation and paid receipt within 60 seconds of success

No-Redirect Embedded Flow Preserving Brand Styling

Given the signer uses a SnapAgree hosted signing page or shared link When progressing through review, sign, and pay Then the top-level URL host remains the SnapAgree domain or configured custom domain throughout the flow And no third‑party checkout page loads in the top‑level context And workspace logo, brand colors, and typography are applied consistently to all steps And there are no mixed‑content or browser security warnings in the latest Chrome, Safari, and Firefox

Progress Indicator and Trust Signals Visibility

Given the flow is loaded When the signer is on any step Then a persistent 3‑step indicator shows "Review", "Sign", and "Pay" with the current step highlighted And the payment step displays trust signals including a lock icon, "Secure • PCI‑DSS compliant" text, and supported card brand icons And the submit action clearly states "Sign and Pay [amount currency]" before submission And an estimated time to complete (≤ 2 minutes) and a help link are visible on all steps

Accessibility and Keyboard/Screen Reader Support (WCAG 2.1 AA)

Given the signer uses only a keyboard or a screen reader When navigating review, signature, and payment steps Then all interactive elements are reachable in logical order via Tab/Shift+Tab with visible focus indicators And form fields have associated labels and ARIA attributes; errors are announced via aria-live and linked to their fields And color contrast meets WCAG 2.1 AA (≥ 4.5:1 for text) And the signature input provides an accessible alternative (type‑to‑sign) with descriptive instructions And manual NVDA (Windows) and VoiceOver (iOS) smoke tests pass the end‑to‑end flow

Atomic Signature-Payment Transaction and Idempotency

Given the signer submits the combined signature and payment When the payment gateway returns a result Then on success, the contract status updates to "Executed – Paid" with a single timestamped audit entry linking payment ID and signature hash And on failure or timeout, the contract remains "Pending Payment – Not Executed" and the signer is prompted to retry payment without re‑signing And retries use an idempotency key to prevent duplicate charges; at most one successful capture is recorded per contract And the system logs a complete audit trail of all attempts with gateway response codes

Error Handling and Recovery Without Data Loss

Given a transient network error, browser refresh, or payment decline occurs during the flow When the signer resumes the session within 30 minutes Then non‑sensitive progress (reviewed pages, signature image/hash, selected payment method type) is restored; sensitive card data is not stored and must be re‑entered And the user is returned to the correct step with a clear, actionable message including reason and next steps And the system prevents progression with incomplete required fields and displays inline error states And a support contact link is available; no dead‑end states are reachable

Contract Amount Autofill & Calculations

"As a business owner, I want the payment amount to auto-populate from my contract terms so that I avoid re-entering numbers and eliminate pricing errors."

Description

Autofill the payable amount from contract variables and pricing tables, supporting fixed amounts, percentage-based deposits, minimums/maximums, discounts, taxes, fees, and currency formatting. Present a transparent line‑item breakdown and update amounts in real time when editable contract fields change prior to signing. Validate inputs, handle rounding rules, and lock the final amount at signature time to prevent tampering, ensuring the payment reflects the agreed terms.

Acceptance Criteria

Percentage Deposit with Min/Max from Pricing Table

Given a contract in USD with a pricing table totaling 2,500.00 and a deposit set to 40% with a minimum of 500.00 and maximum of 1,200.00 When the payment amount is autofilled Then the raw deposit is 1,000.00 (2,500.00 x 40%) And the clamped deposit remains 1,000.00 (within 500.00–1,200.00) And the displayed and chargeable amount is 1,000.00 USD rounded to currency minor units using half-up And if the pricing table total changes, the deposit recalculates as clamp(round_half_up(subtotal x 40%), 500.00, 1,200.00)

Fixed Amount Autofill from Contract Variables

Given a contract variable {{deposit_amount}} = 750.25 in GBP and the contract currency is GBP When the contract is rendered for signature Then the payment amount autofills to 750.25 GBP And if {{deposit_amount}} is edited to a valid value before signing, the amount updates immediately and adheres to GBP minor units And if the variable currency does not match the contract currency, an inline error is shown and Sign & Pay is disabled until resolved

Transparent Line-Item Breakdown and Currency Formatting

Given a payment composed of Subtotal 2,000.00, Discount 10% (200.00), Taxable Amount 1,800.00, Tax 9% (162.00), Platform Fee 15.00, Total 1,977.00 in EUR When the user views the payment breakdown prior to signing Then the UI shows labeled rows: Subtotal, Discount, Taxable Amount, Tax, Fees, Total And each row displays currency-formatted amounts with EUR symbol, thousand separators, and correct minor units And hovering or tapping a row reveals calculation details (e.g., 2,000.00 x 10%) And non-applicable rows are hidden (not shown as zero)

Real-Time Recalculation Prior to Signing

Given editable fields that influence price (e.g., quantity, selected options, discount code) When the user changes any such field Then the line-item breakdown and total recompute within 500 ms after the last change And the Sign & Pay button remains disabled until recomputation completes and validations pass And no stale totals are shown; changes are reflected without requiring a page reload

Input Validation on Amount-Influencing Fields

Given input fields for percent deposit, discounts, taxes, and amounts When a user enters invalid values (percent < 0 or > 100, negative amounts, discount exceeding subtotal, non-numeric text) Then inline error messages are displayed adjacent to the offending fields describing the violated rule And the total is not recomputed using invalid values; the last valid total persists And the Sign & Pay button is disabled until all validation errors are resolved And numeric inputs are constrained to currency minor units per ISO 4217 (0, 2, or 3 decimals)

Amount Lock at Signature and Tamper Prevention

Given the payer clicks Sign & Pay When the signature event is submitted Then the system snapshots the final breakdown and total, hashes it, and stores it server-side with the payment intent And the payment is created using the server-side snapshot amount, ignoring any client-modified amount fields And any attempt to alter form fields or API payload post-signature does not change the charge amount And the contract PDF and audit log include the locked amount and hash

Discounts, Taxes, and Fees Calculation Order

Given line items with per-item taxability flags, a cart-level discount of 15%, and a fixed fee of 25.00 that is taxable When totals are computed Then Subtotal = sum(quantity x unit price of all items) And Discount = 15% of discount-eligible subtotal And Taxable Base = sum of tax-eligible amounts after discount plus taxable fees And Tax = Taxable Base x configured tax rate(s) with rounding per currency minor unit And Total = (Subtotal - Discount) + Fees + Tax

Atomic Sign-and-Charge Orchestration

"As a business owner, I want the payment processed the moment my client signs so that I lock in revenue and never end up with signed-but-unpaid contracts."

Description

Orchestrate signature completion and payment capture as a single atomic transaction. Pre-validate payment method, collect SCA if required, then finalize the signature and capture funds with idempotency to prevent duplicate charges. If payment fails, do not issue the final signed contract; surface actionable errors and offer safe retries without losing progress. Maintain consistent state transitions, rollback on failure, and persist correlation IDs to tie the payment to the signed document version.

Acceptance Criteria

Happy Path: Atomic Sign-and-Charge with SCA

Given a contract with an autofilled deposit amount and a payer whose card requires SCA And an idempotency key generated for the sign-and-charge session When the payer signs and confirms payment Then the system creates or reuses a single payment intent for the exact deposit amount And performs SCA challenge if required and receives successful authorization And captures funds successfully And only then marks the contract as final-signed and generates the immutable signed version And returns the signed document URL and payment receipt to both parties And exactly one charge is created and associated with exactly one final signed contract version And the correlation ID linking payment and signed document is persisted and retrievable

Payment Failure: No Final Signature, Actionable Error, Safe Retry

Given a contract ready for sign-and-charge and a payer with a failing payment method When payment authorization or capture fails (e.g., card_declined, insufficient_funds, SCA_failed, processor_error) Then the contract is not marked final-signed and no countersigned copy is issued And any provisional signature state is rolled back to pre-finalization And no funds are captured and no charge is created And the user sees a clear, actionable error message with a standardized error code and next steps And the session remains active, preserving completed fields and signature input for retry And the system offers retry options: retry same method, update/add payment method, or save-and-exit without finalizing

Idempotent Resubmission: Duplicate Submissions Yield Single Outcome

Given an active sign-and-charge session with a stable idempotency key When the client submits the final confirmation multiple times (double-clicks, reloads, or automatic network retries) within the idempotency window Then only one payment charge is created and only one final signed contract version is produced And all duplicate submissions return the same success payload with identical correlation identifiers And no duplicate notifications, receipts, or signature events are emitted And system logs record a single Completed transition for the session

Retry with New Payment Method Without Losing Progress

Given a failed payment attempt during sign-and-charge When the client updates or adds a new payment method and retries Then previously entered contract edits and signature data remain intact without re-entry And the system creates a new payment intent correlated to the same contract version and session And upon successful capture, the contract is finalized and linked to the successful payment's correlation ID And the audit trail records both failed and successful attempts with timestamps, reasons, and actor

Consistent State Transitions and Webhook Ordering

Given payment provider events may arrive late or out of order When the system processes authorization, capture, or failure webhooks Then state transitions enforce that Completed cannot occur before Captured and Failed cannot override Completed And duplicate or out-of-order events are deduplicated using provider IDs and idempotency keys And the final state is consistent across the contract record, payment record, and user-facing status within 5 seconds of the last event And partial updates do not leak to the user; only coherent states are displayed

Correlation IDs and Receipts Linked to Signed Contract Version

Given a successful atomic sign-and-charge When viewing the signed contract record Then the record displays payment provider ID (intent/charge), idempotency key, amount, currency, and capture timestamp And the same identifiers are present on the downloadable receipt and audit log And querying the payment provider by the stored ID returns details matching the contract amount and capture time within +/- 1 minute And the correlation is immutable; a new contract revision creates a new correlation and does not alter the historical link

Payment Gateway Integration with SCA and Wallets

"As a client signer, I want to pay using a secure, familiar method (card or wallet) so that I feel confident completing payment at the moment of signing."

Description

Integrate Stripe as the initial gateway via a pluggable payments abstraction that supports cards, Apple Pay, Google Pay, and ACH/Bank Debit where available. Use tokenization and client-side elements to keep PCI scope minimal while supporting 3D Secure/SCA flows. Handle multi-currency, localized payment UIs, decline codes, retries, and webhooks for asynchronous events. Provide sandbox mode, test cards, and clear error messaging to maximize completion rates and trust.

Acceptance Criteria

E‑Signature With SCA Card Payment

Given a signer is completing the PaySign Merge step on a contract with a prefilled deposit amount and uses a card that requires SCA When the signer clicks Sign & Pay Then a 3D Secure challenge is presented inline via Stripe and must be completed to proceed And upon successful SCA, the PaymentIntent is confirmed and captured for the exact amount and currency displayed And the contract status updates to Signed & Paid, the signature is finalized, and a receipt is emailed to both parties And if the SCA is canceled, fails, or times out, the payment is not captured, the signature is not finalized, a clear error is shown, and the signer can retry up to 3 times And repeated submits or page refreshes within the session do not create duplicate charges due to idempotency

Apple Pay and Google Pay Eligibility and Display

Given device/browser eligibility and region support for Apple Pay or Google Pay When viewing the PaySign Merge checkout Then the eligible wallet button (Apple Pay on iOS/Safari with Wallet set up; Google Pay on Chrome/Android or supported desktop) is shown; otherwise it is hidden And selecting the wallet opens the native sheet, shows the exact amount and currency, and completes payment on approval And on successful wallet payment, the contract updates to Signed & Paid and a receipt is sent And if wallet availability or authorization fails, a clear error is shown and standard card/ACH options remain usable

ACH/Bank Debit Asynchronous Confirmation

Given a US payer chooses ACH/Bank Debit at PaySign Merge When they complete bank account verification via Stripe Financial Connections or micro‑deposits Then the payment is initiated and the contract status updates to Signed — Payment Pending with an estimated clearance window And the system processes Stripe webhooks (payment_intent.processing, payment_intent.succeeded, payment_intent.payment_failed) to update the contract status and notify both parties And upon payment_intent.succeeded the status becomes Signed & Paid; upon payment_intent.payment_failed the status becomes Signed — Payment Failed with a retry link and reason And webhook signatures are verified, replay attacks are ignored idempotently, and no duplicate charges occur

PCI-Minimizing Tokenization via Stripe Elements

Given PaySign Merge collects payment details using Stripe Elements/Payment Element When the signer enters card or bank details Then all sensitive PAN/CVC/bank numbers are captured only inside Stripe-hosted iframes and never pass through our servers And our backend receives only Stripe PaymentMethod/PaymentIntent identifiers, not raw card or bank data, and server/database/logs contain no PAN/CVC/track data And the integration operates under PCI DSS SAQ A scope, validated by not rendering custom inputs for PAN/CVC and by restricting scripts to Stripe’s domains

Localized Multi-Currency Checkout and UI

Given a contract currency and signer locale are known When PaySign Merge renders the payment UI Then the amount is displayed and charged in the contract currency, correctly formatted (e.g., JPY without decimals), and payment methods unsupported for that currency are hidden And the Stripe Payment Element localizes labels, error messages, and wallet sheets to the signer’s locale with fallback to en‑US And receipts and statement descriptors include the contract ID/reference and display the correct currency and amount

Declines, Retries, and Idempotency

Given a payment attempt is declined or errors When Stripe returns a decline code or network error Then a human‑readable message mapped from the code is shown without exposing raw codes (e.g., “Payment was declined by your bank. Try another card or contact your bank.”) And the signer can retry the same method or choose another method up to 3 total attempts per contract without creating duplicate charges And concurrent or repeated submissions use idempotency keys to ensure only one successful charge is created And soft declines (e.g., authentication_required) trigger SCA and hard declines block further retries for that method in the session

Sandbox Mode and Test Data Parity

Given an organization is operating in Test Mode When PaySign Merge loads Then a visible Test Mode banner is shown, Stripe test keys are used, and Stripe test payment methods (including SCA, declines, wallets, and ACH) behave as documented And no live charges or real ACH debits occur, no real receipts are sent, and webhook events from the test environment update contract states accordingly And switching to Live Mode requires valid live API keys, passes a Stripe API connectivity and account capabilities check, hides test card hints, and enables live webhooks

Receipts, Invoices, and Contract Payment Annotations

"As a business owner, I want automatic receipts and contract payment confirmation so that both parties have clear proof of payment and my records stay organized."

Description

Automatically generate and deliver a branded receipt/invoice upon successful charge, email it to both parties, and annotate the final contract PDF with payment confirmation (amount, method, transaction ID, date). Update the SnapAgree dashboard with payment status and link to the processor transaction. Support refunds and partial refunds with corresponding documentation and maintain a clear, immutable audit trail tying the payment to the exact signed version of the contract.

Acceptance Criteria

Auto-Generate and Email Branded Receipt/Invoice on Successful Charge

Given a client signs a contract via PaySign Merge and the payment is authorized and captured When the processor confirms a successful charge for the deposit/first invoice amount Then SnapAgree generates a branded PDF receipt/invoice containing: payer name, payee business name, contract title/ID, invoice/receipt number, amount with currency, tax (if configured), payment method brand + last4, processor transaction ID, and ISO 8601 UTC date/time And the PDF uses the workspace’s branding (logo, colors, legal name, address) And SnapAgree emails the PDF receipt/invoice to both parties’ account emails within 60 seconds of charge success And the email includes a secure link to view/download the annotated final contract And the receipt/invoice is stored and accessible in the deal’s documents section

Annotate Final Contract PDF with Payment Confirmation Details

Given a successful charge occurs for a signed contract When SnapAgree finalizes the executed contract PDF Then the PDF includes a non-editable Payment Confirmation annotation showing: amount (with currency), payment status = Paid, payment method brand + last4, processor transaction ID, and ISO 8601 UTC date/time And the annotation references the receipt/invoice number And the annotation is embedded on the signature or summary page and cannot be removed or altered by users And the annotated PDF is the version downloadable by both parties

Update Dashboard Payment Status and Transaction Link

Given a contract with a successfully processed payment When a user views the contract record in the SnapAgree dashboard Then the payment status displays Paid with the confirmation timestamp (ISO 8601 UTC) And the exact processor transaction ID is visible with a clickable link to the processor transaction details And links to download the receipt/invoice PDF and the annotated contract PDF are present And the payment amount and currency match the signed contract’s payment terms

Support Refunds and Partial Refunds with Documentation

Given a refund (full or partial) is initiated or received via processor webhook for a prior successful transaction When the refund is completed by the processor Then SnapAgree generates a refund receipt/credit memo PDF referencing the original transaction ID, contract ID, receipt/invoice number, refund amount with currency, and ISO 8601 UTC date/time And SnapAgree emails the refund document to both parties within 60 seconds of refund completion And the dashboard payment status updates to Refunded (full) or Partially Refunded with net paid and refunded amounts displayed And the contract’s payment timeline shows a refund event with the processor refund ID and link to the refund document

Maintain Immutable Audit Trail Tied to Signed Contract Version

Given payment-related events occur (charge success/failure, refund) When SnapAgree records an event Then the audit trail appends an entry including: event type, actor/system, ISO 8601 UTC timestamp, amount/currency (if applicable), processor IDs (charge/refund), related document IDs, and the signed contract PDF hash (e.g., SHA-256) And audit entries are append-only and cannot be edited or deleted by any user role And exporting the audit trail (PDF/CSV) reproduces the same entries and includes a checksum of the export And if a new contract version is created, it receives a new hash and events continue to reference the exact version they pertain to

Handle Failed or Declined Payments Without Premature Artifacts

Given a client signs but the payment attempt is declined or fails authorization/capture When the processor returns a failure response Then no receipt/invoice is generated or emailed And the executed contract PDF is not annotated with Payment Confirmation And the dashboard displays payment status Unpaid with the failure reason code/message when available And both parties receive an email notification with a secure link to retry payment

Ensure Idempotency and No Duplicates on Event Retries

Given duplicate webhooks or retried notifications are received for the same processor transaction/refund ID When SnapAgree processes the events Then only one receipt/invoice or refund document is created per unique transaction/refund ID And each party receives at most one email per unique event And only a single audit trail entry exists per unique transaction/refund ID And processing duplicates does not alter previously recorded timestamps or create duplicate dashboard timeline items

Merchant Configuration & Policy Controls

"As a business owner, I want to configure how sign-and-pay behaves for each template so that it aligns with my pricing, taxes, and payment policies."

Description

Provide settings for merchants to configure deposit rules (fixed or percentage with min/max), accepted payment methods, currencies, tax rates, surcharge handling, descriptor text, retry/backoff policies, and SCA enforcement preferences. Allow enabling PaySign Merge per template, mapping contract fields to payment calculations, and customizing the success page and notification templates. Expose safe defaults while supporting advanced overrides for different services and regions.

Acceptance Criteria

Deposit Rules Configuration (Fixed/Percentage with Min/Max)

Given a merchant selects a fixed deposit amount, When a contract total is present, Then the PaySign Merge amount equals the fixed value and never exceeds the contract total. Given a merchant selects a percentage deposit with min and max, When a contract total is present, Then the computed deposit equals contract_total * percentage, constrained to min ≤ amount ≤ max and not exceeding the contract total. Given a percentage deposit is computed, When currency minor units apply, Then the amount is rounded to the currency’s minor unit precision. Given invalid inputs (negative values, percentage > 100, min > max), When saving settings, Then validation errors prevent save and identify each invalid field. Given no merchant edits are made, When the settings page loads, Then safe defaults are visible and used for new templates. Given deposit rules are configured, When a contract is generated from a template with PaySign Merge enabled, Then the payment block auto-fills the required deposit based on the rules.

Accepted Payment Methods and Currencies

Given a merchant enables specific payment methods, When a signer views the PaySign Merge step, Then only the enabled methods are displayed. Given method-currency compatibility rules, When the template’s currency is not supported by a method, Then that method is hidden for the signer and flagged in the template editor. Given the merchant’s region and buyer’s billing country, When regional restrictions apply, Then only methods allowed in that region are available to the signer. Given no enabled method supports the template currency, When saving the template with PaySign Merge enabled, Then the save is blocked with a clear, actionable error. Given platform defaults, When a new merchant first opens payment settings, Then recommended methods for their country are preselected and can be overridden.

Tax Rates and Surcharge Handling by Region

Given tax rates are configured per jurisdiction, When the buyer’s billing address or tax ID is provided, Then tax is calculated and applied to the payable amount according to the matching jurisdiction. Given the buyer provides a valid tax-exempt ID, When validation succeeds, Then tax is not applied and the receipt reflects tax-exempt status. Given card surcharging is enabled with an allowed rate, When the buyer selects a card method, Then the surcharge is itemized and added; when a non-card method is selected, Then no surcharge is added. Given regional surcharge prohibitions, When the buyer’s region forbids surcharging, Then surcharges are not applied regardless of merchant settings. Given tax and/or surcharge are applied, When the signer reviews the payment summary, Then base amount, tax, surcharge, and total are itemized and rounded to currency precision. Given platform defaults, When merchant has not configured tax or surcharge, Then tax defaults to 0% and surcharges are disabled.

Strong Customer Authentication (SCA) Enforcement Preferences

Given the preference is set to Always require SCA, When a payment is initiated on an SCA-eligible method, Then a step-up challenge is requested before authorization. Given the preference is set to Frictionless when eligible, When the gateway indicates frictionless eligibility, Then no challenge is presented; otherwise a step-up challenge is requested. Given the SCA challenge is abandoned or fails, When the authorization is not completed, Then the payment is canceled, the contract remains signed but unpaid, and notifications are sent per templates. Given SCA events occur, When viewing the payment audit trail, Then SCA outcomes (frictionless, challenged, failed) are recorded with timestamps and reason codes. Given non-SCA eligible methods, When payment is attempted, Then no SCA challenge is triggered.

Payment Retry and Backoff Policies

Given retry policy is configured with max attempts N and base backoff B, When a payment fails with a retryable error, Then the system retries up to N times using exponential backoff (B, 2B, 4B, …) within operational windows. Given a non-retryable (hard decline/fraud) error, When a payment fails, Then no further retries are performed and the merchant is notified immediately. Given a retry succeeds after prior failures, When the payment is captured, Then the contract status updates to Signed & Paid and only a success notification is sent to the client; prior failure notices are not re-sent. Given all retries are exhausted without success, When the final attempt fails, Then the payment status is Failed, the contract remains Signed & Unpaid with a clear flag, and failure notifications are sent per templates. Given platform defaults, When no retry policy is configured, Then the default values for attempts and backoff are applied and visible in settings.

Template-Level Enablement and Field Mapping

Given PaySign Merge is enabled on a template, When a contract is generated from that template, Then the payment step is included and pre-populated with the computed amount and allowed methods. Given field mappings are configured (e.g., Total Amount, Deposit %), When those fields are present in the contract, Then the payable amount is computed from the mapped values; if a mapped field is missing, Then the sender is prompted to supply it before sending. Given template-level overrides (currency, tax rate, descriptor, surcharge), When the template is used, Then those overrides supersede account-level defaults for that contract. Given services or regions vary, When the merchant selects a service/region profile in the template, Then the associated advanced overrides load and are applied to calculations and UI. Given PaySign Merge is disabled on a template, When a contract is generated, Then no payment step is shown and only e-signature is required.

Custom Success Page and Notification Templates

Given a success page URL and message are configured, When a payment completes, Then the signer is redirected to the URL with secure parameters (contract_id, payment_id, amount) and a platform fallback page is used if the URL is unreachable. Given email/SMS templates are customized for success, failure, and retry events, When those events occur, Then notifications are sent using the selected channels with correctly rendered merge fields (e.g., client_name, amount, attempt_number). Given template-level notification overrides exist, When a contract is created from that template, Then template-level notifications supersede account-level defaults. Given the merchant previews templates, When clicking Preview, Then sample data is rendered without sending real messages and validation errors (missing required merge fields) are surfaced before save. Given platform defaults, When the merchant has not customized pages or notifications, Then branded default pages and messages are used.

Compliance, Security, and Audit Logging

"As a security-conscious merchant, I want strong compliance and detailed audit logs so that I can meet regulatory obligations and quickly resolve disputes."

Description

Ensure PCI DSS SAQ A scope by never storing raw card data, using tokenization, and encrypting all sensitive fields in transit and at rest. Implement GDPR/CCPA-aligned data minimization and retention controls, capture explicit consent where required, and enforce access controls. Maintain tamper-evident audit logs for all signature and payment events with timestamps, IP, user agent, and webhook verifications. Provide exportable logs and incident reporting hooks to support dispute resolution and regulatory inquiries.

Acceptance Criteria

SAQ A Card Data Handling and Tokenization

Given a client enters card details during PaySign Merge checkout When the payment form is submitted Then card data is captured only by a PCI DSS Level 1 PSP via hosted fields/iframe and never transits SnapAgree servers And SnapAgree stores only PSP tokens, last4, brand, expiry month/year, and transaction identifiers And no PAN, CVV, or unmasked card data appears in logs, analytics, or data stores (verified by automated PAN-pattern scans) And all data in transit uses TLS 1.2+ with HSTS enabled And sensitive fields at rest are encrypted with AES-256 and keys managed by a KMS with rotation

Explicit Consent Capture for Payment and Data Processing

Given a signer is at the combined sign-and-pay step When the UI is presented Then an unchecked consent checkbox with clear, specific processing purpose text is displayed and is required to proceed And the recorded consent includes timestamp (UTC), IP, user agent, contract ID, signer ID, consent text version, and locale And consent proof is linked to the signature record and payment transaction And if consent is not granted, signing and payment are blocked with an accessible message And a withdrawal-of-consent link is provided in the confirmation email and, when invoked, future processing is halted and retention rules are applied

Tamper-Evident Audit Logs for Signature and Payment Events

Given any signature or payment event occurs When the event is recorded Then an append-only audit entry is created with event type, contract ID, signer ID, actor, UTC ISO-8601 timestamp, IP, user agent, amount/currency, PSP transaction ID, outcome, and webhook status And each entry includes a SHA-256 hash and previous-entry hash to form a verifiable chain And audit storage is logically immutable; deletions create tombstone entries without altering historical records And an integrity verification job recomputes the chain and returns status=pass for unaltered logs And PII fields are masked in exports unless the requester has the Sensitive Logs permission

Webhook Verification and Idempotency for PSP and E‑Signature Events

Given a webhook is received from the PSP or e-signature module When the message signature is validated using HMAC/PK and the timestamp is within a 5-minute tolerance Then the event is processed; otherwise it is rejected with 401 and logged And processing uses an idempotency key so retries do not create duplicate payments or signatures And delivery attempts and outcomes are recorded with exponential backoff up to a configured retry limit before marking as failed And replayed or stale messages are rejected and logged

Exportable Audit Logs for Disputes and Regulatory Inquiries

Given an authorized admin requests logs for a contract or date range When the request is submitted Then the system exports audit logs in CSV and JSONL within 60 seconds for up to 100,000 records And exports include event fields, timestamps, IP, user agent, amounts, PSP IDs, consent details, and hash-chain proofs, plus a file-level checksum And the export action is itself audited with requester, filters, time, and delivery method And exports are delivered via expiring (24h) secure download link or pushed to a configured storage bucket with server-side encryption

Data Minimization and Retention Controls (GDPR/CCPA)

Given workspace-level retention policies are configured When new contracts, payments, and consents are processed Then only data strictly required for contract performance, billing, fraud prevention, and compliance is stored; optional fields are off by default And retention windows are configurable per data category (contracts, audit logs, payment tokens, consents) with documented defaults And upon policy expiry or a verified DSAR deletion request, data is deleted or irreversibly anonymized within 30 days and a deletion certificate is logged And data subject exports are provided in a machine-readable format within 30 days of verified request And backups respect retention schedules and purge deleted data in the next backup cycle

Role-Based Access Controls and Least Privilege

Given users are assigned roles and fine-grained permissions When attempting to view PII, payment tokens, or audit logs Then only users with explicit permissions can view or export such data And sensitive values are masked by default and require just-in-time elevation with reason capture and automatic timeout And all access to sensitive data is logged with user, time, resource, fields viewed, and declared purpose And failed access attempts are rate limited and generate alerts after a configurable threshold And service accounts use scoped tokens with expiration and enforced rotation

Smart Deposit

Get AI‑guided recommendations for deposit size and schedule based on deal value, risk flags, jurisdiction, and past client behavior. Adjust with one tap, preview client impact, and set clear terms so you reduce cash gaps without hurting conversion.

Requirements

Deal Signal Aggregation

"As a service-based business owner, I want SnapAgree to automatically gather the deal, client, and jurisdiction details so that deposit recommendations are accurate without me re-entering data."

Description

Ingest and normalize all inputs required for Smart Deposit, including deal value, contract risk flags, jurisdiction, client identity, and past client payment behavior. Integrate with SnapAgree’s contract editor, CRM integrations, and payment providers to pull signals (e.g., invoice history, late payments) while honoring data minimization and consent. Provide a unified profile and risk score per deal, with resilience features (timeouts, retries, fallbacks) and clear error states when data sources are unavailable.

Acceptance Criteria

Signal Aggregation from Editor and CRM within SLA

Given a deal exists with a saved SnapAgree contract draft and a linked CRM opportunity containing deal value and stage And the CRM API and SnapAgree editor service are available When the Deal Signal Aggregation service is invoked for the deal Then it fetches deal value, contract risk flags, jurisdiction, and client identity from the editor and CRM And completes aggregation within 5 seconds at P95 and 10 seconds at P99 over the last 24 hours And records source system, record ID, and fetched_at timestamp for each signal And persists a traceable aggregation_id linked to the deal

Jurisdiction and Currency Normalization Accuracy

Given incoming signals may contain free‑text jurisdiction and currency values from multiple sources When normalization runs Then jurisdiction values are mapped to ISO 3166-2 codes and countries to ISO 3166-1 alpha-2 And currencies are mapped to ISO 4217 codes with minor unit precision applied And unmapped values are flagged as UNMAPPED_VALUE with the original value preserved and a null normalized field And normalization accuracy on a 500-sample test corpus is ≥ 99% exact match And normalization is deterministic (same input yields same output)

Client Identity Resolution Across CRM and Payments

Given a client appears in CRM and payment provider with different identifiers And email domains and company names may vary in formatting When identity resolution executes Then a single client_id (UUIDv4) is assigned to matched records And exact match on email OR (normalized company name AND billing country) creates a link And fuzzy match (token-based, case-insensitive) with confidence ≥ 0.90 creates a link; otherwise no link is created And the chosen rule, confidence score, and matched fields are stored in an identity_match object And no link is created for confidence < 0.90

Consent and Data Minimization Enforcement

Given the user has connected integrations with explicit consent settings per provider When aggregation requests data Then only fields enumerated in the data minimization allowlist are requested and stored And requests to providers without active consent are blocked and surfaced as CONSENT_REQUIRED And if summary_only is enabled, raw invoice line items are not stored; only totals and payment status are retained And personal data is retained for 365 days then purged, unless consent is renewed And all outbound requests include consent version and purpose in metadata

Unified Deal Profile and Risk Score Output

Given required signals have been ingested or appropriately marked missing When the unified profile is generated Then the profile JSON conforms to schema version v1.0 with required fields: deal_value, currency, risk_flags[], jurisdiction_code, client_id, payment_behavior_summary, risk_score (0–100), confidence (0–1), sources[] And risk_score computation is deterministic for identical inputs and completes within 200 ms at P95 And if any required signal is missing, confidence is reduced proportionally and LOW_SIGNAL is added to risk_flags when confidence < 0.60 And scoring quality on the validation set meets AUC ≥ 0.75 and KS ≥ 0.25 And the schema version is embedded and backward-compatible changes increment the minor version only

Resilience: Timeouts, Retries, and Fallbacks

Given upstream providers may be slow or unavailable When calling each provider API Then per-call timeout is set to 2.5 seconds with 2 retries using exponential backoff with jitter capped at 8 seconds And on timeout or 5xx, cached data not older than 30 days is used and flagged as STALE_SOURCE with fetched_at timestamp And on 429 rate limits, the call fails fast with RATE_LIMITED and a background refresh is scheduled respecting Retry-After And overall aggregation wall-clock time does not exceed a 10-second budget And all retries and fallbacks are recorded in an aggregation_diagnostics object

Clear Error States and Observability

Given any data source returns an error or is unreachable during aggregation When aggregation completes Then the UI shows per-signal error badges with human-readable messages and standardized error codes: CONSENT_REQUIRED, SOURCE_TIMEOUT, SOURCE_ERROR, RATE_LIMITED, UNMAPPED_VALUE And a retry action is available for retryable errors and disabled for non-retryable ones with tooltip explanation And logs include correlation_id, provider, endpoint, status_code, attempt, latency_ms, and redacted payload with no PII And metrics are emitted per provider: success_rate, error_rate by code, p95_latency, retry_count, fallback_rate And an alert is triggered if success_rate < 95% for any provider over a 15-minute window

Deposit Recommendation Engine

"As a freelancer, I want AI to suggest an optimal deposit and schedule so that I reduce cash gaps while preserving my chance of winning the deal."

Description

Compute recommended deposit percentage and payment schedule options (e.g., upfront + milestone splits) using deal value, risk score, industry norms, jurisdictional rules, and past client behavior. Output the top options with rationale, expected cash flow impact, and predicted client acceptance. Enforce configurable business guardrails (min/max deposit, schedule count) and expose a service API for the editor to fetch recommendations on demand.

Acceptance Criteria

Compute Top Deposit and Schedule Options from Multi-Factor Inputs

Given a deal with value, riskScore, industry, jurisdiction, and clientId When the engine generates deposit recommendations Then it returns between 3 and 5 ranked options when at least 3 valid options exist; otherwise it returns all valid options but at least 1 And each option includes fields: depositPercentage (0-100 with 0.01 precision), schedule (array of installments with percentage and dueTrigger), and totalPercentage across installments equals 100 And options are deterministic for identical inputs (same seed) and change when any input changes And options are ordered by descending predictedAcceptance; ties are broken by descending expectedCashFlow.day0

Include Rationale, Cash Flow Impact, and Acceptance Prediction in Output

Given any generated recommendation option When inspecting the option payload Then rationale includes at least 3 contributing factors with fields factorName, valueUsed, and contributionWeight where weights sum to 1.0 +/- 0.01 And expectedCashFlow includes currency, amounts for day0, day30, and day60 that reconcile with the schedule totals within +/- 1 unit of currency rounding And predictedAcceptance is provided as a float in the range [0.00, 1.00] with 2 decimal places And rationaleSummary is present and <= 280 characters

Enforce Configurable Business Guardrails on Recommendations

Given business guardrails minDepositPercent, maxDepositPercent, and maxScheduleCount are configured When the engine generates recommendations Then no option has depositPercentage < minDepositPercent or > maxDepositPercent And schedule length per option <= maxScheduleCount And if all unconstrained options would violate guardrails, the engine adjusts to nearest allowed values and sets guardrailAdjusted = true with guardrailNotes populated

Apply Jurisdictional and Industry Norm Constraints

Given jurisdictionRules exist for the request's jurisdiction and industry When recommendations are generated Then all options comply with any deposit caps and schedule restrictions defined by jurisdictionRules And each option includes compliance = "compliant" and ruleRef identifiers for rules applied And if no rules are found, options include compliance = "unknown" with no ruleRef and the engine still returns recommendations

Service API Returns Recommendations On-Demand with SLAs

Given an authenticated caller with scope contracts:recommendations When a POST /v1/deposits/recommendations request with a valid payload (dealValue > 0, riskScore in [0,1], industry, jurisdiction, clientId) is sent Then the API responds 200 within p95 <= 800 ms and includes requestId, modelVersion, and an options array conforming to the published JSON schema And invalid payloads return 422 with a machine-readable errors[]; unauthorized returns 401; rate-limited returns 429 with Retry-After; transient failures return 503 And repeated requests with the same Idempotency-Key within 24h return the identical response body and idempotencyStatus = "replayed"

Leverage Past Client Payment Behavior in Recommendations

Given two identical requests except clientId where client A has on-time history and client B has chronic late payments (>20 days late on >=3 invoices in the last 12 months) When recommendations are generated Then the top option for client B has a depositPercentage at least 10 percentage points higher than client A unless capped by maxDepositPercent And the rationale for client B includes factors latePaymentRate and avgDaysLate And predictedAcceptance for client B differs from client A by at least 0.05 absolute unless bounded by 0 or 1

Graceful Handling of Missing or Out-of-Range Inputs

Given a request with missing optional fields (industry or clientId) When recommendations are generated Then the engine uses global norms and/or anonymous client priors and includes an assumptions[] describing fallbacks used And for out-of-range inputs (riskScore outside [0,1] or dealValue <= 0), the API returns 422 with specific field errors and no options And for an unsupported jurisdiction, the engine still returns options using global norms with compliance = "unsupported_jurisdiction" and rationale noting the limitation

Client Impact Preview

"As a small-business owner, I want to preview how different deposit options affect client acceptance and my cash flow so that I can choose terms that won’t hurt conversion."

Description

Visualize how each recommended or adjusted deposit option affects client affordability and conversion likelihood. Show projected acceptance probability, upfront amount due, payment timeline, and total cost at each milestone, alongside seller cash flow projections. Update these metrics in real time as the user tweaks sliders or selects presets, and surface any risk or compliance warnings before finalizing.

Acceptance Criteria

Real-Time Update on Deposit Adjustments

Given the Client Impact Preview is visible and an initial deposit is set When the user adjusts the deposit percentage slider, edits the upfront amount, or changes schedule offsets Then the acceptance probability, upfront amount due, payment timeline, total per milestone, and seller cash flow projection recalculate and render within 500 ms at the 95th percentile And all displayed values reflect the latest input (no stale values) and are internally consistent (sum of milestone totals equals contract total within ±$0.01) And an updating indicator appears if recalculation exceeds 500 ms

Required Metrics Visibility and Formatting

Given the Client Impact Preview is visible Then the UI shows for the current option: acceptance probability (0–100% with one decimal), upfront amount due (currency symbol/code with 2 decimals), payment timeline (each milestone shows due date and amount), total cost at each milestone, and seller cash flow projections (per-milestone and cumulative) And currency matches the contract currency and amounts are rounded to 2 decimals with standard rounding And dates use the contract’s timezone and locale date format

Preset Selection Reflects in Preview

Given the user sees a list of deposit presets When the user selects a preset (e.g., 25% now / 75% on delivery) Then the payment timeline renders the preset’s milestones and due dates, and the upfront amount reflects the preset’s upfront percentage And the acceptance probability and cash flow projections update to match the preset within 500 ms at the 95th percentile And the selected preset is visually indicated as active

Risk and Compliance Warnings Before Finalization

Given a recommended or adjusted option triggers risk or compliance rules When the user attempts to finalize the deposit terms Then any blocking warnings prevent finalization and display the rule name, reason, and a suggested remedy And advisory warnings display without blocking finalization And the user can adjust terms to clear warnings, after which finalization becomes enabled

Cash Flow Projection Calculation Accuracy

Given any valid schedule of milestones and amounts Then the cash flow projection shows per-milestone inflows and a cumulative curve that equals the sum of milestone amounts And the cumulative total equals the contract total within ±$0.01 And moving any milestone date or amount updates the projection accordingly within 500 ms at the 95th percentile

Boundary Conditions and Error Handling

Given the user sets deposit to 0% or 100%, or to the min/max allowed by jurisdictional rules Then the preview renders valid metrics without errors or NaN/Infinity values And timelines collapse to a single milestone for 100% upfront and expand appropriately for 0% upfront And applicable warnings surface without blocking unless a rule is violated

Jurisdiction and Currency Consistency

Given the contract jurisdiction and currency are set When the user changes jurisdiction or currency in contract settings Then the preview updates to reflect the new currency formatting, and any jurisdiction-specific rules affecting deposit limits or schedules update the warnings and timeline accordingly And all amounts remain mathematically consistent after conversion (differences restricted to rounding ≤ $0.01 per milestone)

One-tap Adjustment & Validation

"As a user, I want to accept or tweak the suggested deposit with one tap and know it’s valid so that I can finalize terms quickly and confidently."

Description

Provide one-tap controls and presets to accept a recommendation or quickly adjust deposit percentage and schedule (e.g., +5%, split into 3 milestones). Validate in-line against jurisdictional limits and business rules, preventing invalid configurations. Recalculate and display updated client impact instantly, and allow a single confirm action to apply the selection across the contract and downstream systems.

Acceptance Criteria

One-Tap Accept Recommended Deposit

Given a generated deposit recommendation exists for a deal value of $10,000 and the Smart Deposit panel is open When the user taps "Accept recommendation" Then the deposit percentage and schedule fields populate with the recommended values within 300 ms And the selected preset displays as active And no validation errors are shown And the Confirm action becomes enabled

Quick Percentage Adjustment via Presets

Given the current deposit is 30% and the policy max upfront is 33% When the user taps "+5%" Then the deposit updates to 33% within 300 ms (capped at max) And a non-blocking note "Capped at 33% max upfront" is displayed And the Confirm action remains enabled Given the current deposit is 22% and the policy min upfront for High Risk is 20% When the user taps "-5%" Then the deposit updates to 20% within 300 ms (floored at min) And a non-blocking note "Floored at 20% policy minimum" is displayed And the Confirm action remains enabled

Split Deposit into Three Milestones Preset

Given the deposit is 30% and the "3 milestones" preset is available When the user taps "3 milestones" Then the schedule updates to 10% / 10% / 10% within 300 ms And the sum equals the deposit percentage (30%) And milestone due dates default to Start, Midpoint, and Completion based on contract timeline metadata And no validation errors are shown Given the jurisdictional policy MaxUpfrontMilestones = 2 When the user taps "3 milestones" Then the change is blocked And an inline error "Max 2 upfront payments allowed in this jurisdiction" appears within 100 ms And the schedule remains unchanged

Inline Jurisdictional and Policy Validation

Given jurisdiction = CA-ON and policy MaxUpfrontPercentage = 10% When the user inputs 15% deposit via the custom input Then an inline error "Exceeds max upfront (10%) in CA-ON" appears within 100 ms And the deposit field is highlighted as invalid And the Confirm action is disabled Given all policy checks pass When the user adjusts the deposit or schedule Then no validation errors are shown And the Confirm action is enabled

Instant Client Impact Recalculation and Display

Given the Client Impact panel is visible When the user changes the deposit percentage or schedule Then the panel updates the upfront amount (currency and %), number of payments, and projected first payment date within 500 ms at p95 And monetary values are rounded to 2 decimals using the deal currency And any associated risk flags refresh to reflect the new configuration Given the conversion impact model is unavailable When the user changes the deposit or schedule Then the panel displays "Conversion impact unavailable" without blocking confirmation

Single Confirm Applies Across Contract and Systems Atomically

Given a valid deposit configuration is selected When the user taps "Confirm" Then the Payment Terms clause in the contract updates to the selected percentage and milestone schedule And the billing system receives a matching payment schedule (amounts and dates) And the CRM deal record updates with deposit percentage and milestone count And an audit log is recorded with actor, timestamp, previous value, new value, and correlation ID And all updates complete within 2 seconds at p95 And the user sees a success confirmation Given any downstream update fails When the user taps "Confirm" Then no partial changes are persisted And the user sees an error message naming the failed system And the selection remains editable

Graceful Degradation on Validation Service Timeout

Given the policy validation service times out after 800 ms When the user attempts to adjust the deposit or schedule Then a non-blocking banner "Validation temporarily unavailable—retrying" is displayed And the Confirm action is disabled And the system retries validation up to 3 times with exponential backoff starting at 1 second And upon successful validation, the banner clears and Confirm reflects the validation result Given validation remains unavailable after 3 retries When the user is on the Smart Deposit panel Then an error state is shown with a "Try again" action And an analytics event "ValidationUnavailable" is logged with a correlation ID

Clause Auto‑Generation & Contract Sync

"As a contract author, I want the chosen deposit terms to auto-generate as clear clauses in my agreement so that I don’t have to write or rework legal language."

Description

Generate clear, plain-language deposit and payment terms that mirror the selected schedule, including amounts, due dates, refund/forfeit conditions, and late-fee policy. Insert clauses into the active contract, maintain synchronization if terms change, support localization (currency, language, jurisdictional phrasing), and surface tracked changes for client review and e-sign without breaking existing workflows.

Acceptance Criteria

Auto-Generate Deposit & Payment Clause from Selected Schedule

Given a deal value and a selected deposit/payment schedule When the user clicks Generate Clause Then a plain-language clause is inserted into the active contract that includes the deposit amount(s), remaining payment amount(s), due date(s), refund/forfeit conditions, and late-fee policy And all monetary amounts are correctly calculated from the deal value and schedule percentages/amounts and rounded to 2 decimals And the sum of all payment amounts in the clause equals the deal value And due dates in the clause mirror the schedule’s dates or relative triggers (e.g., “on signature,” “on delivery,” specific calendar dates) And currency formatting matches the selected currency conventions And the clause is linked to the selected schedule to enable synchronization

Real-Time Clause–Schedule Synchronization (Two-Way)

Given a clause has been generated and inserted based on Schedule S1 When the user updates Schedule S1 (e.g., changes deposit percentage or a due date) Then the clause updates within 2 seconds to reflect the new amounts and dates And modified text is marked via tracked changes And the sum of amounts continues to equal the deal value Given the user edits an amount or due date directly in the clause When they save the contract Then the underlying schedule updates to match the clause And any inconsistency triggers a validation message offering Apply Changes or Revert, with no silent divergence between clause and schedule

Localization of Currency, Language, and Jurisdictional Phrasing

- When locale=en-US and currency=USD, amounts render like $1,234.56 and dates like Jan 31, 2025; clause language is English (US) - When locale=en-GB and currency=GBP, amounts render like £1,234.56 and dates like 31 Jan 2025; clause language is English (UK) - When locale=fr-FR and currency=EUR, amounts render like 1 234,56 € and dates like 31/01/2025; clause language is French - Jurisdictional phrasing for late fees and refunds uses the approved phrase library for the selected jurisdiction with no unresolved placeholders - Localized content is consistent across the clause and the Smart Deposit panel; no mixed locales - If a requested locale is unsupported, the system falls back to English and ISO currency code with a visible non-blocking notice

Tracked Changes and Redline for Client Review

Given track changes is enabled for the contract When the clause is inserted or updated by the system Then all inserted/modified text is redlined and attributable to System with timestamp And Accept and Reject actions are available per change And accepting all changes yields a clean clause ready for signature And exporting a client preview shows redlines when review mode is on, and the clean version when review mode is off And the e-sign package uses the clean, accepted text while retaining an audit log of changes

Late Fee and Refund/Forfeit Conditions Accuracy

Given policy settings specify a late-fee rate, grace period, and cap, and define refund/forfeit rules for the deposit When the clause is generated Then the clause states the late-fee rate, grace period, and cap exactly as configured And the refund/forfeit conditions are stated exactly as configured And toggling late fees off removes late-fee language from the clause And changing any of these policy settings updates the clause within 2 seconds and is shown via tracked changes

Non-Disruptive Contract Insertion and E‑Sign Workflow Integrity

- Insertion preserves existing numbering and headings without duplication or mis-sequencing - Cross-references update automatically to point to the new clause where applicable - No template variables/placeholders are broken or left unresolved after insertion - Contract exports (e.g., PDF) and share/preview continue to function without errors - E-sign workflow initiates and completes without additional manual steps; existing signature fields remain correctly mapped - Removing the clause reverts numbering and cross-references cleanly without orphaned references

Jurisdictional Rules Management

"As a user operating across regions, I want Smart Deposit to respect local rules automatically so that I stay compliant without researching laws myself."

Description

Maintain an up-to-date rules library for deposit practices by jurisdiction (e.g., caps, escrow requirements, consumer protections). Provide versioning, auditability, admin updates, and automated rule checks during recommendation and validation. Offer safe fallbacks when rules are unknown and log conflicts for review.

Acceptance Criteria

Admin updates a jurisdiction’s deposit cap rule

Given a user with the 'Rules Admin' role When they create or update a 'deposit_cap' rule for a jurisdiction Then the system validates required fields: jurisdiction_code, rule_type, cap_percent (0–100), actor_scope (B2B/B2C/Both), effective_start, optional effective_end, legal_source_url, change_note And Then save is blocked with inline errors if validation fails And When the rule is published Then a new immutable version is created and prior versions become read-only And Then an audit log entry is recorded with admin_id, timestamp, version_from, version_to, change_diff, reason_code, and IP And Then the rule evaluation cache for that jurisdiction is invalidated and the new rule is available to evaluators within 60 seconds And Then only users with 'Rules Admin' can publish; non-admins may save drafts only

Automated rule evaluation during deposit recommendation

Given a draft contract with deal_value, client_type, effective_date, and determined jurisdiction When the Smart Deposit engine generates a recommendation Then all active rules applicable to the jurisdiction and client_type on the effective_date are evaluated And Then the recommended deposit percent does not exceed the active cap_percent And Then if escrow_required=true, the recommendation contains escrow instructions And Then if any rule would be violated, the engine adjusts to the nearest compliant value and attaches explanatory flags including rule_ids and citations And Then evaluation latency is ≤200 ms p95 with warm cache and ≤500 ms p95 on cold start And Then the rules_version used is attached to the recommendation payload

Validation of user-adjusted deposit terms before sending

Given a user edits the deposit percent and/or schedule on a draft contract When they attempt to save or proceed to send for e-signature Then the system validates the terms against applicable rules for the contract’s jurisdiction, client_type, and effective_date And Then violations of mandatory rules block progression with a message naming the rule, required correction, and citation link And Then violations of advisory rules present a non-blocking warning and allow override with a required justification ≥15 characters And Then all overrides are captured in audit with user_id, timestamp, rule_id, justification, and contract_id And Then the "Preview client impact" reflects the final compliant terms and any advisory warnings

Safe fallback when jurisdiction rules are unknown or stale

Given the jurisdiction has no active rules, rules cannot be loaded, or last_verified_date > 365 days When generating recommendations or validating edited terms Then the system applies a conservative fallback policy: cap_percent=20% for consumer (B2C), 40% for B2B, escrow_required=false And Then the UI displays an "Unknown rules" banner with plain-language explanation and a link to request/admin update And Then no hard block is applied solely due to unknown rules; recommendations proceed with flags And Then an internal backlog task is created containing jurisdiction_code, detection_reason, first_seen_timestamp, and impact_count And Then analytics include rules_confidence="low" and fallback_policy_id in the event payload

Rule conflict detection and precedence resolution logging

Given two or more active rules overlap for the same jurisdiction and client_type with conflicting outcomes When the rules engine loads or evaluates rules Then the engine detects the conflict and applies precedence: municipal > state > federal; if tied, newer effective_start wins; if still tied, mandatory > advisory And Then the chosen rule_ids and the discarded rule_ids are recorded in an immutable 'conflict_resolved' log with decision_path and evaluator_version And Then an alert is sent to the Rules Admin channel within 5 minutes summarizing the conflict and linking to a resolution view And Then evaluation continues using the resolved rule set and the recommendation payload includes precedence_summary

Rule versioning and time-travel audit

Given a contract was generated or sent on a past date using rules_version R When a user views history or re-opens the contract for amendment Then the system can display and re-evaluate the deposit recommendation using exactly rules_version R as of the original effective_date And Then the audit view shows the rules_version, evaluator_version, input parameters, outputs, and any user overrides with timestamps And Then exporting the audit produces a downloadable JSON and PDF bundle containing rule citations and diffs within 10 seconds p95

Jurisdiction determination and configuration

Given a contract has governing_law, service_location, and client_billing_address When determining the applicable jurisdiction for rules evaluation Then the system uses workspace-configured precedence: default is governing_law > service_location > client_billing_address And Then if multiple jurisdictions apply, the most restrictive applicable rule outcome is selected and noted And Then the decision path and inputs are logged with a trace_id and persisted with the contract And Then if no jurisdiction can be determined, the user is prompted to select one before proceeding and evaluation is deferred

Override Capture & Learning Feedback

"As a product user, I want the system to learn from my overrides and outcomes so that future recommendations better match my clients and deals."

Description

Capture when users override recommendations, including selected terms, reason codes, and outcomes (acceptance, payment timeliness). Feed this data into analytics and model retraining, with privacy controls and opt-outs. Provide dashboards to monitor acceptance rates, cash gap reduction, and the impact of different deposit schedules over time.

Acceptance Criteria

Override Event Capture for Deposit Recommendations

Given a user modifies AI-recommended deposit terms (amount and/or schedule), When the user saves the draft or sends the contract, Then an OverrideCaptured event is persisted within 2 seconds containing: user_id, org_id, contract_id, version, recommendation_id, recommended_terms, selected_terms, jurisdiction, risk_flags, client_identifier_hash, timestamp, app_version. Given no change is made to AI-recommended deposit terms, When the user saves or sends, Then no OverrideCaptured event is created. Given an override event exists, When queried by contract_id and version, Then exactly one deduplicated record is returned.

Reason Codes and Justification Collection

Given a user modifies AI-recommended deposit terms, When the override UI is shown, Then the user is presented with a single-select list of reason codes: [Client pushback, Cashflow needs, Jurisdictional constraint, Risk flag sensitivity, Custom pricing, Other]. Given a user submits without selecting a reason, When the contract is saved or sent, Then reason_code is stored as "Unspecified" and reason_text is null. Given the user selects "Other", When they proceed, Then a free-text justification up to 500 characters is accepted and stored in reason_text. Given any reason is selected, When persisted, Then reason_code must be one of the allowed values and pass server-side validation.

Outcome Tracking: Acceptance and Payment Timeliness Linkage

Given a contract with an override is sent, When the client accepts, declines, or the offer expires, Then outcome.acceptance_status ∈ {Accepted, Declined, Expired} is recorded and linked to the override by contract_id within 5 minutes of the event. Given an accepted contract with deposit invoice due date D, When a payment event is received, Then payment_timeliness_days = payment_received_at − D is computed and stored; on-time if payment_timeliness_days ≤ 0. Given multiple payment events, When computing payment timeliness, Then the earliest payment meeting or exceeding the deposit amount is used. Given no payment event by D+30 days, When nightly jobs run, Then payment_timeliness_days is set to >30 and status = "Late>30".

Privacy Controls and Opt-Out Enforcement

Given a user opens Data & Privacy settings, When they toggle "Share override data for analytics and model training," Then the preference is saved with timestamp, user_id, and scope (org/user) and is auditable. Given opt-out is enabled, When an override event is created, Then the record is flagged excluded_from_training = true and excluded_from_analytics = true, and no personal data beyond operational necessity is persisted. Given opt-in is enabled, When an override event is created, Then client identifiers are stored only as salted SHA-256 hashes and no raw PII is persisted. Given a data export request is submitted, When processed, Then all override records for that user are exported within 7 days with fields redacted per policy. Given a delete (erasure) request is submitted, When processed, Then override records are removed from analytics/training stores within 30 days and tombstoned in the operational datastore.

Analytics Dashboard: Acceptance, Cash Gap, and Schedule Impact

Given a user with Analytics permission opens the Smart Deposit dashboard, When data loads, Then KPIs are shown for the selected date range: acceptance_rate (%), avg_cash_gap_days, avg_deposit_amount_pct, and breakdown by deposit schedule type. Given filters (jurisdiction, risk flags, client segment, industry, deal value range) are applied, When applied, Then KPIs and charts update within 3 seconds and reflect filtered populations. Given ≥50 eligible contracts in the period, When comparing schedule types, Then the dashboard shows acceptance deltas with a 95% confidence indicator; otherwise displays "insufficient data". Given a data freshness SLA of 60 minutes, When now − last_refresh_at > 60 minutes, Then a stale data banner is displayed. Given the user clicks Download CSV, When export runs, Then a CSV reflecting current filters and visible columns is downloaded within 15 seconds.

Model Retraining Data Pipeline Compliance

Given daily ETL at 02:00 UTC, When it runs, Then a training dataset is written in parquet containing only opted-in, anonymized override records with schema_version ≥ v1.2 and row_count ≥ 80% of previous_day_row_count (or alert triggered). Given ETL completes, When data quality checks run, Then null rate per required field (reason_code, selected_terms, outcome.acceptance_status) ≤ 1% and duplicate rate on (contract_id, version) = 0%. Given a retraining job is triggered, When it consumes the dataset, Then logs include dataset_id, schema_version, generation_timestamp, and privacy_compliance=true. Given a data subject opts out after prior inclusion, When the next ETL runs, Then previously included records are excluded and a backfill deletion removes them from the training store within 48 hours.

AnyPay Checkout

Offer clients their preferred way to pay—cards, ACH, Apple Pay/Google Pay, and local bank methods—in multiple currencies with 3D Secure/SCA compliance. Toggle fee pass‑through vs. absorb, surface VAT/GST fields automatically, and boost completion rates across borders.

Requirements

Payment Method Orchestration

"As a client of a SnapAgree user, I want to pay with my preferred method so that I can complete checkout quickly without friction."

Description

Implement a unified checkout that supports cards, ACH/SEPA debit, Apple Pay, Google Pay, and region-specific bank methods (e.g., iDEAL, Bancontact) with dynamic availability based on buyer locale. Use provider SDKs and tokenization to keep PCI scope minimal, with idempotent payment intents, saved payment methods, and backend webhooks to track lifecycle events. Provide drop-in UI components for web and mobile, plus server endpoints for creating and confirming payments. Ensure fallback handling, retries, and clear error messaging to maximize conversion, while linking each payment to the originating contract and buyer record in SnapAgree.

Acceptance Criteria

Dynamic Payment Method Availability by Locale & Currency

Given buyer country = NL and currency = EUR When the checkout loads Then iDEAL is displayed and Bancontact, ACH, and local-only methods not supported in NL are hidden Given buyer country = BE and currency = EUR When the checkout loads Then Bancontact is displayed and iDEAL, ACH, and other unsupported methods are hidden Given buyer country = US and currency = USD When the checkout loads Then ACH and cards are displayed, iDEAL and Bancontact are hidden Given the buyer changes country or currency in the checkout When the selection is updated Then the payment method list refreshes within 300 ms to reflect supported methods Given Apple Pay/Google Pay device/browser capability and merchant verification status When capability is unavailable or the merchant is not verified Then Apple Pay/Google Pay buttons are not rendered

Provider SDK Tokenization and PCI Scope Minimization

Given a buyer enters card or bank details When a payment method is created Then no raw PAN, CVC, or full bank account numbers are transmitted to SnapAgree servers and only a token/payment_method_id is sent Given application network traffic and logs are inspected When requests to SnapAgree are reviewed Then no sensitive fields are present in payloads or logs and last4/brand-only metadata may appear Given a PCI SAQ assessment is executed for the integration When scope is evaluated Then the implementation qualifies for SAQ A or equivalent minimal scope

Idempotent Payment Intents and Duplicate Submission Protection

Given N (>=5) concurrent POSTs to /payments/confirm for the same contract, buyer, amount, and idempotency key When the server processes the requests Then exactly one payment intent is created/captured and all responses return the same intent id and status Given a client retries /payments/confirm after a network timeout with the same idempotency key When the server receives the retry Then the original intent is returned and no additional charge is created Given provider webhooks for the same intent are delivered multiple times When the webhook handler runs Then processing is idempotent and the payment record is updated once Given an authenticated request to /payments/create with contractId, buyerId, amount, and currency When payload is valid Then the server returns 201 with a client_secret/intent_id; on invalid input it returns 4xx with error codes

SCA/3DS Flow Handling and Compliance

Given a card transaction subject to SCA in the EEA/UK When the provider indicates requires_action Then a 3D Secure challenge is presented and on successful authentication the payment transitions to succeeded Given the provider returns a frictionless authentication result When confirming the payment Then the payment completes without challenge and status is succeeded Given authentication fails or is abandoned When the flow returns failure Then the status is requires_payment_method or failed and the user sees a clear error with a Retry option that reuses the same intent Given 3DS outcome and liability shift details When the payment completes Then the outcome and liability shift flags are stored on the payment record

Saved Payment Methods with Mandates and Consent

Given the buyer checks Save this payment method When the payment succeeds Then the tokenized method is stored on the buyer profile with consent timestamp and scope Given ACH or SEPA Direct Debit is selected When the mandate text is displayed and accepted Then acceptance is recorded and the mandate id is stored and retrievable for audits Given a subsequent payment uses a saved method When the buyer selects the saved method Then the payment completes without re-entering credentials and any required SCA/mandate confirmation is handled Given the buyer deletes a saved method from their account When deletion is confirmed Then the method is removed from vault and no longer appears in checkout

Webhook Lifecycle Tracking Linked to Contract and Buyer

Given a payment intent is created, updated, succeeded, failed, canceled, or refunded at the provider When the webhook is received Then SnapAgree upserts a Payment record linked to the originating contractId and buyerId with correct amount, currency, and status Given events are delivered out of order or retried When processing the events Then handling is idempotent and the final persisted state reflects the latest provider status Given a refund or cancellation occurs When processed via webhook Then the Payment record transitions to refunded or canceled and the Contract timeline displays the event within 5 seconds

Cross-Platform Drop-in Checkout UI with Error States

Given the web checkout component is embedded When tested on the latest Chrome, Safari, Firefox, and Edge Then the UI renders correctly, supports keyboard navigation (WCAG 2.1 AA), and localizes labels/amounts by buyer locale Given mobile SDKs are integrated in iOS and Android apps When paying with Apple Pay, Google Pay, card, ACH/SEPA, or local methods Then payment flows complete and the client reports status to the server endpoints Given an initialization or method-specific error occurs (e.g., Apple Pay unavailable, bank redirect timeout) When the user remains on checkout Then a non-technical error message is displayed and alternative available methods are offered without losing form state

SCA/3DS2 Compliance & Risk Controls

"As a business owner operating in SCA regions, I want authentication handled automatically so that payments remain compliant and approval rates stay high."

Description

Enable PSD2 SCA compliance with automatic 3DS2 flows, including frictionless attempts, step-up challenges, and exemption handling (low-value, MIT, TRA where supported). Orchestrate issuer and wallet-based authentication (Apple Pay/Google Pay) with proper challenge UX, fallbacks to 3DS1 where needed, and comprehensive audit logs. Configure risk rules (velocity checks, AVS/CVC validation, BIN/geo checks) and leverage network tokens/card updater to reduce declines. Surface clear statuses to users and store authentication results on the payment record for dispute evidence.

Acceptance Criteria

Frictionless 3DS2 Authentication for Low-Risk Card Payments

Given a low-risk card payment with a 3DS2-enrolled card and a supported issuer When the customer authorizes payment in checkout Then the system attempts 3DS2 frictionless authentication without displaying a challenge And the checkout UI shows status "Authenticated (Frictionless)" And the payment record stores threeDSVersion, transStatus in {Y, A}, dsTransID, eci, liabilityShift flag, and timestamp And an audit log entry records request/response IDs, transStatus, and issuer response codes

Step-Up 3DS2 Challenge UX and Completion

Given a card payment where the issuer requires a 3DS2 challenge (transStatus = C) When the challenge is initiated Then the customer is presented an embedded/app-to-app challenge flow meeting WCAG 2.1 AA for forms And on successful completion the UI shows status "Authenticated (Challenge)" and proceeds to authorize And on failure/timeout/cancel the UI shows status "Authentication Failed" and offers retry or alternate payment And the payment record stores authenticationValue (CAVV), eci, threeDSVersion, transStatus result, challenge method (browser/app), and timestamps And an audit log captures challenge start/end, outcome, and issuer ACS reference IDs

Wallet-Based SCA via Apple Pay/Google Pay

Given the customer selects Apple Pay or Google Pay for payment When the wallet completes biometric/device-based SCA Then no separate 3DS2 challenge is shown And the UI shows status "Wallet Authenticated" And the payment record stores wallet type, cryptogram/3DS attestation where provided, networkTransactionId, and liabilityShift flag And on wallet failure the system offers fallback to card + 3DS2 with user consent, recording the fallback decision in audit logs

3DS1 Fallback for Unsupported Issuers/Regions

Given a card payment where 3DS2 is unavailable or errors with a retryable code When fallback is enabled by configuration Then the system attempts 3DS1 and presents the issuer challenge page if required And the UI shows status "3DS1 Authenticated" or "3DS1 Attempted" accordingly And the payment record stores 3DS1 fields (xid, cavv if present, eci), fallback reason, and timestamps And an audit log links the failed 3DS2 attempt to the 3DS1 fallback with correlation IDs

Exemption Handling: Low-Value, MIT, TRA

Given a transaction eligible for a PSD2 exemption (Low-Value, MIT, or TRA) When the appropriate exemption indicator is sent to the issuer/acquirer Then if the issuer accepts, no challenge is shown and the UI shows status "Exempted (<type>)" And if the issuer soft-declines, the system automatically falls back to 3DS2 challenge And the payment record stores exemption type requested, outcome (accepted/soft-declined), acquirer/issuer codes, and any reference to prior SCA (for MIT) And audit logs include risk score (for TRA), exemption request/response payload summaries, and decision timestamps

Risk Controls Enforcement: Velocity, AVS/CVC, BIN/Geo

Given merchant-configured risk rules for velocity, AVS/CVC, and BIN/geo When a payment attempt is evaluated Then rules execute in deterministic order and yield an action: allow, step-up (3DS challenge), or block And rule hits are displayed in the review pane and written to audit logs with rule IDs and inputs And if action = step-up, a 3DS2 challenge is initiated; if action = block, authorization is not attempted And the payment record stores the evaluated rules, action taken, and any AVS/CVC result codes received And configuration changes to rules take effect on the next attempt and are versioned in audit logs

Network Tokens & Card Updater to Reduce Declines

Given a stored card eligible for network tokenization and account updater When a payment or vaulting event occurs Then the system prefers network tokens over PAN where available and valid And if tokenization is unavailable, it safely falls back to PAN with the same SCA/risk flow And card details are refreshed via account updater on schedule without customer action, updating expiry and status And the payment record stores whether token or PAN was used, token reference, and updater outcomes And audit logs include tokenization attempts, updater events, and any changes to stored credentials

Multi‑Currency Pricing & Settlement

"As a global seller, I want to charge in my customer’s local currency so that they trust the price and are more likely to complete payment."

Description

Present prices and accept payments in customers’ local currencies with accurate display, rounding, and formatting rules. Support merchant-configurable pricing per currency or dynamic FX conversion with provider rates and optional margin. Allow selection of settlement currency per account, and handle currency mismatches via automatic conversion. Expose APIs and admin settings to map products/contracts to currencies, define rounding rules, and set currency fallbacks when a method or region is unsupported.

Acceptance Criteria

Localized Price Display per Currency

Given a buyer’s locale and currency are detected or selected When the price is rendered in checkout and on receipts Then the currency symbol/code, thousands separator, and decimal separator match the locale conventions (e.g., fr-FR: 1 234,56 €) Given ISO 4217 minor units for the currency When the amount is displayed Then the decimal precision equals the minor units (e.g., JPY=0, USD/EUR=2, KWD=3) and trailing zeros are shown when applicable Given the payment sheet (Apple Pay/Google Pay/card) When the sheet opens Then the currency and amount exactly match the checkout display (no rounding drift) Given tax-inclusive vs. tax-exclusive display settings per currency When totals are shown Then labels and amounts reflect the correct calculation in the selected currency across line items, subtotal, tax, and total

Merchant-Configurable Currency Pricing per SKU

Given a product/contract SKU with a supported currency configured in Admin When a merchant saves a per-currency price Then the price is stored and used verbatim for buyers transacting in that currency (no FX applied) Given a duplicate currency entry for the same SKU When saving Then validation prevents duplicates and returns a descriptive error Given both a per-currency price and dynamic FX are enabled When determining the buyer price Then the per-currency price takes precedence for that currency Given bulk upload via CSV/API for per-currency prices When processing the file/request Then invalid rows (unknown currency, negative/zero amount, bad precision) are rejected with row-level errors and valid rows are persisted Given a future-dated price per currency When the effective timestamp is reached Then new checkouts use the new price while existing sessions retain the prior price

Dynamic FX Conversion with Provider Rates and Margin

Given dynamic FX is enabled and no explicit per-currency price exists When a buyer selects or is assigned a currency Then the system converts from the base list price using the latest provider mid-market rate plus the configured merchant margin and rounds per currency rule Given the provider FX API is temporarily unavailable When fetching a rate Then the system falls back to the last known valid rate not older than the configured staleness threshold; otherwise the currency is disabled with an actionable message Given a configured margin (percentage or basis points) When calculating a converted price Then the effective rate equals provider_rate × (1 + margin) to at least 4-decimal precision and the final amount matches the rounded result Given a payment is captured using a converted price When storing the transaction Then the FX rate, margin, provider source, and timestamp are persisted for audit and export Given pricing cache TTL is configured When rates refresh during active sessions Then sessions created before refresh retain their computed amount; sessions created after use the new rates

Settlement Currency Selection & Automatic Conversion

Given a merchant account with a selected settlement currency When payments are captured in any supported charge currency Then payouts settle in the chosen settlement currency and provider conversion is applied as needed; conversion rate and fees are recorded per transaction Given the settlement currency is changed in Admin When the change is confirmed Then it applies only to new captures; historical transactions and payouts remain unchanged and an audit log entry is created Given a capture in the same currency as the settlement currency When funds are paid out Then no conversion is performed and no FX fees are recorded Given payout/export reports are generated When the merchant downloads them Then each line item includes charge currency, settlement currency, conversion rate, conversion fee, and net amounts

Rounding Rules Configuration & Enforcement

Given per-currency rounding settings are defined in Admin (mode and price endings) When a price is computed via FX Then the amount is rounded using the selected mode (e.g., round half up or banker’s) and adjusted to the configured price ending (e.g., .00, .95, .99) without violating minor unit precision Given zero-decimal and three-decimal currencies When amounts are calculated and displayed across checkout, receipts, and exports Then ISO minor unit precision is enforced consistently (e.g., JPY 0 decimals, KWD 3 decimals) Given rounding settings are modified When the changes are saved Then an audit record is written and only subsequent computations use the new rules; prior transactions remain unchanged

Currency Mismatch Resolution & Fallbacks

Given a product priced in EUR and settlement in USD When a buyer elects to pay in GBP Then checkout shows GBP amount, the charge is in GBP, settlement converts to USD, and all three currencies and applicable rates are recorded on the transaction Given the buyer’s selected currency is unsupported by the chosen payment method or region When initiating payment Then the system selects the configured fallback currency using the hierarchy (per-method override → regional default → global default) and displays a clear notice of the chosen currency prior to payment Given no fallback is configured and the currency is unsupported When proceeding to pay Then checkout blocks submission with an actionable error and offers supported currency options Given a refund is issued for a prior charge When processing the refund Then the refund is created in the original charge currency, and any settlement conversion is recorded with rate and fees for ledger consistency Given API/SDK integrations When a fallback occurs Then the response includes the final currency and a fallback_reason code

Product/Contract Currency Mapping via API & Admin

Given Admin settings for currency mapping When a merchant maps products/contracts to allowed currencies Then only those currencies are offered at checkout for the mapped items Given a public API for currency mapping When creating or updating mappings Then requests require valid product/contract IDs, ISO 4217 currency codes, and idempotency keys; invalid inputs return descriptive 4xx errors Given rounding rules are defined per currency When saving mappings Then the system associates the relevant rounding rule set with each currency for that item Given unsupported currencies for a payment method or region When retrieving available currencies via API Then the response excludes unsupported options and includes a fallback suggestion if configured Given audit and versioning requirements When mappings are changed Then changes are versioned with actor, timestamp, and diff; exports expose the current and prior mappings

VAT/GST Capture & Validation

"As a business owner, I want VAT/GST fields and validation to appear only when needed so that I remain compliant and issue correct invoices without manual work."

Description

Automatically surface tax fields (VAT ID, GST/ABN, company name) based on billing country, IP, and BIN signals. Validate VAT IDs via VIES (EU) and applicable national registries where available, apply reverse-charge logic when eligible, and compute/display tax breakdowns on the checkout and receipt. Store jurisdiction evidence and invoice-ready tax data on the payment and contract. Provide integrations or export for tax engines/accounting (e.g., Avalara/TaxJar, CSV), and ensure localization of tax labels by region.

Acceptance Criteria

Dynamic Tax Field Surfacing by Country, IP, and BIN

Given the checkout is rendered and the billing country is an EU member state, When the page loads or the billing country changes, Then the VAT Number and Company Name fields are visible within 300 ms. Given the billing country is the United Kingdom, When the page loads or the billing country changes, Then the VAT Number and Company Name fields are visible within 300 ms. Given the billing country is Australia, When the page loads or the billing country changes, Then the ABN and Company Name fields are visible within 300 ms. Given no billing country is selected, When IP geolocation or card BIN indicates an EU member state or Australia, Then the corresponding tax ID fields are pre-shown as optional until a billing country is selected. Given IP/BIN signals conflict with the selected billing country, When the billing country is changed, Then the shown tax fields follow the selected billing country and any previously shown non-matching tax ID field values are not submitted. Given the billing country is not in EU/UK/AU, When the page loads or the billing country changes, Then no VAT/GST/ABN fields are shown.

EU/UK VAT ID Validation via Registries

Given a VAT Number that matches the selected EU member state format, When the user blurs the VAT field or attempts to pay, Then the system validates the number via VIES and returns a result within 5 seconds. Given VIES returns a valid result for the entered VAT Number, When validation completes, Then a success indicator is shown, the normalized ID (with country prefix) is stored, and the legal name/address from the registry is captured when available. Given the VAT Number format is invalid or VIES returns invalid, When validation completes, Then an inline error is shown, reverse-charge is disabled, and checkout may proceed with VAT applied. Given the registry service is unavailable or times out after 3 seconds, When validation is attempted, Then a non-blocking warning is shown, the VAT Number is marked Unverified, and checkout proceeds with VAT applied. Given the VAT Number country prefix does not match the selected billing country, When validation is attempted, Then validation fails with an inline error and reverse-charge is disabled. Given a previously validated VAT Number is edited, When its value changes, Then the validation state is reset and revalidation is required before reverse charge can apply.

EU Reverse Charge Application Rules

Given the merchant’s tax nexus is Germany and the buyer’s billing country is France and the buyer’s VAT Number is validated, When the order is submitted, Then VAT rate applied is 0%, a "Reverse charge (EU VAT Art. 196)" note is shown on checkout and receipt, and the totals reflect zero VAT. Given the merchant’s tax nexus is Germany and the buyer’s billing country is Germany and the buyer’s VAT Number is validated, When the order is submitted, Then domestic VAT at the merchant’s German rate is applied and no reverse charge note is shown. Given the buyer’s VAT Number is unverified or invalid, When the order is submitted, Then VAT is charged at the buyer’s jurisdiction rate and reverse charge is not applied. Given a reverse charge decision is taken, When the record is stored, Then the decision, basis (validated buyer VAT), and both VAT numbers (merchant and buyer) are stored in the tax data.

Tax Breakdown Display on Checkout and Receipt

Given tax is chargeable, When the checkout displays totals, Then the following are shown in the transaction currency: Subtotal, Tax label localized to the jurisdiction (e.g., VAT/GST), Tax rate (%), Tax amount, and Total. Given reverse charge is applied, When the checkout displays totals, Then Tax amount is 0.00 and an explanatory note indicates the customer accounts for VAT. Given an order is completed, When the receipt is generated, Then the tax breakdown matches the checkout exactly (same currency, same amounts, same rate) and includes the buyer tax ID if captured/validated. Given a currency without minor units (e.g., JPY), When amounts are displayed, Then no decimal places are shown; otherwise amounts display two decimal places and sums reconcile (Subtotal + Tax = Total).

Jurisdiction Evidence and Invoice-Ready Tax Data Storage

Given a payment is completed, When the record is saved, Then at least two of the following are stored with timestamps and sources: billing country, IP country, card BIN country. Given a tax decision is made, When the record is saved, Then the system stores: tax jurisdiction, tax rate, tax amount, tax label, reverse-charge flag, buyer tax ID, validation status/result, validation source (e.g., VIES), and validation timestamp. Given a contract is associated with the payment, When records are saved, Then the invoice-ready tax data is attached to both the payment and the contract and is retrievable via API. Given client-side attempts to modify stored tax data, When an update is submitted, Then tax evidence and validation data remain read-only and unaltered.

Tax Data Export and Accounting/Tax Engine Integration

Given an admin selects a date range with <= 10,000 payments, When "Export CSV" is requested, Then a CSV is generated within 60 seconds containing for each payment: transaction ID, date/time, currency, subtotal, tax amount, tax rate, tax jurisdiction, tax label, reverse charge flag, buyer tax ID, validation status, evidence countries (billing/IP/BIN), and total. Given an Avalara or TaxJar integration is configured, When a payment is completed, Then a POST payload with normalized tax data is sent to the provider’s endpoint and a 2xx response is recorded; failures are logged and retried per the platform retry policy. Given exports or integrations run, When totals are summed per export, Then the sum of line subtotals, taxes, and totals reconcile to internal reports.

Regional Localization of Tax Labels and Field Names

Given the buyer’s billing country is Spain and locale is es-ES, When tax fields and breakdown are shown, Then labels use regional terms (e.g., "IVA" for VAT) and the VAT field placeholder/format is localized. Given the buyer’s billing country is France and locale is fr-FR, When tax fields and breakdown are shown, Then labels use "TVA" for VAT. Given the buyer’s billing country is Australia and locale is en-AU, When tax fields and breakdown are shown, Then labels use "GST" and the identifier field is labeled "ABN". Given a locale translation is missing, When the UI renders, Then English labels are used as fallback without breaking layout.

Processing Fee Pass‑Through Controls

"As a business owner, I want to choose whether to pass payment processing fees to my clients or absorb them so that I can manage margins while complying with local regulations."

Description

Add organization- and contract-level settings to pass processing fees to the payer or absorb them, with dynamic calculation by method, currency, and provider. Enforce regional compliance rules (e.g., surcharging restrictions and caps) and automatically disable pass-through where prohibited. Clearly disclose fees in the UI before confirmation, reflect them on receipts/invoices, and post fee components to the internal ledger for reporting and reconciliation.

Acceptance Criteria

Org Default and Contract Override for Fee Pass‑Through

- Given an organization default fee handling is Pass‑Through, When a new contract is created with no override, Then checkout applies pass‑through for all eligible payment methods. - Given an organization default is Absorb, When a contract override is set to Pass‑Through before sending, Then checkout uses pass‑through for that contract only. - Given a contract has been countersigned, When the organization later changes its default fee handling, Then the signed contract continues using its saved override/default and is not retroactively changed. - Given a user with Edit Contracts permission updates the contract’s fee handling, When the change is saved, Then an audit log entry records user, timestamp, contract_id, previous_value, and new_value.

Dynamic Fee Calculation by Method, Currency, and Provider

- Given provider fee schedules with percentage and fixed components per method and currency, When the payer selects Card in USD for an amount of 100.00, Then the fee equals schedule_percent*amount + schedule_fixed and is rounded to the currency minor unit. - Given ACH fees have a min and cap, When the computed fee falls below min or above cap, Then the fee is set to min or cap respectively. - Given the pricing currency differs from settlement currency and the provider applies an FX markup, When calculating the fee, Then the provider’s effective FX rate and markup are applied to the fee components. - Given multiple providers are configured, When routing selects Provider B for the transaction, Then the fee is calculated using Provider B’s schedule and rules.

Regional Compliance Enforcement and Auto‑Disable

- Given the rules registry indicates surcharging is prohibited for the buyer’s jurisdiction, payer_type, and method, When pass‑through is enabled at org/contract level, Then checkout auto‑disables pass‑through, absorbs the fee, and hides the fee line from the payer while showing a compliance notice to the seller. - Given a compliance rule caps surcharges at 1.5% for the buyer’s jurisdiction and method, When the computed fee exceeds 1.5% of the transaction amount, Then only 1.5% is passed to the payer and the remainder is absorbed, and the disclosure reflects the split. - Given a compliance rule prohibits surcharging debit cards in the buyer’s jurisdiction, When BIN lookup classifies the card as debit, Then pass‑through is disabled and the fee is absorbed automatically. - Given there is no matching compliance rule, When pass‑through is enabled, Then the surcharge is allowed as configured.

Pre‑Confirmation Fee Disclosure UI

- Given pass‑through is applicable, When the payer reaches the review step, Then the UI displays itemized subtotal, processing fee with method and percent/fixed breakdown, applicable VAT/GST on the fee, grand total, and currency before the Pay button is enabled. - Given pass‑through is disabled due to compliance, When the payer reaches review, Then the UI shows a message that fees are absorbed and no fee line item is displayed to the payer. - Given the payer switches payment methods, When the fee changes, Then the disclosure and totals update within 300 ms and the Pay button is disabled until totals are refreshed. - Given WCAG 2.1 AA requirements, When a screen reader is used on the review step, Then the fee, tax, and total elements have accessible names/roles and are announced in logical order.

Receipts and Invoices Reflect Fees Accurately

- Given a successful payment with pass‑through, When the receipt is generated, Then it includes a separate “Processing Fee” line with amount, method, VAT/GST code (if applicable), and totals that match the checkout disclosure. - Given an absorbed fee, When an invoice/receipt is generated for the payer, Then no processing fee line is shown to the payer while the internal copy records the absorbed fee for accounting. - Given a full or partial refund, When the receipt is reissued, Then the processing fee treatment follows provider policy (refundable or non‑refundable portions) and the updated lines reflect the returned amounts accurately. - Given a multi‑currency payment, When the receipt is generated, Then payer‑facing amounts are shown in payer currency and the internal copy includes settlement currency and exchange rate used.

Internal Ledger Posting and Reconciliation for Fees

- Given a payment completes, When ledger entries are posted, Then fee components are recorded with dimensions org_id, contract_id, provider_id, method, currency, region_code, pass_through_flag, and transaction_id. - Given pass‑through is charged, When posting, Then revenue excludes the processing fee; clearing accounts reflect gross charge, provider fee, and surcharge collected, with no fee expense recognized by the org. - Given fees are absorbed, When posting, Then an expense entry “Processing Fees” is recorded and linked to the payment; revenue equals the product/service amount only. - Given a reconciliation run imports a provider payout report, When matching transactions, Then net amounts and fees match within a tolerance of < 0.01 minor units per transaction; mismatches are flagged and queued for review.

Failure Handling and Fallback Behavior

- Given the fee calculation service times out, When pass‑through is required, Then the Pay button remains disabled and the user sees a retry option; if the org’s fallback policy permits, the system switches to absorb and logs an incident with correlation_id. - Given the compliance rules service is unavailable, When jurisdiction cannot be verified, Then the system defaults to absorb, displays “No fee applied due to compliance verification issues,” and records the event. - Given provider routing changes after review causing the fee to change by more than one minor unit, When the payer proceeds to pay, Then the payer is shown an updated disclosure and must reconfirm before processing continues. - Given rounding discrepancies are detected between UI and server calculations exceeding one minor unit, When the payer attempts to confirm, Then payment is blocked and an error is shown while the discrepancy is logged for investigation.

Localized, Accessible Checkout UX

"As an international client, I want the checkout to match my language and local conventions so that I can understand and complete payment confidently."

Description

Deliver a responsive, mobile-first checkout supporting language localization, right-to-left layouts where applicable, regional address schemas, and local number/date/currency formats. Dynamically prioritize local payment methods and wallets based on locale and device. Meet WCAG 2.1 AA accessibility standards and provide clear error states. Include Apple Pay/Google Pay merchant domain verification and readiness checks for a one-tap experience on supported devices.

Acceptance Criteria

RTL Mobile Checkout (Arabic)

Given the user’s browser locale is ar or ar-XX and the viewport width is ≤ 480px When the checkout loads Then the document sets dir="rtl" on the root, all visible strings render in Arabic, and UI elements are mirrored (including icons, chevrons, progress steps) And primary action buttons appear at the visual bottom-right in RTL And no horizontal scrolling occurs at 320px width And form labels, placeholders, and validation messages are localized And numerals render per locale configuration (Arabic-Indic if enabled)

Locale-based Payment Method Prioritization

Given the checkout is initialized with country/locale detected or selected and device capabilities known When the payment methods are rendered Then the order of methods matches the configured ranking for that locale (top method appears first) And unsupported methods for that locale/device are hidden And Apple Pay/Google Pay are shown only if readiness checks return true for the current browser/device And if no local methods are available, default to Card as a fallback And the selected default method is the top-ranked available method

Regional Address Schema for Japan

Given the user selects country JP (or locale ja-JP) When the billing address form is displayed Then fields are ordered as: Postal Code, Prefecture (select), City, Town/Chome, Block/Building, Recipient Name, Phone And Postal Code auto-formats as NNN-NNNN and validates against JP pattern And Prefecture options include all 47 prefectures And on valid postal code entry, Prefecture and City auto-populate when lookup data is available And submission is blocked until required fields are valid; invalid fields show inline errors

Locale-aware Number, Date, and Currency Formatting

Given an order total and currency are available and the user’s locale is detected or selected When monetary amounts and dates are displayed Then amounts are formatted using the user’s locale and the order currency with correct symbol position and separators And rounding conforms to ISO 4217 minor units (e.g., JPY 0 decimals, EUR 2 decimals) And example checks: 1000.5 EUR in fr-FR renders as "1 000,50 €"; 1000 JPY renders as "￥1,000" And user-entered amounts accept localized separators but are normalized accurately for processing

WCAG 2.1 AA Keyboard and Screen Reader Accessibility

Given a user navigates the checkout using keyboard only and/or a screen reader When traversing all interactive elements Then all controls are reachable with Tab/Shift+Tab in a logical order with no traps And a visible focus indicator of at least 2px thickness and 3:1 contrast is present And text contrast meets 4.5:1; non-text UI components meet 3:1 And form inputs have programmatic labels, groupings, and clear instructions And ARIA landmarks (banner, main, form, region) are present And dynamic messages (validation/errors) are announced via aria-live polite and associated via aria-describedby

Clear Inline Validation and Error States

Given the user submits the form with missing or invalid data When client-side or server-side validation fails Then form submission is prevented and focus moves to the first invalid field And each invalid field is marked aria-invalid="true" and displays a concise, localized error message inline And an error summary appears at the top linking to each invalid field And previously entered valid data is preserved And error messages render within 500 ms of validation failure

Apple Pay and Google Pay Readiness & Merchant Domain Verification

Given the user is on a device/browser that can support Apple Pay or Google Pay and the merchant configuration is present When readiness checks execute at checkout initialization Then Apple Pay is rendered only if window.ApplePaySession is available, canMakePayments returns true, and merchant domain verification succeeds And Google Pay is rendered only if isReadyToPay returns true for the configured gateway/merchant IDs And tapping the wallet button opens the native sheet within 500 ms with the correct total and currency And on success a payment token is returned; on failure buttons are hidden and Card form remains available And telemetry logs readiness result and domain verification status

Reconciliation, Refunds & Reporting

"As a finance manager, I want accurate reconciliation with refunds and payouts reporting so that I can close the books and resolve issues quickly."

Description

Implement a webhook-driven state machine to sync payment events (authorized, captured, partially captured, refunded, disputed, paid out). Support full/partial captures and refunds, voids before capture, and automatic linkage to the originating contract and invoice. Provide payout reconciliation against provider reports, a unified settlement view by currency/method, dispute evidence packaging, and exports (CSV/API) for finance. Expose operational tools for searching transactions, issuing refunds, and resolving mismatches.

Acceptance Criteria

Payment Event State Machine Sync

- Given a valid, signature-verified webhook for payment authorized with providerPaymentId P When it is received Then a payment record exists or is updated with state=authorized, providerPaymentId=P, authAmount, currency, method, and receivedAt timestamp within 2 seconds of processing start - Given a duplicate authorized webhook with the same eventId When processed Then no duplicate records are created, the state remains authorized, and an idempotency record exists - Given a partial capture webhook with amount A1 When processed Then state=partially_captured, capturedTotal increases by A1, remainingAuthorized decreases accordingly, and an audit log entry is created - Given a final capture webhook When processed Then state=captured and capturedTotal equals authorizedTotal - Given a void-before-capture webhook When processed Then state=voided and no subsequent capture is permitted (capture attempts return 409) - Given a refund webhook with amount R When processed Then refundedTotal increases by R and refund state is partial or full accordingly and netCaptured=capturedTotal-refundedTotal - Given a dispute.opened webhook When processed Then state includes disputed=true, fundsAvailability=held, and a dispute record with deadline is created - Given a payout webhook referencing transactions T When processed Then each T is marked settled with payoutId and settlementDate - Given events arrive out of order When processed Then final state reflects the highest-precedence transition by event timestamp with deterministic conflict resolution rules documented - Given any processing error When retried with exponential backoff for up to 24h Then events are eventually applied exactly once

Contract and Invoice Linkage

- Given a checkout session created for contractId C and invoiceId I When a payment is authorized Then the payment record stores contractId=C and invoiceId=I and appears under both entities - Given capture/refund events for the payment When processed Then the linked invoice amounts update: amountPaid=capturedTotal and amountRefunded=refundedTotal and invoiceStatus reflects Paid, Partially Paid, or Refunded correctly - Given a payment event missing metadata When processed Then the system backfills linkage by matching on invoice number or contract metadata; if ambiguous Then sets status=needs_review and raises an ops alert - Given a search by contractId or invoiceId in ops tools When executed Then matching transactions are returned with accurate totals

Operational Search, Refunds, and Voids

- Given a Finance Ops user with permission refunds:write When searching transactions by email, amount range, currency, method, date range, last4, status, providerPaymentId Then results return within 2 seconds for queries over up to 100k records and include pagination and sorting - Given a captured transaction with refundableAvailable RA When the user issues a partial refund amount R<=RA Then the provider refund is created and a local refund record exists with amount=R, reason, actorId, and state=pending until webhook confirmation - Given total requested refunds exceed capturedTotal When attempted Then the UI blocks the action and the API returns 422 with error code REFUND_LIMIT_EXCEEDED - Given an authorized-but-not-captured transaction When the user requests a void Then the provider void is called and local state=voided; any subsequent capture attempt returns 409 - Given a successful provider action (refund/void) When the webhook arrives within 5 minutes Then the local state transitions to refunded/voided and the UI shows success; if no webhook within 5 minutes Then a reconciliation job polls and updates state within 15 minutes - Given any action When completed Then an immutable audit log entry is recorded with user, timestamp, IP, action, and before/after values

Payout Reconciliation and Unified Settlement View

- Given a provider payout report for date D and currency CUR When imported via API/SFTP Then a payout record is created with totals: gross, fees, refunds, disputes, adjustments, net, and transaction count - Given imported payout P When reconciled Then each included transaction is matched by provider ids; unmatched transactions < 0.5% trigger a 'mismatch' status and alert; all matched transactions are marked settled with payoutId=P - Given fee pass-through mode When calculating net Then customer-paid fees are excluded from merchant fees; in absorb mode Then fees reduce merchant net; calculations match provider report within ±0.01 CUR - Given the settlement view filtered by currency or payment method When viewed Then totals and counts reflect filters and equal the sum of underlying transactions - Given the settlement view When exported to CSV/API Then all fields (payoutId, currency, method, gross, fees, net, refund totals, dispute totals, transaction list) are present and numeric fields use minor units with correct precision

Dispute Evidence Packaging and Tracking

- Given a dispute.opened event for transaction T When processed Then an evidence case is created within 30 minutes containing contract file, signed agreement, invoice, communication logs, service delivery proof, customer details, and timestamps - Given an ops user adds notes or attachments When saved Then they are included in the evidence package and versioned - Given provider format constraints max 20 MB per upload and accepted types PDF/JPG/PNG When packaging Then files are compressed/merged to meet limits and unsupported types are converted to PDF with fidelity checks - Given a submission deadline D When within 72 hours of D Then the system sends alerts to the assignee and channel; if past D Then case status=missed_deadline and an incident is logged - Given provider webhook updates dispute status When received Then case status updates to won/lost/needs_more_info and payment hold flags adjust accordingly; audit trail maintained

Finance Exports (CSV and API)

- Given an authenticated Finance role user When requesting /v1/reports/transactions with filters (date range up to 31 days, status, currency, method, contractId, invoiceId, providerPaymentId) and pageSize<=5000 Then the API responds in <=2 seconds with correct pagination and totals - Given a large export request up to 1,000,000 rows When initiated Then an async job generates a CSV within 10 minutes and provides a signed download URL that expires in 24 hours - Given transaction rows in export When verified Then fields include transactionId, providerPaymentId, contractId, invoiceId, createdAt, state, authorized, captured, refunded, fees, net, currency, method, payoutId, disputeStatus, customerCountry; monetary fields use integer minor units and ISO currency - Given fee mode pass_through vs absorb When computing net in exports Then values reflect the configured mode and per-transaction fee lines reconcile to settlement totals - Given an unauthorized user When requesting exports Then the API returns 403 and no data is leaked; all export accesses are logged

CounterSign Lock

Protect your kickoff by gating your countersignature until funds clear. SnapAgree confirms authorization in real time, then releases the countersign and final PDF—ensuring you never start work without money in the door.

Requirements

Real-Time Funding Verification

"As a small-business owner, I want SnapAgree to confirm that my client’s payment is authorized before I countersign so that I never begin work without funds secured."

Description

Integrate with supported payment processors (e.g., card, ACH) to verify authorization or capture of required funds in real time before countersignature. The system must initiate an authorization/charge, listen for webhook callbacks, and update the contract state instantly upon success or failure. It must support configurable payment methods per workspace, handle pending/processing states (e.g., ACH settlement windows), and present clear UI states such as Awaiting Funds, Authorized, Captured, or Failed. All sensitive payment data must be tokenized and never stored on SnapAgree servers, relying on PCI-compliant vendors. Include retry logic, idempotency keys, and timeouts to prevent duplicate charges and race conditions. Provide sandbox/test modes and descriptive error handling to guide users to resolution.

Acceptance Criteria

Card Authorization/Capture Success Releases Countersign

Given a contract with a required amount and currency and the workspace has Cards enabled and a gate rule of Authorize or Capture When the counterparty initiates countersignature and selects Card Then the system creates a payment intent for the exact required amount/currency with an idempotency key unique to contract+attempt And the UI switches to Awaiting Funds within 1s of initiation When the processor returns a success webhook matching the payment intent within 10s Then SnapAgree updates the contract funding state within 2s to Authorized or Captured to match the processor event And releases the countersign and generates the final PDF only if the achieved processor status meets the configured gate rule and the amount equals the required amount And emits exactly one countersign event and one audit log entry with the processor charge/intent ID

ACH Pending Settlement Gating

Given a workspace with ACH enabled and a gate rule requiring settlement When the payer authorizes an ACH debit for the required amount Then the UI displays Awaiting Funds (ACH pending) within 2s and the countersign action remains disabled And the backend records a pending Processing state and listens for settlement/return webhooks for up to 5 business days When a settlement success webhook is received for the exact amount and contract Then the contract funding state updates to Captured within 2s and the countersign is released and final PDF generated When an ACH return/failure webhook (e.g., R01, R07) is received before settlement Then the contract funding state updates to Failed within 2s, countersign remains blocked, and both parties are notified with the return reason code

Funding Outcomes UI and Error Feedback

Given a user viewing a contract with funding in progress When a funding attempt is initiated Then the UI shows an Awaiting Funds banner, disables countersign controls, and displays a spinner that times out after 30s if no response When a success webhook is processed Then the visible status updates within 2s to Authorized or Captured, and the countersign button changes to Released state When a failure occurs (decline, insufficient funds, authentication failed, ACH return) Then the UI shows Failed status within 2s, displays a human-readable message including processor decline code/text, and offers Retry Payment and Change Payment Method actions if allowed And no sensitive payment data (PAN, CVV, full account/routing) is shown in the UI or error messages And all statuses shown are limited to: Awaiting Funds, Authorized, Captured, Failed

Resilient Processing: Idempotency, Retries, Timeouts, and Webhook Consistency

Given a payment initiation request for a contract funding attempt Then an idempotency key derived from contractId+attemptIndex+amount+currency+method is used for all processor API calls When duplicate initiation requests are received with the same idempotency key Then only one processor authorization/capture is created and all responses are consistent (same processor intent/charge ID) When transient errors (HTTP 5xx, network timeouts) occur during initiation Then the system retries up to 3 times with exponential backoff (2s, 4s, 8s) without creating duplicate charges And all attempts and outcomes are recorded in the audit log When no synchronous confirmation is received within 30s of initiation Then the UI remains in Awaiting Funds and the backend continues listening for webhooks without re-initiating the charge When webhooks arrive out of order or are duplicated Then events are deduplicated by processor event ID within a 24h window and the contract resolves to a single correct terminal state, emitting at most one countersign release

Workspace Payment Method Configuration Enforcement

Given a workspace that configures allowed payment methods (Card enabled/disabled, ACH enabled/disabled) and a default method When a contract is presented for countersign Then only the allowed methods are presented to the user, with the workspace default preselected When a user attempts to initiate funding with a disallowed method via client or API Then the server rejects the request with HTTP 403 and a message indicating the method is not permitted When the workspace updates allowed methods Then the change applies to new funding attempts and does not alter in-flight attempts And the gate rule (Authorize vs Capture) configured at workspace or contract level is enforced before releasing countersign

Sensitive Payment Data Tokenization and Storage Constraints

Given payment details are collected for Card or ACH Then collection occurs via PCI-compliant provider elements/hosted fields and SnapAgree servers never receive or store raw PAN, CVV, full account or routing numbers And only tokens and non-sensitive metadata (brand, last4, expiry, bank name) are stored; logs and analytics contain no sensitive fields And all processor communications use TLS 1.2+; stored tokens/keys are encrypted at rest And a security test verifies no sensitive fields exist in databases, logs, crash reports, or monitoring sinks for 10 representative funding attempts

Sandbox/Test Mode Parity and Safety

Given a workspace in Test Mode using sandbox processor keys When funding is initiated with test payment methods Then no real funds are moved, the full gating flow executes end-to-end, and the UI shows a persistent Test Mode indicator on contract and payment screens When sandbox webhooks are received Then they are accepted and processed; production webhooks are ignored in Test Mode, and vice versa And test payment numbers/tokens produce deterministic outcomes for Authorized, Captured, Failed, and Pending states And final artifacts and audit logs are clearly labeled as Test Mode for traceability

Countersign Release Gate

"As a freelancer, I want my countersignature to be automatically withheld and then applied only after payment clears so that my final contract is valid and enforceable with money secured."

Description

Enforce business rules that prevent the platform from applying the company countersignature and releasing the final, clean PDF until the funding condition is met. Prior to clearance, show only a provisional copy watermarked Pending Payment and restrict download/sharing of the final document. On funding success, automatically apply the countersignature, remove the watermark, generate the final PDF, and distribute it to both parties with a verifiable certificate of completion. Support configurable gate conditions (e.g., authorization-only vs. full capture, minimum deposit thresholds) and timeouts after which the contract is auto-cancelled or reverted to draft. Ensure atomicity so countersign, PDF finalization, and notifications occur as a single, traceable transaction.

Acceptance Criteria

Provisional Copy Prior to Funding

Given a contract is in Pending Funding status with CounterSign Lock enabled When any user attempts to view, download, or share the final clean PDF before funding conditions are met Then only a provisional preview is shown with a visible "Pending Payment" watermark on every page And download of the final clean PDF is disabled in UI and API requests for the final PDF return HTTP 403 And external share links for the final PDF are not generated or are unusable (HTTP 403) And the attempt is recorded in the audit log with user, timestamp, and action

Automatic Countersign on Funding Success

Given the contract’s funding gate is configured (authorization-only or full capture) with any deposit thresholds When the payment provider confirms funds meeting the configured condition or internal verification marks the condition as satisfied Then within 60 seconds the system applies the company countersignature to the document And regenerates the document without watermark as a single final PDF with an immutable file hash And attaches a verifiable certificate of completion And updates contract status to Executed And emails both parties the final PDF and certificate And records a single traceable release transaction ID linking countersign, PDF, certificate, and notifications in the audit trail

Configurable Funding Gate Conditions

Given an admin has set the gate mode to Authorization-only or Full Capture and defined a minimum deposit threshold by amount or percentage When one or more payment events are received Then the system sums only eligible amounts per the selected mode (e.g., authorized but not captured for Authorization-only; captured amounts for Full Capture) And excludes voided, reversed, or refunded amounts from the total And treats multiple partial payments cumulatively toward the threshold And triggers release only when the computed eligible total meets or exceeds the configured threshold; otherwise the contract remains Pending Funding

Funding Timeout Handling

Given a funding timeout policy is configured with a duration and an action (Auto-Cancel or Revert to Draft) When the timeout elapses without the funding condition being met Then the system transitions the contract to the configured terminal state atomically And revokes provisional access and disables any pending payment prompts on the contract And notifies both parties with the timeout outcome and next steps And records the timeout event, policy details, and timestamp in the audit trail And ignores or logs (without releasing) any late payment events received after the timeout transition

Atomic Release Transaction and Idempotency

Given a qualifying funding event or a manual recheck triggers release processing When the system executes the release Then countersignature application, final PDF generation, certificate issuance, status update, and notifications succeed together or are fully rolled back on failure And a single transaction ID and idempotency key are used to correlate and deduplicate operations And concurrent or duplicate trigger events do not create multiple final PDFs, multiple certificates, or duplicate notifications And the final PDF hash remains stable across retries And the audit trail captures the transaction ID, idempotency key, and outcome

Payment Provider Edge Cases and Verification

Given payment webhooks may arrive out of order, be retried, or represent partial authorizations When processing events for the same payment intent/charge Then the system processes only the latest non-ambiguous terminal state per provider semantics And ignores older sequence numbers or lower version events And does not release on statuses such as Authorization Reversed, Chargeback, Dispute, or Refund And marks the contract Pending Verification on ambiguous or transient errors and schedules retries with backoff And never transitions to Executed unless a qualifying, verifiable event satisfies the configured gate

Final Document Distribution and Access Controls

Given a contract has been released and executed When the system delivers artifacts to participants Then both parties receive an email within 60 seconds containing links to the final PDF and the certificate of completion And the links require recipient authentication or a signed access token; unauthorized requests return HTTP 403 And the certificate includes contract ID, parties, execution timestamps, signer identities, and the SHA-256 hash of the final PDF And all deliveries and downloads are recorded in the audit log with recipient, timestamp, and artifact identifiers

Deposit and Milestone Payments

"As a service provider, I want to require a deposit at countersign and additional milestone payments later so that I reduce non-payment risk while aligning cash flow with project stages."

Description

Allow contracts to specify a deposit amount or percentage and optional milestone payment schedule that gate countersignature or later deliverables. Present a clear payment breakdown to the client, generate payment links for each required installment, and update contract gating logic as each milestone is paid. Support common configurations such as 30% deposit at countersign and remaining balance before delivery, with currency and tax handling. Handle ACH settlement delays by keeping milestones in a pending state until funds settle. Provide validation to prevent countersign release if the required deposit is not met and surface progress indicators for both parties.

Acceptance Criteria

30% Deposit Gating Countersignature

Given a contract total of T in currency C and a required 30% deposit at countersign When the client opens checkout for the deposit Then the breakdown displays subtotal, tax, and deposit amount = round(T*0.30 plus applicable tax) in C And the payment method options are shown per tenant settings When the client completes payment and the processor returns authorization only (not settled) Then the deposit milestone status is Pending Settlement and countersign status remains Locked When the processor confirms settlement for the deposit Then the deposit milestone status changes to Paid and countersign status transitions to Unlocked And the system applies the countersignature, generates the final PDF, and timestamps the release within 60 seconds When the processor reports a failure or reversal before settlement Then countersign remains Locked and both parties are notified with the failure reason

Milestone Schedule Creation and Unique Payment Links

Given the seller configures a milestone schedule with N milestones using amounts or percentages When the schedule is saved Then the system validates that all milestone amounts are non-negative and sum to 100% ± $0.01 (or the contract total in currency precision) And at least one milestone is marked as gating countersign or delivery And each milestone has a due trigger (date or event) defined Then the system generates a unique, secure payment link per required milestone containing contract_id, milestone_id, amount, currency, and tax metadata And each link opens a checkout scoped to that milestone and shows only that installment’s breakdown And links can be regenerated and prior links are invalidated immediately

Currency and Tax Handling per Installment

Given the contract currency is set (e.g., EUR) and a tax configuration applies (e.g., 20%) When the client views any installment’s checkout or the contract payment breakdown Then all amounts display in the contract currency with ISO code/symbol and two-decimal precision And tax is calculated per-installment according to configuration (tax on deposit and milestones as specified) And the sum of all installment totals (including tax) equals the contract grand total (including tax) within currency rounding rules And line items clearly separate subtotal and tax for each installment

ACH Settlement Delay Handling for Any Milestone

Given a milestone is paid via ACH When the payment processor returns authorization Then the milestone status is Pending Settlement and any related gate (countersign or delivery) remains Locked When the payment settles successfully Then the milestone status updates to Paid and the corresponding gate is lifted automatically When the ACH payment is returned/fails during settlement Then the milestone status updates to Failed, the gate remains or reverts to Locked, and both parties receive a notification with the return code

Gate Final Deliverables Until Remaining Balance Paid

Given a milestone is configured as Remaining balance before delivery When there exists any unpaid or pending-settlement milestone Then final deliverable actions (e.g., file download, export, delivery confirmation) are disabled for the client and flagged for the seller When the remaining balance milestone is Paid (settled) Then final deliverable actions become enabled immediately and the enablement is recorded with timestamp and actor in the audit log

Bidirectional Payment Progress Indicators

Given a contract with one or more milestones When the seller or client views the contract page Then they see a progress indicator showing Paid, Pending Settlement, Not Due, Failed, and Overdue counts per milestone And an overall progress percent = (sum of Paid amounts / contract total) rounded to the nearest whole percent And each milestone row displays amount, due trigger, current status badge, and last update time When a processor event updates a payment Then the indicators refresh within 60 seconds and the audit log records the change

Validation Blocks Countersign When Deposit Not Met

Given a contract requires a deposit amount D for countersign When one or more payments are received and the settled sum for the deposit milestone is < D Then the countersign action is blocked and the UI displays the outstanding deposit amount When the settled sum for the deposit milestone reaches or exceeds D Then the countersign action becomes available and proceeds to apply the countersign and generate the final PDF

Risk Scoring and Fraud Checks

"As an owner-operator, I want SnapAgree to detect risky payments and tighten the countersign lock automatically so that I avoid chargebacks and unpaid work."

Description

Evaluate payment and identity risk signals (e.g., AVS/CVV results, velocity, dispute history, processor risk flags) to produce a contract-level risk score that can tighten gating rules when risk is elevated. When high risk is detected, require full capture instead of authorization-only, add enhanced verification steps, or route for manual review. Surface clear risk badges and explanations in the contract UI and include risk context in notifications. Ensure that risk assessments are logged with inputs and decisions for auditability and future tuning. Provide admin controls to adjust thresholds per workspace and track outcomes to improve precision over time.

Acceptance Criteria

Risk Score Computation with Signal Ingestion and Reason Codes

Given a contract payment attempt with available AVS, CVV, 3DS result, velocity metrics, dispute history, and processor risk flags When the risk assessment runs Then a numeric score between 0 and 100 and a risk level (Low, Medium, High) are produced with at least three ordered reason codes and a unique assessment ID within 800ms at p95 Given some signals are unavailable from the processor When the risk assessment runs Then the score is computed using available signals, missing signals are recorded as reason codes, and no error prevents a decision Given the assessment completes When results are persisted Then the raw inputs (redacted), score, reasons, and decision are stored atomically and retrievable by assessment ID

Dynamic Gating of Countersign by Risk Threshold

Given default thresholds Low < 30, Medium 30–69, High ≥ 70 and workspace-specific overrides if configured When a risk score is produced for a contract payment Then the system selects the applicable action according to the active thresholds and records the decision with the threshold version Given Low risk When authorization succeeds Then countersign and final PDF are released within 2 seconds and capture may occur asynchronously per normal flow Given Medium risk When step-up verification succeeds and authorization succeeds Then countersign and final PDF are released; otherwise countersign is held and the contract is queued for manual review Given High risk When full capture succeeds and step-up verification succeeds Then countersign and final PDF are released; otherwise countersign is held and the contract is queued for manual review

Step-Up Verification Flow for Elevated Risk

Given a contract assessed as Medium or High risk When step-up verification is initiated Then the signer receives a one-time code via their verified email or phone, the code expires in 10 minutes, and a maximum of 3 attempts are allowed Given the signer enters the correct code within the attempt and time limits When verification is checked Then step-up verification is marked Pass and the gating flow proceeds accordingly Given the signer fails step-up verification (expired or max attempts) When verification is checked Then step-up verification is marked Fail, countersign remains locked, and the contract is routed to manual review

Risk Badges and Explanations in Contract UI (Internal)

Given a contract has an active risk assessment When a workspace member with permission views the contract in the app Then a visible badge shows the risk level (Low/Medium/High), numeric score, and is color-coded, and an expandable panel lists the top 3 reason codes and the gating action taken Given an external client views the contract When the contract page renders Then risk badges and explanations are not shown to the client Given the risk decision is updated (e.g., after step-up or capture) When the contract page is refreshed or receives a push update Then the badge, score, reasons, and action reflect the latest state within 2 seconds

Risk Context Included in Notifications

Given a risk decision is made or changes for a contract When in-app, email, or Slack notifications are sent Then notifications include assessment ID, risk level, score, top 3 reasons, action taken (e.g., Full Capture Required, Manual Review), and a deep link to the contract, and exclude sensitive PAN/PII Given a contract is routed to manual review due to risk When notifications are sent Then the designated reviewers group receives an alert within 10 seconds with the risk context and required next steps

Immutable Audit Logging of Risk Assessments

Given a risk assessment is executed When persisting the audit record Then the log entry captures timestamp, assessment ID, redacted signal inputs, score, thresholds in effect, decision, processor response codes (AVS/CVV/3DS), step-up outcome, user overrides (if any), and final countersign outcome Given an auditor queries by assessment ID or contract ID When retrieving audit records Then the complete immutable history is returned, with sensitive values redacted (e.g., PAN last4 only), and entries are retained for at least 24 months and exportable as CSV

Workspace Admin Threshold Controls and Outcome Tracking

Given a workspace admin opens Risk Settings When editing thresholds and actions for Low/Medium/High Then changes can be previewed against the last 30 days of assessments to show projected impact and saved with a versioned change log and effective timestamp Given thresholds are updated When new assessments run Then the new thresholds are applied and the assessment records store the threshold version used Given an admin views Risk Outcomes When filtering by date range and threshold version Then approval rate, step-up rate, manual review rate, capture failure rate, and chargeback rate are displayed and downloadable as CSV

Notifications and Reminders

"As a contractor, I want automated, clear reminders and status updates sent to my client so that payments are completed promptly without me chasing them."

Description

Send real-time notifications to both parties for key events: payment requested, payment authorized/captured, countersign released, payment failed, and approaching timeouts. Provide configurable reminder cadences (e.g., 24h, 3 days) with actionable payment links and status summaries. Support email and in-app notifications initially with templates branded per workspace. Ensure notifications are idempotent, reflect the latest contract state, and suppress noise when events are superseded (e.g., success after failure). Log delivery and open events to aid support and troubleshooting.

Acceptance Criteria

Payment Requested Notification

Given a contract is in Awaiting Payment and a payment request is created When the request is issued Then the payer receives an email and an in-app notification within 15 seconds containing: contract name, amount, due date/timeout, and a secure Pay Now link And the counterparty receives an FYI email and in-app notification within 15 seconds containing: contract name, amount, and current status And notifications use the workspace’s logo, colors, display name, and reply-to And exactly one notification per channel is sent per payment request ID (idempotent) And notification delivery attempts and outcomes are logged

Payment Authorized/Captured Notification

Given a payment for a contract is authorized or captured When the payment provider posts the success event Then both parties receive email and in-app notifications within 15 seconds And the content includes: contract name, amount captured, masked payment method (brand + last4), timestamp, and a link to view contract status And any pending payment-failure reminders for this contract are canceled And exactly one notification per channel is sent per success event ID (idempotent) And the notification thread reflects the latest contract state

Payment Failure Notification with Success Supersession

Given a payment attempt fails for a contract When the failure event is received Then both parties receive email and in-app notifications within 15 seconds describing the failure reason (if provided) and next steps, including a Retry Payment link for the payer And a reminder schedule is queued per the workspace cadence And if a subsequent success event is received before a reminder is sent, pending failure reminders are suppressed and the success notification is sent instead And exactly one failure notification per channel is sent per failure event ID (idempotent) And all deliveries, suppressions, and reasons are logged

Countersign Released Notification

Given a contract uses CounterSign Lock and funds have cleared When the system releases the countersignature and final PDF Then both parties receive email and in-app notifications within 15 seconds confirming countersign release And the email includes the final signed PDF as an attachment or secure link And notifications are sent only after the countersign is created (never before) And exactly one notification per channel is sent per countersign release event (idempotent) And any prior awaiting-payment reminders are canceled

Configurable Reminder Cadence

Given a workspace has configured reminder cadences (e.g., 24h, 3 days) for pending payments When a payment request remains unpaid across those intervals Then reminders are sent to the payer via email and in-app at each configured interval And each reminder includes the current status summary and a secure Pay Now link And reminders stop automatically when the payment is authorized/captured or the request expires And a given interval triggers at most one reminder per channel per payment request (idempotent) And all scheduled reminders and cancellations are logged

Workspace-Branded Templates and Channel Support

Given a workspace with branding assets (logo, color, display name, reply-to) When any notification defined in this requirement is sent Then the email uses the workspace branding and reply-to And the in-app notification displays the workspace identity consistently And notification templates are configurable per workspace without affecting others And both channels (email and in-app) are available and can be toggled per workspace

Delivery and Open Event Logging

Given notifications are sent via email and in-app When provider callbacks or client opens occur Then delivery status (queued, sent, delivered, failed) and open events are recorded with timestamps, channel, recipient, message ID, and contract ID And logs are viewable in the support console, filterable by contract ID, recipient, event type, and time range And the system updates delivery/open status within 10 seconds of receiving provider callbacks

Audit Trail and Legal Evidencing

"As a business owner, I want a complete, immutable record of payment and countersign events so that I can prove agreement validity in case of disputes."

Description

Record a tamper-evident audit trail covering payment authorization IDs, amounts, method, timestamps, webhook receipts, signer identities, IP addresses, countersign events, and PDF hash values. Present a human-readable certificate of completion appended to the final PDF and a machine-readable event log exportable for disputes or compliance reviews. Ensure events are ordered, time-synced, and immutable, with data retention policies aligned to e-sign and payment recordkeeping requirements. Provide one-click export of the full evidence package for a contract.

Acceptance Criteria

Comprehensive Evidence Capture on Countersign Release

Given a contract using CounterSign Lock with payment authorization initiated and the signer completes e‑signature And the payment provider returns an authorization response and SnapAgree receives provider webhooks When the countersignature is released Then the audit trail records a single event bundle containing: payment.authorizationId, amount, currency, method, provider, status; payment.authorizationTimestamp; providerWebhook.receiptId and receivedTimestamp; signer.fullName, signer.email, signer.authMethod, signer.ipAddress; countersign.eventId, countersign.timestamp, countersigner.identity; document.pdfSha256, document.version, document.fileSize; contractId And all recorded fields are non‑null and validate against schema version snapagree.audit.v1 And the event bundle is retrievable via API and UI within 5 seconds of countersign release

Tamper‑Evidence and Integrity Verification

Given an audit trail exists for a contract When an integrity verification job runs Then the log’s hash chain recomputed from genesis equals the stored headHash and the signature validates against the published public key When any stored event payload is altered or reordered Then verification fails with code INTEGRITY_FAILURE and identifies the first mismatched sequenceNumber And the system blocks serving the altered log and emits a security alert entry And no API exists to update or delete persisted audit events (write‑once semantics enforced)

Ordered, Time‑Synced Event Timeline

Given events originate from app, e‑sign, and payment systems When events are persisted Then each event has an ISO‑8601 UTC timestamp with millisecond precision and a strictly increasing sequenceNumber starting at 1 And events are stored and served in ascending sequenceNumber with no gaps or duplicates; any gap or duplicate causes write to fail with code SEQUENCE_VIOLATION And system time is NTP‑synced with maximum offset ≤ 2 seconds; if exceeded, event writes are paused and a SYNC_ALERT is logged And for third‑party webhooks the providerTimestamp and receivedTimestamp are both recorded and the skew is computed; skew > 5 seconds is flagged in the event metadata

Human‑Readable Certificate Appended to Final PDF

Given the final PDF is generated on countersign release When the document is assembled Then a certificate of completion is appended as the last pages of the PDF And the certificate displays: contractId; parties; signer names and emails; signer IP addresses; signing timestamps; countersigner identity and timestamp; payment authorization ID, amount, currency, method, status, authorization timestamp; total event count; pdfSha256; verification URL/QR And the certificate values exactly match the machine‑readable audit log fields And opening the PDF shows the certificate pages without password prompts And the combined PDF’s embedded hash (pdfSha256) matches the value stored in the audit trail

Machine‑Readable Event Log Export

Given a contract with an audit trail When a user exports the machine‑readable log Then a JSON or JSONL file downloads that validates against schema snapagree.audit.v1 And it contains all events in order with sequenceNumber, eventType, timestamp, actor, ipAddress, payment details (authorizationId, amount, currency, method, status), webhook receipts (id, provider, signature/checksum, receivedTimestamp), countersign details, and document.pdfSha256 And the export includes headHash, chainAlgorithm, signature, and the signer public key/certificate And the export action is recorded in the audit with requester identity and IP

Data Retention and Legal Hold Compliance

Given the organization’s retention policy is configured When a contract reaches its retention expiry and no legal hold exists Then audit trail data and related artifacts are purged irreversibly and a deletion tombstone is recorded containing contractId, deletionTimestamp, and a proof hash linking to the last headHash And within the retention period all audit events are immutable and cannot be edited or deleted And when a legal hold is placed before expiry, data is retained until the hold is removed, and hold placement/removal is logged And retention settings cannot be configured below the organization’s compliance minimum; attempts are rejected with code POLICY_VIOLATION

One‑Click Full Evidence Package Export

Given a user with permission views a finalized contract When they click “Export Evidence” Then within 30 seconds a ZIP package is generated containing: final PDF (with certificate), machine‑readable audit log (JSON/JSONL), provider webhook receipts and signatures, the public verification key/certificate, and a README with verification steps and schema version And a SHA‑256 checksum of the ZIP is displayed and stored And a time‑limited (15‑minute) signed download link is generated and scoped to the contract; unauthorized users receive HTTP 403 And the export action is logged in the audit with requester identity, IP address, timestamp, and package checksum

Admin Override with Safeguards

"As an account admin, I want a controlled way to override the payment gate in emergencies so that deals can proceed when needed without losing traceability or protections."

Description

Enable authorized admins to bypass the countersign lock in exceptional cases with mandatory reason codes, optional second approver, and configurable warnings. Require 2FA at the moment of override, record the override in the audit trail, and visibly flag the contract and final PDF as Override Applied. Allow workspace-level policies to disable overrides or limit them by amount thresholds. Provide reporting on overrides to monitor risk and policy adherence.

Acceptance Criteria

Admin 2FA Step-Up at Override

Given a contract is gated by CounterSign Lock and the user has the Admin role with Override permission When the admin initiates an override Then the system enforces a fresh step-up 2FA challenge (TOTP/SMS/WebAuthn) regardless of prior session 2FA And the override flow is blocked until 2FA succeeds within 120 seconds And after 3 failed attempts or timeout the override is cancelled with no state change and an audit entry recorded as Denied

Mandatory Reason Codes and Justifications

Given the override flow has started and 2FA succeeded When the admin proceeds to provide rationale Then the admin must select a reason code from a configurable list or choose Other And if Other is selected a free-text justification of 20–500 characters is required And the Continue action remains disabled until a valid reason code (and justification if required) is provided And upon submission the reason code and justification are stored read-only with the override record and shown in audit and reporting

Policy-Controlled Override Enforcement (Disable, Threshold, Second Approver)

Given workspace policy Disable Overrides is enabled When any user attempts to initiate an override via UI or API Then the attempt is blocked, UI controls are disabled, API returns 403 with policy_code=OVERRIDE_DISABLED, and an audit entry is recorded as Blocked by Policy Given workspace policy Override Amount Threshold T is set When an override is attempted on a contract with total_amount > T Then the action is blocked with a message referencing the threshold, API returns 403 with policy_code=THRESHOLD_EXCEEDED, and an audit entry is recorded as Blocked by Threshold Given workspace policy Second Approver Required is enabled and an override request is submitted When the second approver reviews the request Then the requester cannot approve their own request, only users with Approve Override permission may approve, and approval links expire in 24 hours And if approved within SLA the override proceeds; if rejected or expired the override is cancelled and the contract remains locked

Configurable Risk Warnings and Explicit Acknowledgment

Given the admin has satisfied prerequisite steps for override When the confirmation screen is shown Then workspace-configured warnings are displayed including unpaid status and financial exposure amount And the Confirm Override action is disabled until the admin checks I acknowledge the risks and types the full contract ID to confirm And the exact warning copy and acknowledgment timestamp are stored with the override record

Immutable Audit Trail for Overrides

Given any override attempt (successful or blocked/denied) When the event occurs Then an audit record is appended with: contract_id, workspace_id, requester_id, timestamp (UTC ISO-8601), client_ip, user_agent, device_fingerprint (if available), reason_code, justification_hash, 2FA_method and outcome, second_approver_id and decision (if applicable), policy_snapshot, previous_lock_state, resulting_state, and correlation_id And audit records are immutable (no update/delete), queryable by date range/user/contract, and exportable to CSV/JSON And denied/blocked attempts are marked with outcome=Denied and include failure_reason

Visual Override Flag on UI and Final PDF

Given an override completes successfully When the contract view is loaded Then an Override Applied banner is displayed with reason code, requester, approver (if any), and timestamp And the final PDF includes a visible Override Applied watermark on every page and an appendix noting override details And the signature page notes that countersign was issued via admin override And search and filters allow Override Applied = true to return this contract And the countersign and final PDF are released immediately even if payment funds are not yet cleared

Override Reporting and Monitoring

Given reporting permissions are granted When the Overrides report is viewed Then it shows counts, percentages of total deals, total overridden amounts, breakdowns by user, client, reason code, and time period with filters for date range, workspace, team, and user And the report supports CSV export and a scheduled weekly email summary including blocked incidents And an API endpoint GET /reports/overrides provides paginated, filterable results whose totals match the UI within 1% for the same parameters And each report row links to the underlying contract and audit record

Decline Rescue

Recover failed payments automatically with smart retries, card updater, and branded reminders that invite clients to choose an alternate method. Optional partial‑authorization secures a smaller hold to keep the booking while the client updates details—reducing awkward follow‑ups and lost deals.

Requirements

Smart Retry Orchestration Engine

"As a small-business owner, I want failed payments to retry automatically with smart timing so that I recover revenue without manual chasing or harming customer relationships."

Description

Automatically detects failed payments via processor webhooks and classifies decline reasons to schedule adaptive, compliant retry attempts. Implements reason-based backoff, maximum retry caps, SCA-aware pauses, and idempotent processing to avoid duplicate charges. Provides per-workspace policies (retry windows, cadence, limits) with safe defaults and a kill switch. Integrates with SnapAgree contracts/invoices to update payment status, drive reminder timing, and emit events for downstream systems. Logs outcomes for analytics and ensures retries respect card-network and processor rules, customer time zones, and business hours.

Acceptance Criteria

Webhook Decline Detection and Classification

Given a payment attempt fails and the processor sends a signed webhook with a decline code When the webhook is received Then the engine validates the signature and persists the event within 2 seconds And classifies the decline into one of the supported categories: soft_insufficient_funds, soft_do_not_honor, soft_processor_error, soft_network_error, sca_required, hard_lost_or_stolen, hard_fraud_suspected, hard_invalid_number, hard_expired_card, hard_invalid_cvv, unknown_soft Given a duplicate webhook for the same processor event id or payment_intent_id+attempt_number When processed Then no additional schedule is created and a single classification record exists Given a webhook with invalid signature When processed Then it is rejected, no retries are scheduled, and a security error is logged Given a webhook missing a mappable code When processed Then the decline is classified as unknown_soft and a safe-default retry schedule is created per policy

Reason-Based Retry Scheduling and Backoff Limits

Given a decline classified as soft_insufficient_funds or soft_do_not_honor When scheduling retries Then the engine uses the workspace policy cadence and max_retries (defaults: cadence [6h, 24h, 48h, 5d], max_retries 4, window_days 14) And schedules the next attempt within customer local business hours (09:00–18:00, Mon–Fri) unless policy overrides And never exceeds the workspace max_retries nor the retry window Given a decline classified as soft_processor_error or soft_network_error When scheduling retries Then the minimum backoff between attempts is at least 1 hour and increases per policy backoff multiplier And no more than one retry is scheduled within any 6-hour period Given a decline classified as any hard_* category (lost_or_stolen, fraud_suspected, invalid_number, expired_card, invalid_cvv) When scheduling retries Then no retries are scheduled and the attempt is marked terminal Given card-network/processor code-specific restrictions that require a minimum 24-hour delay When scheduling the next attempt Then the engine enforces the minimum >= 24 hours since the last attempt Given the customer time zone is unavailable When calculating the next attempt time Then the engine falls back to billing address time zone; if unavailable, to the workspace default time zone

SCA-Aware Pause and Resume for 3DS Required Declines

Given a decline classified as sca_required or authentication_failed When handling scheduling Then the engine pauses auto-retries and sets next_action=sca_required And emits sca.action_required event And no retries occur until SCA is completed Given the customer completes SCA within the policy window (default 7 days) When the processor confirms authentication Then the engine queues an immediate retry within 2 minutes during business hours And updates status to retrying Given SCA is not completed within the policy window When the window elapses Then the engine marks the payment as failed_terminal and schedules no further retries

Idempotent Retry Processing Prevents Duplicate Charges

Given multiple triggers occur for the same payment_intent (scheduler tick, duplicate webhook, manual retry) When processing a scheduled attempt Then the engine uses a deterministic idempotency key per attempt and creates at most one authorization request And concurrent workers return idempotent no-op for the same key Given a retry attempt succeeds When late webhooks arrive for the prior failure Then no further retries are scheduled and state remains paid Given a retry attempt is in progress When another trigger fires for the same attempt Then the second trigger is dropped and the event is logged as deduplicated

Workspace Retry Policies, Safe Defaults, and Kill Switch

Given a new workspace with no custom policy When a retry schedule is needed Then the default policy is applied: max_retries=4, window_days=14, cadence=[6h,24h,48h,5d], business_hours_enabled=true, min_backoff=1h Given a workspace admin updates retry policy settings When values exceed platform guardrails Then validation prevents: max_retries>6, window_days>30, min_backoff<1h, cadence times outside [1h,14d] Given a workspace admin enables the Retry Kill Switch When active Then no new retries are scheduled and all pending scheduled retries are canceled within 5 minutes And invoices reflect status retry_paused Given the Retry Kill Switch is disabled When re-enabled Then scheduling resumes using the current policy and does not re-enqueue canceled attempts unless explicitly retried

Invoice/Contract Status Sync and Reminder Timing

Given a retry is scheduled When the schedule is created Then the related invoice status updates to retrying within 2 seconds and the next reminder time is set per policy Given a retry succeeds When confirmation is received from the processor Then the invoice status updates to paid within 3 seconds and any pending reminders are canceled And the associated contract execution record reflects payment_received Given a retry fails with terminal outcome When classification is hard_* or the retry window is exhausted Then the invoice status updates to payment_failed within 3 seconds and a decline-rescue reminder to choose an alternate method is queued within business hours And no additional retries are scheduled Given multiple status updates race When processed Then only the latest valid state is persisted using versioned updates

Event Emission and Outcome Logging for Analytics

Given any retry lifecycle change occurs (scheduled, skipped, executed, succeeded, failed, terminated, paused) When the change is committed Then an event with type retry.{status} is emitted to the event bus within 2 seconds with deduplication id = payment_intent_id+attempt_id Given a retry attempt is executed When logging the outcome Then the log record includes: attempt_id, payment_intent_id, workspace_id, decline_code, category, scheduled_at, executed_at, outcome, processor_response_code, idempotency_key, next_action, trigger_source, customer_timezone And no PAN, full card number, or CVV are stored; last4 and token are permitted Given event delivery fails When retried Then events are delivered at-least-once with deduplication enforced and failures are retried with exponential backoff up to 3 times Given analytics queries run When reading retry logs Then 100% of executed attempts within the last 30 days are present and queryable by workspace_id and date range

Network Card Updater Integration

"As a freelancer, I want expired cards to update automatically so that charges succeed without asking my client for new details."

Description

Integrates with processor-supported account updater services (e.g., Visa Account Updater, Mastercard Automatic Billing Updater) to refresh expired or replaced card tokens. Triggers updater checks on qualifying declines and scheduled intervals, seamlessly swapping updated tokens without exposing PAN data. Handles updater failures gracefully, falls back to reminders, and records outcomes for analytics. Ensures PCI scope remains SAQ A by using tokenized flows only and never storing sensitive card data.

Acceptance Criteria

Token Refresh on Qualifying Decline

Given a saved-card payment declines with a processor reason indicating expired or reissued card, When the decline is received, Then an account updater request is sent within 2 minutes, And if updated credentials are returned, Then the stored token and expiry are atomically replaced, And the payment is retried once within 60 seconds using the new token, And the updater request ID, result code, and retry outcome are recorded.

Scheduled Updater Sweep for Upcoming Payments

Given stored tokens tied to upcoming payments within 30 days, When the daily updater job runs at 02:00 UTC, Then tokens not checked in the last 30 days are submitted, And submissions respect processor rate limits and exponential backoff, And each token submission is idempotent via a per-token schedule key, And successful updates trigger a single $0/$1 authorization verification per processor rules without capturing funds.

Seamless Token Swap Without PAN Exposure

Given an updater response provides updated card details, When applying the update, Then only tokenized values plus masked last4 and expiry are stored, And no PAN/CVV is logged or persisted, And all logs and audit trails show masked values only, And automated data scans across logs and storage detect zero unmasked PAN patterns, And access to token data is restricted by least-privilege roles.

Updater Failure Fallback to Branded Reminder

Given an updater request returns no update, an error, or times out, When this occurs, Then the attempt is recorded with error code and reason, And a branded reminder to update payment method is queued within 5 minutes (unless reminders are disabled) with a secure link for alternate payment, And no more than one reminder per invoice is sent within a 24-hour window, And smart retry scheduling pauses until the customer updates the method or 24 hours elapse.

Analytics and Reporting of Updater Outcomes

Given any updater attempt completes, When logging the outcome, Then a structured analytics event is written with fields including merchant_id, token_id, card_brand, last4, expiry_old, expiry_new, result_code, triggered_by (decline|schedule|manual), and retry_result (success|fail|skipped), And the event is queryable in analytics within 15 minutes, And dashboards report updater hit rate, recovered revenue, and average time-to-recovery.

Idempotency and Duplicate Callback Handling

Given network retries or duplicate callbacks from the updater/processor occur, When duplicate responses with the same updater request ID and token_id are received within 24 hours, Then the update is applied at most once, And only a single analytics event is emitted, And no additional payment retry is triggered, And the system acknowledges subsequent duplicates with 200 OK without side effects.

Branded Multi-channel Dunning Reminders

"As a business owner, I want professional, on-brand reminders sent automatically so that clients are guided to fix their payment quickly without awkward conversations."

Description

Sends on-brand, plain-language reminders via email/SMS/in-app at configurable cadences aligned with retry schedules. Templates support localization, dynamic variables (amount, contract, reason summary), and merge tags, with deep links to a secure update portal. Includes throttling, quiet hours, and opt-out respect. Tracks delivery, opens, clicks, and conversions to inform analytics. Provides an editor in SnapAgree to customize content, tone, and branding per workspace.

Acceptance Criteria

Multi-channel Cadence Aligned to Retry Schedule

Given a declined payment with an active dunning schedule And workspace channels enabled for email, SMS, and/or in-app When a retry attempt is scheduled or completes unsuccessfully Then the system schedules reminders at the configured offsets relative to the retry times (±2 minutes) And sends via the next eligible channel per workspace sequence And cancels any pending reminder if payment succeeds before send time And does not exceed the configured per-invoice cap (default 4) and per-day cap (default 2) for reminders

Localized Templates with Dynamic Variables and Merge Tags

Given a recipient locale determined by client profile or contract When rendering a reminder for a specific channel Then the locale-specific template variant is used if available; otherwise the workspace default locale is used And dynamic variables {amount}, {currency}, {contract_title}, {reason_summary}, {due_date} render with correct values and locale formatting And merge tags {client.first_name}, {workspace.brand_name}, {update_link} resolve without placeholders And the message is blocked from sending if any variable/merge tag is unresolved; an error is logged and surfaced in the dashboard within 60 seconds

Secure Deep Links to Payment Update Portal

Given a rendered reminder message When generating the payment update link Then a signed, single-use deep link is embedded with an expiry (default 7 days) and includes a dunning_message_id for attribution And clicking the link opens the secure update portal in the recipient’s locale with invoice details and payment method options And if the link is expired or already used, the portal shows an expiration screen and allows the recipient to request a new link And the click event is recorded with message_id and client_id

Quiet Hours, Throttling, and Opt-out Compliance

Given workspace-defined quiet hours (e.g., 21:00–08:00 recipient local time) and per-recipient throttling limits When a reminder is scheduled inside quiet hours Then the send is deferred to the next allowed window for that channel And total reminders per recipient do not exceed the configured throttle (e.g., max 3 per 7 days across channels) And if a recipient has opted out of a channel, that channel is skipped; if all channels are opted out, no reminder is sent And email/SMS include functional unsubscribe instructions; opt-out actions update preferences within 60 seconds and take effect immediately

Engagement and Conversion Tracking

Given a reminder is sent via any supported channel Then delivery status (delivered, bounced, failed) is recorded with provider response codes And unique opens (email, in-app) and unique clicks are tracked with timestamps (UTC) and attributed to message_id And a conversion is recorded when the client updates payment details or a subsequent charge succeeds within the attribution window (default 14 days) after the last click/open And analytics expose filterable metrics by workspace, channel, template, locale, and date; event counts reconcile with provider logs within ±1% over a 24-hour window

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Marketplace Maverick Maya

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Redline-Ready Riley

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Flow-Down Fiona

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Mobile-Sign Max

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Privacy-First Farah

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Bilingual Bridge Bruno

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

Live Draft Composer

Requirements

Real-time Transcription & Speaker Diarization

Description

Acceptance Criteria

Intent Detection & Clause Mapping

Description

Acceptance Criteria

Live Draft Assembly Engine

Description

Acceptance Criteria

Calendar & CRM Autofill

Description

Acceptance Criteria

Missing Info Detector & Live Prompter

Description

Acceptance Criteria

Inline Clause Editor with Risk Flags

Description

Acceptance Criteria

Consent & Privacy Compliance

Description

Acceptance Criteria

Co-Edit Studio

Requirements

Secure Mid-Call Share Link

Description

Acceptance Criteria

Real-Time Presence & Conflict-Free Editing

Description

Acceptance Criteria