openapi: 3.0.0
info:
  description: >
    The eCom API allows you to initiate payments, get payment details, capture
    payments, and refund payments.

    See the [API Guide](/docs/APIs/ecom-api/vipps-ecom-api) for more details.
  version: 2.0.3
  title: eCommerce API
tags:
  - name: eCom API
    description: >-
      Functionality provided by the eCommerce API. For details, see the [API
      Guide](/docs/APIs/ecom-api/vipps-ecom-api).
  - name: Merchant Endpoints
    description: >-
      These endpoints must be implemented by the merchant, and are called by
      Vipps.
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:
  /consentRemovalPrefix/v2/consents/{userId}:
    delete:
      tags:
        - Merchant Endpoints
      summary: Remove User Consent (for Vipps Hurtigkasse (express checkout))
      description: >-
        This API endpoint on the merchant side allows Vipps to send
        consent-removal requests to the merchant. When receiving requests, the
        merchant is obliged to remove the user details permanently, as per the
        GDPR guidelines. Request syntax:
        'DELETE:{consentRemovalPrefix}/v2/consents/{userId}'. Vipps will add
        `/v2/consents/{userId}` to the end of the `consentRemovalPrefix` URL.
        URLs passed to Vipps must validate, see the [API
        guide](/docs/APIs/ecom-api/vipps-ecom-api/#url-validation). We do not
        send requests to all ports, so use common ports such as: 80, 443, 8080.
        The URL must use HTTPS.
      operationId: removeUserConsentUsingDELETE
      parameters:
        - name: userId
          in: path
          description: >-
            URL-encoded `userId` provided when requesting user information from
            Vipps. Received by callback or with `/detail` request.
          required: true
          schema:
            type: string
          example: uiJskNQ6qNN1iwN891uuob==
      responses:
        '200':
          description: Remove User Consent (for Vipps Hurtigkasse (express checkout))
  /shippingDetailsPrefix/v2/payments/{orderId}/shippingDetails:
    post:
      tags:
        - Merchant Endpoints
      summary: Fetch Shipping Cost & Method (for Vipps Hurtigkasse (express checkout))
      description: >-
        This API endpoint on the merchant side allows Vipps to get the shipping
        cost and method, based on the provided address and product details. The
        primary use of this service is to support Vipps Hurtigkasse (express
        checkout), where Vipps must present the shipping cost and method to the
        user. There is a *10 second timeout* for these requests, to ensure a
        good user experience, and thus requires a quick reply from the
        merchant's server for successful payments. Request syntax:
        'POST:{shippingDetailsPrefix}/v2/payments/{orderId}/shippingDetails'.
        Vipps will add `/v2/payments/{orderId}/shippingDetails` to the end of
        the `shippingDetailsPrefix` URL. URLs passed to Vipps must be validated,
        see the [API guide](/docs/APIs/ecom-api/vipps-ecom-api/#url-validation).
        We do not send requests to all ports, so use common ports such as: 80,
        443, 8080. The URL must use HTTPS.
      operationId: fetchShippingCostUsingPOST
      parameters:
        - name: orderId
          in: path
          description: orderId
          required: true
          schema:
            type: string
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
        - name: Authorization
          in: header
          description: >-
            The token provided by the merchant in the initiate payment request
            as `authToken` (an optional parameter). Vipps uses this token when
            making calls to the merchant's servers. Used so that the merchant
            may authenticate the request from Vipps.
          schema:
            type: string
          example: ae0cb90d91b4a84a
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ShippingCostAndMethod'
        description: ShippingCostAndMethod
        required: true
      responses:
        '200':
          description: Fetch shipping cost and method.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/schemas-FetchShippingCostResponse'
  /callbackPrefix/v2/payments/{orderId}:
    post:
      tags:
        - Merchant Endpoints
      summary: 'Callback : Transaction Update'
      description: >-
        This API call allows Vipps to send the transaction details. For regular
        eCom payments, the order and transaction details will be shared. For
        Vipps Hurtigkasse (express checkout) payments, it will provide user and
        shipping details, in addition to the order and transaction details.
        Request syntax: 'POST:{callbackPrefix}/v2/payments/{orderId}'. Vipps
        will add `/v2/payments/{orderId}` to the end of the `callbackPrefix`
        URL. URLs passed to Vipps must be validated, see the [API
        guide](/docs/APIs/ecom-api/vipps-ecom-api/#url-validation). We do not
        send requests to all ports, so use common ports such as: 80, 443, 8080.
        The URL must use HTTPS.
      operationId: transactionUpdateCallbackForRegularPaymentUsingPOST
      parameters:
        - name: orderId
          in: path
          description: orderId
          required: true
          schema:
            type: string
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
        - $ref: '#/components/parameters/parameters-Authorization'
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/schemas-TransactionUpdateCallbackOneOf'
        description: >-
          The body of the request made by Vipps. It will differ if the request
          is a regular or express payment.
        required: true
      responses:
        '200':
          description: All ok
  /ecomm/v2/payments:
    post:
      tags:
        - eCom API
      summary: Initiate Payment
      description: >-
        This API call lets the merchants initiate payments. The
        `merchantSerialNumber` (MSN) specifies which sales unit the payment is
        for. Payments are uniquely identified with the `merchantSerialNumber`
        and `orderId` together. The merchant-provided `orderId` must be unique
        per sales unit. Once the transaction is successfully initiated in Vipps,
        you will receive a response with a URL that will direct the customer to
        the Vipps landing page (when using a laptop/desktop), or app-switch to
        Vipps (when using a phone). The landing page detects if the request
        comes from a mobile or laptop/desktop device, and if on a mobile device
        automatically switches to the Vipps app, if it is installed. The
        merchant may also pass the optional 'isApp: true' parameter that will
        make Vipps respond with a app-switch deeplink that will take the
        customer directly to the Vipps app. This is normally not necessary, as
        Vipps handles this automatically. URLs passed to Vipps must validate,
        see the API guide. The URLs must use HTTPS.
      operationId: initiatePaymentV3UsingPOST
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Content-Type'
        - $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'
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/InitiatePaymentCommand'
        description: initiatePaymentCommand
        required: true
      callbacks:
        callbackExpress:
          '{$request.body#/merchantInfo/callbackPrefix}/v2/payments/{$request.body#/transaction/orderId}':
            post:
              summary: 'Callback : Transaction Update'
              description: >-
                This API call lets Vipps send the transaction details to the
                merchant. For regular eCom payments the order and transaction
                details will be shared. For Vipps Hurtigkasse (express checkout)
                payments it will in addition provide user details and shipping
                details. Vipps will add `/v2/payments/{orderId}` to the end of
                this URL. Vipps has a *3 second timeout* for these requests, and
                thus requires a quick reply from the merchant's server for
                successful payments. URLs passed to Vipps must validate, see the
                API guide. We don't send requests to all ports, so to be safe
                use common ports such as: 80, 443, 8080. The URL must use HTTPS.
              operationId: >-
                InitiatePaymentTransactionUpdateCallbackForRegularPaymentUsingPOSTExpress
              parameters:
                - name: orderId
                  in: path
                  description: orderId
                  required: true
                  schema:
                    type: string
              responses:
                '200':
                  description: Vipps does not require a response for this request.
              requestBody:
                content:
                  application/json;charset=UTF-8:
                    schema:
                      $ref: '#/components/schemas/ExpressCheckOutPaymentRequest'
        callbackRegular:
          '{$request.body#/merchantInfo/callbackPrefix}/v2/payments/{$request.body#/transaction/orderId}':
            post:
              summary: 'Callback : Transaction Update'
              description: >-
                This API call lets Vipps send the transaction details to the
                merchant. For regular eCom payments the order and transaction
                details will be shared. For Vipps Hurtigkasse (express checkout)
                payments it will in addition provide user details and shipping
                details. Vipps will add `/v2/payments/{orderId}` to the end of
                this URL. Vipps has a *3 second timeout* for these requests, and
                thus requires a quick reply from the merchant's server for
                successful payments. URLs passed to Vipps must validate, see the
                API guide. We don't send requests to all ports, so to be safe
                use common ports such as: 80, 443, 8080. The URL must use HTTPS.
              operationId: >-
                InitiatePaymentTransactionUpdateCallbackForRegularPaymentUsingPOSTExpress
              parameters:
                - name: orderId
                  in: path
                  description: orderId
                  required: true
                  schema:
                    type: string
              responses:
                '200':
                  description: Vipps does not require a response for this request.
              requestBody:
                content:
                  application/json;charset=UTF-8:
                    schema:
                      $ref: '#/components/schemas/RegularCheckOutPaymentRequest'
        consentRemoval:
          '{$request.body#/merchantInfo/consentRemovalPrefix}/v2/consents/{userId}':
            delete:
              summary: Remove User Consent (for Vipps Hurtigkasse (express checkout))
              description: >-
                This API endpoint on the merchant side lets Vipps send consent
                removal requests to merchant. When receiving requests the
                merchant is obliged to remove the user details permanently, as
                per the GDPR guidelines. Vipps will add `/v2/consents/{userId}`
                to the end of this URL. URLs passed to Vipps must validate, see
                the API guide. We don't send requests to all ports, so to be
                safe use common ports such as: 80, 443, 8080. The URL must use
                HTTPS.
              operationId: removeUserConsentUsingDELETE
              parameters:
                - name: userId
                  in: path
                  description: >-
                    URL-encoded userId provided when requesting user information
                    from Vipps. Received by callback or get detail request.
                  required: true
                  schema:
                    type: string
                  example: uiJskNQ6qNN1iwN891uuob==
              responses:
                '200':
                  description: OK
        shippingDetails:
          '{$request.body#/merchantInfo/shippingDetailsPrefix}/v2/payments/{$request.body#/transaction/orderId}/shippingDetails':
            post:
              summary: >-
                Fetch shipping cost and method (for Vipps Hurtigkasse (express
                checkout))
              description: >-
                This API endpoint on the merchant side lets Vipps get the
                shipping cost and method based on the provided address and
                product details. The primary use of this service is Vipps
                Hurtigkasse (express checkout) where Vipps needs to present
                shipping cost and method to the Vipps user. Vipps will add
                `/v2/payments/{orderId}/shippingDetails` to the end of this URL.
                Vipps has a *10 second timeout* for these requests, and thus
                requires a quick reply from the merchant's server for successful
                payments. If the merchant does not respond in time, the user
                will get an error in Vipps saying "No shipping methods found".
                URLs passed to Vipps must validate, see the API guide. We don't
                send requests to all ports, so to be safe use common ports such
                as: 80, 443, 8080. The URL must use HTTPS.
              operationId: fetchShippingCostUsingPOST
              parameters:
                - name: orderId
                  in: path
                  description: orderId
                  required: true
                  schema:
                    type: string
              responses:
                '200':
                  description: Fetch Shipping Cost & Method.
                  content:
                    application/json;charset=UTF-8:
                      schema:
                        $ref: '#/components/schemas/FetchShippingCostResponse'
              requestBody:
                content:
                  application/json;charset=UTF-8:
                    schema:
                      $ref: '#/components/schemas/ShippingCostAndMethod'
                description: ShippingCostAndMethod
                required: true
      responses:
        '200':
          description: Response for Initiate Payment
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/PaymentInitiationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/payments/{orderId}/capture:
    post:
      tags:
        - eCom API
      summary: Capture Payment
      description: >-
        This API call lets merchant capture the reserved amount. Amount to
        capture cannot be higher than reserved. The API also allows capturing a
        partial amount of the reserved amount. Partial capture can be called as
        many times as required so long there is a remaining reserved amount to
        capture. The transaction text is not optional and is used as a proof of
        delivery (tracking code, consignment number etc.). In a case of direct
        capture, both the reservation and the capture are executed in a single
        operation. It is important to check the response, and the capture is
        only successful when the response is `HTTP 200 OK`.
      operationId: capturePaymentUsingPOST
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - in: header
          name: X-Request-Id
          required: true
          description: >-
            Used for making requests idempotent. Adding the `X-Request-Id`
            header will allow repeated requests without it making additional
            changes. Unique for orderId, merchantSerialNumber and endpoint.
            Required for making partial captures. You can use any unique ID for
            your X-Request-Id. Max 40 characters.
          schema:
            type: string
          example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS
        - $ref: '#/components/parameters/Content-Type'
        - $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'
      requestBody:
        $ref: '#/components/requestBodies/PaymentActionsRequest'
      responses:
        '200':
          description: Capture payment response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/payments/{orderId}/cancel:
    put:
      tags:
        - eCom API
      summary: Cancel Payment
      description: >-
        This API call lets merchants cancel a reserved or initiated transaction
        as long as it is less than 6 months old. In order to enable cancellation
        of remaining funds after partial capture, the
        `shouldReleaseRemainingFunds` flag must be set. Please note that the
        payment will be cancelled by Vipps even in cases of communication errors
        during an initiate payment service call between Vipps and
        PSP/Acquirer/Issuer and even in cases where the customer has confirmed a
        payment. Note this means you cannot cancel a captured payment.
      operationId: cancelPaymentRequestUsingPUT
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Content-Type'
        - $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'
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/CancelPaymentActionRequest'
        description: paymentActionsRequest
        required: true
      responses:
        '200':
          description: Cancel payment response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CancelTransactionResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/payments/{orderId}/refund:
    post:
      tags:
        - eCom API
      summary: 'Refund Payment '
      description: >-
        The API lets a merchant do a refund of an already captured transaction.
        There is an option to do a partial refund of the captured amount.
        Refunded amount cannot be larger than captured. Time frame for issuing a
        refund for a payment is 365 days from the date payment has been
        captured. If the refund payment service call is called after the refund
        time frame, service call will respond with an error. Refunded funds will
        be transferred from the merchant account to the customer credit card
        that was used in payment flow. Pay attention that in order to perform
        refund, there must be enough funds at merchant settlements account.
      operationId: refundPaymentUsingPOST
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Content-Type'
        - $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'
        - in: header
          name: X-Request-Id
          required: true
          description: >-
            Used for making requests idempotent. Adding the `X-Request-Id`
            header will allow repeated requests without it making additional
            changes. Unique for orderId, merchantSerialNumber and endpoint. Max
            40 characters. Required if the amount is partial.
          schema:
            type: string
          example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS
      requestBody:
        $ref: '#/components/requestBodies/PaymentActionsRequest'
      responses:
        '200':
          description: Refund payment response
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/RefundTransactionResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/integration-test/payments/{orderId}/approve:
    post:
      tags:
        - eCom API
      summary: Force Approve Payment
      description: >-
        This endpoint lets developers approve a payment through the eCom API
        without the use of the Vipps app. This is useful for automated testing.
        Express checkout is not supported for this endpoint. The endpoint is
        only available in our Test environment. Attempted use of the endpoint in
        production is not allowed, and will fail. Important: All test users must
        manually approve at least one payment in Vipps (using the app) before
        this endpoint can be used for that user.
      operationId: integrationTestApprovePayment
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Content-Type'
        - $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'
        - in: header
          name: X-Request-Id
          description: >-
            Id used for making requests idempotent. Adding this ID will allow
            the merchant to retry requests without it making additional changes.
            Unique for orderId, merchantSerialNumber and endpoint. Max 40
            characters.
          schema:
            type: string
          example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS
      requestBody:
        $ref: '#/components/requestBodies/ForceApproveRequest'
      responses:
        '200':
          description: Force approve payment response
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/payments/{orderId}/details:
    get:
      tags:
        - eCom API
      summary: Get Payment Details
      description: >-
        This API call lets merchant get the details of a payment transaction.
        Service call returns detailed transaction history of given payment where
        events are sorted from newest to oldest for when the transaction
        occurred.
      operationId: getPaymentDetailsUsingGET
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Content-Type'
        - $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 payment Details
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/TransactionDetails'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ecomm/v2/payments/{orderId}/status:
    get:
      deprecated: true
      tags:
        - eCom API
      summary: 'Deprecated: Get Order Status'
      description: >-
        This deprecated endpoint lets the merchant get the status of the last
        payment transaction. The response may be confusing. Please use
        `/details` instead, as it offers more information.
      operationId: getOrderStatusUsingGET
      parameters:
        - name: orderId
          in: path
          description: The `orderId` is specified when initiating the payment.
          required: true
          schema:
            type: string
        - $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 order status
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        default:
          $ref: '#/components/responses/ErrorResponse'
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
        the
            [`POST:/accesstoken/get`](/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.
      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 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
        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.
      schema:
        type: string
        maxLength: 30
      example: WooCommerce
    Vipps-System-Version:
      name: Vipps-System-Version
      in: header
      description: The version number of the ecommerce solution.
      schema:
        type: string
        maxLength: 30
      example: '5.4'
    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.
      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).
      schema:
        type: string
        maxLength: 30
      example: 1.2.1
    Content-Type:
      in: header
      name: Content-Type
      description: The content type must be `application/json`
      schema:
        type: string
      example: application/json
    parameters-Authorization:
      in: header
      name: Authorization
      description: >-
        The token provided by the merchant in the initiate payment request as
        `authToken` (an optional parameter). Vipps uses this token when making
        calls to the merchant's servers. Used so that the merchant may
        authenticate the request from Vipps.
      required: true
      schema:
        type: string
      example: ae0cb90d91b4a84a
  requestBodies:
    PaymentActionsRequest:
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: '#/components/schemas/PaymentActionsRequest'
      description: paymentActionsRequest
      required: true
    ForceApproveRequest:
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: '#/components/schemas/ForceApproveRequest'
      description: ForceApproveRequest
      required: true
  schemas:
    PaymentActionsRequest:
      type: object
      properties:
        merchantInfo:
          $ref: '#/components/schemas/MerchantInfoPayment'
        transaction:
          $ref: '#/components/schemas/Transaction'
    ForceApproveRequest:
      type: object
      properties:
        customerPhoneNumber:
          type: string
          description: >-
            The customer's phone number, if available.

            Format: 8 digits.


            **Please note:** The phone number 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 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.
          pattern: ^\d{8}$
        token:
          type: string
          description: >-
            The token value received in the `url` property in the Initiate
            response
          example: eyJraWQiOiJqd3R
    Address:
      type: object
      required:
        - addressLine1
        - city
        - country
        - postCode
      properties:
        addressLine1:
          type: string
          description: Address Line 1
          example: Robert Levins gate 5
        addressLine2:
          type: string
          description: Address Line 2
          example: 'Att: Rune Garborg'
        city:
          type: string
          description: City
          example: Oslo
        country:
          type: string
          description: Country
          example: Norway
          enum:
            - Norway
        postCode:
          type: string
          description: Post Code
          example: '0154'
    AddressExpress:
      type: object
      required:
        - addressLine1
        - city
        - country
        - postCode
      properties:
        addressLine1:
          type: string
          description: Address Line 1
          example: Robert Levins gate 5
        addressLine2:
          type: string
          description: Address Line 2
          example: 'Att: Rune Garborg'
        city:
          type: string
          description: City
          example: Oslo
        country:
          type: string
          description: Country
          example: Norway
          enum:
            - Norway
        zipCode:
          type: string
          description: Postcode (apologies for not using `postCode` as elsewhere)
          example: '0154'
    PaymentShippingDetails:
      type: object
      description: >-
        The shipping details for this payment. Only used for Vipps Hurtigkasse
        (express payment).
      required:
        - shippingCost
        - shippingMethod
        - shippingMethodId
      properties:
        address:
          $ref: '#/components/schemas/Address'
        shippingCost:
          $ref: '#/components/schemas/ShippingCost'
        shippingMethod:
          type: string
          description: >-
            The description of the shipping method. Typically the name of the
            shipping company and the name of their service. Max length: 256
            characters. Recommended length for readability on most screens: 25
            characters.
          example: Posten Servicepakke
          maxLength: 256
        shippingMethodId:
          type: string
          maxLength: 100
          example: posten-servicepakke
    TransactionLogHistory:
      type: object
      required:
        - operation
        - amount
        - operationSuccess
        - transactionText
      properties:
        amount:
          type: integer
        operation:
          type: string
          example: RESERVE
          description: >-
            The operation that was performed for this log entry. See the [API
            guide](/docs/APIs/ecom-api/vipps-ecom-api#requests-and-responses)
            for more information.
          enum:
            - INITIATE
            - RESERVE
            - SALE
            - CAPTURE
            - REFUND
            - CANCEL
            - VOID
        operationSuccess:
          type: boolean
          description: If the corresponding operation was successful.
          example: true
        requestId:
          type: string
          description: >-
            The idempotent request ID provided by the merchant for the
            operation.
          example: '12983921873981899000'
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2019-02-05T12:27:42.311Z'
        transactionId:
          type: string
          description: Identifies the transaction
          example: '5001446662'
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
    CancelTransaction:
      type: object
      required:
        - transactionText
      properties:
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
    UserDetails:
      type: object
      description: >-
        Only used for Vipps Hurtigkasse (express payment) and when using
        [userinfo](/docs/APIs/userinfo-api).
      required:
        - email
        - firstName
        - lastName
        - mobileNumber
        - userId
      properties:
        email:
          type: string
          description: Email address
          example: user@example.com
        firstName:
          type: string
          description: First name
          example: Ada
        lastName:
          type: string
          description: Last name
          example: Lovelace
        mobileNumber:
          type: string
          description: The phone number, 8 digits (not MSISDN format as Userinfo).
          example: '12345678'
          minLength: 8
          maxLength: 8
          pattern: ^\d{8}$
        userId:
          type: string
          example: uiJskNQ6qNN1iwN891uuob==
          maxLength: 50
          description: >-
            Identifies a user in Vipps. Merchant is required to store this field
            for future references.
          pattern: ^[\d\w\/=+]+$
    CallbackTransactionInfoRegular:
      type: object
      required:
        - amount
        - status
        - timeStamp
      properties:
        amount:
          type: integer
          description: >-
            Ordered amount. Amounts are specified in minor units. For Norwegian
            kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.
            Minimum 1 NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - RESERVED
            - SALE
            - CANCELLED
            - REJECTED
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API guide](/docs/APIs/ecom-api/vipps-ecom-api#callbacks)
            for more information.
          example: RESERVED
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps
          example: '5432123456'
    CallbackTransactionInfoExpress:
      type: object
      required:
        - amount
        - status
        - timeStamp
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - RESERVE
            - SALE
            - CANCELLED
            - REJECTED
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API guide](/docs/APIs/ecom-api/vipps-ecom-api#callbacks)
            for more information.
          example: RESERVE
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps
          example: '5432123456'
    OrderStatusInfoTransactionInfo:
      type: object
      required:
        - amount
        - status
        - timeStamp
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - INITIATE
            - REGISTER
            - RESERVE
            - SALE
            - CAPTURE
            - REFUND
            - CANCEL
            - VOID
            - FAILED
            - REJECTED
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API
            guide](/docs/APIs/ecom-api/vipps-ecom-api#requests-and-responses)
            for more information.
          example: RESERVE
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps
          example: '5432123456'
    TransactionInfo:
      type: object
      required:
        - amount
        - status
        - timeStamp
        - transactionId
        - transactionText
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - Cancelled
            - Captured
            - Refund
          example: Captured
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API
            guide](/docs/APIs/ecom-api/vipps-ecom-api#requests-and-responses)
            for more information.
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the order was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps
          pattern: ^\d{10,}$
          example: '5432123456'
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
    TransactionInfoCancel:
      type: object
      required:
        - amount
        - status
        - timeStamp
        - transactionText
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - Cancelled
            - Captured
            - Refund
          example: Captured
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API
            guide](/docs/APIs/ecom-api/vipps-ecom-api#requests-and-responses)
            for more information.
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the order was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps
          pattern: ^\d{10,}$
          example: '5432123456'
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
    TransactionDetails:
      description: The full details, including the log/history, for the payment.
      type: object
      properties:
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        shippingDetails:
          $ref: '#/components/schemas/PaymentShippingDetails'
        transactionLogHistory:
          type: array
          description: Array of transaction operations. Sorted from newest to oldest.
          items:
            $ref: '#/components/schemas/TransactionLogHistory'
        transactionSummary:
          $ref: '#/components/schemas/TransactionSummary'
        userDetails:
          $ref: '#/components/schemas/UserDetails'
        sub:
          type: string
          description: >-
            The `sub` is the user identifier, and is included in the response
            for Express Checkout and when a `scope` is specified. This should be
            used with the Userinfo API:
            [`GET:/vipps-userinfo-api/userinfo/{sub}`](/api/userinfo#operation/getUserinfo).
            **Please note:** The `sub` is added asynchronously, so if the
            `/details` request is made within (milli)seconds of the payment
            approval in the app, it may not be available, and thus not included
            in the response. If that happens, simply make another `/details`
            request.
    PaymentInitiationResponse:
      type: object
      required:
        - orderId
        - url
      properties:
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the orderId
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        url:
          type: string
          description: >-
            URL to redirect the user to Vipps landing page or a deeplink URL to
            open Vipps app, if `isApp` was set as true. The landing page will
            also redirect a user to the app if the user is using a mobile
            browser. This link will timeout after 10 minutes. This .c is a
            shortened deeplink URL. The URL received from Vipps should not be
            changed, and the format may change without notice.
          example: >-
            https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJraWQiOiJqd3RrZXkiLC
            <snip>
    ShippingDetailsRequest:
      type: object
      required:
        - address
        - shippingCost
        - shippingMethod
        - shippingMethodId
      properties:
        address:
          $ref: '#/components/schemas/AddressExpress'
        shippingCost:
          $ref: '#/components/schemas/ShippingCost'
        shippingMethod:
          type: string
          description: >-
            The description of the shipping method. Typically the name of the
            shipping company and the name of their service. Max length: 256
            characters. Recommended length for readability on most screens: 25
            characters.
          example: Posten Servicepakke
          maxLength: 256
        shippingMethodId:
          type: string
          maxLength: 100
          example: posten-servicepakke
    RefundTransactionResponse:
      description: >-
        Some details about the orderId is included, but for the full details a
        call to /details is required.
      type: object
      required:
        - orderId
      properties:
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transaction:
          $ref: '#/components/schemas/TransactionInfo'
        transactionSummary:
          $ref: '#/components/schemas/TransactionSummary'
    TransactionResponse:
      description: >-
        Some details about the orderId is included, but for the full details a
        call to /details is required.
      type: object
      required:
        - orderId
      properties:
        paymentInstrument:
          type: string
          description: >-
            Text which describes what instrument was used to complete the
            payment. Not included until a user has chosen and approved in the
            app.
          example: Mastercard
          pattern: ^[a-zA-Z0-9-]{1,30}$
          maxLength: 30
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionInfo:
          $ref: '#/components/schemas/TransactionInfo'
        transactionSummary:
          $ref: '#/components/schemas/TransactionSummary'
    CancelTransactionResponse:
      description: >-
        Some details about the `orderId` is included, but for the full details a
        call to /details is required.
      type: object
      required:
        - orderId
      properties:
        paymentInstrument:
          type: string
          description: >-
            Text which describes what instrument was used to complete the
            payment. Not included until a user has chosen and approved in the
            app.
          example: Mastercard
          pattern: ^[a-zA-Z0-9-]{1,30}$
          maxLength: 30
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionInfo:
          $ref: '#/components/schemas/TransactionInfoCancel'
        transactionSummary:
          $ref: '#/components/schemas/TransactionSummary'
    MerchantInfoPayment:
      type: object
      required:
        - merchantSerialNumber
      properties:
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
    ShippingDetails:
      type: object
      required:
        - isDefault
        - shippingCost
        - shippingMethod
        - shippingMethodId
      properties:
        isDefault:
          type: string
          enum:
            - 'Y'
            - 'N'
        priority:
          type: integer
          description: |-
            Determines the order in which the shipping methods are presented
            to the user in the app, sorted in ascending order.
          example: 1
        shippingCost:
          $ref: '#/components/schemas/ShippingCost'
        shippingMethod:
          type: string
          description: >-
            The description of the shipping method. Typically the name of the
            shipping company and the name of their service. Max length: 256
            characters. Recommended length for readability on most screens: 25
            characters.
          example: Posten Servicepakke
          maxLength: 256
        shippingMethodId:
          type: string
          maxLength: 100
          example: posten-servicepakke
    ShippingCost:
      type: number
      format: double
      description: >-
        Shipping cost in NOK. Please note that this is not øre, and different
        from other amounts.
      example: 499
      minimum: 0
    InitiatePaymentCommand:
      type: object
      required:
        - customerInfo
        - merchantInfo
        - transaction
      properties:
        customerInfo:
          $ref: '#/components/schemas/CustomerInfo'
        merchantInfo:
          $ref: '#/components/schemas/MerchantInfo'
        transaction:
          $ref: '#/components/schemas/TransactionInfoInitiate'
    TransactionInfoInitiate:
      type: object
      required:
        - amount
        - orderId
        - transactionText
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
        skipLandingPage:
          type: boolean
          example: false
          default: false
          description: >-
            Skips the landing page for whitelisted sales units. Requires a valid
            customerInfo.mobileNumber.
        scope:
          type: string
          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](/docs/APIs/userinfo-api/userinfo-api-guide#scope)

            for details.

            Possible values are:

            - name

            - address

            - email

            - phoneNumber

            - birthDate

            - nin
          example: name phoneNumber
        additionalData:
          $ref: '#/components/schemas/AdditionalTransactionData'
        useExplicitCheckoutFlow:
          type: boolean
          description: >-
            Use the new and improved extended UX flow for express checkout which
            forces users to confirm their address and shipping choices
          default: false
          example: true
    AdditionalTransactionData:
      description: >-
        Additional data about the payment. This is only required in special
        situations, and may usually be ignored.
      type: object
      required:
        - passengerName
        - airlineCode
        - airlineDesignatorCode
        - agencyInvoiceNumber
      properties:
        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
        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. IATA:
            https://www.iata.org/en/youandiata/airports/
          format: IATA 2-letter airline code
          example: KL
          minLength: 2
          maxLength: 2
        ticketNumber:
          type: string
          description: The ticket's unique identifier.
          minLength: 1
          maxLength: 150
          example: 074-5799804843
        agencyInvoiceNumber:
          type: string
          description: >-
            Reference number for the invoice, issued by the agency. IATA:
            https://www.iata.org/en/youandiata/travel-agents/
          minLength: 1
          maxLength: 6
          example: '123456'
    MerchantInfo:
      description: Information about the merchant.
      type: object
      required:
        - callbackPrefix
        - fallBack
        - merchantSerialNumber
      properties:
        authToken:
          type: string
          description: >-
            An optional authorization token that the merchant could share to
            make callbacks more secure. If provided, this token will be returned
            as an `Authorization` header for our callbacks. This includes
            shipping details and callback.
          maxLength: 255
          example: iOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImllX3FXQ1hoWHh0MXpJ
        callbackPrefix:
          type: string
          description: >-
            This is an URL for Vipps to call at the merchant's server to provide
            updated information about the order after the payment request.
            Domain name and context path should be provided by merchant as the
            value for this parameter. Vipps will add `/v2/payments/{orderId}` to
            the end or this URL. URLs passed to Vipps must validate, see the API
            guide. We don't send requests to all ports, so to be safe use common
            ports such as: 80, 443, 8080. The URL must use HTTPS.
          maxLength: 255
          example: https://example.com/vipps/callbacks-for-payment-update-from-vipps
        consentRemovalPrefix:
          type: string
          description: >-
            Required for Vipps Hurtigkasse (express checkout) payments. This
            callback URL will be used by Vipps to inform the merchant that the
            user has revoked his/her consent: This Vipps user does not want the
            merchant to store or use his/her personal information any longer.
            Required by GDPR. Vipps will add `/v2/consents/{userId}` to the end
            or this URL. URLs passed to Vipps must validate, see the API guide.
            We don't send requests to all ports, so to be safe use common ports
            such as: 80, 443, 8080. The URL must use HTTPS.
          maxLength: 255
          example: https://example.com/vipps/consent-removal
        fallBack:
          type: string
          description: >-
            Vipps will use the fallBack URL to redirect the Vipps user to the
            merchant’s confirmation page once the payment is completed in Vipps.
            This is normally the “success page”, although the “fallback” name is
            ambiguous (the same URL is also used if payment was not successful).
            In other words: This is the URL Vipps sends the Vipps user back to.
            The page must handle both successful payments and payment failures.
            URLs passed to Vipps must validate, see the API guide. The URL must
            use HTTPS, or a custom URL scheme like "myapp://"".
          maxLength: 255
          example: >-
            https://example.com/vipps/fallback-result-page-for-both-success-and-failure/acme-shop-123-order123abc
        isApp:
          type: boolean
          example: false
          default: false
          description: >-
            This optional parameter indicates whether payment request is
            triggered from Mobile App or Web browser. Based on this value,
            response will be redirect URL for Vipps landing page or deeplink URL
            to connect vipps App. When isApp is set to true, URLs passed to
            Vipps will not be validated as regular URLs.
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
        paymentType:
          type: string
          description: >-
            This optional parameter will identify difference between a regular
            ecommerce payment and an ecommerce express payment. For Vipps
            Hurtigkasse (express checkout), use: "eComm Express Payment".
            Express checkouts require `consentRemovalPrefix`. Note, use the
            value exactly as it is shown below (i.e., "eComm" with two m's).
          enum:
            - eComm Regular Payment
            - eComm Express Payment
          example: eComm Regular Payment
          default: eComm Regular Payment
        shippingDetailsPrefix:
          type: string
          description: >-
            In case of Vipps Hurtigkasse (express checkout) payment, merchant
            should pass this prefix to let Vipps fetch shipping cost and method
            related details. Vipps will add
            `/v2/payments/{orderId}/shippingDetails` to the end or this URL. We
            don't send requests to all ports, so to be safe use common ports
            such as: 80, 443, 8080. The URL must use HTTPS.
          maxLength: 255
          example: https://example.com/vipps/shipping
        staticShippingDetails:
          type: array
          items:
            $ref: '#/components/schemas/ShippingDetails'
          description: >-
            If shipping method and cost are always a fixed value, for example 50
            NOK, then the method and price can be provided during the initiate
            call. The shippingDetailsPrefix callback will not be used if this
            value is provided. This will result in a faster checkout and a
            better customer experience.
    PaymentStatus:
      type: object
      properties:
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionInfo:
          $ref: '#/components/schemas/OrderStatusInfoTransactionInfo'
    Transaction:
      type: object
      required:
        - transactionText
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        transactionText:
          type: string
          description: Transaction text to be displayed in Vipps
          example: One pair of Vipps socks
          maxLength: 100
    ShippingCostAndMethod:
      type: object
      required:
        - addressId
        - addressLine1
        - city
        - country
        - postCode
      properties:
        addressId:
          type: integer
          minimum: 100
          description: >-
            Vipps Provided address Id. To be returned in response in the same
            field
          example: 100
        addressLine1:
          type: string
          example: Robert Levins gate 5
        addressLine2:
          type: string
          example: c/o Rune Garborg
        city:
          type: string
          description: City
          example: Oslo
        country:
          type: string
          description: The only country supported is Norway
          default: 'NO'
          example: 'NO'
        postCode:
          type: string
          description: Four digits for Norway.
          pattern: ^\d{4}$
          example: '0154'
        addressType:
          type: string
          description: 'The type of address: Home, Work, Other.'
          pattern: ^\[A-Z]$
          enum:
            - H
            - W
            - O
          default: H
          example: H
    CustomerInfo:
      type: object
      properties:
        mobileNumber:
          type: string
          description: >-
            The phone number of the Vipps user. Allowed format: '12345678'. No
            `+47`, (or similar) country code. No `00` prefix. No spaces. Vipps
            attempts to correct incorrectly formatted phone numbers instead of
            responding with `HTTP 400 Bad Request`. In cases where the phone
            number still fails, the error will be `errorCode: 81`.
          minLength: 8
          maxLength: 8
          example: 12345678
          pattern: ^\d{8}$
    CancelPaymentActionRequest:
      type: object
      properties:
        merchantInfo:
          $ref: '#/components/schemas/MerchantInfoPayment'
        transaction:
          $ref: '#/components/schemas/CancelTransaction'
        shouldReleaseRemainingFunds:
          type: boolean
          description: >-
            An opt-in field to instruct the release of remaining funds after a
            partial capture.
          default: false
          example: false
      required:
        - merchantInfo
        - transaction
    AuthorizePaymentRequest:
      type: object
      properties:
        merchantInfo:
          $ref: '#/components/schemas/MerchantInfoPayment'
    ExpressCheckOutPaymentRequest:
      type: object
      required:
        - merchantSerialNumber
        - orderId
        - shippingDetails
        - userDetails
        - transactionInfo
      properties:
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        shippingDetails:
          $ref: '#/components/schemas/ShippingDetailsRequest'
        transactionInfo:
          $ref: '#/components/schemas/CallbackTransactionInfoExpress'
        userDetails:
          $ref: '#/components/schemas/UserDetails'
        errorInfo:
          $ref: '#/components/schemas/Error'
    RegularCheckOutPaymentRequest:
      type: object
      required:
        - merchantSerialNumber
        - orderId
        - transactionInfo
      properties:
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionInfo:
          $ref: '#/components/schemas/CallbackTransactionInfoRegular'
        errorInfo:
          $ref: '#/components/schemas/Error'
    FetchShippingCostResponse:
      type: object
      required:
        - addressId
        - orderId
        - shippingDetails
      properties:
        addressId:
          type: integer
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the `orderId`
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        shippingDetails:
          type: array
          items:
            $ref: '#/components/schemas/ShippingDetails'
    TransactionSummary:
      type: object
      required:
        - capturedAmount
        - refundedAmount
        - remainingAmountToCapture
        - remainingAmountToRefund
      properties:
        capturedAmount:
          type: integer
          description: Total amount captured
          example: 49900
        refundedAmount:
          type: integer
          description: Total refunded amount of the order
          example: 0
        remainingAmountToCapture:
          type: integer
          description: Total remaining amount to capture
          example: 0
        remainingAmountToRefund:
          type: integer
          description: Total remaining amount to refund
          example: 49900
        bankIdentificationNumber:
          type: integer
          description: Bank Identification Number, first 6 digit of card number
          example: 123456
    TransactionUpdateCallbackOneOf:
      oneOf:
        - $ref: '#/components/schemas/ExpressCheckOutPaymentRequest'
        - $ref: '#/components/schemas/RegularCheckOutPaymentRequest'
    ErrorFromAzure:
      type: object
      description: >-
        An error from Microsoft Azure. Vipps has limited control of these
        errors, and can not give as detailed information as with the errors from
        our own code. The most important property is the HTTP status code.
      required:
        - responseInfo
        - result
      properties:
        responseInfo:
          type: object
          required:
            - responseCode
            - responseMessage
          properties:
            responseCode:
              type: integer
              example: 401
            responseMessage:
              type: string
              example: Unauthorized
        result:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: 'When possible: A description of what went wrong.'
              example: >-
                (An error from Azure API Management, possibly related to
                authentication)
    Error:
      type: object
      description: >-
        An error from Vipps. The most important property is the HTTP status
        code. The response body contains more details of the error.
      required:
        - errorGroup
        - errorCode
        - errorMessage
      properties:
        errorGroup:
          type: string
          description: >-
            The error group. See:
            https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api#error-groups
          enum:
            - Authentication
            - Payment
            - InvalidRequest
            - VippsError
            - User
            - Merchant
          example: Payment
        errorCode:
          type: string
          description: >-
            The error code. See:
            https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api#error-codes
          example: '44'
        errorMessage:
          type: string
          description: >-
            A description of what went wrong. See
            https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api#errors
          example: Refused by issuer because of expired card
        contextId:
          type: string
          description: A unique ID for this error, useful for searching in logs
          example: f70b8bf7-c843-4bea-95d9-94725b19895f
    ErrorArray:
      type: array
      items:
        $ref: '#/components/schemas/Error'
    schemas-ShippingCost:
      type: number
      format: double
      description: >-
        Shipping cost in NOK. Please note that this is not øre, and different
        from other amounts.
      example: 499
      minimum: 1
    schemas-ShippingDetails:
      type: object
      required:
        - isDefault
        - shippingCost
        - shippingMethod
        - shippingMethodId
      properties:
        isDefault:
          type: string
          enum:
            - 'Y'
            - 'N'
        priority:
          type: integer
          description: |-
            Determines the order in which the shipping methods are presented
            to the user in the app, sorted in ascending order.
          example: 1
        shippingCost:
          $ref: '#/components/schemas/schemas-ShippingCost'
        shippingMethod:
          type: string
          description: >-
            The description of the shipping method. Typically the name of the
            shipping company and the name of their service. Max length: 256
            characters. Recommended length for readability on most screens: 25
            characters.
          example: Posten Servicepakke
          maxLength: 256
        shippingMethodId:
          type: string
          maxLength: 100
          example: posten-servicepakke
    schemas-FetchShippingCostResponse:
      type: object
      required:
        - addressId
        - orderId
        - shippingDetails
      properties:
        addressId:
          type: integer
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the orderId
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        shippingDetails:
          type: array
          items:
            $ref: '#/components/schemas/schemas-ShippingDetails'
    schemas-ShippingDetailsRequest:
      type: object
      required:
        - address
        - shippingCost
        - shippingMethod
        - shippingMethodId
      properties:
        address:
          $ref: '#/components/schemas/AddressExpress'
        shippingCost:
          $ref: '#/components/schemas/schemas-ShippingCost'
        shippingMethod:
          type: string
          description: >-
            The description of the shipping method. Typically the name of the
            shipping company and the name of their service. Max length: 256
            characters. Recommended length for readability on most screens: 25
            characters.
          example: Posten Servicepakke
          maxLength: 256
        shippingMethodId:
          type: string
          maxLength: 100
          example: posten-servicepakke
    schemas-CallbackTransactionInfoExpress:
      type: object
      required:
        - amount
        - status
        - timeStamp
      properties:
        amount:
          type: integer
          description: >-
            Amounts are specified in minor units. For Norwegian kroner (NOK)
            that means 1 kr = 100 øre. Example: 499 kr = 49900 øre. Minimum 1
            NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - RESERVE
            - SALE
            - CANCELLED
            - REJECTED
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API guide](/docs/APIs/ecom-api/vipps-ecom-api#callbacks)
            for more information.
          example: RESERVE
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps MobilePay
          example: '5432123456'
    schemas-ExpressCheckOutPaymentRequest:
      type: object
      required:
        - merchantSerialNumber
        - orderId
        - shippingDetails
        - userDetails
        - transactionInfo
      properties:
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the orderId
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        shippingDetails:
          $ref: '#/components/schemas/schemas-ShippingDetailsRequest'
        transactionInfo:
          $ref: '#/components/schemas/schemas-CallbackTransactionInfoExpress'
        userDetails:
          $ref: '#/components/schemas/UserDetails'
        errorInfo:
          $ref: '#/components/schemas/Error'
    schemas-CallbackTransactionInfoRegular:
      type: object
      required:
        - amount
        - status
        - timeStamp
      properties:
        amount:
          type: integer
          description: >-
            Ordered amount. Amounts are specified in minor units. For Norwegian
            kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.
            Minimum 1 NOK.
          pattern: ^\d{3,}$
          example: 49900
          minimum: 100
        status:
          type: string
          enum:
            - RESERVED
            - SALE
            - CANCELLED
            - REJECTED
          description: >-
            Status which gives the current state of the payment within Vipps.
            See the [API guide](/docs/APIs/ecom-api/vipps-ecom-api#callbacks)
            for more information.
          example: RESERVED
        timeStamp:
          type: string
          description: Timestamp in ISO-8601 representing when the operation was performed.
          example: '2018-12-12T11:18:38.246Z'
        transactionId:
          type: string
          description: Transaction ID, automatically generated by Vipps MobilePay
          example: '5432123456'
    schemas-RegularCheckOutPaymentRequest:
      type: object
      required:
        - merchantSerialNumber
        - orderId
        - transactionInfo
      properties:
        merchantSerialNumber:
          type: string
          description: >-
            Unique ID for this merchant's sales channel: website, mobile app
            etc. Short name: MSN. Early MSNs were five digits, new ones are six
            digits.
          minLength: 5
          maxLength: 6
          example: '123456'
          pattern: ^\d{5,}$
        orderId:
          type: string
          description: >-
            An ID that uniquely identifies a payment. Please see the orderId
            recommendations in the API guide. Maximum length is 50 alphanumeric
            characters: a-z, A-Z, 0-9 and '-'.
          example: acme-shop-123-order123abc
          pattern: ^[a-zA-Z0-9-]{1,50}$
          maxLength: 50
        transactionInfo:
          $ref: '#/components/schemas/schemas-CallbackTransactionInfoRegular'
        errorInfo:
          $ref: '#/components/schemas/Error'
    schemas-TransactionUpdateCallbackOneOf:
      oneOf:
        - $ref: '#/components/schemas/schemas-ExpressCheckOutPaymentRequest'
        - $ref: '#/components/schemas/schemas-RegularCheckOutPaymentRequest'
  responses:
    ErrorResponse:
      description: >-
        Possible error responses. Errors can be from both our own code (where we
        have full control) and from Microsoft Azure (where we rely on standard
        functionality). See the "Common errors" section of the [eCom
        FAQs](/docs/APIs/ecom-api/vipps-ecom-api-faq#common-errors) or from the
        [Knowledge base: Errors](/docs/knowledge-base/errors). See also:
        [Knowledge base: URL Validation](/docs/knowledge-base/url-validation).
      content:
        application/json;charset=UTF-8:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorArray'
              - $ref: '#/components/schemas/ErrorFromAzure'
