Códigos de respuesta y errores

El Get Mini Android SDK utiliza un sistema de errores estructurado para distinguir entre operaciones exitosas, cancelaciones de usuario, fallos técnicos y denegaciones financieras. Comprender estos códigos de respuesta y categorías de error te ayudará a implementar una gestión de errores adecuada y a proporcionar información clara a los usuarios.

Tipos de respuesta RepositoryResult

Todas las operaciones del SDK devuelven resultados envueltos en la clase sellada RepositoryResult. El tipo de resultado indica el desenlace de alto nivel de la operativa.

Tipo de Resultado	Descripción	Cuándo ocurre
`RepositoryResult.Success`	La operación se completó con éxito con datos de resultado	Transacción aprobada, inicialización exitosa, dispositivo conectado
`RepositoryResult.Error`	La operación falló debido a un error técnico o fallo de validación	Error de red, PIN pad desconectado, parámetros inválidos, tiempo de espera agotado
`RepositoryResult.Cancelled`	El usuario canceló la operación	El cliente pulsó cancelar en el PIN pad, el usuario salió de la pantalla de pago

Verifica primero el tipo de resultado antes de acceder a los datos o mensajes de error para garantizar la seguridad de tipos en tu implementación.

Tipos de PaymentResult

Específicamente para las operaciones de pago, los resultados exitosos (RepositoryResult.Success) contienen un PaymentResult que indica el resultado de la transacción.

Resultado de Pago	Descripción	Próximos pasos
`PaymentResult.Accepted`	Transacción autorizada y aprobada por el host de pagos	Guarda el código de autorización y el ID de operación, proporciona el recibo
`PaymentResult.Denied`	Transacción denegada por el host de pagos o el emisor	Muestra el motivo de la denegación al cliente, ofrece otro método de pago

Las denegaciones de pago se consideran operaciones del SDK “exitosas” (la comunicación se realizó correctamente) pero representan rechazos a nivel de negocio por parte del host de pagos.

Códigos de respuesta de autorización

Cuando una transacción es denegada (PaymentResult.Denied), el campo responseCode contiene un código del host de autorización de pagos que indica el motivo específico de la denegación.

Códigos de éxito

Rango de Código	Significado	Descripción
0000-0099	Aprobada	Transacción autorizada con éxito. Proceder con el pedido.

Problemas con la tarjeta

Código	Significado	Acción recomendada
0101	Tarjeta Caducada	Solicita otro método de pago. La fecha de caducidad ha pasado.
0102	Tarjeta Bloqueada	Indica al cliente que contacte con su banco. La tarjeta está bloqueada.
0106	Intentos de PIN excedidos	Tarjeta bloqueada por PIN incorrecto. El cliente debe contactar con su banco.
0202	Tarjeta Restringida	La tarjeta tiene restricciones para este tipo de pago. Solicita otra tarjeta.

Fondos insuficientes

Código	Significado	Acción recomendada
0180	Fondos Insuficientes	No hay suficiente saldo o crédito. Solicita otro método de pago.
0184	Límite de Tarjeta Excedido	El importe excede el límite de la tarjeta. Prueba con un importe menor.

Problemas de transacción

Código	Significado	Acción recomendada
0190	Denegación General	El emisor denegó sin motivo específico. Solicita otro método de pago.
0912	Emisor no Disponible	No se puede contactar con el banco emisor. Reintenta más tarde.
9102	Transacción Inválida	Parámetros inválidos o no soportados. Verifica importe y configuración.

Errores de autenticación

Código	Significado	Acción recomendada
0184	Error de PIN	PIN introducido incorrecto. Permite al cliente reintentar.
0191	Autenticación Fallida	Fallo en la autenticación de la transacción. Solicita otro método.

Los códigos de respuesta pueden variar según el procesador de pagos y la configuración del adquiriente. Consulta con el soporte de Get Mini para mapeos específicos.

Mensajes de error técnicos del SDK

