> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar (TED OUT)

> Envie transferências TED para qualquer banco brasileiro com um fluxo de duas etapas, iniciar e confirmar: prévia da tarifa, liquidação no mesmo dia e conformidade com o BACEN.

O TED OUT deixa os seus clientes enviarem dinheiro para qualquer conta em qualquer banco brasileiro. O fluxo de duas etapas, iniciar e depois confirmar, deixa o cliente revisar a tarifa antes de o sistema efetivar a transferência.

## Como funciona para o seu cliente

***

**Etapa 1: Informar os dados e revisar a tarifa**
O cliente informa os dados bancários do destinatário e o valor. O sistema calcula a tarifa e retorna o custo total antes de debitar qualquer coisa. O cliente vê exatamente o que vai pagar.

**Etapa 2: Confirmar e enviar**
Depois que o cliente confirma, o sistema coloca uma retenção nos fundos (valor + tarifa) na conta dele. Ele envia a transferência pelo gateway SPB da JD até a rede do BACEN e emite um número de confirmação na hora.

## Pré-requisitos

***

Antes de iniciar uma transferência:

* O remetente deve ter uma conta cadastrada no CRM.
* O saldo do remetente deve cobrir o valor da transferência mais a tarifa aplicável.
* Você deve pedir a transferência em um dia útil, dentro da janela de operação (das 06:30 às 17:00, horário de Brasília, por padrão).

## Etapa 1: Iniciar a transferência

***

O cliente envia os dados do destinatário e o valor. O sistema valida a requisição, calcula a tarifa e cria uma intenção de transferência válida até o fechamento da janela de operação daquele dia. O sistema não move fundos nesta etapa.

Veja a especificação completa da requisição na referência [Initiate Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/initiate-transfer.md).

**Endpoint:** POST /v1/transfers/initiate

**Resposta (campos principais):**

```json theme={null}
{
  "initiationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b",
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "status": "PENDING_CONFIRMATION",
  "expiresAt": "2026-02-06T17:00:00-03:00"
}
```

> [!NOTE]
>
> **Direção da tarifa (cash-out):** nas transferências TED OUT, o plugin soma a tarifa por cima do valor da transferência, então `totalAmount = amount + feeAmount`. O plugin retém e depois debita o total completo da conta do remetente.

> [!WARNING]
>
> A intenção de transferência expira em `expiresAt`, o fechamento da janela de operação daquele dia. Se o cliente não confirmar a tempo, crie uma nova iniciação.

## Etapa 2: Confirmar a transferência

***

Depois que o cliente revisa a tarifa e confirma, envie o `initiationId` para processar a transferência. O sistema provisiona os fundos e manda o pagamento para a rede do BACEN.

A maioria das integrações processa a transferência apenas com o `initiationId`. Alguns tenants assinam os payloads de TED OUT fora do plugin. Esses tenants chamam antes o `POST /v1/transfers/signing/prepare`. Depois enviam `signingArtifactId`, `payloadHash` e `signature` com o mesmo `initiationId`.

Veja a especificação completa da requisição na referência [Process Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/process-transfer.md).

**Endpoint:** POST /v1/transfers/process

**Resposta (campos principais):**

```json theme={null}
{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "confirmationNumber": "20260205001",
  "status": "PROCESSING",
  "feeAmount": 1.50,
  "totalAmount": 1001.50
}
```

## Linha do tempo da liquidação

***

**1. Enviada**

O sistema provisiona os fundos e manda a transferência para a rede do BACEN. Status: `PROCESSING`.

**2. Liquidada**

O STR confirma a liquidação, e o plugin debita os fundos retidos. Status: `COMPLETED`.

**3. Status disponível**

O plugin expõe o status `COMPLETED` pelas APIs de transferência e de conciliação, e envia um webhook `transfer.completed`.

O TED liquida no mesmo dia (D+0) para transferências enviadas dentro da janela de operação.

## Horário de funcionamento

***

> [!WARNING]
>
> Peça transferências TED apenas em dias úteis, das 06:30 às 17:00 (Brasília, UTC-3, por padrão). O plugin rejeita na hora qualquer transferência fora dessa janela e não move fundos. Ele também rejeita nos feriados bancários do BACEN. A resposta de erro indica o próximo horário disponível.

