> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/docs/trade-settlement/initiate-trade-settlement/main.md).

# Initiate Trade Settlement

| Campo              | Valor                                                         |
| ------------------ | ------------------------------------------------------------- |
| **Service Domain** | Trade Settlement                                              |
| **BIAN Version**   | 14                                                            |
| **Operation**      | Trade Settlement                                              |
| **Method**         | POST                                                          |
| **API Name**       | Trade Settlement API                                          |
| **Versão**         | v1.0.0                                                        |
| **Endpoint**       | `POST /v1/trade-settlement/TradeSettlementProcedure/Initiate` |
| **Autenticação**   | Bearer Token (OAuth 2.0 / OIDC)                               |

***

## 1. Descrição da Operação

A API **Trade Settlement** permite iniciar o processo de liquidação de uma operação financeira resultante de uma transação de mercado.

A liquidação pode envolver:

* Transferência de fundos;
* Liquidação de títulos;
* Liquidação DvP;
* Liquidação FoP;
* Liquidação parcial;
* Liquidação total.

A API suporta liquidação em moeda local (AKZ) e integra com sistemas de liquidação e compensação.

### 1.1 Descrição Funcional

A API permite:

1. Criar procedimento de liquidação;
2. Registrar instrução;
3. Registrar transação;
4. Associar conta;
5. Definir data;
6. Executar liquidação.

***

## 2. Cabeçalhos HTTP

| Header          | Tipo   | Obrigatório | Descrição          |
| --------------- | ------ | ----------- | ------------------ |
| `Authorization` | String | Sim         | Bearer Token       |
| `Content-Type`  | String | Sim         | `application/json` |
| `Accept`        | String | Sim         | `application/json` |
| `x-request-id`  | String | Não         | Identificador      |
| `x-channel`     | String | Não         | Canal              |

A API utiliza autenticação baseada em Bearer Token (OAuth2 ou JWT).

**Exemplo**

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

***

## 3. Payload de Pedido (Request)

### 3.1 Exemplo

```json
{
  "tradeSettlementProcedure": {
    "tradeSettlementProcedureReference": {
      "identifierValue": "TSP-ANG-20260303-INIT001",
      "identifierIssuerReference": {
        "partyReference": "BANK-ANGOLA-001",
        "involvementReference": "SETTLEMENT-INITIATOR"
      }
    },
    "procedureType": "MarketTradeSettlement",
    "selectedSettlementOption": {
      "featureType": "SettlementFeature",
      "featureIdentification": {
        "identifierValue": "OPT-DVP-AKZ",
        "identifierIssuerReference": {
          "partyReference": "BODIVA-CLEARING",
          "involvementReference": "CSD-ANGOLA"
        },
        "identifierStartDate": {
          "dateTimeContent": "2026-03-03T16:30:00",
          "timeZoneCode": "WAT",
          "dateTimeType": "EffectiveDate"
        },
        "identifierEndDate": {
          "dateTimeContent": "2026-03-10T23:59:59",
          "timeZoneCode": "WAT",
          "dateTimeType": "ExpiryDate"
        }
      },
      "featureName": {
        "name": "Delivery Versus Payment in AKZ"
      },
      "featureDescription": "Initiate DvP settlement for local equity trade"
    },
    "settlementInstruction": {
      "instructionIdentification": {
        "identifierValue": "INST-20260303-TRADE789",
        "identifierIssuerReference": {
          "partyReference": "BROKER-LUANDA-XYZ",
          "involvementReference": "EXECUTING-BROKER"
        },
        "instructionIdentificationType": "SettlementInstructionId"
      },
      "instructionType": "TradeSettlementInstruction",
      "instructionDate": {
        "dateTimeContent": "2026-03-03T16:30:00",
        "timeZoneCode": "WAT",
        "dateTimeType": "DueDate"
      },
      "instructionStatusType": "PendingProcessing",
      "instructionDescription": "Initiation of settlement for market trade 789 - cash leg in AKZ"
    },
    "transactionDetails": {
      "transactionIdentification": {
        "identifierValue": "TXN-TRADE789-SETT-INIT",
        "identifierIssuerReference": {
          "partyReference": "BODIVA-CCP",
          "involvementReference": "CENTRAL-COUNTERPARTY"
        }
      },
      "transactionDate": {
        "dateTimeContent": "2026-03-03T14:00:00",
        "timeZoneCode": "WAT",
        "dateTimeType": "ExecutedDate"
      },
      "transactionType": "FinancialTransaction",
      "transactionDescription": "Local Angolan market trade settlement initiation - securities delivery vs cash payment",
      "transactionStatusType": "Initiated",
      "transactionAmount": 1500000.00,
      "transactionCurrency": "AKZ",
      "transactionMissingAmount": 0.00,
      "accountIdentification": {
        "accountIdentificationType": "BBAN",
        "accountIdentification": {
          "value": "8067305810001"
        },
        "accountType": "CreditorRelatedAccount",
        "accountCurrency": {
          "currencyCode": "AKZ"
        }
      },
      "settlementDate": {
        "dateTimeContent": "2026-03-05",
        "timeZoneCode": "WAT",
        "dateTimeType": "SettlementDate"
      },
      "settlementStatus": "Pending"
    }
  }
}
```

### 3.2 Tabela de Objetos e Cardinalidade

