openapi: 3.0.1
info:
  title: Sales API
  version: '1.0'
  description: Sales reporting API for accounting partners
paths:
  /report/v1/ledgers/{ledgerId}:
    get:
      tags:
        - Merchant Sales
      operationId: GetLedgerEvents
      summary: Get sales events for a ledger
      description: >-
        Returns paginated sales events (captures and refunds) for the specified
        ledger. Use the cursor value to fetch subsequent pages.
      parameters:
        - name: ledgerId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Ledger ID provided by the Report API [Get
            ledgers](https://developer.vippsmobilepay.com/api/report/#tag/settlementv1/operation/getLedgers)
            endpoint
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor from a previous response
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
            maximum: 1000
          description: 'Number of items per page (default: 100, max: 1000)'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEventsResponse'
        '400':
          description: Bad Request - invalid ledgerId format
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - no access to this ledger
  /report/v1/ledgers/{ledgerId}/dates/{ledgerDate}:
    get:
      tags:
        - Merchant Sales
      operationId: GetLedgerEventsByDate
      summary: Get sales events for a ledger on a specific date
      description: >-
        Returns paginated sales events (captures and refunds) for the specified
        ledger filtered by date.
      parameters:
        - name: ledgerId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Ledger ID provided by the Report API [Get
            ledgers](https://developer.vippsmobilepay.com/api/report/#tag/settlementv1/operation/getLedgers)
            endpoint
        - name: ledgerDate
          in: path
          required: true
          schema:
            type: string
            format: date
          description: Date to filter events by (YYYY-MM-DD)
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor from a previous response
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
            maximum: 1000
          description: 'Number of items per page (default: 100, max: 1000)'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEventsResponse'
        '400':
          description: Bad Request - invalid ledgerId or date format
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - no access to this ledger
  /report/v1/ledgers/{ledgerId}/references/{reference}:
    get:
      tags:
        - Merchant Sales
      operationId: GetLedgerEventsByReference
      summary: Get sales events by merchant reference
      description: >-
        Returns sales events for the specified ledger matching the given
        merchant reference.
      parameters:
        - name: ledgerId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Ledger ID provided by the Report API [Get
            ledgers](https://developer.vippsmobilepay.com/api/report/#tag/settlementv1/operation/getLedgers)
            endpoint
        - name: reference
          in: path
          required: true
          schema:
            type: string
          description: The merchant's order reference
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEventsResponse'
        '400':
          description: Bad Request - invalid ledgerId format
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - no access to this ledger
  /report/v1/ledgers/{ledgerId}/psp-references/{pspReference}:
    get:
      tags:
        - Merchant Sales
      operationId: GetLedgerEventsByPspReference
      summary: Get sales events by PSP reference
      description: >-
        Returns sales events for the specified ledger matching the given PSP
        reference.
      parameters:
        - name: ledgerId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Ledger ID provided by the Report API [Get
            ledgers](https://developer.vippsmobilepay.com/api/report/#tag/settlementv1/operation/getLedgers)
            endpoint
        - name: pspReference
          in: path
          required: true
          schema:
            type: string
          description: Payment service provider reference
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEventsResponse'
        '400':
          description: Bad Request - invalid ledgerId format
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - no access to this ledger
components:
  schemas:
    LedgerEventsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LedgerEvent'
          description: List of sales events
        cursor:
          type: string
          nullable: true
          description: Cursor for fetching the next page. Null if no more results.
        hasMore:
          type: boolean
          description: Whether there are more items to fetch
      required:
        - items
        - cursor
        - hasMore
    LedgerEvent:
      type: object
      properties:
        entryType:
          type: string
          enum:
            - capture
            - refund
          description: Type of entry
        time:
          type: string
          format: date-time
          description: Event timestamp
        pspReference:
          type: string
          nullable: true
          description: >-
            Payment service provider reference. Uniquely identifies one
            financial transaction. Corresponds to 'pspReference' in the Report
            API. Null for cash payments.
        reference:
          type: string
          description: >-
            The merchant's order reference. Corresponds to 'reference' in the
            Report API and 'orderId' in the ePayment API.
        currency:
          type: string
          description: Currency code (e.g., NOK)
        paymentType:
          type: string
          enum:
            - CARD
            - CASH
            - WALLET
          description: >-
            Payment instrument category. CARD = card payment, CASH = cash (mPOS
            only), WALLET = Vipps/MobilePay wallet.
        amounts:
          $ref: '#/components/schemas/LedgerEventAmounts'
        lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/LedgerEventLine'
          description: Order line items, if available
        customer:
          $ref: '#/components/schemas/LedgerEventCustomer'
          nullable: true
          description: Customer information, if available
        classification:
          $ref: '#/components/schemas/LedgerEventClassification'
          nullable: true
          description: >-
            Solution and category classification. Null when neither solution nor
            salesCategory is known.
        completeness:
          $ref: '#/components/schemas/LedgerEventCompleteness'
      required:
        - entryType
        - time
        - reference
        - currency
        - paymentType
        - amounts
        - completeness
    LedgerEventAmounts:
      type: object
      properties:
        gross:
          type: integer
          format: int64
          description: Gross amount in minor units
        net:
          type: integer
          format: int64
          nullable: true
          description: Net amount in minor units
        vat:
          type: integer
          format: int64
          nullable: true
          description: VAT amount in minor units
      required:
        - gross
    LedgerEventLine:
      type: object
      description: >-
        Order line item. All monetary values are in minor units (e.g. øre for
        NOK). Gross = incl. VAT, net = excl. VAT. Formula: unitPriceGross *
        quantity - discountTotal = lineTotalGross.
      properties:
        lineId:
          type: string
          nullable: true
          description: Line item identifier
        name:
          type: string
          nullable: true
          description: Product or service name
        quantity:
          type: integer
          format: int32
          description: Number of units
        unitPriceGross:
          type: integer
          format: int64
          nullable: true
          description: Gross unit price in minor units (incl. VAT, before discount)
        unitPriceNet:
          type: integer
          format: int64
          nullable: true
          description: Net unit price in minor units (excl. VAT, before discount)
        discountTotal:
          type: integer
          format: int64
          nullable: true
          description: >-
            Total discount for this line in minor units. unitPriceGross *
            quantity - discountTotal = lineTotalGross
        lineTotalGross:
          type: integer
          format: int64
          nullable: true
          description: >-
            Total gross amount for this line in minor units (incl. VAT, after
            discount)
        lineTotalNet:
          type: integer
          format: int64
          nullable: true
          description: >-
            Total net amount for this line in minor units (excl. VAT, after
            discount)
        vatRate:
          type: integer
          format: int64
          nullable: true
          description: VAT rate in basis points (e.g. 2500 = 25%)
        vatAmount:
          type: integer
          format: int64
          nullable: true
          description: VAT amount for this line in minor units
        category:
          type: string
          nullable: true
          description: Product category
      required:
        - quantity
    LedgerEventCustomer:
      type: object
      properties:
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    LedgerEventClassification:
      type: object
      properties:
        solution:
          type: string
          nullable: true
          enum:
            - VARIABLE_AMOUNT
            - SHOPPING_BASKET
            - MPOS
            - null
          description: Vipps MobilePay solution used for the sale
        salesCategory:
          type: string
          nullable: true
          description: Merchant-defined category for the sale (e.g. food_and_drink)
    LedgerEventCompleteness:
      type: object
      properties:
        hasLineItems:
          type: boolean
          description: Whether line items are present
        hasVatBreakdown:
          type: boolean
          description: Whether VAT breakdown is available
        hasCustomerIdentity:
          type: boolean
          description: Whether customer identity is present
      required:
        - hasLineItems
        - hasVatBreakdown
        - hasCustomerIdentity
