Skip to main content

Transaction data

Transaction data lets a verifier ask a wallet holder to approve specific information while presenting a credential. It connects proof of who the holder is with proof that they authorized a particular action.

For example, a merchant may need the holder to confirm:

  • The payment recipient
  • The amount
  • The currency

The holder reviews those details in their wallet before submitting the presentation. After verification, the merchant can confirm that the approved details are the same details included in the original request.

Why transaction data matters in EU Digital Identity

Payment authentication is an important EU Digital Identity Wallet use case. Transaction data can bind a credential presentation to approval of details such as the payee, amount, and currency. However, the mechanism is not limited to payments. It can also support other structured authorization scenarios when a verifier needs evidence that the wallet holder approved specific information, such as agreeing to terms or authorizing a document-related action.

See the European Commission's Payment Authentication use case and the standard's transaction-data mechanism.

Transaction data records an authorization within the credential-presentation flow. It does not process a payment or, by itself, establish compliance with payment, identity, or electronic-signature regulation.

Before you start​

You need:

Example: payment authorization​

Wallet user starts checkout
↓
Merchant requests identity and payment approval
↓
Wallet displays the payee, amount, and currency
↓
Holder reviews and approves the request
↓
Wallet binds the approval to the credential presentation
↓
Merchant verifies the credential and approved transaction

Two pieces are configured at different times:

  1. The verification template defines which transaction fields are permitted.
  2. Each proof request supplies the values the holder must approve.

This separation lets an organization reuse one verification template for many transactions while validating every request against the same structure.

Define the transaction structure​

Define transactionData when creating a dc+sd-jwt verification template through POST /verification-template/sd-jwt/create.

The following template defines a payment transaction containing a payee, amount, and currency:

{
"name": "Payment approval",
"version": "1.0.0",
"description": "Verify identity and approve a payment",
"requestedAttributes": [
{
"name": "name",
"label": "Name",
"type": "string",
"required": true
}
],
"transactionData": [
{
"type": "payment",
"attributes": [
{
"name": "payment_data",
"type": "object",
"required": true,
"attributes": [
{
"name": "payee",
"type": "string",
"required": true
},
{
"name": "amount",
"type": "number",
"required": true
},
{
"name": "currency",
"type": "string",
"required": true,
"defaultValue": "EUR"
}
]
}
]
}
]
}

The important fields are:

  • transactionData[].type: Identifies the kind of transaction.
  • attributes: Defines the values accepted in a proof request.
  • required: Determines whether a value must be resolved.
  • defaultValue: Supplies a value when a string or number is omitted from the proof request.
  • Nested attributes: Defines fields inside an object.

The template defines the structure only. It does not contain the payee or amount for a particular purchase.

Request approval for a payment​

Create a proof request through POST /verification/send-proof-request. Supply the transaction values at the root when using a single verification template:

{
"verificationTemplateId": "61a5e3b4-b19a-4223-a8d1-098e92786b31",
"transactionData": [
{
"type": "payment",
"payment_data": {
"payee": "Merchant Ltd",
"amount": 23.58
}
}
]
}

The request omits currency, so the template default resolves it to EUR.

The caller supplies only the transaction's business values. Hovi adds:

  • credential_ids, which binds the transaction to the applicable credential query.
  • transaction_data_hashes_alg, which is currently set to ["sha-256"].

Holder reviews the transaction​

The holder should preview the request before submitting it. This gives them an opportunity to review the payee, amount, and currency they are being asked to approve.

Organizational wallet​

Preview through POST /wallet/verification/preview-request:

{
"proofRequestUri": "openid4vp://?client_id=...&request_uri=..."
}

The following excerpt shows the transaction-specific part of the preview:

{
"transactionData": [
{
"entry": {
"transactionData": {
"type": "payment",
"credential_ids": ["7d88c908-3b3f-413d-9dc5-a3a8b7905899"],
"transaction_data_hashes_alg": ["sha-256"],
"payment_data": {
"payee": "Merchant Ltd",
"amount": 23.58,
"currency": "EUR"
}
},
"encoded": "...",
"transactionDataIndex": 0
},
"matchedCredentialIds": ["7d88c908-3b3f-413d-9dc5-a3a8b7905899"]
}
]
}

Cloud Wallet API​

Preview through POST /proof/preview-request:

{
"protocol": "openid",
"proofRequestUri": "openid4vp://?client_id=...&request_uri=..."
}

The Cloud Wallet API exposes the same approval data in its transaction preview shape:

