> 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/service-domain/trade-settlement/operacoes/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.