> 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/corporate-trust-services/operacoes/main.md).

# Create Captive Account

| Campo              | Valor                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------- |
| **Service Domain** | Corporate Trust Services                                                               |
| **BIAN Version**   | 14                                                                                     |
| **Operation**      | Create Captive Account                                                                 |
| **Method**         | POST                                                                                   |
| **API Name**       | Corporate Trust Services API                                                           |
| **Endpoint**       | `POST /corporate-trust/{corporateTrustServicesFacilityId}/escrow-arrangement/initiate` |
| **Autenticação**   | Bearer Token (OAuth2 ou JWT)                                                           |

***

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

A API **Create Captive Account** permite a criação de uma conta cativa (escrow/captive account) associada a uma conta corrente existente, permitindo a retenção de valores para um determinado acordo ou finalidade específica.

Esta API está alinhada com o Service Domain **Corporate Trust Services** definido pelo **BIAN**, e permite:

* Criar contas cativas;
* Associar contas correntes;
* Definir valores cativos;
* Definir período de validade;
* Registrar autorização do cliente.

A operação permite, de forma funcional: criar uma conta cativa, associá-la a uma conta corrente, definir o valor, definir o período e registar o consentimento do cliente.

***

## 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         | ID da requisição   |
| `x-channel`     | String | Não         | Canal de origem    |

**Exemplo de Autorização**

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

***

## 3. Path Parameters

| Parâmetro                          | Tipo   | Obrigatório | Descrição                                                                                             |
| ---------------------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------- |
| `corporateTrustServicesFacilityId` | string | Sim         | Identificador da facilidade de Corporate Trust Services (conta cativa) na qual a operação é iniciada. |

***

## 4. Payload de Pedido (Request)

### 4.1 Exemplo

```json
{
  "corporateTrustServicesFacilityReference": {
    "financialFacility": "CaptiveAccount"
  },
  "escrowReference": "ESC-2026-AKZ-00123",
  "escrowType": "Captive",
  "currentAccountNumber": {
    "accountIdentificationType": "BBAN",
    "accountIdentification": {
      "identifierValue": {
        "value": "8067305810001"
      }
    }
  },
  "accountType": "IndividualCurrentAccount",
  "accountStatus": "Enabled",
  "accountCurrency": {
    "currencyCode": "AKZ"
  },
  "customerAgreementReference": {
    "agreementIdentification": {
      "identifierValue": {
        "value": "80673058"
      }
    },
    "agreementType": "CustomerAgreement"
  },
  "financialAccountingTransaction": {
    "financialAccountingTransactionAmountAndCurrency": {
      "amount": {
        "amountValue": {
          "value": 190000.0
        },
        "amountCurrency": {
          "currencyCode": "AKZ"
        }
      }
    }
  },
  "preconditions": {
    "conditionValidityPeriod": {
      "fromDateTime": {
        "dateTimeContent": "2026-01-01"
      },
      "toDateTime": {
        "dateTimeContent": "2026-01-01"
      },
      "dateTimeType": "MaturityDate"
    }
  },
  "partyAuthorization": {
    "authorizationParty": {
      "partyIdentification": {
        "identifierValue": {
          "value": "80673058"
        }
      },
      "partyName": "ANA KAKUTALA"
    },
    "authorizationType": "AccountOwnerConsent",
    "authorizationStatus": "Granted",
    "authorizationDateTime": {
      "dateTimeContent": "2026-01-01"
    },
    "authorizationChannel": "Digital"
  }
}
```

### 4.2 Descrição dos Campos

| Campo                            | Tipo   | Obrigatório | Descrição        |
| -------------------------------- | ------ | ----------- | ---------------- |
| `EscrowReference`                | String | Sim         | Referência única |
| `EscrowType`                     | String | Sim         | Tipo             |
| `CurrentAccountNumber`           | Object | Sim         | Conta base       |
| `AccountCurrency`                | Object | Sim         | Moeda            |
| `FinancialAccountingTransaction` | Object | Sim         | Valor            |
| `Preconditions`                  | Object | Não         | Período          |
| `PartyAuthorization`             | Object | Sim         | Autorização      |

### 4.3 Tabela de Objetos e Cardinalidade

| Objeto         | Campo                            | Tipo   | Cardinalidade | Descrição   |
| -------------- | -------------------------------- | ------ | ------------- | ----------- |
| CaptiveAccount | `EscrowReference`                | String | 1..1          | Referência  |
| CaptiveAccount | `EscrowType`                     | String | 1..1          | Tipo        |
| CaptiveAccount | `CurrentAccountNumber`           | Object | 1..1          | Conta       |
| CaptiveAccount | `AccountCurrency`                | Object | 1..1          | Moeda       |
| CaptiveAccount | `FinancialAccountingTransaction` | Object | 1..1          | Valor       |
| CaptiveAccount | `Preconditions`                  | Object | 0..1          | Datas       |
| CaptiveAccount | `PartyAuthorization`             | Object | 1..1          | Autorização |

