TED por um parceiro

Envie, receba e devolva TED por uma interface de parceiro.

Envie, receba e devolva TED quando um parceiro conecta sua instituição ao STR.

Esta página sugere uma forma de ler os manuais do BACEN para a TED. A documentação do parceiro e os manuais prevalecem sobre esta página. Sua instituição, como participante, valida o fluxo e o implementa sobre as APIs da Lerian. Veja como ler os diagramas.

​

TED pela JD

---

​

Participantes

• Sua instituição. Chama a API do TED JD e lê o resultado de cada TED.
• TED JD. A interface de conectividade entre o Midaz e a JD. Ele lança cada TED no Midaz e troca as mensagens da TED com a JD.
• Midaz. O ledger que guarda as contas dos seus clientes.
• STR. O Sistema de Transferência de Reservas do BACEN. Liquida cada TED.
• JD. O parceiro que troca as mensagens da TED com o STR.
• Outra instituição. A instituição na outra ponta de uma TED que sua instituição recebe ou que volta.

​

Antes de começar

• O TED JD está configurado para sua instituição. Veja Configuração.
• A conta que envia, recebe ou devolve a TED existe no Midaz e tem um titular.
• Onde a entrega de webhooks está ligada no seu deploy, registre seu endpoint com POST /v1/webhooks. GET /v1/webhooks/event-types lista os eventos que você pode assinar.
• Para devolver uma TED recebida, cada rota de operação do crédito da TED no Midaz tem o operationType bidirectional. Veja Rotas Contábeis.

​

Enviar uma TED pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	TED JD	API da Lerian	POST /v1/transfers/initiate	Envie a conta pagadora em senderAccountId, o recipient, o purpose e o amount. Envie os cabeçalhos X-Organization-Id e X-Idempotency.
2	TED JD	Midaz	Chamada interna		O TED JD lê a conta pagadora e o titular dela no Midaz.
3	TED JD	Sua instituição	API da Lerian	Resposta ao passo 1	O TED JD responde 200 com o initiationId, o feeAmount, o totalAmount e o expiresAt. Nada se moveu ainda.
4	Sua instituição	TED JD	API da Lerian	POST /v1/transfers/process	Envie o initiationId antes do expiresAt. Envie os cabeçalhos X-Organization-Id e X-Idempotency.
5	TED JD	Midaz	Chamada interna		O TED JD reserva o totalAmount na conta pagadora com uma transação pendente. O amount vai para a conta externa.
6	TED JD	JD	API da JD		O TED JD envia a TED à JD.
7	TED JD	Sua instituição	API da Lerian	Resposta ao passo 4	O TED JD responde 200 com a TED em PROCESSING. Guarde o transferId dela.
8	JD	STR	Entre outras partes		A JD envia a TED ao STR.
9	STR	JD	Entre outras partes		O STR liquida ou rejeita a TED.
10	TED JD	JD	API da JD		O TED JD consulta o resultado na JD.
11	TED JD	Midaz	Chamada interna		Para uma TED liquidada, o TED JD confirma a transação pendente. Para uma TED rejeitada, ele cancela a transação pendente e libera o valor.
12	TED JD	Sua instituição	Webhook	Webhook transfer.completed ou transfer.rejected	A TED fica COMPLETED, ou REJECTED para uma TED rejeitada.
13	Sua instituição	TED JD	API da Lerian	GET /v1/transfers/{transferId}	Consulte a TED com o transferId do passo 7.
14	TED JD	Sua instituição	API da Lerian	Resposta ao passo 13	O TED JD responde com a TED e o status dela.

​

Receber uma TED pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Outra instituição	STR	Entre outras partes		A instituição pagadora envia uma TED para uma das suas contas.
2	STR	JD	Entre outras partes		O STR liquida a TED e a envia à JD.
3	TED JD	JD	API da JD		O TED JD consulta as mensagens novas na JD.
4	JD	TED JD	Resposta		A JD responde com a TED recebida.
5	TED JD	Midaz	Chamada interna		O TED JD encontra a conta recebedora no Midaz pela agência, número da conta, tipo de conta e documento do recebedor.
6	TED JD	Midaz	Chamada interna		O TED JD credita a conta recebedora em uma transação. A transação debita a conta externa.
7	TED JD	Sua instituição	Webhook	Webhook transfer_incoming.completed	A TED recebida fica COMPLETED. O evento traz o transferId dela.
8	Sua instituição	TED JD	API da Lerian	GET /v1/transfers/{transferId}	Consulte a TED recebida. Sem o evento, encontre-a com GET /v1/transfers.
9	TED JD	Sua instituição	API da Lerian	Resposta ao passo 8	A TED recebida está em COMPLETED.

​

