Reversar un cobro autorizado
Una reversión deshace un cobro que el procesador ya autorizó y devuelve el monto al tarjetahabiente. Es distinta de cancelar un cobro en curso, que solo aborta algo que todavía no se autorizó.
El SDK orquesta toda la operación. Tu app hace dos cosas: dispararla y escuchar los callbacks.
:::danger Nunca llames doFinishTransaction al reversar
El SDK liquida la reversión por su cuenta. Si además finalizas con status = "reversed", se crea un segundo settlement y el comercio queda debitado dos veces.
:::
1. Obtener la transacción a reversar
La reversión siempre recibe un HistoryMigoItem, pero hay dos formas de conseguirlo según cuándo reverses.
Opción A — el cobro que acabas de hacer
Si reversas dentro de la misma sesión, no necesitas consultar el historial: construyes el ítem con el voucher que te llegó en onVoucherDataResponse.
fun HistoryMigoItem.fromVoucher(voucher: VoucherMigoData) = HistoryMigoItem().apply {
_authorizationCode = voucher.authorizationId // el identificador de la reversión
_id = voucher.referenceNumber // con esto se localiza en el lector
_mainReferenceValue = voucher.referenceNumber
_systemTraceNumber = voucher.systemTrace
_terminalID = voucher.terminalId
_lastFourDigits = voucher.cardObfPAN
_transactionAmount = voucher.transactionAuthorizedAmount
_dateTimeOfTransaction = voucher.transactionDateTime
}
No hace falta llenar _internalId: si viene en 0, el SDK usa el id del cobro que creó en esta sesión.
:::warning Los dos campos que no puedes omitir
_authorizationCode es el identificador de la reversión — sin él la operación ni siquiera arranca. Y _id es con lo que el SDK localiza la transacción en el historial del lector: si no coincide, la reversión falla con onGeneralException(COULD_NOT_SEND_VOID_FOR_THIS_REFUND, "Transaction not found."). Ambos salen del voucher.
:::
Opción B — un cobro anterior, desde el historial
Para reversar algo de una sesión previa, recupéralo del historial y pasa el ítem tal como llegó, sin reconstruirlo:
import com.migo.sdkmigo.domain.usecasesparams.GetHistoryTransactionsParams
// Historial de la terminal
migoSDK.getHistoryTransactions(
GetHistoryTransactionsParams(mActivity = this, terminalId = terminalId, transactionId = null)
)
// Una transacción puntual por su _internalId
migoSDK.getSingleTerminalTransaction(
GetHistoryTransactionsParams(mActivity = this, terminalId = terminalId, transactionId = transactionId)
)
Respuestas:
onHistoryTransactionsResponse(history, terminalId)— lista de transacciones (puede venir vacía).onGetSingleTransactionResponse(item)— la transacción comoHistoryMigoItem, onull.onGetSingleTransactionError(errorMessage, rawResponse)— error al recuperarla.
:::caution Pasa siempre el terminalId
Con terminalId, el historial se resuelve por REST y funciona en cualquier proveedor. Si lo dejas en null, la consulta cae al proveedor nativo y en MIGO_LINK_* no devuelve nada.
:::
2. Disparar la reversión
import com.migo.sdkmigo.domain.usecasesparams.SendTransactionAnnulmentParams
migoSDK.sendTransactionAnnulment(
SendTransactionAnnulmentParams(
mActivity = this,
historyItem = historyItem
)
)
Antes de mover dinero, el SDK verifica con la plataforma si el cobro es reversible. Solo si lo es continúa:
sendTransactionAnnulment()
├─ no elegible / falla la verificación ──► onReversalPreviewError (no se toca la tarjeta)
└─ elegible ──► onReversalPreviewSuccess
└─ (el SDK reversa la tarjeta y liquida)
├─ onReversalConfirmed reversión completa
├─ onReversalCompensated el procesador rechazó; se devolvió el monto
└─ onReversalPending quedó pendiente, se resuelve sola
3. Escuchar los callbacks
// El cobro SÍ es reversible. El SDK continúa solo.
override fun onReversalPreviewSuccess(preview: ReversalPreview?) {
// preview: amount, currency, balance, hasSufficientBalance
}
// No se pudo iniciar. No se tocó la tarjeta ni el lector.
override fun onReversalPreviewError(reason: String?, message: String?, preview: ReversalPreview?) {
showError(message)
}
override fun onReversalConfirmed(reversalId: String?) { /* reversión completa */ }
override fun onReversalCompensated(reversalId: String?) { /* se devolvió el monto */ }
override fun onReversalPending(reversalId: String?) { /* se resolverá sola */ }
override fun onReversalConfirmError(reason: String?, message: String?) { showError(message) }
override fun onReversalCompensationError(reason: String?, message: String?) { showError(message) }
:::warning Impleméntalos siempre Tienen implementación por defecto vacía. Si no los implementas, una reversión no elegible no notifica nada a tu UI: no falla, pero el flujo se queda abierto. :::
Qué significa cada desenlace:
| Callback | Qué pasó | ¿Requiere acción? |
|---|---|---|
onReversalConfirmed | La reversión quedó completa | No |
onReversalCompensated | El procesador rechazó la reversa y el monto volvió a la tarjeta | No |
onReversalPending | El cierre se completará solo | No |
onReversalPreviewError | No se inició: no elegible o falló la verificación | Informar al usuario |
onReversalConfirmError / onReversalCompensationError | El servidor rechazó el cierre | Escalar a soporte |
Cuándo un cobro no es elegible
Antes de mover dinero, la plataforma corre cuatro verificaciones sobre el cobro. Si alguna falla, el cobro no es elegible, no se toca la tarjeta y recibes onReversalPreviewError con el motivo en reason:
| Verificación | reason si falla | Qué significa |
|---|---|---|
| Existe la liquidación asociada al cobro | settlementNotFound | No se encontró el settlement del cobro |
| Hay exactamente un movimiento a tarjeta en estado liquidado | notLiquidated | El cobro aún no se liquidó, o ya fue revertido |
| El cobro está dentro de la ventana del mismo día calendario | outsideSameDayWindow | Pasó el plazo. La ventana la define la política del comercio |
| La tarjeta tiene saldo real suficiente para el débito | insufficientBalance | Revisa balance y hasSufficientBalance en el preview |
| — no se pudo consultar el saldo con el procesador | balanceUnavailable | No se pudo verificar; reintenta más tarde |
:::note Un cobro ya revertido llega como notLiquidated
El contrato declara un motivo alreadyReversed, pero hoy no se emite: reversar dos veces el mismo cobro cae en notLiquidated, porque ya no queda un movimiento liquidado. Manéjalo por si se activa a futuro, pero no esperes recibirlo.
:::
La verificación no es un error: el servicio responde correctamente y la inelegibilidad viaja como dato, junto con el resto del preview (amount, currency, balance, hasSufficientBalance). Úsalos para explicarle el motivo al usuario — por ejemplo, mostrar el saldo real ante un insufficientBalance.
Distinto es que falle la verificación misma (red o error del servidor): ahí reason trae un código de error o null, y preview llega en null. No sabes si el cobro era reversible; reintenta.
El voucher de la reversión
Además de los callbacks anteriores, el voucher llega por onVoucherDataResponse con authorizationMigoType = VOID. Úsalo solo para cerrar tu UI, nunca para finalizar — ver Recibir el voucher y finalizar.
Webhooks
Los webhooks de cobros notifican cuando un cobro se aprueba o se rechaza. Las reversiones y las cancelaciones no emiten ningún evento: un cobro ya notificado como aprobado puede reversarse sin que llegue otro aviso. Para conocer el resultado de una reversión, usa los callbacks del SDK de esta página y las consultas de historial.
Relacionado
- Cancelar un cobro en curso — abortar antes de la autorización.
- Referencia del SDK — firmas de los callbacks y entidades.