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
- Scan the QR Code: Use a QR code scanner or an optical reader to read the QR code.
- Extract the string: Extract the string contained in the QR code.
- 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
Postman Collection¶
To make it easier to integrate to our API, we have created a Postman collection you can use to generate a BankId OIDC Token and test QR codes as described above. Read here