{
"transactionData": [
{
"type": "payment",
"transactionDataIndex": 0,
"matchedCredentialIds": ["7d88c908-3b3f-413d-9dc5-a3a8b7905899"],
"payload": {
"type": "payment",
"credential_ids": ["7d88c908-3b3f-413d-9dc5-a3a8b7905899"],
"transaction_data_hashes_alg": ["sha-256"],
"payment_data": {
"payee": "Merchant Ltd",
"amount": 23.58,
"currency": "EUR"
}
}
}
]
}

matchedCredentialIds contains credential-query IDs, not stored wallet credential IDs. It shows which requested credential can authorize the transaction.

The holder reviews the values from the proof request. The holder does not send replacement transaction values during submission.

Holder submits the presentation​

Transaction data uses the normal presentation-submission flow:

The wallet binds the transaction authorization to the presented credential. No additional transaction-data field is required in the submission body.

If the holder must choose a credential explicitly, use the normal credentialId or selectedCredentials field supported by the request. Do not include another copy of transactionData.

Verifier retrieves the approved transaction​

Retrieve the completed proof request through GET /verification/proof-request/find, using the proofExchangeId returned when the request was created.

The following excerpt shows the transaction-specific result:

{
"hasTransactionData": true,
"transactionData": [
{
"index": 0,
"type": "payment",
"credentialId": "7d88c908-3b3f-413d-9dc5-a3a8b7905899",
"data": {
"payment_data": {
"payee": "Merchant Ltd",
"amount": 23.58,
"currency": "EUR"
}
},
"hash": "Xq3v...",
"hashAlg": "sha-256"
}
]
}
  • hasTransactionData indicates that the request asked the holder to approve transaction details.
  • data contains the values approved by the holder.
  • credentialId identifies the credential query associated with the authorization.
  • hash protects the integrity of the transaction entry.
  • hashAlg identifies the algorithm used to create the hash.

The EU Digital Identity verification webhook includes hasTransactionData. Retrieve the proof request to obtain the complete verified transaction entries. See the verification webhook API reference for the complete webhook schema.

Use transaction data with compound proof requests​

Transaction data can also be attached to a credential query in a compound request:

{
"id": "payment_approval",
"verificationTemplateId": "61a5e3b4-b19a-4223-a8d1-098e92786b31",
"transactionData": [
{
"type": "payment",
"payment_data": {
"payee": "Merchant Ltd",
"amount": 23.58
}
}
]
}

For compound requests:

  • Put the values inside the applicable credentialQueries[] item, not at the request root.
  • The transaction is bound only to its parent query. In this example, credential_ids becomes ["payment_approval"].
  • The transaction-bearing query must belong to an all requirement group.
  • A transaction-bearing query cannot belong to an any requirement group.
  • An mso_mdoc query may appear in the same compound request, but it cannot carry transaction data.

See Compound proof requests for query grouping, credential matching, explicit selection, and submission behavior.

Transaction structure rules​

RuleSupported behavior
Credential formatdc+sd-jwt only
Attribute typesstring, number, and object
Attribute namesLetters, numbers, and underscores only
Maximum nestingFive attribute levels
DefaultsSupported for string and number
Object defaultsNot supported
Transaction typesEach configured type must be supplied exactly once
Hash algorithmsha-256
Template updatesThe transaction structure cannot be updated

The names type, credential_ids, and transaction_data_hashes_alg are reserved at the top level of a transaction definition.

Common problems​

  • The credential format is unsupported. Transaction data is accepted only for a dc+sd-jwt verification template.
  • The template has no transaction structure. Do not send transaction values unless the referenced template defines them.
  • Transaction values are missing. A proof request must include every transaction type defined by the template.
  • A transaction type is duplicated. Supply each configured type exactly once.
  • A required value is missing. Supply it in the request or configure a valid default on the template.
  • A value has the wrong type. Strings, finite numbers, and plain objects must match the template definition.
  • An unexpected field was supplied. Requests cannot add fields that are not present in the template structure.
  • A reserved field was supplied. Hovi generates credential_ids and transaction_data_hashes_alg.
  • The nesting is too deep. Transaction structures support up to five attribute levels.
  • The transaction is attached to an alternative query. In a compound request, the applicable query must belong to an all requirement group.

See the API reference for complete request schemas, HTTP responses, and validation messages.

Current limitations​

  • Transaction data is supported only by dc+sd-jwt verification templates.
  • mso_mdoc, JSON-LD, vc+sd-jwt, JWT, and AnonCreds cannot carry transaction data.
  • The transaction structure is fixed when the verification template is created. Create a new template to change it.
  • Every transaction type defined by the template must be supplied exactly once per request.
  • Only string, number, and nested object values are supported.
  • The hash algorithm is fixed to sha-256 and cannot be selected by the caller.
  • A transaction-bearing compound query must belong to an all requirement group.
  • Shared transaction authorization across alternative queries is not supported.