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 verification exchange record. This is the presentationExchangeId property of the record, not its id property.

    Example: 8e9c0a94-3b7d-4f2c-9d11-2f5a0b1c8d3e

Header Parameters

    X-SandboxOrgId stringrequired

    Optional. Unique identifier of the sandbox organisation to use for this request. When you send this header, the service runs the operation in the context of the named sandbox organisation, that is, against the wallet of that sandbox organisation and not against the main wallet of the organisation. Leave the header out to use the main wallet.

    The service reads this header only when you authenticate with a bearer access token. When you authenticate with an API key, the service takes the sandbox organisation from the API key and ignores this header. To run an API-key call in a sandbox organisation, bind the key to the sandbox organisation with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org instead.

    X-SubwalletId is the deprecated name of this header. The service continues to accept it, but X-SandboxOrgId wins if you send both headers.

    The sandbox organisation must exist, must belong to your organisation and must be deployed. An unknown identifier, an identifier of a sandbox organisation that is not deployed, and an identifier that belongs to a different organisation all make the call fail with HTTP 400.

    Example: 6889e1a4c5b2f30001a3d710

Body

required

The body must hold response, vp_token, or both. The field names are case-sensitive and lowercase. The digital wallet ignores all other fields. Do not send the presentation submission: the wallet derives it from the DCQL query and from the structure of vp_token.

For responseMode = dc_api.jwt, the wallet searches for the JWE in response and in vp_token, and it also unwraps a JSON string that holds one of these keys. For responseMode = dc_api, the wallet reads vp_token first and falls back to response.

    anyOf
    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​

The digital wallet processed the DC API response. The body is the answer of the wallet, forwarded byte-for-byte.

This body is not the verification history shape that the other verifier endpoints return. It is the raw verification record of the digital wallet. The token properties use snake_case (vp_token_request, vp_token_response, …) and organisationId is the identifier of the wallet deployment, not of the gateway organisation. To read the record in the usual shape, call GET /v3/config/digital-wallet/openid/sdjwt/verification/history/{presentationExchangeId} after this call.

Response Headers
    Schema
      id uuidrequired

      Identifier of the verification record in the digital wallet. This value equals the presentationExchangeId of the gateway.

      organisationId uuidrequired

      Identifier of the organisation in the digital wallet deployment.

      presentationDefinitionId uuidnullable

      Identifier of the presentation definition that this verification uses.

      vp_token_request_state stringnullable

      State value of the Authorization Request.

      vp_token_request stringnullable

      Full Authorization Request. This is a signed JWT, or a URI with the request parameters.

      vp_token_qr_code stringnullable

      Authorization Request URI for a QR code or a deep link. Empty for DC API response modes.

      vp_token_response string[]nullable

      Verifiable Presentation tokens that the wallet sent.

      presentationSubmission objectnullable

      Presentation Submission that the server derived from the DCQL query and the structure of the VP Token.

      property name* anynullable

      Presentation Submission that the server derived from the DCQL query and the structure of the VP Token.

      status stringrequired

      Possible values: [request_sent, request_received, presentation_acked]

      Lifecycle status of the verification exchange. The value is presentation_acked after a good DC API response.

      verified boolean

      Result of the verification of the Verifiable Presentation.

      holder objectnullable

      Metadata about the holder, for example the name from the client metadata.

      property name* anynullable

      Metadata about the holder, for example the name from the client metadata.

      presentation object[]nullable

      Decoded credentials that the holder presented.

      presentationValidity object[]nullable

      Validation result for each credential in the presentation.

      credentialExchangeId stringnullable

      Identifier of the credential issuance exchange that this verification started.

      transactionData objectnullable

      Transaction data that the holder approved.

      property name* anynullable

      Transaction data that the holder approved.

      transactionDataBase64 stringnullable

      Base64url encoding of the transaction data that the Authorization Request holds.

      nonce stringnullable

      Cryptographic nonce of the Authorization Request.

      responseType stringnullable

      Possible values: [vp_token, id_token, device_response]

      OAuth 2.0 response type of the Authorization Request.

      idToken stringnullable

      OpenID Connect ID Token from the holder.

      idTokenDecoded objectnullable

      Decoded payload of the ID Token of the holder.

      property name* anynullable

      Decoded payload of the ID Token of the holder.

      clientIdScheme stringnullable

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

      Client ID scheme of the Authorization Request.

      responseMode stringnullable

      Possible values: [direct_post, direct_post.jwt, dc_api, dc_api.jwt, iar-post, iar-post.jwt]

      Response mode of the Authorization Request. This endpoint accepts only dc_api and dc_api.jwt.

      verifierAttestation stringnullable

      Verifier Attestation JWT that the server sent to the holder.

      directPostRedirectUri stringnullable

      URI that the wallet opens after it posts the Authorization Response. Not used for DC API response modes.

      encryptionPrivateKey stringnullable

      Internal field of the digital wallet. Do not use it. The wallet deletes the one-shot response encryption key after it decrypts a dc_api.jwt response.

      requiresEncryption booleannullable

      true when the wallet must encrypt the Authorization Response as a JWE.

      iarAuthSession stringnullable

      Session identifier for the Interactive Authorisation Request flow. Empty for DC API flows.

      version stringnullable

      Possible values: [draft_14, draft_18, draft_23, version_01, iso18013_7_annex_c]

      OpenID4VP profile version that the presentation definition uses.

      files object[]nullable

      Files that the verification made, for example signed and unsigned PDF documents.

      dcApiRequest objectnullable

      Request object for the W3C Digital Credentials API, with one shape for Chrome and one for Safari.

      property name* anynullable

      Request object for the W3C Digital Credentials API, with one shape for Chrome and one for Safari.

      dcApiProtocol stringnullable

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

      Exchange protocol identifier for the W3C Digital Credentials API.

      signatureStamp booleannullable

      true when the signed PDF holds a visible signature stamp.

      signatureCoordinate integer[]nullable

      Possible values: >= 4, <= 4

      Page coordinates of the signature in the signed PDF, as [x1, y1, x2, y2] in points.

      dataAgreement objectnullable

      Data agreement that gives the terms for this verification exchange.

      property name* anynullable

      Data agreement that gives the terms for this verification exchange.

      requestExpired boolean

      true when the exp claim of vp_token_request is in the past.

      createdAt numberrequired

      Unix timestamp in seconds when the wallet made this record.

      updatedAt numberrequired

      Unix timestamp in seconds when the wallet last changed this record.

    Loading...
    Last updated on