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

:::note
To ensure a robust partner integration, it is therefore recommended to read the in-depth documentation about [Generic Settlements](/guides/clearing/generic-settlements).
:::

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](/docs/authentication#partner-services).

Please refer to the [Clearing API documentation](/apis/clearing) 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:

```json
{
  "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:

```json
{
  "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`:

```json
{
  "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:

```json
{
  "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.