Requesting Authorization for Transactions

Use Procivis One to make authorization requests with transaction data. This is represented by transaction_data in OpenID4VP.

Overview

Procivis One is a generic verifier for these transactions and does not create the signature itself. It formats the transaction details you provide into a request the holder's wallet can render and understand, then confirms cryptographically that the holder reviewed and approved that exact request with a valid credential. You use the resulting proof result to carry out the actual transaction (for example, creating the QES) with your signing provider, outside of Procivis One.

Prerequisites

An instance of transactionDataProvider must be configured. Each provider type enables one particular kind of transaction data. See Configuring OpenID4VP for verifiers - Transaction data.

Making a Request

To make a request, include a transactionData array when creating a proof request.

POST /api/proof-request/v1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <TOKEN>

{
  "proofSchemaId": "{{UUID}}",
  "protocol": "OPENID4VP_FINAL1",
  "transactionData": [
    {
      "type": "QES_APPROVAL",
      "credentialSchemaIds": [
        "{{UUID}}"
      ],
      "data": {
        "numSignatures": 1,
        "signatureQualifier": "eu_eidas_qes",
        "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1",
        "documentInfos": [
          {
            "label": "Example Contract",
            "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
            "hashType": "sodr"
          }
        ]
      }
    }
  ],
  "transport": [
    "HTTP"
  ],
  "verifier": "{{IDENTIFIER-UUID}}"
}

• type — This must reference a configured instance of transactionDataProvider.
• credentialSchemaIds — Reference your own (Procivis One) schema definitions for the credentials that may approve this transaction. The system resolves these into the credential_ids values sent to the wallet. This is distinct from the opaque, per-query credential_ids defined by OpenID4VP/CSC itself, which the wallet and holder never see under this name.
• data — Transaction data for the provider referenced in type. Scoped per type — see Transaction types.

Transaction types

QES Approval

For QES_APPROVAL type transactions, data follows the CSC qesApprovalRequest structure (CSC data model bindings §7.1), minus type and credential_ids, which Procivis One adds automatically.

Field	Presence	Description
hashAlgorithmOID	Required	Hash algorithm (OID) for document hashes and the SD-JWT VC approval binding. mdoc credentials always use SHA-256 regardless of this setting.
numSignatures	Required	Number of signatures being approved.
documentInfos	Required	One entry per document; see below.
credentialID / signatureQualifier	Conditional	At least one is required, identifying the certificate or certificate class.
locations	Optional	RSSP locations (RFC 9396).

Documents and hashType

Each documentInfos entry requires a hash: a standard base64-encoded (padded) hash of the document, computed by the caller. Procivis One does not fetch or hash document content; it only handles the hash values you provide.

hashType indicates what was actually hashed:

• sodr — hash of the original document, before any signature-related formatting.
• sdr — hash of the document after formatting (for example, a PDF with the signature dictionary already inserted, but not yet signed).
• dtbsr — (default if hashType is omitted) hash of the data actually submitted to the signature algorithm.

sdr and dtbsr depend on signature-format and RSSP-specific formatting rules. sodr is the simplest choice for testing.

Other optional fields (label, access, href, checksum) are passed through to the wallet for display and are not used in verification.

Supported values

hashAlgorithmOID and signatureQualifier are both closed sets, and any other value is rejected at validation time.

hashAlgorithmOID recognizes the following OIDs as well-formed values, but currently only supports SHA-256. Using non-supported OIDs results in rejection at validation.

Algorithm	OID	Status
SHA-256	2.16.840.1.101.3.4.2.1	Supported
SHA-384	2.16.840.1.101.3.4.2.2	Not supported
SHA-512	2.16.840.1.101.3.4.2.3	Not supported

signatureQualifier accepts: eu_eidas_aes, eu_eidas_qes, eu_eidas_aeseal, eu_eidas_qeseal, eu_eidas_aesqc, eu_eidas_aesealqc, za_ecta_aes, za_ecta_oes.

What happens after the request is created

Creating the proof request assembles and sends the transaction data, and the approval happens through the normal OpenID4VP presentation exchange:

1. Procivis One assembles the request. It takes your data object, adds type (the CSC transaction data type identifier) and credential_ids (derived from credentialSchemaIds), and encodes the result as the transaction_data value in the OpenID4VP authorization request sent to the holder's wallet. No hashing happens at this stage; any document hashes in documentInfos must already be set on the way in.

2. The wallet renders the request to the holder. The wallet displays the document labels and other details so the holder can review exactly what they're being asked to approve before presenting a credential.

3. The holder approves, and the wallet binds the approval to the credential. The wallet hashes the transaction data it received and embeds the result in the presentation using that credential format's native holder binding: a claim in the Key Binding JWT for SD-JWT VC, or a signed data element for mdoc. This cryptographically ties this credential to this exact set of documents.

4. Procivis One verifies the presentation. It recomputes the expected hash from the original transaction data using the same format-specific method, and compares it against what the wallet returned. A mismatch, or a credential that doesn't satisfy the request's schema and validity checks, results in the presentation being rejected.

5. The result is available to you. The proof request status reflects the outcome. Procivis One does not create the actual signature. Instead, you use this result as authorization to proceed with the transaction (for example, requesting the QES from your RSSP) off-platform.