Datos y reportes

Consulta los campos y ciclos de estado disponibles para Bank Transfer — reconciliación, trazas de auditoría y reportes de cumplimiento.

Cada transferencia genera un registro de auditoría completo. Esta página describe los datos disponibles para reportes, reconciliación y cumplimiento.

​

Qué datos se registran por transferencia

---

Campo	Significado
transferId	Su referencia interna para esta transferencia
confirmationNumber	Referencia legible para el usuario (por ejemplo, 20260205001) — muéstresela a los clientes
controlNumber	Referencia JD SPB — úsela para la reconciliación bancaria
type	TED OUT, TED IN o P2P
status	Estado actual de la transferencia
amount	Monto de la transferencia antes de la tarifa
feeAmount	Tarifa cobrada
totalAmount	Total debitado (monto + tarifa)
senderAccountId	Cuenta de envío en su sistema. Siempre presente; para TED IN — donde el remitente es un banco externo sin cuenta local — es un identificador sintético derivado de forma determinista a partir del documento del remitente
recipientAccountId	Cuenta destinataria en Midaz, cuando el destinatario está representado internamente
recipientDetails	Banco, sucursal, número de cuenta y nombre del titular del destinatario
originalTransferId	La transferencia TED OUT original que compensa una devolución (TED IN de retorno)
devolutionCode	Código BACEN del motivo de devolución, cuando aplica
createdAt	Cuándo se inició la transferencia
completedAt	Cuándo se confirmó la liquidación

​

Ciclo de vida del estado de la transferencia

---

​

TED OUT

• Cliente confirmado (CREATED) — el cliente confirmó la transferencia, ahora en cola para envío
• Enviada a la red bancaria (PENDING) — mensaje enviado a JD Consultores, esperando reconocimiento
• Procesamiento bancario (PROCESSING) — JD aceptó la transferencia y la enruta
• Liquidada (COMPLETED) — transferencia liquidada con éxito en el banco de destino
• Rechazada (REJECTED) — JD devolvió un error de negocio (por ejemplo, datos de cuenta inválidos)
• Fallida (FAILED) — falla técnica (timeout o indisponibilidad del servicio)
• Cancelada (CANCELLED) — el cliente canceló antes de que se enviara la transferencia

​

TED IN

• Transferencia detectada (RECEIVED) — mensaje entrante persistido, pendiente de procesamiento interno
• Destinatario validado (PROCESSING) — el sistema acredita la cuenta del destinatario
• Monto acreditado (COMPLETED) — cuenta del destinatario acreditada con éxito

El banco remitente puede revertir una transferencia entrante ya liquidada. Para gestionar estos chargebacks, TED IN admite una transición COMPLETED → FAILED.

​

P2P

• Confirmada (CREATED) — transferencia iniciada entre cuentas internas
• Procesando (PROCESSING) — transacción de Midaz en progreso
• Liquidada (COMPLETED) — ambas cuentas actualizadas con éxito
• Fallida (FAILED) — error de procesamiento
• Cancelada (CANCELLED) — cancelada antes de que comenzara el procesamiento

​

Revisión de tarifa antes de la confirmación (solo TED OUT)

---

Para TED OUT, los clientes pasan por un flujo de dos pasos:

• Pendiente de confirmación — el plugin calculó y presentó la tarifa. El cliente aún no la ha confirmado
• Procesada — el cliente confirmó y el plugin creó la transferencia
• Expirada — transcurrieron 24 horas sin confirmación

Los clientes pueden revisar el costo total (monto + tarifa) antes de confirmar la transferencia.

​

Historial de estados

---

El plugin registra cada transición de estado con una marca de tiempo, el estado anterior, el nuevo estado y un motivo para errores y cancelaciones. Esto te da un registro de auditoría completo de cada transferencia — quién cambió qué y cuándo.

El campo changedBy registra el actor que hizo la transición — por ejemplo, un proceso del sistema o un worker de reconciliación. Puede estar vacío.

​

Campos de reconciliación

---

Usa estos campos para relacionar los registros de transferencia con tus extractos bancarios:

Campo	Uso para
controlNumber	Relacionar con los registros de JD SPB
confirmationNumber	Referencia orientada al cliente
transferId	Búsquedas en el sistema interno
originalTransferId	Vincular una devolución (TED IN de retorno) con el TED OUT original que compensa
devolutionCode	Clasificar el motivo BACEN de una devolución (retorno)
createdAt	Filtrar por fecha de iniciación
completedAt	Filtrar por fecha de liquidación

