Evitar pagos duplicados desde el ECR

Un pago duplicado casi siempre comienza de la misma manera: el ECR pierde la respuesta de un pago que ya envió y luego lo vuelve a enviar o permite que el cliente pague de otra forma. Este artículo proporciona las reglas que debe implementar su ECR y la lógica de recuperación que debe ejecutar con la API local (Nexo Retailer 3.1, JSON sobre HTTP, puerto 8080).

Por qué ocurren los duplicados

El terminal de pago y el adquirente solo conocen las solicitudes que recibieron. No pueden saber si un segundo pago de la misma cesta es un error o una nueva compra. Solo el ECR lo sabe, por lo que la prevención de duplicados es responsabilidad del ECR. Causas habituales:

• El pago con tarjeta se aprueba, la respuesta se pierde (corte de red, tiempo de espera agotado del ECR o bloqueo) y el cajero pulsa de nuevo Pago con tarjeta, o el cliente paga en efectivo. Nadie sabe que se cargó la tarjeta, por lo que nadie revierte el pago.
• El cajero hace doble clic o la biblioteca HTTP vuelve a intentar silenciosamente un POST después de un error de conexión: la misma solicitud llega dos veces al terminal.
• El ECR se reinicia durante un pago y comienza la siguiente venta sin leer el resultado de la anterior.

Lo que el terminal de pago hace y no hace por usted

Dos componentes responden a sus solicitudes: el servidor HTTP del terminal, que mantiene un intercambio por endpoint (un POST lo abre y el 200 final en GET lo cierra), y la aplicación de pago, que ejecuta la transacción. Pueden encontrarse en estados diferentes, y la lógica de recuperación comprueba ambos.

Reglas que debe implementar en el ECR

1. Escriba un registro de transacciones antes de enviar

Antes de cada POST de un pago, una adquisición de tarjeta o una reversión, escriba una entrada en un almacenamiento persistente: ServiceID, SaleTransactionID (TransactionID y TimeStamp), endpoint, importe, divisa y estado IN_FLIGHT. En el 200 final, almacene POIData.POITransactionID y el resultado, y cierre la entrada. Después de un reinicio, una entrada que aún esté en IN_FLIGHT corresponde a un pago con resultado desconocido: resuélvalo antes que cualquier otra cosa en ese puesto.

2. Utilice un ServiceID nuevo para cada solicitud

• Cada solicitud debe recibir un ServiceID nuevo, incluidas /status, /diagnosis, /abort, /login y un reintento de un pago cuyo procesamiento se haya confirmado como no realizado. Haga persistente el contador; nunca utilice una constante como "0".
• El SaleTransactionID identifica la venta: debe ser único por cesta, no debe cambiar entre intentos para la misma cesta y siempre debe enviarse con su TimeStamp.

3. Bloquee la venta mientras su resultado sea desconocido

Desactive el botón de Pago con tarjeta en cuanto se pulse. Mientras una entrada esté en IN_FLIGHT para una cesta: no debe haber ninguna nueva solicitud de pago, ningún otro método de pago (efectivo, vale, segunda tarjeta) ni ninguna venta nueva en ese puesto. El bloqueo siempre termina con un resultado final, una cancelación controlada o el procedimiento sin resolver que se indica a continuación.

4. No permita que la capa HTTP reintente un POST

Desactive los reintentos automáticos en su cliente HTTP y en cualquier proxy entre el ECR y el terminal. Un POST que falle a nivel de transporte debe pasar a la lógica de recuperación, no a un reintento.

5. Consulte hasta obtener 200, con temporizadores adecuados para un pago real

POST /payment responde 202. Después, llame a GET /payment (sin cuerpo) hasta que responda 200.

El terminal aplica su propio tiempo de espera por endpoint, configurado en su servidor HTTP: 180 s en /payment, el mismo en todos los terminales. Es el tiempo que el terminal espera la respuesta final de la aplicación de pago; una vez transcurrido, GET responde 408 en lugar de la respuesta. Mantenga la ventana del pago por debajo de este valor. Cuando expire la ventana del pago, no libere la pantalla ni vuelva a enviar la solicitud: vaya a la lógica de recuperación.

6. Revierta con el POITransactionID si se utilizaron dos métodos de pago

Si un pago con tarjeta resulta aprobado después de que el cliente ya haya pagado de otra forma, envíe una ReversalRequest indicando OriginalPOITransaction.POITransactionID del registro o de /status. Nunca revierta utilizando el SaleTransactionID.

