Recibir (TED IN)

TED IN permite que tu institución reciba transferencias de cualquier banco brasileño. El plugin detecta, valida y acredita cada transferencia. Cuando un cliente de otro banco envía una TED a tu institución, los fondos llegan a la cuenta del destinatario en minutos. Una transferencia que el plugin no puede acreditar ni devolver por su cuenta espera a un operador.

Cómo funciona

Un cliente de otro banco inicia una transferencia TED hacia una de las cuentas de tu institución
Cuando el sondeo de TED IN está activado (JD_POLLING_ENABLED), el plugin sondea la red de JD SPB en busca de nuevas transferencias entrantes cada 60 segundos (valor predeterminado de JD_POLL_INTERVAL_SECONDS)
El plugin busca la cuenta del destinatario en tu CRM por el número de documento del mensaje de la transferencia
El plugin acredita la cuenta del destinatario, menos la comisión de cashin si configuraste una. El plugin registra el crédito en el ledger del destinatario en Midaz, según el enrutamiento del ledger de esa organización, ese ledger y el tipo de transferencia

Créditos al cliente

El plugin también acredita al destinatario en siete créditos al cliente que el banco pagador envía como otros mensajes STR. Cada uno tiene su propio tipo de transferencia:

Mensaje STR	Tipo de transferencia
STR0005R2	`TED_IN_STR0005`
STR0007R2	`TED_IN_STR0007`
STR0029R2	`TED_IN_STR0029`
STR0034R2	`TED_IN_STR0034`
STR0037R2	`TED_IN_STR0037`
STR0041R2 (crédito consignado del INSS)	`TED_IN_STR0041`
STR0051R2	`TED_IN_STR0051`

Cada uno de estos tipos necesita su propio vínculo en el enrutamiento del ledger. El plugin nunca los registra en el vínculo de TED_IN. Un STR0041R2 cuya tarifa bancaria no es cero no se acredita: el plugin lo retiene con el motivo CLASSIFICATION_FAILED. En el modo de comisión legacy, plugin-fees calcula la comisión de cada tipo con su propio paquete de comisiones, nunca con el de TED_IN. Sin paquete para el tipo, el plugin acredita el monto completo.

Cronología de detección y procesamiento

Las etapas de abajo muestran qué pasa después de que el banco de origen envía la transferencia:

Etapa	Qué pasa
Envío	El banco de origen envía la transferencia a la red del SPB
Detección	El plugin obtiene la transferencia en su siguiente ciclo de sondeo. El estado pasa a `RECEIVED`
Validación	El plugin confirma la cuenta del destinatario. El estado pasa a `PROCESSING`
Crédito	El plugin acredita la cuenta del destinatario. El estado pasa a `COMPLETED`
Notificación	El plugin envía el webhook a tu sistema

Tiempo típico: el crédito se completa dentro de un ciclo de sondeo. Con el intervalo de sondeo predeterminado de 60 segundos, los fondos llegan en cerca de un minuto.

Estados de la transferencia

Estado	Qué significa para el destinatario
`RECEIVED`	El plugin detectó la transferencia en la red y empezó a procesarla
`PROCESSING`	El plugin confirmó la cuenta del destinatario y aplica el crédito
`COMPLETED`	Los fondos llegaron a la cuenta del destinatario
`FAILED`	El plugin no pudo aplicar el crédito (por ejemplo, un rechazo de Midaz), o un chargeback revirtió un crédito completado

Comisión de recepción (cashin)

Tu organización puede cobrar una comisión sobre las transferencias entrantes. En el modo de comisión legacy, el plugin descuenta la comisión del monto antes de acreditar al destinatario, y el destinatario recibe el monto neto. En el modo de comisión native, descuenta solo una comisión que el paquete de comisiones saca del monto. Defines el monto y la configuración de la comisión por organización mediante el Fees Engine. Fórmula, para una comisión descontada: credited amount = transfer amount − fee Ejemplo: una transferencia de R$1,000.00 con una comisión descontada de R$2.50 acredita R$997.50 a la cuenta del destinatario. Es lo contrario de TED OUT, donde el plugin suma la comisión encima y el remitente paga más.

En el modo de comisión legacy, una respuesta de comisión inválida, incluida una comisión igual o superior al monto bruto, sigue fees.fail_closed_default. Con false (predeterminado), el plugin acredita el monto bruto con comisión cero y registra el fallo de la comisión. Con true, rechaza el crédito y devuelve los fondos por STR0010. La ruta de comisión nativa del ledger es independiente; consulta Configuración de TED.

Qué pasa cuando no se encuentra al destinatario

