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:

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

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 or 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.

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

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 or 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" : "" 
  }
}

NIN

The National Identity Number (NIN) is a unique personal identification number assigned to each individual by their national government.

Denmark: The NIN is called CPR-nummer / personnummer.
Finland: The NIN is known as henkilötunnus.
Norway: It's called fødselsnummer.
Sweden: It's called personnummer.

The National Identity Number (NIN) is protected. 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.

Access to NIN

Apply for access to NIN by sending an email to agreement@vippsmobilepay.com. In the email you must share:

• Organization number
• Merchant name
• Sales unit name and MSN, fetched from portal.vippsmobilepay.com
• Detailed information on how you plan to use the NIN
• If the request is based on the objective need; explanation of why the purpose can be only achieved with NIN
• Any supportive documents such as user terms, process flows etc.
• If the request is based on the legal requirement, direct reference to the legal text and guidelines, if any.

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.

Consent and data access

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]"
}

Consent management

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.

Sequence diagram

Userinfo through payment

Related feature pages

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

For API call-by-call guides, see:

• Recurring API profile sharing
• ePayment API profile sharing
• eCom API profile sharing