Saltar al contenido principal
Las transferencias P2P mueven fondos entre cuentas dentro de tu institución al instante, las 24 horas del día. Una transferencia P2P puede llevar una comisión. Consulta Configuración de comisiones más abajo. La transferencia nunca sale de tu sistema, así que liquida de forma síncrona y no necesita la red de BACEN.

​
Cuándo usar P2P

P2P es el tipo de transferencia correcto cuando tanto el remitente como el destinatario tienen cuentas en tu institución. Los escenarios comunes incluyen:
  • Mover dinero entre las cuentas de un mismo cliente: un cliente que transfiere de su cuenta corriente a su cuenta de ahorro, o entre dos cuentas que administra.
  • Pagar a otro cliente de la misma institución: un cliente que envía dinero a un amigo, un familiar o un negocio que también opera contigo.
  • Movimientos internos de tesorería: repartir saldos entre cuentas corporativas de la misma organización.
  • División de pagos: distribuir montos entre varias cuentas para nómina, gastos compartidos o cashback.
El plugin detecta P2P de forma automática. Cuando el ISPB del destinatario coincide con el ISPB de tu institución, el plugin enruta la transferencia internamente. Cuando otro core de tu institución comparte tu ISPB, el plugin primero le pregunta a JD Courier qué core tiene la cuenta del destinatario. Consulta Transferencias entre cores. Tu integración de API es idéntica a la de TED OUT, así que no necesitas un endpoint ni una lógica aparte. Ambas cuentas deben estar en la misma organización de Midaz. Para cuentas en dos ledgers, consulta Transferencias entre ledgers.

​
Ventajas principales

​
Cómo funciona

P2P reusa la misma API que TED OUT, así tu integración se mantiene consistente entre los tipos de transferencia. El proceso tiene dos pasos desde la perspectiva del cliente: Diagrama de flujo de P2P
  1. Iniciar: el cliente envía los datos de la transferencia. El plugin valida al destinatario y calcula la comisión. El cliente ve el resumen de la transferencia antes de comprometerse.
  2. Confirmar: el cliente confirma. El plugin crea un débito + crédito atómico en Midaz. La transferencia se completa de inmediato.
El flujo de dos pasos te da un momento natural para mostrarle al cliente una pantalla de confirmación con el resumen completo de la transferencia antes de que se mueva ningún fondo.

​
Estados de la transferencia

Diagrama de la máquina de estados de P2P
El estado PENDING no aplica a las transferencias P2P. TED OUT usa PENDING mientras el plugin prepara el mensaje para JD. La retención ya existe desde CREATED. P2P liquida por completo dentro de Midaz, así que la transferencia pasa de CREATED por PROCESSING a COMPLETED. Una transferencia P2P no se puede cancelar.

​
Configuración de comisiones

El modo de comisión, MIDAZ_FEE_MODE, decide quién cobra la comisión de una transferencia P2P. Consulta Configuración de TED.

​
Validación del destinatario

El destinatario debe tener una cuenta en la misma institución. Cuando envías una transferencia, el plugin busca al destinatario en el CRM. Coteja los datos bancarios que entregas: ISPB, sucursal, cuenta y documento del titular. Si el plugin no encuentra al destinatario, rechaza la transferencia y no mueve fondos. El cliente debe revisar los datos de la cuenta e intentar de nuevo. Si las dos cuentas están en organizaciones de Midaz distintas, el plugin rechaza la transferencia con 422 BTF-0004. Rechaza dos ledgers distintos de la misma forma, a menos que el tenant permita transferencias entre ledgers.

​
Transferencias entre ledgers

Un P2P puede mover fondos entre dos ledgers de la misma organización de Midaz. Esto viene desactivado por defecto. Para activarlo para un tenant, define la política de tenant p2p.cross_ledger_enabled en true a través de la Admin API. El plugin lee este ajuste solo cuando inicias una transferencia. Una transferencia entre dos ledgers necesita todos estos elementos: El plugin registra la transferencia como un solo grupo de ledgers de Midaz: ambos ledgers se mueven, o ninguno se mueve. La transferencia guarda el ledger del pagador en ledgerId, el ledger del destinatario en recipientLedgerId y el grupo en ledgerGroupId.

​
Devolver una transferencia P2P

Puedes revertir una transferencia P2P completada con Return a Transfer. La solicitud necesita el permiso transfers:return. El ledger revierte la transacción original en la misma solicitud. La devolución es una nueva transferencia P2P que debita la cuenta que recibió la original y acredita la cuenta que la pagó. Su originalTransferId nombra la original, que sigue en COMPLETED. La respuesta es COMPLETED.
  • Una devolución necesita Midaz 4.1.3 o posterior, o 4.2.0 o posterior entre dos ledgers.
  • La cuenta que recibió la original debe tener el saldo para devolver.
  • Un P2P tiene como máximo una devolución activa, y una devolución no puede devolverse.
  • Si el resultado en el ledger es desconocido, la respuesta es 503 BTF-2000, y la devolución sigue en CREATED. Envía la misma solicitud de nuevo con una nueva clave X-Idempotency. Retoma esa devolución y nunca crea una segunda.

​
Integración técnica

P2P usa los mismos endpoints que TED OUT. No necesitas trabajo de integración extra más allá del flujo de transferencia saliente que ya construiste.
El campo type en la respuesta de la transferencia es P2P. Las transferencias P2P no tienen controlNumber, porque no pasan por JD SPB.

​
Manejo de errores

Las transferencias P2P son atómicas. Si alguna parte falla, Midaz no aplica ninguna de las dos patas. Ningún estado intermedio mueve fondos de forma parcial ni deja una cuenta con saldo insuficiente. Si una transferencia falla, el cliente mantiene el mismo saldo y puede reintentar. Si /process responde 500 BTF-9014, el dinero se movió, pero el plugin no registró la transferencia como completada. Lee la transferencia y envía de nuevo la misma solicitud /process con una nueva clave X-Idempotency. No inicies una nueva transferencia. Consulta la lista completa de errores para los códigos de error y la guía de recuperación.