1. Stage 8 Objective
Capture the customer's digital signature for inclusion in the Account Opening Form (AOF). The signature is submitted via canvas drawing or image upload, then validated by Claude Vision or AiNXT to confirm it is a genuine, usable handwritten signature.
Non-Blocking Validation — 3 Failed Attempts = NON_STP
Signature validation failures do not block the journey. If the customer fails validation 3 times, the system flags the lead as NON_STP (non-straight-through processing) and allows the journey to continue. The signature is reviewed manually by operations. The customer is never blocked at this stage.
Key Design Principle
The signature stage is a quality gate, not a security gate. The goal is to collect the best possible signature for the AOF. If automated validation cannot confirm quality, the lead is flagged for manual review but the customer proceeds uninterrupted.
2. Preconditions
| Condition | Required Value | Failure Action |
|---|
lead.state |
LIVENESS_DONE |
Return HTTP 409 Conflict with message: "Stage 7 (Liveness) must be completed before signature capture." |
| Lead not dropped |
lead.is_dropped = false |
Return HTTP 403 Forbidden. Journey is terminated. |
| Valid session / token |
Active JWT with matching lead_id |
Return HTTP 401 Unauthorized. |
The backend must accept signatures from two distinct input methods. The frontend determines the method; the backend validates and stores accordingly.
Method A: Draw on Canvas
- Frontend captures signature strokes on an HTML5 canvas element
- Submitted as a Base64-encoded PNG image in the request body
- Backend decodes the Base64 payload and validates image dimensions and content
- Canvas background must be transparent or white; strokes must be dark (black/dark blue)
signature_method = DRAWN
Method B: Upload Image
- Customer uploads a photograph or scan of their physical signature
- Submitted as a multipart file upload
- Accepted formats: JPG, JPEG, PNG only
- Maximum file size: 5 MB
- Backend sends the uploaded image through AiNXT Crop for signature extraction before validation
signature_method = UPLOADED
Upload Requires Cropping
When the customer uploads an image, it may contain background, paper edges, or other artifacts. The uploaded image is sent to the AiNXT Auto-Crop API to extract only the signature region before validation. Drawn canvas signatures skip this step.
4. Signature Validity Criteria
The validation service (Claude Vision or AiNXT) evaluates the submitted signature against the following criteria. A signature must pass all positive criteria and fail none of the rejection criteria to be considered valid.
4.1 Positive Criteria (Must Meet All)
| # | Criterion | Threshold | Rationale |
|---|
| 1 |
Minimum stroke count |
2 or more distinct strokes |
Ensures the signature has enough complexity to be considered a genuine handwritten mark |
| 2 |
Minimum bounding box |
At least 30px wide x 10px tall |
Prevents submissions that are too small to be legible or usable on the AOF |
| 3 |
Minimum entropy |
Sufficient pixel variation / complexity |
Ensures the image contains meaningful content rather than uniform fill or noise |
4.2 Rejection Criteria (Must Fail None)
| # | Rejection Reason | Detection Method | Example |
|---|
| 1 |
Single dot |
Bounding box below minimum dimensions; single stroke with negligible length |
Customer taps canvas once without drawing |
| 2 |
Straight line |
All stroke points are collinear within tolerance; zero or near-zero curvature |
Customer draws a single horizontal or diagonal line |
| 3 |
Closed shape |
Geometric shape detection (circle, rectangle, triangle); start and end points coincide with uniform curvature |
Customer draws a circle or square instead of signing |
| 4 |
Single character |
Character recognition detects a single isolated letter, number, or symbol |
Customer writes just "X" or "O" |
| 5 |
Typed text |
OCR / font uniformity detection; consistent letter spacing, uniform stroke width, machine-generated patterns |
Customer types their name using a text tool or pastes a typed image |
Validation Engine
Claude Vision and AiNXT are interchangeable validation providers. The active provider is determined by the provider_configurations table. If the primary provider is down, the system falls back to the secondary. If both are unavailable, the signature is accepted with PENDING_MANUAL_REVIEW status.
5. Attempt Decision Table
The backend supports up to 3 validation attempts. The following table defines the outcome for every combination of attempt number and validation result:
| Row | Attempt | Validation Result | Action | Lead State | STP Flag |
|---|
| 1 |
1 |
Valid |
Accept signature. Store image. Proceed to next stage. |
SIGNATURE_DONE |
STP |
| 2 |
1 |
Invalid |
Return rejection reason. Prompt customer to retry. Increment signature_attempts. |
LIVENESS_DONE (unchanged) |
— |
| 3 |
1 |
Service Unavailable |
Accept signature with PENDING_MANUAL_REVIEW. Store image. Proceed to next stage. |
SIGNATURE_DONE |
PENDING_MANUAL_REVIEW |
| 4 |
2 |
Valid |
Accept signature. Store image. Proceed to next stage. |
SIGNATURE_DONE |
STP |
| 5 |
2 |
Invalid |
Return rejection reason. Prompt customer to retry. Increment signature_attempts. |
LIVENESS_DONE (unchanged) |
— |
| 6 |
2 |
Service Unavailable |
Accept signature with PENDING_MANUAL_REVIEW. Store image. Proceed to next stage. |
SIGNATURE_DONE |
PENDING_MANUAL_REVIEW |
| 7 |
3 |
Valid |
Accept signature. Store image. Proceed to next stage. |
SIGNATURE_DONE |
STP |
| 8 |
3 |
Invalid |
Accept signature despite invalid result. Flag as NON_STP. Store image. Journey continues — customer is NOT blocked. |
SIGNATURE_DONE |
NON_STP |
| 9 |
3 |
Service Unavailable |
Accept signature with PENDING_MANUAL_REVIEW. Store image. Proceed to next stage. |
SIGNATURE_DONE |
PENDING_MANUAL_REVIEW |
Row 8 is Critical
After 3 failed validation attempts, the system must NOT block the customer. The signature is accepted, the lead is flagged NON_STP, and the journey continues. Operations will review the signature manually post-journey. This is a deliberate business decision to avoid customer drop-off at this late stage.
Service Unavailable Handling
If the validation service (Claude Vision / AiNXT) is unreachable on any attempt, the signature is accepted immediately with PENDING_MANUAL_REVIEW status. The system does not consume an attempt — the customer is not penalized for infrastructure failures.
6. Backend Validations
The backend performs three categories of validation, each with distinct failure behavior:
6.1 Signature Validity Check (Non-Blocking)
1
Receive signature image (Base64 for drawn, multipart for uploaded)
2
If uploaded: send to AiNXT Auto-Crop API to extract signature region from the image
3
Send signature image to Claude Vision or AiNXT validation API (based on provider_configurations)
4
Evaluate response against validity criteria (Section 4)
5
If valid: set stp_signature_flag = STP, proceed
6
If invalid and attempts < 3: return rejection reason, increment counter, prompt retry
7
If invalid and attempts = 3: set stp_signature_flag = NON_STP, accept signature, continue journey
NON_STP Does Not Block
The NON_STP flag is recorded for downstream processing but does not prevent the customer from completing the eKYC journey. It merely routes the application to a manual review queue after journey completion.
6.2 Validation Service Down (Non-Blocking)
| Scenario | Action | Status |
|---|
| Primary provider (Claude Vision / AiNXT) returns timeout or 5xx error |
Attempt fallback provider. If fallback also fails, accept signature. |
signature_validation_status = PENDING_MANUAL_REVIEW |
| Both primary and fallback providers are unreachable |
Accept signature. Log service outage event. Flag for manual review. |
signature_validation_status = PENDING_MANUAL_REVIEW |
Graceful Degradation
Validation service downtime must never block the customer. When the service is unavailable, the system accepts the signature and defers quality review to operations. A downstream_events entry is created to alert the operations team.
6.3 Storage Failure (Blocking)
| Scenario | Action | Status |
|---|
| Signature image fails to save to the configured file storage drive |
Block progression. Return HTTP 500 with retry guidance. Do not advance lead.state. |
Lead state remains LIVENESS_DONE |
Database insert for signature_verifications fails |
Block progression. Rollback any partial writes. Return HTTP 500. |
Lead state remains LIVENESS_DONE |
Storage Failure is the Only Blocking Scenario
Unlike validation failures (which are non-blocking), storage failures must block the journey. If the signature image cannot be persisted, the AOF cannot be generated. The customer must retry the submission.
7. Existing Stored Procedure Mapping
7.1 Stored Procedures (Old System)
These stored procedures from the legacy system map to Stage 8 signature functionality. They serve as reference for what the new backend must replicate:
| Stored Procedure | Purpose | New Backend Equivalent |
|---|
USP_AINXT_SIGN_RESPONSE_SJET |
Store AiNXT signature validation response (valid/invalid result, confidence score, rejection reason) |
signature_verifications table insert with provider = AINXT |
USP_CAPS_SIGN_RESPONSE_SJET |
Store CAPS signature validation response (secondary validation provider results) |
signature_verifications table insert with provider = CAPS |
USP_VALIDATE_AINXT_CROPSIGN_RESPONSE_SJET |
Store auto-crop and validation result for uploaded signature images (crop coordinates + validation outcome) |
signature_verifications table insert with crop_applied = true and crop metadata in response_payload |
7.2 Old External API Calls
Legacy API methods that the new backend must integrate with (or replace):
| Old API Method | Vendor | Purpose | New Backend Action |
|---|
SignatureAPI.AINXT_WetSign_Response() |
AiNXT |
Submit signature image to AiNXT for wet signature validation — returns valid/invalid with confidence score and rejection reason |
Signature validation service → AiNXT provider adapter |
SignatureAPI.Caps_WetSign_Response() |
CAPS |
Submit signature image to CAPS for secondary wet signature validation |
Signature validation service → CAPS provider adapter (fallback/secondary) |
SignatureAPI.AINXT_WetSign_AutoCrop_Response() |
AiNXT |
Submit uploaded image to AiNXT for auto-crop extraction of signature region, then validate the cropped result |
AiNXT Crop service → extract signature → then validate via primary provider |
7.3 Old Database Tables
Legacy tables referenced by the stored procedures above:
| Old Table | Purpose | New Backend Equivalent |
|---|
TBL_AINXT_SIGN_RESPONSE |
Stored AiNXT signature validation request/response logs, confidence scores, and validation outcomes |
signature_verifications (unified table for all signature validation providers) |
TBL_CAPS_SIGN_RESPONSE |
Stored CAPS signature validation request/response logs and results |
signature_verifications (unified table — distinguished by provider column) |
Migration Note
The old system used separate tables per vendor (TBL_AINXT_SIGN_RESPONSE, TBL_CAPS_SIGN_RESPONSE). The new system consolidates all signature validation records into a single signature_verifications table with a provider discriminator column. The new system also adds Claude Vision as a validation provider alongside AiNXT.
8. Error Codes
| Code | Type | Trigger | User Impact |
|---|
FE_SIG_001 |
Frontend Error |
Signature canvas is empty — customer submitted without drawing or uploading any content |
Show error: "Please draw your signature or upload a signature image." Customer must provide input before submission. |
FE_SIG_002 |
Frontend Error |
Uploaded file type is not supported — customer uploaded a file that is not JPG, JPEG, or PNG |
Show error: "Unsupported file format. Please upload a JPG or PNG image." Customer must re-upload with correct format. |
FE_SIG_003 |
Frontend Error |
Uploaded file exceeds the 5 MB maximum size limit |
Show error: "File size exceeds 5 MB limit. Please upload a smaller image." Customer must re-upload a smaller file. |
FE_SIG_004 |
Frontend Error |
Signature validation returned invalid — signature did not meet validity criteria (Section 4). Returned with specific rejection reason (e.g., single dot, straight line, typed text). |
Show error with rejection detail: "Your signature appears to be [reason]. Please draw a proper handwritten signature." Customer can retry (up to 3 attempts). |
FE_SIG_004 Includes Rejection Detail
When the validation service rejects a signature, the response includes a rejection_reason field (e.g., SINGLE_DOT, STRAIGHT_LINE, CLOSED_SHAPE, SINGLE_CHAR, TYPED_TEXT). The frontend maps this to a human-readable message to guide the customer toward a valid submission.
9. Exit State
After Stage 8 completes successfully (signature accepted via validation pass, 3rd-attempt override, or service-unavailable acceptance), the following fields are populated:
| Field | Value / Source | Notes |
|---|
lead.state |
SIGNATURE_DONE |
Set after signature is stored and validation is resolved (pass, NON_STP, or PENDING_MANUAL_REVIEW) |
signature_path |
File path on configured storage drive (e.g., /signatures/{lead_id}/{timestamp}.png) |
Absolute path to the stored signature image on the file storage drive. Used for AOF generation. |
signature_method |
DRAWN | UPLOADED |
DRAWN when customer used canvas; UPLOADED when customer uploaded an image file |
signature_validation_status |
VALID | INVALID_ACCEPTED | PENDING_MANUAL_REVIEW |
VALID = passed validation; INVALID_ACCEPTED = failed 3x, accepted as NON_STP; PENDING_MANUAL_REVIEW = service was down |
stp_signature_flag |
STP | NON_STP | PENDING_MANUAL_REVIEW |
Determines downstream processing path. STP = fully automated; NON_STP = manual review required; PENDING_MANUAL_REVIEW = validation deferred |
signature_attempts |
1 | 2 | 3 |
Total number of validation attempts made by the customer before signature was accepted |
State Transition
LIVENESS_DONE → SIGNATURE_DONE. This transition occurs when the signature is successfully stored, regardless of validation outcome. The stp_signature_flag determines whether the application proceeds via STP or manual review pipeline.
10. Vendor & Integration Calls
| Vendor / System | Purpose | When Called | Sync / Async |
|---|
| Claude Vision |
Primary signature validation — analyzes image to determine if it is a genuine handwritten signature meeting validity criteria |
After signature submission (drawn or cropped upload) |
Sync |
| AiNXT (Validation) |
Secondary / fallback signature validation — wet signature recognition and quality assessment |
After signature submission; used as primary or fallback based on provider_configurations |
Sync |
| AiNXT (Auto-Crop) |
Signature extraction from uploaded images — crops and isolates the signature region from background, paper edges, and noise |
Only for UPLOADED signatures, before validation |
Sync |
| File Storage (Configured Drive) |
Persistent storage of signature image files on a configured network/local drive |
After validation is resolved (pass, NON_STP, or PENDING_MANUAL_REVIEW) |
Sync |
| CleverTap |
Event tracking — signature submitted, validation result, attempt count, STP flag |
After signature stage completion |
Async |
| Zoho CRM |
Lead status update — signature captured, STP/NON_STP flag, validation status |
After signature stage completion |
Async |
| Datalake |
Analytics event logging — signature method, attempt count, validation provider, result, processing time |
After signature stage completion |
Async |
File Storage: Configured Drive, NOT S3
Signature images are stored on a configured file storage drive (network or local path), not on AWS S3 or any cloud object storage. The storage path is configured via application settings. No Redis is used in this stage.
No Redis in Stage 8
Unlike other stages that may use Redis for caching or temporary state, Stage 8 does not use Redis. Signature attempt counters are tracked in the signature_verifications database table. File paths are stored directly in the database after file system write.
11. Database Tables (New Backend)
11.1 Operational Tables
| Table | Purpose | Key Fields (Stage 8 Relevant) |
|---|
signature_verifications NEW |
Signature validation attempt log — one row per validation attempt per lead. Consolidates records from all validation providers (Claude Vision, AiNXT, CAPS). |
lead_id, attempt_number (1/2/3), provider (CLAUDE_VISION / AINXT / CAPS), signature_method (DRAWN / UPLOADED), validation_result (VALID / INVALID / SERVICE_UNAVAILABLE), rejection_reason (SINGLE_DOT / STRAIGHT_LINE / CLOSED_SHAPE / SINGLE_CHAR / TYPED_TEXT / null), confidence_score, crop_applied (boolean), request_payload, response_payload, processing_time_ms, created_at |
document_path_info EXISTING |
Stores file path references for all document types across the journey. Signature images are stored here with document_type = SIGNATURE. |
lead_id, document_type (SIGNATURE), file_path (path on configured drive), file_name, file_size_bytes, mime_type (image/png / image/jpeg), upload_method (DRAWN / UPLOADED), created_at, is_active (boolean — only the latest accepted signature is active) |
journey_stage_events EXISTING |
Stage transition audit trail |
lead_id, stage (STAGE_8), event (SIGNATURE_SUBMITTED / SIGNATURE_VALID / SIGNATURE_INVALID / SIGNATURE_ACCEPTED_NON_STP / SIGNATURE_ACCEPTED_PENDING_REVIEW), metadata (JSON: attempt_number, method, provider, rejection_reason), created_at |
downstream_events EXISTING |
Async events dispatched to external systems |
lead_id, target (clevertap / zoho / datalake), event_type (SIGNATURE_DONE), payload (JSON: stp_flag, method, attempts), status (PENDING / DISPATCHED / DELIVERED / FAILED), dispatched_at |
11.2 Reference / Configuration
| Table | Purpose | Key Fields |
|---|
provider_configurations EXISTING |
Feature flags and configuration for signature validation providers |
provider_name (claude_vision / ainxt_sign / ainxt_crop / caps_sign), is_enabled, is_primary, timeout_ms, retry_count, fallback_provider, base_url |
Unified signature_verifications Table
The old system split validation records across TBL_AINXT_SIGN_RESPONSE and TBL_CAPS_SIGN_RESPONSE. The new signature_verifications table unifies all providers under a single schema with a provider discriminator. This simplifies querying, reporting, and adding new validation providers in the future.
document_path_info.is_active Flag
When a customer retries signature submission, a new document_path_info row is created with is_active = true, and the previous row is set to is_active = false. Only the latest accepted signature should have is_active = true. The old signature file is not deleted from the file storage drive (retained for audit purposes).