Skip to main content
Migo Docs

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 a HistoryMigoItem, or null.
  • 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:

CallbackWhat happenedAction needed?
onReversalConfirmedThe reversal completedNo
onReversalCompensatedThe processor declined the reversal and the amount returned to the cardNo
onReversalPendingThe close will complete on its ownNo
onReversalPreviewErrorNever started: ineligible, or the check failedInform the user
onReversalConfirmError / onReversalCompensationErrorThe server rejected the closeEscalate 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:

Checkreason if it failsWhat it means
The settlement associated with the charge existssettlementNotFoundThe charge's settlement was not found
There is exactly one card movement in a settled statenotLiquidatedThe charge isn't settled yet, or was already reversed
The charge falls inside the same calendar day windowoutsideSameDayWindowThe deadline passed. The window is set by the business's policy
The card has enough real balance for the debitinsufficientBalanceCheck balance and hasSufficientBalance in the preview
β€” the balance could not be checked with the processorbalanceUnavailableCould 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.