Enviar e receber TED

Envie uma TED de uma conta do Midaz ou do seu próprio core, e receba uma TED em uma conta do Midaz, pelo TED Lerian e pelo Lerian SPB.

Envie uma TED de uma conta de cliente no Midaz ou do seu próprio core, e receba uma TED para os seus clientes.

Os manuais do BACEN para o STR prevalecem sobre esta página. Sua instituição valida o fluxo e o implementa sobre as APIs da Lerian. Veja como ler os diagramas.

​

Participantes

---

• Sua instituição. O seu sistema. Ele envia as TEDs, consulta as TEDs e recebe os eventos.
• TED Lerian. A interface de TED entre o Midaz e o Lerian SPB. Ele confere cada TED, movimenta o dinheiro no Midaz e publica os eventos. O Streaming Hub entrega os eventos ao seu sistema.
• Midaz. O ledger. Ele guarda as contas dos clientes e os seus saldos.
• Lerian SPB. A mensageria da Lerian para o STR. Ele envia e recebe as mensagens do STR e informa a liquidação delas.
• STR (BACEN). O Sistema de Transferência de Reservas do BACEN. Ele liquida cada TED entre as contas Reservas Bancárias.
• Instituição remetente. Outra instituição. Ela envia uma TED para um cliente seu.

​

Antes de começar

---

• Defina os seus limites de uso com PUT /v1/policy/limits.
• Carregue o calendário nacional de feriados de cada ano com PUT /v1/policy/holidays, antes de o ano começar. Um ano carregado cobre todas as datas dele. Em uma data cujo ano não está carregado, o TED Lerian recusa a TED.
• Opcionalmente, defina o seu cut-off com PUT /v1/policy/window. Ele não pode ser posterior ao fechamento oficial.
• Para cobrar uma tarifa, crie no ledger um pacote de tarifas do Midaz que selecione pelos rótulos de lançamento do TED Lerian.
• Para receber TEDs, vincule o seu ISPB à organização e ao ledger do Midaz que recebem os créditos, com PUT /v1/policy/ispb-bindings. O vínculo precisa da organização no Midaz, da conta @external/BRL no ledger e do titular da sua instituição com uma conta no CRM.
• Cada conta que recebe TEDs tem um titular e um instrumento no Midaz, com a agência, o número e o tipo da conta em bankingDetails. Veja Cadastrar um titular e abrir uma conta.

​

Diagrama

---

​

Enviar de uma conta do Midaz

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	TED Lerian	Chamada de API	POST /v1/transfers/fee-quotes	Opcional. Envie o recebedor, o valor e o código de finalidade. O header X-Account-Id indica a conta de origem.
2	TED Lerian	Sua instituição	Resposta da API	Resposta ao passo 1	200 com a estimativa de tarifa em feeAmount, totalAmount, windowOpen e nextWindowOpensAt. A cotação não movimenta dinheiro.
3	Sua instituição	TED Lerian	Chamada de API	POST /v1/transfers	Envie a TED com recipient, amount, purposeCode e, opcionalmente, clientReference. Envie a conta de origem em X-Account-Id e uma chave em X-Idempotency.
4	TED Lerian	TED Lerian	Etapa interna		O TED Lerian confere o código de finalidade, o documento do recebedor, o banco do recebedor na lista de participantes do STR, a janela e os seus limites de uso.
5	TED Lerian	Midaz	Chamada interna	POST /v2/transactions/hold	O TED Lerian cria uma transação pendente pelo valor, marcada como ted_sent. O Midaz soma a tarifa que os seus pacotes de tarifas aplicam e retém o valor mais a tarifa na conta de origem. A transferência fica em RESERVED.
6	TED Lerian	Lerian SPB	Chamada interna	POST /v1/str/operations/bank-transfers	O TED Lerian envia a TED ao Lerian SPB, com o remetente e o recebedor como clientes.
7	TED Lerian	Sua instituição	Resposta da API	Resposta ao passo 3	201 com a transferência em SUBMITTED.
8	Lerian SPB	STR (BACEN)	STR0008		O Lerian SPB envia ao STR a TED entre dois clientes.
9	STR (BACEN)	Lerian SPB	STR0008R1		O STR liquida a TED e responde.
10	Lerian SPB	TED Lerian	Evento		O Lerian SPB informa a liquidação com settlement.settled.
11	TED Lerian	Sua instituição	Evento	Evento transfer.settled	A transferência fica em SETTLED.
12	TED Lerian	Midaz	Chamada interna	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit	O TED Lerian confirma a transação pendente. O valor retido vai para @external/BRL, e a tarifa vai para a conta que o seu pacote de tarifas credita.

​