Código	Identificador	Causa	Descripción / Resolución
`1004`	`noInternetConnection`	Sin conectividad a internet	Verifica que el dispositivo tenga una conexión a internet activa.
`1005`	`unrealizedOperation`	Operación no realizada	Fallo general indicando que la operativa no se completó.
`1006`	`transactionDeniedInPinPad`	Denegación offline EMV	La transacción fue denegada localmente por el chip de la tarjeta.
`1007`	`signatureTooBig`	Firma demasiado grande	La imagen de la firma capturada excede el límite de 4999 bytes.
`1008`	`genericError`	Error genérico	Fallo general; revisa los datos de la petición y los logs.
`1009`	`communicationWithPinPadFailed`	Conexión con PIN pad perdida	Se perdió la conexión Bluetooth con el PIN pad Get Mini.
`1010`	`communicationWithWebServiceFailed`	Conectividad Web Service	Fallo al comunicar con el host de pagos o servidores de proceso.
`1011`	`malformedPinPadResponse`	Respuesta PIN pad malformada	La respuesta recibida del PIN pad es técnicamente incorrecta.
`1012`	`malformedPinPadConfirmation`	Confirmación malformada	El mensaje de confirmación del PIN pad es incorrecto.
`1013`	`unInitializedPinPad`	PIN pad no inicializado	Llama a `inicializarPinpad()` antes de procesar cualquier pago.
`1014`	`incorrectSignatureValidation`	Fallo de integridad	Falló la validación de integridad de la respuesta del host.
`1015`	`invalidSelectionDccCurrency`	Error de moneda DCC	La selección de moneda para la conversión DCC no es válida.
`1016`	`unInitializedPinpadByFailedUpdate`	Fallo de carga parámetros	No se pudieron cargar parámetros durante la inicialización.
`1017`	`unInitializedPinpadByFailedTDES`	Fallo de carga TDES	No se pudieron cargar las claves de seguridad durante la inicialización.
`1018`	`pinpadInitializationNotFinished`	Inicialización parcial	El proceso de inicialización del PIN pad no se completó.
`1019`	`pinpadWithOutKeys`	Faltan claves simétricas	El terminal no está operativo porque faltan sus claves internas.
`1020`	`invalidPUPVersion`	Versión protocolo errónea	Versión de protocolo del PIN pad incompatible con esta versión del SDK.
`1021`	`serverResponseWithError`	Respuesta error servidor	El servidor de pagos devolvió un error estructurado; revisa los datos.
`1022`	`invalidTerminalForOperation`	Estado terminal inválido	El terminal seleccionado no es válido para la operativa solicitada.
`1023`	`terminalWithoutPermissionForOperation`	Permiso denegado	La cuenta/terminal no tiene permiso para esta funcionalidad.
`1024`	`creditCardNotValid`	Lectura tarjeta inválida	La tarjeta presentada no es válida o no puede ser procesada.
`1025`	`misApplication`	Error de aplicación	Aplicación incorrecta seleccionada durante la lectura de la tarjeta.
`1026`	`misCodeDeferPayment`	Código de aplazamiento inválido	El código de aplazamiento de la operación no es válido.
`1027`	`rejectedSWAutoDownload`	Telecarga rechazada	Solicitud de telecarga rechazada.
`1028`	`rejectedSWAutoDownloadByTimeout`	Timeout en telecarga	Se recibe un timeout o un error de transmisión al enviar un bloque de software.
`117`	`pinIncorrecto`	PIN incorrecto	El cliente introdujo un PIN incorrecto durante la autorización online.
`195`	`repetirLectura`	Repetir lectura tarjeta	Indica al usuario que repita la lectura (Chip o doble Tap).
`196`	`pinTitular`	PIN requerido	Solicita el PIN al titular de la tarjeta.
`1055`	`noManualEntryEnabled`	Entrada manual deshabilitada	El comercio no está configurado para permitir entrada manual de tarjeta.
`1057`	`operationNotFound`	Operación no encontrada	No se puede realizar una acción sobre una transacción inexistente.

Registra siempre los mensajes de error para depuración y soporte, mostrando alternativas amigables a los clientes.

Errores específicos del PIN pad

Errores adicionales específicos de la operativa con el PIN pad Bluetooth y gestión de periféricos.

Tipo de Error	Descripción	Resolución
Fallo de Emparejamiento	No se puede conectar por Bluetooth	Verifica el modo emparejamiento y que el Bluetooth esté activo.
Batería Crítica	Batería del PIN pad muy baja	Carga el dispositivo PIN pad antes de intentar transacciones.
Firmware Incompatible	Versión de firmware no soportada	Actualiza el firmware a través de las herramientas de soporte.
Dispositivo Ocupado	PIN pad procesando otra acción	Espera a que la operativa actual termine antes de iniciar otra.

