Skip to main content

Verification Integration Flow

Sequence

Verification Scenario.png

Call verify/request (1) API to create a new proof verification, the invitiation_short_url resultat (2) can be embendeed in a QrCode (3) that can be scan from the user with the Dizme Wallet app (4).

The wallet will show the proof requested to the user. After the user accept to send the data a flow of credential verification will start (5) on "background". Event status of progression of the verification will be sent to the Customer Backend via callback api "verify/event" (6). With the verify/event the customer backend will receive also the data sent from the wallet.

At this point (7) on the backend can be done right away a check on the data received.

Customer will sent a verify/update to "COMPLETE" (8) the verification adding also information about the own check on the data received. Optionally can be added an info message to be shown to the user wallet.

The wallet will receive information about the result for this verification (9) and will evaluate the response (10).

DARS Api

verify/request

The /verify/request service allows you to ask for verifiable credentials to a user

In order to request verifiable credentials to a user, a proof template (or request) must be previously created for the own organization. The proof request can be configured using Dizme Studio (see documentation)

POST  /verify​/request
Request body:
{
  "business_code": "string",
  "allow_multiple_read": true,
  "request_uid": "string"
}
busines_code : business code of the proof template configured on Dizme Stack.
By example PROOF_01 business code

allow_multiple_read : true value consent to scan many time the same qrcode from several users

request_uid : must be set with an own generated unique identifier for the request, if the attribute is omitted, a unique identifier will be automatically generated 
Example Response body:
{
   "status_code": 100,
   "message_code": 400,
   "message": "Invitation Created!",
   "request_uid": "12345-12345-12345",
   "invitation_short_link": "https://agent.dizme.io/api/v1/invitation/12345-12345-12345"
}


status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
request_uid : the unique identifier of the request already sent or generated by the system.

invitation_short_link: url to be embended into ar qrcode/or to send to the user via other method (sms, email, webpage)

verify/update With this service an organization can complete a verification activity optionally adding the check result on the data received. Usually after a confirm verify with a success response an organization makes some business logic check or operation. Based on the result of this operation the organization can decide to confirm the success of the verification or the verification. Optionally can added a info message to be shown to the user or a subsequent credential offer link

POST /verify​/update

Request body:
{
  "presentation_id": "string",
  "status": true, /* COMPLETED - NEED_CHECK - CHECK_FAIL */
  "messages": [
    {
      "lang": "string",
      "body": "string"
      "title": "string
    },
   ],
  "availableActions":[
   {
    "action":"ISSUE"
    "data": {
      "credential_offer_link" : "...."
       }
    }
  ]
}


presentation_id : is a unique identifier for a specific outcome of a verification. This value will be received through the verify/event callback.

messages : this will be shown to the user when the wallet receive the result.

availableActions : possible next actions that can be request to the wallet.

status : 

COMPLETED - if the organization confirms a successful verification for credential
 Example for notification status in wallet

CHECK_FAIL - if the organization refuse/reject credential data
 Example for notification status in wallet

WAITING_ORG_CONFIRM - waiting for complete confirmation from the Customer BE.


descriptions : list of messages description in various language
Example Response body:
{
   "status_code": 100,
   "message_code": 400,
   "message": "Invitation Created!"
}
status_code : 100 success, 101 failure
message_code : internal message code for operation 
message : label for message of the operation


credential/offer

The service allows to create a credential offer. The offer can be sent through a pairwise connection (using connection_id).