Enviar do seu próprio core

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Lerian SPB	Chamada de API	POST /v1/str/operations/bank-transfers	Envie sender e recipient com party igual a client, o amount e o purposeCode. Envie uma chave em X-Idempotency.
2	Lerian SPB	Sua instituição	Resposta da API	Resposta ao passo 1	201 com a operação. O Lerian SPB aceitou a TED para envio.
3	Lerian SPB	STR (BACEN)	STR0008		O Lerian SPB envia ao STR a TED entre dois clientes.
4	STR (BACEN)	Lerian SPB	STR0008R1		O STR liquida a TED e responde.
5	Lerian SPB	Sua instituição	Evento	Evento settlement.settled	O Lerian SPB informa a posição final da operação.
6	Sua instituição	Sua instituição	Etapa interna		Lance o débito no seu core.

​

Receber e creditar

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Instituição remetente	STR (BACEN)	STR0008		Outra instituição envia uma TED para um cliente seu.
2	STR (BACEN)	Lerian SPB	STR0008R2		O STR liquida a TED e informa o crédito à sua instituição.
3	Lerian SPB	TED Lerian	Evento		O Lerian SPB repassa o crédito ao TED Lerian com str.operation.received.
4	TED Lerian	Sua instituição	Evento	Evento incoming_transfer.received	O TED Lerian registra a TED como RECEIVED. Nada foi creditado ainda.
5	TED Lerian	Midaz	Chamada interna	GET /v2/organizations/{organization_id}/instruments	O TED Lerian procura a conta na agência e no número da conta do recebedor. Ele procura na organização à qual o seu ISPB está vinculado.
6	Midaz	TED Lerian	Chamada interna		O Midaz devolve a conta, o documento do titular e a data de encerramento, se houver.
7	TED Lerian	TED Lerian	Etapa interna		O TED Lerian confere se a conta está aberta, se o documento do titular corresponde à TED e se o tipo de conta na TED é o tipo da conta.
8	TED Lerian	Midaz	Chamada interna	POST /v2/transactions/direct	O TED Lerian lança uma transação, marcada como ted_received. Ela debita @external/BRL e credita a conta do cliente. Quando o seu pacote de tarifas deduz uma tarifa do crédito, o cliente recebe o valor menos a tarifa.
9	TED Lerian	Sua instituição	Evento	Evento incoming_transfer.credited	A TED fica em CREDITED, com creditedAmount e feeAmount.

​

Devolver quando a conta não pode receber

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Instituição remetente	STR (BACEN)	STR0008		Outra instituição envia uma TED para um cliente seu.
2	STR (BACEN)	Lerian SPB	STR0008R2		O STR liquida a TED e informa o crédito à sua instituição.
3	Lerian SPB	TED Lerian	Evento		O Lerian SPB repassa o crédito ao TED Lerian com str.operation.received.
4	TED Lerian	Sua instituição	Evento	Evento incoming_transfer.received	O TED Lerian registra a TED como RECEIVED.
5	TED Lerian	Midaz	Chamada interna	GET /v2/organizations/{organization_id}/instruments	O TED Lerian procura a conta na agência e no número da conta do recebedor.
6	Midaz	TED Lerian	Chamada interna		O Midaz não encontra conta ali, ou devolve uma conta que não pode receber a TED.
7	TED Lerian	TED Lerian	Etapa interna		O TED Lerian decide devolver a TED com o motivo oficial.
8	TED Lerian	Sua instituição	Evento	Evento incoming_return.requested	O TED Lerian registra a devolução antes de enviá-la. A TED fica em RETURN_REQUESTED.
9	TED Lerian	Lerian SPB	Chamada interna	POST /v1/str/operations/bank-transfers/{operationId}/returns	O TED Lerian pede ao Lerian SPB que devolva a TED com o motivo.
10	Lerian SPB	STR (BACEN)	STR0010		O Lerian SPB envia a devolução ao STR.
11	STR (BACEN)	Lerian SPB	STR0010R1		O STR liquida a devolução e responde.
12	Lerian SPB	TED Lerian	Evento		O Lerian SPB informa a liquidação da devolução com settlement.settled.
13	TED Lerian	Sua instituição	Evento	Evento incoming_return.returned	A TED fica em RETURNED. O dinheiro voltou para a instituição remetente, e nenhum saldo mudou no Midaz.

​

Receber em uma conta da sua instituição

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Instituição remetente	STR (BACEN)	STR0008		Outra instituição envia uma TED para uma conta que a sua instituição detém.
2	STR (BACEN)	Lerian SPB	STR0008R2		O STR liquida a TED e informa o crédito à sua instituição.
3	Lerian SPB	TED Lerian	Evento		O Lerian SPB repassa o crédito ao TED Lerian com str.operation.received.
4	TED Lerian	Sua instituição	Evento	Evento incoming_transfer.received	O TED Lerian registra a TED como RECEIVED.
5	TED Lerian	Midaz	Chamada interna	GET /v2/organizations/{organization_id}/instruments	O TED Lerian procura a conta na agência e no número da conta do recebedor.
6	Midaz	TED Lerian	Chamada interna		O Midaz devolve a conta. O documento do titular é o CNPJ da sua organização no Midaz.
7	TED Lerian	TED Lerian	Etapa interna		O TED Lerian registra a TED e não credita nada no Midaz.
8	TED Lerian	Sua instituição	Evento	Evento incoming_transfer.recorded	A TED fica em RECORDED, com kind igual a INSTITUTION.

