Staging

How to integrate Hypersign KYC in your test environment

Staging Widget Base URL : https://hypersign-kyc-widget.netlify.app

The Hypersign KYC widget can be configured and incorporated in just a few minutes. You'll need to generate a Widget URL and insert it into a DOM element. Additionally, you can monitor events triggered by the widget on your webpage to showcase either success or failure. Once the user completes the KYC process successfully, you'll receive an idToken, which can be utilized to request the user's data/credentials from the KYC server.

The Widget URL has three query params:

pr: Presentation Query Request (base64 encoded)
kycAccessToken: KYC Access Token
ssiAccessToken: SSI Access Token

The final Widget URL format would look something like this:

https://hypersign-kyc-widget.netlify.app?kycAccessToken=${kycAccessToken}&ssiAccessToken=${ssiAccessToken}&pr=${base64EncodedPr}

Let's go ahead and get vaules for each of these query params. We will start with Presentation Query Request

1. Presentation Request

The Presentation Query request is a way to request user's credential from their data vault. The presentation query request is implemented based on W3C Verifiable Presentation Request v0.2 Specification - that means its being widely adopted in the SSI ecosystem.

Below is the sample presentation query request object:

{
    "query": [
        {
            "type": "QueryByExample",
            "credentialQuery": [
                {
                    "example": {
                        "type": "PersonhoodCredential",
                        "credentialSchema": {
                            "id": "sch:hid:testnet:z6Mkvtd73dDgg7HU8wLCmXbe2RAHPAU1Ex1VUXCFtPV7u36i:1.0"
                        }
                    },
                    "trustedIssuer": [
                        {
                            "required": true,
                            "issuer": "did:hid:testnet:zCyAz2wfKjAaWE4FW75KxpZh2wuo9kRAUZyV2xEe93cKr"
                        }
                    ]
                }
            ]
        },
        {
            "type": "QueryByExample",
            "credentialQuery": [
                {
                    "example": {
                        "type": "PassportCredential",
                        "credentialSchema": {
                            "id": "sch:hid:testnet:z6MkgMXXQL7YD7BufNLbjrwueoj4nmih9xujJ6aozJDmzFWx:1.0"
                        }
                    },
                    "trustedIssuer": [
                        {
                            "required": true,
                            "issuer": "did:hid:testnet:zCyAz2wfKjAaWE4FW75KxpZh2wuo9kRAUZyV2xEe93cKr"
                        }
                    ]
                }
            ]
        }
    ],
    "reason": "<Provide a vaild reason>",
    "issuerDID": "<Provide Issuer DID>",
    "issuerDIDVerificationMethod": "<Provide Issuer DID Verification Method>",
    "domain": window.location.href,
    "logoUrl": "<Your Logo Url>"
}

Reason: Please furnish a legitimate justification for why you are seeking access to user data. This information will be displayed on the consent screen for users to review and authorize your app to access their data. Max 110 chars are supported.
IssuerDID: Kindly contact Hypersign Admin
IssuerDIDVerificationMethod: Kindly contact Hypersign Admin
LogoUrl: Provide a URL for the monologue that users can view on the consent screen. See the example widget consent screen for reference.

Keep rest of the fields in the query as it is.

Once presentation query request object is ready, we need encode it in base64 string so that we can pass it in Widget URL.

const presentationRequest = {
   "query": [...],
   "reason": "The verifier app need access of your data",
   "issuerDID": "did:hid:testnet:3d11e40f-2250-4846-bd23-bfb58cf4eea5",
   "issuerDIDVerificationMethod": "did:hid:testnet:3d11e40f-2250-4846-bd23-bfb58cf4eea5#key-1",
   "domain": window.location.href
   "logoUrl": "https://i.ibb.co/xmxv8kw/Screenshot-2024-03-12-at-3-18-37-PM.png"
}
// stringifying it
const presentationRequestStr = JSON.stringify(presentationRequest)
// converting it in base64 string
const base64EncodedPr = btoa(presentationRequestStr)

Here I am using btoa utility function in browser to convert stringified presentation request object to base64 string.

2. KYC Access Token

Kindly contact Hypersign Admin.

3. SSI Access Token

Kindly contact Hypersign Admin.

You can invoke the Hypersign KYC widget through popup from your page

const widgetUrl = `https://hypersign-kyc-widget.netlify.app
?kycAccessToken=${kycAccessToken}&ssiAccessToken=${ssiAccessToken}&pr=${base64EncodedPr}`

window.open(widgetUrl, 'Popup Window', 'width=850,height=870');

Listening to events

You can listen to events thrown by the widget to get the result of verification.

window.addEventListener('message', function (event) {
    if (event.origin === 'https://hypersign-kyc-widget.netlify.app') {
        console.log('Received message from popup:', event.data);
        // make sure to parse the data before use
        const data = JSON.parse(event.data)
        
        // we send these 3 vaules: 
        // status = success / fail, 
        // idToken = you will use this token to extract user's data
        // message = a simple message (if any)
        const { status, idToken, message} = data;
        if (status === 'success') {
            console.log('Successfully finished the KYC')
        }
        else if (status === 'fail') {
            console.log('Failed to finish KYC')
        }
    }
});

Extracting User Data

Once you receive the idToken, you can query the KYC service to extract user data.

Staging KYC service Request:

KYC service URL:

https://ent-4c71874.api.cavach.hypersign.id/api/v1/e-kyc/verification/user-consent?idToken=${idToken}

Method:

GET

Headers:

'Authorization': 'Bearer ' + ${kycAccessToken}
'content-type': 'application/json'

Demo

Try Demo Now: https://hypersign-kyc-demo.netlify.app/

PreviousIntegrations NextIntroduction

Last updated 1 month ago