> 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/merchandising-loan/execute-payment/main.md).

# Execute Merchandising Loan Facility for Documentary Remittance Settlement

| Campo              | Valor                                                                     |
| ------------------ | ------------------------------------------------------------------------- |
| **Service Domain** | Merchandising Loan                                                        |
| **BIAN Version**   | 14.0.0                                                                    |
| **Operation**      | Execute Merchandising Loan Facility for Documentary Remittance Settlement |
| **Method**         | POST                                                                      |
| **API Name**       | Merchandising Loan                                                        |
| **Versão**         | v1.0.0                                                                    |

***

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

A operação interna "Pagamento de Remessa Documentária" materializa a libertação de um Pagamento imediato de Utilização de Remessa Documentária (PIREM) destinada a liquidar uma remessa documentária junto do banco correspondente. A operação:

* Envolve datas de vencimento próprias do instrumento de financiamento;
* Separa a conta de pagamento (crédito do montante financiado) da conta de despesas (débito de encargos, comissões e impostos);
* É associada ao tipo PIREM – Pagamento Imediato de Utilização de Remessa Documentária, utilizando a operação CRDE.

| Campo            | Valor                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| **API Name**     | Merchandising Loan API                                                                                |
| **Versão**       | v1.0.0                                                                                                |
| **Endpoint**     | `POST /v1/merchandising-loan/{merchandisingLoanId}/repayment-schedules/{installmentSequence}/execute` |
| **Autenticação** | Bearer Token (OAuth 2.0 / OIDC — realm nexus)                                                         |

***

## 2. Cabeçalhos HTTP

| Header                           | Obrigatório | Notas                                                                 |
| -------------------------------- | ----------- | --------------------------------------------------------------------- |
| `Authorization: Bearer {token}`  | Sim         | OAuth2 / JWT — client\_credentials para M2M                           |
| `Content-Type: application/json` | Sim         |                                                                       |
| `Accept: application/json`       | Sim         |                                                                       |
| `x-request-id`                   | Recomendado | UUID v4 — identificador único do pedido para correlação em logs/Tempo |
| `x-channel`                      | Recomendado | Canal de origem (SOP, MOBILE, BACKOFFICE, …)                          |

***

## 3. Path Parameters

| Parâmetro             | Tipo   | Obrigatório | Descrição                                                                                          |
| --------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- |
| `merchandisingLoanId` | string | Sim         | Identificador único da facilidade de crédito comercial. Corresponde ao número da conta de Crédito. |

***

## 4. Payload de Pedido (Request)

```json
{
  "merchandisingLoanFacilityParameterType": "DocumentaryRemittance",
  "merchandisingLoanType": "CRDE",
  "merchandisingLoanFacilityReference": {
    "loanMaturityDate":    { "dateContent": "2026-03-03" },
    "loanAmount": {
      "amountValue": 800000.00,
      "amountCurrency": { "currencyCode": "USD" }
    }
  },
  "accountReferences": [
    {
      "accountIdentification": {
        "accountIdentificationType": "PaymentAccount",
        "accountDescription": "Conta para pagamento",
        "identifierValue": "125818816001"
      }
    },
    {
      "accountIdentification": {
        "accountIdentificationType": "ExpenseAccount",
        "accountDescription": "Conta para despesas",
        "identifierValue": "125818810007"
      }
    }
  ]
}
```

### 4.1 Objeto Raiz

Contém os campos de topo que identificam o tipo de facilidade e a operação no core bancário.

| Campo                                    | Tipo | Obrigatório | Descrição                                                                                                                    |
| ---------------------------------------- | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `merchandisingLoanFacilityParameterType` | enum | Sim         | Sub-tipo da facilidade. Valor actual: `DocumentaryRemittance`. Reservado para futuros: `LetterOfCredit`, `BankerAcceptance`. |
| `merchandisingLoanType`                  | enum | Sim         | Código da operação no core Banka. `CRDE` = Crédito Documentário Exportação.                                                  |

### 4.2 Objecto: `merchandisingLoanFacilityReference`

Agrupa os parâmetros financeiros e temporais da facilidade: montante, moeda, datas e sequência de prestação.

| Campo                                    | Tipo              | Obrigatório | Descrição                                                                                               |
| ---------------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `loanMaturityDate.dateContent`           | string (ISO 8601) | Sim         | Data limite para pagamento ao banco correspondente (vencimento). Formato: `YYYY-MM-DD`.                 |
| `loanInstallmentSequence`                | integer           | Sim         | Número sequencial da prestação no plano de pagamento. Começa em 1.                                      |
| `loanAmount.amountValue`                 | decimal (>= 0)    | Sim         | Montante a desembolsar. Máximo 2 casas decimais. Deve ser maior que zero e dentro do plafond aprovado.  |
| `loanAmount.amountCurrency.currencyCode` | string (ISO 4217) | Sim         | Código da moeda da operação. Exemplos: USD, EUR, AOA. Deve coincidir com a moeda da conta de pagamento. |

### 4.3 Objecto: `accountReferences[ ]`

