Userinfo API guide

The Userinfo API is used for profile sharing. This allows merchants to request the user's profile information as part of the payment flow.

The API follows the OIDC Standard.

To get access to user profile information, the merchant adds a scope parameter and initiates specific API calls.

The user will be asked to consent to sharing the information with the merchant as specified in the scope. If the user has not already consented to sharing all the specified information, he/she will be asked for any remaining consents before completing the payment flow.

In the Vipps app, they will be presented with a consent card. For example, Android (left) and iOS (right):

The consent card must be accepted before approving the payment or agreement in Vipps. It is not possible to complete the flow without consenting.

Once the flow is completed, the merchant can get the profile information from the GET:/userinfo/{sub}.

A user's consent to share information with a merchant applies across all Vipps MobilePay services. This is helpful, for example, if the merchant implements the Login API as part of the payment flow, they can use Vipps MobilePay to log the user in without the need for additional consents.

Scope

The scope determines what information the user is asked to share.

Scope	Description	User consent required
address	A list containing the user's addresses. The list always contains the home address from the National Population Register and can also include work address and other addresses added by the user in Vipps.	yes
birthDate	Birth date. Verified with BankID. ISO 8601 format (2022-12-31)	yes
email	Email address. The flag email_verified : true (or false) in the response indicates whether the email address is verified.	yes
name	First, middle and given name. Verified with the National Population Register.	yes
phoneNumber	Phone number. Verified when creating the Vipps or MobilePay account. MSISDN format (4712345678).	yes
nin	National Identity Number (NIN) (verified with National Population Register). Note, merchants need to apply for access to NIN. See Who can get access to NIN and how?.	yes

The scope can include any of the values above, separated by a space. Examples:

• phoneNumber
• email
• name address email
• name phoneNumber
• name birthDate
• name email nin

Sub

The sub is a unique identifier for a Vipps MobilePay user and relates to that user's consent to share information with a specific sales unit.

The sub is based on the user's NIN (National Identity Number). It is not a replacement for NIN or any other unique identifier for the user.

A user may have more than one sub for the same merchant, but there can only be one sub per sales unit (Merchant Serial Number). You cannot combine the sub for one MSN and the API keys for a different MSN.

The sub will not change if a user removes their consents, logs in again, and re-consents.

Please note: There are some special cases where the sub will change for a user:

• If a user deletes the Vipps MobilePay profile and creates a new one.
• If a user changes the phone number or creates a new user.

Flows

There are two main flows for getting user info:

• Through the payment APIs
• Through the Login API

Userinfo through payment APIs

Through the following payment APIs, you can request the user's consent to share their information:

• ePayment API: POST:/epayment/v1/payments
• Recurring API: POST:/recurring/agreements
• eCom API: POST:/ecomm/v2/payments

This is an illustration of a consent card and a payment screen. The user must complete both screens before the merchant can gain access to their profile information. It is not possible for the user to complete the payment without these steps.

Here follows a sequence diagram to illustrate the flow of steps.

Call-by-call guide for payment flow

Scenario: Complete a payment and get the user's name and phone number.

See HTTP headers for the standard headers that should be included.

1. Retrieve the access token with POST:/accesstoken/get.

   See: Access token API guide.

2. Specify the scope for your access request.

   Example using the POST:/payments endpoint from the ePayment API:

   {
     "amount":{
         "currency":"NOK",
         "value":2000
     },
     "customer":{
         "phoneNumber":4712345678
     },
     "paymentMethod":{
         "type":"wallet"
     },
     "profile":{
         "scope":"phoneNumber"
     },
     "reference":"acme-shop-123-order123abc",
     "returnUrl":"https://example.com/redirect?orderId=1512202",
     "userFlow":"WEB_REDIRECT"
   }

   Please note: If the email address that is delivered has the flag email_verified : false, this address should not be used to link the user to an existing account without further authentication. Such authentication could be to prompt the user to log in to the original account or to confirm the account linking by providing a confirmation link sent to the email address.

3. Make the API request that initiates the Vipps MobilePay payment or agreement. Include the scope in the body:

   • ePayment API: POST:/epayment/v1/payments
   • Recurring API: POST:/recurring/agreements
   • eCom API: POST:/ecomm/v2/payments

4. The user consents to the information sharing and completes the payment in Vipps.

