Intenciones de pago

Una intención de pago es un pago esperado, declarado antes de que el dinero se mueva. Donde una plantilla dice "acepto pagos bajo estas reglas", una intención de pago dice "estoy esperando este pago": un pagador, un monto, una ventana de tiempo, un token de pago propio. Cuando el pago llega, Mono lo vincula de vuelta a la intención de pago. Así sabes exactamente qué orden, factura o sesión de checkout fue pagada, antes de leer un solo campo del pago.

Usa intenciones de pago cuando cada pago debe identificarse de antemano: checkout de e-commerce, pago de facturas o cualquier flujo donde "quién paga qué" importa más que "llegó dinero".

Con o sin plantilla

Una intención de pago se crea de una de dos maneras (template_id y subaccount_id son mutuamente excluyentes):

• Desde una plantilla: la intención de pago hereda las reglas de la plantilla (límites, pagadores esperados, payin_data) y puede sobreescribir algunas para sí misma. Para Bre-B, la plantilla debe crear sus llaves por intención de pago (method_params.co_breb.key_per: "intent"); una plantilla con llave compartida no puede vincular pagos a intenciones de pago individuales.
• Sin plantilla: la intención de pago se crea directamente contra una subcuenta y lleva su propia configuración. Mono le aprovisiona un token de pago dedicado de un solo uso.

La creación es idempotente sobre external_id: repetir la petición devuelve la intención de pago existente. Cuando una intención de pago expira, su external_id queda libre para una nueva. Eso es lo que hace seguro el ciclo de reintentos de un checkout.

Montos

Envía exactamente uno de merchant_amount o payer_amount; el otro se deriva. Con el único método disponible hoy (Bre-B, COP) ambos montos son iguales. Los dos campos existen para que el recaudo entre monedas llegue después sin cambiar el contrato. El monto se exige: un pago Bre-B por un monto distinto se rechaza (intent_amount_mismatch) y la intención de pago se rearma para un reintento.

Ciclo de vida

• created: aceptada y persistida; el token de pago todavía se está preparando, así que payment_tokens es null y el pagador aún no puede pagar.
• ready_to_pay: la intención de pago es pagable: payment_tokens lleva la llave Bre-B (y el QR de un solo uso, cuando se pidió) y expires_at queda definido. Para Bre-B la ventana es de 30 minutos.
• awaiting_payment: un pago para la intención de pago fue autorizado y está en vuelo.
• successful: el pago fue confirmado; la intención de pago queda consumida, sus tokens se dan de baja y no puede pagarse nunca más.
• failed: no queda nada por pagar: el token de pago nunca se logró registrar (key_registration_failed, payment_token_registration_failed) o un pago falló en un método que no rearma (payment_failed).
• expired: la ventana se cerró sin que nadie pagara. state_reason es expired.

Cada razón con la que una intención de pago puede terminar, y qué hacer con cada una, está en Errores de intención de pago.

Rearmado: cuando un intento de pago falla después de la autorización pero la intención de pago sigue viva, esta vuelve a ready_to_pay. El pagador puede reintentar contra la misma llave mientras dure la ventana. El intento fallido en sí lo reporta el webhook payin_rejected o payin_failed del pago; la intención de pago emite payin_intent_attempt_failed.

Responder "¿esto ya se pagó?"

GET /v1/core/payins/intents/find_successful_by?external_id=... devuelve la única intención de pago successful para un identificador de tu lado. Existe a lo sumo una por cliente. Le permite a tu conciliación preguntar por tu propio ID de orden sin almacenar IDs de Mono.

Checkout hospedado

url es la página hospedada por Mono donde el pagador completa esa intención de pago específica. Compártela con el pagador cuando prefieras no construir tú la pantalla de pago. Ver Checkout hospedado o API-only.

Cargos

En una intención de pago, calculated_fees llega vacío. Los cargos realmente cobrados aparecen en el pago.

Modelo de datos

El schema completo vive en la referencia de API de intenciones de pago.

Siguientes pasos

• Tokens de pago: llaves por intención de pago y códigos QR dinámicos.
• Recaudar con intenciones de pago: el flujo de extremo a extremo.
• Webhooks: los siete eventos de la intención de pago.