Integración C2P y Conciliación

Diseño de cómo Caudal procesa cobros por Pago Móvil C2P y cómo concilia que el dinero efectivamente llegó a la cuenta destino, según el modelo de negocio.

1 Modelos de liquidación (la decisión madre)

El "tipo de negocio establecido" se reduce a dónde aterriza el dinero. De esto depende el riesgo regulatorio, el onboarding y el método de conciliación.

2 Flujo de cobro C2P

C2P permite que el comercio inicie el cobro debitando la cuenta del cliente, quien lo autoriza con una clave/OTP de un solo uso generada desde su banco (vigencia 3–6 h).

Ejemplo de API

# 1) Crear el cobro
POST /v1/cobros
{ "monto": 2000, "moneda": "USD", "metodo": "c2p", "descripcion": "Pedido #1042" }

# 2) Confirmar con los datos C2P + clave del cliente
POST /v1/cobros/cob_3Nk8x/confirmar
{ "banco_cliente": "0105", "cedula": "V12345678",
  "telefono": "04141234567", "token": "8842" }

# Respuesta
{ "id": "cob_3Nk8x", "estado": "pagado",
  "monto_bs": 730000, "tasa": 36.50, "id_bancario": "REF-99812" }

3 Capa de adaptadores

Cada banco expone su API distinto, pero el resto del sistema ve un solo contrato. El adaptador encapsula autenticación, formato y particularidades de cada banco.

Contrato común

interface AdaptadorBancario {
  codigo: string;  // "mercantil" | "bancaribe" | ...
  iniciarCobroC2P(input: CobroC2PInput): Promise<ResultadoCobro>;
  consultarEstado(idBancario: string): Promise<EstadoCobro>;
  obtenerConciliacion(fecha: string): Promise<RegistroConciliacion[]>;
}

4 Idempotencia y estados

• Idempotencia obligatoria (header Idempotency-Key) en la confirmación. La clave C2P es de un solo uso: un reintento ciego podría fallar o generar doble débito. Garantiza "exactamente una vez".
• Montos en centavos y conversión USD→Bs registrada con la tasa exacta del momento (auditable).
• Rechazos/reversos: la Gaceta fija Bs. 2 por operación rechazada o reversada; modelarlo como costo.

Máquina de estados del cobro

El estado pendiente existe para no perder cobros ante timeouts: se resuelven en la capa de conciliación.

5 Conciliación en 3 capas

Conciliar = verificar que lo que creemos cobrado coincide con lo que el banco realmente movió. No nos fiamos de una sola fuente: tres capas, de la más rápida a la más confiable.

6 Cruce de 3 vías (Capa 3)

Cada día cruzamos tres fuentes usando como llaves: referencia bancaria + monto + fecha + cédula/teléfono.

7 Validación según el modelo

Aquí se responde "validar que el dinero llegue a nuestras cuentas o la del cliente":

8 Excepciones y operación

• Worker de conciliación programado (cron): corre el cruce diario y genera un reporte por comercio.
• Bandeja de excepciones en el dashboard para desajustes que requieren intervención humana (huérfanos, montos distintos, no abonados).
• Timing / float: distinguir abono en línea vs. por lote (al cierre del día); afecta cuándo un pago es firme y, en Modelo B, cuándo se puede liquidar al comercio.
• Reversos: registrar y conciliar reversos/devoluciones; reflejar el costo de Bs. 2.
• Alertas: notificar si el % de desajustes supera un umbral (posible incidencia en la API del banco).

9 Checklist de desarrollo

• Definir el modelo de liquidación inicial (recomendado: A) y el manejo de credenciales por comercio.
• Implementar el contrato AdaptadorBancario + primer adaptador (Bancaribe o Mercantil) en sandbox.
• Servicio de Cobros con máquina de estados e idempotencia.
• Conversión USD→Bs con tasa configurable y registro auditable.
• Webhooks firmados (HMAC) con reintentos exponenciales.
• Worker de conciliación: ingestión del archivo de liquidación + cruce de 3 vías.
• Integración de consulta de movimientos/saldo para validación "dura" (donde el banco lo permita).
• Bandeja de excepciones y reporte de conciliación por comercio en el dashboard.
• (Modelo B) Módulo de payouts + segundo libro conciliado + lógica de comisión/float.