### 4.4 Estrutura de Objetos

**`CorporateTrustServicesFacilityReference`**

| Campo               | Tipo   | Cardinalidade | Descrição |
| ------------------- | ------ | ------------- | --------- |
| `FinancialFacility` | String | 1..1          | Tipo      |

**`CurrentAccountNumber`**

| Campo                       | Tipo   | Cardinalidade | Descrição |
| --------------------------- | ------ | ------------- | --------- |
| `AccountIdentificationType` | String | 1..1          | Tipo      |
| `IdentifierValue`           | String | 1..1          | Conta     |

**`FinancialAccountingTransaction`**

| Campo          | Tipo    | Cardinalidade | Descrição |
| -------------- | ------- | ------------- | --------- |
| `AmountValue`  | Decimal | 1..1          | Valor     |
| `CurrencyCode` | String  | 1..1          | Moeda     |

**`Preconditions`**

| Campo          | Tipo | Cardinalidade | Descrição |
| -------------- | ---- | ------------- | --------- |
| `FromDateTime` | Date | 1..1          | Início    |
| `ToDateTime`   | Date | 1..1          | Fim       |

**`PartyAuthorization`**

| Campo                   | Tipo   | Cardinalidade | Descrição |
| ----------------------- | ------ | ------------- | --------- |
| `PartyIdentification`   | String | 1..1          | Cliente   |
| `PartyName`             | String | 1..1          | Nome      |
| `AuthorizationType`     | String | 1..1          | Tipo      |
| `AuthorizationStatus`   | String | 1..1          | Estado    |
| `AuthorizationDateTime` | Date   | 1..1          | Data      |
| `AuthorizationChannel`  | String | 1..1          | Canal     |

***

## 5. Payload de Resposta (Response — 201 Created)

```json
{
  "escrowReference": "ESC-2026-AKZ-00123",
  "status": "Created",
  "creationDate": "2026-01-01"
}
```

***

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

**Criação de Conta Cativa**

Fluxo:

1. Sistema envia request;
2. API valida token;
3. API valida conta;
4. API valida cliente;
5. API cria cativo;
6. API retorna sucesso.

**Cativo para Garantia** — exemplos: empréstimo, contrato, garantia.

**Cativo Temporário** — exemplos: bloqueio temporário, garantia contratual.

***

## 7. Fluxo Sequencial

1. Cliente envia pedido;
2. API valida token;
3. API valida payload;
4. API valida conta;
5. API verifica saldo;
6. API cria cativo;
7. API regista autorização;
8. API retorna sucesso.

***

## 8. Códigos HTTP de Resposta

| Código | Descrição            |
| ------ | -------------------- |
| 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

**Cenário: Invalid value**

```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"
      }
    ]
  }
}
```

**Cenário: 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"
  }
}
```

### 9.1 Estrutura do Envelope de Erro

| Campo                         | Tipo    | Descrição                                                        |
| ----------------------------- | ------- | ---------------------------------------------------------------- |
| `error.status`                | integer | Código HTTP do erro.                                             |
| `error.reason`                | string  | Código textual de alto nível que identifica a categoria do erro. |
| `error.message`               | string  | Mensagem legível que descreve o problema ocorrido.               |
| `error.path`                  | string  | Método HTTP e caminho do endpoint que originou o erro.           |
| `error.errordetail[]`         | array   | Lista de erros detalhados.                                       |
| `error.errordetail[].code`    | string  | Código do erro.                                                  |
| `error.errordetail[].reason`  | string  | Identificador textual da causa específica do erro.               |
| `error.errordetail[].message` | string  | Mensagem detalhada do erro.                                      |

***

## 10. Regras de Negócio

* Conta deve existir;
* Conta deve estar ativa;
* Cliente deve existir;
* Deve existir autorização;
* Valor deve ser positivo;
* Data válida;
* Moeda válida.

### 10.1 Tipos de Escrow

| Tipo         | Descrição           |
| ------------ | ------------------- |
| `Captive`    | Conta cativa        |
| `Escrow`     | Garantia            |
| `Collateral` | Garantia financeira |

***

## 11. Requisitos Não-Funcionais

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

***

## 12. Mapeamento BIAN

| BIAN                             | API                              |
| -------------------------------- | -------------------------------- |
| `CorporateTrustServicesFacility` | `CaptiveAccount`                 |
| `EscrowAccount`                  | `EscrowReference`                |
| `AccountReference`               | `CurrentAccountNumber`           |
| `Agreement`                      | `CustomerAgreementReference`     |
| `Transaction`                    | `FinancialAccountingTransaction` |
| `Authorization`                  | `PartyAuthorization`             |