> ## 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.
# Receive TED (TED IN)
> Receive TED transfers automatically — the plugin polls SPB, validates recipient Accounts, and credits funds with no manual intervention.
TED IN allows your institution to receive transfers from any Brazilian bank automatically. No action is required from your team — the plugin handles detection, validation, and crediting. When a customer at another bank sends a TED to your institution, the funds appear in the recipient's account within minutes.
## How it works
***
1. A customer at another bank initiates a TED transfer addressed to one of your institution's accounts
2. Every 30 seconds, the plugin polls the JD SPB network for new incoming transfers
3. The recipient account is validated against your CRM using the document number in the transfer message
4. The amount is credited to the recipient's account automatically (minus the cashin fee, if configured)
## Detection and processing timeline
***
What your customer experiences after the origin bank sends the transfer:
| Time | What happens |
| ----- | -------------------------------------------------------------------------- |
| T+0s | Origin bank submits the transfer to the BACEN network |
| T+30s | Plugin detects the transfer; status moves to `RECEIVED` |
| T+32s | Recipient account is looked up and confirmed; status moves to `PROCESSING` |
| T+35s | Amount is credited to the recipient's account; status moves to `COMPLETED` |
| T+36s | Webhook notification is sent to your system |
**Typical SLA:** Under 1 minute from the moment the origin bank sends the transfer.
## Transfer states
***
| State | What it means for the recipient |
| ------------ | ----------------------------------------------------------- |
| `RECEIVED` | Transfer detected on the network; being processed |
| `PROCESSING` | Recipient account confirmed; credit is being applied |
| `COMPLETED` | Funds have arrived in the recipient's account |
| `FAILED` | Recipient could not be identified; funds returned to sender |
## Receiving fee (cashin)
***
Your organization can optionally charge a fee on incoming transfers. When enabled, the fee is deducted from the amount before it is credited — the recipient receives the net amount. The fee amount and configuration are set per organization via the Fees Engine.
Formula: `credited amount = transfer amount − fee`
Example: a R$1,000.00 transfer with a R$2.50 fee results in R\$997.50 credited to the recipient's account. This is the opposite of TED OUT, where the fee is added on top and the sender pays more.
## What happens when a recipient isn't found
***
If the document number in the incoming transfer cannot be matched to an account in your CRM, the transfer is automatically returned to the origin bank. The sending customer receives their money back. No manual intervention is needed and no funds remain unaccounted for.
The transfer record is marked as `FAILED` with the reason "Recipient account could not be identified."
## Querying received transfers
***
Use the [List Transfers](/en/reference/midaz/plugins/ted/list-transfers) endpoint to retrieve all incoming transfers. Filter by `type=TED_IN` to view only received transfers.
**Endpoint:** GET /v1/transfers
**Response (key fields):**
```json theme={null}
{
"data": [
{
"transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
"type": "TED_IN",
"status": "COMPLETED",
"amount": 5000.00,
"feeAmount": 0.00,
"totalAmount": 5000.00,
"recipientHolderName": "Empresa ABC Ltda",
"createdAt": "2026-01-21T10:15:00-03:00"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"totalCount": 150,
"hasNextPage": true
}
}
```
For full query parameter options, see the [List Transfers](/en/reference/midaz/plugins/ted/list-transfers) reference.
## Operational endpoints
***
Two operator endpoints control the TED IN polling loop. They are intended for scripts and runbooks, not for end-user traffic.
| Endpoint | Purpose |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/transfers/ted-in/poll` | Manually trigger the JD poller that normally runs on a 30s cron. Useful after an incident window or to validate JD connectivity. Does not require `X-Organization-Id` since it operates across the polling worker, not a tenant. |
| `POST /v1/transfers/ted-in/replay` | Replay a previously fetched TED IN message that failed downstream credit processing. Requires `X-Organization-Id` and idempotency. |
For request body, response, status codes, and error codes, see the [TED OpenAPI specification](/en/openapi/v3-current/ted.yaml) (operations `triggerTEDInPoller` and `replayTEDInPoller`).
## Three distinct dead-letter paths
***
The plugin uses three separate failure stores. They are not interchangeable and should be monitored independently:
* **JD parse failures** — stored in `jd_incoming_parse_failures`. The message arrived from JD but could not be interpreted (malformed XML, unknown message type). Manual triage required.
* **Undeliverable inbound transfers** — stored in `undeliverable_incoming_transfers`. Parsing succeeded, but the credit could not be applied (e.g., recipient account not found). May result in an automatic devolução to the origin bank.
* **Webhook DLQ** — the retry queue for failed outbound webhook deliveries, exposed via `/v1/transfers/webhooks/dlq`. Unrelated to TED IN ingestion; this is the outbound event channel to integrating clients.
## Webhooks
***
Configure a webhook to get real-time notifications when transfers arrive. The `transfer.incoming.completed` event fires as soon as a transfer is credited. See [Webhooks](/en/midaz/plugins/ted/ted-webhooks) for setup and event payload details.
## Reconciliation
***
For accounting and finance reconciliation, each transfer record includes the following fields:
| Field | Usage |
| --------------- | ------------------------------------------------------------------------------ |
| `controlNumber` | JD SPB control number — unique per transfer, used for interbank reconciliation |
| `transferId` | Lerian internal identifier |
| `createdAt` | Timestamp when the transfer was detected |
| `completedAt` | Timestamp when funds were credited |
Transfer history is retained for **5 years**, as required by BACEN regulations.
## Processing guarantees
***
The plugin is designed so that no transfer is lost and no transfer is credited twice:
* **No duplicate credits** — each transfer message carries a unique sequence number; the plugin rejects any attempt to process the same message more than once
* **Automatic retry on failure** — transient errors (such as a momentary service interruption) are retried with exponential backoff before any failure state is recorded
* **Dead-letter queue for unresolvable issues** — if a transfer cannot be processed after all retries, it is moved to a dead-letter queue for manual review, ensuring nothing is silently dropped