Códigos de denegación offline (EMV)

Cuando una transacción es denegada localmente por el chip de la tarjeta sin consultar online, se pueden devolver los siguientes códigos:

Código	Identificador Técnico	Descripción
`0`	`DENEGADA_OFF_IMPORTE_O`	Importe menor o igual a cero.
`-1`	`DENEGADA_OFF_PAIS_O_MONEDA_EXTRANJERO`	Moneda/país extranjero no permitido offline.
`-2`	`DENEGADA_OFF_BLOQUE_PIN`	Tarjeta bloqueada por intentos de PIN.
`-3`	`DENEGADA_OFF_LIMITE_IMPORTE_SUPERADO`	Importe excede el límite offline permitido.
`-4`	`DENEGADA_OFF_LIMITE_OPERACIONES_SUPERADO`	Número de transacciones offline excedido.
`-5`	`DENEGADA_OFF_OPERACION_BANDA_NO_PERMITIDA`	Banda magnética no permitida offline.
`-6`	`DENEGADA_OFF_OPERACION_ENTRADA_MANUAL_NO_PERMITIDA`	Entrada manual no permitida offline.
`-7`	`DENEGADA_OFF_TARJETA_CADUCADA`	Tarjeta caducada.
`-8`	`DENEGADA_APLICACION_NO_PERMITIDA`	Aplicación (AID) no permitida.
`-9`	`DENEGADA_OPERACION_NO_PERMITIDA`	Tipo de lectura no reconocido.
`-10`	`DENEGADA_9F27`	Tipo de transacción 9F27 denegado por la tarjeta.
`-11`	`DENEGADA_TARJETA_PRIVADA`	Tarjeta privada/no financiera no permitida.
`-12`	`DENEGADA_OPERACION_MOVIL_NO_AUTENTICADA`	Pago móvil sin autenticación.
`-13`	`DENEGADA_OPERACION_CONTACTLESS_NO_AUTENTICADA`	Autenticación de operativa contactless no realizada.
`-14`	`DENEGADA_OFF_LIMITE_IMPORTE_ACUMULADO_SUPERADO`	Límite de importe acumulado offline excedido.
`-15`	`DENEGADA_OFF_LIMITE_OPERACIONES_ACUMULADAS_SUPERADO`	Límite de operaciones offline acumuladas superado.
`-16`	`DENEGADA_PIN_OFF_EXCEDIDO`	Intentos de PIN offline excedidos.
`-17`	`DENEGADA_BYPASS_PIN`	PIN requerido pero no hay PIN pad disponible.
`-18`	`DENEGADA_SDA_FALLIDA`	Validación SDA (Static Data Authentication) fallida.
`-19`	`DENEGADA_DDA_FALLIDA`	—
`-20`	`DENEGADA_APP_CADUCADA`	—
`-21`	`DENEGADA_APP_NO_EFECTIVA`	—
`-22`	`DENEGADA_SERV_NO_PERMITIDO`	—
`-23`	`DENEGADA_VERIF_ERR_TITULAR`	—
`-24`	`DENEGADA_PIN_NO_PINPAD`	—
`-25`	`DENEGADA_FALLBACK`	Fallback no soportado.

Buenas prácticas en gestión de errores

Al procesar errores, considera la categoría para proporcionar la mejor experiencia al usuario:

Errores Técnicos (RepositoryResult.Error): Registra información detallada para depuración. Muestra mensajes genéricos y amigables a los clientes sin exponer detalles técnicos. Ofrece reintento para fallos transitorios como problemas de red.

Denegaciones de Pago (PaymentResult.Denied): Muestra el motivo de la denegación de la respuesta de autorización. Guía a los clientes hacia métodos de pago alternativos. Nunca reintentes automáticamente sin acción del cliente.

Cancelaciones de Usuario (RepositoryResult.Cancelled): Gestiona de forma fluida sin mensajes de error. Permite a los clientes reintentar o elegir otras acciones. Registra las cancelaciones para análisis de negocio.