For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Smartcard signing

The SMARTCARD signing method creates certificate-based electronic signatures with a smart card that holds a qualified signing certificate, such as a national ID card. It uses the Sign API v2 public key infrastructure (PKI) signing flow, PKISIGNING.

One vendor covers all supported countries. The signer chooses their card's country during the signing process.

Supported capabilities​

Supported countries​

The signer can sign with a smart card issued in:

  • Belgium
  • Estonia
  • Finland
  • Iceland
  • Latvia
  • Lithuania
  • Poland

To allow only Estonian ID cards, use the ESTEID signing method instead.

Signer requirements​

The signer needs:

  • A physical smart card from a supported country with a valid and enabled qualified signing certificate.
  • A compatible card reader, card software and browser integration for their country.
  • The card's signing PIN, for example, PIN2 on an Estonian ID card.

Signing setup​

To request Smartcard through the Universal API, set signingSetup[].vendor to SMARTCARD and signingFlow to PKISIGNING in your HTTP POST request to the Signing sessions endpoint.

Include this configuration in the request body:

{
  "signingSetup": [
    {
      "vendor": "SMARTCARD",
      "signingFlow": "PKISIGNING",
      "identityProviders": [],
      "requestedAttributes": ["nin"]
    }
  ]
}

For the complete session creation and document upload process, see our Sign API v2 integration guide.

Signer attributes​

The verified signer name, identity provider name and uniqueId are returned by default. To request the national identity number, include nin in the requestedAttributes array.

Attribute response​

When the session is complete, output.userInfo contains the retrieved attributes:

uniqueId format​

The format of uniqueId varies by country and card generation. Some cards use the ETSI EN 319 412-1 format <type><country>-<identifier>, for example, PNOEE-30303039914 on an Estonian ID card. Others state the identifier without a prefix.

Treat uniqueId as an opaque string. A signer who renews their card can get a different uniqueId. To match a signer to a known person, request nin and use national identity number validation.

Restrict signing to a known person​

To require a particular national identity number, request nin and enable national identity number validation:

{
  "signer": {
    "nationalIdentificationNumber": "30303039914",
    "prefill": [],
    "validations": ["NATIONAL_IDENTIFICATION_NUMBER"]
  },
  "signingSetup": [
    {
      "vendor": "SMARTCARD",
      "signingFlow": "PKISIGNING",
      "identityProviders": [],
      "requestedAttributes": ["nin"]
    }
  ]
}

The session is rejected if the national identity number in the signing result differs from the configured value. Use the number exactly as it appears in output.userInfo.nin for that country. Setting nationalIdentificationNumber without "validations": ["NATIONAL_IDENTIFICATION_NUMBER"] does not enforce a match.

Identity prefill is not supported because the signer is identified by the card used during the signing process.

Signing result​

A completed session contains one PADES result for each signed input document:

{
  "lifecycle": {
    "state": "SIGNED",
    "stateIsFinal": true
  },
  "output": {
    "signatures": [
      {
        "resultDocumentId": "01a08ac4-37a4-79e1-9bc7-b8eb37295b13",
        "originalDocumentId": "01a08ac1-b34c-72c7-86af-1e80e87c8537",
        "signatureType": "PADES"
      }
    ],
    "packages": [],
    "userInfo": {
      "signingTime": "2026-10-28T14:24:18+02:00",
      "fullName": "Jaan Tamm",
      "idpName": "smartcard",
      "nin": "30303039914",
      "uniqueId": "PNOEE-30303039914",
      "firstName": "Jaan",
      "lastName": "Tamm",
      "extra": {
        "client-ip": "203.0.113.42",
        "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/148.0.0.0 Safari/537.36"
      }
    },
    "seals": []
  }
}

Use resultDocumentId to retrieve the signed PDF. For multiple documents, match each result to its input using originalDocumentId rather than array order.

Certificate requirements​

The signing certificate must identify the signer. Signing fails if the certificate contains no signer identifier, and no signed document is produced.

Test accounts​

Smartcard signing does not provide a simulator. Testing requires a physical test card from a supported country, such as an Estonian test ID card, and a card reader. The signer requirements also apply when testing.

On this page