Saltar al contenido principal
Migo Docs

Procesar un pago con terminal

Un cobro con tarjeta presente se ejecuta dentro de tu app llamando a migoSDK.doTransaction(...). El SDK crea el pago en la plataforma de Migo, lee la tarjeta por NFC, te devuelve los datos de la transacción para confirmar y, tras la autorización, te entrega el voucher. Tú lo finalizas con doFinishTransaction(...) para liquidarlo.

Requiere una terminal activa — ver Registro y activación de la terminal.

De un vistazo​

doTransaction(amount, currency, merchantDetailId, merchantTerminalId)
├─ onCreateTerminalPaymentResponse pago creado en backend (status "created")
│ └─ guarda response.data.id ──► terminalPaymentId
├─ onPresentCardRequest pide al cliente acercar la tarjeta al NFC
├─ onReadingCardData leyendo la tarjeta
├─ onUserCardPinRequest (si aplica) PIN del titular
├─ onReturnCurrentTransactionInfo datos de la tarjeta ──► transactionConfirmation()
├─ onSendingTransactionAuthorization enviando a autorizar
└─ onVoucherDataResponse ¿isTransactionApproved? ──► doFinishTransaction()

Tres datos viajan de un paso al siguiente; guárdalos apenas lleguen:

DatoDe dónde salePara qué
terminalDataonServiceConnectedmerchantDetailId, merchantTerminalId y la moneda
terminalPaymentIdonCreateTerminalPaymentResponse (response.data.id)Finalizar el cobro
voucheronVoucherDataResponseDecidir el desenlace y finalizar

1. Iniciar el cobro​

Toma merchantDetailId y merchantTerminalId de terminalData.mPosParameters (recibido en onServiceConnected), y la moneda de la propia configuración de la terminal:

import com.migo.sdkmigo.presentation.migoSDK
import com.migo.sdkmigo.domain.usecasesparams.DoTransactionParams
import com.migo.sdkmigo.domain.enums.TransactionConfirmationMigoMode

val merchant = terminalData.mPosParameters!!.first()

migoSDK.doTransaction(
DoTransactionParams(
mActivity = this,
transactionAmount = 150.50, // Double, no String
transactionCurrency = merchant.currencyInfoList?.first(), // la moneda de la terminal
merchantDetailId = merchant.id!!,
merchantTerminalId = merchant.terminalId!!,
confirmationMode = TransactionConfirmationMigoMode.USER_CONFIRMATION,
isApiRest = true
)
)

confirmationMode:

  • USER_CONFIRMATION — el flujo se pausa en onReturnCurrentTransactionInfo y tú confirmas llamando a transactionConfirmation() (recomendado para mostrar el monto y los datos de la tarjeta antes de autorizar).
  • AUTOMATIC_CONFIRMATION — el SDK continúa hacia la autorización sin pausa.

isApiRest = true integra el cobro con el backend REST de Migo (creación del pago y liquidación).

:::caution En MIGO_LINK el lector trae sus propias pantallas Todo lo que sigue —pedir la tarjeta, leerla, el PIN y la confirmación— solo aplica a MIGO_PAY. En MIGO_LINK_* esa experiencia la conduce el lector con su propia UI: transactionConfirmation no hace nada y los callbacks del paso a paso (onPresentCardRequest, onReadingCardData, onReturnCurrentTransactionInfo…) no se disparan. Tu app dispara el cobro y espera el resultado en onVoucherDataResponse.

El detalle de qué callback llega con cada proveedor está en la Referencia del SDK. :::

Guarda el identificador del pago apenas el backend lo cree:

private var terminalPaymentId: Int? = null

override fun onCreateTerminalPaymentResponse(response: TerminalPaymentResponse?) {
terminalPaymentId = response?.data?.id
}

override fun onCreateTerminalPaymentError(errorMessage: String?, rawResponse: String?) {
// El cobro se detiene aquí: no llegan más callbacks de esta transacción
showError(errorMessage)
}

2. Leer la tarjeta y confirmar​

Implementa los callbacks de MigoSDKCallbacks. Si NFC está apagado, el SDK llama onNFCStateOff() — pide al usuario activarlo.

