TED e transferências

TED para outras instituições e transferência interna entre contas do parceiro, com favoritos. Valores em centavos. Toda conta de origem precisa pertencer ao parceiro do token.

Como acompanhar o desfecho

A TED emite os webhooks ted.confirmed (liquidada) e ted.failed (rejeitada ou expirada). A transferência interna emite transfer.confirmed e transfer.failed. Você também pode consultar o status a qualquer momento em GET /transfers/:id, cujo campo status passa por processing, accepted, settled, confirmed, completed, rejected, timeout, cancelled ou refunded.

Enviar TED

POST /api/partner/v1/transfers/ted
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "account_id": 1042,
  "amount": 25000,
  "recipientName": "João Pereira",
  "recipientDocument": "98765432100",
  "recipientBankCode": "12345678",
  "recipientBranch": "0001",
  "recipientAccount": "123456",
  "purposeCode": "10",
  "description": "Pagamento fornecedor"
}

• Escopo: transfer:write
• Obrigatórios: account_id, amount, recipientName, recipientDocument, recipientBankCode (ISPB da instituição de destino), recipientAccount.
• Opcionais: recipientBranch, purposeCode (padrão "10"), description.

Os dados do remetente (nome, documento, agência e conta) vêm da conta de origem, você não precisa enviá-los.

Resposta 202:

{
  "status": "accepted",
  "transactionId": "TED20260711d8a3695bc594e2577c23",
  "amount": 25000,
  "message": "TED enviado para processamento via SPB/BACEN"
}

Faltando um campo obrigatório, a resposta é 422 com a mensagem Campos obrigatórios SPB ausentes: .... Uma conta bloqueada ou encerrada responde 422 com code: "account_blocked".

Transferência interna

Move dinheiro entre duas contas do próprio parceiro. Origem e destino são validados antes de a transferência ocorrer, e não é possível transferir para a mesma conta.

POST /api/partner/v1/transfers/internal
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "account_id": 1042,
  "destination_account_id": 1043,
  "amount": 5000,
  "description": "Aporte"
}

• Escopo: transfer:write · Obrigatórios: account_id, destination_account_id, amount

Resposta 202:

{ "status": "accepted", "transactionId": "TEF...", "amount": 5000, "message": "Transferência interna aceita para processamento" }

Sem destination_account_id responde 422; origem igual ao destino responde 422; destino de outro parceiro responde 403.

Consultar transferência

GET /api/partner/v1/transfers/{id}
Authorization: Bearer {{access_token}}

• Escopo: transfer:read

{
  "data": {
    "transactionId": "TED20260711d8a3...",
    "type": "ted",
    "status": "settled",
    "amount": 25000,
    "recipientKey": "123456",
    "direction": "outbound",
    "createdAt": "2026-07-11T10:00:00Z",
    "completedAt": "2026-07-11T10:00:02Z"
  }
}

Uma transação de outro parceiro responde 403; um id desconhecido responde 404.

TED recebida (créditos)

Créditos de TED recebidos de outras instituições, com devolução ao remetente comandada pelo cliente.

Listar TED recebidas

GET /api/partner/v1/ted/credits?account_id=1042
Authorization: Bearer {{access_token}}

• Escopo: transfer:read · Filtro opcional status.

{
  "data": {
    "credits": [
      { "id": "9d4f2c1a-7b3e-4c91-8a52-0f1e2d3c4b5a", "numCtrlStr": "STR20260714000000123", "amount": 150075, "senderName": "JOAO PEREIRA", "senderDocument": "12345678901", "senderIspb": "60746948", "status": "credited_member", "refundable": true, "settlementDate": "2026-07-14", "receivedAt": "2026-07-14T21:00:00Z" }
    ],
    "total": 1
  }
}

Valores em centavos, os mais recentes primeiro (até 50). refundable fica true enquanto o crédito pode ser devolvido pelo cliente.

Devolver TED recebida

Comanda a devolução integral do crédito ao remetente, pela mensagem STR0010. Não há devolução parcial: o motor devolve o valor original da operação.

POST /api/partner/v1/ted/credits/{id}/refund
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "reason": "70" }

• Escopo: transfer:write · reason é opcional (padrão 70) e restrito aos códigos abaixo:

reason	Motivo
1	Conta encerrada
2	Agência ou conta inválida
3	CPF/CNPJ ausente ou divergente
4	Mensagem inválida para o tipo de transferência
5	Divergência de titularidade
9	Fraude
31	CPF/CNPJ inapto na Receita Federal
70	Por solicitação do cliente da IF Recebedora (padrão)
72	Não conformidade no pagamento
84	Conta inválida para o tipo ou finalidade da transferência

Resposta 202 (aceite, não o desfecho):

{ "data": { "refundId": "9d4f2c1a-7b3e-4c91-8a52-0f1e2d3c4b5a", "numCtrlStr": "STR20260714000000123", "amount": 150075, "status": "processing" } }

O valor fica reservado na conta até o desfecho, que chega pelos webhooks ted.refund.requested, ted.refund.completed e ted.refund.failed, descritos em Webhooks. Um crédito de outra conta ou inexistente responde 404; devolução já em andamento, crédito já devolvido, motivo inválido ou saldo insuficiente respondem 422.

Favoritos

Beneficiários salvos para reutilizar em transferências. O account_id é obrigatório em todas as chamadas.

POST   /api/partner/v1/transfers/favorites                        # criar (transfer:write)
GET    /api/partner/v1/transfers/favorites?account_id=1042        # listar (transfer:read)
DELETE /api/partner/v1/transfers/favorites/{id}?account_id=1042   # remover (transfer:write)
Authorization: Bearer {{access_token}}

Corpo do POST: name, document, bankCode, branch, accountNumber são obrigatórios; accountType (padrão checking), pixKey e pixKeyType são opcionais. A resposta 201 traz { id, name, document, bankCode, branch, accountNumber, accountType, pixKey, pixKeyType, createdAt }.