​

Retención de datos

---

No elimines los registros de transferencia. El plugin nunca los elimina ni los caduca, así que tú controlas su retención. Consérvalos, junto con los de auditoría, durante al menos 5 años, conforme a los requisitos de conservación de registros del BACEN.

​

Consulta de tus datos

---

Usa Listar Transferencias para consultar transferencias con los siguientes filtros:

• Por rango de fechas — filtra por createdAt o completedAt
• Por tipo — TED OUT, TED IN o P2P
• Por estado — por ejemplo, solo transferencias COMPLETED para reconciliación, o FAILED para investigación

​

Para desarrolladores

---

​

Almacenamiento

El plugin almacena los datos de transferencia en PostgreSQL. El campo recipientDetails usa JSONB. Este campo contiene las diferentes estructuras de datos para los destinatarios de TED OUT, TED IN y P2P. El campo recipientAccountId referencia una cuenta de Midaz cuando el destinatario es interno.

Cada tenant tiene su propia base de datos, y la organización es el filtro principal dentro de un tenant. El plugin mantiene los siguientes índices para los patrones de consulta comunes:

• (midaz_organization_id, created_at) para listados paginados.
• (midaz_organization_id, status, created_at) para filtros basados en estado.
• (control_number, date) (único) para búsquedas de reconciliación de JD.

La tabla de auditoría transfer_status_history usa un índice para flujos de auditoría e investigación:

• (transfer_id, changed_at DESC) para el historial a nivel de transferencia.

​

Deduplicación de TED IN entrante

Antes de procesar una transferencia TED IN, el plugin almacena el mensaje JD sin procesar en la tabla JDIncomingMessage. Esto permite que el plugin recupere las transferencias entrantes si el servicio falla durante el procesamiento.

Para prevenir el procesamiento duplicado, la tabla aplica una restricción única en sequenceNumber (el NumCabSeq de JD). Si JD reentrega el mismo mensaje, el plugin lo identifica automáticamente como duplicado y lo ignora.

​

Qué envía el plugin a Midaz

El plugin registra cada movimiento liquidado en Midaz como una transacción de ledger, pero Midaz guarda el asiento contable — no los detalles bancarios de la transferencia. La identidad de la contraparte (banco, sucursal, cuenta, nombre y documento del titular) y las referencias BACEN (controlNumber, clearingControlNumber) viven solo en el registro Transfer del plugin. En una TED IN, el crédito entra al ledger desde la cuenta @external/BRL; la identidad del remitente no se codifica en la transacción de Midaz.

Lo que la transacción de Midaz lleva son metadatos de correlación:

Clave de metadatos	Valor
transferId	El identificador de la transferencia en el plugin — el pivote de vuelta al registro completo
transferType	TED_OUT, TED_IN o P2P
initiationId	El identificador de la PaymentInitiation (solo TED OUT y P2P — TED IN no tiene paso de initiate)
jdMessageId, jdSequence, messageCode	El mensaje de JD que produjo un crédito de TED IN

Un crédito de devolución lleva adicionalmente refundKind, originalTransferId, devolutionCode y los números de control originales.

La correlación funciona en ambos sentidos:

• El registro de la transferencia almacena el midazTransactionId, así que Consultar Transferencia devuelve el detalle bancario completo de cualquier asiento del ledger.
• La transacción de Midaz almacena el transferId en sus metadatos, así que puedes listar transacciones de Midaz filtrando por metadata.transferId para encontrar el asiento de una transferencia.

Los metadatos personalizados que envías al iniciar una transferencia TED OUT o P2P se fusionan en la transacción de Midaz tal cual. Las claves transferId, transferType e initiationId son reservadas — los valores del plugin siempre prevalecen.

​

Relaciones entre entidades

El modelo de dominio de TED sigue estas relaciones:

• Cada Transfer pertenece a una única organización y puede tener múltiples registros de TransferStatusHistory.
• Las transferencias TED OUT pueden originarse desde una PaymentInitiation en el flujo de transferencia de dos pasos.
• Cada JDIncomingMessage puede crear como máximo un Transfer de tipo TED_IN.