Saltar al contenido principal
El TED OUT permite que sus clientes envíen valores a cuentas en otras instituciones financieras. El proceso sigue un flujo de dos etapas: iniciación (con cálculo de tarifa) y confirmación.

​
Prerrequisitos

Antes de iniciar una transferencia:
  • La cuenta de origen debe estar registrada en el CRM
  • El remitente debe tener saldo suficiente (valor + tarifa)
  • La operación debe ocurrir en día hábil, entre 06:30 y 17:00 (Brasilia)

​
Etapa 1: Iniciar la transferencia

La primera etapa valida los datos, calcula la tarifa y crea una intención de transferencia válida por 24 horas. Ningún fondo es movido en esta etapa. Endpoint: POST /v1/transfers/initiate

​
Qué sucede

  1. El cliente envía los detalles de la transferencia (destinatario, valor)
  2. El sistema valida las reglas de negocio: horario de funcionamiento, límites y duplicidad
  3. El servicio de tarifas (plugin-fees) calcula el costo de la transacción
  4. Una entidad PaymentInitiation es creada con expiración de 24 horas
  5. El sistema retorna el initiationId junto con los valores calculados

​
Headers

HeaderObligatorioDescripción
X-Organization-IdSíUUID de la organización
AuthorizationCondicionalBearer token (si autenticación habilitada)
X-Idempotency-KeyNoClave de idempotencia (UUID v4 recomendado)

​
Request body

{
  "senderAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "123456",
    "accountType": "CACC",
    "holderDocument": "12345678901",
    "holderName": "João Silva"
  },
  "amount": 1000.00,
  "description": "Pago a proveedor"
}

​
Campos del recipient

CampoTipoObligatorioDescripción
ispbStringSíCódigo ISPB del banco (8 dígitos)
branchStringSíAgencia (4 dígitos)
accountStringSíNúmero de cuenta (1-20 dígitos)
accountTypeEnumSíCACC, SLRY, SVGS, TRAN, OTHR (ISO 20022)
holderDocumentStringSíCPF (11 dígitos) o CNPJ (14 dígitos)
holderNameStringSíNombre del titular (1-200 caracteres)

​
Response (200 OK)

{
  "initiationId": "660e8400-e29b-41d4-a716-446655440001",
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "estimatedCompletionAt": "2026-02-05T18:00:00-03:00",
  "expiresAt": "2026-02-06T15:30:00-03:00",
  "status": "PENDING_CONFIRMATION"
}
La iniciación expira en 24 horas. Después de ese período, una nueva iniciación debe ser creada.

​
Etapa 2: Confirmar la transferencia

Después de que el usuario revise la tarifa, confirme la transferencia para iniciar el procesamiento. Endpoint: POST /v1/transfers/process

​
Qué sucede

  1. El sistema valida el initiationId y verifica que no haya expirado
  2. Valida el saldo del remitente y aprovisiona los fondos (valor + tasa) en Midaz
  3. El mensaje STR0008 es enviado al sistema de JD Consultores con firma digital
  4. El estado de la transferencia cambia a PROCESSING
  5. En segundo plano, el worker espera la confirmación (STR0008R2) de JD

​
Request body

{
  "initiationId": "660e8400-e29b-41d4-a716-446655440001"
}

​
Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "20260205001",
  "status": "CREATED",
  "feeAmount": 1.50,
  "totalAmount": 1001.50
}

​
Timeline

El flujo típico de una transferencia TED OUT: 
T+0s:    POST /v1/transfers/process
         ├─ Validar saldo
         ├─ Aprovisionar fondos (Midaz, pending: true)
         └─ Enviar STR0008 a JD

T+2s:    Respuesta JD: ACS99 (mensaje recibido)
         ├─ Almacenar NumCabSeq
         └─ Estado: PROCESSING

T+30s:   Polling RecebeMensagem #1
         └─ ALS01 (sin mensajes aún)

T+60s:   Polling RecebeMensagem #2
         └─ ALS01 (sin mensajes aún)

T+90s:   Polling RecebeMensagem #3
         └─ ALS99 (¡tiene mensaje!)
             ├─ Parsear STR0008R2
             ├─ CommitTransaction (Midaz)
             └─ Estado: COMPLETED

T+95s:   Notificación webhook enviada
SLA: < 10 minutos típico, D+0 mismo día (antes de las 17:00)

​
Tratamiento de errores

  • CancelTransaction inmediato en Midaz (libera aprovisionamiento)
  • Estado actualizado a REJECTED
  • Webhook transfer.failed enviado
  • Reembolso automático (valor + tarifa)
  • Retry automático: 5x (0s, 5s, 25s, 60s, 120s)
  • Consulta ConsultaNumCtrlIF para verificar estado
  • Si aún incierto después de retries: reembolso fail-safe
  • Mensaje de devolución recibido del banco destinatario
  • CancelTransaction o RevertTransaction en Midaz
  • Estado: REJECTED
  • Reembolso automático con código de devolución

​
Códigos de error comunes

CódigoHTTPDescripción
BTF-0001400Datos inválidos (ISPB, valor negativo)
BTF-0010403Fuera del horario de operación del BACEN
BTF-0011422Límite diario/mensual excedido
BTF-0012409Transferencia duplicada detectada
BTF-2001422Saldo insuficiente
BTF-1000503Servicio JD SPB no disponible

​
Ejemplos de respuesta de error

Fuera del horario de funcionamiento (403): 
{
  "code": "BTF-0010",
  "title": "Operating Hours Violation",
  "message": "Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time",
  "fields": {
    "currentTime": "2026-01-21T18:30:00-03:00",
    "nextAvailableTime": "2026-01-22T06:30:00-03:00"
  }
}
Saldo insuficiente (422): 
{
  "code": "BTF-2001",
  "title": "Insufficient Balance",
  "message": "Sender account does not have sufficient balance for this transfer.",
  "fields": {
    "available": 500.00,
    "required": 1001.50
  }
}

​
Consultar estado

Acompañe el progreso de la transferencia: Endpoint: GET /v1/transfers/

​
Response

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "20260205001",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "sender": {
    "accountId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "123456",
    "accountType": "CACC",
    "holderDocument": "12345678901",
    "holderName": "João Silva"
  },
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "description": "Pago a proveedor",
  "createdAt": "2026-02-05T15:30:00-03:00",
  "completedAt": "2026-02-05T15:35:12-03:00",
  "statusHistory": [
    {"status": "CREATED", "timestamp": "2026-02-05T15:30:00-03:00"},
    {"status": "PENDING", "timestamp": "2026-02-05T15:30:02-03:00"},
    {"status": "PROCESSING", "timestamp": "2026-02-05T15:30:05-03:00"},
    {"status": "COMPLETED", "timestamp": "2026-02-05T15:35:12-03:00"}
  ]
}

​
Cancelar transferencia

Las transferencias pueden ser canceladas mientras estén en estado CREATED o PENDING_CONFIRMATION. Endpoint: POST /v1/transfers//cancel

​
Request body (opcional)

{
  "reason": "User requested cancellation"
}

​
Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "status": "CANCELLED",
  "cancelledAt": "2026-02-05T15:32:00-03:00"
}
Las transferencias en PROCESSING o estados posteriores no pueden ser canceladas. Espere a que la operación se complete o falle.

​
Códigos ISPB comunes

BancoISPB
Banco do Brasil00000000
Bradesco60746948
Itaú60701190
Santander90400888
Caixa Econômica00360305
Nubank18236120
Inter00416968
Consulte la lista completa de ISPBs en el sitio del Banco Central.