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 pone una retención sobre los fondos (monto + comisión) en 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, dentro de la ventana de operación (de 06:30 a 17:00 hora de Brasília, de forma predeterminada).
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 hasta el cierre de la ventana de operación de ese día. 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, el plugin suma la comisión encima del monto de la transferencia, de modo que
totalAmount = amount + feeAmount. El plugin retiene y luego debita el total completo de la cuenta del remitente.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 STR confirma la liquidación y el plugin debita los fondos retenidos. Estado:
COMPLETED.3
Estado disponible
El plugin expone el estado
COMPLETED a través de las APIs de transferencia y de conciliación, y envía un webhook transfer.completed.Horarios de operación
Manejo de errores
Transferencia rechazada por JD o el STR
Transferencia rechazada por JD o el STR
JD o el STR rechaza la transferencia. El plugin libera la retención, así que el monto completo, incluida la comisión, vuelve al saldo disponible del remitente. Estado:
REJECTED. El plugin envía un webhook transfer.rejected.Problema temporal de red
Problema temporal de red
El plugin reintenta la llamada a JD (
jdspb.max_retries, predeterminado 3). 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 el estado PROCESSING y entrega la transferencia al worker de conciliación, que le pregunta el resultado a JD. Si la conciliación se queda sin intentos, la transferencia pasa a FAILED con la retención todavía vigente y espera a un operador (MANUAL_REVIEW).Una respuesta pendiente de JD no usa ningún intento. Después de 24 horas en conciliación, una transferencia que JD todavía responde como pendiente sigue en PROCESSING con la retención vigente y espera a un operador (MANUAL_REVIEW, motivo STR_PENDING_AGED). Un rechazo 4xx claro, en cambio, 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. La transferencia original sigue en
COMPLETED. El plugin crea una nueva transferencia de reembolso TED_IN que acredita el monto devuelto al remitente original, con originalTransferId y devolutionCode.El plugin se queda con la comisión, a menos que la política de tenant fees.refund_on_devolucao sea true (predeterminado false). Con true, el reembolso de una devolución total de una TED OUT completada también devuelve la comisión al remitente. La transferencia de reembolso mantiene el monto devuelto en amount y registra la comisión en metadata.feeRefundedAmount. Cuando el ledger no puede devolver la comisión, el plugin reembolsa solo el monto devuelto, y el reembolso lleva metadata.feeRetained con el valor true. El plugin también envía un webhook transfer_outgoing.devolution_notified.Cada solicitud de transferencia que modifica datos debe incluir un header
X-Idempotency (máximo 255 caracteres). Reusa la misma clave para repetir una solicitud cuya respuesta no recibiste. Después de un 5xx, obtén la transferencia antes de enviarla de nuevo. Consulta la guía para desarrolladores 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. No puedes cancelar la devolución de una TED IN.
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.