Incoming Settlements

Server

Create and manage settlements to be cleared by CLEOS

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using.

POST

https://api.entur.io/clearing

/v1/settlement-import/generic

Creates a GenericSettlementImport, in queue for for clearing. Use the returned result for further queries based on the assigned ID

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Headers

ET-Client-Name

string · style: simple

Entur Client Header. It is required that all consumers identify themselves by using this header. Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: <company>-<application>.

X-Correlation-Id

string · style: simple

Correlation id

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Request Body

Generic Settlement submitted by Partner. This is a subset of the CLEOS settlement structure intended for self-serviced clearing.

PartnerSettlementImportDto

posRef

string · minLength: 0 · maxLength: 100 · required

Reference to the PointOfSale (POS) for which the settlement is created.

distributionChannelRef

string · minLength: 0 · maxLength: 100 · required

Reference to the Distribution Channel for which the settlement is created.

settlementDate

string · date · required

Settlement Date for the settlement on the format YYYY.MM.DD

PartnerTransactionImportDto[] · required

List of Generic Transactions associated with the settlement. The list is required but may be empty: a period with no sales still consumes its Settlement Number, and submitting the empty Settlement keeps the sequence unbroken for the next one.

msgSubjectId

string

id

integer · int64

settlementNo

integer · int64

Settlement Sequence Number. This must be a continuous sequence for the settlement not to fail clearing. Negative sequences are typically used for corrections that are out of sequence. If not specified, the next number in a negative sequence will automatically be assigned based previous correction on the same POS.

correctionForSmntId

integer · int64

If this settlement is a correction of a previous settlement, the internal CLEOS ID of the settlement being corrected must be provided.

externalSettlementNo

integer · int64

External Settlement Number provided by the Partner. If not provided, the settlementNo will be used as external reference as well.

PartnerCommentDto[]

Optional comments associated with the settlement. Used for audit trail and additional information relevant for clearing.

object

Context map containing additional key-value pairs relevant for the settlement. Only simple key-value pairs are supported (String, Number, Boolean) with a max length of 100 characters per value.

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Responses

Created

Relevant information on the successfully registered Settlement Import. See documentation for PartnerSettlementImportDto for details on fields that the client submitted.

PartnerSettlementImportResponseDto

id

integer · int64

Unique identifier of queued Settlement Import.

posRef

string

settlementDate

string · date

settlementNo

integer · int64

correctedSettlementId

integer · int64

externalSettlementNo

integer · int64

ignoreSequence

boolean

Indicates whether sequence errors will be ignored during import, typical for negative settlement sequences (corrections).

comments

string[]

status

integer · int32

Status code indicating the result of the import operation. This will always be 0 (TO BE PROCESSED) on creation. 1 indicates SUCCESSFUL CLEARING

Example: 0

statusDescription

string

Message providing additional information on the import status.

POST/v1/settlement-import/generic

curl https://api.entur.io/clearing/v1/settlement-import/generic \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "msgSubjectId": "msgSubjectId",
  "id": 0,
  "posRef": "posRef",
  "distributionChannelRef": "distributionChannelRef",
  "settlementDate": "2024-08-25",
  "settlementNo": 0,
  "correctionForSmntId": 0,
  "externalSettlementNo": 0,
  "comments": [
    {
      "comment": "comment"
    }
  ],
  "genericTransactions": [
    {
      "transactionType": "ACMSALE",
      "orderId": "ORD123456",
      "orderVersion": 1,
      "genericAnnexes": [
        {
          "cancel": true,
          "guid": "guid",
          "annexRef": "annexRef",
          "attributes": {
            "key": "string"
          },
          "price": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "priceContribution": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "foreignAmount": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "description": "description",
          "context": {
            "key": {}
          },
          "parameters": [
            null
          ],
          "subAnnexes": [
            null
          ]
        }
      ]
    }
  ],
  "context": {
    "key": {}
  }
}'

Example Request Body

{
  "msgSubjectId": "msgSubjectId",
  "id": 0,
  "posRef": "posRef",
  "distributionChannelRef": "distributionChannelRef",
  "settlementDate": "2024-08-25",
  "settlementNo": 0,
  "correctionForSmntId": 0,
  "externalSettlementNo": 0,
  "comments": [
    {
      "comment": "comment"
    }
  ],
  "genericTransactions": [
    {
      "transactionType": "ACMSALE",
      "orderId": "ORD123456",
      "orderVersion": 1,
      "genericAnnexes": [
        {
          "cancel": true,
          "guid": "guid",
          "annexRef": "annexRef",
          "attributes": {
            "key": "string"
          },
          "price": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "priceContribution": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "foreignAmount": {
            "amount": "\"12345.34\"",
            "currency": "NOK",
            "taxCode": "\"25\"",
            "localTaxCode": "25A",
            "taxRate": "\"12.00\"",
            "weight": "\"1500.1234\""
          },
          "description": "description",
          "context": {
            "key": {}
          },
          "parameters": [
            null
          ],
          "subAnnexes": [
            null
          ]
        }
      ]
    }
  ],
  "context": {
    "key": {}
  }
}

json

Example Responses

{
  "id": 12345,
  "posRef": "posRef",
  "settlementDate": "2024-08-25",
  "settlementNo": 0,
  "correctedSettlementId": 0,
  "externalSettlementNo": 0,
  "ignoreSequence": false,
  "comments": [
    "string"
  ],
  "status": "0",
  "statusDescription": "Partner Settlement queued for processing."
}

json

application/json

Get a settlement by id.

GET

https://api.entur.io/clearing

/v1/settlement-import/{id}

Get the details of a settlement to see its status or any errors that occurred during clearing.

Get a settlement by id. › path Parameters

id

integer · int64 · required · style: simple

Get a settlement by id. › Headers

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Get a settlement by id. › Responses

Relevant information on the successfully registered Settlement Import. See documentation for PartnerSettlementImportDto for details on fields that the client submitted.

PartnerSettlementImportResponseDto

id

integer · int64

Unique identifier of queued Settlement Import.

posRef

string

settlementDate

string · date

settlementNo

integer · int64

correctedSettlementId

integer · int64

externalSettlementNo

integer · int64

ignoreSequence

boolean

Indicates whether sequence errors will be ignored during import, typical for negative settlement sequences (corrections).

comments

string[]

status

integer · int32

Status code indicating the result of the import operation. This will always be 0 (TO BE PROCESSED) on creation. 1 indicates SUCCESSFUL CLEARING

Example: 0

statusDescription

string

Message providing additional information on the import status.

Did you find what you were looking for?

Incoming Settlements

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using.

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Headers

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Request Body

Submit a Generic Settlement for asynchronous clearing. Read the Developer Guide before using. › Responses

Get a settlement by id.

Get a settlement by id. › path Parameters

Get a settlement by id. › Headers

Get a settlement by id. › Responses

Build with Entur

Contribute

Terms & Policies