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:
| Dato | De dónde sale | Para qué |
|---|---|---|
terminalData | onServiceConnected | merchantDetailId, merchantTerminalId y la moneda |
terminalPaymentId | onCreateTerminalPaymentResponse (response.data.id) | Finalizar el cobro |
voucher | onVoucherDataResponse | Decidir 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 enonReturnCurrentTransactionInfoy tú confirmas llamando atransactionConfirmation()(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 voucher | Qué hacer |
|---|---|
isTransactionApproved == false | No finalices. Muestra responseCodeDescription |
Aprobada y tipo SALE | doFinishTransaction(status = "approved") |
Aprobada y tipo VOID | No llames doFinishTransaction. Cierra tu UI y espera los callbacks de reversión |
| Aprobada, otro tipo | Tipo 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:
onSignatureRequiredyonVoucherDataResponseson excluyentes. No esperes los dos.- Cerrar la transacción no depende de la firma. Llama
doFinishTransaction()apenas dispareonSignatureRequired, firme el cliente o no. - La subida al servidor solo ocurre si el lector aceptó la firma. Si
onSignatureListenerResponsetrae unreason, 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ículo | Notas |
|---|---|
| Tarjeta | Transferencia a una tarjeta (SettlementData.card / cardTransferId) |
| Cuenta bancaria | Depósito a una cuenta de banco |
| Balance | Saldo 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
createdytotalAmount0; pasa aapprovedcuando finalizas condoFinishTransaction. 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ódigo | Nombre | Significado |
|---|---|---|
7307 | ERROR_CREATING_TERMINAL_PAYMENT | Falló la creación del pago con terminal |
7308 | ERROR_TERMINAL_PAYMENT_STATUS | Error al obtener el estado del pago con terminal |
7400 | TERMINAL_NOT_FOUND | La terminal referenciada no existe |
7401 | TERMINAL_INACTIVE | La terminal no está activa (activación pendiente) |
7402 | TERMINAL_PAYMENT_NOT_FOUND | El pago con terminal no existe |
7006 | EXTERNAL_ID_ALREADY_EXISTS | externalId duplicado |
Consulta el Catálogo de errores para la lista completa de códigos y su semántica.
Relacionado
- Cancelar un cobro en curso — aborta antes de la autorización.
- Reversar un cobro autorizado — deshaz un cobro aprobado.
- Referencia del SDK — todos los métodos, callbacks y entidades.
- Instalación del SDK — inicialización y activación de la terminal.