> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Data and reporting
> Reference the data fields and status lifecycles available for TED transfers — reconciliation, audit trails, and compliance reporting.
Every transfer generates a complete audit trail. This page describes the data available for reporting, reconciliation, and compliance.
## What data is recorded per transfer
***
| Field | What it means |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transferId` | Your internal reference for this transfer |
| `confirmationNumber` | Human-readable reference (e.g. 20260205001) — show this to customers |
| `controlNumber` | JD SPB reference — use for bank reconciliation |
| `type` | TED OUT, TED IN, or P2P |
| `status` | Current state of the transfer |
| `amount` | Transfer amount before fee |
| `feeAmount` | Fee charged |
| `totalAmount` | Total debited (amount + fee) |
| `senderAccountId` | Sending account in your system. Always present; for TED IN — where the sender is an external bank with no local account — it is a synthetic identifier deterministically derived from the sender's document |
| `recipientAccountId` | Recipient account in Midaz, when the recipient is represented internally |
| `recipientDetails` | Recipient bank, branch, account number, and holder name |
| `originalTransferId` | The original TED OUT transfer that a devolution (return) TED IN compensates |
| `devolutionCode` | BACEN devolution reason code, when applicable |
| `createdAt` | When the transfer was initiated |
| `completedAt` | When settlement was confirmed |
## Transfer status lifecycle
***
### TED OUT
* **Customer confirmed** (`CREATED`) — the customer confirmed the transfer, now queued for submission
* **Submitted to bank network** (`PENDING`) — message sent to JD Consultores, awaiting acknowledgment
* **Bank processing** (`PROCESSING`) — JD accepted the transfer and routes it
* **Settled** (`COMPLETED`) — transfer successfully settled at the destination bank
* **Rejected** (`REJECTED`) — JD returned a business error (e.g., invalid account data)
* **Failed** (`FAILED`) — technical failure (timeout or service unavailability)
* **Cancelled** (`CANCELLED`) — customer cancelled before the transfer was submitted
### TED IN
* **Transfer detected** (`RECEIVED`) — incoming message persisted, pending internal processing
* **Recipient validated** (`PROCESSING`) — the system credits the recipient account
* **Amount credited** (`COMPLETED`) — recipient account successfully credited
The sending bank can reverse a settled inbound transfer. To handle these chargebacks, TED IN supports a `COMPLETED` → `FAILED` transition.
### P2P
* **Confirmed** (`CREATED`) — transfer initiated between internal accounts
* **Processing** (`PROCESSING`) — Midaz transaction in progress
* **Settled** (`COMPLETED`) — both accounts updated successfully
* **Failed** (`FAILED`) — processing error
* **Cancelled** (`CANCELLED`) — cancelled before processing began
## Fee review before confirmation (TED OUT only)
***
For TED OUT, customers go through a two-step flow:
* **Pending confirmation** — the plugin calculated and presented the fee. The customer has not confirmed it yet
* **Processed** — the customer confirmed and the plugin created the transfer
* **Expired** — 24 hours elapsed without confirmation
Customers can review the full cost (amount + fee) before they confirm the transfer.
## Status history
***
The plugin records every status transition with a timestamp, the previous state, the new state, and a reason for errors and cancellations. This gives you a full audit trail for every transfer — who changed what and when.
The `changedBy` field records the actor that made the transition — for example, a system process or a reconciliation worker. It can be empty.
## Reconciliation fields
***
Use these fields to match transfer records against your bank statements:
| Field | Use for |
| -------------------- | ------------------------------------------------------------------------ |
| `controlNumber` | Matching against JD SPB records |
| `confirmationNumber` | Customer-facing reference |
| `transferId` | Internal system lookups |
| `originalTransferId` | Link a devolution (return) TED IN to the original TED OUT it compensates |
| `devolutionCode` | Classify the BACEN reason for a devolution (return) |
| `createdAt` | Filtering by initiation date |
| `completedAt` | Filtering by settlement date |
## Data retention
***
Do not delete transfer records. The plugin never deletes or expires them, so you own their retention. Keep transfer and audit records for at least 5 years, per BACEN record-keeping requirements.
## Querying your data
***
Use [List Transfers](/en/reference/midaz/plugins/ted/list-transfers) to query transfers with the following filters:
* **By date range** — filter by `createdAt` or `completedAt`
* **By type** — TED OUT, TED IN, or P2P
* **By status** — e.g., only `COMPLETED` transfers for reconciliation, or `FAILED` for investigation
## For developers
***
### Storage
The plugin stores transfer data in PostgreSQL. The `recipientDetails` field uses JSONB. This field holds the different data structures for TED OUT, TED IN, and P2P recipients. The `recipientAccountId` field references a Midaz account when the recipient is internal.
Each tenant has its own database, and the organization is the main filter within a tenant. The plugin maintains the following indexes for common query patterns:
* `(midaz_organization_id, created_at)` for paginated listings.
* `(midaz_organization_id, status, created_at)` for status-based filtering.
* `(control_number, date)` (unique) for JD reconciliation lookups.
The `transfer_status_history` audit table uses one index for audit and investigation workflows:
* `(transfer_id, changed_at DESC)` for transfer-level history.
### Incoming TED deduplication
Before it processes a TED IN transfer, the plugin stores the raw JD message in the `JDIncomingMessage` table. This lets the plugin recover incoming transfers if the service fails during processing.
To prevent duplicate processing, the table enforces a unique constraint on `sequenceNumber` (JD's `NumCabSeq`). If JD re-delivers the same message, the plugin automatically identifies it as a duplicate and ignores it.
### What the plugin sends to Midaz
The plugin posts every settled movement to Midaz as a ledger transaction, but Midaz records the accounting entry — not the transfer's banking details. Counterparty identity (bank, branch, account, holder name and document) and BACEN references (`controlNumber`, `clearingControlNumber`) live only in the plugin's `Transfer` record. For a TED IN, the credit enters the ledger from the `@external/BRL` account; the sender's identity is not encoded into the Midaz transaction.
What the Midaz transaction carries is correlation metadata:
| Metadata key | Value |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| `transferId` | The plugin's transfer identifier — the pivot back to the full record |
| `transferType` | `TED_OUT`, `TED_IN`, or `P2P` |
| `initiationId` | The `PaymentInitiation` identifier (TED OUT and P2P only — TED IN has no initiate step) |
| `jdMessageId`, `jdSequence`, `messageCode` | The JD message that produced a TED IN credit |
A devolution (return) credit additionally carries `refundKind`, `originalTransferId`, `devolutionCode`, and the original control numbers.
Correlation works in both directions:
* The transfer record stores `midazTransactionId`, so [Get Transfer](/en/reference/midaz/plugins/ted/retrieve-transfer) returns the full banking detail for any ledger entry.
* The Midaz transaction stores `transferId` in its metadata, so you can list Midaz transactions filtered by `metadata.transferId` to find the ledger entry for a transfer.
Custom metadata you pass when initiating a TED OUT or P2P transfer is merged into the Midaz transaction as-is. The keys `transferId`, `transferType`, and `initiationId` are reserved — the plugin's values always win.
### Entity relationships
The TED domain model follows these relationships:
* Each `Transfer` belongs to a single organization and can have multiple `TransferStatusHistory` records.
* TED OUT transfers can originate from a `PaymentInitiation` in the two-step transfer flow.
* Each `JDIncomingMessage` can create at most one `Transfer` of type `TED_IN`.
