Reverse an authorized charge
A reversal undoes a charge the processor already authorized and returns the amount to the cardholder. It is different from cancelling an in-progress charge, which only aborts something that was never authorized.
The SDK orchestrates the whole operation. Your app does two things: trigger it and listen to the callbacks.
:::danger Never call doFinishTransaction when reversing
The SDK settles the reversal on its own. If you also finalize with status = "reversed", a second settlement is created and the business is debited twice.
:::
1. Get the transaction to reverseβ
The reversal always takes a HistoryMigoItem, but there are two ways to get one, depending on when you reverse.
Option A β the charge you just madeβ
If you reverse within the same session, you don't need a history lookup: build the item from the voucher delivered to onVoucherDataResponse.
fun HistoryMigoItem.fromVoucher(voucher: VoucherMigoData) = HistoryMigoItem().apply {
_authorizationCode = voucher.authorizationId // the reversal identifier
_id = voucher.referenceNumber // what locates it at the reader
_mainReferenceValue = voucher.referenceNumber
_systemTraceNumber = voucher.systemTrace
_terminalID = voucher.terminalId
_lastFourDigits = voucher.cardObfPAN
_transactionAmount = voucher.transactionAuthorizedAmount
_dateTimeOfTransaction = voucher.transactionDateTime
}
You don't need to fill _internalId: when it comes as 0, the SDK uses the id of the charge it created in this session.
:::warning The two fields you cannot omit
_authorizationCode is the reversal identifier β without it the operation never even starts. And _id is what the SDK uses to locate the transaction in the reader's history: if it doesn't match, the reversal fails with onGeneralException(COULD_NOT_SEND_VOID_FOR_THIS_REFUND, "Transaction not found."). Both come from the voucher.
:::
Option B β an earlier charge, from historyβ
To reverse something from a previous session, fetch it from history and pass the item exactly as it arrived, without rebuilding it:
import com.migo.sdkmigo.domain.usecasesparams.GetHistoryTransactionsParams
// Terminal history
migoSDK.getHistoryTransactions(
GetHistoryTransactionsParams(mActivity = this, terminalId = terminalId, transactionId = null)
)
// A single transaction by its _internalId
migoSDK.getSingleTerminalTransaction(
GetHistoryTransactionsParams(mActivity = this, terminalId = terminalId, transactionId = transactionId)
)
Responses:
onHistoryTransactionsResponse(history, terminalId)β list of transactions (may come back empty).onGetSingleTransactionResponse(item)β the transaction as aHistoryMigoItem, ornull.onGetSingleTransactionError(errorMessage, rawResponse)β error retrieving it.
:::caution Always pass terminalId
With terminalId, history resolves over REST and works on any provider. Leave it null and the query falls through to the native provider, where on MIGO_LINK_* it returns nothing.
:::
2. Trigger the reversalβ
import com.migo.sdkmigo.domain.usecasesparams.SendTransactionAnnulmentParams
migoSDK.sendTransactionAnnulment(
SendTransactionAnnulmentParams(
mActivity = this,
historyItem = historyItem
)
)
Before moving any money, the SDK checks with the platform whether the charge is reversible. Only if it is does it continue:
sendTransactionAnnulment()
ββ ineligible / check failed βββΊ onReversalPreviewError (the card is never touched)
ββ eligible βββΊ onReversalPreviewSuccess
ββ (the SDK reverses the card and settles)
ββ onReversalConfirmed reversal complete
ββ onReversalCompensated processor declined; the amount was returned
ββ onReversalPending left pending, resolves on its own
3. Listen to the callbacksβ
// The charge IS reversible. The SDK continues on its own.
override fun onReversalPreviewSuccess(preview: ReversalPreview?) {
// preview: amount, currency, balance, hasSufficientBalance
}
// Could not start. Neither the card nor the reader was touched.
override fun onReversalPreviewError(reason: String?, message: String?, preview: ReversalPreview?) {
showError(message)
}
override fun onReversalConfirmed(reversalId: String?) { /* reversal complete */ }
override fun onReversalCompensated(reversalId: String?) { /* the amount was returned */ }
override fun onReversalPending(reversalId: String?) { /* will resolve on its own */ }
override fun onReversalConfirmError(reason: String?, message: String?) { showError(message) }
override fun onReversalCompensationError(reason: String?, message: String?) { showError(message) }
:::warning Always implement them They have empty default implementations. If you don't implement them, an ineligible reversal reports nothing to your UI: it doesn't fail, but the flow is left hanging. :::
What each outcome means:
| Callback | What happened | Action needed? |
|---|---|---|
onReversalConfirmed | The reversal completed | No |
onReversalCompensated | The processor declined the reversal and the amount returned to the card | No |
onReversalPending | The close will complete on its own | No |
onReversalPreviewError | Never started: ineligible, or the check failed | Inform the user |
onReversalConfirmError / onReversalCompensationError | The server rejected the close | Escalate to support |
When a charge is not eligibleβ
Before moving any money, the platform runs four checks against the charge. If any fails, the charge is not eligible, the card is never touched, and you get onReversalPreviewError with the reason in reason:
| Check | reason if it fails | What it means |
|---|---|---|
| The settlement associated with the charge exists | settlementNotFound | The charge's settlement was not found |
| There is exactly one card movement in a settled state | notLiquidated | The charge isn't settled yet, or was already reversed |
| The charge falls inside the same calendar day window | outsideSameDayWindow | The deadline passed. The window is set by the business's policy |
| The card has enough real balance for the debit | insufficientBalance | Check balance and hasSufficientBalance in the preview |
| β the balance could not be checked with the processor | balanceUnavailable | Could not verify; retry later |
:::note An already-reversed charge arrives as notLiquidated
The contract declares an alreadyReversed reason, but it is not emitted today: reversing the same charge twice lands on notLiquidated, because no settled movement is left. Handle it in case it is switched on later, but don't expect to receive it.
:::
The check is not an error: the service responds successfully and ineligibility travels as data, alongside the rest of the preview (amount, currency, balance, hasSufficientBalance). Use them to explain the reason to the user β for example, showing the real balance on an insufficientBalance.
It's a different matter when the check itself fails (network or server error): there reason carries an error code or null, and preview arrives as null. You don't know whether the charge was reversible; retry.
The reversal voucherβ
Beyond the callbacks above, the voucher arrives through onVoucherDataResponse with authorizationMigoType = VOID. Use it only to close your UI, never to finalize β see Receive the voucher and finalize.
Webhooksβ
Payment webhooks notify you when a payment is approved or denied. Reversals and cancellations emit no event: a payment already notified as approved can be reversed without another notice. To learn the outcome of a reversal, use the SDK callbacks on this page and the history queries.
Relatedβ
- Cancel an in-progress charge β abort before authorization.
- SDK Reference β callback signatures and entities.