Signing incl. verifying ID (v3)

Preview / Alpha

This version of this step type is in preview / alpha. The functionality and subsequently the documentation can still change. The stable / GA version of this step is Signing incl. verifying ID (v2)

Identity verification combined with electronic signature, with cancellation routing

Extends Signing incl. verifying ID (v2) with an explicit cancelled output route that lets flows handle user-initiated or agent-initiated session cancellations without throwing an error. Use this step when you want to route an enduser cancelled process to a different step or to a rejection step, rather than relying on the generic error path.

Key features

All capabilities of Signing incl. verifying ID (v2) — QES and contract signing modes, document verification, unified Verification data block, signed documents package.
Explicit cancellation routing: When enableCancellation: true, cancelled sessions exit via the cancelled route, enabling flow-level handling (retry prompts, rejection paths). When false (the default), the session immediately aborts with an ABORTED outcome.
Configurable capture: Selectively disable biometric sample or document image capture to reduce data collection scope.

Configuration

Option	Type	Required	Default	Description
`signingMode`	string	Yes	—	Signing mode: `QES` (Qualified Electronic Signature) or `CONTRACT_SIGNING` (standard contract signing). Accepted values: `CONTRACT_SIGNING`, `QES`.
`inputSources`	object	Yes	—	Maps upstream step IDs to input data blocks. See `Input mapping`.
`inputSources.basicIdentity`	string	Yes	—	ID of an upstream step whose `BasicIdentity` output provides identity data for verification and signing.
`inputSources.documentsToSign`	string	No	—	ID of an upstream step whose `DocumentsToSign` output provides the documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`; not required for `QES`.
`config`	object	Yes	—	Environment-specific configuration.
`config.live.shortname`	string	Yes	—	DocIDV shortname for the environment (live or staging). Provided by IDnow during onboarding. (live)
`config.staging.shortname`	string	Yes	—	DocIDV shortname for the environment (live or staging). Provided by IDnow during onboarding. (staging)
`capture`	object	No	—	Capture configuration for optional output data blocks.
`capture.biometricSample`	boolean	No	`true`	When `false`, the biometric sample (selfie) capture step is skipped and the `BiometricSamples` data block is not produced.
`capture.documentImages`	boolean	No	`true`	When `false`, the document image capture step is skipped and the `DocumentImages` data block is not produced.
`handoff`	boolean	No	`false`	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.
`webJourneyOnly`	boolean	No	`false`	When `true`, the redirect URL is constructed as the DocIDV web journey URL instead of the channel chooser URL.
`enableCancellation`	boolean	No	`false`	When `true`, cancelled sessions (user-initiated or agent-initiated) exit via the `cancelled` route. Must be `true` to use the `cancelled` route. When `false` or absent (default), the session immediately ends with an `ABORTED` outcome instead.

Example configuration

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"
  }
}

Input data blocks

Data block	Required	Description
`BasicIdentity`	Yes	Identity data from the upstream step (typically DocIDV). Used for verification and as signer identification in the signature process.
`DocumentsToSign`	Conditional	Documents to sign. Present unless `signingMode` is `QES`.

File size limit

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

Routes

Route	Description
`verified`	Identity verification succeeded and documents were signed successfully. Status from the signature service is either `SUCCESS` or `SUCCESS_DATA_CHANGED`. All data blocks are populated; the signed documents and audit trail are returned in `SignedDocumentsPackage`.
`fraud_detected`	Identity verification failed due to fraud detection, confirmed after review. Identity data and verification information may be available for further analysis, but no `SignedDocumentsPackage` is produced.
`cancelled`	Available only when `enableCancellation` is `true`. User or agent cancelled; the end user can be routed to retry or a different step. Identity data blocks are only populated when an agent cancelled with a business reason.

Wire Cancellation with Retry prompt (v1)

In case of cancellation - triggered by enduser or by agent - we recommend connecting this route to the Retry prompt (v1). So that the user may confirm to retry and go through the step again.

Output data blocks

Route	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `SignedDocumentsPackage` conditionally: `DocumentImages` (unless `capture.documentImages` is `false`) `BiometricSamples` (unless `capture.biometricSample` is `false`)
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification` conditionally: `DocumentImages` (unless `capture.documentImages` is `false`) `BiometricSamples` (unless `capture.biometricSample` is `false`)
`cancelled`	`Verification` Available only when `enableCancellation` is `true`.

Step compatibility

The DocumentImages produced by DOC_ID_SIGNING:v3 are ID-category images (passport, driving licence, etc.). They cannot be used as input to IBAN_VERIFICATION:v1 or PROOF_OF_ADDRESS:v1, which require bank or address documents respectively.

Example payloads

BasicIdentity — verified

{
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "portrait": {
    "$ref": "vault",
    "$id": "01960000-43d8-7000-8000-6814c0bdc35a"
  },
  "nationality": "FRA",
  "personalAdministrativeNumber": null,
  "familyNameBirth": "Dupont",
  "givenNameBirth": "Jean",
  "sex": 1,
  "emailAddress": null,
  "mobilePhoneNumber": null,
  "residentAddress": "24 RUE DANTON 35700 RENNES FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentHouseName": null,
  "residentCountry": "FR",
  "residentState": "Bretagne",
  "residentCity": "RENNES",
  "residentPostalCode": "35700"
}

DocumentData — verified

{
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

Verification — verified

{
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": []
    },
    {
      "type": "electronicSignature",
      "signatureType": "qes_eidas",
      "issuer": "IDnow QES CA",
      "serialNumber": "0123456789abcdef",
      "issuedAt": "2026-02-10T14:00:00.000Z",
      "evidence": []
    }
  ],
  "provider": "IDnow",
  "trustFramework": "eidas",
  "assuranceLevel": "high",
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-abc123"
}

SignedDocumentsPackage — verified

{
  "signatureProcessId": "txn-01960000-7a2b-7000-8000-3f8e91c047d2",
  "signedDocuments": {
    "mode": "archive",
    "archive": {
      "$ref": "vault",
      "$id": "01960000-7a2b-7000-8000-3f8e91c047d2"
    },
    "documents": []
  },
  "createdAt": "2026-02-10T14:00:01.000Z"
}

Verification — fraud_detected

{
  "status": "fraudDetected",
  "terminationReason": {
    "code": "FRAUD_SUSPICION_CONFIRMED",
    "message": "Document fraud confirmed after review"
  },
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "documentValidity",
          "sources": [],
          "outcome": "failed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": []
    }
  ],
  "provider": "IDnow",
  "trustFramework": "eidas",
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:05:33.000Z",
  "verificationProcessId": "txn-def456"
}

Verification — cancelled

{
  "status": "canceled",
  "terminationReason": {
    "code": "USER_CANCELLED",
    "message": null
  },
  "methods": [],
  "provider": "IDnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:02:15.000Z",
  "verificationProcessId": "txn-ghi789"
}

Relationship to Signing incl. verifying ID (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​

Key features​

Configuration​

Example configuration​

Input data blocks​

Routes​

Output data blocks​

Example payloads​

Relationship to Signing incl. verifying ID (v2)​