Transaction Data Profiles

transaction-data-profiles.conf defines the transaction data types the verifier and wallet recognize for binding presentations to specific actions (e.g., payment authorization, account access, SCA payment).

Transaction data types act as namespaces that:

  • Enforce which types the wallet will accept in authorization requests
  • Define the structure and fields for UI/discovery endpoints
  • Are validated by the wallet's TransactionDataTypeRegistry
  • Are used as the DeviceSigned namespace for mso_mdoc transaction-data binding

The transaction-data-profiles feature is enabled by default for Verifier2 and backs the runtime discovery endpoint:

GET /transaction-data-profiles

The same profile format is also used by the walt.id Wallet API (see Wallet2 transaction-data profiles)

mDoc issuance grant: For mso_mdoc credentials, registering a type here is not enough for the holder to device-sign it. The credential's MSO must authorize that type via KeyAuthorizations, which Issuer2 sets from the profile field authorizedTransactionDataTypes. SD-JWT VC presentations bind transaction data in the KB-JWT and do not use that field.

Fields

transactionDataProfiles

Array of Objects — List of recognized transaction data types. Each profile defines:

FieldTypeDescription
typeStringRequired. The transaction data type identifier. Used as the type field in transaction data entries and as the namespace for mdoc DeviceSigned binding. Example: "org.waltid.transaction-data.payment-authorization"
displayNameStringHuman-readable name for this type. Used in UIs and discovery endpoints. Defaults to type if not specified.
fieldsArrayList of expected top-level field names for this type. Used for documentation and UI generation. Nested payloads (e.g. SCA) can declare a single container field such as ["payload"].

Built-in Profiles

The default configuration includes:

transaction-data-profiles.conf
transactionDataProfiles = [
  {
    type = "org.waltid.transaction-data.payment-authorization"
    displayName = "Payment Authorization"
    # Android Credential Manager matcher reads merchant_name and amount for generic payment entries.
    fields = ["merchant_name", "amount", "currency"]
  },
  {
    type = "org.waltid.transaction-data.account-access"
    displayName = "Account Access"
    fields = ["account_identifier", "access_scope"]
  },
  {
    # EUDI TS-12 SCA payment type. Payload nests, so the matcher reads
    # payload.payee.name, payload.currency and payload.amount rather than flat fields.
    type = "urn:eudi:sca:payment:1"
    displayName = "SCA Payment"
    fields = ["payload"]
  },
  {
    # Interop identifier used by some OpenID4VP payment-card verifiers. Prefer a
    # collision-resistant type for new deployments.
    type = "payment_card"
    displayName = "Payment Card"
    fields = ["merchant_name", "amount"]
  }
]
TypeShapeNotes
org.waltid.transaction-data.payment-authorizationFlat fieldswalt.id payment demo type
org.waltid.transaction-data.account-accessFlat fieldsAccount access demo type
urn:eudi:sca:payment:1Nested payloadEUDI TS-12 SCA payment; amount is a JSON number inside payload
payment_cardFlat merchant_name, amountInterop identifier used by some OpenID4VP payment-card verifiers. Prefer a collision-resistant type for new deployments. amount may be a combined string such as "EUR 200.00".

Discovery

The transaction-data-profiles feature is enabled by default and loads transaction-data-profiles.conf. Community Verifier2 exposes that HOCON list at:

GET /transaction-data-profiles

Community Verifier2 does not expose GET /transaction-data-profiles/{type} or create, replace, or delete. Session create checks transaction_data shape and DCQL binding, and validates the built-in TS12 payment payload. Other custom types retain structure-only validation without a type allowlist. The Wallet2 type registry still rejects unknown transaction_data.type values when that feature is enabled.

Runtime overlay mutations are not exposed on Community Verifier2. Durable types live in transaction-data-profiles.conf. Per-service create, replace, delete, and session-create type enforcement live on Enterprise Wallet2 and Verifier2.

Wallet API v1 exposes GET /transaction-data-profiles only.

TS12 Payment Payload

For urn:eudi:sca:payment:1, discovery responses additionally include read-only payloadSchema. The configured fields remains ["payload"]; stored profiles and CRUD request bodies retain their existing shape. Response readers must tolerate the new optional descriptor. It describes authoring fields and cannot override validation or supply authoritative wallet consent labels.

Both Verifier2 editions validate this built-in payload and return HTTP 400 before creating an invalid session. Required fields are transaction_id (1–36 Unicode characters), payee.name, payee.id, currency and numeric amount.

Optional fields include date_time, payee logo/website, pisp (all three of legal_name, brand_name, domain_name are required when present), amount_estimated, amount_earmarked and sct_inst.

