Cómo funciona para tu cliente
Paso 1: ingresar los datos y revisar la comisión El cliente entrega los datos bancarios del destinatario y el monto. El sistema calcula la comisión y devuelve el costo total antes de debitar nada. El cliente ve exactamente lo que va a pagar. Paso 2: confirmar y enviar Después de que el cliente confirma, el sistema debita los fondos (monto + comisión) de su cuenta. Envía la transferencia por el gateway SPB de JD hacia la red de BACEN y emite un número de confirmación de inmediato.
Requisitos previos
Antes de iniciar una transferencia:
- El remitente debe tener una cuenta registrada en el CRM.
- El saldo del remitente debe cubrir el monto de la transferencia más la comisión aplicable.
- Debes solicitar la transferencia en un día hábil, entre las 06:30 y las 17:00 (hora de Brasília).
Paso 1: iniciar la transferencia
El cliente envía los datos del destinatario y el monto. El sistema valida la solicitud, calcula la comisión y crea una intención de transferencia válida por 24 horas. El sistema no mueve fondos en esta etapa. Consulta la especificación completa de la solicitud en la referencia Initiate Transfer. Endpoint: POST /v1/transfers/initiate Respuesta (campos clave):
Dirección de la comisión (cash-out): en las transferencias TED OUT y P2P, el plugin suma la comisión encima del monto de la transferencia, de modo que
totalAmount = amount + feeAmount. El plugin debita la cuenta del remitente por el total completo. TED IN funciona al revés y descuenta la comisión del monto recibido.Paso 2: confirmar la transferencia
Después de que el cliente revisa la comisión y confirma, envía el
initiationId para procesar la transferencia. El sistema provisiona los fondos y manda el pago a la red de BACEN.
La mayoría de las integraciones procesan la transferencia solo con el initiationId. Algunos tenants firman los payloads de TED OUT fuera del plugin. Esos tenants llaman primero a POST /v1/transfers/signing/prepare. Después envían signingArtifactId, payloadHash y signature con el mismo initiationId.
Consulta la especificación completa de la solicitud en la referencia Process Transfer.
Endpoint: POST /v1/transfers/process
Respuesta (campos clave):
Cronología de liquidación
1
Enviada
El sistema provisiona los fondos y envía la transferencia a la red de BACEN. Estado:
PROCESSING.2
Liquidada
El banco de destino confirma la liquidación. Estado:
COMPLETED.3
Estado disponible
El plugin expone el estado
COMPLETED a través de las APIs de transferencia y de conciliación. Todavía no emite transfer.completed para TED OUT.Horarios de operación
Manejo de errores
El plugin siempre da cuenta del dinero de tu cliente cuando algo sale mal:
Transferencia rechazada por el banco de destino
Transferencia rechazada por el banco de destino
La institución receptora rechaza la transferencia. El plugin libera de inmediato los fondos provisionados y devuelve el monto completo, incluida la comisión, al saldo del remitente. Estado:
REJECTED. El plugin envía un webhook transfer.rejected.Problema temporal de red
Problema temporal de red
El plugin reintenta automáticamente, hasta tres intentos de forma predeterminada. Si el resultado sigue siendo desconocido después de los reintentos (un 5xx o un timeout de JD SPB), el plugin no revierte la transferencia por su cuenta. Mantiene la retención y entrega la transferencia al worker de conciliación, que la resuelve contra el ledger. Si la conciliación se queda sin intentos, el plugin marca la transferencia para revisión manual de un operador (
MANUAL_REVIEW). El plugin nunca pierde los fondos, pero la resolución puede tardar. Un rechazo 4xx claro es distinto: revierte la retención de inmediato (ver el caso de rechazo de arriba).Retorno del banco de destino
Retorno del banco de destino
El banco de destino puede devolver los fondos después de la liquidación, por ejemplo por cierre de cuenta o una retención regulatoria. El plugin revierte el monto en tu ledger como una transacción separada. Este retorno queda fuera del ciclo de vida de la transferencia. El registro de la transferencia original sigue en
COMPLETED y el plugin crea un nuevo registro de reversión.Cada solicitud de transferencia que modifica datos debe incluir un header
X-Idempotency (máximo 255 caracteres). Reusa la misma clave cuando reintentes una solicitud para evitar envíos duplicados. Consulta Reintentos e idempotencia para los detalles.Consultar el estado de la transferencia
Sigue el avance de una transferencia en cualquier momento. Endpoint: GET /v1/transfers/ Respuesta (campos clave):
Cancelar una transferencia
Puedes cancelar una transferencia mientras está en estado
CREATED o PENDING, antes de que el plugin la envíe a la red.
Endpoint: POST /v1/transfers//cancel
Códigos ISPB comunes
Última verificación: 2026-02-06. Los valores están sujetos a cambios.
Para la lista completa, consulta el directorio de ISPB en el sitio del Banco Central.