La lógica de recuperación

Ejecútela cuando el ECR se inicie con una entrada IN_FLIGHT, cuando falle una consulta o expire la ventana del pago, cuando un POST responda 403 o falle a nivel de transporte, y cuando GET /payment responda 408 o 423 con una entrada aún en IN_FLIGHT. Utilice un ServiceID nuevo para cada llamada. Los tres pasos responden a tres preguntas diferentes: si sigue abierto un intercambio, si la aplicación de pago sigue ocupada y cuál fue el último resultado.

Paso 1: ¿sigue abierto algún intercambio HTTP?

GET /blocked enumera todos los endpoints con un intercambio abierto, como JSON sin formato:

GET http://<terminal-ip>:8080/blocked

200 {"blocked":["/payment"]}     a result is waiting, or still being produced
200 {"blocked":[]}               no open exchange

• /payment aparece en la lista: reanude GET /payment hasta obtener 200. Esa respuesta es el resultado, independientemente de cuánto tiempo haya pasado desde que terminó el pago. No llame ahora a /status: devolvería la venta anterior. Si la consulta GET que está vaciando el intercambio responde 408 o 423, vaya al paso 2.
• La lista está vacía: la respuesta final ya se leyó (un 200 o un 408) o el pago nunca se inició. El paso 2 le indica si la aplicación de pago sigue trabajando en algo.

Paso 2: ¿la aplicación de pago sigue ocupada?

POST http://<terminal-ip>:8080/diagnosis
{ "MessageHeader": { ..., "MessageCategory":"Diagnosis", "ServiceID":"1042" },
  "DiagnosisRequest": {"POIID":"POI_01"} }

200
{ "DiagnosisResponse": { "Response": {"Result":"Success"},
                         "POIStatus": {"GlobalStatus":"OK"}, ... } }

Paso 3: lea la última transacción completada

POST http://<terminal-ip>:8080/status
{ "MessageHeader": { ..., "MessageCategory":"TransactionStatus", "ServiceID":"1043" },
  "TransactionStatusRequest": {} }

200
{ "TransactionStatusResponse": {
    "Response": {"Result":"Success"},
    "RepeatedMessageResponse": {
      "MessageHeader": {"MessageCategory":"Payment","ServiceID":"1040", ...},
      "PaymentResponse": {
        "Response": {"Result":"Success"},
        "SaleData": {"SaleTransactionID":{"TransactionID":"SALE-1040","TimeStamp":"..."}},
        "POIData":  {"POITransactionID":{"TransactionID":"9991","TimeStamp":"..."}},
        "PaymentResult": {"AmountsResp":{"AuthorizedAmount":"11.99","Currency":"EUR"}}, ... } } } }

La transacción devuelta coincide con la entrada del registro solo si RepeatedMessageResponse.MessageHeader.ServiceID, SaleTransactionID.TransactionID y SaleTransactionID.TimeStamp son iguales, MessageCategory es Payment y el importe es el solicitado (o inferior, en caso de una aprobación parcial).

Procedimiento sin resolver

• Conserve la entrada en el almacenamiento persistente con el estado UNRESOLVED, además del puesto, el importe y la hora, y avise al supervisor de la tienda o al sistema administrativo. Solo se permite otro método de pago mediante este proceso explícito, nunca de forma silenciosa.
• Cuando el terminal vuelva a estar accesible e inactivo, ejecute automáticamente los pasos 1 a 3 para cada entrada UNRESOLVED. Si el pago con tarjeta resulta aprobado y se aceptó otro método de pago, reviértalo (regla 6).
• Si ya no se puede leer el resultado desde el terminal, concilie con el informe de transacciones del comercio antes de reembolsar al cliente.

Cancelar cuando el cliente desiste

Si el pago sigue en curso una vez superada la ventana del pago (por ejemplo, el cliente se alejó durante la solicitud del PIN), el cajero puede cancelarlo: envíe una AbortRequest cuyo MessageReference contenga el ServiceID del pago y siga consultando GET /payment. El 200 final con ErrorCondition: Aborted es el resultado. Después de una adquisición de tarjeta (pago en dos pasos), utilice la variante Admin (AdminRequest con DualTransactionAborted) descrita en la especificación de la API local.

Lo que ve el cajero o el cliente