> **Description:** Comprehensive technical guide for implementing profile sharing with the Userinfo API. Learn how to securely request and handle user profile information as part of your payment flows. # 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](#time-limit-for-data-access). * The shared information must be handled in accordance with GDPR requirements. See our [privacy terms](https://vippsmobilepay.com/en-NO/legal/terms-privacy). ## How to get profile information **TIP** See the [quick start guide](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-quick-start.md) 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`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) * Recurring API: [`POST:/recurring/agreements`](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml) * eCom API: [`POST:/ecomm/v2/payments`](https://developer.vippsmobilepay.com/redocusaurus/ecom-swagger-id.yaml) The options for `scope` include: `address`, `birthDate`, `email`, `name`, `phoneNumber`, and `nin` (in special cases). ```json { "scope": "name phoneNumber address birthDate" }' ``` See [scope](#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](#time-limit-for-data-access), 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](#step-1---request-consent) to retrieve the details of the payment or agreement. * ePayment API: [`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) * Recurring API: [`GET:/recurring/agreements/{agreementId}`](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml) * eCom API: [`GET:/ecomm/v2/payments/{orderId}/details`](https://developer.vippsmobilepay.com/redocusaurus/ecom-swagger-id.yaml) From the response, you will receive a `sub` value. For example: ```json { "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). ### Step 3 - Get the profile information Retrieve the user's profile information using: [`GET:/vipps-userinfo-api/userinfo/{sub}`](https://developer.vippsmobilepay.com/redocusaurus/userinfo-swagger-id.yaml), 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: ```json { "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](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-guide.md). ## 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](https://www.datatilsynet.no/rettigheter-og-plikter/personopplysninger/fodselsnummer/), and other relevant local authorities. **Available scopes:** * `address`: Requests consent for the user's addresses. See [Address](#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)](https://developer.vippsmobilepay.com/docs/knowledge-base/terminology.md#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: ```json { "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 (YYYY-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](#address) * `other_addresses` - Other addresses - see [Address](#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: ```json { "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, the `address` object will be provided with empty strings. For example: ```json { "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*](https://developer.vippsmobilepay.com/docs/knowledge-base/terminology.md#cpr-nummer). Finland: The NIN is known as [*henkilötunnus*](https://developer.vippsmobilepay.com/docs/knowledge-base/terminology.md#henkilötunnus). Sweden: It's called [*personnummer*](https://developer.vippsmobilepay.com/docs/knowledge-base/terminology.md#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](https://www.datatilsynet.no/rettigheter-og-plikter/personopplysninger/fodselsnummer/), and other relevant local authorities. **Access to NIN** Not available in Norway. Apply for access to NIN by sending an email to [operations@vippsmobilepay.com](mailto:operations@vippsmobilepay.com). In the email you must share: * Organization number * Merchant name * Sales unit name and [MSN](https://developer.vippsmobilepay.com/docs/knowledge-base/terminology.md#merchant-serial-number-msn), fetched from the [business portal](https://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 only be achieved with NIN * Any supportive documents such as user terms, process flows, and similar materials. * 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: ```json "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}`](https://developer.vippsmobilepay.com/redocusaurus/userinfo-swagger-id.yaml). **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: ```json "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 ```mermaid sequenceDiagram autonumber actor User actor UserVippsApp participant Merchant participant Vipps as Vipps MobilePay User ->> Merchant: Initiate transaction Merchant ->> Vipps: Initiate transaction Note right of Merchant: Example scopes: name, address, email Vipps -->> Merchant : Session link Merchant ->> UserVippsApp : Trigger transaction session UserVippsApp ->> Vipps : Approve payment and detail sharing Vipps ->> Vipps : Save Consent and generate sub Vipps ->> Vipps : Perform Payment Vipps -->> UserVippsApp : Response UserVippsApp ->> Merchant : Response Merchant ->> Vipps : Retrieve details Vipps -->> Merchant : Return details, sub included Merchant ->> Vipps : Get on userinfo/{sub} Vipps -->> Merchant : Return userinfo Merchant ->> Merchant : Handle session result ``` User initiates a transaction with the Merchant. Merchant initiates the transaction with Vipps MobilePay, specifying scopes such as name, address, and email. Vipps MobilePay returns a session link to the Merchant. Merchant triggers the transaction session in the user's Vipps app. User approves the payment and consents to detail sharing in the Vipps app. Vipps MobilePay saves the consent and generates a subject identifier (sub). Vipps MobilePay performs the payment. Vipps MobilePay sends the response to the user's Vipps app. Vipps app sends the response to the Merchant. Merchant retrieves the details from Vipps MobilePay. Vipps MobilePay returns the details including the sub. Merchant requests userinfo using the sub (GET userinfo/{sub}). Vipps MobilePay returns the userinfo to the Merchant. Merchant handles the session result. ## Related feature pages See the [quick start guide](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-quick-start.md) to run through the complete flow. For API call-by-call guides, see: * [Recurring API profile sharing](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#profile-sharing) * [ePayment API profile sharing](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/profile-sharing.md) * [eCom API profile sharing](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#profile-sharing) > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).