Skip to main content

Userinfo API guide

The Userinfo API enables merchants to request verified user profile information through a consent-driven process integrated with payment flows. This guide explains how to implement profile sharing in your applications using the Userinfo API.

Keep in mind:

  • Profile data is available for 168 hours (1 week) after the initial request. See Time limit for data access.
  • The shared information must be handled in accordance with GDPR requirements. See our privacy terms.

How to get profile information​

tip

See the quick start guide to run through the complete flow.

Step 1 - Request consent​

To request access to user profile information as part of a payment flow, add the scope property to the API request that initiates your flow. Check the API spec for exact details:

The options for scope include: address, birthDate, email, name, phoneNumber, and nin (in special cases).

{
  "scope": "name phoneNumber address birthDate"
}'

See scope for more details.

The user will be prompted to give consent to sharing the corresponding information. If they have previously consented to sharing some details within the time period, these will not be requested again.

The consent card must be accepted before the user can approve the payment or agreement in the Vipps Vipps or MobilePay MobilePay app. If the user does not provide consent, the payment or agreement will fail.

Step 2 - Get the sub​

After the payment or agreement is approved, use the same API from step 1 to retrieve the details of the payment or agreement.

From the response, you will receive a sub value. For example:

{
    "sub": "126684df-c056-4625-821d-f2905febe3f9"
    // ... other items here....
}
  • The sub is a unique identifier for a Vipps MobilePay user.
  • It is specifically tied to their consent to share information with a particular sales unit.

Use this sub to retrieve the user’s profile details, as described in Step 3.

Step 3 - Get the profile information​

Retrieve the user’s profile information using: GET:/vipps-userinfo-api/userinfo/{sub}, where sub is the value you obtained in the previous step.

This endpoint returns the profile details that the user has consented to share.

For example:

{
    "address": {
        "address_type": "home",
        "country": "NO",
        "formatted": "BOKS 6300, ETTERSTAD\n0603\nOSLO\nNO",
        "postal_code": "0603",
        "region": "OSLO",
        "street_address": "BOKS 6300, ETTERSTAD"
    },
    "birthdate": "1955-05-18",
    "email": "test.user@example.com",
    "email_verified": false,
    "family_name": "User",
    "given_name": "Test",
    "name": "Test User",
    "other_addresses": [
        {
            "address_type": "work",
            "country": "NO",
            "formatted": "Robert Levins gate 5\n0152\nOslo\nNO",
            "postal_code": "0152",
            "region": "Oslo",
            "street_address": "Robert Levins gate 5"
        }
    ],
    "phone_number": "4748571123",
    "phone_number_verified": true,
    "sid": "57bccee36b19600c",
    "sub": "126684df-c056-4625-821d-f2905febe3f9"
}

The exact fields returned depend on the scope of the user’s consent.

Consents remain valid for 7 days.

tip

You should fetch the user's information as soon as consent is given. If you delay, the information could become outdated. Always process the data as it was when consent was granted.

For more details about the response as well as consent and data access, see the Userinfo API guide.

Implementation details​

Scope​

The scope parameter determines which user information you request.

When requesting scopes that require user consent, a view listing these scopes will be displayed to the user with the option to allow or deny the consent request. This view is skipped if no scopes requiring consent are requested. The user must either accept or reject the full set of scopes, and can't make changes to the list of requested scopes. A user can therefore not choose to accept name and deny address.

NIN

Only merchants with legal requirements or other objective needs for using the NIN to achieve the required user identification can get access to NIN. We comply with local applicable laws as well as guidance from the Norwegian Data Protection Authority, Datatilsynet, and other relevant local authorities.

Available scopes:

  • address: Requests consent for the user's addresses. See Address for response format.
  • birthDate: User's birthdate, verified with the National Population Register.
  • email: Verified email address.
  • name: Request the user's name.
  • phoneNumber: The phone number verified and used by the user with Vipps MobilePay.
  • nin: National Identity Number (NIN), verified with the National Population Register. Sales units require approval to request this.

