Receive (TED IN)

Receive TED transfers automatically — the plugin polls SPB, validates recipient Accounts, and credits funds with no manual intervention.

TED IN lets your institution receive transfers from any Brazilian bank automatically. Your team takes no action — the plugin detects, validates, and credits each transfer. When a customer at another bank sends a TED to your institution, the funds reach the recipient’s account within minutes.

How it works

---

1. A customer at another bank starts a TED transfer to one of your institution’s accounts
2. Every 60 seconds (default JD_POLL_INTERVAL_SECONDS), the plugin polls the JD SPB network for new incoming transfers
3. The plugin looks up the recipient account in your CRM by the document number in the transfer message
4. The plugin credits the recipient account automatically, minus the cashin fee if you configured one

Detection and processing timeline

---

The stages below show what happens after the origin bank sends the transfer:

Stage	What happens
Submission	The origin bank submits the transfer to the SPB network
Detection	The plugin fetches the transfer on its next poll cycle. Status becomes RECEIVED
Validation	The plugin confirms the recipient account. Status becomes PROCESSING
Credit	The plugin credits the recipient account. Status becomes COMPLETED
Notification	The plugin sends the webhook to your system

Typical time: The credit completes within one poll cycle. With the default 60-second poll interval, the funds land in about a minute.

Transfer states

---

State	What it means for the recipient
RECEIVED	The plugin detected the transfer on the network and started processing
PROCESSING	The plugin confirmed the recipient account and applies the credit
COMPLETED	The funds reached the recipient’s account
FAILED	The plugin could not apply the credit (for example, a Midaz rejection), or a chargeback reversed a completed credit

Receiving fee (cashin)

---

Your organization can charge a fee on incoming transfers. When you enable it, the plugin deducts the fee from the amount before it credits the recipient. The recipient receives the net amount. You set the fee amount and configuration per organization through the Fees Engine.

Formula: credited amount = transfer amount − fee

Example: a R$1,000.00 transfer with a R$2.50 fee credits R$997.50 to the recipient’s account. This is the opposite of TED OUT, where the plugin adds the fee on top and the sender pays more.

What happens when a recipient isn’t found

---

If the plugin cannot match the document number in the incoming transfer to an account in your CRM, it returns the transfer to the origin bank automatically. The sending customer gets their money back. Your team takes no action, and no funds go unaccounted for.

The plugin records the inbound message as an undeliverable incoming transfer in the undeliverable_incoming_transfers store. It then dispatches a devolução (STR0010 return) to the origin bank. This path does not create a credited transfer record set to FAILED.

Querying received transfers

---

Use the 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):

{
  "items": [
    {
      "transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
      "type": "TED_IN",
      "status": "COMPLETED",
      "amount": 5000.00,
      "feeAmount": 0.00,
      "totalAmount": 5000.00,
      "createdAt": "2026-01-21T10:15:00-03:00",
      "updatedAt": "2026-01-21T10:15:30-03:00"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "totalCount": 150,
    "hasNextPage": true
  }
}

For full query parameter options, see the List Transfers reference.

Operational endpoints

---

Three operator endpoints control the TED IN polling loop. They target scripts and runbooks, not end-user traffic.

Endpoint	Purpose
POST /v1/transfers/ted-in/poll	Manually trigger the JD poller that normally runs on a 60s cron. Use it after an incident window or to validate JD connectivity. The route is tenant-scoped but does not require X-Organization-Id, because it resolves the tenant from the authenticated context. It requires X-Idempotency for safe retries. A same-key retry replays the cached response instead of reading JD’s destructive queue again.
POST /v1/transfers/ted-in/replay	Replay persisted, unprocessed TED IN backlog rows that the plugin already fetched from JD. This route does not read JD again. It requires X-Organization-Id for Midaz organization scope and X-Idempotency for safe retries. It still resolves the tenant from the authenticated context.
POST /v1/transfers/ted-in/resume	Clear the fail-closed receive latch and re-arm a poller that auto-recovery cannot revive — a panicked multi-tenant child or a single-tenant poller past the panic hard-cap. Higher-privilege than /poll because it re-opens JD destructive-read consumption. Resume never bypasses the money-path gate: if the current latch has no durable reconciliation gap yet, the request is refused with 409. Verify pending gaps with List TED IN Reconciliation Gaps first, then optionally pass { "acknowledge": true, "note": "..." } to mark the gap resolved in the same call. A healthy, not-latched poller returns resumed: false — the route is a safe idempotent no-op.

For request body, response, status codes, and error codes, see the TED OpenAPI specification (operations triggerTEDInPoller, replayTEDInPoller, and resumeTEDInPoller).

Three distinct dead-letter paths

---

The plugin uses three separate failure stores. They are not interchangeable, and you must monitor each one independently:

• JD parse failures — the plugin stores these in jd_incoming_parse_failures. The message arrived from JD, but the plugin could not interpret it (malformed XML, unknown message type). This store needs manual triage.
• Undeliverable inbound transfers — the plugin stores these in undeliverable_incoming_transfers. Parsing succeeded, but the plugin could not apply the credit (for example, it did not find the recipient account). This path can trigger an automatic devolução to the origin bank.
• Webhook DLQ — the retry queue for failed outbound webhook deliveries, at /v1/webhooks/dlq. It does not relate 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 the plugin credits a transfer. See Webhooks for setup and event payload details.

Reconciliation

---

For accounting and finance reconciliation, each transfer record includes these fields:

Field	Usage
controlNumber	JD SPB control number — unique per transfer, used for interbank reconciliation
transferId	Lerian internal identifier
createdAt	Timestamp when the plugin detected the transfer
completedAt	Timestamp when the plugin credited the funds

The plugin persists transfer records for reconciliation and audit.

Processing guarantees

---

The plugin makes sure that it never loses a transfer and never credits one twice:

• No duplicate credits — each transfer message carries a unique sequence number. The plugin rejects any attempt to process the same message twice.
• Automatic retry on failure — the plugin retries transient errors (such as a momentary service interruption) with exponential backoff before it records any failure state.
• Dead-letter queue for unresolvable issues — if the plugin cannot process a transfer after all retries, it moves the transfer to a dead-letter queue for manual review. The plugin never drops a transfer silently.