​

Regras

---

• Aceita não é liquidada. Um 201 com SUBMITTED significa que o Lerian SPB aceitou a TED para envio. O dinheiro retido só sai da conta de origem depois que o STR liquida a TED.
• Os limites de uso contam o valor mais a tarifa. Uma TED rejeitada ou cancelada libera os limites de novo.
• Quando o banco do recebedor é o seu próprio ISPB, a transferência é interna (type igual a INTERNAL). O Midaz a liquida, e nada vai para o STR.
• Do seu próprio core, defina party no remetente e no recebedor. Sem ele, a parte é institution, e o Lerian SPB envia outra mensagem do STR.
• O TED Lerian credita uma TED recebida uma vez, também quando o Lerian SPB a entrega duas vezes.
• Quando a conta não pode receber uma TED, o TED Lerian a devolve com o motivo oficial:
  • 1: uma conta encerrada.
  • 2: nenhuma conta nessa agência e nesse número.
  • 5: o documento do titular não corresponde.
  • 84: o tipo de conta na TED não é o tipo da conta.
• Uma conta é considerada encerrada quando a sua data de encerramento é hoje ou anterior, no horário de Brasília.
• Quando o TED Lerian não consegue decidir sozinho, por exemplo quando o seu ISPB não tem vínculo, a TED vai para MANUAL_REVIEW.

​

Como saber que terminou

---

• Envio. O evento transfer.settled, ou GET /v1/transfers/{transferId} com status igual a SETTLED. Do seu próprio core, o evento settlement.settled da operação.
• Recebimento. O evento incoming_transfer.credited, incoming_return.returned ou incoming_transfer.recorded, ou GET /v1/incoming-transfers/{incomingTransferId} com status igual a CREDITED, RETURNED ou RECORDED.

​

O que pode dar errado

---

Situação	O que você vê	O que fazer
Fora da grade oficial ou depois do seu cut-off	422 com TED-0020	Nada é reservado. Envie a TED na próxima janela. GET /v1/policy/window mostra a janela.
Um fim de semana ou um feriado	422 com TED-0021	Nada é reservado. Envie a TED no próximo dia útil.
O TED Lerian não consegue determinar a janela	503 com TED-0022	Nada é reservado. Se o calendário de feriados daquele ano não está carregado, carregue-o. Depois envie a TED de novo.
Seus limites de uso não estão definidos	503 com TED-0080	Defina os limites com PUT /v1/policy/limits.
Um limite de uso foi excedido	422 com TED-0030	Nada é reservado. Reduza o valor, ou espere o próximo dia ou mês.
A estimativa de tarifa não está disponível	503 com TED-0040	Nada é reservado. Envie a TED de novo mais tarde.
A conta de origem não consegue pagar o valor mais a tarifa	201 com REJECTED e rejection.code igual a TED-0031	Nada é reservado. Ajuste o valor.
O Lerian SPB ou o STR recusa a TED	REJECTED na resposta, ou depois com transfer.rejected	O TED Lerian libera a reserva. Leia rejection, corrija os dados e envie uma nova TED com uma nova chave.
O Midaz ou o Lerian SPB não responde ao TED Lerian a tempo	201 com AWAITING_RECONCILIATION, ou transfer.awaiting_reconciliation	Não envie a TED de novo. Se a transferência ficar em EXHAUSTED, um operador a destrava com a evidência do STR por POST /v1/transfers/{transferId}/unblock.
A sua requisição fica sem resposta	Um timeout	Não presuma que a TED falhou. Envie a mesma requisição com a mesma chave X-Idempotency. A mesma chave nunca cria uma segunda transferência. Antes de usar uma nova chave, procure a transferência com GET /v1/transfers filtrada por client_reference.
A instituição recebedora devolve uma TED que você enviou	transfer.returned	O TED Lerian credita o valor de volta na conta de origem. A transferência continua SETTLED.
Do seu próprio core, o STR não liquida a TED	settlement.failed	A TED não foi liquidada. Não lance o débito.
Uma TED recebida aguarda uma decisão	incoming_transfer.manual_review	Leia o reviewReason da TED recebida. Depois credite a TED, devolva-a ou confirme o crédito dela com POST /v1/incoming-transfers/{incomingTransferId}/resolve-review. Decida antes de slaDeadlineAt.
O STR recusa uma devolução automática	incoming_return.failed	A TED vai para MANUAL_REVIEW. Decida com POST /v1/incoming-transfers/{incomingTransferId}/resolve-review.

A lista de erros do TED Lerian descreve cada código.

​

Relacionados

---

• Cancelar ou devolver uma TED
• Reservar um valor e depois confirmar ou cancelar
• Como o TED Lerian funciona
• Eventos do TED Lerian
• Eventos e integração com o ledger do Lerian SPB