```bash
POST /credential​/offer

Request body for Certified Credential:
{
  "request_uid": "string",
  "credential_def_refs": ["cred_id1","cred_id2",...], (optional)
  "vcs": [
          {
            "vc": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
              ],
              "id": "urn:uuid:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION (see below)",
              "type": [
                "VerifiableCredential",
                "OpenBadgeCredential"
              ],
              "name": "JFF x vc-edu PlugFest 3 Interoperability",
              "issuer": {
                "type": [
                  "Profile"
                ],
                "id": "did:key:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION FROM CONTEXT (see below)",
                "name": "Jobs for the Future (JFF)",
                "url": "https://www.jff.org/",
                "image": "https://w3c-ccg.github.io/vc-ed/plugfest-1-2022/images/JFF_LogoLockup.png"
              },
              "issuanceDate": "2023-07-20T07:05:44Z (THIS WILL BE REPLACED BY DYNAMIC DATA FUNCTION (see below))",
              "expirationDate": "WILL BE MAPPED BY DYNAMIC DATA FUNCTION (see below)",
              "credentialSubject": {
                "id": "did:key:123 (THIS WILL BE REPLACED BY DYNAMIC DATA FUNCTION (see below))",
                "type": [
                  "AchievementSubject"
                ],
                "achievement": {
                  "id": "urn:uuid:ac254bd5-8fad-4bb1-9d29-efd938536926",
                  "type": [
                    "Achievement"
                  ],
                  "name": "JFF x vc-edu PlugFest 3 Interoperability",
                  "description": "This wallet supports the use of W3C Verifiable Credentials and has demonstrated interoperability during the presentation request workflow during JFF x VC-EDU PlugFest 3.",
                  "criteria": {
                    "type": "Criteria",
                    "narrative": "Wallet solutions providers earned this badge by demonstrating interoperability during the presentation request workflow. This includes successfully receiving a presentation request, allowing the holder to select at least two types of verifiable credentials to create a verifiable presentation, returning the presentation to the requestor, and passing verification of the presentation and the included credentials."
                  },
                  "image": {
                    "id": "https://w3c-ccg.github.io/vc-ed/plugfest-3-2023/images/JFF-VC-EDU-PLUGFEST3-badge-image.png",
                    "type": "Image"
                  }
                }
              }
            },
            "mapping": {
              "id": "<uuid>",
              "issuer": {
                "id": "<issuerDid>"
              },
              "credentialSubject": {
                "id": "<subjectDid>"
              },
              "issuanceDate": "<timestamp>",
              "expirationDate": "<timestamp-in:365d>"
            },
            "selectiveDisclosure": {
              "fields": {
                "name": {
                  "sd": true
                }
              }
            }
          }
  ],
  "comment": "string"
}

Example for credential values :
Certified identity

request_uid : must be set with an own generated unique identifier for the request, if the attribute is omitted, a unique identifier will be automatically generated 

credential_def_refs : list of reference of the credentials to issue (optional)
vcs : json schema of the credential filled with the value to issue.

Example Response body:

{
  "status_code": 0,
  "message_code": 0,
  "message": "string",
  "request_uid": "string"
}

status_code : 100 success, 101 failure
message_code : internal message code for operation 
message : label for message of the operation
request_uid : the unique identifier of the request already sent or generated by the system.

Callback API

connection/notify The organization will receive this callback after a pairwise connection (previously requested) has been established. Note that in case of verify request or credential offer without connection, a pairwise connection is established before the verify or issue operation. This service is invoked even if a connection has been reused by the owner.

POST /owners​/connection​/notify

Request body:
{
  "connection_id": "string",
  "status": "string",
  "request_uid": "string",
  "reused": true
}

connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.

reused : true value if is an existent connection with user

status : “active”

request_uid : 
is a unique identifier of the request that triggered the connection (verify request, credential offer, connection offer)


Example Response body:
{
  "status_code": "100",
  "message_code": "0",
  "message": "Success!"
}

status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation

verify/confirmevent Upon invocation of this service, all the attributes requested in the verify request will be received.

POST/verification​```bash
POST​ /verify​/confirmevent
Request body:
{
  "organization_name": "string",
  "proof_business_code": "string",
  "request_uid": "string",
  "revealed_attributes": {},
  "unrevealed_attributes": {},
  "self_attested_attributes": {},
  "proof_request": {},
  "proof": {},
  "presentation_id": "string",
  "connection_id": "string"
}

example of revealed attribute :

revealed_attributes : {“attribute1”:”value”, “attribute2”:”value}
proof_business_code : business code of the proof template configured.
By example PROOF_01 is configured

request_uid : 
is a unique identifier of the verify request 

organization_name : name of the organization that require the proof

proof_request : raw value of the proof request
proof : raw value of the proof sent by the user wallet

presentation_id : is a unique identifier for a specific outcome of a verification. 

revealed_attributes : all the attributes that comes from credential with the value revealed 

self_attested_attributes : all the attributes that comes from self attested

unrevealed_attributes : all the attributes that comes from credential but without the value

Example Response body:
{
  "status_code": 100,
  "message_code": 0,
  "message": "Success!",
  "result": true,
  "send_response": false,
  "descriptions": [
    {
      "lang": "en",
      "message": "Verifica eseguita con successo"
    },
    {
      "lang": "it",
      "message": "Verify executed successfully"
    }
  ]
}

status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
result : result of the organization verification. The organization accept the data of the proof response 

send_response : 
true -  send the response status to the wallet user

result=true - if the organization confirms a successful verification for credential

result=false - if the organization refuse/reject credential data

false - don’t send the response to the wallet . Usually is used false when the organization accept the data from the proof response and need some other async operation to complete the verification


descriptions: text messages

confirm/issuecredential/offer/event

Send the confirm for an issued credential

POST /owners​/credential​/confirm_issuecredential/offer/event
Request body:
{
  "connection_id": "string",
  "request_uid": "string",
  "credential_def_id": "string",
  "tid": "string",
  "credential_exchange_id"status": "string"
}


connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.


credential_def_id : id of the credential issued

tid : transaction id of the issue

credential_exchange_id : is a unique identifier for a specific exchange  of credentials.

request_uid : 
is a unique identifier of the request that triggered the connectionoffer

(verifystatus:
request,READ 
credentialDOWNLOADED 
offer,REJECTED 
connection offer)FAILURE


Example Response body:
{
  "status_code": "100",
  "message_code": "0",
  "message": "Success!"
}


status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation

proof/discard

Forwarded the proof discard sent by the wallet owner

POST owners/proof/discard
Request body:
{
  "connection_id": "string",
  "request_uid": "string",
  "description": "string"
}


connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.

request_uid : 
is a unique identifier of the request that triggered the verification

description : description added from the wallet owner when reject the proof

Example Response body:
{
  "status_code": "100",
  "message_code": "0",
  "message": "Success!"
}


status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation

credential/discard

Forwarded the credential offer discard sent by the wallet owner. When a user receives a credential offer notification, can decide to refuse/reject the credential offered for some reason. By the rejection the organization receive this callback back to be informed about the user choice

POST owners/credential/discard
Request body:
{
  "connection_id": "string",
  "request_uid": "string",
  "credential_def_id": "string",
  "description": "string"
}

connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.

request_uid : 
is a unique identifier of the request that triggered the credential offer

credential_def_id : id of the credential rejected

description : description added from the wallet owner when reject the credential


Example Response body:
{
  "status_code": "100",
  "message_code": "0",
  "message": "Success!"
}

status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
Back to top