multipaz/org.multipaz.documenttype/TransactionType

TransactionType

abstract class TransactionType<PayloadT : Any>(val displayName: String, val identifier: String, val kbJwtResponseClaimName: String = identifier, val iso18013RequestInfoIdentifier: String = identifier, val openId4VpMdocResponseNamespace: String = identifier)

Represents a transaction data type used for dynamic linking and transaction authorization in digital credential presentations.

Dynamic linking cryptographically binds a presentation to a specific transaction context (such as payment amount, currency, payee, or nonce) and optional user input (such as tip amount), ensuring the credential holder explicitly authorizes the transaction and protecting against relay, replay, and man-in-the-middle attacks.

Supported Protocols and Credential Formats

Transaction processing supports both major presentment protocols and credential formats across four distinct combinations:

ISO/IEC 18013-5 with ISO mdoc (mso_mdoc): The verifier sends transaction data inside the requestInfo.transactionData map of an ISO 18013-5 DeviceRequest. The wallet returns transaction response elements (e.g. amount, currency, and tipAmount) nested inside a CBOR map under the transaction identifier within the standard namespace (ISO_18013_TRANSACTION_DATA_NAMESPACE) in DeviceSigned.nameSpaces, bound to the request via docRequestId.
ISO/IEC 18013-5 with SD-JWT VC (dc+sd-jwt): The verifier requests an SD-JWT VC within an ISO 18013-5 DeviceRequest. The wallet generates a Key Binding JWT (KB-JWT) where transaction processing response claims are placed under kbJwtResponseClaimName (along with doc_request_id).
OpenID4VP with SD-JWT VC (dc+sd-jwt): The verifier supplies transaction_data in the OpenID4VP authorization request. The wallet hashes the transaction payload and inserts transaction_data_hashes_alg and transaction_data_hashes (along with user input claims) directly into the SD-JWT KB-JWT payload.
OpenID4VP with ISO mdoc (mso_mdoc): The verifier supplies transaction_data in the OpenID4VP authorization request. The wallet places transaction evidence directly in DeviceSigned.nameSpaces under openId4VpMdocResponseNamespace (defaulting to identifier), returning top-level data elements for the computed hash (transactionDataHash), hash algorithm (transactionDataHashAlg), and user input (tipAmount).

Lifecycle & Verification

All transaction types expected to be processed or rejected must be registered in a DocumentTypeRepository.

Applicability (isApplicable): Validates that candidate credentials authorize the device key to sign under the protocol's designated namespace (ISO_18013_TRANSACTION_DATA_NAMESPACE for ISO 18013-5, or openId4VpMdocResponseNamespace for OpenID4VP) in the Mobile Security Object (MSO).
Generation (generateMdocResponseElements, generateSdJwtResponseClaims): Invoked during wallet presentment to populate device-signed elements or KB-JWT claims based on the transaction payload and optional TransactionUserInput.
Verification (verifyMdocResponse, verifySdJwtResponse): Invoked on the verifier side during document authentication to validate that returned amounts, currencies, user inputs, and transaction hashes match the requested transaction.

Parameters

PayloadT

type of the transaction-specific payload data.

displayName

human-readable transaction name.

identifier

unique transaction type identifier, corresponds to the type property in transaction data in OpenID4VP; all TransactionType objects must have distinct identifiers.

kbJwtResponseClaimName

if transaction processing results in any data, it will be inserted in key binding JWT using this claim name; all TransactionType objects must have distinct values.

iso18013RequestInfoIdentifier

transaction type to use in transactionData map in requestInfo map in ISO/IEC 18013-5 document request to represent this transaction data; all TransactionType objects must have distinct values.

openId4VpMdocResponseNamespace

namespace to use in deviceSigned namespace map in OpenID4VP response; defaults to identifier.

Constructors

TransactionType

constructor(displayName: String, identifier: String, kbJwtResponseClaimName: String = identifier, iso18013RequestInfoIdentifier: String = identifier, openId4VpMdocResponseNamespace: String = identifier)