Use either execution_date or recurrence, never both. All timestamps use date-time strings with an explicit offset, following the published schema where the TS12 prose uses date wording. Execution time must not be in the past. Recurrence requires frequency and supports start_date, end_date, number and mit_options. MIT options are amount_variable, min_amount, max_amount, total_amount, initial_amount, initial_amount_number and apr. Supported frequency codes are INDA, DAIL, WEEK, TOWK, TWMN, MNTH, TOMN, QUTR, FOMN, SEMI, YEAR and TYEA. Frequency and Boolean wording is available in English and German (for example, “Monthly” and “Yes”/“No”). Consent chooses a complete language from the preferred-language list, including regional fallback (for example, de-AT to de). It fails with MISSING_TRANSLATION when no preferred language covers every present field, UI label, frequency and Boolean value; raw frequency codes are never used as fallback text.

Payment and MIT monetary amounts use major currency units with ISO 4217 decimal precision; apr is a percentage with independent precision. Counts are mathematical integers. Unknown nested properties, blank identity strings, numeric tokens longer than 128 characters and exponents outside -128 to 128 are rejected. Nested property rejection and resource bounds are product policy beyond the upstream schema.

Both session editors provide guided fields and JSON editing, preserving optional absence, false/zero values and exact numeric tokens. Every present consent leaf still needs an issuer-provided claim label, including fields omitted by visualisation level 4. The Android additional-review preference and its system-sheet display limitations remain.

App reviews group payee details and show the amount with its ISO currency code. Issuer labels and placement remain authoritative. Payment timing and recurring monetary terms use separate cards; main-review fields stay visible without expansion, while supplementary details can start collapsed. Valid logos appear beside the payee; missing or failed logos stay hidden. Remote logos load only on an explicit tap. HTTPS websites are clickable and retain the full destination; other URI schemes remain text.

The demos omit visible logo and currency captions while retaining issuer metadata and accessible logo labels. Production use of these omissions requires permission from the applicable SCA Attestation Rulebook under TS12 §3.3.1.

For the four TS12 timestamps, supported display forms use the device's current locale and timezone with an explicit timezone label. Other valid forms remain labelled source text. Original offset-bearing strings remain unchanged for validation and proof binding; identifiers that resemble timestamps remain text.

Roll out updated issuer metadata and backend/wallet support before enabling scheduled or recurring authoring in deployed portals. Fresh public-demo acceptance requires this rollout and new credentials. Portals retain generic editing when older discovery omits payloadSchema. Credentials that pin changed metadata by integrity hash need versioned metadata and reissuance; failed integrity checks must not be bypassed. No database migration is required.

The contract follows EUDI TS12 v1.0.1 §4.3.1 and its payment schema.

Adding Custom Types

To add a custom transaction data type, add a new entry to the transactionDataProfiles array in both config files and restart:

  • Verifier: waltid-services/waltid-verifier-api2/config/transaction-data-profiles.conf
  • Wallet: waltid-services/waltid-wallet-api2/config/transaction-data-profiles.conf

For mDoc holders that must device-sign the type, also list it on the Issuer2 profile as authorizedTransactionDataTypes

Example: Adding a subscription authorization type:

transaction-data-profiles.conf
transactionDataProfiles = [
  {
    type = "org.waltid.transaction-data.payment-authorization"
    displayName = "Payment Authorization"
    fields = ["merchant_name", "amount", "currency"]
  },
  {
    type = "org.waltid.transaction-data.account-access"
    displayName = "Account Access"
    fields = ["account_identifier", "access_scope"]
  },
  {
    type = "urn:eudi:sca:payment:1"
    displayName = "SCA Payment"
    fields = ["payload"]
  },
  {
    type = "org.example.subscription-authorization"
    displayName = "Subscription Authorization"
    fields = ["service_name", "billing_cycle", "price"]
  }
]

Important: Transaction data types must be configured on both the verifier and wallet. Mismatched configurations will cause the wallet to reject authorization requests with unknown types.

Usage in Verification Requests

Once configured, use the type in your verification session transaction data.

Flat walt.id payment type:

{
  "flow_type": "cross_device",
  "core_flow": {
    "dcql_query": { "...": "..." }
  },
  "openid": {
    "transactionData": [
      {
        "type": "org.waltid.transaction-data.payment-authorization",
        "credential_ids": ["pid"],
        "require_cryptographic_holder_binding": true,
        "transaction_data_hashes_alg": ["sha-256"],
        "merchant_name": "ACME Corp",
        "amount": "42.00",
        "currency": "EUR"
      }
    ]
  }
}

Nested SCA payment type:

{
  "openid": {
    "transactionData": [
      {
        "type": "urn:eudi:sca:payment:1",
        "credential_ids": ["sca_payment_card"],
        "require_cryptographic_holder_binding": true,
        "transaction_data_hashes_alg": ["sha-256"],
        "payload": {
          "transaction_id": "8D8AC610-566D-4EF0-9C22-186B2A5ED793",
          "payee": {
            "name": "Super Store",
            "id": "merchant-001"
          },
          "currency": "EUR",
          "amount": 11.56
        }
      }
    ]
  }
}

See Transaction Data Authorization for complete usage details.

Last updated on November 6, 2026