Una respuesta API puede indicar que una solicitud fue aceptada. Un webhook puede notificar un estado. Ninguno demuestra por sí solo que el receptor obtuvo el importe, el pedido avanzó, el ledger balanceó y contabilidad recibió el asiento correcto. Los sistemas confiables conservan evidencia en cada capa.
Pix funciona continuamente, pero la aplicación observa creación del cobro, consentimiento, autorización, instrucción, liquidación, crédito, notificación, asiento interno, liberación del pedido, devolución y cierre. Open Finance añade recursos de consentimiento y pago con estados propios.
No reduzcas todo a un booleano pagado. Cada transición necesita fuente, ID, event time, receive time, importe, estado, razón y confianza. El negocio define qué evidencia libera inventario, activa servicio, habilita retiro, devuelve o reconoce ingreso.
Crear un cobro o recurso registra una oportunidad, no movimiento de dinero. La autorización confirma intención bajo un consentimiento. La liquidación completa la transferencia. El crédito y la disponibilidad se observan por API, extracto o archivo del PSP.
El webhook reduce latencia, pero es solo un canal de evidencia. Autentícalo, almacénalo inmutable y confirma outcomes críticos con status autoritativo o movimiento de cuenta. Un webhook perdido no debe ocultar un pago; uno falso o duplicado no debe liberar valor.
Un timeout puede ocurrir después del acceptance. Reintentar con otro ID puede crear un segundo cobro. Genera la clave antes del primer intento y vincula merchant, tipo, importe, destino y hash; conserva respuesta y estado.
Los eventos entrantes también requieren dedupe. Usa event ID y unicidad sobre PSP, txid, end-to-end ID, tipo y versión. Una notificación repetida devuelve el mismo journal y transición.
La tabla payment proyecta el estado actual. La integridad requiere ledger append-only de partida doble donde cada journal balancea y referencia su fuente. Separa receivable, clearing, cash disponible, saldo cliente, payable, fee, liability de devolución, pérdida y suspense.
No edites historia para corregir. Publica reversal o ajuste con razón y autorización. Verifica débitos igual a créditos, moneda, reglas de cuenta y vínculo entre liberación y journal committed.
La operacional compara webhooks con API. La de caja compara PSP/banco con cash y clearing internos. La de negocio compara pagos con pedidos, facturas y suscripciones. La contable compara saldos y exports con el libro mayor.
Near real-time encuentra pedidos pagos atascados; intraday detecta postings faltantes o duplicados; el cierre diario captura fees, devoluciones, límites de fecha y archivos fallidos.
Primero end-to-end ID, txid, payment ID, transacción, cuenta, importe y moneda. Después claves secundarias acotadas. Un fuzzy match no debe mover dinero ni cerrar facturas automáticamente sin policy de confianza.
Dinero sin match va a suspense con owner y aging. Pagos parciales o agregados necesitan reglas explícitas y evidencia del motivo del match.
| Divergencia | Causa probable | Check | Acción segura | Evidencia |
|---|---|---|---|---|
| PSP liquidó; pedido pendiente | Webhook perdido, worker, lock o schema. | Consultar pago y buscar journal/transición. | Asentar/aplicar idempotentemente si pasan invariantes. | Evento, API, journal, trace y versión. |
| Pedido pagado sin cash | Evento falso, mapping prematuro, ambiente o override. | Comprobar PSP, extracto, receptor, importe y credenciales. | Congelar liberación/payout e investigar. | Actor, policy, payload, extracto y auth. |
| Pago duplicado | Retry con nueva key, dos cobros o replay. | Agrupar por pedido, importe, payer, tiempo e IDs. | No fusionar; usar policy de devolución/crédito. | Ambas pruebas e intención. |
| Importe distinto | Cobro stale, descuento, fee, parcial o factura errónea. | Comparar gross, net, fees, esperado y quote. | Suspense o asignación parcial. | Cobro, factura, tarifa, extracto y policy. |
| Devolución distinta | Pendiente, parcial, original erróneo o duplicada. | Vincular original, return ID, importe, estado y journal. | Asentar solo estado verificado; mantener liability. | Original, devolución, razón y aprobación. |
| Consentimiento autorizado; pago ausente | Journey interrumpida, rechazo, expiración o participante. | Leer consent y payment por separado. | Mostrar estado exacto e iniciar journey nueva. | IDs, tiempos, client, participante e historial. |
El reembolso comercial nace de la relación con el cliente. La devolución Pix usa mecanismos del rail. MED cubre escenarios específicos de fraude y no sustituye devolución común ni prevención.
Modela solicitado, aprobado, enviado, procesando, completo, rechazado, cancelado, parcial y fallido. Reserva liability al comprometerte, pero marca cash devuelto solo con evidencia. El total no puede superar el original elegible.
La iniciación incluye consent, autorización, client, participante, resource status y journeys redirigidas o desacopladas. Conserva historia completa. El pago no puede superar scope, importe, acreedor, agenda o validez.
Aplica FAPI, autenticación fuerte, sender-constrained access cuando corresponda, validación exacta, autoridad breve, rotación, firmas requeridas, replay prevention y conformance. Registra versión y participante.
Evalúa antigüedad, device, sesión, beneficiario, importe, velocidad, hora, ubicación, canal, conducta, señales de estafa y límites. Conserva lo autorizado. Después monitorea cuentas relacionadas, devoluciones, disputas, indicadores mule y recovery.
Los modelos necesitan reason codes calibrados. Mide pérdida evitada junto con falso positivo, abandono, accesibilidad, revisión, queja y recuperación.
Correlaciona pedido, consent, cobro, payment, webhook, consulta, end-to-end ID, extracto, journal, transición, devolución y caso. Mide lag, dedupe, valor unmatched, edad de suspense, intentos de romper invariantes, cierre y backlog.
Alerta por valor y edad, no solo cantidad.
Simula timeout post-aceptación, duplicados, webhook perdido/desordenado, PSP caído, liquidación tardía, API versus extracto, cambio de día, devolución parcial, refund duplicado, precisión, rotación, consent expirado y resume tras deploy.
Ejecuta cierre diario simulado y prueba que rerun no duplica.
Construiría un payment control plane con adapters, outbox, inbox inmutable, state machines, risk gateway, verifier, ledger de partida doble, transiciones, motor de conciliación, suspense, consola de excepciones y export contable.
Cada adapter conservaría código externo y mapping versionado. Correcciones serían idempotentes, explicables y reversibles mediante nuevo journal.
La liquidación rápida no elimina complejidad contable; comprime el tiempo. Sistemas confiables separan estados, conservan IDs, publican partidas inmutables, verifican evidencia independiente y asignan owner a cada divergencia.
Artículo sobre pipelines de Pix y Open Finance en Brasil, incluyendo estados, consentimiento, idempotencia, liquidación, ledger de partida doble, matching, devoluciones, MED, fraude, excepciones, pruebas y observabilidad.