Depósitos
🛡️ Fluxo de Retenção de Depósitos (/v1/accounts/:accountId/deposit-retention)
1. Criação da Regra de Retenção (POST / PATCH)
Para iniciar a retenção, é necessário configurar a regra definindo os seguintes parâmetros:
| Parâmetro | Tipo | Descrição e Regras de Negócio |
|---|---|---|
| name / description | string | Identificação e descrição da regra. |
| startDate / endDate | date | Período de Retenção. A retenção ocorrerá entre estas datas. |
| amountPercentage | number | Porcentagem a ser retida de cada depósito que cair na conta. Ex: 50 para reter 50%. |
| maxAmount | number | Teto de Retenção. A retenção para (é interrompida) quando o valor total acumulado atinge este valor. |
| origins | array of string | Opcional. Se preenchido com CPFs/CNPJs, a retenção só ocorre sobre depósitos (Pix/TED) vindos dessas origens. Se vazio, retém de todos. |
| shouldRetainSlc | boolean | Retenção de SLC (Cartões). Se true, a retenção considera recebíveis de maquininha de cartão (eventos SLC), além de Pix e TED. Se false, ignora SLC. |
| accountDestination | UUID | ID da Conta de Liquidação. É a conta para onde o valor retido será transferido ao final da regra. É obrigatório e deve ser o ID de um destinatário criado via /v1/accounts/:accountId/destinations. |
2. Funcionamento (Processo Automático)
- Monitoramento: A API monitora todos os depósitos que caem na accountId especificada (Conta Livre).
- Verificação: Se a data da transação estiver entre startDate e endDate:
- Verifica se a origem está na lista origins (se aplicável).
- Verifica o tipo de entrada (Pix, TED ou SLC, se shouldRetainSlc for true).
- Retenção: A porcentagem definida em amountPercentage é retida do valor do depósito e bloqueada. O saldo retido é visível no endpoint de saldo (/v1/accounts/:accountId/balance) como blockedAmount.
- Limite: O processo de retenção cessa imediatamente se o total retido atingir o maxAmount.
3. Liquidação (Finalização da Retenção)
A liquidação (liberação dos fundos retidos) é o ato de transferir o valor acumulado para a Conta Livre de destino. Ela é disparada automaticamente quando:
É atingida a data final (endDate) configurada. É atingido o limite máximo de valor (maxAmount).
No momento da liquidação, o valor retido é enviado para a conta referenciada pelo accountDestination.
4. Gestão do Recurso
A API permite gerenciar as regras de retenção ativas:
Listar: GET /v1/accounts/:accountId/deposit-retention para ver todas as regras de retenção da conta. O retorno inclui o balanceRetention e o blockedAmount. Atualizar: PATCH /v1/accounts/:accountId/deposit-retention/:depositRetentionId para alterar configurações da retenção (ex: prorrogar endDate). Deletar: DELETE /v1/accounts/:accountId/deposit-retention/:depositRetentionId para remover uma regra de retenção.
A Conta de Destino (accountDestination) deve ser um registro de beneficiário criado, pois as contas Escrow trabalham com destinatários fixos e registrados em contrato.
Updated about 20 hours ago