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) — transfer confirmed by the customer, queued for submission - Submitted to bank network (
PENDING) — message sent to JD Consultores, awaiting acknowledgment - Bank processing (
PROCESSING) — JD accepted the transfer and is routing 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) — system is crediting the recipient account - Amount credited (
COMPLETED) — recipient account successfully credited
TED IN supports a
COMPLETED → FAILED transition to handle chargebacks — cases where a transfer was initially settled but later reversed by the sending bank.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 fee has been calculated and presented; the customer hasn’t confirmed yet
- Processed — the customer confirmed and the transfer was created
- Expired — 24 hours elapsed without confirmation
Status history
Every status transition is recorded 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 whether the transition was triggered by the system, the customer, or an admin.
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
Querying your data
Use List Transfers to query transfers with the following filters:
- By date range — filter by
createdAtorcompletedAt - By type — TED OUT, TED IN, or P2P
- By status — e.g., only
COMPLETEDtransfers for reconciliation, orFAILEDfor investigation
For developers
Storage
Transfer data is stored in PostgreSQL. TherecipientDetails field uses JSONB to support the different data structures required by TED OUT, TED IN, and P2P recipients, while recipientAccountId references a Midaz account when the recipient is internal.
To support common query patterns, the plugin maintains the following indexes:
(tenant_id, created_at)for paginated listings.(tenant_id, status, created_at)for status-based filtering.(control_number)for JD Consultores lookups.
transfer_status_history audit table is optimized for audit and investigation workflows through the following indexes:
(transfer_id, changed_at DESC)for transfer-level history.(tenant_id, changed_at DESC)for tenant-wide audit queries within a time range.
Incoming TED deduplication
Before a TED IN transfer is processed, the plugin stores the raw JD message in theJDIncomingMessage table. This ensures that incoming transfers can still be recovered 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.
Entity relationships
The TED domain model follows these relationships:- Each
Transferbelongs to a single organization and can have multipleTransferStatusHistoryrecords. - TED OUT transfers can originate from a
PaymentInitiationwhen using the two-step transfer flow. - Each
JDIncomingMessagecan create at most oneTransferof typeTED_IN.
