Cuándo usar P2P
P2P es el tipo de transferencia adecuado cuando tanto el remitente como el destinatario tienen cuentas en su institución. Los escenarios comunes incluyen:
- Mover dinero entre las propias cuentas de un cliente — un cliente que transfiere desde su cuenta corriente a su cuenta de ahorros, o entre dos cuentas que administra.
- Pagar a otro cliente de la misma institución — un cliente enviando dinero a un amigo, familiar o empresa que también opera con usted.
- Movimientos internos de tesorería — distribución de saldos entre cuentas corporativas dentro de la misma organización.
- División de pagos — distribución de montos entre múltiples cuentas para nómina, reparto de gastos o cashback.
Ventajas clave
| Aspecto | P2P | TED OUT |
|---|---|---|
| Tiempo de liquidación | Menos de 2 segundos | 5–10 minutos |
| Horario de operación | 24/7, incluyendo fines de semana y feriados | Lun–Vie, 06:30–17:00 |
| Tarifa (por defecto) | Ninguna | Configurable |
| Dependencia de BACEN | Ninguna | Requerida (JD SPB) |
Cómo funciona
P2P reutiliza la misma API que TED OUT, por lo que su integración permanece consistente entre tipos de transferencia. El proceso es de dos pasos desde la perspectiva del cliente:
- Iniciar — El cliente envía los datos de la transferencia. El plugin valida al destinatario, verifica el saldo del remitente y confirma la tarifa (típicamente R$ 0,00). El cliente ve el resumen de la transferencia antes de comprometerse.
- Confirmar — El cliente confirma. El plugin crea un débito + crédito atómico en Midaz. La transferencia se completa de inmediato — típicamente en 2 segundos.
Estados de transferencia
| Estado | Qué significa |
|---|---|
CREATED | Transferencia iniciada, esperando confirmación del cliente |
PROCESSING | Transacción atómica de Midaz en curso |
COMPLETED | Transferencia liquidada — los fondos se han movido |
FAILED | Error interno; no se movieron fondos |
CANCELLED | Cancelada por el cliente antes de la confirmación |
El estado
PENDING no aplica a las transferencias P2P. PENDING se usa en TED OUT para indicar fondos reservados mientras se espera la presentación al SPB. Las transferencias P2P se liquidan completamente dentro de Midaz, por lo que pasan directamente de PROCESSING a COMPLETED — típicamente en menos de 2 segundos.Configuración de tarifas
Las tarifas P2P están deshabilitadas por defecto. La mayoría de las instituciones ofrecen transferencias internas sin costo, pero la configuración está disponible si su modelo de precios lo requiere. Para habilitar tarifas para P2P, consulte Configuración TED.
Validación del destinatario
El destinatario debe ser una cuenta registrada dentro de la misma institución. Cuando envía una transferencia, el plugin busca al destinatario en CRM usando los datos bancarios que proporciona (ISPB, sucursal, cuenta y documento del titular). Si no se encuentra al destinatario, la transferencia se rechaza y no se mueven fondos. El cliente debe verificar los datos de la cuenta e intentarlo de nuevo.
Integración técnica
P2P usa los mismos endpoints que TED OUT. No se requiere trabajo de integración adicional más allá de lo que ya construyó para las transferencias salientes.
- Initiate Transfer — POST /v1/transfers/initiate
- Process Transfer — POST /v1/transfers/process
- Get Transfer — GET /v1/transfers/
El campo
type en la respuesta de la transferencia será P2P. Las transferencias P2P no tienen controlNumber, ya que no pasan por JD SPB.Manejo de errores
Las transferencias P2P son atómicas: el débito y el crédito se crean en una sola transacción de Midaz. Si alguna parte de la operación falla, toda la transacción se revierte. No existe un estado intermedio en el que los fondos estén parcialmente movidos o temporalmente ausentes de una cuenta. Si una transferencia falla, el saldo del cliente no cambia y puede reintentar. Consulte la lista completa de errores para conocer los códigos de error específicos y la guía de recuperación.