override fun onPresentCardRequest(data: PresentCardTransactionMigoData?) {
// Muestra "Acerca la tarjeta al teléfono"
}

override fun onReturnCurrentTransactionInfo(
info: CurrentTransactionMigoInfo?,
mode: TransactionConfirmationMigoMode?
) {
// info trae monto, marca, cardHolderName, cardObfPan, etc.
// En modo USER_CONFIRMATION confirma para autorizar:
migoSDK.transactionConfirmation(
TransactionConfirmationParams(
mActivity = this,
sendTransactionAuthorization = true, // false para abortar
additionalTransactionInfo = null
)
)
}

3. Recibir el voucher y finalizar​

Cuando llega la respuesta de la transacción, el SDK llama onVoucherDataResponse(voucherData). Ese callback no significa "aprobada": trae el desenlace, y tú decides qué hacer con él.

:::info onVoucherDataResponse es un callback compartido Lo dispara tanto el cobro como la anulación. El authorizationMigoType te dice cuál llegó, y de eso depende qué hacer: un SALE lo finalizas tú; un VOID no, porque la anulación ya se liquidó sola. :::

:::danger No finalices una anulación sendTransactionAnnulment ya crea la liquidación de la reversión dentro del SDK. Si además llamas doFinishTransaction(status = "reversed"), se crea un segundo settlement: doble débito al comercio. En la rama VOID solo cierra tu UI. :::

La decisión es la siguiente:

Estado del voucherQué hacer
isTransactionApproved == falseNo finalices. Muestra responseCodeDescription
Aprobada y tipo SALEdoFinishTransaction(status = "approved")
Aprobada y tipo VOIDNo llames doFinishTransaction. Cierra tu UI y espera los callbacks de reversión
Aprobada, otro tipoTipo no válido para este flujo. No finalices

:::note El responseCode "14" Es el voucher sintético que arma el SDK cuando el intento expiró o se canceló en el lector: nunca se leyó la tarjeta. Siempre llega con isTransactionApproved = false, así que la validación de arriba ya lo cubre; el authorizationMigoType solo te dice si expiró un cobro o una anulación, para el mensaje que muestres. :::

override fun onVoucherDataResponse(voucher: VoucherMigoData?) {
voucher ?: return

// Rechazada, expirada o cancelada en el lector
if (voucher.isTransactionApproved != true) {
showError(voucher.responseCodeDescription ?: "Transacción rechazada")
return
}

// Anulación: el SDK ya liquidó la reversión. Solo cierra la UI.
if (voucher.authorizationMigoType == AuthorizationMigoType.VOID) {
closeReversalUI(voucher)
return
}

if (voucher.authorizationMigoType != AuthorizationMigoType.SALE) {
showError("Tipo de transacción no válido")
return
}

migoSDK.doFinishTransaction(
DoFinishTransactionParams(
mActivity = this,
terminalPaymentId = terminalPaymentId!!, // Int, de onCreateTerminalPaymentResponse
status = "approved",
authorizationId = voucher.authorizationId!!, // código de autorización del procesador
voucherData = voucher
)
)
}

override fun onCreateSettlementResponse(response: CreateSettlementResponse?) {
// Liquidación creada — response.data trae idRequest, card, balance, cardTransferId
}

override fun onCreateSettlementError(errorMessage: String?, rawResponse: String?) {
// Maneja el fallo de liquidación
}

Para deshacer un cobro ya autorizado, ver Reversar un cobro autorizado.

Capturar la firma del titular​

Algunas transacciones exigen la firma manuscrita del titular — típicamente las que superan el límite de CVM de la marca. Aplica a integraciones Migo Link.

Cuando ocurre, el SDK llama onSignatureRequired(voucher) en lugar de onVoucherDataResponse:

doTransaction()
├─ no requiere firma ──► onVoucherDataResponse(voucher)
└─ requiere firma ──► onSignatureRequired(voucher)
├─► doFinishTransaction() ← siempre, firme o no
└─► (tu pantalla de captura)
└─► doSignatureTransaction(historyItem, bitmap)
└─► onSignatureListenerResponse(reason, code)
└─ si reason == null ──► onSignatureUploaded(url)
/ onSignatureUploadError(msg, code)

