openapi: 3.0.0
servers:
  - url: https://api.vipps.no/epayment
    description: >-
      Production environment (uses the production API keys, the official app and
      live data)
  - url: https://apitest.vipps.no/epayment
    description: Test environment (uses the test API keys, the test app and test data)
info:
  description: >-
    The ePayment API enables you to create Vipps MobilePay payments for online
    and in-person payments.

    See the [ePayment API
    Guide](https://developer.vippsmobilepay.com/docs/APIs/epayment-api)

    for more details.
  version: 1.6.0
  title: ePayment API
  contact:
    name: Vipps MobilePay AS
    url: https://developer.vippsmobilepay.com/
  license:
    name: MIT
    url: https://choosealicense.com/licenses/mit/
  termsOfService: https://vippsmobilepay.com/legal/terms-and-conditions/
  x-logo:
    url: >-
      https://vipps.no/static/vipps_frontend/311340/media/extra-images/vipps-logo.svg
    backgroundColor: '#FFFFFF'
    altText: Logo
tags:
  - description: Create payment endpoints
    name: CreatePayments
  - description: Query payments endpoints
    name: QueryPayments
  - description: Adjust payments endpoints
    name: AdjustPayments
  - description: Force approve payments endpoints
    name: ForceApprove
paths:
  /v1/payments:
    parameters:
      - $ref: '#/components/parameters/Idempotency-Key'
      - $ref: '#/components/parameters/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'
    post:
      operationId: createPayment
      summary: Create a payment
      tags:
        - CreatePayments
      description: Create a new payment
      requestBody:
        description: New `CreatePaymentRequest` body.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreatePaymentResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '409':
          $ref: '#/components/responses/ProblemResponse'
  /v1/payments/{Reference}:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
    get:
      summary: Get a payment
      tags:
        - QueryPayments
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentResponse'
      operationId: getPayment
      description: Get a payment object by its `reference` id.
  /v1/payments/{Reference}/events:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
    get:
      summary: Get a payment's event log
      tags:
        - QueryPayments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentEvent'
      operationId: getPaymentEventLog
      security:
        - Bearer-Authorization: []
      description: Get event log for the specified payment's `reference` id.
  /v1/payments/{Reference}/cancel:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
      - $ref: '#/components/parameters/Idempotency-Key'
      - $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'
    post:
      summary: Cancel a payment
      operationId: cancelPayment
      requestBody:
        description: New `CancelModificationRequest` body.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelModificationRequest'
      responses:
        '200':
          $ref: '#/components/responses/AdjustResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '409':
          $ref: '#/components/responses/ProblemResponse'
      description: Cancel the payment with the specified `reference` id.
      security:
        - Bearer-Authorization: []
      tags:
        - AdjustPayments
  /v1/payments/{Reference}/capture:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
      - $ref: '#/components/parameters/Idempotency-Key'
      - $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'
    post:
      summary: Capture a payment
      operationId: capturePayment
      responses:
        '200':
          $ref: '#/components/responses/AdjustResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '409':
          $ref: '#/components/responses/ProblemResponse'
      description: Capture the given payment
      security:
        - Bearer-Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureModificationRequest'
        description: Requested capture modification
      tags:
        - AdjustPayments
  /v1/payments/{Reference}/refund:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
      - $ref: '#/components/parameters/Idempotency-Key'
      - $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'
    post:
      summary: Refund a payment
      operationId: refundPayment
      responses:
        '200':
          $ref: '#/components/responses/AdjustResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '409':
          $ref: '#/components/responses/ProblemResponse'
      description: Refund the given payment
      security:
        - Bearer-Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundModificationRequest'
        description: Requested refund modification
      tags:
        - AdjustPayments
  /v1/test/payments/{Reference}/approve:
    parameters:
      - $ref: '#/components/parameters/Payment-Reference-ID'
      - $ref: '#/components/parameters/Merchant-Serial-Number'
      - $ref: '#/components/parameters/APIM-Subscription-Key'
    post:
      summary: Force approve a payment
      tags:
        - ForceApprove
      responses:
        '200':
          description: OK
      operationId: forceApprove
      description: >-
        This endpoint is only available in the test environment.

        It allows developers to approve a payment through the ePayment API

        without the use of the Vipps or MobilePay app. This is useful for
        automated testing.

        Express checkout is not supported for this endpoint.

        Attempted use in production is not allowed, and will fail.

        Important: All test users must manually approve at least one payment

        in the Vipps or MobilePay app before this endpoint can be used for that
        user.
      security:
        - Bearer-Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForceApprove'
        description: Force approve request body
components:
  schemas:
    Customer:
      title: Customer
      type: object
      description: >-
        The target customer if the identity is known.

        The customer can be specified either with phone number, the customer
        token

        or with the user's personal QR code

        Specifying more than one of these will result in an error.
      oneOf:
        - $ref: '#/components/schemas/CustomerPhoneNumber'
        - $ref: '#/components/schemas/PersonalQrCode'
        - $ref: '#/components/schemas/CustomerToken'
      x-examples:
        example phonenumber:
          phoneNumber: '4712345678'
        example personal Qr:
          personalQr: https://qr.vipps.no/p/{{internationalMobileNumber}}
    CustomerPhoneNumber:
      title: Customer phone number
      type: object
      description: >-
        The customer's phone number, if available.


        **Please note:** The phone number (and QR code) is optional and should
        only be sent if it is

        already known. Users should never be asked for the phone number, as they
        will

        either be automatically app-switched to the Vipps or MobilePay app, or
        they will be presented

        with the landing page. The exception for this is "manual POS"
        integration,

        where the cashier asks the customer for the number, and then enters it
        manually on the POS.


        If the customer's phone number is needed by the merchant,

        use `scope` and the [Userinfo
        API](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/).

        See also [Landing
        page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/).
      properties:
        phoneNumber:
          type: string
          description: >-
            The phone number of the user paying the transaction with Vipps
            MobilePay.

            The format is MSISDN: Digits only: Country code and subscriber
            number, but no prefix.

            If the phone number is a Norwegian phone number `(+47) 91 23 45 67`,
            the MSISDN representation is `4712345678`.

            See: https://en.wikipedia.org/wiki/MSISDN
          minLength: 10
          maxLength: 15
          example: '4712345678'
          pattern: ^\d{10,15}$
    PersonalQrCode:
      title: Personal QR code
      type: object
      description: >-
        The full content of the user's personal QR code in the app, used in
        'merchant scan' scenarios. 

        After the personal QR code has been scanned in a physical context, send
        the complete QR

        code content in this field to initiate a payment from the user (and do
        not send `phoneNumber`).


        **Important:** The content of the QR code can change at any time,
        without warning.

        It is very important to send the _complete content of the QR code_, like
        the complete URL in the example below.

        While the personal QR code does reveal the user's phone number in this
        example, that may change.

        The [Userinfo
        API](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/)

        should be used if you need the user to share personal information, 

        such as phone number, email address, etc.
      properties:
        personalQr:
          type: string
          description: The full content of the user's personal QR code in the app.
          minLength: 5
          maxLength: 255
          example: https://qr.vipps.no/28/2/01/031/4712345678?v=1
    CustomerToken:
      title: Customer token
      type: object
      description: >-
        The customer's token, if it is available. This token will be sent as
        part of the user.checked-in.v1 webhook event when a user scans a
        merchant callback QR
      properties:
        customerToken:
          type: string
          description: A distinct token per customer.
          example: ey%382jf8+qk3nnfdsao0i5jlalidugujnakgo9t8ghn
    Amount:
      description: Amount object, containing a `value` and a `currency`.
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        value:
          type: integer
          minimum: 0
          maximum: 65000000
          example: 49900
          format: int64
          description: >-
            Amounts are specified in minor units (i.e., integers with two
            trailing zeros).

            For example: 10.00 NOK should be written as 1000.

            The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.
      required:
        - value
        - currency
    Currency:
      type: string
      example: NOK
      enum:
        - NOK
        - DKK
        - EUR
      description: Available types of currency are NOK, DKK, and EUR.
    Metadata:
      type: object
      description: >-
        Metadata is a key-value map that can be used to store additional

        information about the payment. The metadata is not used by Vipps

        MobilePay, but is passed through in the `GetPaymentResponse` object.

        Key length is limited to 100 characters, and value length is limited to
        500 characters.

        Max capacity is 5 key-value pairs.
      additionalProperties:
        type: string
      maxProperties: 5
      example:
        key1: value1
        key2: value2
        key3: value3
      nullable: true
    CreatePaymentRequest:
      title: Create payment request
      description: The `CreatePaymentRequest` object.
      type: object
      x-examples:
        example with order lines:
          amount:
            value: 1234
            currency: NOK
          paymentMethod:
            type: WALLET
          customer:
            phoneNumber: '4796844569'
          reference: acme-shop-123-order123abc
          userFlow: PUSH_MESSAGE
          returnUrl: https://example.com/redirect?reference=577531713174689605
          expiresAt: '2024-05-01T13:03:56+02:00'
          paymentDescription: Purchase of socks
          receipt:
            orderLines:
              - name: Vipps socks
                id: '1234567890'
                totalAmount: 1000
                totalAmountExcludingTax: 800
                totalTaxAmount: 200
                taxPercentage: 25
                unitInfo:
                  unitPrice: 500
                  quantity: '2'
                  quantityUnit: PCS
                discount: 2000
                productUrl: https://example.com/store/socks
                isReturn: false
                isShipping: false
              - name: Vipps Hoodie
                id: '1234567890'
                totalAmount: 11000
                totalAmountExcludingTax: 10000
                totalTaxAmount: 1000
                taxPercentage: 10
                unitInfo:
                  unitPrice: 11000
                  quantity: '1'
                  quantityUnit: PCS
                discount: 0
                productUrl: https://example.com/store/socks
                isReturn: false
                isShipping: false
            bottomLine:
              currency: NOK
              tipAmount: 2000
              giftCardAmount: 20000
              posId: I will put posId in here
              totalAmount: 0
              totalTax: 0
              totalDiscount: 0
              shippingAmount: 0
              shippingInfo:
                amount: 1000
                amountExcludingTax: 1000
                taxAmount: 250
                taxPercentage: 25
              paymentSources:
                giftCard: 0
                card: 0
                voucher: 0
                cash: 0
              barcode:
                format: EAN-13
                data: string
              receiptNumber: receiptnumberyolo
        example with personal Qr:
          amount:
            value: 1234
            currency: NOK
          paymentMethod:
            type: WALLET
          customer:
            personalQr: https://qr.vipps.no/p/4796844569
          reference: acme-shop-123-order123abc
          userFlow: PUSH_MESSAGE
          returnUrl: https://example.com/redirect?reference=577531713174932058
          paymentDescription: Purchase of socks
        example with user info:
          amount:
            value: 1234
            currency: NOK
          paymentMethod:
            type: WALLET
          customer:
            phoneNumber: 4796844569
          reference: acme-shop-123-order123abc
          userFlow: PUSH_MESSAGE
          returnUrl: https://example.com/redirect?reference=577531713175705837
          paymentDescription: Purchase of socks
          profile:
            scope: name phoneNumber address birthDate
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        customer:
          $ref: '#/components/schemas/Customer'
        minimumUserAge:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          example: 16
          description: Minimum age in years required for the customer to make the purchase.
        customerInteraction:
          type: string
          description: >-
            The type of customer interaction that triggers the purchase.

            `CUSTOMER_PRESENT` means that the customer is physically present at
            the

            point of sale when the payment is made, typically in a store.
          enum:
            - CUSTOMER_PRESENT
            - CUSTOMER_NOT_PRESENT
          x-enum-varnames:
            - CUSTOMER_PRESENT
            - CUSTOMER_NOT_PRESENT
          example: CUSTOMER_NOT_PRESENT
          default: CUSTOMER_NOT_PRESENT
        industryData:
          $ref: '#/components/schemas/IndustryData'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        profile:
          $ref: '#/components/schemas/ProfileRequest'
        reference:
          $ref: '#/components/schemas/Reference'
        returnUrl:
          type: string
          example: https://example.com/redirect?orderId=acme-shop-123-order123abc
          description: |-
            The URL the user is returned to after the payment session.
            The URL must use the `https://` scheme or a custom URL scheme.
        userFlow:
          type: string
          enum:
            - PUSH_MESSAGE
            - NATIVE_REDIRECT
            - WEB_REDIRECT
            - QR
          x-enum-varnames:
            - PUSH_MESSAGE
            - NATIVE_REDIRECT
            - WEB_REDIRECT
            - QR
          example: WEB_REDIRECT
          description: >-
            The flow for bringing the user to the Vipps or MobilePay app's
            payment confirmation screen.

            If `userFlow` is `PUSH_MESSAGE`, a valid value for `customer` is
            required.

            If `userFlow` is `WEB_REDIRECT`, a valid value for `returnUrl` is
            required.

            `WEB_REDIRECT` is the normal flow for browser-based payment flows. 

            If on a mobile device, the Vipps or MobilePay app will open. A valid
            value for `returnUrl` is required.

            Otherwise, the [landing
            page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/)
            will open.

            `PUSH_MESSAGE` is to skip the landing page for payments initiated on
            a device other than the user's phone.

            The user gets a push message that opens the payment in the app. This
            requires a valid `customer` field.

            `QR` returns a QR code that can be scanned to complete the payment.

            `NATIVE_REDIRECT` is not recommended, except in some cases where
            merchant doesn’t have web presence.

            It provides automatic app-switch between the merchant's native app
            and the Vipps or MobilePay app.

            We recommend using `WEB_REDIRECT` instead.
        expiresAt:
          type: string
          example: '2023-02-26T17:32:28Z'
          pattern: >-
            ^((?:(\d{4}-\d{2}-\d{2})(T|t)(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|z|([+-](?:2[0-3]|[01][0-9]):[0-5][0-9])))$
          nullable: true
          description: >-
            The payment will expire at the given date and time.

            The format must adhere to RFC 3339.

            The value must be more than 10 minutes and less than 60 days in the
            future.

            Can only be combined with `userFlow: PUSH_MESSAGE` or `userFlow:
            QR`.


            If `ExpiresAt` is set, `receipt` also must be set.
        qrFormat:
          nullable: true
          type: object
          description: >-
            Optional setting that is only applicable when `userFlow` is set to
            `QR`.

            This is used to set the format for the QR code.
          properties:
            format:
              type: string
              enum:
                - TEXT/TARGETURL
                - IMAGE/SVG+XML
                - IMAGE/PNG
              example: IMAGE/SVG+XML
              description: >-
                If `userFlow` is `QR` and `qrFormat` is not set, the QR code
                image will be returned as `SVG+XML`, by default.
              default: IMAGE/SVG+XML
            size:
              type: integer
              example: 1024
              description: >-
                For example, if the value is 200, then 200x200 px is set as the
                dimension for the QR code.

                This is only applicable when the format is set to `PNG`. If not
                set, the default is 1024.
              minimum: 100
              maximum: 2000
              nullable: true
          required:
            - format
        paymentDescription:
          type: string
          minLength: 3
          maxLength: 100
          description: |-
            The payment description summary that will be provided to the user
            through the app, the merchant portal, and the settlement files.
            See the [recommendations](/docs/knowledge-base/transactiontext/).
          example: >-
            Temporary reservation of maximum amount. You will only be charged
            for the actual use.
        receipt:
          $ref: '#/components/schemas/Receipt'
        metadata:
          $ref: '#/components/schemas/Metadata'
        receiptUrl:
          type: string
          description: |-
            The URL where a receipt can be viewed or downloaded.
            The URL must use the `https://` scheme or a custom URL scheme.
          example: https://example.com/receipt/9876543210
          nullable: true
      required:
        - amount
        - paymentMethod
        - reference
        - userFlow
    CreatePaymentResponse:
      title: Create payment response
      description: The `CreatePaymentResponse` object.
      type: object
      properties:
        redirectUrl:
          type: string
          format: uri
          example: https://landing.vipps.no?token=abc123
          description: |-
            The URL to which the user is redirected when continuing the payment
            for `NATIVE_REDIRECT` and `WEB_REDIRECT`. When `userFlow` is `QR`,
            a link to the QR image (or the target URL) will be returned.
            Nothing will be returned when `userFlow` is `PUSH_MESSAGE`.
        reference:
          $ref: '#/components/schemas/Reference'
      required:
        - reference
    GetPaymentResponse:
      title: Get payment response
      description: The `GetPaymentResponse` object.
      type: object
      x-examples: {}
      properties:
        aggregate:
          $ref: '#/components/schemas/Aggregate'
        amount:
          $ref: '#/components/schemas/Amount'
        state:
          $ref: '#/components/schemas/State'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethodResponse'
        profile:
          $ref: '#/components/schemas/ProfileResponse'
        pspReference:
          $ref: '#/components/schemas/PspReference'
        redirectUrl:
          type: string
          format: uri
          example: https://landing.vipps.no?token=abc123
          description: >-
            The URL you should redirect the user to to continue with the
            payment.

            This is the URL to the Vipps MobilePay landing page.

            See:
            https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/
        reference:
          $ref: '#/components/schemas/Reference'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - aggregate
        - amount
        - state
        - paymentMethod
        - profile
        - pspReference
        - reference
    IndustryData:
      description: Additional compliance data related to the transaction.
      type: object
      properties:
        airlineData:
          $ref: '#/components/schemas/AirlineData'
    AirlineData:
      title: AirlineData
      type: object
      required:
        - agencyInvoiceNumber
        - airlineCode
        - airlineDesignatorCode
        - passengerName
      description: |-
        Airline related data.
        If present, `passengerName`, `airlineCode`, `airlineDesignatorCode`,
        and `agencyInvoiceNumber` are all required.
      properties:
        agencyInvoiceNumber:
          type: string
          description: Reference number for the invoice, issued by the agency.
          minLength: 1
          maxLength: 6
        airlineCode:
          type: string
          description: |-
            IATA 3-digit accounting code (PAX); numeric.
            It identifies the carrier. eg KLM = 074.
          format: IATA 3-digit accounting code (PAX)
          example: '074'
          minLength: 3
          maxLength: 3
        airlineDesignatorCode:
          type: string
          description: |-
            IATA 2-letter accounting code (PAX); alphabetical.
            It identifies the carrier. Eg KLM = KL.
          format: IATA 2-letter airline code
          example: KL
          minLength: 2
          maxLength: 2
        passengerName:
          type: string
          description: Passenger name, initials, and a title.
          format: last name + first name or initials + title.
          example: FLYER / MARY MS.
          minLength: 1
          maxLength: 49
        ticketNumber:
          type: string
          description: The ticket's unique identifier.
          minLength: 1
          maxLength: 150
          example: 123-1234567890
    Aggregate:
      title: Aggregate
      type: object
      properties:
        authorizedAmount:
          $ref: '#/components/schemas/Amount'
        cancelledAmount:
          $ref: '#/components/schemas/Amount'
        capturedAmount:
          $ref: '#/components/schemas/Amount'
        refundedAmount:
          $ref: '#/components/schemas/Amount'
      required:
        - authorizedAmount
        - cancelledAmount
        - capturedAmount
        - refundedAmount
    CancelModificationRequest:
      title: CancelModificationRequest
      type: object
      x-examples: {}
      properties:
        cancelTransactionOnly:
          type: boolean
          description: >-
            Only cancel transaction if it has not been authorized.

            If this flag is set and the transaction has been authorized, the
            reserved amount will not be canceled.
    CaptureModificationRequest:
      title: CaptureModificationRequest
      type: object
      x-examples: {}
      properties:
        modificationAmount:
          $ref: '#/components/schemas/Amount'
      required:
        - modificationAmount
    RefundModificationRequest:
      title: RefundModificationRequest
      type: object
      x-examples: {}
      properties:
        modificationAmount:
          $ref: '#/components/schemas/Amount'
      required:
        - modificationAmount
    ModificationResponse:
      title: ModificationResponse
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        state:
          $ref: '#/components/schemas/State'
        aggregate:
          $ref: '#/components/schemas/Aggregate'
        pspReference:
          $ref: '#/components/schemas/PspReference'
        reference:
          $ref: '#/components/schemas/Reference'
      required:
        - amount
        - state
        - aggregate
        - pspReference
        - reference
    MSN:
      type: string
      title: MSNType
      pattern: ^[0-9]{4,7}$
      minLength: 4
      maxLength: 7
      example: '1234567'
      description: The merchant serial number (MSN) for the sales unit.
    Reference:
      type: string
      title: ReferenceType
      description: >-
        The `reference` is the unique identifier for the payment, specified when
        initiating the payment. The reference must be unique for the sales unit
        (MSN), but is not _globally_ unique, so several MSNs may use the same
        reference. See the [recommendations](/docs/knowledge-base/orderid/).
      pattern: ^[a-zA-Z0-9-]{8,50}$
      minLength: 8
      maxLength: 50
      example: acme-shop-123-order123abc
      x-examples: {}
    PaymentEventName:
      type: string
      enum:
        - CREATED
        - ABORTED
        - EXPIRED
        - CANCELLED
        - CAPTURED
        - REFUNDED
        - AUTHORIZED
        - TERMINATED
      example: AUTHORIZED
      x-enum-varnames:
        - CREATED
        - ABORTED
        - EXPIRED
        - CANCELLED
        - CAPTURED
        - REFUNDED
        - AUTHORIZED
        - TERMINATED
    PspReference:
      type: string
      title: PspReference
      description: Reference value for a payment, defined by Vipps MobilePay.
    Address:
      title: Address
      type: object
      x-examples:
        Vipps:
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
          lines:
            - Robert Levins gate 5
          postCode: '0154'
          city: Oslo
          country: Norway
      properties:
        city:
          type: string
          example: Oslo
        country:
          type: string
          example: 'NO'
          pattern: ^[A-Z]{2}$
          description: Country code according to ISO 3166-2 (two capital letters).
        id:
          type: string
          format: uuid
          description: >-
            Unique ID of the address, always provided in response from Vipps
            MobilePay.
        lines:
          type: array
          description: Array of addressLines, for example street name, number, etc.
          items:
            type: string
            example: Robert Levins gate 5
        postCode:
          type: string
          description: Postcode of the address in local country format.
          example: '0154'
      required:
        - lines
        - postCode
        - city
        - country
    ProfileRequest:
      title: Profile
      type: object
      properties:
        scope:
          type: string
          example: name phoneNumber
          description: >-
            A space-separated string list of the required user information
            (e.g., "name phoneNumber") for the payment, in

            accordance with the OpenID Connect specification.

            See the

            [Userinfo user
            guide](https://developer.vippsmobilepay.com/docs/APIs/userinfo-api/userinfo-api-guide#scope)

            for details.

            Possible values are:

            - name

            - address

            - email

            - phoneNumber

            - birthDate

            - nin
    ProfileResponse:
      title: Profile
      type: object
      properties:
        sub:
          type: string
          description: >-
            If `profile.scope` was requested in `createPayment`, this value will
            be populated once

            `state` is `AUTHORIZED`. This can be used towards the

            [Userinfo
            endpoint](https://developer.vippsmobilepay.com/api/userinfo#operation/getUserinfo)

            to fetch required user data.
    PaymentMethod:
      title: PaymentMethod
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethodType'
      required:
        - type
    PaymentMethodResponse:
      title: PaymentMethodResponse
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethodType'
        cardBin:
          description: |-
            The payment card's Bank Identification Number (BIN), that
            identifies which bank has issued the card.
          minLength: 6
          maxLength: 6
          type: string
          example: '540185'
      required:
        - type
    PaymentMethodType:
      type: string
      enum:
        - WALLET
        - CARD
      example: WALLET
      description: >-
        The paymentMethod type to be performed.

        `WALLET` is a card used in the Vipps or MobilePay app.

        `CARD` is free-standing card payments, outside of the Vipps or MobilePay
        app.

        `CARD` has to be combined with a `userFlow` of `WEB_REDIRECT`,

        as the card payment can not be completed in the Vipps or MobilePay app.
    PaymentAdjustment:
      title: PaymentAdjustment
      type: object
      properties:
        modificationAmount:
          $ref: '#/components/schemas/Amount'
        modificationReference:
          $ref: '#/components/schemas/Reference'
      required:
        - modificationAmount
        - modificationReference
    WebhookEvent:
      title: WebhookEvent
      type: object
      x-examples: {}
      properties:
        msn:
          $ref: '#/components/schemas/MSN'
        reference:
          $ref: '#/components/schemas/Reference'
        pspReference:
          $ref: '#/components/schemas/PspReference'
        name:
          $ref: '#/components/schemas/PaymentEventName'
        amount:
          $ref: '#/components/schemas/Amount'
        timestamp:
          type: string
          format: date-time
        idempotencyKey:
          type: string
          description: The Idempotency key of the request.
          nullable: true
        success:
          type: boolean
          description: The outcome of the event
      required:
        - msn
        - reference
        - pspReference
        - name
        - amount
        - timestamp
        - success
    PaymentEvent:
      title: PaymentEvent
      type: object
      x-examples: {}
      properties:
        reference:
          $ref: '#/components/schemas/Reference'
        pspReference:
          $ref: '#/components/schemas/PspReference'
        name:
          $ref: '#/components/schemas/PaymentEventName'
        amount:
          $ref: '#/components/schemas/Amount'
        timestamp:
          type: string
          format: date-time
          example: '2022-12-31T00:00:00Z'
        idempotencyKey:
          type: string
          description: |-
            The idempotency key of the request.
            Specified by the merchant/partner making the API request.
          nullable: true
          maxLength: 50
          example: fb492b5e-7907-4d83-ba20-c7fb60ca35de
        success:
          type: boolean
          description: The outcome of the event
      required:
        - reference
        - pspReference
        - paymentAction
        - amount
        - timestamp
        - success
    Problem:
      title: Problem
      description: |-
        The standard error object, based on RFC 7808.
        See https://developer.vippsmobilepay.com/docs/knowledge-base/errors
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: >-
            A short, human-readable summary of the problem type. It will not
            change from occurrence to occurrence of the problem.
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        status:
          type: integer
          description: The HTTP response code.
        traceId:
          type: string
          description: An id that can be used to facilitate in tracing the error.
        extraDetails:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ExtraDetail'
      required:
        - type
        - title
        - status
        - traceId
    State:
      type: string
      title: State
      description: >-
        The state of the Payment.

        One of:

        - `CREATED`: The user has not yet acted upon the payment.
          Example: The user has received a push message, but not yet opened it.
        - `ABORTED`: The user has aborted the payment before authorization. This
        is a final state.
          Example: The user cancelled instead of accepting the payment.
        - `EXPIRED`: The user did not act on the payment within the payment
        expiration time. This is a final state.
          Example: The user received a push message, but did nothing before the payment request timed out.
        - `AUTHORIZED`: The user has approved the payment. This is a final
        state.
          Example: A payment that has been refunded may have one or more refund events, but the state would be `AUTHORIZED`. 
        - `TERMINATED`: The merchant has terminated the payment via the
        cancelPayment endpoint. This is a final state.
          Example: The merchant was not able to provide the product or service, and has cancelled the payment.
      enum:
        - CREATED
        - ABORTED
        - EXPIRED
        - AUTHORIZED
        - TERMINATED
      x-enum-varnames:
        - CREATED
        - ABORTED
        - EXPIRED
        - AUTHORIZED
        - TERMINATED
    ExtraDetail:
      title: ExtraDetail
      type: object
      properties:
        name:
          type: string
        reason:
          type: string
      required:
        - name
        - reason
    ForceApprove:
      title: ForceApprove
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
        token:
          type: string
          description: >-
            The token value received in the `redirectUrl` property in the Create
            payment response
    QuantityUnitEnum:
      type: string
      title: QuantityUnitEnum
      enum:
        - PCS
        - KG
        - KM
        - MINUTE
        - LITRE
        - KWH
      description: Available units for quantity. Will default to PCS if not set
      default: PCS
      nullable: true
    UnitInfo:
      title: UnitInfo
      type: object
      description: >-
        Optional. If no quantity info is provided the order line will default to
        1 pcs
      x-examples:
        example-1:
          value:
            quantity: '0.822'
            unitPrice: 15000
            quantityUnit: KG
        example-2:
          value:
            quantity: '2'
            unitPrice: 20000
            quantityUnit: PCS
      properties:
        unitPrice:
          type: integer
          minimum: 0
          format: int64
          description: Total price per unit, including tax and excluding discount
          nullable: true
        quantity:
          type: string
          maxLength: 10
          pattern: ^\d+([\.]\d{1,8})?$
          example: '0.822'
          description: Quantity given as a integer or fraction (only for cosmetics)
        quantityUnit:
          $ref: '#/components/schemas/QuantityUnitEnum'
      required:
        - unitPrice
        - quantity
    OrderLine:
      title: OrderLine
      type: object
      description: >-
        Amounts are specified in minor units (i.e., integers with two trailing
        zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
      x-examples:
        OrderLineExample:
          value:
            orderLines:
              - name: socks
                id: line_item_1
                totalAmount: 1000
                totalAmountExcludingTax: 800
                totalTaxAmount: 200
                taxPercentage: 25
                unitInfo:
                  unitPrice: 400
                  quantity: '2.5'
                  quantityUnit: KG
                discount: 0
                productUrl: https://example.com/store/socks
              - name: flip-flops
                id: line_item_2
                totalAmount: 5000
                totalAmountExcludingTax: 4000
                totalTaxAmount: 1000
                taxPercentage: 25
                unitInfo:
                  unitPrice: 2500
                  quantity: '3'
                  quantityUnit: PCS
                discount: 2500
                productUrl: https://example.com/store/flipflops
      properties:
        name:
          type: string
          description: Name of the product in the order line.
          example: socks
        id:
          type: string
          description: The product ID
          example: '1234567890'
        totalAmount:
          type: integer
          description: >-
            Total amount of the order line, including tax and discount. Amounts
            are specified in minor units (i.e., integers with two trailing
            zeros). For example: 10.00 EUR/NOK/DKK should be written as 1000.
          example: 1000
          format: int64
        totalAmountExcludingTax:
          type: integer
          description: >-
            Total amount of order line with discount excluding tax. Amounts are
            specified in minor units (i.e., integers with two trailing zeros).
            For example: 10.00 EUR/NOK/DKK should be written as 1000.
          example: 800
          format: int64
        totalTaxAmount:
          type: integer
          description: >-
            Total tax amount paid for the order line. Amounts are specified in
            minor units (i.e., integers with two trailing zeros). For example:
            10.00 EUR/NOK/DKK should be written as 1000.
          example: 250
          format: int64
        taxPercentage:
          type: integer
          description: >-
            Tax percentage for the order line. Between 0-100. Either this or
            taxRate must be set.
          example: 25
          deprecated: true
          minimum: 0
          maximum: 100
          nullable: true
        taxRate:
          type: integer
          description: >-
            Tax percentage for the order line, represented with 0.01 decimal
            points. 5000 equals 50% . Between 0-10000. Either this or
            taxPercentage must be set.
          example: 2500
          minimum: 0
          maximum: 10000
          nullable: true
        unitInfo:
          $ref: '#/components/schemas/UnitInfo'
        discount:
          type: integer
          description: >-
            Total discount for the order line. Amounts are specified in minor
            units (i.e., integers with two trailing zeros). For example: 1.00
            EUR/NOK/DKK should be written as 100.
          example: 2000
          minimum: 0
          format: int64
          nullable: true
        productUrl:
          type: string
          description: Optional URL linking back to the product at the merchant.
          example: https://example.com/store/socks
          nullable: true
        isReturn:
          type: boolean
          example: false
          description: >-
            Flag for marking the order line as returned. This will make it count
            negative towards all the sums in bottomLine.
          nullable: true
        isShipping:
          example: false
          type: boolean
          description: >-
            Flag for marking the order line as a shipping line. This will be
            shown differently in the app.
          nullable: true
      required:
        - name
        - id
        - totalAmount
        - totalAmountExcludingTax
        - totalTaxAmount
    CurrencyEnum:
      type: string
      title: CurrencyEnum
      enum:
        - NOK
        - DKK
        - EUR
      description: Currency information
      nullable: true
    ShippingInfo:
      title: ShippingInfo
      type: object
      description: >-
        Deprecated, use a regular orderLine with "isShipping" flag. Using this
        will result in faulty calculation of sum and tax.
      deprecated: true
      properties:
        amount:
          type: integer
          minimum: 0
          format: int64
          description: Total amount for the shipping, including tax and discount
          example: 1000
          nullable: true
        amountExcludingTax:
          type: integer
          minimum: 0
          format: int64
          description: Total amount for shipping excluding tax
          example: 1000
          nullable: true
        taxAmount:
          type: integer
          minimum: 0
          format: int64
          description: Total tax amount paid for the shipping
          example: 250
          nullable: true
        taxPercentage:
          type: integer
          minimum: 0
          maximum: 100
          description: Tax-percentage for the Shipping
          example: 25
          nullable: true
      required:
        - amount
        - amountExcludingTax
        - taxAmount
        - taxPercentage
    PaymentSources:
      type: object
      x-examples:
        PaymentSourcesExample:
          giftCard: 200
          card: 50
          voucher: 25
          cash: 25
      properties:
        giftCard:
          type: integer
          nullable: true
        card:
          type: integer
          nullable: true
        voucher:
          type: integer
          nullable: true
        cash:
          type: integer
          nullable: true
    BarcodeFormatEnum:
      type: string
      title: BarcodeFormatEnum
      enum:
        - EAN-13
        - CODE 39
        - CODE 128
      nullable: true
    Barcode:
      title: Barcode
      type: object
      properties:
        format:
          $ref: '#/components/schemas/BarcodeFormatEnum'
        data:
          type: string
          nullable: true
      required:
        - format
        - data
    BottomLine:
      title: BottomLine
      type: object
      description: >-
        Summary of the order. Total amount and total. Amounts are specified in
        minor units (i.e., integers with two trailing zeros). For example: 10.00
        EUR/NOK/DKK should be written as 1000.
      x-examples:
        BottomLineExample:
          value:
            currency: NOK
            tipAmount: 0
            posId: pos_122
            paymentSources:
              card: 100
              giftCard: 50
            barcode:
              format: EAN-13
              data: '123456'
            receiptNumber: '1234567'
      properties:
        currency:
          $ref: '#/components/schemas/CurrencyEnum'
        tipAmount:
          type: integer
          description: >-
            Tip amount for the order. Amounts are specified in minor units
            (i.e., integers with two trailing zeros). For example: 10.00
            EUR/NOK/DKK should be written as 1000.
          example: 2000
          minimum: 0
          format: int64
          nullable: true
        giftCardAmount:
          type: integer
          description: Amount paid by gift card or coupon.
          example: 20000
          minimum: 0
          format: int64
          deprecated: true
          nullable: true
        posId:
          type: string
          description: POS ID is the device number of the POS terminal
          nullable: true
        totalAmount:
          type: integer
          description: >-
            Deprecated, sum will be calculated based on the sum of the
            orderLines
          format: int64
          deprecated: true
          nullable: true
        totalTax:
          type: integer
          description: >-
            Deprecated, tax will be calculated based on the sum of the
            totalTaxAmount field on each orderLine
          minimum: 0
          format: int64
          deprecated: true
          nullable: true
        totalDiscount:
          type: integer
          description: >-
            Deprecated, discount will be calculated based on the sum of the
            discount field on each orderLine
          minimum: 0
          format: int64
          deprecated: true
          nullable: true
        shippingAmount:
          type: integer
          description: >-
            Deprecated, use a regular orderLine with "isShipping" flag. Using
            this will result in faulty calculation of sum and tax.
          minimum: 0
          format: int64
          deprecated: true
          nullable: true
        shippingInfo:
          $ref: '#/components/schemas/ShippingInfo'
        paymentSources:
          $ref: '#/components/schemas/PaymentSources'
        barcode:
          $ref: '#/components/schemas/Barcode'
        receiptNumber:
          type: string
          nullable: true
        terminalId:
          type: string
          description: Deprecated, use "posId" instead.
          nullable: true
          deprecated: true
      required:
        - currency
    Receipt:
      title: Receipt
      type: object
      x-examples:
        ReceiptExample:
          orderLines:
            - name: socks
              id: '1234567890'
              totalAmount: 1000
              totalAmountExcludingTax: 800
              totalTaxAmount: 200
              taxPercentage: 25
              unitInfo:
                unitPrice: 0
                quantity: '0.822'
                quantityUnit: PCS
              discount: 0
              productUrl: https://example.com/store/socks
              isReturn: false
              isShipping: false
          bottomLine:
            tipAmount: 0
            currency: NOK
            posId: string
            paymentSources:
              giftCard: 0
              card: 0
              voucher: 0
              cash: 0
            barcode:
              format: EAN-13
              data: '123456'
            receiptNumber: '1234567'
      properties:
        orderLines:
          type: array
          description: >-
            Amounts are specified in minor units (i.e., integers with two
            trailing zeros). For example: 10.00 EUR/NOK/DKK should be written as
            1000.
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderLine'
        bottomLine:
          $ref: '#/components/schemas/BottomLine'
      required:
        - orderLines
        - bottomLine
  parameters:
    Merchant-Serial-Number:
      name: Merchant-Serial-Number
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/MSN'
    APIM-Subscription-Key:
      name: Ocp-Apim-Subscription-Key
      in: header
      required: true
      schema:
        type: string
        example: da7d5b0e18a84aeda961c0c31b75c2a9
      description: |-
        The subscription key for a sales unit.
         See [API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys/).
    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](https://developer.vippsmobilepay.com/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](https://developer.vippsmobilepay.com/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](https://developer.vippsmobilepay.com/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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: 1.2.1
    Payment-Reference-ID:
      name: Reference
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    Idempotency-Key:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 50
      description: >-
        Idempotency key for the request, ensures idempotent actions.

        See
        [idempotency](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers#idempotency)
      example: fb492b5e-7907-4d83-ba20-c7fb60ca35de
  securitySchemes:
    Bearer-Authorization:
      name: Authorization
      type: apiKey
      in: header
      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 the

        [`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost)

        endpoint.

        It is valid for 1 hour in the test environment and 24 hours in the
        production environment.
  responses:
    GetPaymentResponse:
      description: Get Payment response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetPaymentResponse'
    CreatePaymentResponse:
      description: Create Payment response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreatePaymentResponse'
          examples:
            UrlRedirect:
              value:
                redirectUrl: >-
                  https://landing.vipps.no?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni
                reference: acme-shop-123-order123abc
            QrImageUrl:
              value:
                redirectUrl: >-
                  https://qr-image.vipps.no/v1?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni
                reference: acme-shop-123-order123abc
            NativeRedirect:
              value:
                redirectUrl: vipps://token=abc123
                reference: racme-shop-123-order123abc
            PushFlow:
              value:
                reference: acme-shop-123-order123abc
    AdjustResponse:
      description: Adjustment response
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ModificationResponse'
      headers: {}
    ProblemResponse:
      description: Standard problem response.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers: {}
  examples: {}
security:
  - Bearer-Authorization: []