Si el plugin no puede asociar el número de documento de la transferencia entrante con una cuenta de tu CRM, la política de tenant jd_polling.auto_return_authorized decide qué pasa. En ambos casos, el plugin no acredita nada y no crea ningún registro de transferencia.

false (predeterminado): el plugin no devuelve nada. Retiene el mensaje con el motivo RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED. Un operador liquida los fondos fuera del plugin y luego registra el resultado con Close Unsettled TED IN Credit. El cierre no mueve dinero.
true: el plugin devuelve la transferencia al banco de origen (devolução STR0010) y el cliente que envió recupera su dinero.

El plugin devuelve la transferencia al banco de origen, sin importar lo que diga esta política, en estos casos:

La cuenta del destinatario no existe en el ledger o coincide con más de una cuenta en tu CRM.
El ledger rechaza el crédito.
La comisión no se puede resolver y fees.fail_closed_default es true.

Consultar las transferencias recibidas

Usa el endpoint List Transfers para obtener todas las transferencias entrantes. Filtra por type=TED_IN para ver las TED recibidas, por un tipo TED_IN_STR para ver una clase de crédito al cliente, y por ledgerId para ver las transferencias de un ledger. Endpoint: GET /v1/transfers Respuesta (campos clave):

{
  "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
  }
}

Para conocer todas las opciones de parámetros de consulta, consulta la referencia List Transfers.

Endpoints operativos

Estos endpoints de operador controlan el bucle de sondeo de TED IN. Están pensados para scripts y runbooks, no para tráfico de usuario final.

Endpoint	Propósito
`POST /v1/transfers/ted-in/poll`	Dispara manualmente el poller de JD que normalmente corre en un cron de 60s. Úsalo después de una ventana de incidente o para validar la conectividad con JD. La ruta tiene ámbito de tenant pero no requiere `X-Organization-Id`, porque resuelve el tenant desde el contexto autenticado. Requiere `X-Idempotency` para reintentos seguros.
`POST /v1/transfers/ted-in/replay`	Reprocesa las filas de backlog de TED IN persistidas y sin procesar que el plugin ya obtuvo de JD. Esta ruta no vuelve a leer JD. Requiere `X-Organization-Id` para el ámbito de organización de Midaz y `X-Idempotency` para reintentos seguros. Sigue resolviendo el tenant desde el contexto autenticado.
`POST /v1/transfers/ted-in/resume`	Libera el latch de recepción fail-closed y rearma un poller que la recuperación automática no puede revivir (un poller que superó el tope duro de pánico). Tiene más privilegio que `/poll` porque reabre el consumo de lectura destructiva de JD. Resume nunca omite la compuerta de la ruta del dinero: si el latch actual todavía no tiene una brecha de conciliación durable, la solicitud se rechaza con `409`. Verifica primero las brechas pendientes con List TED IN Reconciliation Gaps y luego, de forma opcional, pasa `{ "acknowledge": true, "note": "..." }` para marcar la brecha como resuelta en la misma llamada. Un poller sano y sin latch devuelve `resumed: false`, y la ruta es un no-op idempotente y seguro.
`GET /v1/transfers/ted-in/poller`	Lee el estado del poller: habilitado, en ejecución, desactualizado y el motivo de la detención.

Para el cuerpo de la solicitud, la respuesta, los códigos de estado y los códigos de error, consulta la especificación OpenAPI de TED.

Devolver una transferencia recibida

Puedes devolver una TED IN completada al banco pagador con Return a Transfer. La solicitud necesita el permiso transfers:return.

El plugin coloca una retención del monto acreditado en la cuenta del destinatario.
El plugin envía un STR0010 voluntario (código de motivo de devolución 70), que devuelve el monto bruto de la TED IN al banco pagador.
Cuando el STR liquida el STR0010, el plugin revierte el crédito original en el ledger. La devolución pasa a COMPLETED.

Si la devolución se rechaza, el plugin cancela la retención, y la devolución pasa a REJECTED. La devolución es una nueva transferencia TED_OUT sin comisión, y su originalTransferId nombra la TED IN. Considera estas reglas:

Solo una TED recibida como STR0008R2 puede devolverse. Un crédito al cliente no puede, y un crédito entre cores tampoco (422 BTF-0118).
Una TED IN tiene como máximo una devolución activa.
La devolución se ejecuta solo dentro de la ventana de operación. El 24 de diciembre y el último día hábil del año, la ventana de las devoluciones cierra como máximo a las 13:00.
La devolución se registra en el vínculo de TED_OUT del ledger de la TED IN.
No puedes cancelar una devolución.

