Receive (TED IN)

TED IN lets your institution receive transfers from any Brazilian bank. 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. A transfer that the plugin cannot credit or return on its own waits for an operator.

How it works

A customer at another bank starts a TED transfer to one of your institution’s accounts
When TED IN polling is on (JD_POLLING_ENABLED), the plugin polls the JD SPB network for new incoming transfers every 60 seconds (default JD_POLL_INTERVAL_SECONDS)
The plugin looks up the recipient account in your CRM by the document number in the transfer message
The plugin credits the recipient account, minus the cashin fee if you configured one. The plugin posts the credit on the recipient’s Midaz ledger, under the ledger routing for that organization, ledger, and TED IN

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, the tenant policy jd_polling.auto_return_authorized decides what happens. The plugin credits nothing and creates no transfer record in either case.

false (default): the plugin returns nothing. It retains the message with reason RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED. An operator settles the funds outside the plugin, then records the outcome with Close Unsettled TED IN Credit. The close moves no money.
true: the plugin returns the transfer to the origin bank (STR0010 devolução), and the sending customer gets the money back.

The plugin returns the transfer to the origin bank, whatever this policy says, in these cases:

The recipient’s account is not in the ledger or matches more than one account in your CRM.
The ledger refuses the credit.
The fee leaves nothing to credit.
The fee cannot be resolved and fees.fail_closed_default is true.

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-21T13:15:00Z",
      "updatedAt": "2026-01-21T13:15:30Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "totalCount": 150,
    "hasNextPage": true
  }
}

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

Operational endpoints

These 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 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.
`GET /v1/transfers/ted-in/poller`	Read the poller state: enabled, running, stale, and the stop reason.

For request body, response, status codes, and error codes, see the TED OpenAPI specification.

Messages that wait for an operator

Monitor each of these queues on its own. They are not interchangeable:

Queue	What it holds	How to read it
Retained messages	Messages the plugin neither credited nor returned. The reason tells you why: for example `UNRECOGNIZED_TYPE`, `ACCOUNT_NOT_OWNED`, `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED`, or `LEDGER_ROUTE_UNRESOLVED`. A message retained for `LEDGER_ROUTE_UNRESOLVED` or `RECIPIENT_AMBIGUOUS_ORGANIZATIONS` is processed again on each poll cycle and clears when the cause is fixed. Close the others with Close Unsettled TED IN Credit	List Retained TED IN Messages
Undeliverable credits	Credits the plugin could not apply, with the state of their return to the origin bank	List Undeliverable TED IN Credits
Transfers held by reconciliation	TED IN credits the ledger could not confirm, and chargeback refunds the plugin could not finish. The plugin retries a `REVERSING` chargeback on each cycle. Close a chargeback refund in `MANUAL_REVIEW` with Resolve Transfer Reconciliation, action `RE_POST` or `SETTLED_BY_HAND`	List Pending Reconciliation
Reconciliation gaps	Poll cycles whose receive outcome is unknown	List TED IN Reconciliation Gaps
JD parse failures	Messages the plugin could not parse (malformed XML or schema mismatch). No API reads them: the operator of the deployment triages them	None

The webhook DLQ is a different path: it holds failed outbound webhook deliveries, not inbound transfers. See Webhooks.

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

No duplicate credits: the plugin stores each JD message once, by its sequence number (NumCabSeq). It also deduplicates credits by control number, sender ISPB, and amount.
Message first: the plugin stores each message before it processes it. A message that it cannot finish stays unprocessed, and the next poll cycle processes it again.
Operator queues: a message that the plugin can neither credit nor return waits in the queues above.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Receive (TED IN)

How it works

Detection and processing timeline

Transfer states

Receiving fee (cashin)

What happens when a recipient isn’t found

Querying received transfers

Operational endpoints

Messages that wait for an operator

Webhooks

Reconciliation

Processing guarantees

​How it works

​Detection and processing timeline

​Transfer states

​Receiving fee (cashin)

​What happens when a recipient isn’t found

​Querying received transfers

​Operational endpoints

​Messages that wait for an operator

​Webhooks

​Reconciliation

​Processing guarantees

How it works

Detection and processing timeline

Transfer states

Receiving fee (cashin)

What happens when a recipient isn’t found

Querying received transfers

Operational endpoints

Messages that wait for an operator

Webhooks

Reconciliation

Processing guarantees