Intro

This document provides examples and surface-level information on generic settlements in the Clearing API.

A generic settlement consists of financial transactions used to distribute money between relevant parties/accounts. The clearing process itself is to ensure:

• Data integrity and validation of the settlement and its transactions.
• Creation of accounting entries for general ledger and financial reporting.
• Documentation for auditing purposes.

The Clearing API

All endpoints in the Clearing API requires an authentication header. To start using the API, you will need a client ID with the correct permissions. Read more in the guide about Authentication.

Please refer to the Clearing API documentation for more information about the endpoints used in the examples below.

Examples

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": []
}

When you submit it to the POST /settlement-import/generic endpoint, you will get 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 Clearing service 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.

It might take some time before the clearing is fully processed. You can check the status by querying GET /settlement-import/{id} 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..."
}

Settlement with a payment annex

Settlements consist of the hierarchical elements: Transactions, Annexes, and Parameters. This next example defines a settlement with one transaction of type ADVANCE, which contains one annex of type EOS:Payment:Advance. This represents an advance payment of 372.00 defined in a priceContribution. The in-depth documentation provides more information on the hierarchical structure.

When this settlement is cleared, the Clearing service will generate accounting entries. The transaction will be visible in the user interface and relevant financial reports:

Code
{
  "posRef": "EOS:Pos:ExternalPSP",
  "distributionChannelRef": "ENT:DistributionChannel:ExternalPSP",
  "settlementNo": 2,
  "settlementDate": "2025-11-26",
  "comments": [
    {"comment":"This is a comment"}
  ],
  "genericTransactions": [
    {
      "transactionType": "ADVANCE",
      "genericAnnexes": [
        {
          "annexRef": "EOS:Payment:Advance",
          "attributes": {
            "paymentType": "AgentVYG",
            "paymentTypeGroup": "AGENT"
          },
          "priceContribution": {
            "amount": "372.00"
          },
          "description": "A konto betaling for 3part VY-COIN"
        }
      ]
    }
  ]
}

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. Refer to the in-depth documentation for settlement corrections.

• 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 Clearing service. 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.

• The annex can be expanded with additional attributes as needed: MVA code, external settlement number, etc. You can for example add a "context" field to the settlement/annex to specify additional information relevant to the transaction. This will not affect the clearing process, but will appear on financial reports that support the specific key.

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

• It can be assumed that any 4xx or 5xx HTTP Code responses when posting a generic settlement, result in the settlement not being saved by the Clearing service for processing. Therefore, the same settlement data can be posted again for a retry. This includes retries on the same settlementNo and posRef combination.