Reversing a transaction

A reversal cancels a previously completed payment — for example, when the wrong amount was charged. The critical thing to get right is which identifier you reverse against: a reversal targets the POI transaction ID the terminal returned in the original payment response, not your own sale reference.

Prerequisite: a live session, and the POITransactionID from the payment you want to reverse.

You need the original POI transaction ID

When a payment succeeds, its SuccessRetailerPaymentResponse carries a POITransactionID in the POI data. That is what a reversal cancels. If you didn't capture it at payment time, you can retrieve it with a transaction status request (see Guide: checking transaction status) — but the clean approach is to store it when the payment succeeds.

This is the most common reversal mistake: passing your own saleTransactionId where the original POI transaction ID belongs. They are different identifiers; the reversal must reference the terminal's ID.

The call

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

• originalPoiTransactionId — the POITransactionID from the payment being reversed. This is the key field.
• saleTransactionId — your reference for this reversal operation.
• transactionAmountsData — a nested TransactionAmountsData carrying reversedAmount and currency.

Reading the result

when (message) {
    is SuccessRetailerReversalResponse -> { /* reversal accepted */ }
    is ErrorRetailerReversalResponse   -> { /* reversal rejected — inspect detail */ }
}

A rejected reversal commonly means the POI transaction ID was wrong, the transaction was already reversed, or it's no longer reversible. The error response carries the detail.

Reversal vs. abort

These solve different problems and are easy to confuse:

• Abort (sendAbortRequest()) stops a payment that is still in progress, before host authorization. There is nothing to undo yet.
• Reversal cancels a payment that has already completed. The money moved; the reversal moves it back.

If authorization has happened, abort no longer applies — reverse instead. See Troubleshooting: abort has no effect after authorization.

Related

• Guide: taking a payment — produces the POITransactionID you reverse.
• Guide: checking transaction status — recover a POITransactionID you didn't store.
• How the message model works — handling the response super-type.
• API reference (sdk-doc.zip) — full ReversalRequestMessageArguments and TransactionAmountsData fields.