openapi: 3.0.0
info:
  description: >
    We offer the possibility for merchants to ask for the user's profile
    information as part of the payment flow.

    This follows the [OIDC Standard: UserInfo
    endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).


    See the [Userinfo API guide](/docs/APIs/userinfo-api) for more details.
  version: 2.0.3
  title: Userinfo API
servers:
  - url: https://api.vipps.no
    description: >-
      Production environment (uses the production API keys, the official app and
      live data)
  - url: https://apitest.vipps.no
    description: Test environment (uses the test API keys, the test app and test data)
paths:
  /vipps-userinfo-api/userinfo/{sub}:
    get:
      summary: Get Userinfo
      description: >-
        This endpoint returns the payload with the information that the user has
        consented to share. Find more info on the `/userinfo` endpoint at the
        [OIDC
        Standard](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
      operationId: getUserinfo
      parameters:
        - $ref: '#/components/parameters/sub'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Merchant-Serial-Number'
        - $ref: '#/components/parameters/Vipps-System-Name'
        - $ref: '#/components/parameters/Vipps-System-Version'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Name'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Version'
      responses:
        '200':
          description: Get Userinfo
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Userinfo'
        '400':
          description: Bad Request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '403':
          description: Forbidden
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
  /vipps-userinfo-api/userinfo/:
    get:
      summary: Get Userinfo in the Login API flow
      description: >-
        This endpoint is only for use in the [Login API: Integrate from a
        website](/docs/APIs/login-api/api-guide/browser-flow-integration/#userinfo).
        It returns the payload with the information that the user has consented
        to share. Find more info on the `/userinfo` endpoint at the [OIDC
        Standard](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
      operationId: userinfoAuthorizationCode
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Merchant-Serial-Number'
        - $ref: '#/components/parameters/Vipps-System-Name'
        - $ref: '#/components/parameters/Vipps-System-Version'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Name'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Version'
      responses:
        '200':
          description: Get Userinfo
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Userinfo'
        '400':
          description: Bad Request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '403':
          description: Forbidden
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/UserinfoError'
components:
  parameters:
    Authorization:
      in: header
      name: Authorization
      description: >-
        The access token is a base64-encoded string that is required for all API
        calls. It is a JWT (JSON Web Token). The access token is fetched from
        [`POST:/accesstoken/get`](/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost).
        It is valid for 1 hour in the test environment and 24 hours in the
        production environment.
      required: true
      schema:
        type: string
      example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...
    Ocp-Apim-Subscription-Key:
      in: header
      name: Ocp-Apim-Subscription-Key
      description: >-
        The subscription key for your sales unit. See [API
        keys](/docs/knowledge-base/api-keys/).

        Keep it secret.
      required: true
      schema:
        type: string
      example: 0f14ebcab0ec4b29ae0cb90d91b4a84a
    Merchant-Serial-Number:
      name: Merchant-Serial-Number
      in: header
      description: >-
        The Merchant Serial Number (MSN) is a unique ID for the sales unit

        for which this payment is made.

        This is a required parameter if you are a Vipps MobilePay Recurring
        partner

        making payments on behalf of a merchant.

        The partner must use the merchant's MSN (not the partner's MSN).

        This parameter is optional, and recommended, for regular Vipps MobilePay

        merchants making payments for themselves.
      required: false
      schema:
        type: string
      example: 123456
    Vipps-System-Name:
      name: Vipps-System-Name
      in: header
      description: |-
        The name of the ecommerce solution.
        One word in lowercase letters is good.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
      example: WooCommerce
    Vipps-System-Version:
      name: Vipps-System-Version
      in: header
      description: |-
        The version number of the ecommerce solution.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
      example: 5.4.0
    Vipps-System-Plugin-Name:
      name: Vipps-System-Plugin-Name
      in: header
      description: |-
        The name of the ecommerce plugin (if applicable).
        One word in lowercase letters is good.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
      example: woocommerce-payment
    Vipps-System-Plugin-Version:
      name: Vipps-System-Plugin-Version
      in: header
      description: |-
        The version number of the ecommerce plugin (if applicable).
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
      example: 1.2.1
    sub:
      name: sub
      in: path
      description: The `sub` is specified when fetching payment details.
      schema:
        type: string
      required: true
  schemas:
    Userinfo:
      type: object
      properties:
        accounts:
          description: >-
            Contains an array with the user''s bank accounts registered in the
            app.

            Although this feature is now deprecated, it will remain available to
            merchants and partners who entered

            into an agreement to use it prior to deprecation.
          deprecated: true
          type: array
          items:
            $ref: '#/components/schemas/UserinfoAccountInfo'
        address:
          allOf:
            - $ref: '#/components/schemas/UserinfoAddress'
            - description: Contains the user's preferred (default) address.
        other_addresses:
          description: >-
            Contains an array with the user's non-default addresses, if any.
            This list can contain an address with the address_type home, work,
            and/or other, if the user has registered them in the Vipps app
          type: array
          items:
            $ref: '#/components/schemas/UserinfoAddress'
        birthdate:
          description: The user's birthday formatted as YYYY-MM-DD
          type: string
          example: '2000-12-31'
        email:
          description: The user's email address.
          example: user@example.com
          type: string
        email_verified:
          description: >-
            Boolean value indicating whether the user's email address is
            verified or not.
          type: boolean
          example: true
        family_name:
          description: Surname(s) or last name(s) of the user.
          example: Lovelace
          type: string
        given_name:
          description: >-
            Given name(s) or first name(s) of the user. Note that in some
            cultures, people can have multiple given names; all can be present,
            with the names being separated by space characters.
          type: string
          example: Ada
        name:
          description: >-
            The user's full name in displayable form including all name parts,
            possibly including titles and suffixes, ordered according to the
            user's locale and preferences.
          type: string
          example: Ada Lovelace
        nin:
          description: >-
            National identity number:\n

            * Norway: "fødselsnummer": 11 digits: `DDMMYYNNNNN`, where `DDMMYY`
            is the date of birth, and `NNNNN` is a serial number. 

            * Denmark: "CPR-nummer": 11 characters: 10 digits and a separator:
            `DDMMYY-NNNN`, where `DDMMYY` is the date of birth and `NNNN` is a
            personal identifier. 

            * Sweden: "personnummer": 11 characters: 10 digits and a separator:
            `YYMMDD-NNNN` or `YYYYMMDD-NNNN` (with or without the century part).
            The `-` can change to a `+` for people born 100+ years ago. 

            * Finland: "Henkilötunnus": 11 characters, including a separator and
            a letter: `DDMMYYCZZZX`, where `C` is the separator (`+`, `-`, or
            `A`), and `ZZZX` includes a check digit. 
          type: string
          example: '09057517287'
          pattern: (\d{11}|\d{6}[\-\+]\d{4}|\d{6}[\-\+]\d{3}[0-9A-Z])
        phone_number:
          description: |-
            The user's telephone number.
            The format is MSISDN with digits only: Country code and subscriber.
            number, but no prefix.
            See https://en.wikipedia.org/wiki/MSISDN
          type: string
          example: '4712345678'
          pattern: ^\d{14,15}$
        sid:
          description: |-
            Session identifier: This represents a session of a User Agent or
            device. Currently, not in use.
          type: string
          example: 7d78a726-af92-499e-b857-de263ef9a969
        sub:
          description: |-
            Subject: Unique identifier for the user.
            The sub is based on the user's national identity number (NIN) and
            does not change (except in very special cases).
            The `sub` is the same when the user logs in again and re-consents.
          type: string
          example: c06c4afe-d9e1-4c5d-939a-177d752a0944
        delegatedConsents:
          description: Marketing consents collected from the user.
          $ref: '#/components/schemas/UserinfoMarketingConsents'
    UserinfoAccountInfo:
      type: object
      description: >-
        Bank account.

        Although this feature is now deprecated, it will remain available to
        merchants and partners who entered

        into an agreement to use it prior to deprecation.
      deprecated: true
      properties:
        account_name:
          description: The user''s defined name for account
          type: string
          example: Savings account
        account_number:
          description: The user''s account number
          type: string
          example: 86011117947
        bank_name:
          description: The bank connected to the account number
          type: string
          example: ACME Bank
    UserinfoAddress:
      type: object
      properties:
        address_type:
          description: Address type is either `home`, `work` or `other`.
          type: string
          example: home
        country:
          description: Two-letter country code
          type: string
          format: ^[A-Z]{2}$
          example: 'NO'
        formatted:
          description: The user's address as a formatted string
          type: string
          example: |-
            Robert Levins gate 5
            0154 Oslo
        postal_code:
          description: Postal code
          type: string
          example: '0154'
        region:
          description: The user's region (typically a county, town or city)
          type: string
          example: Oslo
        street_address:
          description: The user's street address
          type: string
          example: Robert Levins gate 5
    UserinfoMarketingConsents:
      description: Marketing consents collected from the user.
      type: object
      properties:
        language:
          type: string
          example: EN
        heading:
          type: string
          example: How would you like to receive communication?
        termsDescription:
          type: string
          example: >-
            By confirming, you accept Butikken AS's terms of membership. They
            are responsible for processing the consents. You can withdraw them
            at any time on their website.
        confirmConsentButtonText:
          type: string
          example: Confirm
        links:
          type: object
          properties:
            termsLinkText:
              type: string
              example: Read the terms of use.
            termsLinkUrl:
              type: string
              format: uri
              example: https://example.com/vilkar/vilkar-privat/
            privacyStatementLinkText:
              type: string
              example: Read the privacy policy.
            privacyStatementLinkUrl:
              type: string
              format: uri
              example: https://example.com/vilkar/cookie-og-personvern/
        timeOfConsent:
          type: string
          format: date-time
          example: '2024-06-17T12:25:53Z'
        consents:
          type: array
          items:
            $ref: '#/components/schemas/Consent'
    Consent:
      type: object
      properties:
        id:
          type: string
          enum:
            - email
            - sms
            - digital
            - personal
          example: email
        accepted:
          type: boolean
          example: true
        required:
          type: boolean
          example: true
        textDisplayedToUser:
          type: string
          example: Email
    UserinfoError:
      type: object
      description: |-
        The standard Error object.
        See https://developer.vippsmobilepay.com/docs/knowledge-base/errors
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
          example: https://example.com/validation-error
        title:
          type: string
          description: >-
            A short, human-readable summary of the problem type.  It will not
            change from occurrence to occurrence of the problem.
          example: Your request parameters didn't validate.
        status:
          type: string
          description: The HTTP status code.
          example: 400
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          example: The request body contains one or more errors
        instance:
          type: string
          description: An ID that can help when troubleshooting.
          example: 123e4567-e89b-12d3-a456-426655440000
        extraInfo:
          type: object
          additionalProperties:
            type: object
