About Generic Settlements
A Generic Settlement is a data structure used to clear financial transactions between financially relevant parties. It's a flexible, extensible structure for representing settlement data in a standardized format that can be process directly, eliminating the need for custom integration modules. The settlement also documents the resulting General Ledger entries.
Settlements are processed atomically — they either succeed completely or fail entirely, ensuring data integrity. The Clearing system supports several settlement variants, but each requires custom mapping logic to transform external data into clearing-compatible structures. The mapping logic needs to be configured by Entur before the settlements is submitted.
This document focuses on submitting Generic Settlements as supported by the Clearing API.
Settlement clearing is a complex topic requiring solid understanding of accounting principles, VAT regulations, business requirements, and configuration of the Clearing system.
This guide enables developers to submit Generic Settlements but does not cover the full scope of settlement clearing. Developers must collaborate closely with the Chart of Accounts administrator to ensure proper modelling of the data to be cleared.
Settlement Structure
A Settlement can model any type of financial transaction data, not limited to fare product sales. Relevant use cases include:
- Cash Deposit transactions
- Settlement corrections
- Payment provider reconciliation
- Third-party marketplace transactions
- Revenue sharing agreements
- Sales commission calculations
The structure is designed to support wide number of clearing mechanisms, with extensibility for future requirements.
The following diagram illustrates the hierarchical structure of a Settlement:
Structure Overview
Settlements consist of hierarchical elements — Transactions, Annexes, and Parameters — each with unique identifiers and attributes that provide additional context for clearing and reporting.
The "Generic" designation reflects the structure's ability to model any type of settlement data, not just fare products. This flexibility enables the Clearing system to process diverse financial scenarios through a standardized format.
Persistent Storage and Transaction Boundaries
PersistedSettlement and PersistedTransaction represent settlements and transactions as stored in the Clearing system. These
define the atomic units of work for settlement processing and establish important operational boundaries for API integration.
Transaction content is stored as JSON, enabling the flexible structure that makes Generic Settlements possible. The key distinction between persistent and parsed structures lies in their identity management:
Settlement processing guarantees:
- Settlements are processed atomically — they either succeed completely or fail entirely (COMMIT or ROLLBACK semantics)
- Individual
PersistedTransactionentries can be replaced through correction settlements to resolve processing failures - Corrections cannot target individual annexes or parameters within the JSON structure, only complete transactions can be replaced
- Annexes may include custom GUIDs in the incoming settlement for external tracking purposes
- The Clearing system assigns transient GUIDs to all annexes without client provided GUID, useful for aggregation and reporting
Key point: Settlement and transaction identities are persistent and stable across systems (GUI, API, logs). Annex identities within the JSON structure are transient unless explicitly provided as GUIDs by the client.
Structure Inheritance
The Generic Settlement structure uses inheritance to propagate attributes and context values through the hierarchy. The following overview is essential to understand the importance of constructing settlements correctly.
Inheritance rules:
- Annex identity inheritance: All annex IDs are inherited from parent annexes and automatically added to child annex attributes
- Parameter propagation: Parameters add their ID, attributes, and context values to their associated annex
- Recursive attribute inheritance: All annex attributes and context values cascade recursively from parent to child annexes
Benefits:
This inheritance model enables concise settlement representation by sharing common data across hierarchies, reducing redundancy and simplifying structure while maintaining full context at every level.
From the example above, the effective attributes and context for annex Product:345 are:
- Attributes:
- ids:
- POS
- DCI
- id=Product:345
- id=SalesPackage:123
- id=Discount
- POS
- keyB=valueB
- keyC=valueC
- keyD=valueD
- ids:
- Context:
- keyF=valueF
- keyG=valueG
Note that keyE=valueE is not included, as it belongs to sibling annex Product:456 and does not propagate to
Product:345.
The inheritance of attributes in particular enables clearing rules to target specific combinations of annexes and
parameters, such as applying custom logic when Product:345 appears under discount Discount:Child within the
context of SalesPackage:123.
The entire settlement is during the normalization phase of the clearing process modelled as a single hierarchical tree structure. The settlement itself appears to the clearing engine as the root of a single annex.
This inheritance model is the core mechanism that enables the Clearing system to flatten hierarchical tree structures into tabular rows for clearing and reporting, where each row contains the complete inherited context from its ancestor chain. Each possible path from the root annex to a leaf annex represents a potential row in the flattened dataset.
Example: Birthday Package Settlement
The following example demonstrates a Generic Settlement for a complex multi-party transaction; a birthday package sale at ACME Cafe. This example deliberately uses a non-transport scenario to illustrate the structure's flexibility beyond fare products.
Business scenario:
ACME Cafe sells a birthday package combining products from partners Baker Hansen (BKH) and The Coffee Experts (CFE) with entertainment services provided by external clown providers. The sale includes:
- A seasonal Christmas campaign discount on all packages
- Senior citizen rebates
- Room rental fees for hosting the party
- A composite product sourced partly from external partners (BKH and CFE)
The example above can be cleared by submitting the following JSON representation.
Code
Understanding the Settlement Structure
Transaction composition:
- Settlements contain one or more transaction types, each representing a distinct business operation
- This example includes
ACMSALESPACKAGE(representing the sale) andACMPAY(representing payment collection) - Each transaction type may have specific clearing and reporting requirements
Hierarchical relationships:
- Parameters apply to their parent annex and cascade to all nested sub-annexes
- This hierarchical structure enables proportional distribution of adjustments (discounts, fees) across multiple components
- Annexes can be nested to model complex product structures
Identifiers and price contributions:
- Each annex and parameter requires a unique
annexRefidentifier following the namespace format (NAMESPACE:TYPE:IDENTIFIER) - Price contributions can be positive (revenue, fees) or negative (discounts, refunds)
- Transaction totals equal the sum of all annex and parameter price contributions
Tax handling:
- Different annexes may have distinct tax rates and codes based on product/service classification
- Tax information (
taxRate,taxCode) is specified per price contribution - In this example, tax rates range from 0% (not applicable for payments) to 25% (standard VAT)
- Discounts and fees may span multiple tax rates, making the clearing more complex
Price adjustments:
- The top-level annex includes a
-0.01price contribution to round the total to a whole number - This adjustment technique ensures customer-facing prices match business requirements
Extensibility:
- Use
attributesto provide data that influences clearing logic (e.g.,paymentType,clownProvider) - Use
contextto include supplementary reporting data (e.g.,roomNumber,clownName) - Context values must be explicitly referenced in reporting templates to appear in reports
Clearing Flexibility and Business Logic
The settlement structure provides information for clearing but does not dictate clearing behavior. Actual clearing logic is determined by Clearing Mappings configured in the Clearing system. This is done by Entur.
Example clearing scenarios:
- Context-driven reporting: The room rental fee parameter includes
roomNumberandnumberOfHourscontext values that enable detailed facility utilization reports - Provider-specific routing: The clown service annex uses the
clownProviderattribute to support separate clearing agreements with different service providers - Partner revenue sharing: External partner products (BKH, CFE) are modeled as sub-annexes, enabling accurate revenue distribution and inter-company accounting between ACME Cafe and its suppliers
- Commission extraction: Clearing rules can calculate and allocate commissions on partner product sales, ensuring ACME receives their contractual revenue share
- Proportional adjustments: The senior discount parameter applies to the
CoffeeAndCakeannex and cascades to all sub-annexes, automatically distributing the discount across multiple partners and tax codes weighted by their respectivepriceContributionvalues
Settlement Corrections
Any modification to previously submitted transactions requires a correction settlement. Due to the batched processing architecture, settlements may have already been cleared and reported before corrections are identified, making direct modification of previously submitted settlements impossible.
Correction mechanism:
Corrections use a two-step approach within a single settlement:
- Reversal: A complete reversal of the original transaction (DEBIT and CREDIT switched), negating the original entry in the General Ledger
- Replacement: A new transaction containing the corrected data, effectively superseding the original
Refunds as corrections:
Refunds follow the same pattern but serve a different business purpose:
- Reversal: A complete reversal of the original sales transaction (DEBIT and CREDIT switched), negating the original entry
- Credit: A new credit transaction that returns funds to the customer
Implementation:
- Set the
cancelfield totrueon the root annex in the reversal transaction - Include both the cancellation and replacement transactions in the same settlement submission
- Optionally reference the original settlement using the
correctionForfield at the settlement level
Key point: Corrections must include both the reversal and optional replacement within a single settlement to maintain proper accounting and audit trails.
Client Responsibilities
Clients submitting settlements act as Settlement Agents in Entur clearing terminology. A Settlement Agent is the authenticated organization responsible for submitting settlements on behalf of one or more clearing partners.
Settlement Agent scope:
Typically, a Settlement Agent represents only itself. However, in marketplace or platform scenarios, a single Settlement Agent may represent multiple partners. For example, Entur acts as the Settlement Agent for all partner products sold through its platform.
Delegated responsibilities:
The Settlement Agent is a trusted role with delegated responsibility for ensuring settlement accuracy and completeness. This includes:
- Structural correctness: Verify that settlements are properly formatted and balanced
- Authorization: Ensure proper authentication and authorization for all submitted data
- Data scope: Include only information relevant to the Agent and its partners
- Validation: Confirm that point of sale references, distribution channels, VAT codes, and tax rates are correct
- Legal compliance: Recognize that submitted settlements constitute legal vouchers for accounting purposes
Validation and correction:
Depending on incoming data quality, Settlement Agents may need to implement local staging areas for validation and correction before submission to the Clearing system.
The Clearing system performs validation during settlement processing, but the failed settlement lists is not currently self-serviced. Any settlement failing clearing requires manual analysis and correction by the Chart of Accounts Administrator in cooperation with the Settlement Agent.
Under Norwegian accounting regulations, submitted settlements are considered vouchers for accounting data. The Settlement Agent assumes full responsibility for data accuracy, completeness, and compliance with accounting and VAT reporting requirements.
Best Practices
Multiple approaches exist for modeling settlements. Consider these best practices when creating Generic Settlements:
Settlements Must Be Balanced
A settlement must ultimately balance (SUM DEBIT = SUM CREDIT). For example, the Payment transaction must accompany the Sales Package transaction within the same settlement. The specific balancing mechanism depends on your business scenario, the clearing configuration and accounting rules configured.
Key point: Submitting separate settlements for each transaction type will likely fail, as each settlement must be balanced independently.
Transaction Types Should Represent Logical Units of Work
Transaction types define logical units of work with shared context. For example, a sales package transaction
(ACMSALESPACKAGE) and its associated payment transaction (ACMPAY) are separate transaction types with distinct
clearing and reporting requirements.
Each transaction type typically has several associated reporting templates showing columns relevant to that
transaction's context.
New transaction types must be registered by the Clearing administrator and assigned to all relevant Charts of Accounts before they can be submitted in settlements.
Key point: New transaction types require careful analysis and registration before use.
Hierarchical vs. Flat Annex Structures
Each price contribution can be represented as a separate annex directly under the transaction. However, this flat structure eliminates the ability to leverage annex relationships when defining clearing rules.
For example, clearing rules can target specific parent-child annex combinations, such as applying custom accounting
logic when ACM:HireService:ClownServicesLtd appears under ACM:Campaign:Christmas2025.
The hierarchical structure also enables proportional distribution of rebates and discounts across multiple annexes based on their relative price contributions.
Key point: Design the annex structure to match your clearing logic requirements. Use hierarchical nesting when clearing rules need to consider annex relationships.
Deep Annex Structures vs. Multiple Transactions
In our example, the takeaway goodie bag (BKH:Takeaway:Goodiebag) is modeled as a separate annex under the birthday
sales package transaction (ACM:SalesPackage:Birthday). However, this structure may be problematic if the cafe needs
to refund the goodie bag independently of the rest of the birthday package.
Key point: Split annexes into separate transactions when they require independent correction or refund capabilities.
Annex vs Parameter
Parameters are functionally similar to simply adding a parent annex with equivalent values, but parameters exhibit distinct inheritance behavior:
Bidirectional inheritance:
- The parameter inherits attributes and context from its associated annex (child-like behavior)
- The associated annex inherits values from the parameter (parent-like behavior)
Clearing perspective:
- Parameters can be cleared as child annexes of their associated annex
- Associated annexes can simultaneously be cleared as child annexes of their parameters
This bidirectional relationship creates a unique inheritance pattern. While the recursive structure technically allows parameters to have sub-annexes, this practice should be avoided.
Key point: Use parameters as modifiers (such as discounts, fees, or adjustments) applied to robust
annex structures rather than creating structural variations for each modification. This enables clearer semantics and
better reuse of existing clearing logic.
Attributes vs. Context
Use attributes for data that drives clearing logic, such as payment types or service provider identifiers. Use context for supplementary information needed for reporting or analysis that doesn't affect clearing rules.
Important considerations about the Clearing system:
- It's not a general-purpose data store. Include only essential reporting data in context: external references or critical metadata, not large data payloads.
- It may produce datasets containing the context values, but context not relevant for clearing should be joined with these datasets locally using external references from the datasets, not embedded directly in the settlement.
- Context values are not automatically included in reports. Each context key must be explicitly referenced in a reporting template column.
- Several context keys are already standardized and must be used as specified to ensure compatibility with existing reports. Consult the support team for details on standardized context keys.
Key point: Use attributes for clearing logic and context for reporting. Collaborate with the Chart of Accounts administrator when designing context for new transaction types to maintain compatibility with existing reporting templates.
Generic Settlements and 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.
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.
Identifier Requirements and Namespacing
The Clearing system is designed to process settlements from partners who may not use the broader Entur platform. This necessitates a highly flexible approach to identifier management.
Namespaced References ("refs"):
All identifier fields suffixed with Ref (such as posRef, distributionChannelRef, annexRef, etc.) must be
globally unique. This is achieved by enforcing a namespaced format: NAMESPACE:TYPE:IDENTIFIER. For example:
ACM:SalesPackage:Birthday. Each namespace must be registered with Entur prior to use.
The Clearing system maintains an internal mapping of refs to human-readable names, so descriptive labels are not required in the settlement payload.
Attribute Identifiers:
Identifiers used within the attributes map (e.g., paymentType, clownProvider) are not required to be globally
unique or follow a specific format. These are key-value pairs that may be referenced in clearing logic. Keys and values
should be concise, meaningful strings without special characters. The value may also be a namespaced ref.
Context Identifiers:
Identifiers within the context map (e.g., externalBatchId, roomNumber) are also not required to be globally unique
or follow a specific format. These values typically provide supplementary metadata for reporting or audit purposes.
When attribute or context values represent entities shared across partners (such as clownProvider in revenue-sharing
scenarios), naming conventions must be coordinated to ensure consistent interpretation in clearing logic.
Summary:
- All refs must be globally unique and namespaced.
- Attribute and context identifiers are flexible but should remain meaningful and consistent.
- Any ref can be assigned a display name for use in the GUI and reports.
Validation and Schema Flexibility
The Generic Settlement structure provides flexibility but does not accept arbitrary data structures. While basic structural validation occurs during submission, most validation is deferred to the asynchronous clearing process.
The Clearing system performs comprehensive consistency checks during clearing ("mottakskontroll"). Any validation failures cause the entire settlement to be rejected, requiring manual intervention.
Validation considerations:
- Schema validation is intentionally minimal. The effective "schema" is defined implicitly by clearing mappings and reporting templates configured in the Clearing system.
- As common patterns emerge, the system may introduce stricter validation for specific context values to ensure consistent reporting, especially for transaction types shared across multiple Charts of Accounts.
- Any changes to validation that is not compatible with existing settlements will be carefully analysed and communicated in advance.
- Incorrect structures may pass initial validation but fail during clearing or produce invalid reports.
Key point: Thoroughly validate settlement structures before submitting large volumes. Test with small batches first to avoid creating backlogs of failed settlements that require manual correction by the Chart of Accounts administrator.
Key point: Settlements may be unbalanced or structurally incorrect for any number of reasons (client bugs, delays, infrastructure issues etc). The Client must implement local validation and correction facilities before submission.