Revocare una transazione

Una revoca annulla un pagamento precedentemente completato — ad esempio, quando è stato addebitato un importo errato. La cosa fondamentale da fare correttamente è contro quale identificatore effettuare la revoca: una revoca si riferisce al POI transaction ID restituito dal terminale nella risposta di pagamento originale, non al proprio riferimento di vendita.

Prerequisito: una sessione attiva e il POITransactionID del pagamento che si desidera revocare.

Serve l'ID della transazione POI originale

Quando un pagamento ha successo, la sua SuccessRetailerPaymentResponse contiene un POITransactionID nei dati POI. È quello che una revoca annulla. Se non lo hai acquisito al momento del pagamento, puoi recuperarlo con una richiesta di stato della transazione (vedi Guida: controllo dello stato della transazione) — ma l'approccio corretto è memorizzarlo quando il pagamento ha successo.

Questo è l'errore più comune nelle revoche: passare il proprio saleTransactionId invece del POI transaction ID originale. Sono identificatori diversi; la revoca deve fare riferimento all'ID del terminale.

La chiamata

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

• originalPoiTransactionId — il POITransactionID del pagamento da revocare. Questo è il campo chiave.
• saleTransactionId — il tuo riferimento per questa operazione di revoca.
• transactionAmountsData — un oggetto TransactionAmountsData annidato che contiene reversedAmount e currency.

Lettura del risultato

when (message) {
    is SuccessRetailerReversalResponse -> { /* revoca accettata */ }
    is ErrorRetailerReversalResponse   -> { /* revoca rifiutata — controlla i dettagli */ }
}

Una revoca rifiutata generalmente significa che il POI transaction ID era errato, la transazione era già stata revocata o non è più reversibile. La risposta di errore contiene i dettagli.

Revoca vs. annullamento

Risolvono problemi diversi e sono facili da confondere:

• Annullamento (sendAbortRequest()) interrompe un pagamento ancora in corso, prima dell'autorizzazione dell'host. Non c'è nulla da annullare ancora.
• Revoca annulla un pagamento che è già stato completato. Il denaro è stato trasferito; la revoca lo riporta indietro.

Se l'autorizzazione è già avvenuta, l'annullamento non è più applicabile — bisogna fare una revoca. Vedi Risoluzione problemi: l'annullamento non ha effetto dopo l'autorizzazione.

Correlati

• Guida: effettuare un pagamento — produce il POITransactionID che revoci.
• Guida: controllo dello stato della transazione — recupera un POITransactionID che non hai memorizzato.
• Come funziona il modello di messaggi — gestione del super-tipo di risposta.
• Riferimento API (sdk-doc.zip) — campi completi di ReversalRequestMessageArguments e TransactionAmountsData.