Skip to main content

Receive DC API verification response

POST 
/v2/config/digital-wallet/openid/sdjwt/verification/history/:presentationExchangeId/receive

Receives an OpenID4VP Authorization Response delivered over the W3C Digital Credentials API (DC API) transport for a previously created verification request.

The verifier frontend invokes the browser's navigator.credentials.get() with the request returned in dcApiRequest. The browser routes the request to the holder's wallet, which produces a credential response. The frontend forwards that response to this endpoint.

This endpoint is a transparent gateway: it authenticates the caller, looks up the verification record by presentationExchangeId, then proxies the request body byte-for-byte to the underlying digital wallet deployment, where JWE decryption (when responseMode is dc_api.jwt), VP Token parsing per OID4VP 1.0 §8.1, DCQL structure validation, and persistence are performed. The wallet's response body and HTTP status are returned to the caller unchanged.

Use this endpoint only when the verification request was created with responseMode set to dc_api or dc_api.jwt. For direct_post and direct_post.jwt flows the wallet posts the response directly to the verifier's redirect_uri and this endpoint is not used.

Request​

Path Parameters

    presentationExchangeId stringrequired

    Unique identifier of the presentation exchange record tracking a single OpenID4VP verification lifecycle.

Body

required

Body must contain exactly one of the two fields below. Field names are case-sensitive (lowercase, snake_case). Any additional fields are silently ignored downstream; the presentation submission is not sent; it is derived downstream from the DCQL query and the structure of vp_token.

    oneOf
    response stringrequired

    For responseMode = dc_api.jwt: JWE compact serialization (five base64url segments separated by .) returned by the wallet. The downstream wallet decrypts it with the encryption key minted for this verification record and extracts vp_token from the decrypted payload.

    For responseMode = dc_api (alternative form): a JSON-encoded string whose decoded form is {"vp_token": { ... }}.

Responses​

Wallet processed the DC API response. Body is the wallet's response forwarded verbatim; the updated verification record, including dcApiRequest, dcApiProtocol, parsed presentation, and verification status.

