Saltar al contenido principal
Migo Docs

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 como HistoryMigoItem, o null.
  • 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:

CallbackQué pasó¿Requiere acción?
onReversalConfirmedLa reversión quedó completaNo
onReversalCompensatedEl procesador rechazó la reversa y el monto volvió a la tarjetaNo
onReversalPendingEl cierre se completará soloNo
onReversalPreviewErrorNo se inició: no elegible o falló la verificaciónInformar al usuario
onReversalConfirmError / onReversalCompensationErrorEl servidor rechazó el cierreEscalar 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ónreason si fallaQué significa
Existe la liquidación asociada al cobrosettlementNotFoundNo se encontró el settlement del cobro
Hay exactamente un movimiento a tarjeta en estado liquidadonotLiquidatedEl cobro aún no se liquidó, o ya fue revertido
El cobro está dentro de la ventana del mismo día calendariooutsideSameDayWindowPasó el plazo. La ventana la define la política del comercio
La tarjeta tiene saldo real suficiente para el débitoinsufficientBalanceRevisa balance y hasSufficientBalance en el preview
— no se pudo consultar el saldo con el procesadorbalanceUnavailableNo 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​