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.
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:
- An EU Digital Identity API key and the verifier's organization ID, sent in the
x-organization-idheader. - A
dc+sd-jwtverification template that defines the transaction structure (see below). - For the holder side: an organizational wallet, or a cloud wallet and its wallet access token.
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:
- The verification template defines which transaction fields are permitted.
- 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 anobject.
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:
- Organizational wallet:
POST /wallet/verification/submit-presentation - Cloud Wallet API:
POST /proof/submit-presentation
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"
}
]
}
hasTransactionDataindicates that the request asked the holder to approve transaction details.datacontains the values approved by the holder.credentialIdidentifies the credential query associated with the authorization.hashprotects the integrity of the transaction entry.hashAlgidentifies 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_idsbecomes["payment_approval"]. - The transaction-bearing query must belong to an
allrequirement group. - A transaction-bearing query cannot belong to an
anyrequirement group. - An
mso_mdocquery 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
| Rule | Supported behavior |
|---|---|
| Credential format | dc+sd-jwt only |
| Attribute types | string, number, and object |
| Attribute names | Letters, numbers, and underscores only |
| Maximum nesting | Five attribute levels |
| Defaults | Supported for string and number |
| Object defaults | Not supported |
| Transaction types | Each configured type must be supplied exactly once |
| Hash algorithm | sha-256 |
| Template updates | The 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-jwtverification 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_idsandtransaction_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
allrequirement group.
See the API reference for complete request schemas, HTTP responses, and validation messages.
Current limitations
- Transaction data is supported only by
dc+sd-jwtverification 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 nestedobjectvalues are supported. - The hash algorithm is fixed to
sha-256and cannot be selected by the caller. - A transaction-bearing compound query must belong to an
allrequirement group. - Shared transaction authorization across alternative queries is not supported.