Defining Invoice Fees

The system allows generating invoice fees relating to various transactions such as trades, payments, and messages.

The Billing engine subscribes to trade events, message events, and transfer events to generate invoice fees (billing trades) based on billing grids and fee billing rules.

Before you Begin

You can set a default book for billing trades in the legal entity attribute "FUNDING BOOK" of the legal entity that pays / receives the fee (broker, counterparty, agent, etc.).

The fee types for billing fees are created in the Fee Definition.

Example:

Billing Trade Workflow

Billing trades follow the standard trade workflow. However, make sure that the AMEND action is available, as new billing fees will be added to the same trade during the billing period, and the billing trade will therefore be amended. Also, it is recommended to move the billing trade to a status that can no longer be amended at the end of he billing period.

1. Defining Billing Grids

The billing grid allows automating the fee calculation for trades, messages, and transfers.

From the Calypso Navigator, navigate to Configuration > Fees, Haircuts & Margin Calls > Fee Set Up (menu action refdata.FeeSetUpWindow), and select the Billing Grid panel.

Sample billing grid for invoice fee

Enter the fee application criteria as needed and select the event type for which the fee will be generated: Message, Trade, or Transfer.

Enter the validity dates of the grid - They apply to the selected "Fee Value Date" of the related object.

See Note on "Fee Value Date" for details.

Fill in the Description field to describe the grid. This field is mandatory.

You can check "Use Multiple Calculators" to generate a fee for each applicable calculator. Otherwise, a fee is generated only for the first applicable calculator.

The event types Account and MaintenanceTrade apply to account management fees.

See Cash Management - Management Fees for details on account management fees.

Select a calculator (Default, FeeConfig, FTT), and click Add to define the calculator.

–

For the Default calculator, the fee will be computed based on the amount defined here.

Enter a description and an amount. The amount can be signed: "-" means the PO pays the fees, "+" means the PO receives the fee.

You can check "use Time Period" to select a date rule to generate the fee.

Then click Apply.

–

For the FeeConfig calculator, the fee will be computed based on a fee schedule defined in the Fee Config panel.

See Defining Invoice Fee Schedules for details on defining fee schedules for invoice fees.

You can check the "Split by book" checkbox to allocate the fees to the original books, and click Apply.

–

FTT allows computing the Financial Transaction Tax on the physical settlement of securities.

See Computing the Financial Transaction Tax for full setup details.

Save the billing grid.

Note that if the Authorization mode is enabled, an authorized user must approve your entry.

Note on “Fee Value Date”

The “Fee Value Date” determines which date on the billing event should be used to select the Billing Grid and the Billing Rule.

By default, it can be set to the following values based on the type of event:

•

Messages: CurrentDate (Today), CustomDate (if the Fee Value Date of the billing event has been customized), MessageCreationDate, or MessageSettleDate – You can add more types of dates to the domain “billingMessage.feeValueDates”.

•

Trades: CurrentDate, CustomDate, TradeDate, or TradeSettleDate – You can add more types of dates to the domain “billingTrade.feeValueDates”.

•

Transfers: CurrentDate, CustomDate, TransferValueDate, or TransferSettleDate – You can add more types of dates to the domain “billingTransfer.feeValueDates”.

2. Defining Fee Billing Rules

The billing rule allows defining the billing frequency, and a billing threshold if needed.

Define the Billing rules from the Calypso Navigator using Configuration > Fees, Haircuts & Margin Calls > Fee Billing Rule (menu action refdata.FeeBillingRuleWindow).

Sample billing rule for invoice fee

Enter the following fields:

–

Select a legal entity, or double-click the Legal Entity label to set the legal entity to ALL.

–

Select the same role as in the billing grid.

–

Select the billing currency or ANY.

–

Select the billing date rule to determine the billing frequency.

–

Select the settlement date rule to determine the settlement frequency of the fee.

–

Input Date Type - Select the reference date to load the trades, messages, transfers:

TradeDate - Trade date

SettleDate - Trade value date

FeeDate - Fee date (Fee Value Date defined in the Billing Grid)

EnteredDate - Trade entered date

–

Open the "Defaults Trade Billing Values" panel, and select the transfer type of the billing trade as needed. If not set, the transfer type is set to INTEREST. Note that transfer types are defined in the domain “flowType”.

Ⓘ [NOTE: If the attribute EntryType is set, and the Default Transfer Type is not set, the transfer type defaults to the EntryType]

You also need to define the following attributes - This only applies if you have selected the FeeConfig calculator in the Billing Grid.

–

BillingAggregation - When set to true, the system does not create the billing fees. It creates billing fee details that can be aggregated into a single billing fee using the scheduled task EOD_BILLING_AGGREGATION.

See Aggregating Billing Fees for details.

–

BillingOnly - Set to True so that it is only used for billing trades.

–

EntryType - Set to the fee type ,"BROKERINVFEE" for example.

–

