Revertir una transacción

Una reversión cancela un pago previamente completado — por ejemplo, cuando se cobró un importe incorrecto. Lo más importante es contra qué identificador se realiza la reversión: una reversión apunta al ID de transacción POI que el terminal devolvió en la respuesta de pago original, no a tu propia referencia de venta.

Requisito previo: una sesión activa y el POITransactionID del pago que deseas revertir.

Necesitas el ID de transacción POI original

Cuando un pago se realiza con éxito, su SuccessRetailerPaymentResponse lleva un POITransactionID en los datos POI. Eso es lo que una reversión cancela. Si no lo capturaste en el momento del pago, puedes recuperarlo con una solicitud de estado de transacción (consulta Guía: comprobación del estado de la transacción) — pero la forma correcta es almacenarlo cuando el pago se complete con éxito.

Este es el error más común en las reversiones: pasar tu propio saleTransactionId donde debería ir el ID de transacción POI original. Son identificadores diferentes; la reversión debe referenciar el ID del terminal.

La llamada

viewModelScope.launch {
    clientSDK.sendReversalRequest(
        RetailerMessageArguments.ReversalRequestMessageArguments(
            originalPoiTransactionId = "<POITransactionID del pago original>",
            saleTransactionId = "Sale001",
            transactionAmountsData =
                RetailerMessageArguments.ReversalRequestMessageArguments.TransactionAmountsData(
                    reversedAmount = BigDecimal("10.00"),
                    currency = "EUR"
                )
        )
    )
}

• originalPoiTransactionId — el POITransactionID del pago que se está revirtiendo. Este es el campo clave.
• saleTransactionId — tu referencia para esta operación de reversión.
• transactionAmountsData — un TransactionAmountsData anidado que lleva reversedAmount y currency.

Interpretar el resultado

when (message) {
    is SuccessRetailerReversalResponse -> { /* reversión aceptada */ }
    is ErrorRetailerReversalResponse   -> { /* reversión rechazada — inspeccionar detalles */ }
}

Una reversión rechazada comúnmente significa que el ID de transacción POI fue incorrecto, la transacción ya fue revertida o ya no es reversible. La respuesta de error contiene los detalles.

Reversión vs. abortar

Estos resuelven problemas diferentes y es fácil confundirlos:

• Abortar (sendAbortRequest()) detiene un pago que aún está en progreso, antes de la autorización del host. Aún no hay nada que deshacer.
• Reversión cancela un pago que ya se ha completado. El dinero se movió; la reversión lo devuelve.

Si la autorización ya ocurrió, abortar ya no aplica — en su lugar, realiza una reversión. Consulta Solución de problemas: abortar no tiene efecto después de la autorización.

Relacionado

• Guía: realizar un pago — produce el POITransactionID que revertirás.
• Guía: comprobación del estado de la transacción — recupera un POITransactionID que no almacenaste.
• Cómo funciona el modelo de mensajes — manejo del supertipo de respuesta.
• Referencia de la API (sdk-doc.zip) — campos completos de ReversalRequestMessageArguments y TransactionAmountsData.