Response Headers
    Schema
      presentationExchangeId stringrequired

      Unique identifier for the verification exchange record, tracking the full lifecycle of a single OpenID for Verifiable Presentation (OpenID4VP) verification request.

      id stringrequired

      Unique identifier for this verification exchange record. Same value as presentationExchangeId.

      vpTokenQrCode stringrequired

      OpenID4VP Authorization Request URI encoded for QR code display or deep link. The holder's wallet scans or clicks this to initiate the presentation flow. Empty when using DC API response modes (dc_api or dc_api.jwt).

      vpTokenRequestState stringrequired

      State parameter for the OpenID4VP Authorization Request, used to correlate the request with the response.

      vpTokenRequest stringrequired

      Full OpenID4VP Authorization Request URI or payload. Empty when using DC API response modes (dc_api or dc_api.jwt).

      presentationSubmission objectrequired

      Wrapper containing the Presentation Submission object received from the holder's wallet.

      presentation_submission objectrequired

      DIF Presentation Exchange Submission object mapping the holder's credentials to the verifier's requirements.

      definition_id stringrequired

      Identifier of the Presentation Definition that this submission fulfills.

      descriptor_map object[]required

      Array of Descriptor Map entries mapping each requested credential to its location in the Verifiable Presentation.

    • Array [
      • format stringrequired

      Credential format of the matched credential (e.g. jwt_vc_json, dc+sd-jwt, mso_mdoc).

      id stringrequired

      Identifier of the Input Descriptor from the Presentation Definition that this entry satisfies.

      path stringrequired

      JSONPath expression pointing to the Verifiable Credential within the Verifiable Presentation token.

      path_nested object

      Nested path descriptor for credentials wrapped in envelope formats (e.g. JWT inside a VP JWT).

      format stringrequired

      Credential format of the nested credential (e.g. jwt_vc_json, dc+sd-jwt, mso_mdoc).

      id stringrequired

      Identifier of the Input Descriptor from the Presentation Definition that this nested entry satisfies.

      path stringrequired

      JSONPath expression pointing to the credential within the nested envelope.

    • ]
      • id stringrequired

      Unique identifier for this Presentation Submission.

      status stringrequired

      Possible values: [request_sent, request_received, presentation_acked]

      Lifecycle status of the verification exchange:

      1. request_sent: The OpenID4VP Authorization Request has been created and is waiting for the holder.
      2. request_received: The holder's wallet has received/scanned the Authorization Request.
      3. presentation_acked: The holder has submitted the Verifiable Presentation and the verifier has processed it.
      verified booleanrequired

      Result of verifying the Verifiable Presentation: validates cryptographic signatures, credential status, and the Presentation Submission against the Presentation Definition.

      createdAt numberrequired

      Unix timestamp (in seconds) when this verification record was created.

      updatedAt numberrequired

      Unix timestamp (in seconds) when this verification record was last modified.

      presentationDefinitionId stringrequired

      Identifier of the presentation definition used for this verification request.

      openIdOrganisationId stringrequired

      Identifier of the OpenID4VP organisation that initiated this verification request.

      holder objectrequired

      Contains the metadata describing a holder. For e.g. Name, location, logo e.t.c

      name stringrequired

      Identifier of the holder. For .e.g. DID or Name obtained from client metadata if available.

      walletUnitAttestation string

      Wallet Unit Attestation credential presented by the holder during the verification flow.

      walletUnitAttestationPoP string

      Proof of Possession for the holder's Wallet Unit Attestation.

      walletUnitAttestationVerified boolean

      Indicates whether the holder's Wallet Unit Attestation was successfully verified.

      presentation object[]

      Array of decoded credential objects presented by the holder.

      vpTokenResponse string[]required

      Array of Verifiable Presentation JWTs received from the holder.

      transactionData object

      Transaction data confirmed by the holder during the presentation flow.

      property name* any

      Transaction data confirmed by the holder during the presentation flow.

      transactionDataBase64 string

      Base64-encoded transaction data included in the presentation.

      presentationValidity object[]

      Array of validation results for each credential in the presentation, including signature verification, expiry checks, and revocation status.

      walletUnitValidity object[]

      Array of validation results for the holder's Wallet Unit Attestation.

      clientIdScheme string

      Possible values: [redirect_uri, did, verifier_attestation, x509_san_dns]

      Client ID scheme used by the verifier in the OpenID4VP Authorization Request.

      directPostRedirectUri string

      URI the wallet redirects to after posting the Authorization Response. Empty when using DC API response modes (dc_api or dc_api.jwt).

      responseMode string

      Possible values: [direct_post, direct_post.jwt, dc_api, dc_api.jwt]

      OpenID4VP response mode determining how the Authorization Response is delivered:

      • direct_post: Response sent via HTTP POST to the verifier's redirect_uri without encryption.
      • direct_post.jwt: Response sent via HTTP POST encrypted as a JWE.
      • dc_api: Response delivered over the W3C Digital Credentials API transport without JWE encryption. Compatible with both signed and unsigned dcApiRequestType values.
      • dc_api.jwt: Response delivered over the W3C Digital Credentials API transport encrypted as a JWE.
      verifierAttestation string

      Verifier Attestation JWT sent to the holder, proving the verifier's authorization.

      individualId string

      Identifier of the individual the verification request was sent to.

      mapperId string

      Mapper identifier linking the verification to an external individual record.

      dataAgreement object

      Data agreement referencing the terms governing this verification.

      nonce string

      Cryptographic nonce used in the OpenID4VP Authorization Request to ensure freshness and prevent replay attacks.

      dcApiProtocol string

      Possible values: [openid4vp-v1-unsigned, openid4vp-v1-signed]

      Digital Credentials API exchange protocol identifier returned when the presentation definition is configured for DC API response modes. Identifies the protocol variant used with the W3C Digital Credentials API (navigator.credentials.get()):

      • openid4vp-v1-unsigned: The Authorization Request is passed unencrypted to the browser's DC API. The browser can inspect the request for risk analysis. Use for development/testing only.
      • openid4vp-v1-signed: The Authorization Request is signed by the verifier's key and passed as an opaque string to the browser's DC API. Provides verifier authentication. Recommended for production. Only present when responseMode is dc_api or dc_api.jwt.
      dcApiRequest object

      Request object for the W3C Digital Credentials API, structured for browser invocation via navigator.credentials.get(). Contains browser-specific request formats for Chrome and Safari. Only present when responseMode is dc_api or dc_api.jwt.

      chrome object

      Digital Credentials API request format for Chromium-based browsers. Uses the providers structure per the W3C Digital Credentials API specification.

      digital object

      Digital credential request options for Chromium-based browsers.

      providers object[]

      Array of credential request providers, each specifying a protocol and request data.

    • Array [
      • protocol string

      Digital Credentials API exchange protocol identifier (e.g. openid4vp-v1-signed, openid4vp-v1-unsigned).

      request object

      The OpenID4VP Authorization Request payload. Structure varies by protocol:

      • For openid4vp-v1-signed: Contains { "request": "<signed-JWT>" }, a JWT signed by the verifier's key.
      • For openid4vp-v1-unsigned: Contains the full Authorization Request object with client_metadata, dcql_query, nonce, response_mode, response_type.
      property name* any

      The OpenID4VP Authorization Request payload. Structure varies by protocol:

      • For openid4vp-v1-signed: Contains { "request": "<signed-JWT>" }, a JWT signed by the verifier's key.
      • For openid4vp-v1-unsigned: Contains the full Authorization Request object with client_metadata, dcql_query, nonce, response_mode, response_type.
    • ]
      • safari object

      Digital Credentials API request format for Safari-based browsers. Uses the requests structure.

      digital object

      Digital credential request options for Safari-based browsers.

      requests object[]

      Array of credential requests for Safari, each containing data and protocol.

    • Array [
      • data string

      JSON-stringified Authorization Request payload (Safari's DC API expects a string, not an object).

      Decoding it yields the same structure that Chrome receives in request:

      • For openid4vp-v1-signed: { "request": "<signed-JWT>" }.
      • For openid4vp-v1-unsigned: the full inline Authorization Request object (response_type, response_mode, nonce, dcql_query, client_metadata, …).
      protocol string

      Digital Credentials API exchange protocol identifier (e.g. openid4vp-v1-signed, openid4vp-v1-unsigned).

    • ]
      • requiresEncryption boolean

      Indicates whether the OpenID4VP Authorization Response must be encrypted as a JWE. true when responseMode is direct_post.jwt or dc_api.jwt. false when responseMode is direct_post or dc_api.

      signatureStamp boolean

      When false, the signature stamp is hidden in signed PDFs.

      signatureCoordinate number[]

      Possible values: >= 4, <= 4

      Coordinates for signature placement in signed PDFs as [x1, y1, x2, y2].

      files object[]

      List of files generated during the verification, including signed and unsigned PDF documents.

    • Array [
      • credentialId string

      Identifier of the credential associated with this file.

      error stringnullable

      Error code if signing failed, null otherwise.

      errorDescription stringnullable

      Detailed error message if signing failed, null otherwise.

      signedFile uri

      URL of the signed PDF file.

      unsignedFile uri

      URL of the unsigned PDF file.

    • ]
    Loading...
    Last updated on