Enviar uma TED

Uma TED é uma transferência de uma das suas carteiras para uma conta em outro banco, identificada pelos dados bancários. Enviar uma tem duas etapas: você cria a TED com os dados bancários do favorecido e o valor e depois a confirma, escolhendo a categoria de saldo de onde o valor sai. Nada sai da carteira até você confirmar, e até lá você pode cancelar a TED.

Para pagar uma conta pelos dados bancários você também pode usar Pix — veja Enviar um pagamento Pix.

Fluxo

Quem pode enviar uma TED

Você precisa de permissão para pagar com a carteira:

na carteira principal da organização, ser administrador da organização ou do realm;
em outra carteira, ser um desses administradores ou ter a carteira compartilhada com você como OWNER ou USER.

A mesma regra vale para confirmar e cancelar. Sem ela, você recebe 403 FORBIDDEN_WALLET. Qualquer membro da organização pode ler e listar TEDs.

Etapa 1: Criar a TED

Envie o valor em centavos, os dados bancários do favorecido em creditParty e, em debitParty, o nome de quem está fazendo a transferência do seu lado.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 235000,
    "description": "Ensaio fotográfico da campanha de novembro",
    "creditParty": {
      "bankCode": "341",
      "branch": "1234",
      "accountNumber": "0045671",
      "accountType": "CACC",
      "document": "11222333000181",
      "name": "Estúdio Lumen Fotografia Ltda"
    },
    "debitParty": {
      "personName": "Mariana Souza Lima"
    }
  }'

Campo	Observações
`amount`	Em centavos — `235000` é R$ 2.350,00. Obrigatório.
`description`	Uma anotação guardada com a TED e enviada ao banco junto com ela. Opcional.
`creditParty.bankCode`	O código de três dígitos (COMPE) do banco do favorecido, como `341` ou `001`.
`creditParty.branch`	A agência: 4 dígitos, sem o dígito verificador.
`creditParty.accountNumber`	O número da conta com o dígito verificador: só dígitos, no mínimo 5, sem hífen.
`creditParty.accountType`	`CACC` para conta corrente, `SVGS` para conta poupança.
`creditParty.document`	O CPF ou CNPJ do titular da conta, com dígitos verificadores válidos. A pontuação é aceita e removida.
`creditParty.name`	O nome do titular da conta.
`debitParty.personName`	Quem está fazendo a transferência do seu lado. É enviado ao banco junto com a TED.

Envie bankCode, branch e accountNumber como texto, para manter os zeros à esquerda. Use default como {walletId} para a carteira principal da organização. A TED é criada como REQUESTED e nada é enviado ainda. Os dados bancários não são verificados nesse momento — o banco os verifica quando você confirma. Guarde o _id da TED: ele é o {tedId} das próximas etapas.

{
  "_id": "6728c4e1b4d3e80012c9a5b3",
  "status": "REQUESTED",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "txnAmount": 235000,
  "txnCurrency": "986",
  "confirmedAmount": 0,
  "creditParty": {
    "_id": "6728c4e1b4d3e80012c9a5b4",
    "bankCode": "341",
    "branch": "1234",
    "accountNumber": "0045671",
    "accountType": "CACC",
    "document": "11222333000181",
    "name": "Estúdio Lumen Fotografia Ltda"
  },
  "debitParty": { "_id": "6728c4e1b4d3e80012c9a5b5", "personName": "Mariana Souza Lima" },
  "description": "Ensaio fotográfico da campanha de novembro"
}

Referência: Criar um pagamento por TED

Etapa 2: Confirmar a TED

Confirme-a com a categoria de saldo da carteira de onde o valor sai. FLEX_INTERNATIONAL é a de uso geral.

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted/{tedId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "category": "FLEX_INTERNATIONAL" }'

Uma confirmação bem-sucedida responde 200 com a TED PAID: o banco aceitou a transferência e o valor saiu da carteira. confirmedAmount, confirmedBalanceCategory e confirmedAt registram isso, external.tedId guarda o identificador da transferência no banco, e o débito aparece nas transações da carteira. Se a confirmação falhar durante o envio — a categoria de saldo não cobre o valor, um limite de transação é ultrapassado ou o banco recusa os dados do favorecido —, você recebe o erro e a TED passa a FAILED. Uma TED FAILED não pode ser confirmada de novo: crie outra. Um erro antes de qualquer envio (a verificação de permissão, ou o banco sem responder enquanto a carteira é lida) deixa a TED REQUESTED; na dúvida, leia a TED. O banco aplica os limites de transação de TED da carteira quando você confirma. Referência: Confirmar um pagamento por TED

