Sales API guide

Under development

This documentation is under development. Content and integration details may change as we continue internal discussions. Feedback is welcome.

This requires a stable and explicit mapping between the two APIs.

Description

The Sales API exposes order-centric entries, where each entry represents one financial transaction on an order (capture or refund) enriched with sales context.

Each entry:

• Includes a stable order identifier (reference)
  • Same field name as reference in the Report API
• Includes a transaction identifier (pspReference)
  • Same field name as pspReference in the Report API
• Includes sales amounts (gross, net, VAT) in minor units when available
• Includes order lines, VAT, categories (potentially also customer identity, in the future)
• Does not expose payment state or settlement correctness

The Sales API does not attempt to replace or duplicate the Report API.

Historical data availability

The Sales API has limited historical data currently available.

• mPOS data from 2026-03-09 12:45 UTC
• Vippsnummer variable amount from 2026-03-16 09:28 UTC
• Vippsnummer shopping basket from 2026-04-22 11:04 UTC

Get ledgers

Partners use the Report API to discover which ledger IDs they have access to:

GET /settlement/v1/ledgers

---

Get sales report by feed

Provides a continuous stream of sales data.

GET /sales/report/v1/ledgers/{ledgerId}

Query parameters

• cursor Example: cursor=2ScAAAAAAAA=

  • If not provided, the response starts from the first sale on the given ledgerId.
  • Each response includes a cursor indicating where the stream stopped.
  • Partners must persist the cursor and include it in subsequent requests to continue from the last checkpoint.

• pageSize Example: pageSize=100

  • Limits the number of rows returned per request (default: 100, max: 1000).
  • Used to control payload size and processing volume.
  • Partners may request fewer rows than the default by specifying pageSize.

---

Get sales report by date

Returns sales data for a specific date.

GET /sales/report/v1/ledgers/{ledgerId}/dates/{ledgerDate}

If the number of sales exceeds the response limit:

• The response includes:
  • cursor
  • hasMore = true
• Partners must repeat the request for the same date including the cursor to retrieve remaining records.

Query parameters

• cursor Example: cursor=2ScAAAAAAAA=

  • If not provided, the response starts from the first sale on the given ledgerId.
  • Each response includes a checkpoint cursor.
  • Partners must store and reuse the cursor to continue retrieving remaining records.

• pageSize Example: pageSize=100

  • Limits the number of rows returned per request (default: 100, max: 1000).
  • Partners can request a smaller page size if desired.

---

Get sales report by reference

Returns all captures and returns related to a specific reference.

GET /sales/report/v1/ledgers/{ledgerId}/references/{reference}

---

Get sales report by PSP reference

Returns a specific capture or return using the PSP reference.

GET /sales/report/v1/ledgers/{ledgerId}/psp-references/{pspReference}

External payload shape

{
  "items": [
      {
        "entryType": "capture",
        "time": "2026-01-19T12:45:00Z",
        "pspReference": "35054310398",
        "reference": "12494299492",
        "currency": "NOK",
        "paymentType": "CARD",
        "classification": {
            "solution": "MPOS",
            "salesCategory": null
          },
        "amounts": {
            "gross": 25000,
            "net": 20000,
            "vat": 5000
          },
        "lines": [
          {
            "lineId": "121772",
            "name": "Product A",
            "quantity": 2,
            "unitPriceGross": 12500,
            "unitPriceNet": 10000,
            "discountTotal": 0,
            "lineTotalGross": 25000,
            "lineTotalNet": 20000,
            "vatRate": 2500,
            "vatAmount": 5000,
            "category": "GOODS"
          }
        ],
        "customer": {
            "email": "customer@example.com",
            "phone": "+4712345678",
            "name": "Ola Nordmann"
          },
        "completeness": {
            "hasLineItems": true,
            "hasVatBreakdown": true,
            "hasCustomerIdentity": true
          }
        }
  ],
  "cursor": "8gsAAAAAAAA=",
  "hasMore": true
}

Field semantics

Identifiers

• reference
  • Identifies the order / sale
  • Same field name as reference in the Report API (equals orderId in the ePayment API)
  • Stable across captures, refunds, and fees
• pspReference
  • Identifies one financial transaction
  • Same field name as pspReference in the Report API
  • Unique per capture or refund. null for payment methods without a PSP (e.g. cash)

paymentType

CARD | CASH | WALLET

Amounts

All monetary values are in minor units (e.g. øre for NOK). "Gross" means including VAT. "Net" means excluding VAT.

Line Items

• unitPriceGross — Gross unit price before discount (including VAT)
• unitPriceNet — Net unit price before discount (excluding VAT)
• discountTotal — Total discount for this line
• lineTotalGross — Final gross line price after discount (incl. VAT)
• lineTotalNet — Final net line price after discount (excluding VAT)
• vatRate — VAT rate in basis points (e.g. 2500 = 25%)
• vatAmount — VAT amount for this line

Invariants

• unitPriceGross * quantity - discountTotal = lineTotalGross
• sum(lines[].lineTotalGross) = amounts.gross
• sum(lines[].vatAmount) = amounts.vat

Completeness Flags

Completeness flags are required and allow consumers to distinguish:

• "not provided / not available"
• from "empty but known"

Report API mapping

Sales API field	Report API field	Meaning
reference	reference	Identifies the order
pspReference	pspReference	Identifies the transaction

Accounting partners are expected to:

1. Fetch sales entries from the Sales API
2. Fetch transactions (funds + fees) from the Report API
3. Join on reference (order-level) or pspReference (transaction-level)

Classification

Each entry may include a classification object with the following fields:

• solution — Identifies the Vipps MobilePay solution used for the sale:
  • VARIABLE_AMOUNT — Open-amount Vippsnummer payment (no line items)
  • MPOS — mPOS / Kassa sale (card, cash, or wallet at terminal)
• salesCategory — Merchant-defined category for the sale (nullable). Primarily relevant for open-amount Vippsnummer payments where line items are absent.