Saltar al contenido principal
Las transferencias P2P (peer-to-peer) son operaciones entre cuentas que pertenecen al mismo ISPB. Como no involucran comunicación con el SPB, son procesadas instantáneamente y con menor costo operacional.

​
Cuándo usar P2P

El plugin detecta automáticamente cuando una transferencia puede ser procesada como P2P:
EscenarioTipo de transferencia
ISPB del destinatario diferente del suyoTED OUT (via SPB)
ISPB del destinatario igual al suyoP2P (interno)
La detección es transparente para el cliente de la API — el mismo endpoint es usado para ambos casos.

​
Ventajas del P2P

  • Velocidad: Liquidación en menos de 2 segundos (contra minutos del TED).
  • Costo: Sin tasas de JD SPB, tasas Lerian reducidas.
  • Disponibilidad: Funciona 24/7, sin depender del horario del BACEN.

​
Comparativo con TED OUT

AspectoTED OUTP2P
Tiempo de liquidación5-10 minutos< 2 segundos
Horario de funcionamientoLun-Vie 06:30-17:0024/7
Costo operacionalInvolucra JD SPBSolo Midaz
Dependencias externasJD Consultores, BACENNinguna

​
Cómo funciona

El flujo P2P es simplificado: 
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Iniciación    │────▶│  Detección P2P  │────▶│   Validación    │
│   (initiate)    │     │  (mismo ISPB)   │     │   destinatario  │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
┌─────────────────┐     ┌─────────────────┐              │
│   Completado    │◀────│   Transacción   │◀─────────────┘
│   (completed)   │     │   atómica Midaz │
└─────────────────┘     └─────────────────┘
  1. Iniciación: el cliente llama /v1/transfers/initiate
  2. Detección: el plugin compara el ISPB del destinatario con el ISPB de la organización
  3. Validación: el destinatario es validado en el CRM
  4. Confirmación: el cliente llama /v1/transfers/process
  5. Ejecución: una transacción atómica es creada en Midaz (débito + crédito)
  6. Conclusión: la transferencia se completa inmediatamente

​
Timeline

T+0:     POST /v1/transfers/process
         ├─ Verificar ISPB (mismo = P2P)
         ├─ Validar destinatario en CRM
         └─ Validar saldo del remitente

T+1s:    Crear transacción atómica en Midaz
         ├─ Débito de la cuenta del remitente
         └─ Crédito en la cuenta del destinatario

T+2s:    Transferencia completada
         └─ Estado: COMPLETED
SLA: < 2 segundos (vs TED OUT < 10 minutos)

​
Iniciando una transferencia P2P

El proceso es idéntico al TED OUT. El plugin detecta automáticamente que es P2P.

​
Etapa 1: Iniciar

Endpoint: POST /v1/transfers/initiate 
{
  "senderAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654",
    "accountType": "CACC",
    "holderName": "Ana Costa",
    "holderDocument": "98765432100"
  },
  "amount": 500.00,
  "description": "Transferencia interna"
}

​
Response

{
  "initiationId": "e5f6a7b8-c9d0-1234-efgh-567890123456",
  "feeAmount": 0.00,
  "totalAmount": 500.00,
  "estimatedCompletionAt": "2026-01-21T22:00:02-03:00",
  "expiresAt": "2026-01-22T22:00:00-03:00",
  "status": "PENDING_CONFIRMATION"
}
Note que el estimatedCompletionAt es prácticamente inmediato (2 segundos), indicando que será procesado como P2P.

​
Etapa 2: Confirmar

Endpoint: POST /v1/transfers/process 
{
  "initiationId": "e5f6a7b8-c9d0-1234-efgh-567890123456"
}

​
Response

{
  "transferId": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "confirmationNumber": "20260121001",
  "status": "COMPLETED",
  "feeAmount": 0.00,
  "totalAmount": 500.00
}
El estado ya retorna como COMPLETED — la transferencia es instantánea.

​
Estados del P2P

El ciclo de estados es más simple que el TED OUT: 
CREATED → PROCESSING → COMPLETED
                    → FAILED
       → CANCELLED