Quando o banco de destino devolve a TED

Uma TED PAID ainda pode voltar: quando o banco de destino devolve a transferência — por exemplo, porque os dados não correspondem a uma conta aberta —, o valor é creditado de volta na carteira e a TED passa a REFUNDED, com o horário em refundedAt. Uma TED FAILED cuja confirmação expirou depois de o banco já ter recebido a transferência pode terminar REFUNDED do mesmo jeito.

Cancelar uma TED

Uma TED que ainda está REQUESTED pode ser cancelada — ela passa a CANCELLED e nada é enviado. Não envie corpo:

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted/{tedId}/cancel' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

A resposta é 204. Uma TED em qualquer outro status — inclusive uma já CANCELLED — responde 409 TED_STATUS_IS_NOT_PENDING.

Acompanhar uma TED

Leia a TED para ver o status, ou liste as TEDs de uma carteira, de uma conta, de uma organização ou do seu realm — das mais novas para as mais antigas, filtradas por status (por exemplo, ?status=PAID,REFUNDED) e paginadas com limit + next. Envie o mesmo x-environment em que você criou a TED. Não há webhook para TEDs.

Status	Significado
`REQUESTED`	Criada, ainda não enviada. Confirme-a ou cancele-a.
`PAID`	O banco aceitou a transferência e o valor saiu da carteira.
`FAILED`	A confirmação falhou. Crie outra TED.
`CANCELLED`	Cancelada antes de ser enviada.
`REFUNDED`	O banco devolveu a transferência e o valor voltou para a carteira — em geral depois de `PAID`.

Erros comuns

Os erros vêm no envelope de erro, com um code estável. Quando o banco recusa uma transferência por um motivo que não tem um código próprio nesta API, code traz o motivo do banco em minúsculas e message, a explicação do banco — ou Unknown error, quando ele não deu nenhuma. Baseie sua lógica no code, não na mensagem.

Status	`code`	Quando	O que fazer
`422`	`BAD_REQUEST`	Um campo é inválido — por exemplo, um `document` com dígitos verificadores errados ou um `bankCode` que não tem 3 dígitos. `fields` lista cada um.	Corrija a requisição.
`403`	`FORBIDDEN_WALLET`	Você não pode pagar com esta carteira.	Veja Quem pode enviar uma TED.
`404`	`TED_NOT_FOUND`	A carteira não tem uma TED com este ID neste ambiente.	Confira o `tedId` e o `x-environment`.
`409`	`TED_STATUS_IS_NOT_PENDING`	A TED não está `REQUESTED`: já foi paga, cancelada, falhou ou foi devolvida.	Leia a TED; crie outra se precisar.
`422`	`INSUFFICIENT_FUNDS`	A categoria de saldo não cobre o valor. A TED agora está `FAILED`.	Adicione saldo à carteira e crie outra TED.
`422`	`LIMIT_EXCEEDED`	O valor passa de um dos limites de TED da carteira. A TED agora está `FAILED`.	Crie outra TED dentro do limite.
`422`	`BANKING_PROVIDER_VALIDATION_ERROR`	O banco recusou um campo da transferência, como os dados do favorecido. A TED agora está `FAILED`.	Confira os dados bancários e crie outra TED.
`500` / `502` / `503` / `504`	`BANKING_PROVIDER_UNAVAILABLE`	O banco não respondeu.	Tente de novo. Se aconteceu ao confirmar, leia a TED antes: ainda `REQUESTED` quer dizer que nada foi enviado — confirme de novo; `FAILED` quer dizer que falhou durante o envio — confira o saldo e as transações da carteira antes de criar outra, porque o dinheiro ainda pode sair.

A página de referência de cada endpoint lista todos os erros que ele pode retornar.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

Fluxo

Quem pode enviar uma TED

Etapa 1: Criar a TED

Etapa 2: Confirmar a TED

Quando o banco de destino devolve a TED

Cancelar uma TED

Acompanhar uma TED

Erros comuns

Próximos passos

Enviar um pagamento Pix

Carteiras para seus clientes

​Fluxo

​Quem pode enviar uma TED

​Etapa 1: Criar a TED

​Etapa 2: Confirmar a TED

​Quando o banco de destino devolve a TED

​Cancelar uma TED

​Acompanhar uma TED

​Erros comuns

​Próximos passos

Enviar um pagamento Pix

Carteiras para seus clientes

Fluxo

Quem pode enviar uma TED

Etapa 1: Criar a TED

Etapa 2: Confirmar a TED

Quando o banco de destino devolve a TED

Cancelar uma TED

Acompanhar uma TED

Erros comuns

Próximos passos