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 debita os fundos (valor + tarifa) da 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, entre 06:30 e 17:00 (horário de Brasília).
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 por 24 horas. 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 e P2P, o plugin soma a tarifa por cima do valor da transferência, então
totalAmount = amount + feeAmount. O plugin debita a conta do remetente pelo total completo. O TED IN funciona ao contrário e desconta a tarifa do valor recebido.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 banco de destino confirma a liquidação. Status:
COMPLETED.3
Status disponível
O plugin expõe o status
COMPLETED pelas APIs de transferência e de conciliação. Ele ainda não emite transfer.completed para o TED OUT.Horário de funcionamento
Tratamento de erros
O plugin sempre mantém o dinheiro do seu cliente contabilizado quando algo dá errado:
Transferência rejeitada pelo banco de destino
Transferência rejeitada pelo banco de destino
A instituição recebedora recusa a transferência. O plugin libera na hora os fundos provisionados e devolve o valor completo, incluindo a tarifa, ao saldo do remetente. Status:
REJECTED. O plugin envia um webhook transfer.rejected.Problema temporário de rede
Problema temporário de rede
O plugin repete automaticamente, até três tentativas por padrão. 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 preserva a retenção e passa a transferência ao worker de conciliação, que a resolve contra o ledger. Se a conciliação esgota as tentativas, o plugin marca a transferência para revisão manual do operador (
MANUAL_REVIEW). O plugin nunca perde os fundos, mas a resolução pode demorar. Uma rejeição 4xx clara é diferente: ela 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. O plugin estorna o valor no seu ledger como uma transação separada. Essa devolução fica fora do ciclo de vida da transferência. O registro da transferência original continua
COMPLETED, e o plugin cria um novo registro de estorno.Cada requisição de transferência que altera dados deve incluir um header
X-Idempotency (no máximo 255 caracteres). Reutilize a mesma chave quando repetir uma requisição para evitar envios duplicados. Veja Novas tentativas e idempotência 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.
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.