# Trade model: Settlement

This page describes the FX Integration API's **Settlement** trade model, as defined in the file `config/TradingAdapter/Blade/DataSource/etc/trademodels.xml` in the FX Integration API Kit.

This documentation is for the FX Integration API 12.10.0.

Trade models are XML-defined state machines used by the [Java Trading API](https://docs.caplin.com/developer/api/trading_java/latest/) and Caplin Trader's [Trading API](../caplin-trader/4/trading-api/index.md) to manage trading workflows. For more information on trade model XML definitions, see the [Trade model XML schema](../caplin-platform/cis/cis-trade-model-schema.md) reference.

## State model

The Settlement trade model's state model in Mermaid JS format:

```mermaid
%% State diagram for the Settlement trade model
stateDiagram-v2
    [*] --> Initial
    Initial --> Requested : Request (client)
    Requested --> Completed : Complete (server)
    Requested --> Error : Error (server)
    Completed --> [*]
    Error --> [*]
```

The Settlement trade model's state model in a flat state-transition matrix:

| Source state | Event trigger | Origin | Target state |
| ------------ | ------------- | ------ | ------------ |
| [*] | - | - | Initial |
| Initial | Request | client | Requested |
| Requested | Complete | server | Completed |
| Requested | Error | server | Error |
| Completed | - | - | [*] |
| Error | - | - | [*] |

## Event message specifications

This section describes the messages sent between client and server when a state-model event occurs. The origin of an event (the client or the server) is specified in brackets after the name of the event.

The specification of some events depends on the type of financial product being traded, and when this applies, the variant specifications are detailed under level-4 headings.

Back-end developers build server events by using classes in the Caplin's FX Integration API, a Java library that makes it easy to provide data to Caplin's web applications. Where appropriate, the specifications below include references to JavaDoc documentation and code examples.

### Event: Request (client)

Message specification:

```json
{
  "trade_model_name": "Settlement",
  "trade_model_trigger": "Request",
  "message_origin": "client",
  "parts": [
    {
      "part_name": "SettlementInstructions",
      "parts": [
        {
          "part_name": "SettlementInstructionLeg",
          "fields": [
            {
              "name": "Ln_TradeID",
              "type": "string",
              "flags": "",
              "definition": "A unique identifier for this trade",
              "example_value": "00001561",
              "deprecated": false
            },
            {
              "name": "Ln_PaymentID",
              "type": "",
              "flags": "",
              "definition": "The unique ID of the payment the client wants to net",
              "example_value": "",
              "deprecated": false
            }
          ]
        }
      ],
      "fields": [
        {
          "name": "Action",
          "type": "",
          "flags": "",
          "definition": "Affirm, Confirm, Dispute, Cancel, Replace, AutoConfirm, Unconfirm, Net, ApproveInstructions, RejectInstructions or Release",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "TradeID",
          "type": "string",
          "flags": "",
          "definition": "A unique identifier for this trade",
          "example_value": "00001561",
          "deprecated": false
        },
        {
          "name": "PayBankAccountType",
          "type": "",
          "flags": "",
          "definition": "The type of routing or BIC code assigned to an AdHoc Settlement Instruction on the pay side",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PaySettlementID",
          "type": "",
          "flags": "",
          "definition": "The ID corresponding to the payee's settlement details",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PaySettlementInstructionType",
          "type": "",
          "flags": "",
          "definition": "The type of settlement instruction on the pay side.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIsAdhocForCommit",
          "type": "",
          "flags": "",
          "definition": "If the pay settlement instruction is an adhoc that should be saved.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayAdhocForCommitDirection",
          "type": "",
          "flags": "",
          "definition": "The direction(s) the adhoc settlement instruction should be saved on.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PaySettlementDisplayName",
          "type": "",
          "flags": "",
          "definition": "The name of the paying settlement instruction",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankAccount",
          "type": "",
          "flags": "",
          "definition": "The account number of the payee's bank",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankAddress1",
          "type": "",
          "flags": "",
          "definition": "The first line of the payee's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankAddress2",
          "type": "",
          "flags": "",
          "definition": "The second line of the payee's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankAddress3",
          "type": "",
          "flags": "",
          "definition": "The third line of the payee's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankName",
          "type": "",
          "flags": "",
          "definition": "The name of the payee's bank",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayBankSwift",
          "type": "",
          "flags": "",
          "definition": "The BIC of the payee's bank ",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIndividualAccount",
          "type": "",
          "flags": "",
          "definition": "The account number of the payee",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIndividualAddress1",
          "type": "",
          "flags": "",
          "definition": "The first line of the payee",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIndividualAddress2",
          "type": "",
          "flags": "",
          "definition": "The second line of the payee",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIndividualName",
          "type": "",
          "flags": "",
          "definition": "The name of the payee",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PayIndividualSwift",
          "type": "",
          "flags": "",
          "definition": "The BIC of the payee's account",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankAccountType",
          "type": "",
          "flags": "",
          "definition": "The type of routing or BIC code assigned to an AdHoc Settlement Instruction on the receive side",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveSettlementID",
          "type": "",
          "flags": "",
          "definition": "The ID corresponding to the recipient's settlement details",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveSettlementInstructionType",
          "type": "",
          "flags": "",
          "definition": "The type of settlement instruction on the receive side.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIsAdhocForCommit",
          "type": "",
          "flags": "",
          "definition": "If the receive settlement instruction is an adhoc that should be saved.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveAdhocForCommitDirection",
          "type": "",
          "flags": "",
          "definition": "The direction(s) the adhoc settlement instruction should be saved on.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveSettlementDisplayName",
          "type": "",
          "flags": "",
          "definition": "The name of the receiving settlement instruction",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankAccount",
          "type": "",
          "flags": "",
          "definition": "The account number of the recipient's bank",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankAddress1",
          "type": "",
          "flags": "",
          "definition": "The first line of the recipient's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankAddress2",
          "type": "",
          "flags": "",
          "definition": "The second line of the recipient's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankAddress3",
          "type": "",
          "flags": "",
          "definition": "The third line of the recipient's bank's address",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankName",
          "type": "",
          "flags": "",
          "definition": "The name of the recipient's bank",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveBankSwift",
          "type": "",
          "flags": "",
          "definition": "The BIC of the recipient's bank ",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIndividualAccount",
          "type": "",
          "flags": "",
          "definition": "The account number of the recipient",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIndividualAddress1",
          "type": "",
          "flags": "",
          "definition": "The first line of the recipient",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIndividualAddress2",
          "type": "",
          "flags": "",
          "definition": "The second line of the recipient",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIndividualName",
          "type": "",
          "flags": "",
          "definition": "The name of the recipient",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIndividualSwift",
          "type": "",
          "flags": "",
          "definition": "The BIC of the recipient's account",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ReceiveIntermediaryDetection",
          "type": "",
          "flags": "",
          "definition": "The intermediary detection flag for AdHoc Settlement Instruction",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "SettlementStatus",
          "type": "string",
          "flags": "",
          "definition": "Caplin supported statuses are [PENDING, AFFIRMED, CONFIRMED, DISPUTED, CANCELLED, REPLACED, AUTO_CONFIRMED, OVERDUE, REJECTED]",
          "example_value": "",
          "deprecated": false
        }
      ]
    }
  ],
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "Request",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: Complete (server)

Message specification:

```json
{
  "trade_model_name": "Settlement",
  "trade_model_trigger": "Complete",
  "message_origin": "server"
}
```

### Event: Error (server)

Message specification:

```json
{
  "trade_model_name": "Settlement",
  "trade_model_trigger": "Error",
  "message_origin": "server"
}
```