openapi: 3.0.2
info:
  title: Report API
  description: >
    The Report API provides data for payments for accounting purposes.


    For detailed information about payments, the payment API (such as the eCom,

    ePayment API or Recurring API) should be used. 


    This API is primarily for accounting partners who will use the API to
    integrate with their

    accounting systems, allowing them to provide the accounting information to
    their merchants. 


    For details, see the [Report API Guide](/docs/APIs/report-api/api-guide/).
  version: '2.0'
servers:
  - url: https://api.vipps.no
tags: []
paths:
  /settlement/v1/ledgers:
    get:
      summary: Get ledgers
      deprecated: false
      description: >
        Returns the ledgers you have access to.


        If you are integrating a single

        merchant it may be enough to hit this endpoint once manually to identify

        the `ledgerId`, and then put that in your configuration.

        If you are integrating for an accounting system or similar, you should

        call this endpoint periodically in order to synchronize the list

        of ledgers you have access to.


        There is no need to specify the merchant or sales unit.

        The response contains all ledgers that are available for the API keys
        used,

        and also the sales units that use this ledger.


        The full response example below displays the ePayment and eCom case.
      tags:
        - /settlement/v1
      operationId: getLedgers
      parameters:
        - $ref: '#/components/parameters/JWT'
        - $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: query
          name: settlesForRecipientHandles
          required: false
          schema:
            type: string
            description: >-
              Filters the list of ledgers, and only returns the ledger(s) that
              settle(s) for the given `settlesForRecipientHandle`.

              This can either be an ePayment MSN, prefixed by `api:` (like
              `api:123456`),

              or a Vippsnummer/MyShop number, prefixed by `NO:`, `DK:` or `FI:`
              depending on country (like `NO:654321`).
            example: api:123456
        - in: query
          required: false
          name: cursor
          schema:
            type: string
            example: >-
              eyJhZnRlckxlZGdlcklkIjoieHh4eCIsInNldHRsZXNGb3JSZWNpcGllbnRIYW5kbGVzIjpudWxsfQ==
            description: >-
              We limit the amount of rows returned to reduce the amount of data
              we need to process on each request. 

              If the total number of rows is greater than that amount we return
              a cursor in addition to

              the rows in the body. This cursor given can be used with this
              parameter to fetch the next set of ledgers.

              If this is used, no other parameters is needed.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  cursor:
                    type: string
                    example: eyJhZnRlckxlZGdlcklkIjoie
                    description: >-
                      A cursor that can be used to fetch the next ledgers.

                      It is empty if there are no more rows to fetch after the
                      current one.

                      You can insert this value into the url as part of the
                      cursor parameter.
                  ledgers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ledger'
                  salesUnits:
                    type: array
                    items:
                      $ref: '#/components/schemas/SalesUnit'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Default problem response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate}:
    get:
      tags:
        - /report/v2/ledgers
      summary: Fetch report by date
      description: >-
        Complete report of entries on an account for a given "ledger date".

        A "ledger date" normally lasts from midnight to midnight in the timezone

        of the merchant; but it can be configured to other cutoffs such as 04:00
        to 04:00.

        The caller should periodically poll for a report for the next date to
        download,

        and interpret HTTP 404 as a signal to try again later.

        You can get two different types of ledgers with this endpoint. The funds
        ledger, which

        tracks the sales, refunds, and a total of fees for the time period, and
        the fees ledger, which

        provides details about the fees you have been charged.
      parameters:
        - $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: path
          name: ledgerId
          required: true
          schema:
            type: string
            description: Ledger ID provided by `GET:/settlement/v1/ledgers`.
        - in: path
          name: ledgerDate
          required: true
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}
            description: Date in format YYYY-MM-DD.
        - in: path
          name: topic
          required: true
          schema:
            type: string
            enum:
              - funds
              - fees
            description: >-
              `funds` provides the funds ledger which tracks the sales, refunds,
              and a total of fees for the time period. `fees` 

              provides the fees ledger with details about the fees you have been
              charged.
        - in: query
          required: false
          name: cursor
          schema:
            type: string
            example: eyJhZnRlckxlZGdlcklkIjoie <truncated>
            description: >-
              We limit the amount of rows returned to reduce the amount of data
              we need to process on each request. 

              If the total number of rows is greater than that amount we return
              a cursor in addition to

              the rows in the body. This cursor given can be used with this
              parameter to fetch the next set of ledgers.

              If this is used, no other parameters is needed.
        - in: query
          required: false
          name: includeGDPRSensitiveData
          schema:
            type: boolean
            description: >-
              When set to `true`, the funds and fees endpoints return the text
              that the user entered, name, and masked phone number

              for in-person payments (like Vippsnummer and MyShop).

              See [GDPR data](/docs/APIs/report-api/api-guide/#gdpr-data).
            example: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: The report for this date is not available yet
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Default problem response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /report/v2/ledgers/{ledgerId}/{topic}/feed:
    get:
      tags:
        - /report/v2/ledgers
      summary: Fetch report by feed
      description: >-
        Continuous stream of data. Upon reaching the end of the feed, the
        `cursor` will not become empty and `items` can 

        become an empty list. One should retry to fetch the same `cursor` until
        new data and a new `cursor` will be returned.

        Unless in the need of data with low latency try not to poll the endpoint
        too often and effectively batch your reports.
      parameters:
        - $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: path
          name: ledgerId
          required: true
          schema:
            type: string
            description: Ledger ID provided by GET:/settlement/v1/ledgers
        - in: path
          name: topic
          required: true
          schema:
            type: string
            enum:
              - funds
              - fees
            description: One of `funds`, `fees`
        - in: query
          required: false
          name: cursor
          schema:
            type: string
            example: eyJhZnRlckxlZGdlcklkIjoie <truncated>
            description: >-
              We limit the amount of rows returned to reduce the amount of data
              we need to process on each request. 

              If the total number of rows is greater than that amount we return
              a cursor in addition to

              the rows in the body. This cursor given can be used with this
              parameter to fetch the next set of ledgers.

              If this is used, no other parameters is needed.
        - in: query
          required: false
          name: includeGDPRSensitiveData
          schema:
            type: boolean
            description: >-
              When set to `true`, the funds and fees endpoints return the text
              that the user entered, name, and masked phone number

              for in-person payments (like Vippsnummer and MyShop).

              See [GDPR data](/docs/APIs/report-api/api-guide/#gdpr-data).
            example: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Default problem response
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  parameters:
    JWT:
      name: Authorization
      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`](/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 <truncated>
    Vipps-System-Name:
      name: Vipps-System-Name
      in: header
      description: |-
        The name of the ecommerce solution.
        One word in lowercase letters is good.
        See [HTTP headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: woocommerce
    Vipps-System-Version:
      name: Vipps-System-Version
      in: header
      description: |-
        The version number of the ecommerce solution.
        See [HTTP headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: 5.4.0
    Vipps-System-Plugin-Name:
      name: Vipps-System-Plugin-Name
      in: header
      description: |-
        The name of the ecommerce plugin (if applicable).
        One word in lowercase letters is good.
        See [HTTP headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: vipps-woocommerce
    Vipps-System-Plugin-Version:
      name: Vipps-System-Plugin-Version
      in: header
      description: |-
        The version number of the ecommerce plugin (if applicable).
        See [HTTP headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: 1.2.1
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              cursor:
                type: string
                example: eyJhZnRlckxlZGdlcklkIjoie
                description: >-
                  A cursor that can be used to fetch the next transactions.

                  You insert this value into the url as part of the cursor
                  parameter.

                  This property is always present on the `.../feed` endpoint and
                  will always

                  have a value that can be used to try to fetch more data.

                  On the `.../dates` endpoint, it is only present if `hasMore`
                  is true.
              hasMore:
                type: boolean
                example: false
                description: >-
                  Only present on the `.../dates/...` endpoint. Indicates
                  whether the client needs to do another

                  request with the given `cursor` to fetch the next page of
                  data.
              tryLater:
                type: boolean
                example: false
                description: >-
                  Indicates that data is not yet available, and that you should
                  pause for some time

                  before trying again. For the `.../feed` endpoint, this means
                  you are at the

                  end of the feed; wait at least a second before continuing to
                  consume the feed

                  like normal. For the `.../dates/...` endpoint, it means that
                  the date has not

                  yet been "closed" so that the report is not complete; try the
                  same request

                  again in at least half an hour. (Note: In Norway, `tryLater`
                  can stay `true`

                  for a long time in some cases; please see the FAQ for
                  details).
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: Unauthorized
              message:
                type: string
                example: Please check your API keys
    '500':
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                type: number
                description: The error-code for the problem
                example: 100001
              errorMessage:
                type: string
                description: A human readable summary of the problem
                example: Your request parameters didn't validate.
              contextId:
                type: string
                description: >-
                  Unique ID for the request which can be used to find related
                  events (logs)
                example: 123e4567-e89b-12d3-a456-426655440000
  schemas:
    BankAccount:
      type: object
      properties:
        scheme:
          type: string
          description: >-
            The scheme for the bank account, typically account identifier type
            (BBAN) and

            country code (`NO`, `DK`, `FI`, etc), separated by a colon (':').
          example: BBAN:NO
        id:
          type: string
          description: The bank account ID, typically the account number.
          example: '86011117947'
    Ledger:
      type: object
      properties:
        ledgerId:
          type: string
          description: The ID for the ledger.
          example: '302321'
        currency:
          type: string
          example: NOK
          description: >-
            Currency code as defined in ISO 4217. Typically `NOK`, `DKK` or
            `EUR.`
        payoutBankAccount:
          $ref: '#/components/schemas/BankAccount'
        owner:
          $ref: '#/components/schemas/Organization'
        settlesForRecipientHandles:
          type: array
          description: >-
            Identifies the sales units that this Ledger will settle for.

            This can either be an ePayment MSN, prefixed by `api:` (like
            `api:123456`),

            or a Vippsnummer/MyShop number, prefixed by `NO:`, `DK:` or `FI:`
            depending on country (like `NO:654321`).
          items:
            type: string
            example: NO:123455
    SalesUnit:
      type: object
      properties:
        name:
          type: string
          description: The name of the sales unit.
          example: ACME Fitness
        recipientHandle:
          description: >-
            Identifies the sales unit that this Ledger will settle for. 

            This can either be an ePayment MSN, prefixed by `api:` (like
            `api:123456`),

            or a Vippsnummer/MyShop number, prefixed by `NO:`, `DK:` or `FI:`
            depending on country (like `NO:654321`).
          items:
            type: string
            example: NO:123455
        businessIdentifier:
          $ref: '#/components/schemas/Organization'
    Problem:
      title: Problem
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://example.com/problem/unauthorized
          description: A URI reference that identifies the problem type.
        title:
          type: string
          example: Not authorized to create a product order
          description: >-
            A short, human-readable summary of the problem type.  It will not
            change from occurrence to occurrence of the problem.
        status:
          type: integer
          description: The HTTP response code
          example: 401
        detail:
          type: string
          example: >-
            Not authorized to create a product order. Check whether
            Authorization token and Ocp-Apim-Subscription-Key are correct.
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        instance:
          type: string
          example: /products/orders
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
    Transaction:
      type: object
      properties:
        pspReference:
          type: string
          description: >-
            A reference generated by Vipps MobilePay relevant for the entry.

            The specific meaning of `pspReference` depends on the `entryType`;

            please see documentation in [Report API
            Guide](/docs/APIs/report-api/api-guide/).
          example: '3343121302'
        time:
          type: string
          description: Transaction time in UTC.
          format: DateTime
          example: '2020-10-05T00:00:00.000000Z'
        ledgerDate:
          type: string
          format: Date in YYYY-MM-DD format.
          example: '2020-10-05'
        entryType:
          type: string
          description: The type of transaction.
          enum:
            - refund
            - capture
            - fees-retained
            - fees-invoiced
            - payout-scheduled
            - payout-aborted
            - retained-disputed-capture
            - returned-disputed-capture
            - correction
            - capture-fee
            - top-up
          example: capture
        reference:
          type: string
          description: >-
            A reference associated with the entry; usually provided by the
            merchant/integrator.

            The meaning of `reference` depends on the `entryType`;

            please see documentation in [Report API
            Guide](/docs/APIs/report-api/api-guide/).
          example: acme-shop-123-order123abc
        currency:
          type: string
          example: NOK
          description: >-
            Currency code as defined in ISO 4217. Typically `NOK`, `DKK` or
            `EUR.`
        amount:
          $ref: '#/components/schemas/Money'
        balanceBefore:
          $ref: '#/components/schemas/Money'
        balanceAfter:
          $ref: '#/components/schemas/Money'
        recipientHandle:
          type: string
          description: >-
            Identification of the sales unit that this payment was made to/from.

            This can either be an ePayment MSN, prefixed by `api:` (like
            `api:123456`),

            or a Vippsnummer/MyShop number, prefixed by `NO:`, `DK:` or `FI:`
            depending on country (like `NO:654321`).
          example: NO:123455
        message:
          type: string
          description: >-
            A message associated with the entry; usually provided by the
            merchant/integrator.

            The meaning of `message` depends on the `entryType`.

            Please see documentation in [API
            Guide](/docs/APIs/report-api/api-guide/).

            Only available when `includeGDPRSensitiveData` is set to `true`, and
            only for certain types of payments.

            Please see documentation in [API
            Guide](/docs/APIs/report-api/api-guide/).
          example: Order 123ABC
        name:
          type: string
          description: >-
            The name of the person or organization that made the payment.

            This is typically the name of the customer.

            Only available when `includeGDPRSensitiveData` is set to `true`, and
            only for certain types of payments.

            Please see documentation in [API
            Guide](/docs/APIs/report-api/api-guide/).
          example: John Doe
        maskedPhoneNo:
          type: string
          description: >-
            The phone number of the person or organization that made the
            payment.

            This is typically the phone number of the customer.

            Only available when `includeGDPRSensitiveData` is set to `true`, and
            only for certain types of payments.

            Please see documentation in [API
            Guide](/docs/APIs/report-api/api-guide/).
          example: xxxx 5678
    Organization:
      type: object
      properties:
        id:
          type: string
          description: The identifier for this organization.
          example: '987654321'
        scheme:
          type: string
          description: |-
            The type of organization identifier.
            For Norway this is `business:NO:ORG`, for Denmark
            it is `business:DK:CVR` and for Finland `business:FI:Y-tunnus`.
          example: business:NO:ORG
    Money:
      type: number
      format: int32
      description: >-
        Amounts are specified in minor units.

        NOK and DKK: 1 kr = 100 øre. EUR: 1 Euro = 100 cent.

        499 NOK will be represented as 49900.

        Negative amounts, for instance a `refund` of 499 NOK, will be negative:
        -49900.
      example: 49900
