Class DocVerificationChallenge

Namespace

SEBT.Portal.Core.Models.DocVerification

Assembly

SEBT.Portal.Core.dll

Represents a single document verification attempt for a user. Each challenge tracks its own lifecycle independently from the user's overall proofing status. The user entity is only updated when a challenge reaches a terminal state.

public class DocVerificationChallenge

Inheritance

object

DocVerificationChallenge

Properties

AllowIdRetry

Whether the user is allowed to retry with a different ID number instead of document verification. Derived server-side based on compliance policy — never passed via URL.

public bool AllowIdRetry { get; set; }

Property Value

bool

CreatedAt

public DateTime CreatedAt { get; init; }

Property Value

DateTime

DocvTokenIssuedAt

When DocvTransactionToken was last issued or refreshed (UTC).

public DateTime? DocvTokenIssuedAt { get; set; }

Property Value

DateTime?

DocvTransactionToken

The Socure DocV transaction token passed to the frontend SDK. Set when the DocV session is started.

public string? DocvTransactionToken { get; set; }

Property Value

string

DocvUrl

The Socure verification URL for the document capture flow.

public string? DocvUrl { get; set; }

Property Value

string

EvalId

Socure's evaluation ID, used as a fallback key for webhook correlation.

public string? EvalId { get; set; }

Property Value

string

ExpiresAt

When this challenge expires. Pending challenges past this time are transitioned to Expired on read.

public DateTime? ExpiresAt { get; set; }

Property Value

DateTime?

Id

Database primary key. Not exposed in API responses — use PublicId instead.

public Guid Id { get; init; }

Property Value

Guid

IsTerminal

Whether this challenge is in a terminal state (Verified, Rejected, Expired, or Resubmit). Terminal challenges cannot be modified. A Resubmit challenge is terminal at this challenge's scope; the user opens a fresh challenge to retry.

public bool IsTerminal { get; }

Property Value

bool

OffboardingReason

Reason code for off-boarding when verification is rejected.

public string? OffboardingReason { get; set; }

Property Value

string

ProofingDateOfBirth

Date of birth (yyyy-MM-dd) from the ID-proofing submission that created this challenge. Used to re-run Socure evaluation when the DocV transaction token expires.

public string? ProofingDateOfBirth { get; set; }

Property Value

string

ProofingIdType

Government ID type from the ID-proofing submission (e.g. ssn, itin).

public string? ProofingIdType { get; set; }

Property Value

string

ProofingIdValue

Government ID value from the ID-proofing submission.

public string? ProofingIdValue { get; set; }

Property Value

string

PublicId

Opaque identifier exposed to API consumers. Prevents IDOR enumeration of challenge records.

public Guid PublicId { get; init; }

Property Value

Guid

SocureEventId

The event ID from the last processed Socure webhook. Used for idempotency — if a webhook arrives with an event_id already recorded, it is silently ignored.

public string? SocureEventId { get; set; }

Property Value

string

SocureReferenceId

Socure's reference ID, used as the primary key for webhook correlation. Set when the DocV session is started (transition to Pending).

public string? SocureReferenceId { get; set; }

Property Value

string

Status

Current lifecycle state. Transitions enforced by TransitionTo(DocVerificationStatus).

public DocVerificationStatus Status { get; }

Property Value

DocVerificationStatus

UpdatedAt

public DateTime UpdatedAt { get; set; }

Property Value

DateTime

UserId

The ID of the user who owns this challenge. All API reads are scoped by (PublicId, UserId) to enforce ownership.

public Guid UserId { get; init; }

Property Value

Guid

Methods

Reconstitute(Guid, Guid, Guid, DocVerificationStatus, string?, string?, string?, string?, string?, string?, bool, DateTime, DateTime, DateTime?, string?, string?, string?, DateTime?)

Reconstitutes a challenge from persisted data without replaying state transitions. Used by the repository layer during deserialization. Business logic should use TransitionTo(DocVerificationStatus) instead.

public static DocVerificationChallenge Reconstitute(Guid id, Guid publicId, Guid userId, DocVerificationStatus status, string? socureReferenceId, string? evalId, string? socureEventId, string? docvTransactionToken, string? docvUrl, string? offboardingReason, bool allowIdRetry, DateTime createdAt, DateTime updatedAt, DateTime? expiresAt, string? proofingDateOfBirth = null, string? proofingIdType = null, string? proofingIdValue = null, DateTime? docvTokenIssuedAt = null)

Parameters

id Guid

publicId Guid

userId Guid

status DocVerificationStatus

socureReferenceId string

evalId string

socureEventId string

docvTransactionToken string

docvUrl string

offboardingReason string

allowIdRetry bool

createdAt DateTime

updatedAt DateTime

expiresAt DateTime?

proofingDateOfBirth string

proofingIdType string

proofingIdValue string

docvTokenIssuedAt DateTime?

Returns

DocVerificationChallenge

TransitionTo(DocVerificationStatus)

Transitions the challenge to a new status, enforcing valid state transitions. Allowed: Created → Pending → Verified | Rejected | Expired | Resubmit. Terminal states cannot be overwritten.

public void TransitionTo(DocVerificationStatus newStatus)

Parameters

newStatus DocVerificationStatus

The target status.

Exceptions

InvalidOperationException

Thrown when the transition is not allowed from the current state.