Uma TED enviada volta pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Outra instituição	STR	Entre outras partes		A instituição que recebeu sua TED a devolve.
2	STR	JD	Entre outras partes		O STR liquida a devolução e a envia à JD.
3	TED JD	JD	API da JD		O TED JD consulta as mensagens novas na JD.
4	JD	TED JD	Resposta		A JD responde com a devolução da sua TED.
5	TED JD	Sua instituição	Webhook	Webhook transfer_outgoing.devolution_notified	O evento indica a TED que você enviou, o código de devolução em codDevTransf e o amount.
6	TED JD	Midaz	Chamada interna		O TED JD credita a conta pagadora com o valor devolvido. A transação debita a conta externa.
7	TED JD	Sua instituição	Webhook	Webhook transfer_incoming.completed	O crédito fica COMPLETED.
8	Sua instituição	TED JD	API da Lerian	GET /v1/transfers/{transferId}	Consulte a TED que você enviou.
9	TED JD	Sua instituição	API da Lerian	Resposta ao passo 8	A TED que você enviou continua em COMPLETED e mostra o código de devolução em devolutionCode.

​

Devolver uma TED recebida pela JD

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	TED JD	API da Lerian	POST /v1/transfers/{transferId}/return	Envie o transferId da TED recebida no caminho. Envie os cabeçalhos X-Organization-Id e X-Idempotency. Quando uma aplicação chama, envie também o externalReference no corpo.
2	TED JD	Midaz	Chamada interna		O TED JD lê no Midaz o crédito da TED recebida e as rotas de operação dele. Ele confere se o crédito pode ser revertido.
3	TED JD	Midaz	Chamada interna		O TED JD reserva o valor creditado com uma transação pendente. Ela debita a conta que recebeu a TED e credita a conta externa.
4	TED JD	Sua instituição	Webhook	Webhook transfer_incoming.return_requested	O TED JD começou a devolução.
5	TED JD	JD	API da JD		O TED JD envia à JD a devolução do valor total, com o código de devolução 70.
6	TED JD	Sua instituição	API da Lerian	Resposta ao passo 1	O TED JD responde 201 com a devolução em PROCESSING. Guarde o transferId dela.
7	JD	STR	Entre outras partes		A JD envia a devolução ao STR.
8	STR	JD	Entre outras partes		O STR liquida ou rejeita a devolução.
9	TED JD	JD	API da JD		O TED JD consulta o resultado na JD.
10	TED JD	Midaz	Chamada interna		Para uma devolução liquidada, o TED JD cancela a transação pendente. Depois, ele reverte o crédito da TED recebida em uma transação nova. Para uma devolução rejeitada, ele só cancela a transação pendente.
11	TED JD	Sua instituição	Webhook	Webhook transfer_incoming.returned ou transfer_incoming.return_rejected	A devolução fica COMPLETED, ou REJECTED para uma devolução rejeitada.
12	Sua instituição	TED JD	API da Lerian	GET /v1/transfers/{transferId}	Consulte a devolução com o transferId do passo 6.
13	TED JD	Sua instituição	API da Lerian	Resposta ao passo 12	O TED JD responde com a devolução e o status dela.

​

Regras para a JD

​

Enviar uma TED

• O TED JD envia uma TED por iniciação. Quando você confirma o mesmo initiationId de novo, o TED JD não envia uma segunda TED.
• A reserva no Midaz não é a liquidação.

​

Receber uma TED

• Quando a JD entrega a mesma TED de novo, o TED JD não a credita de novo.

​

Uma TED enviada volta

• O crédito é uma nova transferência recebida, com um transferId próprio. O originalTransferId dela indica a TED que você enviou.
• Onde a configuração da sua instituição a liga, uma devolução do valor total também pode devolver a tarifa da TED que você enviou.

​

Devolver uma TED recebida

• A devolução envia de volta o valor total da TED recebida.
• A devolução é uma nova transferência de type TED_OUT, com um transferId próprio. A TED recebida continua em COMPLETED.

​

Como saber que terminou na JD

• Enviar uma TED. O webhook transfer.completed ou transfer.rejected informa o status final. Depois de uma conciliação, o webhook transfer.reconciliation_resolved ou transfer.reconciliation_failed informa o status, e a TED também pode terminar em FAILED. GET /v1/transfers/{transferId} mostra o status.
• Receber uma TED. O webhook transfer_incoming.completed informa o crédito. GET /v1/transfers/{transferId} mostra a TED recebida em COMPLETED.
• Uma TED enviada volta. O webhook transfer_outgoing.devolution_notified informa a devolução, e transfer_incoming.completed informa o crédito. GET /v1/transfers/{transferId} mostra a TED que você enviou com um devolutionCode.
• Devolver uma TED recebida. O webhook transfer_incoming.returned ou transfer_incoming.return_rejected informa o status final. GET /v1/transfers/{transferId} com o transferId da devolução mostra COMPLETED ou REJECTED.

​

O que pode dar errado na JD

​

Enviar uma TED

