Document ID signing (v3)

Identity verification combined with electronic signature, with cancellation routing (v3)

Extends Document ID signing (v2) with an explicit cancelled output route that lets flows handle user-initiated or agent-initiated session cancellations without throwing an error. Use DOC_ID_SIGNING:v3 when you want to route cancelled sessions to a RETRY_PROMPT:v1 step or to a rejection end node, rather than relying on the generic error path.

Key features

All capabilities of Document ID signing (v2) — QES and contract signing modes, document verification, unified Verification data block, signed documents package.
Explicit cancellation routing — Cancelled sessions always exit via the cancelled port instead of throwing, enabling flow-level handling (retry prompts, rejection paths).
Configurable capture — Selectively disable biometric sample or document image capture to reduce data collection scope.

Configuration

Parameter	Type	Required	Description
`signingMode`	string (enum)	Yes	Signing mode: `QES` (Qualified Electronic Signature) or `CONTRACT_SIGNING` (standard contract signing).
`config.live.shortname`	string	Yes	DocIDV shortname for the live environment. Provided by IDnow during onboarding.
`config.staging.shortname`	string	Yes	DocIDV shortname for the staging environment. Provided by IDnow during onboarding.
`inputSources.basicIdentity`	string	Yes	ID of an upstream step whose `BasicIdentity` output provides identity data for verification and signing.
`inputSources.documentsToSign`	string	Conditional	ID of an upstream step whose `DocumentsToSign` output provides the documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`; not required for `QES`.
`handoff`	boolean	No	When `true`, redirects the player immediately when the identification enters a pending review state and resumes polling in the background. Uses the session `redirectUrl` if configured; otherwise shows a submission-complete message. Default: `false`.
`webJourneyOnly`	boolean	No	When `true`, the redirect URL is constructed as the DocIDV web journey URL instead of the channel chooser URL. Default: `false`.
`capture.biometricSample`	boolean	No	When `false`, the biometric sample (selfie) capture step is skipped and the `BiometricSamples` data block is not produced. Default: `true`.
`capture.documentImages`	boolean	No	When `false`, the document image capture step is skipped and the `DocumentImages` data block is not produced. Default: `true`.

Example

QES mode:

{
  "signingMode": "QES",
  "config": {
    "live": { "shortname": "acme-live" },
    "staging": { "shortname": "acme-staging" }
  },
  "inputSources": {
    "basicIdentity": "SPHINX"
  }
}

Contract signing mode:

{
  "signingMode": "CONTRACT_SIGNING",
  "config": {
    "live": { "shortname": "acme-live" },
    "staging": { "shortname": "acme-staging" }
  },
  "inputSources": {
    "basicIdentity": "SPHINX",
    "documentsToSign": "COLLECT_DOCUMENTS"
  }
}

Wiring cancellation routing with a retry prompt

[
  {
    "id": "DOC_ID_SIGNING",
    "type": "DOC_ID_SIGNING:v3",
    "options": {
      "signingMode": "QES",
      "inputSources": { "basicIdentity": "SPHINX" },
      "config": { "live": { "shortname": "acme-live" }, "staging": { "shortname": "acme-staging" } }
    },
    "next": [
      { "port": "verified", "id": "END_ACCEPTED" },
      { "port": "fraud_detected", "id": "END_REJECTED" },
      { "port": "cancelled", "id": "RETRY_PROMPT" }
    ]
  },
  {
    "id": "RETRY_PROMPT",
    "type": "RETRY_PROMPT:v1",
    "options": {},
    "next": [
      {
        "port": "retry",
        "id": "DOC_ID_SIGNING",
        "type": "rollback",
        "rollback": { "maxAttempts": 3 }
      }
    ]
  }
]

Input data blocks

Data block	Required	Mode	Description
`BasicIdentity`	Yes	Both	Identity data from the upstream node (typically DocIDV). Used for verification and as signer identification in the signature process.
`DocumentsToSign`	Conditional	CONTRACT_SIGNING	Documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`; not required for `QES`.

File size limit

Each file referenced in DocumentsToSign must not exceed 20 MB. Exceeding this limit returns HTTP 422 with error code FILE_TOO_LARGE at session creation.

Routes

Route	Condition	Description
`verified`	Always available	Identity verification succeeded and documents were signed successfully. Status from the signature service is either `SUCCESS` or `SUCCESS_DATA_CHANGED`.
`fraud_detected`	Always available	Identity verification failed due to fraud detection. Fraud was detected and confirmed after review. Identity data and verification information may be available for further analysis.
`cancelled`	Always available	Session cancelled by the user or agent. Carries a `Verification` data block; identity data blocks present only on agent-initiated cancellations.

Output data blocks

Route	Data blocks produced	Notes
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `SignedDocumentsPackage`, `DocumentImages` (unless `capture.documentImages: false`), `BiometricSamples` (unless `capture.biometricSample: false`)	All blocks populated; signed documents and audit trail returned in `SignedDocumentsPackage`.
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (unless `capture.documentImages: false`), `BiometricSamples` (unless `capture.biometricSample: false`)	`SignedDocumentsPackage` not produced on the fraud path.
`cancelled`	`Verification`	Identity data blocks populated only when an agent cancelled with a business reason.

Relationship to Document ID signing (v2)

DOC_ID_SIGNING:v3 is a superset of DOC_ID_SIGNING:v2. Existing DOC_ID_SIGNING:v2 flows do not need to migrate — use DOC_ID_SIGNING:v3 for new flows that require explicit cancellation handling.

Identity verification combined with electronic signature, with cancellation routing (v3)​

Key features​

Configuration​

Example​

Wiring cancellation routing with a retry prompt​

Input data blocks​

Routes​

Output data blocks​

Relationship to Document ID signing (v2)​