Documentation
Settlement Tracking
An introduction to Settlement Tracking.
Settlement Progress can be Tracked
Responsibility for settlement is handed over to the Users of this system. However, a facility is provided to allow Users to identify which trades await settlement, which trades are in progress, and which trades are settled.
Each trade involves two Orders matching and executing. Each execution creates two Fill records, one for the Buy Order and one for the Sell Order. The Fill records have a field called SettlementState that can be updated to reflect the progress of the settlement process, even though the process is outside this system.
This allows Users to check off which executions are new, which are in progress, and which are resolved and settled.
Settlement State
Fill records have a SettlementState field that can be set to one of the following values...
- NEW: The Fill has been created but settlement has not begun.
- PENDING: Trading counterparties have been notified of the execution, or an external process has started the customer fulfilment process.
- SETTLED: Counterparties have completed settlement, or the customer fulfilment process is finished.
- BUSTED: The trade has been unwound and will not be settled.
- ERROR: An error has occurred and needs manual resolution.
Note that Fills are linked by the unique identifier for the execution, so the two Fills created by that execution remain permanently associated. Both Fills therefore share the same SettlementState. API functions that update the SettlementState use the execution's unique identifier so that both Fills are updated at the same time to the same state.
NEW Settlement State
When a match results in an execution, a Fill record is created for each Order. The Fill records are created with the SettlementState field set to NEW.
PENDING Settlement State
A User of the system with the FILL right will query for new Fill data to begin their settlement process. Once a Fill record has been received, the domain-specific settlement process can begin, and the User handling settlement can make a call back to this system to set the SettlementState of both Fills to PENDING. When the User later queries for Fill records in NEW state, they will see only newly created Fills and any earlier Fills whose settlement process has not yet begun.
As such, the PENDING state can be used to check off Fills and to mark them as under way. For example, payment may have been requested and delivery might be in progress.
SETTLED Settlement State
Once the off-system settlement process is completed (customer has paid and delivery is complete), the User handling settlement can make a call back to this system to update the Fills and set them to SETTLED.
BUSTED Settlement State
A trade might be unwound for any number of reasons. The trade might have been a genuine error, or might have been illegal, prohibited or related to fraud.
A User handling settlement can mark such trades with a SettlementState field value of BUSTED, so that these Fills remain recorded but are excluded from normal settlement processing.
ERROR Settlement State
If a trade somehow manages to get into an unresolved state, perhaps because one counterparty claims the trade is settled and another disputes this, then the SettlementState for both Fills can be set to ERROR. The intention is that the problem will be resolved manually or externally, and once resolved, the Fills can be moved to the appropriate state such as BUSTED or SETTLED.
Using Settlement State is Optional
Users of the system do not have to use the SettlementState field at all. Management of the process of settlement can be handled entirely externally.
The ability to update SettlementState is provided as a convenience to Users.
Settlement Notification
When a Market is used by a single User, that single User routes customer Buy Orders to the Market to match with employee Sell Orders. In this use case, the settlement is also handled by the same User, as customer sales go through the business-specific fulfilment process.
If a Market is used by a group of peer Users, like an association of farmers trading together, settlement could be handled by each User. In this situation, the Market provides a way to notify the two counterparties of a trade, so that they can settle between themselves as they see fit.