Intención, intento y veredicto

Imagina un peaje con varios carriles. El carro es la venta; el carril es el medio de pago. Si un carril está cerrado, el carro prueba otro, pero sigue siendo el mismo carro. El Merchant modela el cobro exactamente así, con tres objetos.

Objeto	Qué es	Ejemplo
Intención	Lo que el comercio quiere cobrar: el importe, la moneda, una descripción y un vencimiento	«Venta 0042, Bs 150,00»
Intento	Un medio de pago concreto ejecutándose, con su propio estado	«Pago móvil por Bs 150,00»
Veredicto	El desenlace de ese intento: aprobado, rechazado o en duda. Es uno solo y no cambia	«Rechazado: fondos insuficientes»

flowchart LR
  I["Intención<br/>Venta 0042 · Bs 150,00"] --> A1["Intento 1<br/>Pago móvil"]
  A1 --> V1["Veredicto<br/>Rechazado"]
  I --> A2["Intento 2<br/>Tarjeta"]
  A2 --> V2["Veredicto<br/>Aprobado"]
  V2 --> P["Intención PAGADA"]

Por qué separar la intención del intento

Porque en la vida real el primer medio de pago muchas veces falla. El cliente intenta pagar con pago móvil, su banco lo rechaza, y paga con tarjeta. Si cada intento fuera una venta distinta, el comercio vería dos ventas para un solo pedido y la conciliación nunca cuadraría. Con la intención como paraguas:

• La venta es una sola, aunque haya tenido tres intentos.
• Cada intento conserva su historia: quién lo rechazó y con qué código.
• La intención queda PAGADA cuando la suma de lo aprobado cubre el importe. Puede cubrirse con más de un intento (por ejemplo, una parte en efectivo y el resto con tarjeta).
• Hay un intento a la vez. No se abre el segundo mientras el primero no tiene veredicto.

La idempotencia: pedir dos veces no cobra dos veces

El sistema del comercio crea la intención con una clave de idempotencia, que suele ser el número de su factura o de su pedido. Si la red falla y el sistema repite la misma petición con la misma clave, el Merchant devuelve la intención que ya existe en lugar de crear otra. Así, un reintento automático nunca termina en un doble cobro.

La regla para quien integra

Usa siempre la misma clave para reintentar la misma venta. Una clave nueva significa una venta nueva.

EN_DUDA: cuando nadie sabe si se cobró

Un intento puede terminar en tres veredictos:

Veredicto	Qué significa	Qué se hace
Aprobado	El autorizador dijo que sí	La venta avanza; si es tarjeta, entra al lote
Rechazado	El autorizador dijo que no, con un motivo	Se puede intentar otro medio de pago
EN_DUDA	Se venció el tiempo de espera o se cortó la comunicación: no se sabe si el banco cobró	No se vuelve a cobrar. El sistema consulta después, reversa o lo resuelve la conciliación

EN_DUDA es el estado más importante de entender. Un tiempo de espera nunca es un rechazo: el banco pudo haber cobrado y la respuesta perderse en el camino. Si el cajero cobra otra vez, el cliente paga dos veces. Por eso el Merchant barre los intentos en duda y los consulta, y las aplicaciones de FINORA muestran el mensaje «No lo cobres otra vez».

Cómo lo ve cada punto de venta: en una caja, la venta en duda; en una caja de terceros conectada por FINORA Pago, los veredictos; en una tienda web, los estados de una sesión de cobro.

Por qué está hecho así

Hay tres decisiones de diseño detrás de este modelo:

1. El banco se llama fuera de toda transacción de base de datos. Un banco puede tardar varios segundos en responder; mientras tanto, ningún registro queda bloqueado esperando. Crear la intención y abrir el intento son operaciones cortas.
2. El veredicto lo gana una sola escritura. Cuando dos procesos quieren resolver el mismo intento (por ejemplo, la respuesta tardía del banco y el barrido de los vencidos), gana el que cambia el registro primero; el otro ve que ya está resuelto y no hace nada.
3. Cada hecho del dominio publica un evento que el monitor en vivo (la Torre) muestra al instante.

Lo que necesitas recordar

• Una intención es la venta; un intento es un medio de pago; un veredicto es su desenlace.
• La misma clave de idempotencia nunca crea dos ventas.
• EN_DUDA no es rechazo: no se vuelve a cobrar.

Siguiente: Qué funciona de verdad, riel por riel.