Recaudar con intenciones de pago

Una intención de pago por cada pago: QR dinámico, reintentos y conciliación exacta.

Este flujo declara cada pago esperado antes de que el dinero se mueva: por cada orden o factura, tu backend crea una intención de pago, Mono le acuña una llave Bre-B dedicada y un QR dinámico, y el pago que llega se vincula a la intención de pago automáticamente. La conciliación deja de ser trabajo de detective: preguntas "¿se pagó la intención de pago order-1042?" y la API responde.

Úsalo para checkout de e-commerce, pago de facturas o cualquier caso donde el monto y el pagador se conocen por pago y deben coincidir exactamente.

Antes de empezar

Vas a necesitar:

Una cuenta de Mono con Core y la feature de recaudos habilitada para tu programa. Ver Métodos: configuración del programa.
Una plantilla de recaudo creada con method_params.co_breb.key_per: "intent", o la decisión de crear intenciones de pago sin plantilla directamente contra una subcuenta.
Un endpoint de webhooks suscrito a los eventos de recaudos.
El concepto de Intenciones de pago fresco en la cabeza.

Vista de la secuencia

Pasos

Crea una intención de pago por cada pago. Idempotente sobre external_id. Usa tu ID de orden, para que un doble clic no pueda crear dos intenciones de pago:
```
{
  "external_id": "order-1042",
  "template_id": "<template con key_per intent>",
  "method": "co_breb",
  "merchant_amount": { "amount": 8990000, "currency": "COP" },
  "method_params": { "create_qr": true }
}
```
Envía exactamente uno de merchant_amount o payer_amount. Con una intención de pago sin plantilla, reemplaza template_id por subaccount_id.
Espera payin_intent_ready_to_pay. Entrega payment_tokens (la llave propia de la intención de pago y un QR de un solo uso con el monto exacto) y expires_at: para Bre-B, 30 minutos. Muestra el QR en tu checkout con un contador.
El cliente paga. El monto se exige: un pago por cualquier valor distinto al de la intención de pago se rechaza (intent_amount_mismatch).
Maneja los tres finales.
- Pagado: payin_intent_successful (más el subaccount_credited del pago). Confirma la orden.
- Intento fallido: payin_intent_attempt_failed: el pago rebotó pero la intención de pago se rearmó de vuelta a ready_to_pay. Mantén el QR en pantalla; el cliente puede reintentar contra la misma llave mientras dure la ventana.
- Expirado: payin_intent_expired: la ventana se cerró sin pago. El external_id queda libre, así que ofrecer un checkout nuevo para la misma orden es seguro.
Concilia sin almacenar IDs de Mono. GET /v1/core/payins/intents/find_successful_by?external_id=order-1042 devuelve la intención de pago exitosa para tu identificador, o nada: una respuesta en una llamada a "¿esto ya se pagó?".

¿Con plantilla o sin plantilla?

Con una plantilla key_per: "intent": las intenciones de pago heredan límites, pagadores esperados y payin_data; administras la configuración de la campaña en un solo lugar.
Sin plantilla: cada intención de pago se sostiene sola contra una subcuenta, con su propia configuración. Menos piezas móviles cuando no hay una campaña compartida de la cual hablar.

Siguientes pasos

Intenciones de pago: la máquina de estados completa, el rearmado y la expiración.
Tokens de pago: los QRs dinámicos en detalle.
Recaudar con una plantilla: la alternativa de pagos anónimos.