Skip to content
/
Services Callback
Last updated

Services CallBack

To receive a response after using the init issuance and init verification APIs, it is necessary to define an endpoint and specify it in the callback parameter within both services.

Verification CallBack

When using the verification API, it is possible to receive the results of the verification process automatically via a callback. The callback_url parameter specifies the URL where the verification results will be sent, providing access to the Wallet user’s presented claims.

To enable this, you must create a callback endpoint and provide its URL in the API request using the callback_url field. Once the verification process is completed, the results will be sent to this endpoint.

Key points of the callback:

  • Must be a POST endpoint, meaning that the URL receiving the callback must accept HTTP POST request.
  • Receives a JSON body containing verification results.
  • Even if the request includes multiple credentials (verification_template_ids), only one callback is sent with all results, avoiding multiple requests.

Example JSON Callback

{
   "state" : "123456789012",
   "code": "abc123",
   "tokens": {
       "1": {
           "token": "eyJhbGciOiJIfUzI1NiIsInR5cCI6IkpXVCJ9...",
           "status": "COMPLETED"
       },
       "2": {
           "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
           "status": "FAILED"
      }
   }
}

Fields Description

  • state: value passed when calling the API; defaults to none if not provided.

  • code: unique code returned during verification initialization; used for additional security check.

  • tokens: dictionary where keys are verification_template_ids of credentials and values contain:

    • status: human-readable verification status; if not "COMPLETED", the verification is considered failed (KO).
    • token: JWT (JSON Web Token) of the verification (to be decoded), including:
      • iss: base URL of the service that issued the JWT.
      • jwks_uri: endpoint to fetch the issuer’s public keys.
      • vp_token: token sent by the app (e.g., mdoc/sdjwt).
      • verification_id: unique ID of the verification.
      • presented claims: the actual verified data.

Issuance Callback

It is possible to set a callback also for the issuance service.

The issuance callback is sent for each requested credential. If the issuance request includes multiple credentials (each associated with a different template_id), a separate callback will be generated for each credential.

{
  "state": "1234567890",
  "code": "abc123",
  "template_id": 1,
  "status": "Issued",
  "completed": true

}

Parameters descrpition:

  • state: the state value passed during initialization (init); if not specified, defaults to none.

  • Code: the security code returned during initialization; used for an additional security check (double security check).

  • template_id: the identifier of the processed credential template.

  • status: the status of the credential. If the value is different from "Issued", the issuance is considered failed (KO).

  • completed: a boolean indicating whether the interaction process between the Gateway and the wallet has finished (true) or is still in progress (false).

Previous page