| Objeto                   | Campo                    | Tipo   | Cardinalidade | Descrição  |
| ------------------------ | ------------------------ | ------ | ------------- | ---------- |
| TradeSettlementProcedure | ProcedureReference       | Object | 1..1          | Referência |
| TradeSettlementProcedure | ProcedureType            | String | 1..1          | Tipo       |
| TradeSettlementProcedure | SelectedSettlementOption | Object | 1..1          | Opção      |
| TradeSettlementProcedure | SettlementInstruction    | Object | 1..1          | Instrução  |
| TradeSettlementProcedure | TransactionDetails       | Object | 1..1          | Transação  |
| TransactionDetails       | AccountIdentification    | Object | 1..1          | Conta      |

### 3.3 Objecto: `TradeSettlementProcedure`

| Campo                               | Tipo   | Obrigatório | Descrição  |
| ----------------------------------- | ------ | ----------- | ---------- |
| `TradeSettlementProcedureReference` | Object | Sim         | Referência |
| `ProcedureType`                     | String | Sim         | Tipo       |
| `SelectedSettlementOption`          | Object | Sim         | Opção      |
| `SettlementInstruction`             | Object | Sim         | Instrução  |
| `TransactionDetails`                | Object | Sim         | Transação  |

### 3.4 Objecto: `SelectedSettlementOption`

| Campo                   | Tipo   | Cardinalidade | Descrição |
| ----------------------- | ------ | ------------- | --------- |
| `FeatureType`           | String | 1..1          | Tipo      |
| `FeatureIdentification` | Object | 1..1          | ID        |
| `FeatureName`           | String | 1..1          | Nome      |
| `FeatureDescription`    | String | 0..1          | Descrição |

### 3.5 Objecto: `SettlementInstruction`

| Campo                       | Tipo   | Cardinalidade | Descrição |
| --------------------------- | ------ | ------------- | --------- |
| `InstructionIdentification` | Object | 1..1          | ID        |
| `InstructionType`           | String | 1..1          | Tipo      |
| `InstructionDate`           | Date   | 1..1          | Data      |
| `InstructionStatusType`     | String | 1..1          | Estado    |
| `InstructionDescription`    | String | 0..1          | Descrição |

### 3.6 Objecto: `TransactionDetails`

| Campo                       | Tipo    | Cardinalidade | Descrição |
| --------------------------- | ------- | ------------- | --------- |
| `TransactionIdentification` | Object  | 1..1          | ID        |
| `TransactionDate`           | Date    | 1..1          | Data      |
| `TransactionType`           | String  | 1..1          | Tipo      |
| `TransactionStatusType`     | String  | 1..1          | Estado    |
| `TransactionAmount`         | Decimal | 1..1          | Valor     |
| `TransactionCurrency`       | String  | 1..1          | Moeda     |
| `AccountIdentification`     | Object  | 1..1          | Conta     |
| `SettlementDate`            | Date    | 1..1          | Data      |
| `SettlementStatus`          | String  | 1..1          | Estado    |

***

## 4. Estados de Liquidação

| Estado      | Descrição |
| ----------- | --------- |
| `Initiated` | Iniciado  |
| `Pending`   | Pendente  |
| `Settled`   | Liquidado |
| `Failed`    | Falhou    |

***

## 5. Payload de Resposta (Response — Sucesso)

```json
{
  "tradeSettlementProcedureReference": "TSP-ANG-20260303-INIT001",
  "settlementStatus": "Pending"
}
```

***

## 6. Cenários de Utilização

**Liquidação DvP**

Fluxo:

1. Broker envia;
2. API valida;
3. API registra;
4. API liquida.

**Liquidação Manual**

Fluxo:

1. Operador inicia;
2. API executa.

**Liquidação Automática**

Fluxo:

1. Scheduler inicia;
2. API liquida.

***

## 7. Fluxo Sequencial

1. Cliente envia request;
2. API valida token;
3. API valida payload;
4. API valida conta;
5. API registra instrução;
6. API registra transação;
7. API agenda liquidação;
8. API retorna resposta.

***

## 8. Códigos HTTP de Resposta

| Código | Descrição            |
| ------ | -------------------- |
| 200    | Sucesso              |
| 201    | Criado               |
| 400    | Pedido inválido      |
| 401    | Não autorizado       |
| 403    | Proibido             |
| 404    | Conta não encontrada |
| 409    | Já existe            |
| 500    | Erro interno         |

***

## 9. Envelope Padrão de Erro

### 9.1 Cenário de Erro: Valor Inválido

```json
{
  "error": {
    "status": 400,
    "reason": "INVALID_VALUE",
    "message": "Invalid Srci-Client Id",
    "path": "POST /v1/corporate-trust/988776/escrow-arrangement/initiate",
    "errordetail": [
      {
        "code": "123332",
        "reason": "INVALID_VALUE",
        "message": "Invalid Srci-Client Id"
      }
    ]
  }
}
```

### 9.2 Cenário de Erro: Erro Interno

```json
{
  "error": {
    "status": 500,
    "reason": "INVALID_STATE",
    "message": "Internal server error. Typically a server bug. The client should report this error to the Mastercard support team",
    "path": "GET /v1/corporate-trust/988776/escrow-arrangement/initiate"
  }
}
```

***

## 10. Regras de Negócio

* Conta deve existir;
* Conta deve estar ativa;
* Valor deve ser positivo;
* Data válida;
* Moeda válida.

***

## 11. Requisitos Não-Funcionais

* HTTPS obrigatório;
* Bearer Token obrigatório;
* Auditoria obrigatória;
* Logging obrigatório.

***

## 12. Mapeamento BIAN

| BIAN                       | API        |
| -------------------------- | ---------- |
| `TradeSettlementProcedure` | Settlement |
| `SettlementInstruction`    | Instrução  |
| `FinancialTransaction`     | Transação  |
| `AccountReference`         | Conta      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/trade-settlement/initiate-trade-settlement/main.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.