5. Retrieve the sub, which identifies the user. The sub is a link between the merchant and the user and can be used to retrieve the user's details from GET:/userinfo/{sub}. The sub is based on the user's national identity number (NIN) and does not change (except in very special cases). See Who can get access to NIN and how?.

   The format of the sub is:

   "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944",

   Retrieve the sub by calling the API endpoint that provides information about the payment or agreement. For example:

   • ePayment API: GET:/epayment/v1/payments/{reference}
   • Recurring API: GET:/recurring/agreements/{agreementId}
   • eCom API: GET:/ecomm/v2/payments/{orderId}/details

6. To retrieve the user's information, call GET:/vipps-userinfo-api/userinfo/{sub} with the sub that was retrieved earlier.

   This endpoint returns the payload with the information that the user has consented to share. See below on how to construct the call.

   Please note: It is recommended to get the user's information directly after completing the transaction. There is a time limit of 168 hours (one week) to retrieve the consented profile data from GET:/userinfo/{sub}.

   This is to better support merchants that depend on manual steps/checks in their process of fetching the profile data. The merchant will get the information that is in the user profile at the time when they actually fetch the information. This means that the information might have changed from the time the user completed the transaction and the fetching of the profile data.

   Please note: The sub is added asynchronously, so if the API request in (5) above is made within milliseconds of the payment approval in the app, it may not be available. If that happens, simply make another request. See Polling guidelines for more recommendations.

Example request

This is an example based on the Recurring API.

See HTTP headers for additional standard headers that should be included.

To request the scope, add the scope to the initial POST:/recurring/agreements request.

For example:

{
  "phoneNumber":"4712345678",
  "interval": {
    "unit": "MONTH",
    "count": 1
  },
  "merchantRedirectUrl": "https://example.com/confirmation",
  "merchantAgreementUrl": "https://example.com/my-customer-agreement",
  "pricing": {
    "type": "LEGACY",
    "amount": 49900,
    "currency": "NOK"
  },
  "productDescription": "Access to all games of English top football",
  "productName": "Premier League subscription",
  "scope": "address name email birthDate phoneNumber"
}

Response:

{
  "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944",
  "birthdate": "2000-07-16",
  "email": "user@example.com",
  "email_verified": true,
  "nin": "10121550047",
  "name": "Ada Lovelace",
  "given_name": "Ada",
  "family_name": "Lovelace",
  "sid": "f26d25af56909b55",
  "phone_number": "4712345678",
  "address": {
    "street_address": "Suburbia 23",
    "postal_code": "2101",
    "region": "OSLO",
    "country": "NO",
    "formatted": "Suburbia 23\\n2101 OSLO\\nNO",
    "address_type": "home"
  },
  "other_addresses": [
    {
      "street_address": "Robert Levins gate 5",
      "postal_code": "0154",
      "region": "OSLO",
      "country": "NO",
      "formatted": "Robert Levins gate 5\\n0154 OSLO\\nNO",
      "address_type": "work"
    },
    {
      "street_address": "Summer House Lane 14",
      "postal_code": "1452",
      "region": "OSLO",
      "country": "NO",
      "formatted": "Summer House Lane 14\\n1452 OSLO\\nNO",
      "address_type": "other"
    }
  ],
  "accounts": [
    {
      "account_name": "My savings",
      "account_number": "12064590675",
      "bank_name": "My bank"
    }
  ]
}

Time limit

It is recommended to get the user's information directly after completing the transaction.

There is a time limit of 168 hours (one week) to retrieve the consented profile data from the /userinfo endpoint.

This is to better support merchants that depend on manual steps/checks in their process of fetching the profile data. The merchant will get the information that is in the user profile at the time when they actually fetch the information. This means that the information might have changed from the time the user completed the transaction and the fetching of the profile data.

If you attempt to retrieve the user's information after 168 hours, you will get an error.

Example response after expiration

If you use the eCom API and GET:/ecomm/v2/payments/{orderId}/details after 168 hours, the response will not contain the user's information.

"userDetails": {
  "bankIdVerified": 0,
  "email": "[Expired]",
  "firstName": "[Expired]",
  "lastName": "[Expired]",
  "mobileNumber": "[Expired]",
  "userId": "[Expired]"
}

Userinfo through Login API

Getting user consent through the Login API requires doing the full log-in flow, as described in the Login API guide.

Once the user is logged in, request consent with GET:/vipps-userinfo-api/userinfo/.

Provide the access token retrieved during the login session.

curl -X GET https://apitest.vipps.no/vipps-userinfo-api/userinfo/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
-H 'Vipps-System-Name: acme' \
-H 'Vipps-System-Version: 3.1.2' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \

To see the full login flow, see the Login API Quick start guide.