## Tratamento de erros

***

> [accordion] Transferência rejeitada pela JD ou pelo STR
>
> A JD ou o STR rejeita a transferência. O plugin libera a retenção, e assim o valor completo, incluindo a tarifa, volta ao saldo disponível do remetente. Status: `REJECTED`. O plugin envia um webhook `transfer.rejected`.

> [accordion] Problema temporário de rede
>
> O plugin repete a chamada à JD (`jdspb.max_retries`, padrão 3). Se o resultado continua desconhecido depois das tentativas (um 5xx ou um timeout do JD SPB), o plugin não reverte a transferência sozinho. Ele mantém a retenção e o status `PROCESSING` e passa a transferência ao worker de conciliação, que pergunta o resultado à JD. Se a conciliação esgota as tentativas, a transferência passa a `FAILED` com a retenção ainda ativa e aguarda um operador (`MANUAL_REVIEW`).
>
> Uma resposta pendente da JD não usa tentativa. Depois de 24 horas em conciliação, uma transferência que a JD ainda responde como pendente continua `PROCESSING` com a retenção ativa e aguarda um operador (`MANUAL_REVIEW`, motivo `STR_PENDING_AGED`). Uma rejeição 4xx clara, ao contrário, reverte a retenção na hora (veja o caso de rejeição acima).

> [accordion] Devolução do banco de destino
>
> O banco de destino pode devolver os fundos depois da liquidação, por exemplo em um encerramento de conta ou em uma retenção regulatória. A transferência original continua `COMPLETED`. O plugin cria uma nova transferência de reembolso `TED_IN` que credita o valor devolvido ao remetente original, com `originalTransferId` e `devolutionCode`.
>
> O plugin fica com a tarifa, a menos que a política de tenant `fees.refund_on_devolucao` seja `true` (padrão `false`). Com `true`, o reembolso de uma devolução integral de um TED OUT concluído também devolve a tarifa ao remetente. A transferência de reembolso mantém o valor devolvido em `amount` e registra a tarifa em `metadata.feeRefundedAmount`. Quando o ledger não consegue devolver a tarifa, o plugin reembolsa apenas o valor devolvido, e o reembolso traz `metadata.feeRetained` com o valor `true`. O plugin também envia um webhook `transfer_outgoing.devolution_notified`.

> [!NOTE]
>
> Cada requisição de transferência que altera dados deve incluir um header `X-Idempotency` (no máximo 255 caracteres). Reutilize a mesma chave para repetir uma requisição cuja resposta você não recebeu. Depois de um `5xx`, consulte a transferência antes de enviá-la de novo. Veja o [guia do desenvolvedor](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-developer-guide.md#idempotency) para os detalhes.

Para a lista completa de códigos de erro, veja a [referência de erros do TED](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/ted-error-list.md).

## Consultar o status da transferência

***

Acompanhe o andamento de uma transferência a qualquer momento.

**Endpoint:** [GET /v1/transfers/{transferId}](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer.md)

**Resposta (campos principais):**

```json theme={null}
{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "confirmationNumber": "20260205001",
  "senderAccountId": "019c96a0-a910-7abc-d1e2-8c9d0e1f2a3b",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "createdAt": "2026-02-05T18:30:00Z",
  "completedAt": "2026-02-05T18:35:12Z"
}
```

## Cancelar uma transferência

***

Você pode cancelar uma transferência enquanto ela está no status `CREATED` ou `PENDING`, antes de o plugin enviá-la à rede. Você não pode cancelar a [devolução de um TED IN](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-in.md#return-a-received-transfer).

**Endpoint:** [POST /v1/transfers/{transferId}/cancel](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/cancel-transfer.md)

> [!WARNING]
>
> Você não pode cancelar uma transferência em `PROCESSING` ou em um estado posterior. Depois que o plugin a envia à rede do BACEN, a transferência deve ser concluída ou falhar antes de qualquer estorno.

## Códigos ISPB comuns

***

*Última verificação: 2026-02-06. Os valores podem mudar.*

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

Para a lista completa, consulte o [diretório de ISPB](https://www.bcb.gov.br/pom/spb/estatistica/port/AODO.asp) no site do Banco Central.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.