XferByBook - Set to True to create a transfer by book.

You can click Domain to add an attribute if it is not available.

Save the billing rule.

Note that if the Authorization mode is enabled, an authorized user must approve your entry.

3. Generating Invoice Fees

The Billing engine is used to create the billing fees.

3.1 Configuring the Billing Engine

The Billing engine is configured in the Engine Manager of Web Admin: event subscription and engine parameters.

You may need to add this engine if it is not available for configuration: Create a new engine called BillingEngine, with class name com.calypso.engine.billing.BillingEngine.

The Billing engine must subscribe to the following events: PSEventTrade, PSEventMessage, PSEventTransfer.

The behavior of the Billing engine may be modified with the following engine parameters.

If a parameter is not available for setup, you can register it in the domain "engineParam".

Parameters	Description
IGNORE_ACTION	Comma-separated list of trade actions to be ignored by the engine.
MAX_BATCH_EVENT	Maximum number of persistent events loaded at one time by an engine in batch mode. The engine will load events in MAX_BATCH_EVENT chunks until all events are processed. Persistent events received after MAX_QUEUE_SIZE is reached will be processed in batch mode. Allows controlling engine memory usage, therefore improving the performance.
MAX_QUEUE_SIZE	Maximum number of events buffered on an engine event queue. When this number is exceeded, real time events are discarded and the engine restarts based on the restart timer (TIMEOUT_RESTART), in order to process the unprocessed persistent events using batch mode. This parameter can be useful for controlling the engine’s memory usage. If not set, the default value for this parameter is no limit on queue size. Allows controlling engine memory usage, therefore improving the performance.
PricingEnv	Pricing environment used by the engine. If not set, the default Pricing Environment of the user running the engine will be used.
TIMEOUT_RESTART	Number of seconds to wait before an engine restarts after MAX_QUEUE_SIZE has been reached. The default value is 3600 seconds (1 hour).

3.2 Starting the Billing Engine

The Billing engine can be started from the Engine Manager in Web Admin.

Please refer to Calypso Web Admin documentation for complete details.

In order to update the same billing trade for a given counterparty, account ID and billing rule ID, you need to provide the account ID in a trade keyword. The trade keyword that holds the account ID information must be defined in the domain “BillingAccountTradeKeyword”.

3.3 Aggregating Billing Fees

When the Fee Billing Rule attribute "BillingAggregation=true" the billing fees are not created directly. The system publishes a PSEventTrade, processed by the Billing engine, when a trade is booked. If valid Billing Grid, Fee Config (optional) and Billing Rule are found, the system creates billing fee details. Billing fee details can then be aggregated into a single billing entry (creation of a new billing trade, or update of an existing one) using the scheduled task EOD_BILLING_AGGREGATION.

You can set the following attributes:

•

APPLY ACTION - It is possible to specify the action to be applied by the scheduled task. It is AMEND by default.

•

LegalEntity - Enter the Legal Entity short name to reduce the scope of the Scheduled Task or leave blank.

3.4 Billing Fees for Trade Events

When a trade is booked, the system publishes a PSEventTrade which is processed by the Billing engine. If valid Billing Grid, Fee Config (optional) and Billing Rule are found, the system creates a billing entry (creation of a new billing trade, or update of an existing one). This billing entry is linked to the original trade.

3.5 Billing Fees for Transfer events

When a transfer is created by the transfer engine, the system publishes a PSEventTransfer which is processed by the Billing engine. If valid Billing Grid, Fee Config (optional) and Billing Rule are found, the system creates a billing entry (creation of a new billing trade, or update of an existing one) linked to this transfer. This billing entry is linked to the original transfer (and trade if known).

3.6 Billing Fees for Message Events

When a message is created by the message engine, the system publishes a PSEventMessage which is precessed by the Billing engine. If valid Billing Grid, Fee Config (optional) and Billing Rule are found, the system creates a billing entry (creation of a new billing trade, or update of an existing one) linked to this message. This billing entry is linked to the original message (and transfer or trade if known).

3.7 Example

For example, the processing organization, receives $2,000 each time it generates a message for the agent.

The Billing engine subscribes to message events and generates a Billing trade. The system generates one trade per billing period. So, every new message will create an update of this Billing trade.

From the Calypso Navigator, navigate to Processing > Accounting Operations > Billing > Trade > Open (menu action trading.TradeBillingWindow). It opens the Trade Selector. Click Show Trades to view all billing trades. Double-click a trade to view its details.

Sample billing fee trade

Select the Billing Fees panel to see the details of each fee:

You can select a row and click Billing Event to open the corresponding event report - Message report in this case.

You can click Billing Grid to see the detail of the grid used for this calculation.

Billing Fee Override

Sample billing fee override

Check the "Manual amount" column and enter the modified amount in the "Converted Amount" column.

To prevent the fee from being automatically recomputed upon saving the trade, clear the Override column.

Save the trade.