Array de contas envolvidas na operação. São obrigatórias exactamente duas contas: uma `PaymentAccount` e uma `ExpenseAccount`, ambas activas e pertencentes ao mesmo cliente.

| Campo                  | Tipo  | Obrigatório | Descrição                                                                 |
| ---------------------- | ----- | ----------- | ------------------------------------------------------------------------- |
| `accountReferences[ ]` | array | Sim         | Lista de objectos de identificação de conta. Mínimo e máximo: 2 entradas. |

#### 4.3.1 Objecto: `accountReferences[].accountIdentification`

| Campo                       | Tipo   | Obrigatório | Descrição                                                                                                                                          |
| --------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountIdentificationType` | enum   | Sim         | Papel da conta na operação. Valores: `PaymentAccount` (recebe o montante financiado) \| `ExpenseAccount` (suporta encargos, comissões e impostos). |
| `accountDescription`        | string | Não         | Texto livre descritivo. Apenas informativo — não influencia o routing da operação.                                                                 |
| `identifierValue`           | string | Sim         | Número de conta no Banka. Deve estar activa e pertencer ao titular da facilidade.                                                                  |

***

## 5. Payload de Resposta (Response — 200 OK)

```json
{
  "merchandisingLoanFacilityStatus": "Executed",
  "executionReference": "EXEC-7f1c3a5e-9d22-4b88",
  "executionDateTime": "2026-05-08T11:42:17.305Z"
}
```

### 5.1 Campos da Resposta

| Campo                             | Tipo                   | Descrição                                                                                                  |
| --------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `merchandisingLoanOperationId`    | string                 | Identificador único da operação gerado pelo sistema core (Banka).                                          |
| `merchandisingLoanFacilityStatus` | enum                   | Estado da facilidade após execução. Valores: `Executed` \| `PartiallyExecuted` \| `Rejected` \| `Pending`. |
| `executionReference`              | string (UUID v4)       | Referência única da execução gerada pelo NEXUS. Usada para correlação e auditoria.                         |
| `executionDateTime`               | string (ISO 8601 + TZ) | Carimbo temporal UTC da execução. Exemplo: `2026-05-08T11:42:17.305Z`.                                     |

***

## 6. Códigos HTTP de Resposta

| Código | Estado                | Descrição                                                                                                       |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| 200    | OK                    | Execução concluída com sucesso.                                                                                 |
| 202    | Accepted              | Pedido aceite; execução assíncrona pendente de confirmação do Banka.                                            |
| 204    | No Content            | Pagamento efectuado com sucesso.                                                                                |
| 400    | Bad Request           | Payload inválido: datas inconsistentes, montante ≤ 0, moeda inválida ou contas em falta.                        |
| 401    | Unauthorized          | Token ausente, expirado ou inválido.                                                                            |
| 403    | Forbidden             | Cliente autenticado mas sem scope para `merchandising-loan:execute`.                                            |
| 404    | Not Found             | `merchandisingLoanId` inexistente ou conta de pagamento/despesas não encontrada.                                |
| 409    | Conflict              | Facilidade já executada anteriormente ou em estado terminal (Cancelled, Closed).                                |
| 422    | Unprocessable Entity  | Regra de negócio violada: saldo insuficiente na conta de despesas, moeda da conta diferente da facilidade, etc. |
| 500    | Internal Server Error | Erro inesperado no NEXUS ou no Backbone.                                                                        |
| 502    | Bad Gateway           | Resposta inválida ou indisponibilidade do core Banka.                                                           |
| 504    | Gateway Timeout       | Timeout na chamada ao AS/400.                                                                                   |

***

## 7. Envelope Padrão de Erro

### 7.1 Exemplo

```json
{
  "status": 422,
  "reason": "BUSINESS_RULE_VIOLATION",
  "message": "Saldo insuficiente na conta de despesas para liquidar comissões.",
  "path": "POST /v1/merchandising-loan/CRDE-2025-000128/execute",
  "errors": [
    {
      "code": "ML-422-001",
      "reason": "INSUFFICIENT_FUNDS_EXPENSE_ACCOUNT",
      "message": "Conta 125818810007: saldo 850.00 USD < despesa 1250.75 USD."
    }
  ]
}
```

***

## 6bis. Payload de Resposta (Response — 200 OK) — Variante

```json
{
  "merchandisingLoanFacilityStatus": "Executed",
  "executionDateTime": "2026-05-08T11:42:17.305Z"
}
```

### 6bis.1 Campos da Resposta de Sucesso (200 OK)

| Campo                             | Tipo                    | Descrição                                                  |
| --------------------------------- | ----------------------- | ---------------------------------------------------------- |
| `merchandisingLoanId`             | string                  | Identificador da facilidade (eco do path param).           |
| `merchandisingLoanFacilityStatus` | enum                    | `Executed` · `PartiallyExecuted` · `Rejected` · `Pending`. |
| `executionDateTime`               | string (ISO 8601 c/ TZ) | Carimbo temporal da execução.                              |

***

## 7bis. Códigos HTTP

| Código                    | Significado                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 200 OK                    | Execução concluída com sucesso.                                                                                |
| 202 Accepted              | Pedido aceite, execução assíncrona pendente de confirmação do Banka.                                           |
| 400 Bad Request           | Payload inválido (datas inconsistentes, montante ≤ 0, moeda inválida, contas em falta).                        |
| 401 Unauthorized          | Token ausente, expirado ou inválido.                                                                           |
| 403 Forbidden             | Cliente autenticado mas sem âmbito (scope) para `merchandising-loan:execute`.                                  |
| 404 Not Found             | `merchandisingLoanId` não existe ou conta de pagamento/despesas inexistente.                                   |
| 409 Conflict              | Facilidade já executada anteriormente, ou em estado terminal (Cancelled, Closed).                              |
| 422 Unprocessable Entity  | Regra de negócio violada (ex.: saldo insuficiente na conta de despesas, moeda da conta ≠ moeda da facilidade). |
| 500 Internal Server Error | Erro inesperado no NEXUS / Backbone.                                                                           |
| 502 Bad Gateway           | Resposta inválida ou indisponibilidade do core Banka.                                                          |
| 504 Gateway Timeout       | Timeout na chamada AS/400.                                                                                     |

***

## 8. Envelope Padrão de Erro

```json
{
  "status": 422,
  "reason": "BUSINESS_RULE_VIOLATION",
  "message": "Saldo insuficiente na conta de despesas para liquidar comissões.",
  "path": "POST /v1/merchandising-loan/CRDE-2025-000128/execute",
  "errordetail": [
    {
      "code": "ML-422-001",
      "reason": "INSUFFICIENT_FUNDS_EXPENSE_ACCOUNT",
      "message": "Conta 125818810007: saldo 850.00 USD < despesa 1250.75 USD."
    }
  ]
}
```

### 8.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. Pode estar ausente em erros genéricos (500).              |
| `error.errordetail[].code`    | string  | Código específico do domínio (ex.: `ML-422-001`).                                    |
| `error.errordetail[].reason`  | string  | Identificador textual da causa específica do erro.                                   |
| `error.errordetail[].message` | string  | Mensagem detalhada sobre a causa específica, com valores concretos quando aplicável. |

### 8.2 Códigos de Erro do Domínio

| Código       | Cenário                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `ML-400-001` | `merchandisingLoanType` não suportado.                                                             |
| `ML-400-003` | `accountReferences` não contém exactamente uma `PaymentAccount` e uma `ExpenseAccount`.            |
| `ML-404-001` | Facilidade `merchandisingLoanId` inexistente no Banka.                                             |
| `ML-409-001` | Facilidade já executada — `executionReference` anterior é devolvido sem repetir o desembolso.      |
| `ML-422-001` | Saldo insuficiente na conta de despesas para cobrir comissões, imposto de selo e encargos SWIFT.   |
| `ML-422-002` | Moeda da conta de pagamento diferente da moeda da facilidade (sem cobertura cambial pré-aprovada). |
| `ML-422-003` | Cliente não autorizado a operar em divisas pelo BNA (Banco Nacional de Angola).                    |
| `ML-502-001` | Banka devolveu return code diferente de zero.                                                      |

***

## 9. Regras de Negócio

| # | Regra                           | Detalhe                                                                                                                                                                             |
| - | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Estado da Facilidade            | A facilidade `merchandisingLoanId` deve existir no Banka e estar em estado `Approved` ou `Pending`. Qualquer outro estado resulta em erro.                                          |
| 2 | Contas Obrigatórias             | Devem ser fornecidas exactamente uma `PaymentAccount` e uma `ExpenseAccount`. Ambas devem estar activas e pertencer ao mesmo cliente titular da facilidade.                         |
| 3 | Consistência de Moeda           | A moeda da conta de pagamento deve coincidir com `loanAmount.amountCurrency.currencyCode`, ou deve existir cobertura cambial pré-aprovada.                                          |
| 4 | Montante Válido                 | `loanAmount.amountValue` deve ser maior que zero e não pode exceder o plafond aprovado da facilidade.                                                                               |
| 5 | Saldo da Conta de Despesas      | A conta de despesas deve ter saldo suficiente para cobrir comissões, imposto de selo e encargos SWIFT calculados no momento da execução.                                            |
| 6 | Protecção contra Dupla Execução | Antes de chamar o Banka, o serviço verifica o estado da facilidade. Se já estiver `Executed`, devolve `409 Conflict` com o `executionReference` original, sem repetir o desembolso. |
| 7 | Autorização Cambial BNA         | O cliente deve possuir autorização cambial válida do Banco Nacional de Angola para operações em divisas.                                                                            |

***

## 10. Requisitos Não-Funcionais

| Requisito           | Detalhe                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| HTTPS / TLS         | Obrigatório TLS 1.2 ou superior em todas as comunicações.                                               |
| Bearer Token        | Obrigatório — scope `merchandising-loan:execute`. Pedidos sem token ou com token inválido retornam 401. |
| Auditoria           | Registo persistente obrigatório de todas as execuções (log estruturado + Loki).                         |
| Logging Estruturado | Todos os logs devem incluir o campo `x-request-id` para correlação de pedidos.                          |


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/merchandising-loan/execute-payment/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 `build a script that syncs our docs to a CMS` 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.