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. Endpoint: POST /v1/transfers/initiate Resposta (campos principais):
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.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.
Endpoint: POST /v1/transfers/process
Resposta (campos principais):
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.Horário de funcionamento
Tratamento de erros
Transferência rejeitada pela JD ou pelo STR
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.Problema temporário de rede
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).Devolução do banco de destino
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.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 para os detalhes.Consultar o status da transferência
Acompanhe o andamento de uma transferência a qualquer momento. Endpoint: GET /v1/transfers/ Resposta (campos principais):
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.
Endpoint: POST /v1/transfers//cancel
Códigos ISPB comuns
Última verificação: 2026-02-06. Os valores podem mudar.
Para a lista completa, consulte o diretório de ISPB no site do Banco Central.