Enviar TED (TED OUT)

O TED OUT permite que seus clientes enviem valores para contas em outras instituições financeiras. O processo segue um fluxo de duas etapas: iniciação (com cálculo de tarifa) e confirmação.

Pré-requisitos

Antes de iniciar uma transferência:

A conta de origem deve estar cadastrada no CRM
O remetente deve ter saldo suficiente (valor + tarifa)
A operação deve ocorrer em dia útil, entre 06:30 e 17:00 (Brasília)

Etapa 1: Iniciar a transferência

A primeira etapa valida os dados, calcula a tarifa e cria uma intenção de transferência válida por 24 horas. Nenhum fundo é movimentado nesta etapa. Endpoint: POST /v1/transfers/initiate

O que acontece

O cliente envia os detalhes da transferência (destinatário, valor)
O sistema valida as regras de negócio: horário de funcionamento, limites e duplicidade
O serviço de taxas (plugin-fees) calcula o custo da transação
Uma entidade PaymentInitiation é criada com expiração de 24 horas
O sistema retorna o initiationId junto com os valores calculados

Headers

Header	Obrigatório	Descrição
`X-Organization-Id`	Sim	UUID da organização
`Authorization`	Condicional	Bearer token (se autenticação habilitada)
`X-Idempotency-Key`	Não	Chave de idempotência (UUID v4 recomendado)

Request body

{
  "senderAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "123456",
    "accountType": "CHECKING",
    "taxId": "12345678901",
    "name": "João Silva"
  },
  "amount": 1000.00,
  "description": "Pagamento de fornecedor"
}

Campos do recipient

Campo	Tipo	Obrigatório	Descrição
`ispb`	String	Sim	Código ISPB do banco (8 dígitos)
`branch`	String	Sim	Agência (4 dígitos)
`account`	String	Sim	Número da conta (1-20 dígitos)
`accountType`	Enum	Sim	CHECKING, SAVINGS, SALARY, PAYMENT
`taxId`	String	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos)
`name`	String	Sim	Nome do 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"
}

A iniciação expira em 24 horas. Após esse período, uma nova iniciação deve ser criada.

Etapa 2: Confirmar a transferência

Após o usuário revisar a tarifa, confirme a transferência para iniciar o processamento. Endpoint: POST /v1/transfers/process

O que acontece

O sistema valida o initiationId e verifica se não expirou
Valida o saldo do remetente e provisiona os fundos (valor + taxa) no Midaz
A mensagem STR0008 é enviada ao sistema da JD Consultores com assinatura digital
O status da transferência muda para PROCESSING
Em segundo plano, o worker aguarda a confirmação (STR0008R2) da JD

Request body

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

Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "TED-2026-000123",
  "status": "PROCESSING",
  "type": "TED_OUT",
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "createdAt": "2026-02-05T15:30:00-03:00",
  "estimatedCompletionAt": "2026-02-05T18:00:00-03:00"
}

Timeline

O fluxo típico de uma transferência TED OUT:

T+0s:    POST /v1/transfers/process
         ├─ Validar saldo
         ├─ Provisionar fundos (Midaz, pending: true)
         └─ Enviar STR0008 para JD

T+2s:    Resposta JD: ACS99 (mensagem recebida)
         ├─ Armazenar NumCabSeq
         └─ Status: PROCESSING

T+30s:   Polling RecebeMensagem #1
         └─ ALS01 (sem mensagens ainda)

T+60s:   Polling RecebeMensagem #2
         └─ ALS01 (sem mensagens ainda)

T+90s:   Polling RecebeMensagem #3
         └─ ALS99 (tem mensagem!)
             ├─ Parsear STR0008R2
             ├─ CommitTransaction (Midaz)
             └─ Status: COMPLETED

T+95s:   Webhook notification enviado

SLA: < 10 minutos típicos, D+0 mesmo dia (antes das 17:00)

Tratamento de erros

4xx da JD (rejeição imediata)

CancelTransaction imediato no Midaz (libera provisão)
Status atualizado para REJECTED
Webhook transfer.failed enviado
Reembolso automático (valor + taxa)

5xx/Timeout (erro transitório)

Retry automático: 5x (0s, 5s, 25s, 60s, 120s)
Consulta ConsultaNumCtrlIF para verificar status
Se ainda incerto após retries: reembolso fail-safe

Chargeback (STR0010R2)

Mensagem de devolução recebida do banco destinatário
CancelTransaction ou RevertTransaction no Midaz
Status: REJECTED
Reembolso automático com código de devolução

Códigos de erro comuns

Código	HTTP	Descrição
`BTF-0001`	400	Dados inválidos (ISPB, valor negativo)
`BTF-0010`	403	Fora do horário de operação do BACEN
`BTF-0011`	422	Limite diário/mensal excedido
`BTF-0012`	409	Transferência duplicada detectada
`BTF-2001`	422	Saldo insuficiente
`BTF-1000`	503	Serviço JD SPB indisponível

Exemplos de resposta de erro

Fora do horário de funcionamento (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 status

Acompanhe o progresso da transferência: Endpoint: GET /v1/transfers/{transferId}

Response

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "TED-2026-000123",
  "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": "CHECKING",
    "taxId": "12345678901",
    "name": "João Silva"
  },
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "description": "Pagamento de fornecedor",
  "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": "PROCESSING", "timestamp": "2026-02-05T15:30:05-03:00"},
    {"status": "COMPLETED", "timestamp": "2026-02-05T15:35:12-03:00"}
  ]
}

Cancelar transferência

Transferências podem ser canceladas enquanto estiverem no status CREATED ou PENDING. Endpoint: POST /v1/transfers/{transferId}/cancel

Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "status": "CANCELLED",
  "cancelledAt": "2026-02-05T15:32:00-03:00"
}

Transferências em PROCESSING ou posteriores não podem ser canceladas. Aguarde a conclusão ou falha da operação.

Códigos ISPB comuns

Banco	ISPB
Banco do Brasil	00000000
Bradesco	60746948
Itaú	60701190
Santander	90400888
Caixa Econômica	00360305
Nubank	18236120
Inter	00416968

Consulte a lista completa de ISPBs no site do Banco Central.

​Pré-requisitos

​Etapa 1: Iniciar a transferência

​O que acontece

​Headers

​Request body

​Campos do recipient

​Response (200 OK)

​Etapa 2: Confirmar a transferência

​O que acontece

​Request body

​Response (200 OK)

​Timeline

​Tratamento de erros

​Códigos de erro comuns

​Exemplos de resposta de erro

​Consultar status

​Response

​Cancelar transferência

​Response (200 OK)

​Códigos ISPB comuns

Pré-requisitos

Etapa 1: Iniciar a transferência

O que acontece

Headers

Request body

Campos do recipient

Response (200 OK)

Etapa 2: Confirmar a transferência

O que acontece

Request body

Response (200 OK)

Timeline

Tratamento de erros

Códigos de erro comuns

Exemplos de resposta de erro

Consultar status

Response

Cancelar transferência

Response (200 OK)

Códigos ISPB comuns