Get started with settlements

This guide shows how to submit Generic Settlements for clearing as a partner. The process has three steps: Authentication, Submission (POST a settlement for clearing), and Status (check the settlement's status).

Minimal settlement

This is the minimal required structure to perform a successful clearing of an (empty) settlement:

Code
{
  "distributionChannelRef": "ENT:DistributionChannel:ExternalPSP",
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "genericTransactions": []
}

Submitting it returns a response similar to this:

Code
{
  "id": 111122222,
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "externalSettlementNo": 1,
  "ignoreSequence": false,
  "comments": [],
  "status": 0,
  "statusDescription": "Partner Settlement queued for processing."
}

This means that the Clearing system has accepted the settlement for processing, and put it in queue to be cleared asynchronously. Since no annexes are defined, the clearing will not generate any accounting entries and has therefore little purpose for a partner. See Submit an advance settlement for an example with annexes.

It might take some time before the clearing is fully processed. You can check the status with the returned id:

Code
{
  "id": 11111222222,
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "externalSettlementNo": 1,
  "ignoreSequence": false,
  "comments": [],
  "status": 1,
  "statusDescription": "100M-Mottakskontroll av oppgjør id=11111222222,ENT:Pos:OsloS1,onr=1,date=25.11.2025,priority=2,batchId=1763981079206 påbegynt 2025-11-25T11:44:39.274030841.\n..."
}

Important to remember

• The settlementNo must be sequentially incremented by 1 per settlement, and the combination of settlementNo and posRef must be unique. Keeping track of settlement numbers is the responsibility of the partner.

• It's worth noting that if previous settlements fail, or if settlements become out of sequence, subsequent settlements will not be processed until all previous settlements are successfully cleared.

• Once a settlement is cleared, it cannot be modified or deleted. Any corrections must be submitted through new settlements — see Submit a correction or refund.

• The definition of settlementDate is partially up to the partner. This could for example be the date the sale was made or the date the settlement is uploaded to the Clearing system. However, it's worth noting that setting it to a future date can delay the clearing process if it happens to fall outside the current calendar month.

• Comments are supposed to be short and relevant to the settlement/clearing.

Resubmitting settlements

The Clearing system supports settlement resubmission using the same posRef and settlementNumber combination. If a settlement with matching identifiers has already been successfully received, the resubmission will be rejected to prevent duplicate processing.

Client responsibilities:

• Generate sequential settlement numbers for each settlement submission
• Implement retry logic to resubmit failed settlements (within reasonable limits)

Note that the duplicate detection mechanism is limited to settlements submitted within the last 7 days, it is only intended to handle transient submission failures. Older duplicates will be detected and failed during clearing.

Key point: Settlement identifiers (posRef + settlementNumber) must be unique and sequential. Resubmit failed settlements using the same identifiers; do not create new settlement numbers for retry attempts.

High transaction volumes

The Clearing system can process large volumes of transactions efficiently. However, the Generic Settlement API is optimized for moderate-sized settlements rather than bulk processing.

Submitting settlements containing thousands of transactions and multi-megabyte JSON payloads introduces reliability and performance risks. Instead, distribute high-volume transaction data across multiple smaller settlements submitted at regular intervals.

For scenarios requiring continuous high-volume processing, a streaming-based integration module may be more appropriate. This capability will be developed based on identified use cases.

Key point: Split high-volume transaction data into multiple smaller settlements.