Un chargeback (STR0010R2) de una TED IN cuya devolución todavía está en curso espera hasta que la devolución termine. Un chargeback que llega después de que la devolución salió espera a un operador.

Mensajes que esperan a un operador

Monitorea cada una de estas colas por separado. No son intercambiables:

Cola	Qué contiene	Cómo consultarla
Mensajes retenidos	Mensajes que el plugin no acreditó ni devolvió. El motivo te dice por qué: por ejemplo `UNRECOGNIZED_TYPE`, `ACCOUNT_NOT_OWNED`, `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED` o `LEDGER_ROUTE_UNRESOLVED`. Un mensaje retenido por `LEDGER_ROUTE_UNRESOLVED` o `RECIPIENT_AMBIGUOUS_ORGANIZATIONS` se libera cuando la configuración lo cubre. Después de una reparación en el CRM, llama a `POST /v1/transfers/ted-in/replay`. Cierra los demás con Close Unsettled TED IN Credit	List Retained TED IN Messages
Créditos no entregables	Créditos que el plugin no pudo aplicar, con el estado de su devolución al banco de origen	List Undeliverable TED IN Credits
Transferencias retenidas por la conciliación	Créditos TED IN que el ledger no pudo confirmar, reembolsos de chargeback que el plugin no pudo terminar y devoluciones cuyo resultado no está comprobado. El plugin reintenta un chargeback en `REVERSING` en cada ciclo. Cierra un reembolso de chargeback en `MANUAL_REVIEW` con Resolve Transfer Reconciliation, acción `RE_POST` o `SETTLED_BY_HAND`. Para una devolución, el código de motivo en la transferencia decide qué acción la cierra	List Pending Reconciliation
Brechas de conciliación	Ciclos de sondeo cuyo resultado de recepción es desconocido	List TED IN Reconciliation Gaps
Fallos de parseo de JD	Mensajes que el plugin no pudo parsear (XML mal formado o esquema que no coincide). Ninguna API los lee: el operador del despliegue hace su triage	Ninguna

La DLQ de webhooks es un camino distinto: contiene las entregas de webhook salientes que fallaron, no las transferencias entrantes. Consulta Webhooks.

Webhooks

Configura un webhook para recibir notificaciones en tiempo real cuando lleguen transferencias. El evento transfer_incoming.completed se dispara apenas el plugin acredita una transferencia. Consulta Webhooks para ver la configuración y los detalles del payload del evento.

Conciliación

Para la conciliación contable y financiera, cada registro de transferencia incluye estos campos:

Campo	Uso
`controlNumber`	Número de control de JD SPB (único por transferencia, se usa para la conciliación interbancaria)
`transferId`	Identificador interno de Lerian
`createdAt`	Marca de tiempo de cuando el plugin detectó la transferencia
`completedAt`	Marca de tiempo de cuando el plugin acreditó los fondos

El plugin persiste los registros de transferencia para conciliación y auditoría.

Garantías de procesamiento

Sin créditos duplicados: el plugin guarda cada mensaje de JD una vez, por su número de secuencia (NumCabSeq). También deduplica los créditos por número de control, ISPB del remitente y monto.
Primero el mensaje: el plugin guarda cada mensaje antes de procesarlo. Un mensaje que no puede terminar queda sin procesar, y el siguiente ciclo de sondeo lo procesa de nuevo.
Colas de operador: un mensaje que el plugin no puede acreditar ni devolver espera en las colas de arriba.

Introducción

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Recibir (TED IN)

Cómo funciona

Créditos al cliente

Cronología de detección y procesamiento

Estados de la transferencia

Comisión de recepción (cashin)

Qué pasa cuando no se encuentra al destinatario

Consultar las transferencias recibidas

Endpoints operativos

Devolver una transferencia recibida

Mensajes que esperan a un operador

Webhooks

Conciliación

Garantías de procesamiento

​Cómo funciona

​Créditos al cliente

​Cronología de detección y procesamiento

​Estados de la transferencia

​Comisión de recepción (cashin)

​Qué pasa cuando no se encuentra al destinatario

​Consultar las transferencias recibidas

​Endpoints operativos

​Devolver una transferencia recibida

​Mensajes que esperan a un operador

​Webhooks

​Conciliación

​Garantías de procesamiento

Cómo funciona

Créditos al cliente

Cronología de detección y procesamiento

Estados de la transferencia

Comisión de recepción (cashin)

Qué pasa cuando no se encuentra al destinatario

Consultar las transferencias recibidas

Endpoints operativos

Devolver una transferencia recibida

Mensajes que esperan a un operador

Webhooks

Conciliación

Garantías de procesamiento