Quais dados são registrados por transferência
| Campo | O que significa |
|---|---|
transferId | Sua referência interna para esta transferência |
confirmationNumber | Referência legível pelo usuário (ex: 20260205001) — exiba isso aos clientes |
controlNumber | Referência JD SPB — use para reconciliação bancária |
type | TED OUT, TED IN ou P2P |
status | Estado atual da transferência |
amount | Valor da transferência antes da tarifa |
feeAmount | Tarifa cobrada |
totalAmount | Total debitado (valor + tarifa) |
senderAccountId | Conta de envio no seu sistema. Sempre presente; para TED IN — quando o remetente é um banco externo sem conta local — é um identificador sintético derivado de forma determinística a partir do documento do remetente |
recipientAccountId | Conta destinatária no Midaz, quando o destinatário é representado internamente |
recipientDetails | Banco, agência, número de conta e nome do titular do destinatário |
originalTransferId | A transferência TED OUT original que uma devolução (retorno) TED IN compensa |
devolutionCode | Código BACEN do motivo da devolução, quando aplicável |
createdAt | Quando a transferência foi iniciada |
completedAt | Quando a liquidação foi confirmada |
Ciclo de vida do status da transferência
TED OUT
- Cliente confirmou (
CREATED) — transferência confirmada pelo cliente, aguardando envio - Enviada à rede bancária (
PENDING) — mensagem enviada à JD Consultores, aguardando reconhecimento - Processamento bancário (
PROCESSING) — JD aceitou a transferência e está roteando - Liquidada (
COMPLETED) — transferência liquidada com sucesso no banco de destino - Rejeitada (
REJECTED) — JD retornou um erro de negócio (ex: dados de conta inválidos) - Falhou (
FAILED) — falha técnica (timeout ou indisponibilidade do serviço) - Cancelada (
CANCELLED) — cliente cancelou antes de a transferência ser enviada
TED IN
- Transferência detectada (
RECEIVED) — mensagem recebida persistida, aguardando processamento interno - Destinatário validado (
PROCESSING) — sistema está creditando a conta destinatária - Valor creditado (
COMPLETED) — conta destinatária creditada com sucesso
O TED IN suporta uma transição de
COMPLETED para FAILED para tratar chargebacks — casos em que uma transferência foi inicialmente liquidada mas posteriormente revertida pelo banco remetente.P2P
- Confirmada (
CREATED) — transferência iniciada entre contas internas - Processando (
PROCESSING) — transação Midaz em andamento - Liquidada (
COMPLETED) — ambas as contas atualizadas com sucesso - Falhou (
FAILED) — erro de processamento - Cancelada (
CANCELLED) — cancelada antes do início do processamento
Revisão da tarifa antes da confirmação (somente TED OUT)
Para TED OUT, os clientes passam por um fluxo de duas etapas:
- Aguardando confirmação — a tarifa foi calculada e apresentada; o cliente ainda não confirmou
- Processada — o cliente confirmou e a transferência foi criada
- Expirada — 24 horas se passaram sem confirmação
Histórico de status
Cada transição de status é registrada com um timestamp, o estado anterior, o novo estado e um motivo (para erros e cancelamentos). Isso fornece uma trilha de auditoria completa para cada transferência — quem alterou o quê e quando. O campo
changedBy registra se a transição foi acionada pelo sistema, pelo cliente ou por um administrador.
Campos de reconciliação
Use estes campos para conciliar registros de transferência com seus extratos bancários:
| Campo | Uso para |
|---|---|
controlNumber | Conciliar com registros do JD SPB |
confirmationNumber | Referência para o cliente |
transferId | Consultas internas no sistema |
originalTransferId | Vincular uma devolução (retorno) TED IN ao TED OUT original que ela compensa |
devolutionCode | Classificar o motivo BACEN de uma devolução (retorno) |
createdAt | Filtrar por data de iniciação |
completedAt | Filtrar por data de liquidação |
Retenção de dados
Consultando seus dados
Use Listar Transferências para consultar transferências com os seguintes filtros:
- Por intervalo de datas — filtre por
createdAtoucompletedAt - Por tipo — TED OUT, TED IN ou P2P
- Por status — ex: apenas transferências
COMPLETEDpara reconciliação, ouFAILEDpara investigação
Para desenvolvedores
Armazenamento
Os dados de transferência são armazenados em PostgreSQL. O camporecipientDetails usa JSONB para suportar as diferentes estruturas de dados exigidas pelos destinatários de TED OUT, TED IN e P2P, enquanto recipientAccountId referencia uma conta Midaz quando o destinatário é interno.
Para suportar os padrões de consulta comuns, o plugin mantém os seguintes índices:
(tenant_id, created_at)para listagens paginadas.(tenant_id, status, created_at)para filtros baseados em status.(control_number)para consultas na JD Consultores.
transfer_status_history é otimizada para fluxos de auditoria e investigação por meio dos seguintes índices:
(transfer_id, changed_at DESC)para o histórico em nível de transferência.(tenant_id, changed_at DESC)para consultas de auditoria de todo o tenant dentro de um intervalo de tempo.
Deduplicação de TED IN recebido
Antes de uma transferência TED IN ser processada, o plugin armazena a mensagem bruta da JD na tabelaJDIncomingMessage. Isso garante que as transferências recebidas ainda possam ser recuperadas se o serviço falhar durante o processamento.
Para evitar o processamento duplicado, a tabela aplica uma restrição única em sequenceNumber (o NumCabSeq da JD). Se a JD reentregar a mesma mensagem, o plugin a identifica automaticamente como duplicada e a ignora.
Relacionamentos entre entidades
O modelo de domínio de TED segue estes relacionamentos:- Cada
Transferpertence a uma única organização e pode ter múltiplos registros deTransferStatusHistory. - Transferências TED OUT podem se originar de uma
PaymentInitiationao usar o fluxo de transferência de duas etapas. - Cada
JDIncomingMessagepode criar no máximo umTransferdo tipoTED_IN.