Situação	O que você vê	O que fazer
A janela de operação da TED está fechada.	422, código BTF-0010.	Nada se moveu. Envie a TED quando a janela estiver aberta.
A iniciação expirou.	O passo 4 responde 410, código BTF-0202.	Nada se moveu. Comece uma TED nova.
A conta pagadora não tem o saldo.	O passo 4 responde 422, código BTF-2003.	Nada se moveu. Adicione fundos e comece uma TED nova.
A JD recusa a TED.	O passo 4 responde 422, código BTF-1001, com o código da JD em upstream.code.	O TED JD liberou o valor reservado. A TED está em REJECTED. Confira os dados do recebedor e comece uma TED nova.
A JD não responde.	O passo 4 responde 503, código BTF-1000 ou BTF-1003, com o transferId.	Não envie uma TED nova. O TED JD mantém a reserva e pergunta o resultado à JD. Consulte a TED mais tarde.
A JD não recebeu a TED, ou informa um erro para ela.	O webhook transfer.reconciliation_resolved ou transfer.reconciliation_failed. A TED está em FAILED, com reconciliationStatus RESOLVED.	O TED JD liberou o valor reservado. Comece uma TED nova.
A resposta ao passo 4 não chega.	Nenhuma resposta, ou um timeout.	Envie o passo 4 de novo com o mesmo initiationId e a mesma chave X-Idempotency.
O TED JD não consegue saber o resultado pela JD.	A TED mostra reconciliationStatus MANUAL_REVIEW, e o valor continua reservado. A TED está em PROCESSING, ou em FAILED quando o TED JD esgotou as tentativas. O webhook transfer.reconciliation_exhausted informa o caso FAILED e alguns casos PROCESSING.	Confirme o resultado com a JD. Quando a JD responder liquidada, resolva a TED com POST /v1/transfers/{transferId}/reconciliation/resolve e SETTLE, que conclui a TED. Quando a JD responder recusada, resolva com REVERT, que libera o valor reservado. Quando a JD responder pendente ou não encontrada, devolva uma TED em PROCESSING para a conciliação com POST /v1/transfers/{transferId}/reconciliation/retry. O TED JD consulta a JD de novo, e a reserva continua.
Você quer parar uma TED que o TED JD ainda não enviou.	A TED está em CREATED ou PENDING.	Cancele-a com POST /v1/transfers/{transferId}/cancel. O TED JD cancela a TED e libera qualquer valor reservado.

​

Receber uma TED

Situação	O que você vê	O que fazer
O TED JD não consegue creditar a TED recebida.	O webhook transfer_incoming.undeliverable.	O TED JD devolve a TED à instituição pagadora, ou a guarda para a sua análise. Encontre-a com GET /v1/transfers/ted-in/undeliverables.

​

Devolver uma TED recebida

Situação	O que você vê	O que fazer
A TED não pode ser devolvida.	422, código BTF-0118.	Nada foi criado. Confira o transferId.
A TED recebida já tem uma devolução.	409, código BTF-0119. O transferId indica essa devolução.	Consulte essa devolução.
A janela de operação da TED está fechada.	422, código BTF-0010.	Nada foi criado. Peça de novo quando a janela estiver aberta.
O Midaz não pode reverter o crédito da TED recebida.	422, código BTF-0120. O reason diz o motivo.	Nada foi reservado nem enviado. route_not_reversible quer dizer que o roteamento do crédito da TED no Midaz não permite uma reversão.
O Midaz recusa a reserva.	422, código BTF-0121, com o reason insufficient_balance ou prior_reservation_pending.	Nada foi enviado. Com insufficient_balance, peça de novo quando a conta tiver o valor creditado. Com prior_reservation_pending, peça de novo mais tarde. Use uma chave X-Idempotency nova.
O TED JD não consegue concluir o pedido.	503, código BTF-2000. Quando a devolução existe, o transferId indica essa devolução.	Nada foi enviado. O TED JD encerra essa devolução e libera qualquer valor reservado. Depois, peça de novo com uma chave X-Idempotency nova.
A JD recusa a devolução.	422, código BTF-1001, com o código da JD em upstream.code.	O TED JD libera o valor reservado, e a devolução termina em REJECTED.
O TED JD não tem certeza de que a JD recebeu a devolução.	O passo 6 traz reconciliationStatus AWAITING.	O TED JD pergunta o resultado à JD. Consulte a devolução mais tarde.
O TED JD separa a devolução para uma decisão manual.	O webhook transfer_incoming.return_manual_review.	Consulte a devolução. O reconciliationReasonCode dela diz o motivo. Depois, resolva a devolução com POST /v1/transfers/{transferId}/reconciliation/resolve.
A resposta ao passo 1 não chega.	Nenhuma resposta, ou um timeout.	Envie a mesma chamada de novo com a mesma chave X-Idempotency.

​

Relacionados

---

• Enviar e receber TED: as mesmas jornadas no Lerian SPB nativo.
• Cancelar ou devolver uma TED: a devolução no Lerian SPB nativo.
• Enviar (TED OUT)
• Receber (TED IN)
• Webhooks
• Guia do desenvolvedor