EstadoDescripción
CREATEDTransferencia creada
PROCESSINGEjecutando transacción en Midaz
COMPLETEDTransferencia completada
FAILEDError en Midaz (raro)
CANCELLEDCancelada antes del procesamiento
En la práctica, la transición de CREATED a COMPLETED ocurre en menos de 2 segundos.

​
Consultar transferencia P2P

Endpoint: GET /v1/transfers/ 
{
  "transferId": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "type": "P2P",
  "status": "COMPLETED",
  "sender": {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "holderName": "João Santos"
  },
  "recipient": {
    "accountId": "660e8400-e29b-41d4-a716-446655440001",
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654",
    "accountType": "CACC",
    "holderName": "Ana Costa",
    "holderDocument": "98765432100"
  },
  "amount": 500.00,
  "feeAmount": 0.00,
  "totalAmount": 500.00,
  "confirmationNumber": "20260121001",
  "createdAt": "2026-01-21T22:00:00-03:00",
  "completedAt": "2026-01-21T22:00:01-03:00",
  "statusHistory": [
    {"status": "CREATED", "timestamp": "2026-01-21T22:00:00-03:00"},
    {"status": "PROCESSING", "timestamp": "2026-01-21T22:00:00-03:00"},
    {"status": "COMPLETED", "timestamp": "2026-01-21T22:00:01-03:00"}
  ]
}
El campo type es P2P y no hay controlNumber (pues no pasó por JD SPB).

​
Tarifas P2P

Las tarifas para transferencias P2P son configuradas separadamente de las tarifas de TED:
ConfiguraciónDescripción
p2p_fee_enabledHabilita cobro de tarifa en P2P
p2p_fee_typeTipo de tarifa (fija, porcentual, escalonada)
Es común que las instituciones no cobren tarifa en transferencias internas, pero la configuración está disponible.

​
Funcionamiento 24/7

A diferencia del TED, las transferencias P2P pueden ser realizadas en cualquier momento:
  • Días hábiles: funciona normalmente
  • Fines de semana: funciona normalmente
  • Feriados: funciona normalmente
  • Madrugada: funciona normalmente
No hay validación de horario de funcionamiento para P2P, pues la operación no depende del SPB.

​
Validación del destinatario

El plugin valida al destinatario de dos formas:

​
Por datos bancarios

Si el destinatario es informado con ISPB, agencia y cuenta:
  1. Verifica si el ISPB corresponde al de la organización
  2. Busca la cuenta en el CRM por los datos bancarios
  3. Valida si el documento corresponde

​
Por accountId (optimizado)

Si ya conoce el accountId Midaz del destinatario, puede usar una validación más directa a través del CRM.

​
Tratamiento de errores

​
Destinatario no encontrado (404)

{
  "code": "BTF-0500",
  "title": "Account Not Found",
  "message": "Recipient account not found in CRM.",
  "fields": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654"
  }
}

​
Saldo insuficiente (422)

{
  "code": "BTF-2001",
  "title": "Insufficient Balance",
  "message": "Sender account does not have sufficient balance.",
  "fields": {
    "available": 300.00,
    "required": 500.00
  }
}

​
Misma cuenta de origen y destino (400)

{
  "code": "BTF-0001",
  "title": "Invalid Input",
  "message": "Sender and recipient cannot be the same account."
}

​
Casos de uso comunes

CasoDescripción
Transferencia entre usuariosCliente A transfiere a Cliente B
Movimiento entre cuentas propiasCliente mueve entre cuenta corriente y ahorro
Pago internoEmpresa paga a empleado en la misma institución
Split de pagoDistribución de valores entre múltiples cuentas

​
Atomicidad

Las transferencias P2P son atómicas en Midaz:
  • El débito y el crédito ocurren en la misma transacción
  • Si cualquier parte falla, toda la operación es revertida
  • No hay estado intermedio donde el dinero “desaparece”
Esto garantiza consistencia incluso en escenarios de falla.
Sin riesgo de duplicación: La transacción Midaz atómica elimina la necesidad de ventana de deduplicación para P2P.