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.

sequenceDiagram
    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:

• SessionId
• Authorization Token (Read here on how to obtain)

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

Retrieving user data using SessionId and Authorization Token

Example Request

POST https://visleg-test-merchantservice-cnhvehb0cvdgggah.z01.azurefd.net/api/merchant/session
    &Authorization=Bearer <AuthorizationToken>
    &Payload={"SessionId": "<SessionId>"}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "documentPhoto":"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 (yyyy.mm.dd)	Age
1	EDGAR HETLAND	MALE	1980-09-02	43
2	ANNETTE INGVILD BERGAN	FEMALE	1994-09-02	29
3	JAKOB HALVORSEN	MALE	2010-03-05	14
4	NORA SOLBERG	FEMALE	2005-09-14	18

Example Request

curl -X 'GET' \
'https://visleg-test-merchantservice-cnhvehb0cvdgggah.z01.azurefd.net/api/qrtest/{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
}