You can have multiple values in the scope field, in any order, separated by spaces. For example:

{
  "scope": "email address name phoneNumber"
}
tip

We recommend asking for the minimal number of scopes needed for your use case to minimize the number of users that deny the consent request.

Scope responses

  • name: User’s full name with first, middle, and last names.
  • given_name: User’s first and middle names
  • family_name: User’s last name (aka surname)
  • birthdate: User’s birthdate (YYY-MM-DD)
  • email: Email address.
  • email_verified: If true, the email is verified for each request.
  • phoneNumber: The phone number verified and used by the user with Vipps MobilePay.
  • phone_number_verified: If true, the phoneNumber is verified for each request.
  • nin: National Identity Number
  • address: User's default address - see Address
  • other_addresses - Other addresses - see Address.

Name and birthdate are verified with the National Population Register.

Address​

The user can have up to three addresses in their Vipps or MobilePay app: home, work and other. We recommend that merchants fetch all addresses on a user and allow the user to choose which address to use in the relevant context.

User addresses are given as objects:

  • address - the address set as default for the user.
  • other_addresses - any other addresses of the user.

For example:

{
    "address": {
        "address_type": "home",
        "country": "NO",
        "formatted": "BOKS 6300, ETTERSTAD\n0603\nOSLO\nNO",
        "postal_code": "0603",
        "region": "OSLO",
        "street_address": "BOKS 6300, ETTERSTAD"
    },
    "other_addresses": [
        {
            "address_type": "work",
            "country": "NO",
            "formatted": "Robert Levins gate 5\n0152\nOslo\nNO",
            "postal_code": "0152",
            "region": "Oslo",
            "street_address": "Robert Levins gate 5"
        }
    ],
}

If a user has information in the Unit, floor or other details field of the Vipps Vipps or MobilePay MobilePay app, this will be included in the street_address field. The Street address will then be presented first, before "\n". Then, the contents from Unit, floor or other details (e.g., Suburbia 23"\nUnit B5).

If the user doesn't have any registered address, address object will be provided with empty strings. For example:

{
"address" : {
  "country" : "",
  "street_address" : "",
  "address_type" : "",
  "formatted" : "",
  "postal_code" : "",
  "region" : "" 
  }
}

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 format of the sub is:

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

The sub is based on the user's national identity number (NIN) and does not change if a user removes their consents, logs in again, and re-consents; however, there are some special cases where the sub will change for a user. For instance:

  • If a user deletes their Vipps MobilePay profile and creates a new one.

The sub is used to retrieve the user's details from GET:/userinfo/{sub}.

Troubleshooting

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 is added asynchronously, so if the API request is made within milliseconds of the payment approval in the app, it may not be available. If that happens, simply make another request.

You should fetch the user's information at the time consent is given. If you delay, the information could change and become invalid.

Time limit for data access​

Profile data access is subject to a strict time limit:

  • There is a 168-hour (7-day) time limit to retrieve consented profile data
  • This time limit starts when the user provides consent during the payment flow
  • Once expired, the data cannot be accessed through the API
  • For privacy reasons, manual data provision after expiration is not possible

Example response after expiration:

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

The consent system has some important characteristics:

  • Initial consent: Users must provide consent before completing the payment or agreement.
  • Consent revocation: The data remains accessible for 168 hours, even if consent is revoked.
    To support merchants who need time for manual processing, profile information remains accessible for 168 hours after consent, even if the user revokes consent during this period. This ensures merchants can complete necessary post-payment processes.

Access to NIN​

Only merchants with legal requirements or other objective needs for using the NIN to achieve the required user identification can get access to NIN. We comply with local applicable laws as well as guidance from the Norwegian Data Protection Authority, Datatilsynet, and other relevant local authorities.

Sequence diagram​

Userinfo through payment

👉 See the quick start guide to run through the complete flow.

For API call-by-call guides, see:

Last updated on