> 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-documentary-collection-payment/main.md). # Initiate Documentary Collection Payment | Campo | Valor | | ------------------ | ----------------------------------------------------------- | | **Service Domain** | Trade Settlement | | **BIAN Version** | 14 | | **Operation** | Initiate Documentary Collection Payment | | **Method** | POST | | **API Name** | Trade Settlement – Documentary Remittance Payment | | **Versão** | v1.0.0 | | **Endpoint** | `POST /v1/trade-settlement/documentary-collections/payment` | | **Autenticação** | Bearer Token (OAuth 2.0 / OIDC) | *** ## 1. Descrição da Operação A API **Trade Settlement** permite iniciar o pagamento de uma **remessa documentária (Documentary Collection)** no contexto de operações de comércio internacional. Um **Pagamento de Remessa Documentária** (também conhecido como *Documentary Collection*) é um método de pagamento usado principalmente no comércio internacional, onde o banco atua como intermediário para garantir que documentos e pagamentos sejam trocados de forma segura entre comprador e vendedor. ### 1.1 Em termos simples É quando o vendedor envia mercadorias, mas os documentos necessários para levantar a mercadoria (como fatura, conhecimento de embarque, etc.) só são entregues ao comprador através do banco, mediante certas condições de pagamento. *** ## 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 único | | `x-idempotency-key` | String | Recomendado | Evitar duplicação | A API utiliza Bearer Token (OAuth2 / JWT). **Exemplo** ```json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` *** ## 3. Payload de Pedido (Request) ### 3.1 Exemplo ```json { "tradeSettlementProcedure": { "tradeSettlementProcedureID": 2022002717, "tradeSettlementProcedureTransactionType": { "transactionTypeName": { "name": "Operação de pagamento de remessas documentárias" }, "transactionType": "FinancialTransaction", "transactionDescription": "Pagamento de remessa documentaria de compras", "tradeSettlementProcedureTransaction": { "partyReference": "Banco Keve", "expenseNote": { "noteContent": "Pagamento CDOC 25404.83 USD-2022002717" }, "transactionDueDate": { "dateTimeContent": "2026-03-03T14:00:00" }, "transactionCurrency": "AKZ", "currencyForExpenses": "AKZ", "currencyForPayment": "AKZ", "currencyPaymentTransaction": "EUR", "accountNumberExpenses": "65344310001", "accountNumberPayment": "65344310001", "accountNumber": "65344310001", "PaymentFrequency": { "FrequencyCode": 1 }, "creditValue": 25404.83 } }, "bankBranchLocationReference": [ { "branchIdentificationMoviment": { "identifierValue": { "value": "519" } } }, { "branchIdentificationExpenses": { "identifierValue": { "value": "519" } } }, { "branchIdentificationPayment": { "identifierValue": { "value": "519" } } } ], "linkedAccounts": [ { "accountIdentification": { "accountIdentificationType": "CCB Payment", "accountIdentification": { "identifierValue": { "value": "8067305810001" } } } }, { "accountIdentification": { "accountIdentificationType": "CCB Expense", "accountIdentification": { "identifierValue": { "value": "8067305810001" } } } } ] } } ``` ### 3.2 Descrição dos Campos | Campo | Tipo | Obrigatório | Descrição | | ---------------------------- | -------- | ----------- | ------------------------- | | `tradeSettlementProcedureID` | Long | Sim | Identificador da operação | | `transactionType` | String | Sim | Tipo de transação | | `transactionDescription` | String | Sim | Descrição | | `partyReference` | String | Sim | Entidade envolvida | | `transactionDueDate` | DateTime | Sim | Data de liquidação | | `transactionCurrency` | String | Sim | Moeda base | | `currencyPaymentTransaction` | String | Sim | Moeda da operação | | `accountNumber` | String | Sim | Conta principal | | `paymentAccountNumber` | String | Sim | Conta de pagamento | | `accountNumberExpenses` | String | Não | Conta de despesas | | `creditValue` | Decimal | Sim | Valor da transação | ### 3.3 Tabela de Objetos e Cardinalidade | Objeto | Campo | Tipo | Cardinalidade | Descrição | | ------------------------ | ----------------------------------- | ------- | ------------- | --------------- | | TradeSettlementProcedure | tradeSettlementProcedureID | Long | 1..1 | ID | | TradeSettlementProcedure | TransactionType | Object | 1..1 | Tipo | | TransactionType | tradeSettlementProcedureTransaction | Object | 1..1 | Transação | | Transaction | accountNumber | String | 1..1 | Conta | | Transaction | paymentAccountNumber | String | 1..1 | Conta pagamento | | Transaction | creditValue | Decimal | 1..1 | Valor | | Transaction | PaymentFrequency | Object | 0..1 | Frequência | *** ## 4. Payload de Resposta (Response — Sucesso) ```json { "tradeSettlementProcedureID": 2022002717, "status": "Pending", "message": "Documentary collection payment initiated successfully" } ``` *** ## 5. Cenários de Utilização **Pagamento de Remessa Documentária** * Cliente empresarial realiza pagamento; * Banco liquida operação. **Liquidação Internacional** * Conversão de moeda; * Liquidação em EUR/USD. **Pagamento com Despesas** * Débito de encargos adicionais. *** ## 6. Fluxo Sequencial 1. Cliente envia pedido; 2. API valida token; 3. API valida payload; 4. API valida contas; 5. API verifica saldo; 6. API aplica FX (se necessário); 7. API registra transação; 8. API envia para liquidação; 9. API retorna resposta. *** ## 7. 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 | Duplicado | | 500 | Erro interno | *** ## 8. Envelope Padrão de Erro ### 8.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" } ] } } ``` ### 8.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" } } ``` *** ## 9. Regras de Negócio * Conta deve estar ativa; * Saldo suficiente; * Moedas válidas (ISO 4217); * Transação deve ser única; * Data não pode ser passada. *** ## 10. Requisitos Não-Funcionais * HTTPS obrigatório; * Bearer Token obrigatório; * Idempotência obrigatória; * Logging e auditoria. *** ## 11. Mapeamento BIAN | BIAN | API | | -------------------------- | ----------------------------------- | | `TradeSettlementProcedure` | tradeSettlementProcedure | | `FinancialTransaction` | tradeSettlementProcedureTransaction | | `AccountReference` | accountNumber | | `PaymentInstruction` | PaymentFrequency | --- # 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-documentary-collection-payment/main.md?ask=&goal= ``` `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.