Como funciona para o seu cliente
Etapa 1 — Informar dados e revisar tarifa O cliente fornece os dados bancários do destinatário e o valor. O sistema calcula a tarifa e retorna o custo total antes de debitar qualquer valor. O cliente vê exatamente o que irá pagar. Etapa 2 — Confirmar e enviar Após a confirmação do cliente, o sistema debita os fundos (valor + tarifa) da conta. Ele submete a transferência pelo gateway SPB da JD à rede BACEN e emite um número de confirmação de imediato.
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 solicitar a transferência em dia útil, entre 06:30 e 17:00 (horário de Brasília).
Etapa 1: Iniciar a transferência
O cliente submete os dados do destinatário e o valor. O sistema valida a solicitação, calcula a tarifa e cria uma intenção de transferência válida por 24 horas. O sistema não movimenta nenhum fundo nesta etapa. Consulte a especificação completa da requisição na referência Iniciar Transferência. Endpoint: POST /v1/transfers/initiate Resposta (campos principais):
Direção da tarifa (cash-out): Para transferências TED OUT e P2P, o plugin soma a tarifa ao valor da transferência, de modo que
totalAmount = amount + feeAmount. O plugin debita a conta do remetente pelo total completo. O TED IN funciona ao contrário e deduz a tarifa do valor recebido.Etapa 2: Confirmar a transferência
Após o cliente revisar a tarifa e confirmar, submeta o
initiationId para processar a transferência. O sistema provisiona os fundos e envia o pagamento à rede BACEN.
A maioria das integrações processa a transferência apenas com o initiationId. Alguns tenants assinam payloads TED OUT fora do plugin. Esses tenants primeiro chamam POST /v1/transfers/signing/prepare. Em seguida, enviam signingArtifactId, payloadHash e signature com o mesmo initiationId.
Consulte a especificação completa da requisição na referência Processar Transferência.
Endpoint: POST /v1/transfers/process
Resposta (campos principais):
Cronograma de liquidação
1
Submetida
O sistema provisiona os fundos e envia a transferência à rede BACEN. Status:
PROCESSING.2
Liquidada
O banco destino confirma a liquidação. Status:
COMPLETED.3
Status disponível
O plugin expõe o status
COMPLETED pelas APIs de transferência e reconciliação. Ele ainda não emite transfer.completed para TED OUT.Horário de funcionamento
Tratamento de erros
O plugin sempre contabiliza o dinheiro do seu cliente quando algo dá errado:
Transferência rejeitada pelo banco destino
Transferência rejeitada pelo banco destino
A instituição recebedora recusa a transferência. O plugin libera os fundos provisionados de imediato 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 tenta novamente de forma automática, até três tentativas por padrão. Se o resultado continuar desconhecido após as tentativas — um 5xx ou um timeout da JD SPB — o plugin não reverte a transferência automaticamente. Ele preserva a retenção e entrega a transferência ao worker de reconciliação, que a resolve contra o razão. Se a reconciliação esgotar 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 levar tempo. Uma rejeição 4xx clara é diferente: ela reverte a retenção de imediato (consulte o caso de rejeição acima).Devolução do banco destino
Devolução do banco destino
O banco destino pode devolver os fundos após a liquidação, por exemplo por encerramento de conta ou uma retenção regulatória. O plugin reverte o valor no seu razão como uma transação separada. Essa devolução fica fora do ciclo de vida da transferência. O registro original permanece
COMPLETED, e o plugin cria um novo registro de reversão.Toda requisição de transferência que altere dados deve incluir um header
X-Idempotency (máximo de 255 caracteres). Reutilize a mesma chave ao tentar novamente uma requisição para evitar submissões duplicadas. Consulte Retries e idempotência para mais detalhes.Consultar status da transferência
Acompanhe o progresso 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 estiver no status
CREATED ou PENDING, antes de o plugin submetê-la à rede.
Endpoint: POST /v1/transfers//cancel
Códigos ISPB comuns
Última verificação: 2026-02-06. Os valores estão sujeitos a alterações.
Para uma lista completa, consulte o diretório ISPB no site do Banco Central.