Skip to main content

Sales API guide

This guide is for accounting partners using accounting keys. It covers how to authenticate with and call the Sales API to retrieve order lines, VAT, and sales context for VM-number (also called Vippsnummer) and mPOS payments.

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 replace or duplicate the Report API.

Historical data availability​

The Sales API currently has limited historical data available.

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

Integration steps​

For a step-by-step walkthrough of authentication, discovering ledger IDs, and calling the Sales API endpoints, see the Quick start guide.

Endpoints​

EndpointDescription
Get ledgers(Report API) Returns the ledgers you have access to.
Get sales report by feedContinuous stream of sales data for a ledger
Get sales events for a ledger on a specific dateSales data for a specific date
Get sales events by merchant referenceAll captures and returns for a specific reference
Get sales events by PSP referenceA specific capture or return by PSP reference

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.

Example request:

curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}?pageSize=100" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Get sales events for a ledger on a specific 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.

Example request:

curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/dates/2026-05-01" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Get sales events by merchant reference​

Returns all captures and returns related to a specific reference.

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

Example request:

curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/references/{reference}" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Get sales events by PSP reference​

Returns a specific capture or return using the PSP reference.

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

Example request:

curl -X GET "https://api.vipps.no/sales/report/v1/ledgers/{ledgerId}/psp-references/{pspReference}" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

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 or not available" from "empty but known".

Report API mapping

Sales API fieldReport API fieldMeaning
referencereferenceIdentifies the order
pspReferencepspReferenceIdentifies 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 VM-number 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 VM-number payments where line items are absent.
Last updated on