Tres reglas que evitan la mayoría de los errores:

  1. onSignatureRequired y onVoucherDataResponse son excluyentes. No esperes los dos.
  2. Cerrar la transacción no depende de la firma. Llama doFinishTransaction() apenas dispare onSignatureRequired, firme el cliente o no.
  3. La subida al servidor solo ocurre si el lector aceptó la firma. Si onSignatureListenerResponse trae un reason, no hay subida.
override fun onSignatureRequired(voucherData: VoucherMigoData?) {
finishTransaction(voucherData) // 1) cierra el cobro igual que en el flujo normal
showSignatureCaptureUI() // 2) muestra tu pantalla de captura
}

fun submitSignature(bitmap: Bitmap) {
migoSDK.doSignatureTransaction(
DoSignatureTransactionParams(
historyItem = signatureHistoryItem, // la transacción que pidió la firma
signature = bitmap
)
)
}

override fun onSignatureListenerResponse(reason: String?, code: Int?) {
if (reason == null) {
// Firma guardada en el lector. La subida al servidor arranca sola.
} else {
showError("Error de firma ($code): $reason")
}
}

override fun onSignatureUploaded(signatureUrl: String?) {
// La firma ya viaja con el cobro y se puede volver a dibujar en el detalle
}

override fun onSignatureUploadError(errorMessage: String?, code: String?) {
// Aviso, no error de pago: el cobro es válido y el lector ya tiene la firma
}

No hace falta redimensionar el Bitmap: el SDK lo convierte a PNG y lo reescala si excede el máximo del servidor. Si historyItem es null, el SDK responde onSignatureListenerResponse(reason = "Transaction not found", code = null) y no hace nada más.

:::note branchId es obligatorio para la firma La subida usa el branchId que pasaste en initService. Si viene null o <= 0, la firma no se sube y recibes onSignatureUploadError. La transacción no se ve afectada. :::

La firma vuelve en el detalle de la transacción (getSingleTerminalTransaction), en los campos _signatureUrl y _signatureData del HistoryMigoItem.

Liquidación​

Cada cobro aprobado se finaliza con doFinishTransaction(status = "approved"), que crea la liquidación en la plataforma y dispara onCreateSettlementResponse. El vehículo de liquidación — a dónde llega el dinero — se define con tu contacto comercial al activar la terminal. Las opciones actuales son:

VehículoNotas
TarjetaTransferencia a una tarjeta (SettlementData.card / cardTransferId)
Cuenta bancariaDepósito a una cuenta de banco
BalanceSaldo en la plataforma de Migo (SettlementData.balance)

El cierre por lote contra el proveedor (distinto de la liquidación por transacción) se dispara con migoSDK.sendSettlement(SendSettlementParams(mActivity)), que responde en onSettlementResponse(success, message). Solo aplica a MIGO_PAY: en MIGO_LINK_* la llamada no hace nada.

Notas​

  • El registro de pago con terminal que crea el SDK nace con estado created y totalAmount 0; pasa a approved cuando finalizas con doFinishTransaction. Los campos monetarios viajan como strings.
  • Si se pierde conectividad tras autorizar, el SDK guarda la transacción localmente y avisa con onStoringOfflineAuthorizedTransaction().
  • Errores del backend de pago con terminal (envelope CustomResponse):
CódigoNombreSignificado
7307ERROR_CREATING_TERMINAL_PAYMENTFalló la creación del pago con terminal
7308ERROR_TERMINAL_PAYMENT_STATUSError al obtener el estado del pago con terminal
7400TERMINAL_NOT_FOUNDLa terminal referenciada no existe
7401TERMINAL_INACTIVELa terminal no está activa (activación pendiente)
7402TERMINAL_PAYMENT_NOT_FOUNDEl pago con terminal no existe
7006EXTERNAL_ID_ALREADY_EXISTSexternalId duplicado

Consulta el Catálogo de errores para la lista completa de códigos y su semántica.

Relacionado​