Skip to content

Integration API

This page desribes how a merchant can use our Merchant API in order to request user details through the sessionId in a QR code.

'VisLeg' is the internal name we use for the Id card in BankId App product.

Flow overview

The diagram bellow illustrates the flow to obtain the data.

    participant m as Merchant
    participant b as BankID OIDC
    participant v as VisLeg

    m->> m: Scan QR-Code to Retrieve SessionId
    m->> b: Request BankID OIDC token
    b-->> m: Obtain access token
    m->> v: Request session detail with BankID access token and sessionId
    v -->> m: Obtain session detail

Detailed API swagger file can be found here

Merchant SessionId Request

In order to retrieve user data through a QR code the following are required:

Getting a SessionId from the QR code

  1. Scan the QR Code: Use a QR code scanner or an optical reader to read the QR code.
  2. Extract the string: Extract the string contained in the QR code.
  3. Verify the string: Verify that the string starts with "VisLeg". If not then disgard.

You should now have a valid SessionId that should look something like this: "VisLeg-9fa44f41-ce68-4f03-bc1a-498b00cf5fec".

Example of a genuine QR code

Image Title

Retrieving user data using SessionId and Authorization Token

Example Request

    &Authorization=Bearer <AuthorizationToken>
    &Payload={"SessionId": "<SessionId>"}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "age": int

The response will only return the data the merchant has a need for. If a merchant only needs Age of a user, the rest of the fields will be empty.

If a Merchant has occassions where more or less data is required for certain transactions, this should be done by changing Scope when getting an Authorization Token read more here.

Getting Test QR codes

For testing purposes, you can use /api/merchant/qrtest/{userNuber} to generate QRCodes that can be scanned. The userNumber is to be one of the pre-defined users bellow.

List of valid test users

User Number Name Gender Dob ( Age
1 EDGAR HETLAND MALE 1980-09-02 43
3 JAKOB HALVORSEN MALE 2010-03-05 14
4 NORA SOLBERG FEMALE 2005-09-14 18

Example Request

curl -X 'GET' \
'{UserNumber}' \
-H 'accept: application/json' \
-H "Authorization: Bearer <ACCESS_TOKEN>"

Example response

HTTP/1.1 200 OK
Content-Type: application/json

"qrCode": "string",
"ttl": 0,
"ts": 0